Introduction

This is a tutorial on how to install and run the Hector simple climate model.

The code written in this tutorial partially follows the tutorials on the GCIMS YouTube page for installing Hector in R and completing a basic Hector run.

Installing RTools

In order to compile Hector from source code, you will need to ensure that you have RTools installed and functioning.

Guidance for installing RTools and ensuring that it is on PATH is also available on the Installing Hector in R video, beginning at 1:03.

Intsalling Hector

Once you have the correct version of RTools installed working on you computer, you are now ready to install Hector.

Hector is an open-source package hosted on the JGCRI GitHub page. Therefore, the remotes package so we can install Hector directly from GitHub.

First, install remotes if you do not yet have it installed. Once installed you can load the library:

# Install remotes 
install.packages("remotes")
# Load remotes
library(remotes)

Once loaded, you can use the install_github() function to locate and install Hector from GitHub:

# Install Hector from GitHub
install_github("JGCRI/hector")

Note that you must supply the username of the account the repository is stored (for Hector, this is the JGCRI account). Bu default, this will download the main branch of the repository, but you can download other branches using the @[name of branch] after hector.

It will take a minute for the package build to be completed. Once finished you will see DONE (hector) in the console.

Load the Hector library, and you are good to go:

# Load Hector 
library(hector)

Congrats! You just installed Hector!

Basic Hector Run

Here we will walk through a basic Hector run to show how you run the model, query/fetch results, and produce a basic plot.

First, ensure the libraries you need are loaded. In this example, we will only need hector and ggplot2:

# Load libraries
library(hector)
library(ggplot2)

Indentify a climate scenario and load .ini file

In order to run Hector, we will need to use a climate scenario. Because Hector works by simulating how the Earth system responds after being prescribed, we have to pass a climate scenario to Hector before we can run the model. The climate scenarios provide Hector with information about fossil-fuel emissions, emissions from land use change, and atmospheric concentrations of non-CO2 GHGs among other important future climate pathway information.

It is possible to use your own emissions pathway to run Hector, but the package contains commonly referenced climate scenarios for use.

You can check all the climate scenarios available in the package using this line of code:

list.files(system.file("input", package = "hector"))
##  [1] "hector_picontrol.ini"   "hector_ssp119.ini"      "hector_ssp126.ini"     
##  [4] "hector_ssp245.ini"      "hector_ssp370.ini"      "hector_ssp434.ini"     
##  [7] "hector_ssp460.ini"      "hector_ssp534-over.ini" "hector_ssp585.ini"     
## [10] "tables"

This tells R to locate on the folder input inside the installed hector package and list all the files in that folder.

We will use the SSP 2-4.5 climate scenario for this tutorial. To use this climate scenario we will save the path to that .ini file as an object in our R env:

# importing scenario config file
ini_ssp245 <- system.file("input/hector_ssp245.ini", package = "hector")
ini_ssp245
## [1] "/Users/jkbrown/Library/R/arm64/4.5/library/hector/input/hector_ssp245.ini"

Running Hector

We can now use this climate scenario to run Hector.

To run the model we will first need to make a Hector core. The function newcore() reads the climate scenario configuration file and creates a model instance that contains the scenario inputs, model components, parameter values, current year and internal state, and will contain the results after the model is run.

# Initialize new hector core
hcore <- newcore(ini_ssp245, name = "ssp245")

By printing hcore we can see the model has been initialized.

hcore
## Hector core: ssp245
## Start date:  1745
## End date:    2300
## Current date:    1745
## Input file:  /Users/jkbrown/Library/R/arm64/4.5/library/hector/input/hector_ssp245.ini

You should notice the start and end date, these are the years for which Hector will run. You should also notice the Current date is matching the Start date, indicating that we have not run the model yet.

Once the model instance is created we can run the model using the run() function. At a minimum we must supply the function with our core:

# Run hector for ssp245
run(core = hcore)
## Hector core: ssp245
## Start date:  1745
## End date:    2300
## Current date:    2300
## Input file:  /Users/jkbrown/Library/R/arm64/4.5/library/hector/input/hector_ssp245.ini

Don’t blink or you will miss it!

The Hector run will take roughly 1/10th of a second to run, which speaks to the utility of simple climate models like this one. They are computationally cheap to run. You should notice now that Current date matches End date indicating we ran the model to completion.

Query Results

As previously mentioned the results of the model are stored in our core, so we have to produce a query to fetch the results we are interested in.

We do this using a function called fetchvars() - for fetch variables. You can explore the different variables we can extract from the Hector result, there are many. In this example we will fetch global mean surface temperature anomaly (GMST()) for the years 1850-2100. You will also need to supply the core from which to fetch the data from.

# dates we want to fetch
dates1 <- 1850:2100

# variables we want to fetch
vars1 <- GMST()

# fetch data
data <- fetchvars(core = hcore, dates = dates1, vars = vars1)

If we take a look at the data, we can see the fields that are provided for each time step:

head(data)
##   scenario year variable      value units
## 1   ssp245 1850     gmst 0.03814024  degC
## 2   ssp245 1851     gmst 0.04919186  degC
## 3   ssp245 1852     gmst 0.05875537  degC
## 4   ssp245 1853     gmst 0.05263445  degC
## 5   ssp245 1854     gmst 0.04398821  degC
## 6   ssp245 1855     gmst 0.05052055  degC

Plotting data

Once we have fetched data from the model run we can plot results using ggplot2.

ggplot(data = data) +
  geom_line(aes(x = year, y = value, color = scenario)) +
  labs (title = "GMST from 1850-2100", 
        y = "deg C")

Challenge

Now that you have complete the step-wise process of running Hector, try completing the following:

  1. Run Hector using the SSP 3-7.0 climate scenario.

  2. Fetch data for both GMST() and CONCENTRATIONS_CO2 for the years 1970-2050.

    HINT: use c() to combine multiple variables into a vector.

  3. Plot the CO2 and gmst results in a two-panel figure.

  • HINT: use facet-wrap() by variable (~variable), and ensure you adjust the y-axis freely using scales = "free_y".