Data Supplement: Demeter v1.2.0 Example Data

This data set is to accompany the version 1.2.0 release of Demeter.  Demeter can be accessed on GitHub here:  https://github.com/JGCRI/demeter

## Structure
demeter_v1.2.0_data_supplement
├── config_gcam_reference.ini
├── example.py
├── inputs
│   ├── allocation
│   │   ├── gcam_regbasin_modis_v6_type5_5arcmin_constraint_alloc.csv
│   │   ├── gcam_regbasin_modis_v6_type5_5arcmin_kernel_weighting.csv
│   │   ├── gcam_regbasin_modis_v6_type5_5arcmin_observed_alloc.csv
│   │   ├── gcam_regbasin_modis_v6_type5_5arcmin_order_alloc.csv
│   │   ├── gcam_regbasin_modis_v6_type5_5arcmin_projected_alloc.csv
│   │   └── gcam_regbasin_modis_v6_type5_5arcmin_transition_alloc.csv
│   ├── constraints
│   │   ├── 000_nutrientavail_hswd_5arcmin.csv
│   │   └── 001_soilquality_hswd_5arcmin.csv
│   ├── observed
│   │   └── gcam_reg32_basin235_modis_v6_2010_5arcmin_sqdeg_wgs84_11Jul2019.zip
│   └── projected
│       └── gcam_ref_scenario_reg32_basin235_v5p1p3.csv
└── outputs
    └── gcam5p1p3_ref_2021-05-19_10h57m15s
        ├── log_files
        │   └── logfile_gcam5p1p3_ref_2021-05-19_10h57m15s.log
        └── spatial_landcover_tabular
            ├── landcover_2010_timestep.csv
            ├── landcover_2015_timestep.csv
            ├── landcover_2020_timestep.csv
            └── landcover_2025_timestep.csv

## Context
- **demeter_v1.2.0_data_supplement**: root directory
- **config_gcam_reference.ini**: example configuration file for Demeter.  The `run_dir` needs to be set to the directory where this data has been downloaded to.
- **example.py**: sample Python script to run Demeter 
- **inputs**:  directory containing the model input files 
- **allocation**:  directory containing the model allocation input files 
- **gcam_regbasin_modis_v6_type5_5arcmin_constraint_alloc.csv**: allocation file to weight the influence of constraint.  See https://github.com/JGCRI/demeter#constraint-weighting
- **gcam_regbasin_modis_v6_type5_5arcmin_kernel_weighting.csv**: allocation file to weight the influence of kernel density on extensification.  See https://github.com/JGCRI/demeter#kernel-density-weighting
- **gcam_regbasin_modis_v6_type5_5arcmin_observed_alloc.csv**: allocation file to bin land classes in the observed spaital data input to Demeter's final output land types.  See https://github.com/JGCRI/demeter#observational-spatial-data-class-allocation
- **gcam_regbasin_modis_v6_type5_5arcmin_order_alloc.csv**:  allocation file having the order in which land classes will be processed.  See https://github.com/JGCRI/demeter#treatment-order
- **gcam_regbasin_modis_v6_type5_5arcmin_projected_alloc.csv**:  allocation file to bin the land classes in the projected data input to Demeter's final output land classes.  See https://github.com/JGCRI/demeter#projected-land-class-allocation
- **gcam_regbasin_modis_v6_type5_5arcmin_transition_alloc.csv**: allocation file that defines the order in which one land class should transition to another.  See https://github.com/JGCRI/demeter#transition-priority
- **constraints**:  directory containing the model constraints 
- **000_nutrientavail_hswd_5arcmin.csv**: constraint file for nutrient availability from data provided in the Harmonized World Soil Database (HWSD) and described in Le Page et al. 2016 containing a feature id matching that in the observed spatial data and a weight per grid cell that describes how suitable a grid cell is for the target constraint. 
- **001_soilquality_hswd_5arcmin.csv**: constraint file for soil workability from data provided in the Harmonized World Soil Database (HWSD) and described in Le Page et al. 2016 containing a feature id matching that in the observed spatial data and a weight per grid cell that describes how suitable a grid cell is for the target constraint.
- **observed**:  directory containing the observed spatial base layer data for Demeter 
- **gcam_reg32_basin235_modis_v6_2010_5arcmin_sqdeg_wgs84_11Jul2019.zip**:  compressed CSV file of a 5-arcmin (0.083333-degree) resolution dataset of land cells that have a region/basin designation in GCAM.  Values are in units square degrees.  The observed data was derived from MODIS v6 Classification Scheme 5 data (Friedl et al. 2010) and binned into Demeter's final land cover types for each 5-arcmin grid cell
- **projected**: directory containing the projected data file
- **gcam_ref_scenario_reg32_basin235_v5p1p3.csv**: projected land allocation data for years 2010 through 2100 derived from a Global Change Analysis Model (GCAM; Calvin et al. 2019) version 5.1.3 output database for a Reference scenario. Demeter can build this file directly from a GCAM output XML database by adding the `gcam_database` option with a path to a target database into the `[PROJECTED]` section of the configuration file if so desired.  GCAM output databases can be rather large; therefore, we provide the output of that query as a CSV in this data record.
- **outputs**: directory containing the expected outputs from a Demeter run under the example configuration for years 2010 through 2025 in 5 year timesteps
- **gcam5p1p3_ref_2021-05-19_10h57m15s**:  directory from the example Demeter run to compare against.  Other runs will generate a new directory with the appropriate time stamp.
- **log_files**:  directory containing any log files 
- **logfile_gcam5p1p3_ref_2021-05-19_10h57m15s.log**: log file from the example run 
- **spatial_landcover_tabular**:  directory containing the outputs from Demeter 
- **landcover_2010_timestep.csv**:  output file from Demeter containing the fraction of land for each 5-arcmin grid cell for each final land type from Demeter for year 2010.  Units are in fraction of a grid cell.  Spatial reference is EPSG:4326 (WGS84) for the latitude and longitude of each grid cell centroid in degrees.
- **landcover_2015_timestep.csv**:  output file from Demeter containing the fraction of land for each 5-arcmin grid cell for each final land type from Demeter for year 2015.  Units are in fraction of a grid cell.  Spatial reference is EPSG:4326 (WGS84) for the latitude and longitude of each grid cell centroid in degrees.
- **landcover_2020_timestep.csv**:  output file from Demeter containing the fraction of land for each 5-arcmin grid cell for each final land type from Demeter for year 2020.  Units are in fraction of a grid cell.  Spatial reference is EPSG:4326 (WGS84) for the latitude and longitude of each grid cell centroid in degrees.
- **landcover_2025_timestep.csv**:  output file from Demeter containing the fraction of land for each 5-arcmin grid cell for each final land type from Demeter for year 2025.  Units are in fraction of a grid cell.  Spatial reference is EPSG:4326 (WGS84) for the latitude and longitude of each grid cell centroid in degrees.

## References
Calvin, K., Patel, P., Clarke, L., Asrar, G., Bond-Lamberty, B., Cui, R. Y., Di Vittorio, A., Dorheim, K., Edmonds, J., Hartin, C., Hejazi, M., Horowitz, R., Iyer, G., Kyle, P., Kim, S., Link, R., McJeon, H., Smith, S. J., Snyder, A., Waldhoff, S., and Wise, M.: GCAM v5.1: representing the linkages between energy, water, land, climate, and economic systems, Geosci. Model Dev., 12, 677–698, https://doi.org/10.5194/gmd-12-677-2019, 2019.

Friedl, M. A., Sulla-Menashe, D., Tan, B., Schneider, A., Ramankutty, N., Sibley, A., andHuang, X. (2010). MODIS Collection 5 global land cover: Algorithm refinements and characterization of new datasets. Remote Sensing of Environment, 114, 168–182

Le Page, Y, West, T, Link, R and Patel, P 2016 Downscaling land use and land cover from the Global Change Assessment Model for coupling with Earth system models. Geosci. Model Dev., 9: 3055–3069. DOI: https://doi.org/10.5194/gmd-9-3055-2016