# Using openNCAI’s Data Entry Templates

## Introduction

openNCAI requires data inputs in specific formats. The helper functions `create_ncai_template()` and `read_ncai_template()` are can be used to make this process easier and to ensure that data entry matches the format required by the package.

    library(openNCAI)

## Step 1: Assembling the metadata

We start by defining the metadata for the region we wish to study, specifically:

- The natural habitats found in the region which we wish to monitor,
- The ecosystem services produced by those habitats,
- The habitat condition indicators which we will use to estimate the likely flow of ecosystemservices from habitats,
- The list of years over which we will calculate the index.

It is sensible to take time to get these right at the start as they define the scope of the whole calculation.

For this demonstration, we use the display-ready versions of the metadata bundled with the package: ns_display_habitats_label_tree, ns_display_es_label_tree, and ns_display_ci_names. Note carefully the format of the label trees…

The Habitats Label Tree contains EUNIS1 level 2 habitats, nested within EUNIS level 1 broad habitat categories. The structure is a named list of character vectors. Let’s see the first three broad habitat groups and the habitats within them:

    ns_display_habitats_label_tree[1:3]
    #> $`B. COASTAL HABITATS`
    #> [1] "B1 Coastal dunes and sandy shores"
    #> [2] "B2 Coastal shingle"
    #> [3] "B3 Rock cliffs, ledges and shores, including the supralittoral"
    #>
    #> $`C. INLAND SURFACE WATERS`
    #> [1] "C Inland surface waters"
    #>
    #> $`D. MIRES, BOGS AND FENS`
    #> [1] "D1 Raised and blanket bogs"
    #> [2] "D2 Valley mires, poor fens and transition mires"
    #> [3] "D4 Base-rich fens and calcareous spring mires"
    #> [4] "D5 Sedge and reedbeds, normally without free-standing water"

To input a tree like this manually, we would use this form:

    my_hab_tree <- list(
      "Woodlands" = c("Deciduous woodland",
                     "Evergreen woodland",
                     "Scrub woodland"),
      "Coastal" = c("Dunes and sandy shores",
                   "Shingle")
    )

The Ecosystem Services Label Tree has a similar form, with SEEA2 ecosystem service types at the top level, and individual CICES-style3 ecosystem services within:

    ns_display_es_label_tree[1:3]
    #> $PROVISIONING
    #>  [1] "1.1 Cultivated crops"
    #>  [2] "1.2 Reared animals and their outputs"
    #>  [3] "1.3 Wild animals, plants and algae (and their outputs)"
    #>  [4] "1.4 Animals, plants and algae from in-situ aquaculture"
    #>  [5] "1.5 Water for drinking purposes"
    #>  [6] "1.6 Materials from animals, plants and algae (for direct use or processing)"
    #>  [7] "1.7 Materials from animals, plants and algae (for agricultural use)"
    #>  [8] "1.8 Genetic material from all biota"
    #>  [9] "1.9 Water for non-drinking purposes"
    #> [10] "1.10 Plant-based energy sources"
    #> [11] "1.11 Animal-based energy sources"
    #> [12] "1.12 Animal-based mechanical energy"
    #>
    #> $`REGULATION AND MAINTENANCE`
    #>  [1] "2.1 Mediation of waste, toxins and other nuisances (by biota)"
    #>  [2] "2.2 Mediation of waste, toxins and other nuisances (by ecosystems)"
    #>  [3] "2.3 Mediation of mass flows and erosion"
    #>  [4] "2.4 Mediation of liquid flows (hydrological cycle/flood protection)"
    #>  [5] "2.5 Mediation of gas/air flows (storm protection/ventilation/transpiration)"
    #>  [6] "2.6 Pollination and seed dispersal"
    #>  [7] "2.7 Maintenance of nursery populations and habitats"
    #>  [8] "2.8 Pest and disease control"
    #>  [9] "2.9 Soil formation and composition"
    #> [10] "2.10 Maintenance of water's chemical condition"
    #> [11] "2.11 Global, regional and micro climate regulation"
    #>
    #> $CULTURAL
    #> [1] "3.1 Physical and experiential interactions"
    #> [2] "3.2 Heritage, scientific and educational interactions"
    #> [3] "3.3 Aesthetic and entertainment interactions"
    #> [4] "3.4 Symbolic, sacred and/or religious interactions"
    #> [5] "3.5 Existence and bequest"

The Condition Indicator List is a simple character vector:

    ns_display_ci_names[1:4]
    #> [1] "2 Pollution: orthophosphate at safe level"
    #> [2] "4 Coastal bathing water quality (guideline and mandatory)"
    #> [3] "6 Woodland bird index"
    #> [4] "8 Wintering waterbird index"

We could input a list like this manually using this form:

    my_ci_list <- c("Bathing water quality index", "Forestry yield", "Woodland bird count")

We will also need a list of years, and this can be input either as a numeric list or a character vector of year names. We will define a numeric list:

    my_num_year_list <- 2000:2022

## Step 2: Creating the data input spreadsheet

We use the function `create_ncai_template()` to build a spreadsheet into which we can enter data. For a blank template, we only need to pass a file path to save the new template and the four metadata arguments:

    create_ncai_template(template_out = "Blank_NS_Data_Entry_Template.xlsx",
                         habitats_label_tree = ns_display_habitats_label_tree,
                         es_label_tree = ns_display_es_label_tree,
                         ci_names = ns_display_ci_names,
                         year_list = my_num_year_list)

The function generates a spreadsheet into which you can manually enter data. Additional optional arguments allow you to pass in data to pre-populate the template. Use these with caution: the order and dimensions of the data must match what is passed in to the spreadsheet, and no automatic sorting or ordering takes place. Create a blank template first to verify the formats which need to be matched.

The row and column headers are locked. Take care not to edit these. If you make any changes, these will need to be reflected in the metadata you use to read the data into R in the next step. If you decide to change the metadata, it is probably easiest to start with a fresh blank template.

## Step 3: Read in data from the completed template

The function `read_ncai_template()` is designed to read the data back in to R, producing a list of objects ready to use with `get_ncai()`. As part of the process, the labels are cleaned to remove capital letters and special characters, and replace spaces with “_“. So”K. MONTANE” in becomes “k_montane” in `ns_habitats_label_tree`.

We read the completed template back in using the same label trees and condition indicator list that we used to create the template.

    ncai_data_objects <- read_ncai_template(
      path = "Complete_NS_Data_Entry_Template.xlsx",
      habitats_label_tree = ns_display_habitats_label_tree,
      es_label_tree = ns_display_es_label_tree,
      ci_names = ns_display_ci_names)

The function returns a list of data objects ready to use with `get_ncai()`. We can see the names of the objects by running:

    names(ncai_data_objects)

And access individual items on the list with `$` notation:

    ncai_data_objects$clean_habitats_label_tree

The objects returned are:

Object Name | Description | Data Format
--- | --- | ---
clean_habitats_label_tree | Cleaned version of the habitats label tree. | A named list of character vectors.
clean_es_label_tree | Cleaned version of the ecosystem service label tree. | A named list of character vectors.
habitat_extent | Habitat areas over time. | A data frame where rows are habitats and columns are years.
ci_scores | Condition indicator scores over time. | A data frame where rows are years and columns are condition indicators.
provision_per_unit_scores | Provision-per-unit scores, denoting relative capacity of habitats to provide ecosystem services. | A data frame where rows are habitats and columns are ecosystem services.
between_importance | Importance scores for each ecosystem service type. | A named list of numeric values.
within_importance | Importance scores for individual ecosystem services within each type group. | A nested list of named lists.
indicator_directory | Table recording the salience of each condition indicator in representing flow of services of each SEEA type. | A data frame with a column for condition indicator names, and a column for each of the ecosystem service types.
ci_relevance_matrices | Binary relevance matrices for every condition indicator, recording for which habitat/ecosystem service combinations that indicator is relevant. | A named list of data frames (one per indicator).

1. European Nature Information System↩︎

2. System of Environmental-Economic Accounting↩︎

3. Common International Classification of Ecosystem Services↩︎