ARtracks - a Global Atmospheric River Catalogue Based on ERA5 and IPART

Content

• About
• Overview
• Installation
• Getting Original Data
• Creating the ARtracks Atmospheric River Catalogue
• Loading the ARtracks Atmospheric River Catalogue Using Python
• Data Content

About

This repository provides a collection of Python scripts that produces a global, high-resolution catalogue of atmospheric rivers (AR). The catalogue is based on the ERA5 climate reanalysis dataset, specifically the output parameters "vertical integral of east-/northward water vapour flux". Most of the processing relies on IPART (Image-Processing based Atmospheric River Tracking), a Python package for automated AR detection, axis finding and AR tracking.

The catalogue is provided as a pickled pandas.DataFrame, as well as a CSV file.

Note: the quality of the ARtracks catalogue depends on the ERA5 input data, as well as the IPART algorithm. It is therefore strongly recommended to read the respective documentation

• ERA5 Documentation
• IPART paper
• IPART documentation

Download: the ARtracks catalogue, processed for the years 1979-2019, can be downloaded here: https://doi.org/10.5281/zenodo.7018725

Overview

Essentially, this repository provides convenience scripts to produce a global catalogue of atmospheric rivers (ARs) utilizing ERA5 data and the IPART software package. In addition to the functionality IPART provides, we add some pre- and post-processing scripts, as well as one central location to adjust all the parameters that go into creating the AR catalogue.

The first step in creating the AR catalogue is to adjust the parameters and folder settings in config.yml. The original ERA5 data can then be downloaded with 00_download_ERA5_ivt.py. Running 01_regrid_ivt.py will regrid the ivt data from the original 0.25° lat/lon (1-hourly) grid to a 0.75° lat/lon (6-hourly) grid. After aggregating the regridded data (02_aggregate.py), subsequent scripts perform the main functionalities of IPART

• top-hat by reconstruction (THR) computation on input data (03_ipart_ar_tracking_thr_multifile.py)
• Detect ARs from the output of the previous step (04_ipart_ar_tracking_detection.py)
• Identify AR axis (04_ipart_tracking_detection.py)
• Track ARs detected at individual time steps to form tracks (05_ipart_ar_tracking_trace_over_time.py)

Please refer to the documentation of IPART for details.

At this point, all the output of the IPART software package is stored in the output folder set in config.py. Postprocessing of this output is implemented in 06_ar_landfall_continents.py and 07_aggregate.py, resulting in a single file AR catalogue. Postprocessing involves several computations. For each AR detected, we compute the following properties in addition to the output of IPART

• Each sequence of ARs that forms a track is associated with a unique trackid
• The AR area and axis length computed by IPART is discarded, and a more accurate estimation respecting the geographical projection is provided (ar_area and axis_length)
• Each AR is intersected with continental land masses, to compute the proportion of the AR that is located over ocean and land, and over the different continents (Africa, Asia, Australia, North America, Oceania, South America, Antarctica, Europe)
• For each landfalling AR, we provide the location of the landfall (lf_lon, lf_lat) and the respective IVT value (lf_ivt). If an AR hits multiple locations over a continent, which is usually the case, the location with the highest IVT is chosen as the landfalling location. In case an AR hits multiple continents, a priority list of continents can be set in config.py.

A complete description of the variables stored in the ARtracks catalogue is given in Data Content.

Installation

No installation is required.

However, to run the python scripts the following packages are required

• ipart
• netcdf4
• xarray
• matplotlib
• xesmf
• geopandas
• pyproj
• numpy
• pandas
• rioxarray
• cartopy
• shapely
• dask
• antimeridian_splitter

You can use conda to set up an environment and install dependencies via

$ conda create -n AR
$ conda activate AR
$ conda install -c conda-forge ipart netcdf4 xarray matplotlib xesmf geopandas pyproj numpy pandas rioxarray cartopy shapely dask

Additionally, you need to install the antimeridian_splitter-0.1.0.tar.gz provided in this repository

$ pip install antimeridian_splitter-0.1.0.tar.gz

To compute intersections of ARs with continental land masses and landfalling locations (06_ar_landfall_continents.py), you need to download the WORLD_CONTINENTS folder provided in this repository, and place it in the same folder as the Python scripts.

Getting Original Data

To create the ARtracks catalogue, you need to first download the original ERA5 IVT data that it is based on.

You can download the data here: https://confluence.ecmwf.int/display/CKB/How+to+download+ERA5

We provide a script to download the correct data variables and store them the way they need to be stored to work with the other scripts: 00_download_ERA5_ivt.py.

Creating the ARtracks Atmospheric River Catalogue

1. Follow the Installation instructions

2. Download the python scripts and config.yml contained in this repository

3. Set user parameters in config.yml

4. cd into the directory containing the scripts, then run the scripts in the indicated order

• 00_download_ERA5_ivt.py (optional, to download original data)
• 01_regrid_ivt.py for each year in the range given in config.yml
• 02_aggregate.py
• 03_ipart_ar_tracking_thr_multifile.py
• 04_ipart_ar_tracking_detection.py for each year in the range given in config.yml
• 05_ipart_ar_tracking_trace_over_time.py
• 06_ar_landfall_continents.py for each year in the range given in config.yml
• 07_aggregate.py
• 08_convert_ar_to_csv.py

Note: some scripts have positional and/or optional arguments. Use

$ python *script*.py -h

for more information.

Loading the ARtracks Atmospheric River Catalogue Using Python

Using Python Pandas, you can load the pickled DataFrame / CSV file via the following commands

import pandas as pd

# pickled dataframe
ar_pkl = pd.read_pickle('ar.pkl')

# csv table
ar_csv = pd.read_csv('ar.csv', index_col=0)

Data Content

The following table describes the columns of the ARtracks catalogue. Note that the CSV version does not contain the following columns: contour_y, contour_x, axis_y, axis_x, axis_rdp_y and axis_rdp_x.

Name	Description	Unit	Valid Range	Data Type
id	numeric id for the AR at this particular time point	-	>= 0	int64
time	date and time	-	-	datetime64
contour_y	y-coordinates (latitudes) of the AR contour	degrees	[-90, 90]	list of float64
contour_x	x-coordinates (longitude) of the AR contour	degrees	[-180, 180]	list of float64
centroid_y	latitude of the AR centroid, weighted by the IVT value	degrees	[-90, 90]	float64
centroid_x	longitude of the AR centroid, weighted by the IVT value	degrees	[-180, 180]	float64
axis_y	latitudes of the AR axis	degrees	[-90, 90]	list of float64
axis_x	longitude of the AR axis	degrees	[-180, 180]	list of float64
axis_rdp_y	latitude of the simplified AR axis	degrees	[-90, 90]	list of float64
axis_rdp_x	longitude of the simplified AR axis	degrees	[-180, 180]	list of float64
width	effective width as area/length	km	> 0	float64
LW_ratio	length/width ratio	-	> 0	float64
strength	spatially averaged IVT value within the AR region	kg m^-1 s^-1	> 0	float64
strength_ano	spatially averaged anomalous IVT value within the AR region	kg m^-1 s^-1	> 0	float64
strength_std	standard deviation of IVT within the AR region	kg m^-1 s^-1	> 0	float64
max_strength	maximum IVT value within the AR region	kg m^-1 s^-1	> 0	float64
mean_angle	spatially averaged angle between the IVT vector and the AR axis	degrees	[-180, 180]	float64
is_relaxed	True or False, whether the AR is flagged as "relaxed"	-	-	bool
qv_mean	spatially averaged meridional integrated vapor flux	kg m^-1 s^-1	[-inf, inf]	float64
trackid	unique AR track id	-	>= 0	int64
axis_length	length of the AR	km	> 0	float64
ar_area	area of the AR	km^2	> 0	float64
ocean	percentage of area over ocean	-	[0, 100]	float64
land	percentage of area over land	-	[0, 100]	float64
lf_lon	longitude of landfalling location	degrees	[-180, 180]	float64
lf_lat	latitude of landfalling location	degrees	[-90, 90]	float64
lf_ivt	ivt-value of landfalling location	kg m^-1 s^-1	> 0	float64
Africa	percentage of area over Africa	-	[0, 100]	float64
Asia	percentage of area over Asia	-	[0, 100]	float64
Australia	percentage of area over Australia	-	[0, 100]	float64
North America	percentage of area over North America	-	[0, 100]	float64
Oceania	percentage of area over Oceania	-	[0, 100]	float64
South America	percentage of area over South America	-	[0, 100]	float64
Antarctica	percentage of area over Antarctica	-	[0, 100]	float64
Europe	percentage of area over Europe	-	[0, 100]	float64