Why jsmetrics?

The planet’s jet streams are complex and not well defined at any one scale (see what are jet streams), and as such there are a wide range of metrics, algorithms and statistics which have been employed in research to help identify and characterise them. However, it has been generally quite difficult to reconcile various types of information provided by different techniques. The motivation for this package was thus to standardise the most common methods developed for the identification and characterisation of jet streams, so that various techniques are immediately available for anyone wishing to look at jet streams in data. Also, it is hoped that jsmetrics provides a foundation for new metrics and for researchers to be able to quantitatively compare differences provided by existing techniques.

For more information about the standardisation process of the metrics into Python, see the philosophy of jsmetrics.

For a quick overview for the sort of things jsmetrics will help you do, see our quick start section below.

Quick start

I would like to…


Read in wind-speed data from NetCDF (.nc) or GRIB (.grib) format

Python’s xarray library can read in climate data in a .nc
or .grib format by default. And all metrics in jsmetrics
have been implementated to work with xarray data types.
Rename data coords so that they are compatible with

jsmetrics e.g. to standarise names (i.e. lat, lon).

Python’s xarray library provide functions to rename data
and we provide some basic examples of renaming your data

Merge u and v components of wind

Python’s xarray library can merge data, but be careful
that the data you are merging has the exact same time, lat
and lon dimensions, otherwise the merge can take a long time.

Know the mean position of the jet stream

The most common method for this would be to calculate the
‘jet latitude’, which are provided by jsmetrics under the
jet statistics group of methods.
Around 9 jet latitude methods are available in this package,
the most commonly used is ‘woollings_et_al_2010’.

Know the average speed of the jet stream

The most common method for this would be to calculate the
‘jet speed’, which are provided by jsmetrics under the
jet statistics group of methods.
Around 8 jet speed methods are available in this package,
the most commonly used is ‘woollings_et_al_2010’.

Make a map of the jet stream

Methods for identifying the coordinates of jets on are provided
by the jet core algorithms group
of methods available in jsmetrics. These methods all produce
masks of the latitude/longitude/level coordinates where a given
algorithm has discovered jet cores. Our reccomendation is to
use ‘koch_et_al_2006’, which provides a weighted windspeed or
‘manney_et_al_2011’ which will seperate different jet cores
within the same region. Be warned that most of the 5 jet core
algorithms available are computationally expensive, so read the
docstring of a given method for information about the run time.

Know the waviness of the jet stream or upper-air flow

Methods for quantifying the waviness of the jet stream are
provided by the waviness metrics
available in jsmetrics. These are fairly quick to run methods
and there are currently only two available in this package.

Please send me an email if you would like some more help the

What are jet streams?

Jet streams are features of the atmospheric circulation that manifest as fast-flowing ribbons of air, usually around 8-12 km above the surface. They are generated and maintained in regions with extreme temperature gradients. These extreme gradients are produced on the Earth by two major processes: (1) disturbances in the zonal mean-flow (known as eddy-driven processes) and (2) conservation of angular momentum at the poleward edge of the Hadley Cell (known as thermally-driven processes).

In general, these processes create two major types of jets at a climatological scale in each Hemisphere (see Figure 1):

  1. the Polar Front Jet (PFJ) – a deep and primarily eddy-driven feature

  2. the Subtropical Jet (STJ) – a shallow and primarily thermally-driven feature

Earth's two major jet streams

Figure 1. Idealised view of the planet’s jet streams

Figure 1 shows a idealised version of the jet streams – clearly seperated and flowing circumglobal west-to-east fashion. As you can imagine, in reality, the location, strength and direction of a given jet stream is not well defined at any scale. They also exhibit fairly strong seasonality (generally moving closer to the Equator in colder months, and closer to the poles in warmer ones). To see what we mean, we reccomend having a play with Earth null school for one view of how jet stream-like features manifest on the planet (i.e. at 250-850 hPa).

The complexity in their structure, and lack of strong definition (they are essential just ‘atmospheric phenomena’) means that a vast range of metrics, statistics and algorithms have been employed to identify and characterise different aspects of them in atmospheric data. With jsmetrics, we have tried to include as many of the most common methods used to characterise jet streams as possible in the hope that this would help researchers reconcile information about them and allow for a more quantitative comparison of their differences and impact on trends and changes shown to the jet streams.

I am still writing this section, so please email me if you have some suggestions or feedback.

The philosophy of jsmetrics

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.

The motivation for this was to allow the user to handle these factors and allow for the comparison of various metrics on the same underlying data.


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.