Metadata-Version: 2.1
Name: jsmetrics
Version: 0.0.14
Summary: Library of algorithms and metrics used to characterise and/or identify jet-streams, based on xarray.
Home-page: https://github.com/Thomasjkeel/jsmetrics
Author: Thomas Keel
Author-email: thomas.keel.18@ucl.ac.uk
License: MIT License
Keywords: jet-stream climate metrics algorithms xarray
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.7.0
Description-Content-Type: text/x-rst
Provides-Extra: dev
Provides-Extra: data_install
License-File: LICENSE

============================================
jsmetrics: Jet-stream metrics and algorithms
============================================

|pypi| |pre-commit| |codefactor| |coveralls| |docs| |license| |black| |zenodo|  
------------------------------------------------------------------------------

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.
*WORK IN PROGRESS*

.. WRITE WHY JET-STREAM (maybe in blog, maybe in readme) -> heatwaves, beast from the east, climate proxy (put it all down)
.. At the foundation of studies that look at jet-streams is the metric used to describe or characterise it.

.. WRITE CURRENT PROGRESS WITH MODULDE in highlighted section near the top of this readme 

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)
- lat/lon resolution
- latitude/longitude region (where possible),
- pressure level region
All of these can be handled user-side.

.. 
        ALSO all algorithms have been broken down into various components and these components are not coupled to a given methodology.
        As such each can be used seperately and this allows users to rebuilt aspects of a methodology (e.g. to replace a filtering method)


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

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

Usage
-------------
.. code-block:: python

    import xarray as xr
    import jsmetrics

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

    # run Kuang et al. 2014 metric 
    k14 = jsmetrics.jetstream_algorithms.kuang_et_al_2014(uv_data)

.. image:: docs/_static/images/kuang_jet_centers.png
  :width: 360
  :align: center
  :alt: Kuang et al. 2014 Jet-core algorithm

DISCLAIMER
-------------
I have tried to replicate the various metrics based on the equations and details in the methodology as accurately as possible.
In some cases I have used a different dataset to the one used in the paper they originate from or with different data resolution. 
Further, 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 [TODO]

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

Where you can find my working-out:
- I have included all of my working out in jupyter-notebooks available at: ... [TODO] (warning: these notebooks have not been formatted nicely) 
- I am currently creating a verification notebook available at: ... [TODO] 


Metrics & Algorithms
--------------------
See `all metrics`_ for specifications of each 'Complete' or 'In progress' metric and algorithm. For progress on their completion see `Status`_.


.. table::
   :align: left
   :widths: auto
   
   =============================================================================== ==============  ==  =============================================================================== ==============
   Metric/Algorithm                                                                `Status`_           Metric/Algorithm                                                                `Status`_                                                                                
   =============================================================================== ==============  ==  =============================================================================== ==============
   `Gallego et al. 2005 <http://link.springer.com/10.1007/s00382-005-0006-7>`_     To start            `Strong & Davis 2005 <http://doi.wiley.com/10.1029/2004GL022039>`_              To start
   `Koch et al. 2006 <https://onlinelibrary.wiley.com/doi/10.1002/joc.1255>`_      To verify           `Archer & Caldiera 2008 <http://doi.wiley.com/10.1029/2008GL033614>`_           To verify
   `Schiemann et al. 2009 <https://doi.org/10.1175/2008JCLI2625.1>`_               To verify           `Woollings et al. 2010 <https://onlinelibrary.wiley.com/doi/10.1002/qj.625>`_   Complete
   `Manney et al. 2011 <https://acp.copernicus.org/articles/11/6115/2011/>`_       In progess*         `Allen et al. 2012 <http://www.nature.com/articles/nature11097>`_               To start
   `Barnes & Polvani 2013 <https://doi.org/10.1175/JCLI-D-12-00536.1>`_            To verify           `Pena-Ortiz et al. 2013 <http://doi.wiley.com/10.1002/jgrd.50305>`_             To verify      
   `Screen & Simmonds 2013 <http://doi.wiley.com/10.1002/grl.50174>`_              In progress*        `Kuang et al. 2014 <http://link.springer.com/10.1007/s00704-013-0994-x>`_       To verify            
   `Barnes & Polvani 2015 <https://doi.org/10.1175/JCLI-D-14-00589.1>`_            To verify           `Francis & Vavrus 2015 <https://doi.org/10.1088/1748-9326/10/1/014005>`_        Complete            
   `Cattiaux et al. 2016 <https://doi.wiley.com/10.1002/2016GL070309>`_            To verify           `Barnes & Simpson 2017 <https://doi.org/10.1175/JCLI-D-17-0299.1>`_             To verify            
   `Chenoli et al. 2017 <http://link.springer.com/10.1007/s00382-016-3102-y>`_     In progress         `Grise & Polvani 2017 <https://doi.org/10.1175/JCLI-D-16-0849.1>`_              Complete                        
   `Molnos et al. 2017  <https://doi.org/10.5194/esd-8-75-2017>`_                  In progress*        `Adam et al. 2018 <https://doi.org/10.5194/gmd-11-4339-2018>`_                  To start            
   `Bracegirdle et al. 2018 <https://doi.org/10.1175/JCLI-D-17-0320.1>`_           Complete            `Ceppi et al. 2018 <https://doi.org/10.1175/JCLI-D-17-0323.1>`_                 To verify            
   `Kern et al. 2018 <http://ieeexplore.ieee.org/document/8017585/>`_              To start*           `Rikus 2018 <http://dx.doi.org/10.1007/s00382-015-2560-y>`_                     In progress            
   `Kern & Westermann 2019 <https://doi.org/10.2312/vmv.20191321>`_                To start            `Kerr et al. 2020 <https://doi.org/10.1029/2020JD032735>`_                      To verify            
   `Maher et al. 2020 <https://doi.org/10.1007/s00382-019-05084-6>`_               To start            `Winters et al. 2020 <https://doi.org/10.1175/MWR-D-19-0353.1>`_                To start            
   `Martin 2021 <https://onlinelibrary.wiley.com/doi/10.1029/2020JD033668>`_       To start*           `Bosiger et al. 2022 <https://doi.org/10.5194/gmd-15-1079-2022>`_               To start            
   `Local Wave Activity <https://doi.org/10.1175/JAS-D-15-0194.1>`_                In progress*                        
   =============================================================================== ==============  ==  =============================================================================== ==============

* == help needed

.. _all metrics: https://github.com/Thomasjkeel/jsmetrics/blob/write-docs/jsmetrics/details_for_all_metrics.py
.. _Status: https://github.com/Thomasjkeel/jsmetrics/projects/1

.. 
        _also mention related references (i.e. Manney et al. )
        also Local Wave Activity (maybe martineu?)
        Gallego


Installation 
-------------
.. code-block:: bash
    
    pip install jsmetrics

.. 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`_. There is also a chat room on gitter (|gitter|).

.. * If you would like to contribute code or documentation (which is greatly appreciated!), check out the `Contributing Guidelines`_ before you begin!

.. .. _issue tracker: https://github.com/Thomasjkeel/jsmetrics/issues
.. .. _Contributing Guidelines: https://github.com/Thomasjkeel/jsmetrics/blob/master/.github/CONTRIBUTING.rst


.. How to cite this package
.. ------------------------
.. If you wish to cite `jsmetrics` in a research publication, we kindly ask that you use the bibliographical reference information available through `Zenodo`


Project To-Do's
---------------
        - WRITE AND CLEAN-UP README
        - FINISH verification notebook.
        - WRITE plan to finish metrics.
        - 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/)

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.

.. |license| image:: https://img.shields.io/github/license/thomasjkeel/jsmetrics
        :target: https://github.com/Thomasjkeel/jsmetrics/blob/master/LICENSE
        :alt: License

.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
        :target: https://github.com/python/black
        :alt: Python Black

.. |pre-commit| image:: https://results.pre-commit.ci/badge/github/Thomasjkeel/jsmetrics/main.svg
   :target: https://results.pre-commit.ci/latest/github/Thomasjkeel/jsmetrics/main
   :alt: pre-commit.ci status

.. |codefactor| image:: https://www.codefactor.io/repository/github/thomasjkeel/jsmetrics/badge
   :target: https://www.codefactor.io/repository/github/thomasjkeel/jsmetrics
   :alt: CodeFactor
   
.. |coveralls| image:: https://coveralls.io/repos/github/Thomasjkeel/jsmetrics/badge.svg?branch=main
   :target: https://coveralls.io/github/Thomasjkeel/jsmetrics?branch=main

.. |zenodo| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.7081634.svg
        :target: https://doi.org/10.5281/zenodo.7081634
        :alt: DOI

.. |docs| image:: https://readthedocs.org/projects/jsmetrics/badge/?version=latest
    :target: https://jsmetrics.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status

.. |pypi| image:: https://img.shields.io/pypi/v/jsmetrics.svg
        :target: https://pypi.org/project/jsmetrics/
        :alt: Python Package Index Build

.. .. |conda| image:: https://img.shields.io/conda/vn/conda-forge/jsmetrics.svg
..         :target: https://anaconda.org/conda-forge/jsmetrics
..         :alt: Conda-forge Build Version


=======
History
=======

0.0.14 (2022-10-25)
-------------------------
* 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


