CEDS documentation for SLCF

docs/dataset-overviews/anthropogenic-slcf-co2-emissions.md

@@ -1,83 +1,182 @@
-<!--- These values are used by `fill-out-auto-generated-sections.py` -->
-<!--- forcing="Anthropogenic short-lived climate forcer (SLCF) and CO<sub>2</sub> emissions" -->
-<!--- source_id_stub="CEDS-CMIP" -->
-# Anthropogenic short-lived climate forcer (SLCF) and CO<sub>2</sub> emissions
-
-**This section is a work in progress.**
-**For a first draft, see https://github.com/PCMDI/input4MIPs_CVs/pull/146**
-
-## Key contacts
-
-- Names: Rachel Hoesly, Steve Smith
-- Emails: [email protected]; [email protected]
-
-## Summary
-
-CEDS data is available for testing (see the section below).
-However, note that CEDS' testing data is published under multiple source IDs.
-For everything except aircraft emissions, bulk NMVOCs and speciatated NMVOCs, 
-use the source ID "CEDS-CMIP-2024-11-25".
-For aircraft emissions and speciatated NMVOCs, use the source ID "CEDS-CMIP-2024-10-21".
-It is also worth noting that solid biofuel emissions and speciatated NMVOCs 
-have the suffix "-supplemental" added to their source ID
-(to avoid inadvertent double counting).
-
-<!--- begin-cmip7-phases-source-ids -->
-<!--- Do not edit this section, it is automatically updated when the docs are built -->
-### Source IDs for CMIP7 phases
-
-The source ID that identifies the dataset to use in the different phases of CMIP7 is given below.
-
-#### Testing
-
-For the testing of CMIP7, you will need data from the following source IDs:
-
-- [CEDS-CMIP-2024-10-21](https://aims2.llnl.gov/search?project=input4MIPs&versionType=all&&activeFacets=%7B%22source_id%22%3A%22CEDS-CMIP-2024-10-21%22%7D)
-- [CEDS-CMIP-2024-11-25](https://aims2.llnl.gov/search?project=input4MIPs&versionType=all&&activeFacets=%7B%22source_id%22%3A%22CEDS-CMIP-2024-11-25%22%7D).
-
-Retrieving and only using valid data will require some care.
-Please make sure you read the guidance given at the start of this Summary section
-and process the data carefully.
-
-This data is for testing (both of the forcing data and of modelling workflows) only.
-Production simulations should not be started based on any data that has a `mip_era` value equal to 'CMIP6Plus'.
-(The `mip_era` metadata value appears both in each file's global attributes as well as its metadata on ESGF.)
-
-If you have any feedback, please add it to the [relevant GitHub discussion](https://github.com/PCMDI/input4MIPs_CVs/discussions).
-
-#### CMIP7 AR7 fast track
-
-No data available for this phase yet.
-
-This data will be for the CMIP7 AR7 fast track.
-All data sets for use in the fast track will be published with a `mip_era` metadata value of 'CMIP7'.
-This metadata value will appear both in the file's global metadata as well as its metadata on ESGF.
-
-Further details will follow in early 2025.
-
-#### CMIP7
-
-No data available for this phase yet.
-
-This data will be for CMIP7.
-All data sets for use in CMIP7 will be published with a `mip_era` metadata value of 'CMIP7'.
-This metadata value will appear both in the file's global metadata as well as its metadata on ESGF.
-
-Further details will follow after the fast track is underway
-(including details about how updates to this data will be handled over the lifetime of CMIP7).
-
-<!--- end-cmip7-phases-source-ids -->
-
-<!--- placeholder for piControl recommendation -->
-## Navigating the data
-
-### Recommendation for pre-industrial control
-
-Apply the 1850 values on repeat.
-
-<!--- end of placeholder for piControl recommendation -->
-
-<!--- begin-revision-history -->
-<!--- Do not edit this section, it is automatically updated when the docs are built -->
-<!--- No revisions, hence section is blank -->
-<!--- end-revision-history -->
+<!--- These values are used by `fill-out-auto-generated-sections.py` -->
+<!--- forcing="Anthropogenic short-lived climate forcer (SLCF) and CO<sub>2</sub> emissions" -->
+<!--- source_id_stub="CEDS-CMIP" -->
+# Anthropogenic short-lived climate forcer (SLCF) and CO<sub>2</sub> emissions
+
+## Key contacts
+
+- Names: Rachel Hoesly, Steve Smith
+- Emails: [email protected]; [email protected]
+
+## Summary
+
+CEDS data is available for testing (see the section below).
+Emissions data are provided for SO<sub>2</sub>, NOx, BC, OC, NH<sub>3</sub>, NMVOC,  CO, CO<sub>2</sub> from 1750 - 2022.
+Emissions data for CH<sub>4</sub> and N<sub>2</sub>O are provided from 1970 - 2022.
+
+When handling this data, some extra care must be taken given that CEDS' testing data is published under multiple source IDs. In addition, solid biofuel emissions and speciated NMVOCs have the suffix "-supplemental" added to their source ID to avoid inadvertent double counting.
+
+- Bulk emissions for all species except NMVOC's and supplementary solid biofuel emissions files are identified by the source ID "CEDS-CMIP-2024-11-25" (or "CEDS-CMIP-2024-11-25-supplemental" for the solid biofuel emissions) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.13952845.svg)](https://doi.org/10.5281/zenodo.13952845)
+- Air emissions for all species, NMVOC bulk emissions, and supplementary speciated VOCs are identified by the source ID "CEDS-CMIP-2024-10-21" (or "CEDS-CMIP-2024-10-21-supplemental" for the speciated VOCs) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.14145000.svg)](https://doi.org/10.5281/zenodo.14145000)
+
+The underlying data releases are documented [here](https://zenodo.org/records/13952845) and [here](https://zenodo.org/records/14145000).
+
+This data is derived from CEDS' v_2024_07_08 aggregate emissions release. Aggregate data by country and sector for this release is also available in units of kilo-tonne (kt) per year and can be found [here](https://zenodo.org/records/12803197). Note that country totals in these summary files do not include international shipping or aircraft emissions, which are reported under the "global" iso. 
+
+Full details on the dataset and all relevant links can be found on the [CEDS GitHub page](https://github.com/JGCRI/CEDS).
+
+<!--- begin-cmip7-phases-source-ids -->
+<!--- Do not edit this section, it is automatically updated when the docs are built -->
+### Source IDs for CMIP7 phases
+
+The source ID that identifies the dataset to use in the different phases of CMIP7 is given below.
+
+#### Testing
+
+For the testing of CMIP7, you will need data from the following source IDs:
+
+- [CEDS-CMIP-2024-10-21](https://aims2.llnl.gov/search?project=input4MIPs&versionType=all&&activeFacets=%7B%22source_id%22%3A%22CEDS-CMIP-2024-10-21%22%7D)
+- [CEDS-CMIP-2024-11-25](https://aims2.llnl.gov/search?project=input4MIPs&versionType=all&&activeFacets=%7B%22source_id%22%3A%22CEDS-CMIP-2024-11-25%22%7D).
+
+Retrieving and only using valid data will require some care.
+Please make sure you read the guidance given at the start of this Summary section
+and process the data carefully.
+
+This data is for testing (both of the forcing data and of modelling workflows) only.
+Production simulations should not be started based on any data that has a `mip_era` value equal to 'CMIP6Plus'.
+(The `mip_era` metadata value appears both in each file's global attributes as well as its metadata on ESGF.)
+
+If you have any feedback, please add it to the [relevant GitHub discussion](https://github.com/PCMDI/input4MIPs_CVs/discussions).
+
+#### CMIP7 AR7 fast track
+
+No data available for this phase yet.
+
+This data will be for the CMIP7 AR7 fast track.
+All data sets for use in the fast track will be published with a `mip_era` metadata value of 'CMIP7'.
+This metadata value will appear both in the file's global metadata as well as its metadata on ESGF.
+
+Further details will follow in early 2025.
+
+#### CMIP7
+
+No data available for this phase yet.
+
+This data will be for CMIP7.
+All data sets for use in CMIP7 will be published with a `mip_era` metadata value of 'CMIP7'.
+This metadata value will appear both in the file's global metadata as well as its metadata on ESGF.
+
+Further details will follow after the fast track is underway
+(including details about how updates to this data will be handled over the lifetime of CMIP7).
+
+<!--- end-cmip7-phases-source-ids -->
+
+## Navigating the data
+
+### Recommendation for pre-industrial control
+
+Repeat the 1850 values.
+
+### Grids and frequencies provided
+
+CEDS emissions are provided at monthly resolution, on a 0.5 degree grid, with 50-years per data file. (A 0.1° grid for recent decades is also available.) Emissions are relatively smooth over the early portion of this time period, but annual data is supplied for consistency across the dataset. The files are in netcdf v4 (HDFv5) format with CF-compliant and ESGF-compliant metadata.
+
+
+Gridded aircraft emissions are also supplied in a separate file with 25 vertical layers (using the CMIP5 historical emissions Lamarque et al. 2010, as drawn from Lee et al., as a template). Note that aircraft emissions are zero in early years, but files are provided for all years consistency.
+
+The gridded emissions incorporate a monthly seasonal cycle by sector drawing largely from the [ECLIPSE project](https://iiasa.ac.at/models-tools-data/global-emission-fields-of-air-pollutants-and-ghgs), [Carbon Tracker](https://carbontracker.org/), and [EDGAR](https://edgar.jrc.ec.europa.eu/).
+
+VOC speciation is provided at the 23 species resolution from [EDGAR](https://edgar.jrc.ec.europa.eu/). 
+
+### Variables provided
+
+Subsequent CEDS data releases since August 2016 are in a format of one variable per data file, with the sectors included as a dimension of the variable's data. 
+
+
+The sectors in the netCDF files (other than aviation) are:
+
+Sector	Description
+
+- 0: AGR	Non-combustion agricultural sector
+- 1: ENE	Energy transformation and extraction
+- 2: IND	Industrial combustion and processes
+- 3: TRA	Surface Transportation (Road, Rail, Other)
+- 4: RCO	Residential, commercial, and other
+- 5: SLV	Solvents
+- 6: WST	Waste disposal and handling
+- 7: SHP	International shipping (including VOCs from oil tanker loading/leakage)
+
+Within the netCDF files the sector ids are:
+sector:ids = "0: Agriculture; 1: Energy; 2: Industrial; 3: Transportation; 4: Residential, Commercial, Other; 5: Solvents production and application; 6: Waste; 7: International Shipping" ;
+
+### Supplementary Data
+
+For use in setting aerosol size distribution and additional speciation (if desired), an auxiliary dataset emissions providing emissions from solid biomass combustion is also provided. Note that these are a subset of emissions in the main files. These data, therefore, should NOT be added to the emissions in the main files. (Note that no data files for CO2 emissions from solid biomass are released, as CO2 emissions from CEDS are from fossil fuels only.)
+
+Supplementary "checksum" .csv text files that provide total global mass for each sector, month, and year are also available as well as global seasonal diagnostic plots can be found [here](https://zenodo.org/records/14145000).
+
+### Gridding Methodology
+
+Emissions were first estimated at the level of country, sector, and fuel. Emissions by sector were then mapped to spatial grids by country and sector (several intermediate gridded sectors were combined to form the final release sectors for CMIP6Plus). Grid cells that contain more than one country can have portions of emissions from each country. 
+
+For recent decades, emissions were mapped to the grid level largely using the distribution of emissions from EDGAR within each country and gridding sector (usually using year-specific EDGAR grids from 1970 forward). For some sectors, the emissions distribution varies over time, while for other sectors it was held constant. For most emission species, residential combustion is the dominant source by 1850, so emissions from the RCO sector were distributed using HYDE population distributions by 1900 (with blended spatial distributions between 1900 and 1970). For other sectors the emissions distribution within each country was held fixed before 1970. 
+
+Because of the simplifying assumptions, emissions distributions, particularly in earlier years, should not be taken literally. Overall, however, anthropogenic emissions become small relative to either natural sources or mid-to-late 20th century emissions so we anticipate that these assumptions are not likely to have major impacts on global or regional modeling results.
+
+In this release, large SO2 point sources, along with any co-emitted species, are explicitly represented - largely through use of a SO2 point source catalog developed by [Fioletov et al 2023](https://doi.org/10.5194/essd-15-75-2023). Remaining emissions for any country/sector are distributed using EDGAR or other proxies as described above (after removing any point sources now explicitly represented)>
+
+More details on the use of point sources in gridding methodology can be found [here](https://zenodo.org/records/6949566/files/CEDS_Point_Source_Documentation.pdf).
+
+For more details on the gridding methodology see:
+Feng, L., Smith, S. J., Braun, C., Crippa, M., Gidden, M. J., Hoesly, R., Klimont, Z., van Marle, M., van den Berg, M., and van der Werf, G. R.: The generation of gridded emissions data for CMIP6, Geosci. Model Dev., 13, 461–482, https://doi.org/10.5194/gmd-13-461-2020, 2020.
+
+For more details on the underlying emissions data see:
+Hoesly, R. M., Smith, S. J., Feng, L., Klimont, Z., Janssens-Maenhout, G., Pitkanen, T., Seibert, J. J., Vu, L., Andres, R. J., Bolt, R. M., Bond, T. C., Dawidowski, L., Kholod, N., Kurokawa, J.-I., Li, M., Liu, L., Lu, Z., Moura, M. C. P., O'Rourke, P. R., and Zhang, Q. (2018) Historical (1750–2014) anthropogenic emissions of reactive gases and aerosols from the Community Emissions Data System (CEDS), Geosci. Model Dev., 11, 369-408. doi: 10.5194/gmd-11-369-2018. 
+
+
+### Uncertainty
+
+At present, uncertainties are not quantified. 
+Uncertainties in recent years (most recent 2-3 years) are higher due to delays in reporting data and common revision of data point in recent years (as documented [here](https://iopscience.iop.org/article/10.1088/1748-9326/aaebc3)). Uncertainties farther back in time are also higher, especially the spatial distribution. However, the importance of anthropogenic emissions compared to natural sources also become less significant in these early years. In between (roughly between 1970 and 5 years before now)
+the uncertainties can be smaller.
+
+### Examples of working with the data
+
+See the [CEDS GitHub page](https://github.com/JGCRI/CEDS).
+The [emission harmonization team's notebooks](https://github.com/iiasa/emissions_harmonization_historical/)
+may also be of interest.
+
+### Differences from CMIP6 or other previous versions
+
+Comparison figures showing CMIP6 vs CMIP6Plus data sets by aggregate region and sector can be found [here](https://github.com/JGCRI/CEDS/blob/master/documentation/Version_comparison_figures_v_2024_07_08_vs_2016_07_16(CMIP6).pdf).
+
+### File formats and naming
+
+The file formats are identical to CMIP6.
+
+#### Emissions Data file name format
+
+Bulk Gridded emissions: [em_species]-em-anthro_input4MIPs_emissions_CMIP_CEDS-2024-10-21_gn_YYYY01-ZZZZ12.nc
+(where YYYY is the starting year contained in this file, and ZZZZ is the ending year)
+netCDF variable name: [em_species]_em_anthro
+
+Gridded aircraft emissions: [em_species]-em-AIR-anthro_input4MIPs_emissions_CMIP_[source_id]_gn_YYYY01-ZZZZ12.nc
+
+netCDF variable name: [em_species]_em_AIR_anthro
+
+#### Supplemental emissions Data file name format
+
+Gridded biomass emissions: [em_species]-em-SOLID-BIOFUEL-anthro_input4MIPs_emissions_CMIP_[source_id]_gn_YYYY01-ZZZZ12.nc
+
+netCDF variable name: [em_species]_em_SOLID_BIOFUEL_anthro
+
+VOC speciation grids: VOC01-alcohols-em-speciated-VOC-anthro_input4MIPs_emissions_CMIP_[source_id]_gn_YYYY01-ZZZZ12.nc
+
+netCDF variable name: VOC01_alcohols_em_speciated_VOC_anthro
+(There is a separate README file with further information on VOC speciation -- see the CEDS project web site. Note there is a variable naming inconsistency for these file - described in the VOC README)
+
+
+<!--- begin-revision-history -->
+<!--- Do not edit this section, it is automatically updated when the docs are built -->
+<!--- No revisions, hence section is blank -->
+<!--- end-revision-history -->