Library of algorithms and metrics used to characterise and/or identify jet-streams, based on xarray.
Project description
jsmetrics: Jet-stream metrics and algorithms
preprint now available here: https://egusphere.copernicus.org/preprints/2023/egusphere-2023-661/ example notebooks: https://github.com/Thomasjkeel/jsmetrics-examples
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. Please feel free to email me if you would like some help working with this package.
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.metrics.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.metrics.jet_core_algorithms.kuang_et_al_2014(uv_data)
print(k14['jet_center'].sel(time=0))
Examples
Some example notebooks are available here: https://github.com/Thomasjkeel/jsmetrics-examples
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.
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 |
Metric/Algorithm |
|||
---|---|---|---|---|
To start |
To start |
|||
To verify |
To verify |
|||
To verify |
Complete |
|||
In progess* |
To start |
|||
To verify |
To verify |
|||
In progress* |
To verify |
|||
To verify |
Complete |
|||
To verify |
Complete |
|||
In progress |
Complete |
|||
In progress* |
To start |
|||
Complete |
Complete |
|||
To start* |
In progress |
|||
Complete |
To start |
|||
To verify |
To start |
|||
To start |
To start* |
|||
To start |
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.
History
0.1.6 (2023-XX-XX)
- Overhaul the ReadTheDocs documentation in the package
add examples and notes to each metric in package
0.1.6-alpha (2023-08-19)
Fix Manney et al. 2011 implementation
Correct Manney 2011 method
Move old method to new metric: ‘jet_core_identification_algorithm’
Update docs for Manney 2011 and sub-components
0.1.5-beta (2023-08-16)
Update Schiemann method with new variable name (jet occurence), docstring and changes to sub-component function names
Add ws_threshold parameter to Schiemann
Update methods that work on one time unit of data and add squeeze method to properly deal if time not in dims
Add basic outline of jet core algorithm docstrings
0.1.5-alpha (2023-08-15)
Begin overhaul of ReadTheDocs documentation
Add notes and example to Koch et al. 2006 metric
Rename variable returned by K06 to jet_events_ws
0.1.4 (2023-08-02)
Add new metric to package: Zappa et al. 2018 (This method builds on Ceppi et al. 2018)
Raise KeyError if no time coordinate is passed to a given metrics
0.1.4-alpha (2023-07-21)
add KeyError raise if no time coordinate is passed to various metrics
0.1.3 (2023-07-07)
Add “method=’nearest’” to jet statistics and core algorithms for cases when coords cannot be represented within float precision range.
0.1.2 (2023-06-06)
Fix Barnes & Polvani 2013 to better deal when min max jet lat is at edge data
Add check for NoLeapDatetime
0.1.2-alpha (2023-05-27)
Add check for NoLeapDatetime
0.1.1 (2023-05-26)
Fix Woollings et al. 2010 and filter windows to use day timeunits for window to stop it removing too much data.
Add data util function to add number of days to 360Day Datetime type
0.1.1-beta (2023-04-07)
add parameter for Kerr et al. 2020
Add Ceppi et al jet speed adaptation from Screen et al. 2022
Add fix for sort_xarray_data_coords so it works when only one coord value in coordinate (i.e. so each metric can work when only one longitude)
Supress warning for quadratic func
0.1.1-alpha (2023-03-31)
Add fix for Kuang to run when there is no time dim
Add fix for BP15 to except errors where all nan data
Add warning for BS17 when more than 10 days resolution
0.1.0 (2023-01-22)
MAJOR UPDATE: re-organise the structure of the package into core, metrics and utils
rename jet statistics, waviness metrics and jet core algorithm files
add wrappers to check data is xarray and is sorted in descending order (in core/check_data.py)
move waviness metrics to new file
Update appropriate tests
0.0.19-alpha (2022-12-21)
Update JetStreamOccurenceAndCentreAlgorithm to skip longitude values outside lon range in data
Make changes to work with Shapely version 1.8/2.0. Means changes to Cattiaux et al. 2016
0.0.18 (2022-11-23)
update fitted parabola func for Barnes & Polvani 2015
Add Blackport & Fyfe 2022
update Barnes & Simpson 2017 to drop all NaN slices
update to check for more than one time step for time groupby methods
add test to check all metrics when input is one time step
0.0.17 (2022-11-13)
add try and except for Grise & Polvani 2017 to account for missing vals
0.0.16 (2022-11-09)
skipna=True for calc_latitude_and_speed_where_max_ws
Barnes and Simpson mean over longitude for jet lat
0.0.15 (2022-11-09)
rename max_lat_0.01 to jet_lat for Grise & Polvani 2017
Fix get_3_latitudes_and_speed_around_max_ws to work with isel around lon
Fix barnes polvani parabola to deal with nan values
0.0.14 (2022-11-09)
add plev mean to Bracegirdle
0.0.14-alpha (2022-10-25)
update Pena Ortiz so that it returns monthyear and by day local wind maxima
remove make_empty_local_wind_maxima_data func
Fix CI
Add millibars to get_all_hPa_list
0.0.13 (2022-10-19)
fox workflow for publish to PyPi and TestPyPi
0.0.12 (2022-10-19)
fix kuang to work for southern hemisphere as well
add workflow for publish to PyPi
0.0.12-alpha (2022-10-18)
Update calc_latitude_and_speed_where_max_ws to use numpy methods
Fix Barnes and Simpson 2017 method so it runs on each longitude
0.0.11 (2022-09-15)
Update and fix the JetStreamOccurenceAndCentreAlgorithm method for Kuang
Change LICENSE
Upload to Zenodo
0.0.10 (2022-08-21)
First release to pypi
Clean up rst docs
0.0.9 (2022-08-16)
Finish tests
Remove TODOs
Outline metric_verification notebooks
Improve docs
0.0.8 (2022-07-18)
Format the readme
seperate metrics into metrics and algorithms
Reorder and write better docstrings for the utils files
Update year on LICENSE
0.0.7-beta (2022-06-30)
swap ‘plev’ and ‘lat’ in manney_et_al_2011 method so that it groups cores better
rename ‘sinouisity’ to ‘sinuosity’
0.0.7-alpha (2022-06-10)
update spatial_utils with lazy method for guessing bounds and assuming a regular grid (func is “_standardise_diffs_by_making_all_most_common_diff”)
update Pena-Ortiz method to seperate into subtropical and polar front jet
remove prints from windspeed utils
rename bp13 jet lat
0.0.6 (2022-06-09)
add Barnes & Polvani 2015
add Kerr et al. 2020
add nearest method function to general utils
Speed up Ceppi and fix integration method within (still need to verify)
Add spatial utils for grid cell m2 method
0.0.6-beta (2022-05-31)
Fix ‘get_latitude_and_speed_where_max_ws_at_reduced_resolution’ with check for np.nans
0.0.6-alpha (2022-05-25)
add Barnes & Polvani 2013
Fix ‘get_latitude_and_speed_where_max_ws’ so it can take one value
Fix Barnes & Simpson 2017 and Woollings et al. 2010 and change name of col
Fix Barnes & Polvani neighbouring lats and speed
0.0.5 (2022-05-23)
add Barnes & Simpson 2017
Update ‘get_latitude_and_speed_where_max_ws’ function
Update calc_mass_weighted wind
BIG CHANGES
Change the ‘get_latitude_and_speed_where_max_ws’ function to take abs() max -> will mean that negative u-wind values can be considered the jet lat
0.0.5-beta (2022-05-03)
update Woollings et al. 2010 with seasonal cycle
update metric details dict with ‘plev_units’ argument
fix archer and caldiera call to mass weighted ws (STILL TODO: better plev understanding)
0.0.5-alpha (2022-04-24)
add metric verification notebooks
0.0.4-beta (2022-02-09)
add description, name and DOI to metric details dict
0.0.4-alpha (2022-01-26)
remove Docker
remove get data scripts
0.0.3-gamma (2022-01-14)
remove python 3.6 compatibility
update environment yml (still broken)
0.0.3-beta (2022-01-14)
Use real part from fourier filter to Woollings and its tests
0.0.3-alpha (2022-01-14)
Remove main and experiment related files (moved to another directory so this one is cleaner)
0.0.2 (2022-01-10)
First release on github
0.0.2-beta (2022-01-10)
Add docstrings to all metrics and sub-components
0.0.2-alpha (2022-01-04)
Add docstrings to Archer & Calidera metric
0.0.1 (2022-01-04)
Allow jsmetric to call jetstream_metrics and utils
0.0.1-beta (2021-12-30)
Add currently existing metrics
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for jsmetrics-0.1.6a0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9e939d470c752bb1a928e4ae98c0a4802f80afa60ea56bb890db94ff2507287b |
|
MD5 | ed989f5d7c4fd58c9104b62de6145bad |
|
BLAKE2b-256 | d4cafa39e69ee58af05f9e6986f63ec0138d177857b379acd4959aad698e4c5a |