jsmetrics: Jet-stream metrics and algorithms

preprint now available here: https://egusphere.copernicus.org/preprints/2023/egusphere-2023-661/

This is jsmetrics, a package containing implementations of various metrics and algorithms for identifying or characterising jet-streams written in Python and built from xarray.

The philosophy of this package was to keep the methodology of each metric as close as possible to the given research paper's description of it (if not exact), but to not limit the method to a given:

time period,

time unit (i.e. day, month, DJF),

latitude/longitude resolution,

region (where possible),

pressure level height.

All can be handled user-side.

Installation

pip install jsmetrics

Let me know if you have any problems installing this package, as I have not extensively tested for Mac-OS and Windows versions.

Documentation

The official documentation is at https://jsmetrics.readthedocs.io/en/latest/

My email is: thomas.keel.18@ucl.ac.uk

Usage

import xarray as xr
import jsmetrics

# load windspeed data with u- and v- component wind.
uv_data = xr.open_dataset(filename)

# run Woollings et al. 2010 metric
w10 = jsmetrics.jet_statistics.woollings_et_al_2010(uv_data)

print(w10['jet_lat'])
print(w10['jet_speed'])

# run Kuang et al. 2014 metric. NOTE: may take a long time after you have more than 50 time steps.
k14 = jsmetrics.jet_core_algorithms.kuang_et_al_2014(uv_data)
print(k14['jet_center'].sel(time=0))

Gallery

Estimation of North Pacific mean jet latitude by month with 1-stdev errorbars. Data is monthly ERA5 700-850 hPa u-wind between 1980-2020.

Comparison of jet core algorithms estimation of the 6-hourly jet position. Data is 6-hourly ERA5 100-500 hPa u-v-wind.

By latitude estimation of the jet latitude of the subtropical and polar jet stream. Data is monthly ERA5 differenced-250 hPa (orange) and 700-850 hPa (blue) u-wind between 1980-2020.

DISCLAIMER

We have tried to replicate the various metrics based on the equations and details in the methodology as accurately as possible. However, in some cases, we have chosen to exclude or alter parts of the methodology which reduce the resolution of the output (i.e. grouping into season or region) with the hope to preserve the parts of the method that specifically isolate a characteristics of the jet-stream at any inputted scale. Again, any further subsetting is passed onto the user. If data input is at a daily resolution, part of the output should also be daily resolution.

Also note that, the data we used to test these metrics may have a different resolution to the one it was developed with.

Finally, although these metric were found with a literature search, this is not an exaustive list of all methods used to identify or characterise the jet-stream or upper-level wind. This project is very much a work in progress, so contributors are very welcome.

You can find details of each metric or algorithm here: all metrics.

Where you can find my working-out (coming soon): - I am hoping to make available all of my working out in jupyter-notebooks available soon (warning: these notebooks are not formatted) - I am also currently creating a verification notebook.

Metrics & Algorithms

See all metrics for specifications of each 'Complete' or 'In progress' metric and algorithm. For progress on their completion see Status.

Metric/Algorithm	Status	Metric/Algorithm	Status
Gallego et al. 2005	To start	Strong & Davis 2005	To start
Koch et al. 2006	To verify	Archer & Caldiera 2008	To verify
Schiemann et al. 2009	To verify	Woollings et al. 2010	Complete
Manney et al. 2011	In progess*	Allen et al. 2012	To start
Barnes & Polvani 2013	To verify	Pena-Ortiz et al. 2013	To verify
Screen & Simmonds 2013	In progress*	Kuang et al. 2014	To verify
Barnes & Polvani 2015	To verify	Francis & Vavrus 2015	Complete
Cattiaux et al. 2016	To verify	Barnes & Simpson 2017	Complete
Chenoli et al. 2017	In progress	Grise & Polvani 2017	Complete
Molnos et al. 2017	In progress*	Adam et al. 2018	To start
Bracegirdle et al. 2018	Complete	Ceppi et al. 2018	To verify
Kern et al. 2018	To start*	Rikus 2018	In progress
Kern & Westermann 2019	To start	Kerr et al. 2020	To verify
Maher et al. 2020	To start	Winters et al. 2020	To start
Martin 2021	To start*	Bosiger et al. 2022	To start
Local Wave Activity	In progress*

== help needed

Contributing

jsmetrics is in active development.

If you're interested in participating in the development of jsmetrics by suggesting new features, new metrics or algorithms or report bugs, please leave us a message on the issue tracker
If you would like to contribute code or documentation (which is greatly appreciated!), check out the Contributing Guidelines before you begin!

Project To-Do's

WRITE a 'I would like to calculate... Table with which statistics you can get from which metrics, latitude, speed, width etc.'

FINISH verification notebook.

LOOK INTO timing/benchmarking the metrics (maybe in seperate github repo)

TO SOLVE: dealing with data from different sources (some sort of data translator module or maybe included in tests)

for example what if 'v' or 'v-wind' is passed to func instead of 'va' (answer: cf-xarray)

for example what if 'mbar' or 'model levels' instead of 'plev' (answer: pint)

TO SOLVE: subsetting longitude if it wraps around 0-360

ADD: cf_xarray (see: https://cf-xarray.readthedocs.io/en/latest/index.html)

ADD: pint (see: https://pint.readthedocs.io/en/stable/)

ADD: var names to details_for_all_metrics

Credits

The layout and content of this project and was inspired by xclim (https://github.com/Ouranosinc/xclim) which contains other climate indices and metrics.

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.

mukeshraeee/jsmetrics