This vignette demonstrates very briefly how to use openNCAI to calculate a Natural Capital Assets Index. We use the data assets bundled with the package, namely metadata, environmental measurements, and weight sets used by NatureScot to calculate Scotland’s NCAI from 2000 to 2022.
First we load the package:
We can see a list of the data objects which are included.
# The packaged data objects all have names beginning with `ns_` (for NatureScot):
ls("package:openNCAI", patter = "^ns_")## [1] "ns_between_importance_scores" "ns_ci_relevance_matrices"
## [3] "ns_ci_scores" "ns_custom_divisor_matrix"
## [5] "ns_display_ci_names" "ns_display_es_label_tree"
## [7] "ns_display_habitats_label_tree" "ns_es_label_tree"
## [9] "ns_habitat_extent" "ns_habitats_label_tree"
## [11] "ns_indicator_directory" "ns_provision_per_unit_scores"
## [13] "ns_within_importance_scores" "ns_year_list"What are all these data objects? They fall into three groups:
metadata, environmental measurements, and weight sets. You can read more
about them in the tables below, but for now, since this is
openNCAI in brief, let’s just see how to use the
package. get_ncai() requires eleven arguments to calculate
the index:
scot_ncai <- get_ncai(habitat_extent = ns_habitat_extent,
ci_scores = ns_ci_scores,
habitats_label_tree = ns_habitats_label_tree,
es_label_tree = ns_es_label_tree,
year_list = ns_year_list,
year_one = NULL, # Default is the first year of year list
provision_per_unit_scores = ns_provision_per_unit_scores,
custom_divisor_matrix = ns_custom_divisor_matrix,
between_importance_scores = ns_between_importance_scores,
within_importance_scores = ns_within_importance_scores,
ci_relevance_matrices = ns_ci_relevance_matrices,
indicator_directory = ns_indicator_directory,
return = NULL # By default the overall index is returned
)## Note: NCAI calculated using a custom divisor matrix for Provision Per Unit weights.Let’s see what is returned:
## raw_total raw_index smoothed_index
## 2000 10000.000 100.00000 100.00000
## 2001 10028.103 100.28103 100.15613
## 2002 10088.681 100.88681 100.46318
## 2003 10120.128 101.20128 100.74262
## 2004 10110.951 101.10951 100.90501
## 2005 10155.579 101.55579 101.19170
## 2006 10127.365 101.27365 101.28062
## 2007 10110.488 101.10488 101.24711
## 2008 10053.071 100.53071 101.00767
## 2009 10006.247 100.06247 100.65686
## 2010 9897.437 98.97437 100.01315
## 2011 9904.897 99.04897 99.56640
## 2012 9925.694 99.25694 99.33729
## 2013 10024.472 100.24472 99.56063
## 2014 10095.796 100.95796 100.04079
## 2015 10206.066 102.06066 100.82881
## 2016 10218.951 102.18951 101.45403
## 2017 10284.662 102.84662 102.08892
## 2018 10252.536 102.52536 102.37741
## 2019 10249.089 102.49089 102.50236
## 2020 10267.712 102.67712 102.58720
## 2021 10285.577 102.85577 102.69049
## 2022 10309.185 103.09185 102.82806Three versions of the index are returned: the raw assets total, the raw index (indexed around 100 at year one), and the smoothed index (uses a rolling average which is weighted towards more recent years). We can plot one:
scot_ncai$years <- as.numeric(rownames(scot_ncai))
plot(
x = scot_ncai$years,
y = scot_ncai$raw_index,
type = "l",
main = "Scotland's Natural Capital Assets Index",
xlab = "Year",
ylab = "Index (Base = 100)",
las = 1, # Makes axis labels horizontal (easier to read)
lwd = 2, # Makes the line slightly thicker
col = "steelblue" # Adds a bit of professional color
)
Type ?openNCAI to get help, including seeing all the
return options available:
To understand more, read about the bundled data objects below, or explore a fuller demonstration in Replicating Scotland’s NCAI.
# Access the vignette within R with this command:
vignette("replicating_scotlands_ncai", package = "openNCAI")To use openNCAI with your own data, it’s important to pass in data
and metadata in the correct formats. The helper functions
create_ncai_template() and read_ncai_template
are provided to support that process. Read more about them in Using openNCAI’s Data
Entry Templates.
To understand more about the calculation process which openNCAI reproduces, look at this diagram:
NCAI Calculation Process Diagram
openNCAI includes includes example data objects which show the correct format for data input, and can be used to recreate Scotland’s openNCAI as published by NatureScot for the years 2000 to 2022.
| Object Name | Description | Data Format |
|---|---|---|
| ns_habitats_label_tree | Habitats Label Tree: a hierarchy of natural habitats (based on EUNIS1 level 2) grouped within their respective broad habitat categories (EUNIS level 1) found in Scotland. | A named list of character vectors where names are broad habitats and vectors contain the specific habitats within them. |
| ns_es_label_tree | Ecosystem Services Label Tree: a hierarchy of individual CICES-style2 ecosystem services organized by their SEEA3 service type groups (Provisioning, Regulation & Maintenance, and Cultural). | A named list of character vectors where names are service types and vectors contain the individual services. |
| ns_year_list | Year List: the specific range of years over which the index is calculated. | A character vector of years. |
| ns_display_habitats_label_tree | The display names version of the Habitats label tree,
with original capital letters, punctuation, etc., before they were
regularised for use inside the program. E.g. ‘B1 COASTAL HABITATS’ in
this object becomes ‘b1_coastal_habitats’ in
ns_habitats_label_tree. Used to demonstrate the helper
functions create_ncai_template() and
read_ncai_template() |
A named list of character vectors where names are broad habitats and vectors contain the specific habitats within them. |
| ns_display_es_label_tree | The display names version of the Ecosystem Services Label Tree. | A named list of character vectors where names are service types and vectors contain the individual services. |
| ns_display_ci_names | A list of the Condition Indicator labels, again before cleaning. | A character vector of Condition Indicator labels. |
| Object Name | Description | Data Format |
|---|---|---|
| ns_habitat_extent | Habitat Extent for Scotland: measurement in hectares of the area of each natural habitat over the years. | A data frame where rows are habitats and columns are years. |
| ns_ci_scores | Condition Indicator Score Matrix: yearly condition score on each of the Condition Indicators (CIs). | A data frame where rows are years and columns are CIs. |
| Object Name | Description | Data Format |
|---|---|---|
| ns_provision_per_unit_scores | Provision Per Unit Scores: scores denoting the relative capacity of one area unit of a habitat to provide each of the ecosystem services. | A data frame where rows are habitats and columns are ecosystem services. |
| ns_between_importance_scores | Ecosystem Service Importance Scores (between-service-type): scores denoting the relative importance of the different ecosystem service types (‘Provisioning’, ‘Regulation & Maintenance’, ‘Cultural’) to Scotland. | A named list of numeric values where names match the top-level names of the Service Label Tree. |
| ns_within_importance_scores | Ecosystem Service Importance Score (within-service-type): scores denoting the relative importance of individual ecosystem services within their service type group. | A nested list of named lists, with a hierarchy matching the Service Label Tree. |
| ns_ci_relevance_matrices | Condition Indicator Relevance Matrices: a set of matrices marking whether an indicator is relevant to specific habitat/ecosystem service combinations (e.g., ‘Woodland bird index’ relevance to ‘Pollination’). | A named list of data frames (one per CI) with binary (1/0) values; rows are habitats and columns are ecosystem services. |
| ns_indicator_directory | Indicator Directory: a table recording the salience of each condition indicator (between 0 and 1) in representing the capacity of habitats to provide each ecosystem service type. | A data frame with a ci_id column and
columns for each ecosystem service type containing salience scores. |
| ns_custom_divisor_matrix | NatureScot’s Custom Divisor Matrix: weights used to adjust potential provision scores to reflect scale and context dependence (e.g., adjusting scores by dividing by 1 instead of 5). | A data frame where row names are habitats and column names are ecosystem services. |