/ar_avalanche

Atmospheric rivers and avalanches project

Primary LanguageJupyter Notebook

Atmospheric Rivers and Avalanches

Background

This codebase will download ERA5 6 hourly pressure level data in the vicinity of Alaska and apply an atmospheric river (AR) detection algorithm. Outputs include a multiple attributed shapefiles for future work correlating avalanche events (or other phenomena) to ARs.

The AR detection algorithm used here is adapted from Guan & Waliser (2015) and uses a combination of vertically integrated water vapor transport (IVT), geometric shape, and directional criteria to define ARs. See the annotated bibilography document for more detail and other references. Users of this codebase should know the following information about AR criteria:

All of the AR criteria proposed by Guan and Waliser (2015) either judge the geometry of the candidate AR object and/or measure some parameter of integrated water vapor transport (magnitude, direction, and poleward component). Each candidate AR object represents a specific time (six hour resolution) slice of the IVT data where contiguous groups of grid cells in which the magntiude the target quantile are labeled with unqiue integers >=1. The 0 value is reserved to mask the region that did not exceed the IVT quantile threshold.

The five critera are:

Length

Objects longer than 2000 km are retained as AR candidates.

Length/Width Ratio

The ratio of the major to minor axes of the ellipse fit to the AR object shape. Objects with length/width ratio greater than 2 are retained as AR candidates.

Coherence in IVT Direction

If more than half of the grid cells have IVT deviating more than 45° from the object's mean IVT, the object is discarded. This is aimed to filter out objects which do not exhibit a coherent IVT direction and to make a calculation of mean/characteristic IVT direction physically meaningful.

Object Mean Meridional IVT

Considering the notion that ARs transport moisture from low to high latitudes, an object is discarded if the mean IVT does not have an appreciable poleward component (>50 kg m−1 s−1).

Consistency Between Object Mean IVT Direction and Overall Orientation

The overall orientation of the object (i.e., the direction of the shape elongation) is the geographic azimuth along the major axis of an ellipse drawn around the object. An object is discarded if the direction of mean IVT deviates from the overall orientation by more than 45°. This is aimed to filter objects where the IVT does not transport in the direction of object elongation.

Structure

  • All download specifications and model parameters are defined in config.py.
  • The download.py script will download the necessary ERA5 input data.
  • The compute_ivt.py script will transform the downloaded ERA5 input data into a datacube with the additional variables of IVT magnitude, direction, and an IVT quantile value.
  • The ar_detection.py module contains a collection of AR detection functions that will filter AR candidates based on the criteria and create shapefile outputs of objects classified as ARs. These functions may be orchestrated from a notebook (see AR_detection.ipynb) or ran as a script.

Usage

  1. Register for a Climate Data Store (CDS) account and install the CDS API client according to the instructions here. Be sure to accept the user agreement.
  2. Create a new conda environment using the environment.yml file in this codebase, or install packages manually from the list below. (If you run into problems building the environment using conda, or experience errors when running ar_detection.py, we recommend trying mamba to build your environment before attempting to debug any code.)
  3. Set a local environment variable defining the data directory (e.g. export AR_DATA_DIR=path/to/store/ar/data).
  4. Review parameters in config.py and adjust if desired. Note that there is a download request limit of 120,000 items, so adjusting the timestep or date range may overload the request and break the script.
  5. Execute download.py
  6. Execute compute_ivt.py
  7. Execute ar_detection.py or use AR_detection.ipynb to orchestrate the detection.
  8. Examine the results using the AR_QC.ipynb notebook.
  9. Explore spatiotemporal relationships between avalanches and AR events using the AR_avalanche_exploration.ipynb notebook.

Packages

  • rasterio
  • rioxarray
  • xarray
  • pyproj
  • geopandas
  • pandas
  • tqdm
  • scipy
  • haversine
  • shapely
  • cdsapi
  • matplotlib
  • seaborn
  • jupyterlab
  • dask
  • scikit-image

Figures

Figure 1. Subsetting candidate regions before applying AR criteria. Upper left: IVT magnitude of an individual timestep calculated from 6hr ERA5 data. Upper right: 90th percentile of IVT magnitude, calculated across all years in the dataset. Lower left: IVT magnitude after applying a threshold of 90th percentile IVT magnitude. Lower right: Contiguous regions identified and labeled after applying threshold. Each individual region will be evaluated against the AR criteria defined in config.py.

AR thresholding figure

Figure 2. Flowchart of AR detection processing.

FLowchart figure