regTable: Register a new areal data table

Description

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

Usage

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
)

Value

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

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.

Details

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

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.
Provide a begin and end date for the areal data.
Run the function.
(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.
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.

Examples

Run this code

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")
}