---
title: 'README: GMBA SDG 15.4.1 Calculator'
author: "Amina Ly"
date: "02/10/2023"
output:
  html_document: default
  pdf_document: default
---

## Code Contributors: 
Amina Ly, Stanford University 2021-22
Mark Snethlage, University of Bern, 2021-22

"Intersection_Official" and "Intersection GMBA" are based on
code by Ash Simkins & Lizzie Pearmain, March 2020

## OS Requirements
This code has been tested on Linux and MAC OSX operating systems and should operate on 
Linux, Mac OSX, and Windows

The code was created and tested on R versions 4.1.1 and 4.1.2

## Purpose:
This project contains a set of scripts used to calculate mountain biodiversity protections 
utilizing the GMBA mountain inventory V2.0. Contents of this project are aimed at 
improving reporting progress towards SDG 15.4.1 by disaggregating calculations 
to the mountain level 

## Data Availability: 
The most recent version of World Database on Protected Areas (WDPA) can be accessed through the website: https://www.protectedplanet.net/en/thematic-areas/wdpa?tab=WDPA. Data on key biodiversity areas (KBA) can be accessed by request via this form: https://www.keybiodiversityareas.org/kba-data/request. The GMBA mountain inventory is accessible online: https://www.earthenv.org/mountains. Preselection of mountainous KBAs provided by Bird Life International as one of the indicator custodians, and the data file is available as part of our repository: https://github.com/GMBA-biodiversity/SDG15.4.1_Calculator/tree/master/data/KBA/kba_class_2020.csv 

Two versions of the GMBA Mountain Inventory v 2.0 were used in this analysis:
- "standard", in which the outer borders of the mountain range polygons correspond to the new (conservative) GMBA mountain definition, and

- "broad" in which these outer borders correspond to the union of the three major mountain definitions (including the UNEP-WCMC mountain definition, which is used in the official site-based calculation of SDG 15.4.1)

## Setup: 

The results of this analysis are reproducible using only this repo, and all r
required input data files. To do so:

1. Clone this repository
2. Download data files (see metadata for list of necessary input files)
3. Run the desired analysis (see below for details)

### Intersection_Official.R :
Calculate the % coverage of mountainous Key Biodiversity Areas (KBAs) by 
Protected Areas (PAs) using the official SDG method. For any KBA that overlaps
with one or more polygons of the GMBA Mountain Inventory v2.0 (Broad), the KBA 
is assigned to the GMBA polygon with which it has the largest overlap., the _full_ KBA 
is overlapped with all PAs to determine the % coverage. For PAs that increase in size,
each additional entry is the additional overlap. Initial output results are _not_ cumulative. 
Adapted from the Birdlife International script:  (https://github.com/BirdLifeInternational/kba-overlap)

Runtime: Full dataset will take 8-15 hours depending on compute power

#### Output: 
   + **/results/finaltab_official_'YEAR_RUN'.csv"** : table with % added coverage for
   each KBA
   + **/results/results_official/...** : folder with country-specific results
   
### Intersection_GMBA.R
Calculate the % coverage of mountainous Key Biodiversity Areas (KBAs) by 
Protected Areas (PAs) using the new GMBA proposed method. For any KBA that overlaps
with one or more polygons of the GMBA Mountain Inventory 2.0 (Standard),
the _KBA is intersected_ with the mountain, and then overlapped
with all PAs to determine the % coverage. For PAs that increase in size, each 
additional entry is the additional overlap. Initial output results are _not_ 
cumulative. Adapted from the Birdlife International script:  
(https://github.com/BirdLifeInternational/kba-overlap)

Runtime: Full dataset will take 8-15 hours depending on compute power

#### Output: 
  + **/results/finaltab_gmba_'YEAR_RUN'.csv** : table with % coverage of each 
  mountainous area of each KBA as identified by the GMBA polygons
  + **/results/results_mt/...** : folder with mountain range-specific results
  
## Additional Scripts:

### Data_Prep_for_Visuals.R

To simplify aggregation and translate the data to show cumulative coverage for 
every year, this script reads in the results of a previous run (updated by user
in section 1.2), and outputs multiple aggregation files.

Runtime: Full dataset will take 5-15 minutes depending on compute power

#### Output: 

Four main output files are created after running the above script: 

  + **results/results_all_years.csv** : cumulative coverage by KBA for every year 
  starting with the minimum year in the result file when using the official
  SDG 15.4.1 method. Each row is the total coverage for a KBA in that year. 
  All aggregations for official results come from this dataset
  
  + **results/results_gmba_all_years.csv** : cumulative coverage by KBA for every year 
  starting with the minimum year in the result file when using the GMBA proposed
  method. Each row is the total coverage for a KBA in that year. All aggregations 
  for official results come from this dataset
  
  + **results/clean_data_for_visuals_range_MONTHYEAR.csv** : All range-level 
  aggregations for both official WCMC method and GMBA proposed method
  
      + Country_Highland_KBAPA_WCMC_Area
      + Range_Highland_KBAPA_WCMC_Area
      + CountryRange_Highland_KBAPA_WCMC_Area
      + Country_Highland_KBAPA_WCMC_Site
      + Range_Highland_KBAPA_WCMC_Site
      + CountryRange_Highland_KBAPA_WCMC_Site
      + Country_Highland_KBAPA_GMBA_Area
      + Range_Highland_KBAPA_GMBA_Area
      + CountryRange_Highland_KBAPA_GMBA_Area

  + **results/clean_data_for_visuals_system_MONTHYEAR.csv** : All range-level 
  aggregations for both official WCMC method and GMBA proposed method
      + System_Highland_KBAPA_WCMC_Area
      + CountrySystem_Highland_KBAPA_WCMC_Area
      + System_Highland_KBAPA_WCMC_Site
      + CountrySystem_Highland_KBAPA_WCMC_Site
      + System_Highland_KBAPA_GMBA_Area 
      + CountrySystem_Highland_KBAPA_GMBA_Area
      
  
See associated publication (Ly et al. 2023) for details on aggregation levels