Package: jsmetrics
jsmetrics: Jet-stream metrics and algorithmsjsmetricsis an open-source Python package containing implementations of various statistics and algorithms which have been
developed to identify or characterise jet streams.The package is built usingxarrayand currently contains 17 methods,
consisting of jet statistics, waviness metrics and jet core algorithms (describedhere).
As this is an ongoing project, we are always in the process of finding and implementing new methods.
You can find a full list of methods and their current state in thedocs.preprint now `available <https://egusphere.copernicus.org/preprints/2023/egusphere-2023-661/>`_example `notebooks <https://github.com/Thomasjkeel/jsmetrics-examples>`_InstallationpipinstalljsmetricsLet me know if you have any problems installing this package, as I have not extensively tested for Mac-OS and Windows versions.DocumentationThe official documentation is athttps://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.Jet stream metricsSeeall metricsfor specifications of each ‘Complete’ or ‘In progress’ metric and algorithm. For progress on their completion seeStatus.Statistic/AlgorithmStatusStatistic/AlgorithmStatusGallego et al. 2005To startStrong & Davis 2005To startKoch et al. 2006CompleteArcher & Caldiera 2008CompleteSchiemann et al. 2009CompleteWoollings et al. 2010CompleteManney et al. 2011To verifyAllen et al. 2012To startBarnes & Polvani 2013CompletePena-Ortiz et al. 2013To verifyScreen & Simmonds 2013In progress*Grise & Polvani 2014CompleteKuang et al. 2014To verifyBarnes & Polvani 2015CompleteFrancis & Vavrus 2015CompleteCattiaux et al. 2016To verifyBarnes & Simpson 2017CompleteChenoli et al. 2017In progressBracegirdle et al. 2018CompleteCeppi et al. 2018CompleteRikus 2018In progressZappa et al. 2018CompleteKerr et al. 2020To verifyMaher et al. 2020To startBosiger et al. 2022To startLocal Wave ActivityIn progress*== help neededUsagejsmetricsis designed to be easy to use and should integrate seemlessly with*xarray*.
An extensive knowledge of Python orxarrayisnotrequired to usejsmetrics, although it will help you use the package
more effectively if you wish to run some of the more advanced use cases.Below we introduce a simple use of the package to run a single jet statistic.importxarrayasxrimportjsmetrics# load windspeed data with u- and v- component wind.uv_data=xr.open_dataset(filename)# run Woollings et al. 2010 metricw10=jsmetrics.metrics.jet_statistics.woollings_et_al_2010(uv_data)print(w10['jet_lat'])print(w10['jet_speed'])ExamplesFor examples please check out the examples here:https://jsmetrics.readthedocs.io/en/latest/usage.htmlSome example notebooks are available onGitHubComparison of jet core algorithms estimation of the 6-hourly jet position. Data is 6-hourly ERA5 100-500 hPa u-v-wind.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.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.DISCLAIMERWe 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.Contributingjsmetrics 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 theissue trackerIf you would like to contribute code or documentation (which is greatly appreciated!), check out theContributing Guidelinesbefore you begin!Project To-Do’sADD: cf_xarray (see:https://cf-xarray.readthedocs.io/en/latest/index.html)ADD: pint (see:https://pint.readthedocs.io/en/stable/)CreditsThe 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.History0.2.1 (2023-12-01)Update Manney et al. 2011 method to include ‘check_diagonals’ parameterUpdate Manney et al. 2011 method to select maximum windspeed if no cores found above thresholdAdd ‘slice_array_by_index_breaks’ to data utilsUpdate examples of use and quick start table in docsAdd check for plev units to data_utilsUpdate Archer & Calidera to more properly check for whether data plev coords are Pa or hPa.Fix typos and clarify writing in docs0.2.0 (2023-10-12)Fix CI and Github actionsFinish overhaul the ReadTheDocs documentation in the packageConfirm completed and to verify metricsUpdate Schiemann et al. 2009 method to run faster and introduce u_threshold parameter defaultAdd more complete inline ‘Steps’ to each metric in the package for readability.Remove Screen & Simmonds and Local Wave Activity leftover codeUpdate Manney et al. 2011 further with padding to capture cores near the edge of dataset0.1.7 (2023-10-10)Changes:MAJOR:Rename to Barnes & Polvani 2014 and update tests and all mentions ofUpdate Cattiaux method to deal with Matplotlib depreciation warning about using ‘allsegs’ or ‘collections’ in contour plotAdd tests for new spatial utils method ‘seperate_one_contour_into_line_segments’Add readthedocs.yml0.1.7-beta (2023-10-05)Rename to Barnes & Polvani 2014 and update tests and all mentions of0.1.7-alpha (2023-09-19)Update Cattiaux method to deal with Matplotlib depreciation warning about using ‘allsegs’ or ‘collections’ in contour plotAdd tests for new spatial utils method ‘seperate_one_contour_into_line_segments’0.1.6 (2023-09-14)Overhaul the ReadTheDocs documentation in the packageWrite a more detailed description of each metricAdd examples and implementation notes to each metricUpdate listing in ‘details_for_all_metrics.py’Update the ‘Why jsmetrics’ section with notes about what jets are and quick start helpAdd some Examples of Use for each type of metricAdd ws_threshold parameter to Pena-Ortiz methodRename Pena-Ortiz method to ‘pena_ortiz_et_al_2016’ (as earlier paper)0.1.6-alpha (2023-08-19)Fix Manney et al. 2011 implementationCorrect Manney 2011 methodMove old method to new metric: ‘jet_core_identification_algorithm’Update docs for Manney 2011 and sub-components0.1.5-beta (2023-08-16)Update Schiemann method with new variable name (jet occurence), docstring and changes to sub-component function namesAdd ws_threshold parameter to SchiemannUpdate methods that work on one time unit of data and add squeeze method to properly deal if time not in dimsAdd basic outline of jet core algorithm docstrings0.1.5-alpha (2023-08-15)Begin overhaul of ReadTheDocs documentationAdd notes and example to Koch et al. 2006 metricRename variable returned by K06 to jet_events_ws0.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 metrics0.1.4-alpha (2023-07-21)add KeyError raise if no time coordinate is passed to various metrics0.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 dataAdd check for NoLeapDatetime0.1.2-alpha (2023-05-27)Add check for NoLeapDatetime0.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 type0.1.1-beta (2023-04-07)add parameter for Kerr et al. 2020Add Ceppi et al jet speed adaptation from Screen et al. 2022Add 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 func0.1.1-alpha (2023-03-31)Add fix for Kuang to run when there is no time dimAdd fix for BP15 to except errors where all nan dataAdd warning for BS17 when more than 10 days resolution0.1.0 (2023-01-22)MAJOR UPDATE: re-organise the structure of the package into core, metrics and utilsrename jet statistics, waviness metrics and jet core algorithm filesadd wrappers to check data is xarray and is sorted in descending order (in core/check_data.py)move waviness metrics to new fileUpdate appropriate tests0.0.19-alpha (2022-12-21)Update JetStreamOccurenceAndCentreAlgorithm to skip longitude values outside lon range in dataMake changes to work with Shapely version 1.8/2.0. Means changes to Cattiaux et al. 20160.0.18 (2022-11-23)update fitted parabola func for Barnes & Polvani 2015Add Blackport & Fyfe 2022update Barnes & Simpson 2017 to drop all NaN slicesupdate to check for more than one time step for time groupby methodsadd test to check all metrics when input is one time step0.0.17 (2022-11-13)add try and except for Grise & Polvani 2017 to account for missing vals0.0.16 (2022-11-09)skipna=True for calc_latitude_and_speed_where_max_wsBarnes and Simpson mean over longitude for jet lat0.0.15 (2022-11-09)rename max_lat_0.01 to jet_lat for Grise & Polvani 2017Fix get_3_latitudes_and_speed_around_max_ws to work with isel around lonFix barnes polvani parabola to deal with nan values0.0.14 (2022-11-09)add plev mean to Bracegirdle0.0.14-alpha (2022-10-25)update Pena Ortiz so that it returns monthyear and by day local wind maximaremove make_empty_local_wind_maxima_data funcFix CIAdd millibars to get_all_hPa_list0.0.13 (2022-10-19)fix workflow for publish to PyPi and TestPyPi0.0.12 (2022-10-19)fix kuang to work for southern hemisphere as welladd workflow for publish to PyPi0.0.12-alpha (2022-10-18)Update calc_latitude_and_speed_where_max_ws to use numpy methodsFix Barnes and Simpson 2017 method so it runs on each longitude0.0.11 (2022-09-15)Update and fix the JetStreamOccurenceAndCentreAlgorithm method for KuangChange LICENSEUpload to Zenodo0.0.10 (2022-08-21)First release to pypiClean up rst docs0.0.9 (2022-08-16)Finish testsRemove TODOsOutline metric_verification notebooksImprove docs0.0.8 (2022-07-18)Format the readmeseperate metrics into metrics and algorithmsReorder and write better docstrings for the utils filesUpdate year on LICENSE0.0.7-beta (2022-06-30)swap ‘plev’ and ‘lat’ in manney_et_al_2011 method so that it groups cores betterrename ‘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 jetremove prints from windspeed utilsrename bp13 jet lat0.0.6 (2022-06-09)add Barnes & Polvani 2015add Kerr et al. 2020add nearest method function to general utilsSpeed up Ceppi and fix integration method within (still need to verify)Add spatial utils for grid cell m2 method0.0.6-beta (2022-05-31)Fix ‘get_latitude_and_speed_where_max_ws_at_reduced_resolution’ with check for np.nans0.0.6-alpha (2022-05-25)add Barnes & Polvani 2013Fix ‘get_latitude_and_speed_where_max_ws’ so it can take one valueFix Barnes & Simpson 2017 and Woollings et al. 2010 and change name of colFix Barnes & Polvani neighbouring lats  and speed0.0.5 (2022-05-23)add Barnes & Simpson 2017Update ‘get_latitude_and_speed_where_max_ws’ functionUpdate calc_mass_weighted windBIG CHANGESChange 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 lat0.0.5-beta (2022-05-03)update Woollings et al. 2010 with seasonal cycleupdate metric details dict with ‘plev_units’ argumentfix archer and caldiera call to mass weighted ws (STILL TODO: better plev understanding)0.0.5-alpha (2022-04-24)add metric verification notebooks0.0.4-beta (2022-02-09)add description, name and DOI to metric details dict0.0.4-alpha (2022-01-26)remove Dockerremove get data scripts0.0.3-gamma (2022-01-14)remove python 3.6 compatibilityupdate environment yml (still broken)0.0.3-beta (2022-01-14)Use real part from fourier filter to Woollings and its tests0.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 github0.0.2-beta (2022-01-10)Add docstrings to all metrics and sub-components0.0.2-alpha (2022-01-04)Add docstrings to Archer & Calidera metric0.0.1 (2022-01-04)Allow jsmetric to call jetstream_metrics and utils0.0.1-beta (2021-12-30)Add currently existing metrics