---
title: "Reference lists and using them"
author: "Floris Vanderhaeghe"
date: "2019-05-06"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{010. Reference lists and using them}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
options(stringsAsFactors = FALSE)
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
library(n2khab)
```


## Overview

With reference lists we mean complete and authorative lists of all items or categories that constitute some collection.
Their purpose is typically to promote standardization and thereby to ease collaborative work.

The `n2khab` package provides the following built-in reference lists, 
relevant to N2KHAB projects [^N2KHAB]:

- `types`: checklist of types (habitat (sub)types and regionally important biotopes) (documentation links: [this website](../reference/types.html) / [installed package](../html/types.html)), 
represented by their *current* codes
- `env_pressures`: checklist of environmental pressures, represented by codes (documentation links: [this website](../reference/env_pressures.html) / [installed package](../html/env_pressures.html))

Additionally, `namelist` provides names and (optionally) shortnames for IDs/codes used in the above lists (documentation links: [this website](../reference/namelist.html) / [installed package](../html/namelist.html)).

[^N2KHAB]: With N2KHAB projects, we mean scientific monitoring programmes and research projects regarding Flemish Natura 2000 habitats and regionally important biotopes (RIBs).


### More on list contents and package functionality

Beside enlisting all items, the reference lists provide additional information on them, sometimes in a generic way with variables like 'attribute_1', 'attribute_2', 'tag_1' and so on (explained in the **documentation files**).
This information may be of a defining nature (and obligate), or may just provide useful categories and tags to filter by.

Reading functions of the `n2khab` package return the reference lists as **tibbles**, with appropriate text from `namelist` added.
A tibble is a data frame that makes working in the tidyverse a little [easier](https://r4ds.had.co.nz/tibbles.html).



### Multilanguage support

In the data source on disk, each item envisaged by a reference list is always represented by a **code** (sometimes a combination of two codes) -- not a name.
The same approach is often followed for other attributes (use of codes, not names or descriptions).
However for some variables English has been used directly in the data source.

The splitting between code and explanatory names, shortnames and other language-dependent text made it possible to store the latter in _multiple languages_ in `namelist`, in the variables `name` and `shortname`.
Currently, this list systematically provides English and Dutch text for each code. This can be extended in future versions of the package (not necessarily in a systematic way).




## Get the reference lists in R

Making the `types` reference list available in the R environment is as easy as:

```{r}
read_types()
```

By default, English is used.
But, you can also choose to get a tibble in another language:

```{r}
read_types(lang = "nl")
```

The `lang` argument is available in the below functions as well.

`env_pressures` is made available with:

```{r}
read_env_pressures()
```

When actually using these reading functions, you will -- of course -- assign its result to an object.