| Title: | Calculates a Natural Capital Assets Index |
|---|---|
| Description: | Calculates a regional natural capital assets index (NCAI) following the methodology designed by NatureScot for Scotland as described in Albon, Balana, Brooker & Eastwood (2014) <https://www.nature.scot/sites/default/files/2025-06/naturescot-commissioned-report-751.pdf> and McKenna et al. (2019) <doi:10.1016/J.ECOLIND.2019.105645>. Processes habitat extent and condition data alongside metadata and weighting systems to produce a yearly single figure indexed relative to a base-year value of 100. |
| Authors: | Kate O'Hara [aut, cre] |
| Maintainer: | Kate O'Hara <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.0 |
| Built: | 2026-06-01 16:54:12 UTC |
| Source: | https://github.com/oharakate/openncai |
Generates a highly formatted, protected Excel (.xlsx) workbook containing the necessary sheets for a user to populate an openNCAI account. The template includes internal logic for habitat and ecosystem service trees, automated styling, and cell locking to ensure data integrity for subsequent re-import. Note that the habitats and ecosystem service label trees passed here may be used to subsequently read in the data with read_ncai_template().
create_ncai_template( template_out, habitats_label_tree, es_label_tree, ci_names, year_list, overwrite = FALSE, habitat_extent = NULL, provision_per_unit_scores = NULL, between_importance_scores = NULL, within_importance_scores = NULL, ci_scores = NULL, indicator_directory = NULL, ci_relevance_matrices = NULL )create_ncai_template( template_out, habitats_label_tree, es_label_tree, ci_names, year_list, overwrite = FALSE, habitat_extent = NULL, provision_per_unit_scores = NULL, between_importance_scores = NULL, within_importance_scores = NULL, ci_scores = NULL, indicator_directory = NULL, ci_relevance_matrices = NULL )
template_out |
A string representing the file path where the .xlsx will be saved. |
habitats_label_tree |
A named list of character vectors representing the habitat hierarchy. Names: broad habitats, typically EUNIS level 1. Character vector items: typically EUNIS level 2 habitats. |
es_label_tree |
A named list of character vectors representing the ecosystem service hierarchy. Names: typically SEEA ecosystem service types. Character vector items: typically CICES-type ecosystem services. |
ci_names |
A character vector of condition indicator names. |
year_list |
A vector of years (numeric or character) to be included in the account. |
overwrite |
Logical. If |
habitat_extent |
Optional data frame of existing habitat extent data. Row and column order and dimensions MUST matched label trees/year list. |
provision_per_unit_scores |
Optional data frame of existing ES Potential
Unit scores. Row and column order MUST match lower levels of
|
between_importance_scores |
Optional list of ecosystem service type
importance weights. Order MUST match names of |
within_importance_scores |
Optional list of lists of weights for
specific services. Order MUST match the order and dimensions of the lower
level of |
ci_scores |
Optional data frame of existing condition indicator scores.
Rows and columns MUST match dimensions and order of |
indicator_directory |
Optional data frame of existing indicator salience
data. Row order and length MUST match |
ci_relevance_matrices |
Optional list of existing binary relevance
matrices. Matrix list order and length must mach |
Optional arguments to pre-populate the template with data assume that the passed-in data matches those of the label trees, year list and condition indicator list as relevant. Users are recommended to create an empty template first to verify the required formats before attempting to pass in data.
Generates an Excel file at the specified path and returns a message of success.
# 1. Define the habitat hierarchy habitat_label_tree <- list( 'B. Coastal Habitats' = c( "Coastal vegetated shingle", "Coastal dunes and sandy shores" ), 'E. Grasslands' = c( "Dry Grasslands", "Mesic Grasslands" ) ) # 2. Define the ecosystem service hierarchy ecosystem_service_label_tree <- list( 'PROVISIONING' = c( "1.1 Cultivated Crops", "1.2 Reared Animals And Their Outputs" ), 'CULTURAL' = c( "3.5. Existence & bequest" ) ) # 3. Define indicators and temporal scope condition_indicator_list <- c("National Water Quality Index", "AgriSCOR") list_of_years <- 2020:2025 # 4. Generate the template in a temporary location # tempfile() ensures a valid path that won't clutter your working directory. tmp_path <- tempfile(fileext = ".xlsx") create_ncai_template( template_out = tmp_path, habitats_label_tree = habitat_label_tree, es_label_tree = ecosystem_service_label_tree, ci_names = condition_indicator_list, year_list = list_of_years ) message("Template successfully created at: ", tmp_path)# 1. Define the habitat hierarchy habitat_label_tree <- list( 'B. Coastal Habitats' = c( "Coastal vegetated shingle", "Coastal dunes and sandy shores" ), 'E. Grasslands' = c( "Dry Grasslands", "Mesic Grasslands" ) ) # 2. Define the ecosystem service hierarchy ecosystem_service_label_tree <- list( 'PROVISIONING' = c( "1.1 Cultivated Crops", "1.2 Reared Animals And Their Outputs" ), 'CULTURAL' = c( "3.5. Existence & bequest" ) ) # 3. Define indicators and temporal scope condition_indicator_list <- c("National Water Quality Index", "AgriSCOR") list_of_years <- 2020:2025 # 4. Generate the template in a temporary location # tempfile() ensures a valid path that won't clutter your working directory. tmp_path <- tempfile(fileext = ".xlsx") create_ncai_template( template_out = tmp_path, habitats_label_tree = habitat_label_tree, es_label_tree = ecosystem_service_label_tree, ci_names = condition_indicator_list, year_list = list_of_years ) message("Template successfully created at: ", tmp_path)
This is the primary function for calculating the NCAI. It processes habitat extent, condition scores, and importance weights through the full NCAI pipeline, with options to return intermediate matrices or specific breakdowns.
get_ncai( habitat_extent, ci_scores, habitats_label_tree, es_label_tree, year_list, year_one = NULL, provision_per_unit_scores, provision_per_unit_divisor = 5, custom_divisor_matrix = NULL, between_importance_scores, within_importance_scores, ci_relevance_matrices, indicator_directory, total_indicator_relevances_constant = 2, smoothing_weights = c(0.2, 0.4, 0.6, 0.8, 1), return = c("overall_ncai", "by_ecosystem_service_type", "by_broad_habitat", "wellbeing_index", "flow_of_es_index", "yearly_ncai_matrices", "yearly_wellbeing_matrices", "flow_of_es_matrices", "es_potential_base", "wellbeing_potential_base", "flow_of_es_base", "everything") )get_ncai( habitat_extent, ci_scores, habitats_label_tree, es_label_tree, year_list, year_one = NULL, provision_per_unit_scores, provision_per_unit_divisor = 5, custom_divisor_matrix = NULL, between_importance_scores, within_importance_scores, ci_relevance_matrices, indicator_directory, total_indicator_relevances_constant = 2, smoothing_weights = c(0.2, 0.4, 0.6, 0.8, 1), return = c("overall_ncai", "by_ecosystem_service_type", "by_broad_habitat", "wellbeing_index", "flow_of_es_index", "yearly_ncai_matrices", "yearly_wellbeing_matrices", "flow_of_es_matrices", "es_potential_base", "wellbeing_potential_base", "flow_of_es_base", "everything") )
habitat_extent |
A data frame of habitat area/extent per year. |
ci_scores |
A matrix of condition indicator scores. |
habitats_label_tree |
A named list defining the hierarchy of habitats. |
es_label_tree |
A named list defining the hierarchy of ecosystem services. |
year_list |
A vector (character or numeric) of years for the index. |
year_one |
Optional. The baseline year for indexing (where index = 100).
Defaults to the first year in |
provision_per_unit_scores |
A data frame of Ecosystem Service Provision Potential per Unit. |
provision_per_unit_divisor |
Numeric. A standard divisor to convert
Provision Per Unit scores to weights; the number out of which Provision
Per Unit scores have been awarded. Default value is 5.
Alternatively, a |
custom_divisor_matrix |
Optional. A matrix of divisors specific to habitat/service combinations. |
between_importance_scores |
Scores representing the relative importance between different ecosystem service types. |
within_importance_scores |
Scores representing the relative importance within ecosystem service types. |
ci_relevance_matrices |
Condition Indicator Relevance Matrices list. |
indicator_directory |
Directory mapping indicators to services/habitats. |
total_indicator_relevances_constant |
Numeric. The constant used in the Total Indicator Relevance calculation. Defaults to 2. |
smoothing_weights |
Numeric vector of weights for 5-year trailing
smoothing. Defaults to |
return |
Character. Specifies the object to return. Options include:
|
Mandatory Inputs: Users must provide either an provision_per_unit_divisor
or a custom_divisor_matrix to convert potential scores into weights.
Smoothing and Baseline Years:
The smoothed index is calculated using a 5-year trailing window.
If year_one
is set to a year other than the first year of the dataset, the
smoothed_index value for that baseline year will likely not be
exactly 100. This is because the smoothing reflects the trend of the
preceding 4 years. The raw_index will always remain anchored at 100
for the year_one.
An object of the type specified by the return argument.
Typically a data frame or a named list of NCAI components.
# Calculate the NCAI using the bundled NatureScot sample data ncai_objects <- 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, 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 = "everything" ) # View the final indexed results names(ncai_objects) head(ncai_objects$overall_ncai)# Calculate the NCAI using the bundled NatureScot sample data ncai_objects <- 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, 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 = "everything" ) # View the final indexed results names(ncai_objects) head(ncai_objects$overall_ncai)
A set of scores denoting the importance of each type group of ecosystem services to Scotland.
ns_between_importance_scoresns_between_importance_scores
A named list of scores where values range from 0 to 20, representing the relative importance of each ecosystem service type. Item names are ecosystem service types.
A set of matrices recording whether or not each condition indicator is relevant to each habitat/ecosystem service combination.
ns_ci_relevance_matricesns_ci_relevance_matrices
A named list of data frames:
Names are condition indicator IDs matching ns_indicator_directory.
Each data frame has habitats as rows and ecosystem services as columns.
Values are binary (0 or 1) indicating relevance.
A matrix containing the raw condition indicator scores over the years of the time series.
ns_ci_scoresns_ci_scores
A data frame:
Rows represent years in the time series.
Columns represent condition indicators (e.g., "Adult red grouse density").
Values are numeric condition scores.
A matrix containing numbers by which the Ecosystem Service Potential per Unit Scores will be divided to calculate a weight.
ns_custom_divisor_matrixns_custom_divisor_matrix
A data frame:
Rows represent habitats matching the habitats label tree.
Columns represent ecosystem services matching the ecosystem services label tree.
Values are numeric divisors used for weight normalization.
Display name (no string cleaning) list of condition indicator names which is used internally.
ns_display_ci_namesns_display_ci_names
A character vector where items are the original number and name of NatureScot's 38 condition indicators:
Display name version (no string cleaning) version of ns_es_label_tree
which is used internally.
ns_display_es_label_treens_display_es_label_tree
A named list of character vectors:
Names represent ecosystem service types (e.g., "Provisioning").
Values are character vectors of specific ecosystem services (e.g., "Cultivated crops").
Display name version (no string cleaning) version of ns_habitats_label_tree
which is used internally.
ns_display_habitats_label_treens_display_habitats_label_tree
A named list of character vectors:
Names represent broad habitat groups (e.g., "Coastal habitats").
Values are character vectors of specific habitat types (e.g., "Coastal shingle").
A hierarchical tree mapping ecosystem service types to specific ecosystem services.
ns_es_label_treens_es_label_tree
A named list of character vectors:
Names represent ecosystem service types (e.g., "Provisioning").
Values are character vectors of specific ecosystem services (e.g., "Cultivated crops").
A table containing the annual extent (area) of various habitats.
ns_habitat_extentns_habitat_extent
A data frame:
Rows represent broad habitats matching the habitats label tree.
Columns represent years (e.g., 2000 to 2022).
Values are numeric representing area in hectares.
A hierarchical tree mapping broad habitat groups to specific habitat types.
ns_habitats_label_treens_habitats_label_tree
A named list of character vectors:
Names represent broad habitat groups (e.g., "Coastal habitats").
Values are character vectors of specific habitat types (e.g., "Coastal shingle").
A table recording the salience of habitat condition scores as indicators of the likely flow of services under each ecosystem service type.
ns_indicator_directoryns_indicator_directory
A data frame with the following columns:
ci_id: Unique condition indicator identifier.
provisioning: Salience for Provisioning services.
regulation_and_maintenance: Salience for Regulation and Maintenance services.
cultural: Salience for Cultural services.
A matrix of scores denoting the exemplary capacity of each habitat to provide each ecosystem service.
ns_provision_per_unit_scoresns_provision_per_unit_scores
A data frame:
Rows represent habitats matching the habitats label tree.
Columns represent ecosystem services matching the ecosystem services label tree.
Values are numeric scores from 0 (No potential) to 5 (Maximum potential).
Sets of scores denoting the importance of each ecosystem service to Scotland, within its type group.
ns_within_importance_scoresns_within_importance_scores
A named list of named lists of scores:
Names represent ecosystem service types.
Names of scores represent individual ecosystem services
Values are numeric scores (0-20) for specific services within that group.
A list of years for which data is available and over which the index will be calculated.
ns_year_listns_year_list
A character vector of year labels (e.g., "2000", "2001").
Imports data from an Excel workbook created by create_ncai_template.
The function uses the provided label trees to re-align the data and applies
automated cleaning to headers to ensure compatibility with internal openNCAI
calculation engines. Note that the habitat and ecosystem service label trees
should match the labels used in the spreadsheet; typically the same label trees
should be used to generate and read the template.
read_ncai_template(path, habitats_label_tree, es_label_tree, ci_names)read_ncai_template(path, habitats_label_tree, es_label_tree, ci_names)
path |
String. The file path to the populated .xlsx file. |
habitats_label_tree |
A named list of character vectors representing the habitat hierarchy. Names: broad habitats, typically EUNIS level 1. Character vector items: typically EUNIS level 2 habitats. |
es_label_tree |
A named list of character vectors representing the ecosystem service hierarchy. Names: typically SEEA ecosystem service types. Character vector items: typically CICES-type ecosystem services. |
ci_names |
The original character vector of indicator names used to create the template. |
A named list of data structures ready for use in get_ncai:
clean_habitats_label_tree: Cleaned version of habitat hierarchy.
clean_es_label_tree: Cleaned version of ES hierarchy.
habitat_extent: Data frame of habitat areas over time.
ci_scores: Data frame of indicator scores over time.
provision_per_unit_scores: Data frame of ES potential per unit area.
between_importance: List of broad ES type weights.
within_importance: List of specific ES service weights.
indicator_directory: Data frame mapping indicators to service types.
ci_relevance_matrices: List of binary matrices for every indicator.
# 1. Define the trees (same as used in create_ncai_template) habitat_label_tree <- list( 'B. Coastal Habitats' = c("Coastal vegetated shingle", "Coastal dunes"), 'E. Grasslands' = c("Dry Grasslands", "Mesic Grasslands") ) ecosystem_service_label_tree <- list( 'PROVISIONING' = c("1.1 Cultivated Crops"), 'CULTURAL' = c("3.5. Existence & bequest") ) condition_indicator_list <- c("National Water Quality Index") # 2. Create a temporary template to read back in # This ensures the example is self-contained and runnable. tmp_path <- tempfile(fileext = ".xlsx") create_ncai_template( template_out = tmp_path, habitats_label_tree = habitat_label_tree, es_label_tree = ecosystem_service_label_tree, ci_names = condition_indicator_list, year_list = 2024:2025 ) # 3. Read the template # Even though it's empty, the function will process the headers and structure. ncai_data <- read_ncai_template( path = tmp_path, habitats_label_tree = habitat_label_tree, es_label_tree = ecosystem_service_label_tree, ci_names = condition_indicator_list ) # 4. Access the cleaned data structures # Show the first few rows of the imported habitat extent matrix head(ncai_data$habitat_extent)# 1. Define the trees (same as used in create_ncai_template) habitat_label_tree <- list( 'B. Coastal Habitats' = c("Coastal vegetated shingle", "Coastal dunes"), 'E. Grasslands' = c("Dry Grasslands", "Mesic Grasslands") ) ecosystem_service_label_tree <- list( 'PROVISIONING' = c("1.1 Cultivated Crops"), 'CULTURAL' = c("3.5. Existence & bequest") ) condition_indicator_list <- c("National Water Quality Index") # 2. Create a temporary template to read back in # This ensures the example is self-contained and runnable. tmp_path <- tempfile(fileext = ".xlsx") create_ncai_template( template_out = tmp_path, habitats_label_tree = habitat_label_tree, es_label_tree = ecosystem_service_label_tree, ci_names = condition_indicator_list, year_list = 2024:2025 ) # 3. Read the template # Even though it's empty, the function will process the headers and structure. ncai_data <- read_ncai_template( path = tmp_path, habitats_label_tree = habitat_label_tree, es_label_tree = ecosystem_service_label_tree, ci_names = condition_indicator_list ) # 4. Access the cleaned data structures # Show the first few rows of the imported habitat extent matrix head(ncai_data$habitat_extent)