globsim 4.4.1

Using global reanalysis data for local permafrost simulation

Globsim + DReaMIT

last revision November 2025

Welcome to the DReaMIT_demo branch of Globsim, a tool for automating the downloading, interpolation, and scaling of different reanalyses to produce meteorological time series for user-defined point locations.

The new DReaMIT_demo branch is the result of the integration of the DReaMIT (Dynamical Reanalysis Model for Inversions of Temperature) model into GlobSim. This allows the user to directly produce surface-based inversion (SBI) metrics and air temperature for any point location. Full desciption available in a coming GMD publication, authored by Victor Pozsgay, Nick Noad, Philip Bonnaventure, and Stephan Gruber.

We provide a demonstration folder: globsim/DReaMIT_demo/

The main files for the integration are:

1. core file for the model dreamit.py
2. integration into the GlobSim scaling process for ERA5 and JRA-3Q.

Installation

Start by cloning this branch

git clone --branch DReaMIT_demo --single-branch https://github.com/geocryology/globsim.git

Use a conda environment to handle most dependencies to avoid building ESMF yourself. Navigate to the globsim/DReaMIT_demo/ folder, install the globsim_DReaMIT conda environment from the YAML file, and activate it, before navigating back to the root of the globsim/ folder and installing it:

cd globsim/DReaMIT_demo/
conda env create -f environment.yml
conda activate globsim_DReaMIT
cd ..
python -m pip install -e .
cd DReaMIT_demo/

For the remaining of the demonstration use, users will need to work from the folder globsim/DReaMIT_demo/.

Details for usage (and outdated installation instructions) for Globsim can be found on our ReadTheDocs page.

Credentials for ERA5 and JRA-3Q

All paths in this section are given relative to the root of /globsim/DReaMIT_demo/.

See the Credentials page for details about credentials.

Get personal tokens (credentials) to be able to download ERA5 and JRA-3Q data.

• ERA5:
  1. Create an ECMWF account, complete the form, activate your profile, and go to https://cds-beta.climate.copernicus.eu/how-to-api.
  2. Fill the credential file ./user_input/.cdsapirc with your info.
  3. Install the CDS API client (pip install 'cdsapi>=0.7.0').
  4. Go to: https://cds-beta.climate.copernicus.eu/datasets/reanalysis-era5-pressure-levels?tab=download and scroll down a lot and accept the Licence to use Copernicus Products under the 'Terms of use'
• JRA-3Q:
  1. Create a GDEX account at https://gdex.ucar.edu/
  2. Go to your Profile->API Token, and copy it into ./user_input/rdams_token.txt

Run the Notebook

All paths in this section are given relative to the root of /globsim/DReaMIT_demo/.

Depending on your Jupyter notebook interpreter, you might be prompted to install ipykernel too.

The downloaded DEM data is not included in GitHub due to large file size limits. However, the user should feel free to use the notebook to download the data locally.

The folder provides the reanalysis data, downloaded for a short time window. If the user wishes to download it for a longer time period, or different locations, they should feel free to modify the GlobSim configuration files in the ./user_input/ folder.

The main notebook, DReaMIT_demo.ipynb is an interactive Jupyter notebook. There, you can

1. Download ArcticDEM
2. Compute hypsometry of point locations from DEM data
3. Download, scale, and interpolate reanalysis data at point locations, including DReaMIT model metrics, such as air temperature, top of inversion, lapse rate, etc.
4. Produce plots of the hourly DReaMIT time-series.

Initial structure of the notebook

DReaMIT_demo/
├── DReaMIT_demo.ipynb               # main Jupyter notebook for the demonstration
├── environment.yml                  # file from which to build the conda environment
├── dem_to_hypso/                    # where all the ArcticDEM data will be stored
│   ├── dem_download.py              # python script to download DEM data
│   └── __pycache__
├── reanalysis/                      # where all the reanalysis data will be stored
│   ├── reanalysis.py                # python script to download reanalysis data
│   └── __pycache__
└── user_input/                      # where the user should modify location, period, etc.
    ├── config_globsim_era5.toml     # GlobSim config file for ERA5
    ├── config_globsim_jra3qg.toml   # GlobSim config file for JRA-3Q
    ├── config_globsim_pre_hypso.csv # csv list of stations
    ├── .cdsapirc                    # ECMWF credentials for ERA5
    └── rdams_token.txt              # GDEX credentials for JRA-3Q

Final structure of the notebook

DReaMIT_demo/
├── DReaMIT_demo.ipynb
├── environment.yml
├── dem_to_hypso/
│   ├── dem_download.py
│   ├── config_globsim_with_hypso.csv
│   ├── __pycache__
│   ├── DMP_WS01                              # All the DEM data for station 1: DMP_WS01
|   |   ├── df_grid_DMP_WS01.pkl              # pickled DEM data as a panda dataframe
|   |   ├── arcticdem_clipped.tif
|   |   ├── arcticdem_merged.tif
|   |   └── arcticdem_data/
|   |       └── lots of files and folders
│   └── DMP_WS02                              # All the DEM data for station 2: DMP_WS02
|       ├── df_grid_DMP_WS02.pkl              # pickled DEM data as a panda dataframe
|       ├── arcticdem_clipped.tif
|       ├── arcticdem_merged.tif
|       └── arcticdem_data/
|           └── lots of files and folders
├── reanalysis/
│   ├── reanalysis.py
│   ├── __pycache__
│   ├── era5/
│   │   ├── par/
│   │   │   └── config_globsim_with_hypso.csv # automatically-generated file with 'hypsometry' column
│   │   ├── some .nc files
│   │   ├── era5_to.grib
│   │   ├── grib_files/
│   │   │   └── some .grib files
│   │   ├── interpolated/
│   │   │   └── some .nc files
│   │   └── scaled/
│   │       └── scaled_era5.nc                # final scaled ERA5 netCDF file
│   └── jra3qg/
│       ├── par/
│       │   └── config_globsim_with_hypso.csv # automatically-generated file with 'hypsometry' column
│       ├── some .nc files
│       ├── interpolated/
│       │   └── some .nc files
│       └── scaled/
│           └── scaled_jra3qg.nc              # final scaled JRA-3Q netCDF file
├── user_input/
│   ├── config_globsim_era5.toml
│   ├── config_globsim_jra3qg.toml
│   ├── config_globsim_pre_hypso.csv
│   ├── .cdsapirc
│   └── rdams_token.txt
└── plots/                                    # all the produced plots are found here
    └── some .pdf files

Adapting the code

Change locations

1. Make sure to update the list of stations in ./user_input/config_globsim_pre_hypso.csv
2. Update the area bounding box of the ERA5 and JRA-3Q TOML configuration files (MAKE SURE TO HAVE AT LEAST 1.5 DECIMAL DEGREES IN BOTH LATITUDE AND LATITUDE)

See the Siteslist page for details about sites list.

Change period

Change 'beg' and 'end' fields under [scale], [interpolate], and [scale] sections of both TOML configuration files.

Change kernels

See the Operation page for details about available scaling kernels and associated netCDF variables.

Change model parameters (e.g., for new regional calibration)

The file that contains the calibrated model parameters (alpha, beta) is found at globsim/globsim/data/DReaMIT_params.csv. If you would like to update the parameters with your own, modify this csv file.

Observational data

Observational data used in the study to calibrate and test the model is available in the ./observations/ folder. There, you will find hourly air temperature data for all WS01 and WS02 sites, together with all Dawson sites. Note that data from ECCC/NAVCAN sites is accessible for download with the R-package weathercan (Lazerte, 2018).

Disclaimer

GlobSim is made available for use under the GNU GPL-3 license. We do not guarantee that this software will work with your particular hardware or software. We also make no claim of offering technical support or continued development. However, any issues or bugs should be reported using the github issue tracking tool.

Have fun

Please customise the code and use it for your project. Then let us know how things work. We hope this is useful for you.