This is a publicly available, statistical-dynamical tropical cyclone downscaling model, and a derivative of the MIT tropical cyclone downscaling model. It is composed of three primary components: (1) a random seeding process that determines genesis, (2) an intensity-dependent beta-advection model that determines the track, and (3) a non-linear differential equation set that determines the intensification rate. The model is entirely forced by the large-scale environment. Downscaling ERA5 reanalysis data shows that the model is generally able to reproduce observed tropical cyclone climatology, such as the global seasonal cycle, genesis locations, track density, and lifetime maximum intensity distributions. Inter-annual variability in tropical cyclone count and power-dissipation is also well captured, on both basin-wide and global scales. The model is also able to reasonably capture the observed return period curves of landfall intensity in various sub-basins around the globe. The incorporation of an intensity-dependent steering flow is shown to lead to regionally dependent changes in power dissipation and return periods.
Citation: Lin et al. (2023) (accepted to JAMES)
If you know what you are doing and familiar with Python packages, here is a quick start command list to get the model running.
conda env create -f environment.yml
conda activate tc_risk
pip install cdsapi
[generate .cdsapirc file in home directory]
python3 scripts/download_era5.py
python3 run.py GL
We strongly recommend creating a virtual environment to install the packages required to run this model. A very popular virtual environment/package manager is Anaconda. We have provided the YAML file that worked in our testing of the model.
conda env create -f environment.yml
This requires conda to be installed, and should create a virtual environment with the name tc_risk. See here for more details.
If you prefer to do a clean install of the required packages, the following commands will create a virtual environment:
conda create -n tc_risk basemap cftime xarray numpy matplotlib cartopy python jupyter scipy netCDF4 dask
pip install global-land-mask cdsapi
Note, not all Python packages are fully supported on Apple Silicon architecture yet.
The namelist file contains various parameters used in the model. It is useful for tuning the model, as well as adding a variety model data sources. The namelist file contains self-explanatory descriptions for most of the variables, but we will add some detail here.
| Variable Name | Description |
|---|---|
| base_directory | master directory that all input data are located |
| output_directory | master directory to save all output data |
| exp_name | name of the experiment; output will be saved in this folder |
| dataset_type | key used in var_keys for variable mapping (see Formatting Input) |
| output_interval_s | output interval of tropical cyclone tracks |
| tracks_per_year | total number of tracks to simulate each year |
| PI_reduc | reduction factor for potential intensity ( |
| p_midlevel | pressure (Pa) of which to calculate mid-level saturation entropy deficit |
| select_thermo | 1 or 2 for pseudoadiabatic and reversible thermodynamics, respectively |
| select_interp | leave it at 2 |
The manuscript uses ERA5 reanalysis data to compare model output to observations. While the user is free to use their own input data (according to the format described in the next section), we have provided a script that downloads and organizes ERA5 reanalysis data into a digestible format for the downscaling model, but it requires cdsapi. Here are detailed instructions on how to install cdsapi on your machine. In short, you will need to create your own account and the cdsapirc key file in your home directory, then install the client via:
pip install cdsapi
After this, run the script download_era5.py from the home directory. It will download data to the directory specified in namelist.base_directory.
Unfortunately, we have not tested the model on the reanalysis datasets of other modeling centers.
While the original manuscript does not make any climate projections with the downscaling model, we provide an example script, download_cmip6.py, to download and organize CMIP6 model. There is no additional account creation necessary.
The input data needs to be formatted in relatively loose way. For a variable VAR In the directory namelist.base_directory, it finds all files that match *namelist.exp_prefix*VAR*.nc. The files can be in organized sub-directories (such as sub-directories by year of data), or any other way that is easy for the user. The variables in the netCDF files should contain timestamps that makes them amenable to multifile dataset reading in xarray. Typically, there is nothing extra that needs to be done when downloading ERA5 reanalysis or CMIP6 climate model output.
Every modeling center, however, has different naming conventions for variables. The variable namelist.var_keys is a Python dictionary that allows the user to specify the standard variable name (dictionary key) and how it is represented in the dataset (dictionary value). The standard variable names used in the model are:
| Variable Name | Description |
|---|---|
| sst | sea surface temperature (monthly-averaged) |
| mslp | mean sea level pressure (monthly-averaged) |
| temp | temperature (monthly-averaged) |
| sp_hum | specific humidity (monthly-averaged) |
| u | zonal wind (daily) |
| v | meridional wind (daily) |
| lvl | pressure vertical level |
| lon | longitude |
| lat | latitude |
For instance, the specific humidity is named 'q' in the ERA5 datasets, so we set the key-value pair 'sp_hum' and 'q' in the 'ERA5' (which is specified by namelist.dataset_type) entry in namelist.var_keys.
Note, when using CMIP6 model data, some GCMs use non-rectangular horizontal coordinates. The interpolation code expects rectangular grids, so you will need to regrid the NetCDF files into rectanguular coordinate. The cdo library is convenient for this. In addition, some vertical grids are output in sigma coordinates. You will need the vertical grid in pressure coordinates.
We have provided a simple script, run.py, to run the model.
conda activate tc_risk
python3 run.py GL
where the first argument is the basin with which to downscale tracks. The first time the model is run, land masks will be generated in the source directory. This script will run the downscaling model and save pre-processed large-scale fields (potential intensity, environmental winds, thermodynamic fields) to the file directory namelist.output_directory/, and the downscaled tropical cyclone tracks to namelist.output_directory/namelist.exp_name/.
The tropical cyclone tracks will be output in a netCDF file. These netCDF files can be read using xarray, and are compatible with multifile dataset reads.
| Variable Name | Description |
|---|---|
| lon_trks | longitude of tropical cyclone track (°E) |
| lat_trks | latitude of tropical cyclone track |
| u250_trks | 250-hPa environmental zonal wind (m/s) |
| v250_trks | 250-hPa environmental meridional wind (m/s) |
| u850_trks | 850-hPa environmental zonal wind (m/s) |
| v850_trks | 850-hPa environmental meridional wind (m/s) |
| v_trks | maximum azimuthal wind (m/s) |
| m_trks | non-dimensional inner core moisture |
| vmax_trks | maximum wind, or intensity (m/s) |
| tc_basins | basin of tropical cyclone occurrence |
| tc_month | month of tropical cyclone occurrence |
| tc_years | year of tropical cyclone occurrence |
| seeds_per_month | number of random seeds placed |
| time | time since track genesis (seconds) |
The model also includes a new, CAPE-based method to calculate potential intensity. The thermo.py is a file that only depends on the constants.py file, and contains the functions to calculate potential intensity. The function, CAPE_PI is written in a transparent and straightforward way. There is also a vectorized method that is fast to use, but less readable than the non-vectorized code, CAPE_PI_vectorized.
Below is a comparison of the 24h-hour intensity change distribution from the downscaling model in the North Atlantic basin, as compared to observations. Only open-ocean tropical cyclones with intensities of at-least 35 knots were considered.
Jonathan Lin
Raphael Rousseau-Rizzi
Version 1.1 (2024-05-14) - see release notes
Version 1.0 (2023-02-17) - model released
The MIT License (MIT)
Copyright (c) 2023 Jonathan Lin
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.