Register a new areal data table

This function registers a new areal data table into the geospatial database.

regTable(
  ...,
  subset = NULL,
  dSeries = NULL,
  gSeries = NULL,
  label = NULL,
  begin = NULL,
  end = NULL,
  schema = NULL,
  archive = NULL,
  archiveLink = NULL,
  downloadDate = NULL,
  updateFrequency = NULL,
  metadataLink = NULL,
  metadataPath = NULL,
  notes = NULL,
  diagnose = FALSE,
  overwrite = FALSE
)

Arguments

...

character(1)
name and value of the topmost unit under which the table shall be registered. The name of this must be a class of the gazetteer and the value must be one of the territory names of that class, e.g. nation = "Estonia".

subset

character(1)
optional argument to specify which subset the file contains. This could be a subset of territorial units (e.g. only one municipality) or of a target variable.

dSeries

character(1)
the dataseries of the areal data (see regDataseries).

gSeries

character(1)
optionally, the dataseries of the geometries, if the geometry dataseries deviates from the dataseries of the areal data (see regDataseries).

label

integerish(1)
the label in the onology this geometry should correspond to.

begin

integerish(1)
the date from which on the data are valid.

end

integerish(1)
the date until which the data are valid.

schema

schema
the schema description of the table to read in (must have been placed in the global environment before calling it here).

archive

character(1)
the original file from which the boundaries emerge.

archiveLink

character(1)
download-link of the archive.

downloadDate

character(1)
value describing the download date of this dataset (in YYYY-MM-DD format).

updateFrequency

character(1)
value describing the frequency with which the dataset is updated, according to the ISO 19115 Codelist, MD_MaintenanceFrequencyCode. Possible values are: 'continual', 'daily', 'weekly', 'fortnightly', 'quarterly', 'biannually', 'annually', 'asNeeded', 'irregular', 'notPlanned', 'unknown', 'periodic', 'semimonthly', 'biennially'.

metadataLink

character(1)
if there is already metadata existing: link to the meta dataset.

metadataPath

character(1)
if an existing meta dataset was downloaded along the data: the path where it is stored locally.

notes

character(1)
optional notes.

diagnose

logical(1)
whether or not to try to reorganise the table with the provided schema. note: this does not save the reogranised table into the database yet, further steps of harmonisation are carried out by normTable before that.

overwrite

logical(1)
whether or not the geometry to register shall overwrite a potentially already existing older version.

Value

Returns a tibble of the entry that is appended to 'inv_tables.csv' in case update = TRUE.

Details

When processing areal data tables, carry out the following steps:

1. Determine the main territory (such as a nation, or any other polygon), a subset (if applicable), the ontology label and the dataseries of the areal data and of the geometry, and provide them as arguments to this function.

2. Provide a begin and end date for the areal data.

3. Run the function.

4. (Re)Save the table with the following properties:

   • Encoding: UTF-8

   • File name: What is provided as message by this function

   • make sure that the file is not modified or reshaped. This will happen during data normalisation via the schema description, which expects the original table.

5. Confirm that you have saved the file.

Every areal data dataseries (dSeries) may come as a slight permutation of a particular table arrangement. The function normTable expects internally a schema description (a list that describes the position of the data components) for each data table, which is saved as paste0("meta_", dSeries, TAB_NUMBER). See package tabshiftr.

See also

Other register functions: regDataseries(), regGeometry()

Examples

if(dev.interactive()){
  # build the example database
  adb_exampleDB(until = "regGeometry", path = tempdir())

  # the schema description for this table
  library(tabshiftr)

  schema_madeUp <-
    setIDVar(name = "al1", columns = 1) %>%
    setIDVar(name = "year", columns = 2) %>%
    setIDVar(name = "commodities", columns = 3) %>%
    setObsVar(name = "harvested",
              factor = 1, columns = 4) %>%
    setObsVar(name = "production",
              factor = 1, columns = 5)

  regTable(nation = "Estonia",
           subset = "barleyMaize",
           label = "al1",
           dSeries = "madeUp",
           gSeries = "gadm",
           begin = 1990,
           end = 2017,
           schema = schema_madeUp,
           archive = "example_table.7z|example_table1.csv",
           archiveLink = "...",
           nextUpdate = "2024-10-01",
           updateFrequency = "quarterly",
           metadataLink = "...",
           metadataPath = "my/local/path")
}