# openNCAI in Brief

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:

    library(openNCAI)

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
                  )

    ## openNCAI missingness check:
    ## habitat_extent            ✓ Complete.
    ## ci_scores                 ✓ Complete.
    ## habitats_label_tree       ✓ Complete.
    ## es_label_tree             ✓ Complete.
    ## year_list                 ✓ Complete.
    ## provision_per_unit_scores ✓ Complete.
    ## between_importance_scores ✓ Complete.
    ## within_importance_scores  ✓ Complete.
    ## ci_relevance_matrices     ✓ Complete. (38 elements)
    ## indicator_directory       ✓ Complete.

    ## Note: NCAI calculated using a custom divisor matrix for Provision Per Unit weights.

Let’s see what is returned:

    scot_ncai

    ##      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.82806

Three 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:

    ?openNCAI

### Learn more

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.

    # Access the vignette:
    vignette("using_openNCAIs_data_entry_templates", package = "openNCAI")

To understand more about the calculation process which openNCAI reproduces, look at this diagram:

NCAI Calculation Process Diagram

### Details of the bundled data objects

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.

#### Metadata objects

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.

#### Environmental measurements objects

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.

#### Weighting objects

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.

1. European Nature Information System↩︎

2. Common International Classification of Ecosystem Services↩︎

3. System of Environmental-Economic Accounting↩︎