Package {openNCAI}

openNCAI: 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.

Author(s)

Maintainer: Kate O'Hara k.a.ohara@stir.ac.uk

See Also

Useful links:

• https://github.com/oharakate/openNCAI

• Report bugs at https://github.com/oharakate/openNCAI/issues

Build All Natural Capital Asset Matrices

Description

Orchestrates the generation of asset matrices for every year in the series. Each matrix represents the final "Year Sheet" in the NatureScot account methodology, combining condition, wellbeing, and extent.

Usage

build_all_ncai_matrices(
  tyf_list,
  wellbeing_potential_base,
  habitat_extent,
  year_one = NULL,
  year_list,
  habitat_labels
)

Arguments

Value

A named list of data frames, one for each year. Each data frame displays the calculated natural capital assets by habitat and service.

Build All Total Yearly Flow Matrices (TYFs)

Description

Orchestrates the full process of generating the Total Yearly Flow matrices for every year in the series. It builds the indicator-specific contribution matrices (YWCCMs) and then aggregates and normalizes them.

Usage

build_all_tyfs(
  raw_cis,
  year_list,
  ciwms_list,
  total_indicator_relevances,
  total_indicator_relevances_constant
)

Arguments

Value

A named list of matrices, one for each year in year_list. Each matrix represents the aggregated flow of ecosystem services for that year.

Build Yearly Weighted Condition Contribution Matrices (YWCCMs)

Description

Generates a list of matrices where each indicator's relevance weighting (CIWM) is multiplied by its indexed condition score for a given year.

Usage

build_all_ywccms(raw_cis, year, year_list, ciwms_list)

Arguments

Value

A named list of matrices (YWCCMs), one for each indicator.

Build Condition Indicator Weight Matrices (CIWM)

Description

Converts relevance matrices (CIRM) into weight matrices (CIWM) by multiplying the relevance scores by the indicator's importance weights (per ecosystem service type) as defined in the Indicator Directory.

Usage

build_ciwm_list(
  cirm_list,
  indicator_directory,
  es_label_tree,
  habitats_label_tree = NULL
)

Arguments

Value

A named list of data frames, one list object for each Condition Indicator each containing the weighted relevance of that indicator to each combination of habitats and ecosystem services.

Build a Single Year's Natural Capital Asset Matrix

Description

Calculates the Natural Capital Asset (NCA) matrix for a specific target year. It combines the Total Yearly Flow (condition) with the Wellbeing Base and adjusts for the change in Habitat Extent relative to a base year.

Usage

build_ncai_matrix(
  tyf,
  wellbeing_potential_base,
  habitat_extent,
  target_year,
  year_one,
  habitat_labels
)

Arguments

Details

The final calculation follows the formula: (TYF \times Wellbeing Base \times Extent Index) / 10,000. The Extent Index is the target year's extent divided by the base year's extent, multiplied by 100.

Value

A data frame of natural capital assets for the target year.

Build Total Yearly Flow (TYF) for a Single Year

Description

Aggregates a list of YWCCMs and normalizes the sum against the Total Indicator Relevances matrix.

Usage

build_tyf(
  list_of_ywccms,
  total_indicator_relevances,
  total_indicator_relevances_constant
)

Arguments

Value

A numeric matrix for one year.

Calculate the Ecosystem Service Potential Base

Description

Multiply the Provision Per Unit (weights) by the habitat extent in the baseline year of the index.

Usage

calc_es_potential_base(
  provision_per_unit_weights,
  habitat_extent,
  year_list,
  year_one = NULL,
  habitats_label_tree,
  es_label_tree
)

Arguments

Value

A labelled data frame with the same dimensions as 'provision_per_unit_weights'.

Calculate Importance Weights using Hierarchical Named Lists

Description

This function calculates the final importance weights for ecosystem services by combining between-group scores (broad categories) and within-group scores (specific services). It uses a name-aware approach, matching list names to the provided label tree to ensure scores are applied to the correct categories.

Usage

calc_importance_weights(between_scores, within_scores, es_label_tree)

Arguments

Details

The function first normalizes the between-group scores to 100. For each category, it then normalizes the within-group scores and multiplies them by the category's broad weight. If a category has a total score of zero, all services within it are assigned a weight of 0.

Value

A single-row data frame where columns are the individual ecosystem services and the values are their calculated importance weights, scaled by both between-group and within-group priorities.

Calculate NCAI Broken Down by Broad Habitat

Description

Calculates the index subsetted by broad habitat

Usage

calc_ncai_by_bh(
  total_assets_matrix_list,
  habitats_label_tree,
  year_one = NULL,
  ...
)

Arguments

Value

A list of NCAI data frames, one for each habitat group.

Calculate NCAI Broken Down by Ecosystem Service Type

Description

Calculate the index subsetted by ecosystem service type.

Usage

calc_ncai_by_st(total_assets_matrix_list, es_label_tree, year_one = NULL, ...)

Arguments

Value

A list of NCAI data frames, one for each ecosystem service group.

Calculate Weights from Provision Per Unit Scores

Description

Converts scores denoting ecosystem service Provision Per Unit of habitats to weights by dividing by either a common denominator, or a matrix of custom divisors per habitat/ecosystem service combination.

Usage

calc_provision_per_unit_weights(
  provision_per_unit_scores,
  divisor = 5,
  custom_divisor_matrix = NULL,
  habitats_label_tree = NULL,
  es_label_tree = NULL
)

Arguments

Value

A labelled data frame of the same dimensions as provision_per_unit_scores containing the calculated Provision Per Unit weights.

Warning

Either divisor or custom_divisor_matrix must be provided. If custom_divisor_matrix is provided, it must have the same dimensions as provision_per_unit.

Calculate Total Indicator Relevances

Description

Aggregates a list of weighted condition indicator matrices into a single matrix representing the total relevance of all selected indicators to each habitat-service combination.

Usage

calc_total_indicator_relevances(
  all_ciwms_list,
  total_indicator_relevances_constant
)

Arguments

Details

The function uses Reduce("+", ...) to perform element-wise addition across all matrices in the input list. A constant is then added to every cell to ensure that subsequent divisions (e.g., when calculating the NCAI) do not encounter zeros.

Value

A data frame of numeric values representing the summed relevance scores plus the constant, with the same dimensions as the input matrices.

Worker Function to Calculate Weighted Habitat Extent Time Series

Description

An internal helper that multiplies a weight matrix by an indexed habitat extent vector across a time series.

Usage

calc_weighted_habitat_extent(
  habitat_extent,
  year_one,
  weight_matrix,
  as_matrices = FALSE
)

Arguments

Value

Depending on as_matrices, either a named list of matrices or an indexed data frame.

Scales the Ecosystem Service (ES) Potential Base by the Importance Weight for each service to generate the Wellbeing Base. ES Potential Base is expressed as each habitat's contribution as a proportion of the total potential for that service. Label trees may be passed in for optional labelling of the output data frame.

Description

Scales the Ecosystem Service (ES) Potential Base by the Importance Weight for each service to generate the Wellbeing Base. ES Potential Base is expressed as each habitat's contribution as a proportion of the total potential for that service. Label trees may be passed in for optional labelling of the output data frame.

Usage

calc_wellbeing_potential_base(
  es_potential_base,
  importance_weights,
  habitats_label_tree = NULL,
  es_label_tree = NULL
)

Arguments

Value

A data frame representing the Wellbeing Base.

Examples

# Assuming es_potential_base and importance_weights are already calculated:
# wellbeing_potential_base_matrix <- calc_wellbeing_potential_base(
#   es_potential_base = es_potential_base_matrix,
#   importance_weights = weights_vector,
#   habitats_label_tree = habitats_tree,
#   es_label_tree = es_tree
# )

Create an NCAI Data Entry Template

Description

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().

Usage

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
)

Arguments

Details

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.

Value

Generates an Excel file at the specified path and returns a message of success.

Examples

# 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)

Calculate Habitat Extent (Indexed) for a Target Year

Description

This helper function extracts habitat extent vectors for a specific target year and a baseline year, then calculates a percentage-based index.

Usage

get_habitat_extent_year_vec(target_year, year_one, habitat_extent)

Arguments

Details

The function performs the calculation:
(Target Extent / Baseline Extent) * 100

Value

A numeric vector of the same length as the number of rows in habitat_extent, representing the extent of each habitat in the target_year as a percentage of its extent in year_one.

Main User Interface for the Natural Capital Asset Index (NCAI)

Description

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.

Usage

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")
)

Arguments

Details

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.

Value

An object of the type specified by the return argument. Typically a data frame or a named list of NCAI components.

Examples

# 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)

Extract List of Condition Indicator Relevance Matrices (CIRMs)

Description

Extract List of Condition Indicator Relevance Matrices (CIRMs)

Usage

get_ns_cirm_list(
  path,
  sheet_list,
  matrix_range,
  ci_ids,
  all_service_labels,
  all_habitat_labels
)

Arguments

Extract Ecosystem Service Importance Scores

Description

Extract Ecosystem Service Importance Scores

Usage

get_ns_importance_scores(path, sheet, importance_ranges, es_tree)

Arguments

Extract Indexed Condition Score for a Specific Indicator

Description

Retrieves and indexes (base 100) a condition score for a single indicator.

Usage

get_yearly_condition(raw_cis, year_to_get, ci_num, year_list)

Arguments

Value

A numeric indexed score.

Get Yearly Ecosystem Service Flow Rates

Description

This high-level function orchestrates the transformation of raw condition scores into normalized Total Yearly Flow (TYF) matrices. It builds the weighted relevance matrices (CIWMs), calculates the total indicator relevances, and processes every year in the series.

Usage

get_yearly_flow(
  cirm_list,
  indicator_directory,
  es_label_tree,
  habitats_label_tree,
  ci_scores,
  year_list,
  total_indicator_relevances_constant = 2
)

Arguments

Value

A named list of Total Yearly Flow (TYF) matrices, one for each year in year_list.

Calculate Yearly Potential Provision of Ecosystem Services

Description

Calculates the potential provision time series by multiplying indexed habitat extent by the Ecosystem Service (ES) Potential Base.

Usage

get_yearly_potential_provision(
  habitat_extent,
  year_one,
  es_potential_base,
  as_matrices = FALSE
)

Arguments

Value

Depending on the value of as_matrices:

• If FALSE: A data frame with columns raw_total, raw_index, and smoothed_index.

• If TRUE: A named list of annual provision matrices.

Calculate Yearly Potential Wellbeing Contribution

Description

Calculates the potential wellbeing contribution time series by multiplying indexed habitat extent by the Wellbeing Base. It can be understood as the the potential wellbeing contribution of the habitat assets over the years, before weighting by likely flow of ecosystem services based on habitat condition.

Usage

get_yearly_potential_wellbeing(
  habitat_extent,
  year_one,
  wellbeing_potential_base,
  as_matrices = FALSE
)

Arguments

Value

Depending on the value of as_matrices:

• If FALSE: A data frame with columns raw_total, raw_index, and smoothed_index.

• If TRUE: A named list of annual wellbeing matrices.

Import and Process Natural Capital Account Data

Description

This is the primary wrapper function for importing data from the NatureScot NCAI Excel template. It extracts habitat classifications, ecosystem service weights, condition indicators, and yearly measurements, bundling them into a structured list for subsequent index calculations.

Usage

import_ns_data(
  path,
  year_list = 2000:2022,
  total_indicator_relevances_constant = 2
)

Arguments

Value

A named list containing 14 components:

• ns_habitat_extent: Data frame of habitat area per year.

• ns_ci_scores: Data frame of yearly scores for each condition indicator.

• ns_habitats_label_tree: Nested list of cleaned broad and detailed habitat labels.

• ns_es_label_tree: Nested list of cleaned ecosystem service types and specific labels.

• ns_year_list: Character vector of years included in the account.

• ns_provision_per_unit_scores: Data frame of Ecosystem Service Potential Per Unit scores.

• ns_custom_divisor_matrix: Custom matrix of divisors for converting Provision Per Unit scores to weights.

• ns_between_importance_scores: Named list of broad ES importance weights.

• ns_within_importance_scores: Named list of weights for specific services.

• ns_ci_relevance_matrices: List of binary Condition Indicator Relevance Matrices.

• ns_indicator_directory: Data frame mapping condition indicators to services.

• ns_display_habitats_label_tree: Nested list of original habitat names for display.

• ns_display_es_label_tree: Nested list of original ecosystem service names for display.

• ns_display_ci_names: Character vector of condition indicator names in "Number Name" format.

A named list containing structured NCAI data objects.

Import Reference Data for Replication Testing

Description

Imports selected sheets and ranges from the NatureScot NCAI spreadsheet that contain the intermediate and final results of their calculations. This data is used as a "gold standard" to ensure the 'openNCAI' package replicates the methodology reliably.

Usage

import_ns_testing_data(path, habitats_label_tree, es_label_tree, year_list)

Arguments

Value

A nested list containing:

• ref_es_potential_base: Ecosystem Service Potential Base matrix (Sheet 6).

• ref_wellbeing_potential_base: Well-being Base matrix (Sheet 7).

• ref_total_indicator_relevances: Total Indicator Relevances matrix (Sheet 74).

• ref_all_year_sheets: A list of yearly natural capital asset matrices.

• ref_index_breakdowns: Data frames containing the final index and its breakdowns by service type and habitat.

Index matrices and apply smoothing

Description

This function calculates the raw and smoothed Natural Capital Asset Index from a list of yearly asset matrices, e.g. the NCAI matrices. It anchors the index to a specific baseline year and applies a weighted trailing moving average.

Usage

index_and_smooth(
  matrix_list,
  smoothing_weights = c(0.2, 0.4, 0.6, 0.8, 1),
  year_one = names(matrix_list)[[1]]
)

Arguments

Details

Smoothing and Baseline Years: The smoothed index is calculated using a 5-year trailing window via a weighted moving average (using the slider package). 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.

Value

A data frame containing:

• raw_total: The absolute sum of assets for each year.

• raw_index: The index value relative to the baseline year.

• smoothed_index: The weighted 5-year trailing smoothed trend.

Label NCAI Habitat/Ecosystem Service Matrix This function takes a habitat/ecosystem service matrix of values used in openNCAI and returns it as a data frame with the habitat and ecosystem service labels applied.

Description

Label NCAI Habitat/Ecosystem Service Matrix This function takes a habitat/ecosystem service matrix of values used in openNCAI and returns it as a data frame with the habitat and ecosystem service labels applied.

Usage

label_ncai_matrix(matrix, habitats_label_tree, es_label_tree)

Arguments

Value

A labelled data frame.

Generate Custom Divisor Matrix

Description

Creates a matrix of normalization divisors (e.g., scoring scales) for every habitat-service combination. It allows for specific adjustments where certain services or habitats use a different scale (e.g., a 1-point scale instead of a 5-point scale).

Usage

make_custom_divisor_matrix(
  all_habitat_labels,
  all_es_labels,
  habitats_to_adjust,
  services_to_adjust,
  usual_divisor,
  custom_divisor
)

Arguments

Value

A data frame where rows represent habitats and columns represent ecosystem services, containing the divisor values for each intersection.

Ecosystem Service Importance Scores (between-service-type)

Description

A set of scores denoting the importance of each type group of ecosystem services to Scotland.

Usage

ns_between_importance_scores

Format

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.

Condition Indicator Relevance Matrix List

Description

A set of matrices recording whether or not each condition indicator is relevant to each habitat/ecosystem service combination.

Usage

ns_ci_relevance_matrices

Format

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.

Condition Indicator Score Matrix

Description

A matrix containing the raw condition indicator scores over the years of the time series.

Usage

ns_ci_scores

Format

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.

Nature Scot Custom Divisor Matrix

Description

A matrix containing numbers by which the Ecosystem Service Potential per Unit Scores will be divided to calculate a weight.

Usage

ns_custom_divisor_matrix

Format

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 names of Condition Indicators

Description

Display name (no string cleaning) list of condition indicator names which is used internally.

Usage

ns_display_ci_names

Format

A character vector where items are the original number and name of NatureScot's 38 condition indicators:

Display name version of Ecosystem Services Label Tree

Description

Display name version (no string cleaning) version of ns_es_label_tree which is used internally.

Usage

ns_display_es_label_tree

Format

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 of Habitats Label Tree

Description

Display name version (no string cleaning) version of ns_habitats_label_tree which is used internally.

Usage

ns_display_habitats_label_tree

Format

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").

Ecosystem Services Label Tree

Description

A hierarchical tree mapping ecosystem service types to specific ecosystem services.

Usage

ns_es_label_tree

Format

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").

Habitat Extent for Scotland

Description

A table containing the annual extent (area) of various habitats.

Usage

ns_habitat_extent

Format

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.

Habitats Label Tree

Description

A hierarchical tree mapping broad habitat groups to specific habitat types.

Usage

ns_habitats_label_tree

Format

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").

Indicator Directory

Description

A table recording the salience of habitat condition scores as indicators of the likely flow of services under each ecosystem service type.

Usage

ns_indicator_directory

Format

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.

Provision Per Unit Scores

Description

A matrix of scores denoting the exemplary capacity of each habitat to provide each ecosystem service.

Usage

ns_provision_per_unit_scores

Format

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).

Ecosystem Service Importance Scores (within-service-type)

Description

Sets of scores denoting the importance of each ecosystem service to Scotland, within its type group.

Usage

ns_within_importance_scores

Format

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.

Year List

Description

A list of years for which data is available and over which the index will be calculated.

Usage

ns_year_list

Format

A character vector of year labels (e.g., "2000", "2001").

Prepare a blank data frame based on Habitat and ES trees

Description

Prepare a blank data frame based on Habitat and ES trees

Usage

prepare_template_matrix(hab_tree, es_tree)

Read and Process a Populated NCAI Template

Description

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.

Usage

read_ncai_template(path, habitats_label_tree, es_label_tree, ci_names)

Arguments

Value

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.

Examples

# 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)

Read and Label a Specific Yearly Asset Sheet

Description

Read and Label a Specific Yearly Asset Sheet

Usage

read_ns_year_sheet(sheet, path, es_label_tree, habitats_label_tree)

Arguments

Value

A labeled data frame representing the asset matrix for a single year.

Read Yearly Condition Indicator Scores

Description

Read Yearly Condition Indicator Scores

Usage

read_the_ci_scores(path, sheet_list, vector_range, ci_ids)

Arguments

Read Index and Breakdown Results

Description

Extracts the final index values (total, raw index, and smoothed index) for specific breakdowns (e.g., by habitat or service type) from the results sheet.

Usage

read_the_indices(indices_range, path, sheet, year_list)

Arguments

Value

A data frame with years as row names and columns for raw total, raw index, and smoothed index.

Write Condition Scores Time-Series Sheet

Description

Write Condition Scores Time-Series Sheet

Usage

write_condition_scores_sheet(
  wb,
  sheet_name,
  ci_names,
  years,
  source_data = NULL
)

Write Habitat Extent Time-Series Sheet

Description

Write Habitat Extent Time-Series Sheet

Usage

write_extent_sheet(
  wb,
  sheet_name,
  hab_tree,
  years,
  hab_palette,
  source_data = NULL
)

Write the specialized Importance Weights sheet

Description

Write the specialized Importance Weights sheet

Usage

write_importance_sheet_with_data(
  wb,
  sheet_name,
  es_tree,
  between_data,
  within_list,
  instruction_style,
  entry_style
)

Write Indicator Directory Sheet

Description

Write Indicator Directory Sheet

Usage

write_indicator_directory(
  wb,
  sheet_name,
  ci_names,
  es_types,
  source_data = NULL
)

Write standard Matrix sheets (e.g., ES Potential or CI Relevance)

Description

Write standard Matrix sheets (e.g., ES Potential or CI Relevance)

Usage

write_input_matrix(
  wb,
  sheet_name,
  data_df,
  hab_tree,
  es_tree,
  style_obj,
  hab_palette,
  thick_border_style,
  instruction_style,
  instruction
)

Write a clean Instructions sheet at the start of the workbook

Description

Write a clean Instructions sheet at the start of the workbook

Usage

write_instructions_sheet(wb, sheet_name)