Skip to contents

Lookup functions/definitions

Reto Stauffer

Source: vignettes/lookupfunctions.Rmd
lookupfunctions.Rmd

Introduction

The package is using a series of ‘lookup tables’ and data sets to validate the correctness the data.

This includes testing if the config object are in the correct format or to validate the XLSX file. In case problems are found, the error messages, warnings, and notes should include hints on what has been going wrong.

A series of small helper functions exist which allow the user to get the definitions used internally for these kind of tests.

Variable definition

annex_variable_definition() returns a data.frame (or list) containing the names of all allowed variables as well as some additional information.

## Loading required package: annex
var_def <- annex_variable_definition()
head(var_def, n = 3)
##   name required lower upper          allowed_units
## 1  CO2    FALSE   350 10000                 ppm, %
## 2   CO    FALSE     0   100 ug/m3, mg/m3, ppm, ppb
## 3 HCHO    FALSE     0  1000 ug/m3, mg/m3, ppm, ppb
  • name: Name of the variable (as used in column variable in the config object)
  • required: Whether or not additional variable information is required (used by annex_validate())
  • lower: Lower bound; observations below this threshold will be considered of bad quality. Used to calculate quality_lower by annex_stats(). NA if no bound defined.
  • upper: Upper bound; observations above this threshold will be considered of bad quality. Used to calculate quality_upper by annex_stats(). NA if no bound defined.
  • allowed_units: Comma separated list of allowed units as needed in the config object or NA if not defined. If set, the first entry is the ‘annex standard unit’ (see also Unit conversion).

The table below shows this table in a web-table form:

Room definition

annex_room_definition() returns a data.frame containing the names of all allowed room definitions. For each allowed room type there is a base name (e.g., "BED"; Bedroom) which can be extended by adding up to two numeric digits. This allows to define multiple bedrooms if needed (see examples_valid_labels included below). These are the labels as used in the config object.

require("annex")
room_def <- annex_room_definition()
head(room_def, n = 3)
##   name   long_name  examples_valid_labels
## 1  AMB     Ambient AMB, AMB1, AMB2, AMB25
## 2  BED     Bedroom BED, BED1, BED2, BED25
## 3  LIV Living room LIV, LIV1, LIV2, LIV25
  • name: Base name/base abbreviation of all available room types.
  • long_name: Human readable description.
  • examples_valid_labels: Examples of allowed names to label multiple rooms of the same type within one home.

The table below shows the full list in a web-table form:

ISO3 country code

In the output XLSX file (sheet “META-home”) the user needs to specify the country (location) of each ‘home’ using the ISO3 (ISO3166 alpha-3) country codes. A list of all available country codes is shipped with the annex package and can be accessed using annex_countries(). This information is used when validating the output XLSX (see Write and validate).

require("annex")
iso3_def <- annex_countries()
head(iso3_def, n = 3)
##         country ISO2 ISO3
## 1   Afghanistan   AF  AFG
## 2 Åland Islands   AX  ALA
## 3       Albania   AL  ALB

The table below shows all 249 defined countries; searchable table.