indiGO_Tutorial1.0.qmd

---
title: "How to use the indiGO R Package"
subtitle: "indiGO Tutorial 1.0"
author: Jessica Hetzer (jessica.hetzer@senckenberg.de)
execute:
  warning: false
format:
  html:
    number-sections: true
    toc: true        
    toc-depth: 3    
---

```{r, echo=FALSE}
library(kableExtra)
library(devtools)
library(dbplyr)
```


# Package description

The indiGO R package provides an open-access framework that enables users to access annually aggregated indicators as described in the [first Global Assessment Report on Biodiversity and Ecosystem Services](https://doi.org/10.5281/zenodo.3831673) by the Intergovernmental Science-Policy Platform on Biodiversity and Ecosystem Services (IPBES, 2019). It follows the standardization of indicators outlined in the supplementary material of the Global Assessment Report, [Chapter 2.2: Status and Trends – Nature](https://doi.org/10.5281/zenodo.3832005).

The package offers a flexible framework for handling a wide variety of indicators, not limited to a specific region, ecosystem, or time period. Its generalized outputs are broad and adaptable, allowing users to apply them to various data sets or indicator types across global or regional scales. Additionally, indiGO allows users to include their own data, enabling local data integration for customized indicator analysis.

# Download and install

You can download and install the indiGO R package directly from the [indiGO R package GitHub repository](https://github.com/IPBES-Data/indiGO) using the following commands in R:

``` r
# Install devtools if not already installed
install.packages("devtools")

# Install indiGO package from GitHub
devtools::install_github("IPBES-Data/indiGO")
```

# Indicator data included

The package includes a variety of indicator data, in specific data sets that represent the state of nature globally or across multiple regions. The package focuses on the indicators defined and classified by IPBES (2019). Indicators are assigned to Essential Biodiversity Variable (EBV) classes and categorized based on their relevance to ecosystems and their sensitivity to human impacts. For an overview of the indicator meta data see Table 1, which can be loaded using the indiGO function `indi_summary()`.

```{r}
Table1<-indiGO::indi_summary()
```

***Table 1: Example of indicator metadata**. This internally loaded data table includes the indicator names "Indicator", data sources "Reference", and the Essential Biodiversity Variable "EBV.Class" as designated by IPBES (2019). The column "Core.Highlight.Other" represents the Knowledge & Data TSU’s assessment of the importance of each indicator. While all indicators are available as globally aggregated values, some specify subsets of these metrics. For example, the global Red List Index indicator is further broken down into subsets, such as the Red List Index of pollinators. The column "Whole.or.Part.of.indicator" indicates whether the entry represents the overall indicator or a subset.*

```{r, echo=FALSE}

Table1 %>%
  dplyr::select(1, 2, 5, 3, 4) %>% 
  head(25) %>%
  kbl(escape = FALSE) %>%
  kable_styling(bootstrap_options = c("striped", "hover", "condensed", "responsive")) 
```

The package provides an internal function, `indi_search()`, to explore the available data. This function allows you to filter and display files that match a specific pattern in their filenames. For example, to list all files related to biodiversity, you can use the following:

```{r}
indiGO::indi_search("biodiversity")
```

Data can be loaded into the R environment using the `indi_data("indicatorName")` function. This function retrieves the data in its raw form, exactly as it is stored in the file.

```{r}
indiGO::indi_data("biodiversity_habitat_index_hotspots")
```

**Advanced**

The package provides the option to analyze local files formatted in the same way as the package's internal data (i.e., .txt files with two columns: year and value). To specify the local directory, adjust the `indicatorDataPath` option. Additionally, each indicator data file is accompanied by a corresponding `.yaml` file located in the internal folder `indicatorConfigPath`. These YAML files contain metadata and settings for plots, such as the plot title, full name, and other configurations.

```{r}
#options(indicatorDataPath = "\path\to\local\DATA\directory")
#options(indicatorConfigPath = "\path\to\local\CONFIG\directory")

```

# Exploring indiGO package functionalities

Trends over time in comparison o a pristine world can be examined using the `plot_scaled_to_remaining("indicatorName")` function, while changes since 1970 can be assessed with `plot_scaled_to_1970("indicatorName")`, displaying the globally aggregated value standardized to a percentage or relative to its 1970 value.

```{r, fig.width=15, fig.height=5}
indiGO::plot_indi_data("extent_of_forests")
indiGO::plot_scaled_to_remaining("extent_of_forests")
indiGO::plot_scaled_to_1970("extent_of_forests")
```

Finally, to display the status and trends of the indicator side by side, the `plot_indiGO()` function can be used:

```{r,fig.width=15, fig.height=5}
indiGO::plot_indiGO("extent_of_forests")
```

# Display all indicators available

## Indicators of ecosystem structure

### Aboveground biomass

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("aboveground_biomass")
```

indiGO::plot_indiGO

### Biodiversity Habitat Index (overall habitat integrity)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("biodiversity_habitat_index_overall")
indiGO::plot_indiGO("biodiversity_habitat_index_hotspots")
indiGO::plot_indiGO("biodiversity_habitat_index_invertebrates")
indiGO::plot_indiGO("biodiversity_habitat_index_plants")
indiGO::plot_indiGO("biodiversity_habitat_index_vertebrates")
```

### Coastal protection habitats

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("coastal_protection_habitats_overall")

```

Subset: Coastal carbon-rich habitat

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("coastal_protection_habitats_natural")

```

### Extent of forests

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("extent_of_forests")

```

### Extent of intact forest landscapes

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("extent_of_intact_forest_landscapes")
```

### Extent of marine wilderness

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("extent_of_marine_wilderness")
```

### Extent of terrestrial wilderness

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("extent_of_terrestrial_wilderness")
```

### Fraction of ocean not fished per year

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("fraction_of_ocean_not_fished_per_year")

```

### Land not cultivated or urban

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("land_not_cultivated_or_urban_overall")
indiGO::plot_indiGO("land_not_cultivated_or_urban_hotspot")
indiGO::plot_indiGO("land_not_cultivated_or_urban_indigenous_land")
indiGO::plot_indiGO("land_not_cultivated_or_urban_tundra_and_mountains")
indiGO::plot_indiGO("land_not_cultivated_or_urban_desert_and_drylands")
indiGO::plot_indiGO("land_not_cultivated_or_urban_temperate_forests")
indiGO::plot_indiGO("land_not_cultivated_or_urban_mediterranean_forests")
indiGO::plot_indiGO("land_not_cultivated_or_urban_tropical_grassland")
indiGO::plot_indiGO("land_not_cultivated_or_urban_tropical_forests")
indiGO::plot_indiGO("land_not_cultivated_or_urban_temperate_grassland")


```

### Mangrove forest area

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("mangrove_forest_area")

```

### Natural habitat extent

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("natural_habitat_extent")

```

### Percentage of live coral cover

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("percentage_of_live_coral_cover")

```

### Permanent surface water extent

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("permanent_surface_water_extent")
```

### Remaining primary vegetation

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("remaining_primary_vegetation")
indiGO::plot_indiGO("remaining_primary_vegetation_hotspot")
indiGO::plot_indiGO("remaining_primary_vegetation_indigenous_land")

```

### Seagrass meadow area

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("seagrass_meadow_area")
```

### Soil organic carbon (correlative model)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("soil_organic_carbon_correlative_model")

```

### Soil organic carbon (mechanistic models)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("soil_organic_carbon_mechanistic_models")
```

### Tree cover

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("tree_cover")

```

### Vegetation biomass (mechanistic model)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("vegetation_biomass_mechanistic_model")
```

### Wetland Extent Trends index

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("wetland_extent_trends_index")
```

## Indicators of ecosystem function

### Biological pump efficiency

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("biological_pump_efficiency")
```

### Biomass turnover rate

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("biomass_turnover_rate")
```

### Evapotranspiration (model ensemble)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("evapotranspiration_model_ensemble")
```

### Marine net primary productivity (remote-sensing)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("marine_net_primary_productivity_remote_sensing")
```

### NPP remaining in terrestrial ecosystems

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("npp_remaining_in_terrestrial_ecosystems")
```

### Oceanic carbon sequestration

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("oceanic_carbon_sequestration")	

```

### Terrestrial carbon sequestration (model ensemble)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("terrestrial_carbon_sequestration_model_ensemble")	
```

### Terrestrial NPP (model ensemble)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("terrestrial_npp_model_ensemble")	
```

### Terrestrial NPP (remote-sensing)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("terrestrial_npp_remote_sensing")	
```

## Indicators of community composition – local scale

### Biodiversity Intactness Index (overall)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("biodiversity_intactness_index_overall")	
indiGO::plot_indiGO("biodiversity_intactness_index_hotspots")	
indiGO::plot_indiGO("biodiversity_intactness_index_indigenous_land")	
```

Subset: Tropical Forest BII

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("biodiversity_intactness_index_tropical_forest")		
indiGO::plot_indiGO("biodiversity_intactness_index_tropical_forest_indigenous_land")		


```

### Local species richness (BioTime)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("local_species_richness_biotime")	

```

### Local species richness (PREDICTS)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("local_species_richness_predicts")

```

### Mean Species Abundance index

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("mean_species_abundance_index_lu")
indiGO::plot_indiGO("mean_species_abundance_index_cc")
indiGO::plot_indiGO("mean_species_abundance_index_hotspots")
indiGO::plot_indiGO("mean_species_abundance_index_indigenous_land")
```

## Indicators of community composition – regional scale

### Bird species per grid cell (cSAR)

#indiGO::plot_indiGO("sar_iDiv_Allbirds_Localtoglobal.csv")

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("bird_species_per_grid_cell_csar_overall")

```

Subset: Forest-specialist bird species per grid cell (cSAR)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("bird_species_per_grid_cell_csar_forest_specialists")

```

### Cumulative number of alien species

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("cumulative_number_of_alien_species")
```

### Cumulative introduced invasive aliens

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("cumulative_introduced_invasive_aliens")

```

### Functional intactness (Madingley)

```{r, fig.width=15, fig.height=5}
 indiGO::plot_indiGO("functional_intactness_madingley")  
```

### Species richness per grid cell (AIM)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("species_richness_per_grid_cell_aim_overall") 
indiGO::plot_indiGO("species_richness_per_grid_cell_aim_amphibians") 
indiGO::plot_indiGO("species_richness_per_grid_cell_aim_birds") 
indiGO::plot_indiGO("species_richness_per_grid_cell_aim_mammals") 
indiGO::plot_indiGO("species_richness_per_grid_cell_aim_plants") 
indiGO::plot_indiGO("species_richness_per_grid_cell_aim_reptiles") 

```

## Indicators of species population – species persistence

### Biodiversity Habitat Index (species persistence)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("biodiversity_habitat_index_species_persistence_overall") 
indiGO::plot_indiGO("biodiversity_habitat_index_species_persistence_hotspots") 
indiGO::plot_indiGO("biodiversity_habitat_index_species_persistence_invertebrates") 
indiGO::plot_indiGO("biodiversity_habitat_index_species_persistence_plants") 
indiGO::plot_indiGO("biodiversity_habitat_index_species_persistence_vertebrates") 

```

### Global bird species richness change (cSAR)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("bird_species_per_grid_cell_csar_overall")

```

Subset: Global forest-specialist bird richness (cSAR)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("bird_species_per_grid_cell_csar_forest_specialists")

```

### Global mammal and bird species remaining

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("global_mammal_and_bird_species_remaining") 

```

### Red List Index (overall)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("red_list_index_overall") 

```

Subset: Red List Index (forest specialists)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("red_list_index_forest_specialists") 

```

Subset: Red List Index (internationally traded species)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("red_list_index_internationally_traded_species")

```

### Driver-specific Red List Indices

Subset: Red List Index (impacts of invasive alien species)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("red_list_index_impacts_of_invasive_alien_species")

```

Red List Index (impacts of utilisation)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("red_list_index_impacts_of_utilisation")
```

Red List Index (Impacts of pollution)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("red_list_index_impacts_of_pollution")

```

Red List Index (Impacts of fisheries)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("red_list_index_impacts_of_fisheries")
```

## Indicators of species population – geographic distribution

### Extent of suitable habitat (mammals)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("extent_of_suitable_habitat_mammals")

```

### Mammalian range size

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("mammalian_range_size")
```

Subset: Megafaunal range size

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("megafaunal_range_size")
```

### Species Habitat Index

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("species_habitat_index")

```

## Indicators of species population – population size

### Fish stocks biologically sustainable

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("fish_stocks_biologically_sustainable")

```

### Living Planet Index

```{r, fig.width=15, fig.height=5}
#indiGO::plot_indiGO("Living Planet Index (overall) ") # name
indiGO::plot_indiGO("living_planet_index_freshwater")
indiGO::plot_indiGO("living_planet_index_marine")
indiGO::plot_indiGO("living_planet_index_terrestrial")
```

### Predatory fish biomass

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("predatory_fish_biomass")
```

### Prey fish biomass

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("prey_fish_biomass")
```

### Wild Bird Index (habitat specialists)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("wild_bird_index_habitat_specialists")

```

### Wild mammal biomass

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("wild_mammal_biomass")
```

## Indicators of species traits

### Functional richness (Madingley)

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("functional_richness_madingley")

```

### Mammalian body mass

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("mammalian_body_mass")

```

### Region-based Marine Trophic Index

```{r, fig.width=15, fig.height=5}
indiGO::plot_indiGO("region_based_marine_trophic_index")

```