## -----------------------------------------------------------------------------
library(openNCAI)

## -----------------------------------------------------------------------------
# The packaged data objects all have names beginning with `ns_` (for NatureScot):
ls("package:openNCAI", patter = "^ns_")

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

## -----------------------------------------------------------------------------
scot_ncai

## ----fig.width=7, fig.height=5, out.width="100%"------------------------------
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
)

## -----------------------------------------------------------------------------
?openNCAI

## ----run-big-vignette, eval = FALSE-------------------------------------------
# # Access the vignette within R with this command:
# vignette("replicating_scotlands_ncai", package = "openNCAI")

## ----run-data-entry-vignette, eval = FALSE------------------------------------
# # Access the vignette:
# vignette("using_openNCAIs_data_entry_templates", package = "openNCAI")

## ----echo=FALSE, fig.cap="NCAI Calculation Process Diagram", out.width="100%"----
knitr::include_graphics("../man/figures/ncai_calculation_process.png")

## -----------------------------------------------------------------------------
d_subset <- data.frame(
  `Object Name` = c(
    "ns_habitats_label_tree", 
    "ns_es_label_tree", 
    "ns_year_list",
    "ns_display_habitats_label_tree",
    "ns_display_es_label_tree",
    "ns_display_ci_names"
  ),
  `Description` = c(
    "Habitats Label Tree: a hierarchy of natural habitats (based on EUNIS[^1] level 2) grouped within their respective broad habitat categories (EUNIS level 1) found in Scotland.",
    "Ecosystem Services Label Tree: a hierarchy of individual CICES-style[^2] ecosystem services organized by their SEEA[^3] service type groups (Provisioning, Regulation & Maintenance, and Cultural).",
    "Year List: the specific range of years over which the index is calculated.",
    "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()`",
    "The display names version of the Ecosystem Services Label Tree.",
    "A list of the Condition Indicator labels, again before cleaning."
  ),
  `Data Format` = c(
    "A named list of character vectors where names are broad habitats and vectors contain the specific habitats within them.",
    "A named list of character vectors where names are service types and vectors contain the individual services.",
    "A character vector of years.",
    "A named list of character vectors where names are broad habitats and vectors contain the specific habitats within them.",
    "A named list of character vectors where names are service types and vectors contain the individual services.",
    "A character vector of Condition Indicator labels."
  ),
  check.names = FALSE
)

knitr::kable(d_subset)

## -----------------------------------------------------------------------------
d_subset <- data.frame(
  `Object Name` = c(
    "ns_habitat_extent", 
    "ns_ci_scores"
  ),
  `Description` = c(
    "Habitat Extent for Scotland: measurement in hectares of the area of each natural habitat over the years.",
    "Condition Indicator Score Matrix: yearly condition score on each of the Condition Indicators (CIs)."
  ),
  `Data Format` = c(
    "A data frame where rows are habitats and columns are years.",
    "A data frame where rows are years and columns are CIs."
  ),
  check.names = FALSE
)

knitr::kable(d_subset)

## -----------------------------------------------------------------------------
d_subset <- data.frame(
  `Object Name` = c(
    "ns_provision_per_unit_scores", 
    "ns_between_importance_scores", 
    "ns_within_importance_scores", 
    "ns_ci_relevance_matrices", 
    "ns_indicator_directory", 
    "ns_custom_divisor_matrix"
  ),
  `Description` = c(
    "Provision Per Unit Scores: scores denoting the relative capacity of one area unit of a habitat to provide each of the ecosystem services.",
    "Ecosystem Service Importance Scores (**between**-service-type): scores denoting the relative importance of the different ecosystem service **types** ('Provisioning', 'Regulation & Maintenance', 'Cultural') to Scotland.",
    "Ecosystem Service Importance Score (**within**-service-type): scores denoting the relative importance of individual ecosystem services within their service type group.",
    "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').",
    "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.",
    "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)."
  ),
  `Data Format` = c(
    "A data frame where rows are habitats and columns are ecosystem services.",
    "A named list of numeric values where names match the top-level names of the Service Label Tree.",
    "A nested list of named lists, with a hierarchy matching the Service Label Tree.",
    "A named list of data frames (one per CI) with binary (1/0) values; rows are habitats and columns are ecosystem services.",
    "A data frame with a `ci_id` column and columns for each ecosystem service type containing salience scores.",
    "A data frame where row names are habitats and column names are ecosystem services."
  ),
  check.names = FALSE
)

knitr::kable(d_subset)