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.
We start by defining the metadata for the region we wish to study, specifically:
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:
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:
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.
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:
And access individual items on the list with $
notation:
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). |