hector-CEDS

This project can be used to prepare the Hector .ini file and emissions .csv table from the 2025-03-08 CEDS release.

This is project converts the CEDS data into the hector expected inputs, also because CEDS does not include all of the input time series required by hector (halocarbons or the contributions from open burning) additional data must be processed and formatted to set up the complete historical hector input files.

Getting started

1. Clone the Repository Clone a copy of this repository to your local machine.
2. Download Raw Data Files The raw data files are too large to be committed to the Git repository. You can download them from Zenodo by running the following commands in your terminal:

# Assuming starting from the ceds4hector root directory
cd data/raw-data 
sh 1.get-raw-data.sh

3. R

Other than the bash script to download the raw-data files which only has to be done once this wrork flow is written entierly in R using starnard R pacakges and one custom JGCRI pacakge.

I've set up a renv file to help with setup, renv::status() and/or renv::restore() to load the package environment.

But I've found renv to sometimes be finicky, so here are some explicit notes on my R version the JGCRI package used in ceds4hector.

R version 4.3.3 (2024-02-29)
Platform: aarch64-apple-darwin20 (64-bit)
Running under: macOS 26.6.1

I have also saved a copy of my session information (session_info.txt) if helpful.

4. hector

Install the correct version of hector by running the following in R

remotes::install_github("jgcri/hector@v3.5.0"")

This only needs to be run once then library(hector) will be calling the correct hector version.

Work Flow Description

A description the contents of the scripts directory/general workflow, generally speaking L0 are the scripts that format the raw data into the hector appropriate values/variables, L1 aggregates to the global values, L2 generates the input csv and ini file, L3 are the scripts related to the analysis and results for the manuscript.

scripts/	Description
constants.R	Load packages & common helper functions
dev	A collection of random and not well documented scripts that were somewhat helpful during development, may want to delete.
L0.BB4CMIP-emiss.R	Load and convert the global biomass burning emissions for open burning data sets into the correct units, to be aggregated with the anthropogenic CEDS.
L0.CEDS-emiss.R	Load and convert the CEDS data, this is the anthropogenic data for select CEDS species.
L0.hectorV-emiss.R	Format the hector v3.5 emissions, to be used as comparisons.
L0B.cmip6_era_inputs.R	Format the hector V3.5 inputs RCMIP I from the original source, this will be used to complement CEDS inputs.
L1.aggregate_CEDS_emissions.R	Combine the CEDs data with additional data sources in order to get the total global emissions required for hector inputs. The csv file returned here still needs to be formatted.
L2A.global_total_emissions.R	Read in the CEDS L1 emissions and add add in the missing historical inputs (non CEDS speices).
L2B.natural_emiss.R	Calculate natural CH4 and N2O emissions.
L3A.run_hector.R	Run hector with the old and new CEDS input files, generate some figures.
L3B.single_emission_runs.R	Run hector changing a single input time series at time and generate comparison plots.
L3C.portion_of_total.R	Determine the portion of CEDS contribution to changes vs non CEDS.

What is the difference between the data and inputs directory?

The data directory contains the raw-data and the intermediate data products created by this workflow. These csv files are not committed to the git history. The inputs directory is set up to be similar to the the hector/inputs in that it contains the custom hector input ini and csv files generated from the workflow. These materials are committed to git history.

The results folder typically sent to the CEDS team is found at data/L3 which should contain the requested figures and csv files.

Using pre built CEDS emissions in Hector

The Hector inputs generated by this workflow are included in this repository. Most users can use the default ceds4hector/inputs/hector_ceds_historical.ini file after cloning the repository without running scripts/A.run_all.R.

Here’s an example of how to use this .ini created by the scripts/A.run_all.R workflow or included in the repository:

# Load Hector package
library(hector)

# Define the path to the hector_ceds_historical ini file
# Replace PATH/TO with the path to where you installed hector-CEDS on your local machine
ini <- "PATH/TO/hector-CEDS/inputs/hector_ceds_historical.ini"

# Create a new Hector core with the specified ini file
hc <- newcore(ini)

# Run Hector up to the end of CEDS emissions data in 2023
run(hc, runtodate = 2023)

# Use fetchvars to examine Hector results
# For more examples, visit https://github.com/JGCRI/hector