Skip to contents

Validate a movenet config file

validate_config.Rd

validate_config() validates that file is a valid movenet config file, by checking that:

  • file can be parsed as a YAML string.

  • All required top-level, fileopts, and cols configuration keys are present in file.

  • All configuration values follow data format requirements.

Usage

validate_config(file)

Arguments

file

Path of the config file to validate.

Value

  • If the provided config file is valid, TRUE (returned invisibly).

  • If the provided config file is not valid, an error is raised, with a message indicating the reason(s) validation has failed.

Details

Config file types

There are three types of config files, each with slightly different requirements:

  • Movement config files, with information on how to read movement data files. Configuration groupings in these files are prefixed with "movedata_".

  • Holding config files, with information on how to read holding data files. Configuration groupings in these files are prefixed with "holdingdata_".

  • Combined config files, containing both "movedata_" and "holdingdata_" configuration groupings. These need to fulfill criteria for both movement and holding config files.

Top-level configuration key requirements

Config files must contain each of two types of configuration groupings:

  • File and data options that commonly vary between datasets. Indicated by top-level key movedata_fileopts or holdingdata_fileopts.

  • Column headers/indices for data fields that are either required or that you want to extract along for analyses. Indicated by top-level key movedata_cols or holdingdata_cols.

fileopts configurations and data format requirements

Within each fileopts grouping, the following configurations are required, with the value taking the indicated format:

  • separator: Separator (or delimiter) used in the data file. Format: Single character.

  • decimal: Decimal mark used in the data file. Format: Single character.

  • encoding: Encoding used in the data file. Format: Character string.

Additionally, required for movedata_fileopts:

  • date_format: Date format specification used in the movement data file. Format: Character string matching readr date format specifications. See readr::parse_date() for guidance.

Additionally, required for holdingdata_fileopts, if geographical coordinates are to be included in data extraction:

  • country_code: Two-letter country code for the data in the holding data file. Format: Character string consisting of two upper-case letters.

  • coord_EPSG_code: Numeric part of the EPSG code for the Coordinate Reference System used in the holding data file. Format: Single integer.

cols configurations and data format requirements

Within movedata_cols groupings, the following configurations are required:

  • from: Header/index of the column containing identifiers of the holdings of origin.

  • to: Header/index of the column containing identifiers of the destination holdings.

  • date: Header/index of the column containing movement dates.

  • weight: Header/index of the column containing movement weights/quantities.

For holdingdata_cols, there is only one required configuration:

  • id: Header/index of the column containing holding identifiers (matching to from/to in movement data).

Additionally, for inclusion of geographical coordinates, holdingdata_cols requires the following configurations:

  • coord_x: Header/index of the column containing longitudinal geographical coordinates (x/longitude) of holdings

  • coord_y: Header/index of the column containing latitudinal geographical coordinates (y/latitude) of holdings

All cols configuration values must either be a character string or a single integer. All configurations within a cols grouping must have unique values.

See also

  • vignette("configurations") for an explanation of the movenet config system.

  • list.files(system.file("configurations", package = "movenet")) for a list of list of pre-installed templates and validated config files.

Other configurations-related functions: change_config(), get_config(), load_config(), new_config(), save_config()

Examples

# Validate a valid config file
validate_config(system.file("configurations", "fakeScotEID_holding.yml", package="movenet"))

# Validate an invalid config file (empty template)
try(validate_config(system.file("configurations", "holdingconfig_template.yml", package="movenet")))
#> Error in validate_config(system.file("configurations", "holdingconfig_template.yml",  : 
#>   C:/Users/cboga/OneDrive - University of Glasgow/Documents/R/win-library/4.1/movenet/configurations/holdingconfig_template.yml is not a valid movenet config file
#> Values for holdingdata_cols options must be unique. The following options have duplicate values: holdingdata_cols.id, holdingdata_cols.coord_x, holdingdata_cols.coord_y, holdingdata_cols.type, holdingdata_cols.herd_size
#> Data field(s) not in expected character format: holdingdata_fileopts.separator, holdingdata_fileopts.encoding, holdingdata_fileopts.decimal, holdingdata_fileopts.country_code
#> Data field(s) do not have the expected format of a single character: holdingdata_fileopts.separator, holdingdata_fileopts.decimal
#> Data field `holdingdata_fileopts.country_code` doesn't have the expected format of two uppercase letters
#> Data field `holdingdata_fileopts.coord_EPSG_code` not in expected integer format
#> Data field(s) not in expected character or integer format: holdingdata_cols.id, holdingdata_cols.coord_x, holdingdata_cols.coord_y, holdingdata_cols.type, holdingdata_cols.herd_size