Merge pull request #630 from nci/develop

Release 1.1.0

.zenodo.json

@@ -0,0 +1,71 @@
+{
+    "creators": [
+        {
+            "orcid": "https://orcid.org/0009-0008-2024-1967",
+            "affiliation": "Bureau of Meteorology",
+            "name": "Leeuwenburg, Tennessee"
+        },
+        {
+            "orcid": "https://orcid.org/0009-0000-5796-7069",
+            "affiliation": "Bureau of Meteorology",
+            "name": "Loveday, Nicholas"
+        },
+        {
+            "affiliation": "Bureau of Meteorology",
+            "name": "Ebert, Elizabeth E."
+        },
+        {
+            "orcid": "https://orcid.org/0009-0009-3207-4876",
+            "affiliation": "Bureau of Meteorology",
+            "name": "Cook, Harrison"
+        },
+        {
+            "orcid": "https://orcid.org/0000-0002-5017-9622",
+            "affiliation": "Bureau of Meteorology",
+            "name": "Khanarmuei, Mohammadreza"
+        },
+        {
+            "orcid": "https://orcid.org/0000-0002-0067-5687",
+            "affiliation": "Bureau of Meteorology",
+            "name": "Taggart, Robert J."
+        },
+        {
+            "orcid": "https://orcid.org/0009-0002-7406-7438",
+            "affiliation": "Bureau of Meteorology",
+            "name": "Ramanathan, Nikeeth"
+        },
+        {
+            "orcid": "https://orcid.org/0009-0008-6830-8251",
+            "affiliation": "Bureau of Meteorology",
+            "name": "Carroll, Maree"
+        },
+        {
+            "orcid": "https://orcid.org/0009-0007-0796-4127",
+            "affiliation": "Independent Contributor",
+            "name": "Chong, Stephanie"
+        },
+        {
+            "affiliation": "Work undertaken while at the Bureau of Meteorology",
+            "name": "Griffiths, Aidan"
+        },
+        {
+            "affiliation": "Bureau of Meteorology",
+            "name": "Sharples, John"
+        },                      
+    ],
+
+    "license": "Apache-2.0",
+
+    "title": "scores: A Python package for verifying and evaluating models and predictions with xarray",
+
+    "related_identifiers": [
+        {
+            "scheme": "doi",
+            "identifier": "10.21105/joss.06889",
+            "relation": "isDocumentedBy",
+            "resource_type": "publication-article"
+        }
+    ],
+
+    "keywords": ["verification", "statistics", "modelling", "geoscience", "earth system science"],
+}

README.md

@@ -1,51 +1,64 @@
 # scores: Verification and Evaluation for Forecasts and Models
 
-[![CodeQL](https://github.com/nci/scores/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/nci/scores/actions/workflows/github-code-scanning/codeql) [![Coverage Status](https://coveralls.io/repos/github/nci/scores/badge.svg)](https://coveralls.io/github/nci/scores) [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/nci/scores/main?labpath=tutorials%2FTutorial_Gallery.ipynb) [![DOI](https://joss.theoj.org/papers/10.21105/joss.06889/status.svg)](https://doi.org/10.21105/joss.06889)
+[![CodeQL](https://github.com/nci/scores/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/nci/scores/actions/workflows/github-code-scanning/codeql) [![Coverage Status](https://coveralls.io/repos/github/nci/scores/badge.svg)](https://coveralls.io/github/nci/scores) [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/nci/scores/main?labpath=tutorials%2FTutorial_Gallery.ipynb) [![PyPI Version](https://img.shields.io/pypi/v/scores.svg)](https://pypi.org/project/scores/) [![Conda Version](https://img.shields.io/conda/vn/conda-forge/scores.svg)](https://anaconda.org/conda-forge/scores)
 
 > 
 > **A list of over 50 metrics, statistical techniques and data processing tools contained in `scores` is [available here](https://scores.readthedocs.io/en/stable/included.html).**
 
 `scores` is a Python package containing mathematical functions for the verification, evaluation and optimisation of forecasts, predictions or models. It supports labelled n-dimensional (multidimensional) data, which is used in many scientific fields and in machine learning. At present, `scores` primarily supports the geoscience communities; in particular, the meteorological, climatological and oceanographic communities.
 
-Documentation is hosted at [scores.readthedocs.io](https://scores.readthedocs.io).  
-Source code is hosted at [github.com/nci/scores](https://github.com/nci/scores).  
-The tutorial gallery is hosted at [as part of the documentation, here](https://scores.readthedocs.io/en/stable/tutorials/Tutorial_Gallery.html). 
+Documentation: [scores.readthedocs.io](https://scores.readthedocs.io)  
+Source code: [github.com/nci/scores](https://github.com/nci/scores)  
+Tutorial gallery: [available here](https://scores.readthedocs.io/en/stable/tutorials/Tutorial_Gallery.html)  
+Journal article: [*scores: A Python package for verifying and evaluating models and predictions with xarray*](https://doi.org/10.21105/joss.06889)
 
 ## Overview
 Here is a **curated selection** of the metrics, tools and statistical tests included in `scores`:
 
 |                       	| **Description** 	| **Selection of Included Functions** 	|
 |-----------------------	|-----------------	|--------------	|
-| **[Continuous](https://scores.readthedocs.io/en/stable/included.html#continuous)**        	|Scores for evaluating single-valued continuous forecasts.                  	|Mean Absolute Error (MAE), Mean Squared Error (MSE), Root Mean Squared Error (RMSE), Additive Bias, Multiplicative Bias, Pearson's Correlation Coefficient, Flip-Flop Index, Quantile Loss, Murphy Score, families of consistent scoring functions for quantiles and expectiles.              	|
+| **[Continuous](https://scores.readthedocs.io/en/stable/included.html#continuous)**        	|Scores for evaluating single-valued continuous forecasts.                  	|Mean Absolute Error (MAE), Mean Squared Error (MSE), Root Mean Squared Error (RMSE), Additive Bias, Multiplicative Bias, Pearson's Correlation Coefficient, Flip-Flop Index, Quantile Loss, Murphy Score, families of consistent scoring functions for quantiles and expectiles, Threshold Weighted Squared Error, Threshold Weighted Quantile Score, Threshold Weighted Absolute Error, Threshold Weighted Expectile Score, Threshold Weighted Huber Loss.             	|
 | **[Probability](https://scores.readthedocs.io/en/stable/included.html#probability)**       	|Scores for evaluating forecasts that are expressed as predictive distributions, ensembles, and probabilities of binary events.                 	|Brier Score, Continuous Ranked Probability Score (CRPS) for Cumulative Density Function (CDF), Threshold weighted CRPS for CDF, CRPS for ensembles, Receiver Operating Characteristic (ROC), Isotonic Regression (reliability diagrams).              	|
 | **[Categorical](https://scores.readthedocs.io/en/stable/included.html#categorical)**       	|Scores (including contingency table metrics) for evaluating forecasts of categories.                	|Probability of Detection (POD), False Alarm Ratio (FAR), Probability of False Detection (POFD), Success Ratio, Accuracy, Peirce's Skill Score, Critical Success Index (CSI), Gilbert Skill Score, Heidke Skill Score, Odds Ratio, Odds Ratio Skill Score, F1 score, Symmetric Extremal Dependence Index, FIxed Risk Multicategorical (FIRM) Score.               	|
 | **[Spatial](https://scores.readthedocs.io/en/stable/included.html#spatial)** 	|Scores that take into account spatial structure.                 	|Fractions Skill Score.              	|
 | **[Statistical Tests](https://scores.readthedocs.io/en/stable/included.html#statistical-tests)** 	|Tools to conduct statistical tests and generate confidence intervals.                 	|Diebold Mariano.              	|
 | **[Processing Tools](https://scores.readthedocs.io/en/stable/included.html#processing-tools-for-preparing-data)**        	|Tools to pre-process data.                 	|Data matching, Discretisation, Cumulative Density Function Manipulation.              	|
 
 
-`scores` not only includes common scores (e.g. MAE, RMSE), it includes novel scores not commonly found elsewhere (e.g. FIRM, Flip-Flop Index), complex scores (e.g. threshold weighted CRPS), and statistical tests (such as the Diebold Mariano test). Additionally, it provides pre-processing tools for preparing data for scores in a variety of formats including cumulative distribution functions (CDF). `scores` provides its own implementations where relevant to avoid extensive dependencies.
+`scores` not only includes common scores (e.g., MAE, RMSE), it includes novel scores not commonly found elsewhere (e.g., FIRM, Flip-Flop Index), complex scores (e.g., threshold weighted CRPS), and statistical tests (such as the Diebold Mariano test). Additionally, it provides pre-processing tools for preparing data for scores in a variety of formats including cumulative distribution functions (CDF). `scores` provides its own implementations where relevant to avoid extensive dependencies.
 
 `scores` primarily supports xarray datatypes for Earth system data allowing it to work with NetCDF4, HDF5, Zarr and GRIB data sources among others. `scores` uses Dask for scaling and performance. Some metrics work with pandas and we aim to expand this capability. 
 
 All of the scores and metrics in this package have undergone a thorough scientific review. Every score has a companion Jupyter Notebook tutorial that demonstrates its use in practice.
 
 ## Contributing
-To find out more about contributing, see our [Contributing Guide](https://scores.readthedocs.io/en/stable/contributing.html).
+To find out more about contributing, see our [contributing guide](https://scores.readthedocs.io/en/stable/contributing.html).
 
-All interactions in discussions, issues, emails and code (e.g. pull requests, code comments) will be managed according to the expectations outlined in the [ code of conduct ](https://github.com/nci/scores/blob/main/CODE_OF_CONDUCT.md) and in accordance with all relevant laws and obligations. This project is an inclusive, respectful and open project with high standards for respectful behaviour and language. The code of conduct is the Contributor Covenant, adopted by over 40,000 open source projects. Any concerns will be dealt with fairly and respectfully, with the processes described in the code of conduct.
+All interactions in discussions, issues, emails and code (e.g., pull requests, code comments) will be managed according to the expectations outlined in the [ code of conduct ](https://github.com/nci/scores/blob/main/CODE_OF_CONDUCT.md) and in accordance with all relevant laws and obligations. This project is an inclusive, respectful and open project with high standards for respectful behaviour and language. The code of conduct is the Contributor Covenant, adopted by over 40,000 open source projects. Any concerns will be dealt with fairly and respectfully, with the processes described in the code of conduct.
 
-## Using This Package
+## Installation
 
 The [installation guide](https://scores.readthedocs.io/en/stable/installation.html) describes four different use cases for installing, using and working with this package.
 
-Most users currently want the *all* installation option. This includes the mathematical functions (scores, metrics, statistical tests etc.), the tutorial notebooks and development libraries.
+**Most users currently want the *all* installation option.** This includes the mathematical functions (scores, metrics, statistical tests etc.), the tutorial dependencies and development libraries.
 
-From a Local Checkout of the Git Repository
+```bash
+# From a local checkout of the Git repository
+pip install -e .[all]
+```
+**To install the mathematical functions ONLY** (no tutorial dependencies, no developer libraries), use the default *minimal* installation option. *minimal* is a stable version with limited dependencies. This can be installed from the [Python Package Index (PyPI)](https://pypi.org/project/scores/) or with [conda](https://anaconda.org/conda-forge/scores).
 
 ```bash
-> pip install -e .[all]
+# From PyPI
+pip install scores
 ```
+```bash
+# From conda-forge
+conda install conda-forge::scores
+```
+(Note: at present, only the *minimal* installation option is available from conda. In time, we intend to add more installation options to conda.)
+
+## Using `scores`
 
 Here is a short example of the use of scores:
 
@@ -58,16 +71,11 @@ Here is a short example of the use of scores:
 <xarray.DataArray ()>
 array(2.)
 ```
-
-To install the mathematical functions ONLY (no tutorial notebooks, no developer libraries), use the *minimal* installation option. *minimal* is a stable version with limited dependencies and can be installed from the Python Package Index.
-
-```bash
-> pip install scores
-```
+[Jupyter Notebook tutorials](https://scores.readthedocs.io/en/stable/tutorials/Tutorial_Gallery.html) are provided for each metric and statistical test in `scores`, as well as for some of the key features of `scores` (e.g., [dimension handling](https://scores.readthedocs.io/en/stable/tutorials/Dimension_Handling.html) and [weighting results](https://scores.readthedocs.io/en/stable/tutorials/Weighting_Results.html)). 
 
 ## Finding, Downloading and Working With Data
 
-All metrics, statistical techniques and data processing tools in `scores` work with [xarray](https://xarray.dev). [Some metrics](https://scores.readthedocs.io/en/stable/included.html#pandas) work with [pandas](https://pandas.pydata.org/). As such, `scores` works with any data source for which xarray or pandas can be used. See the [Data Sources](https://scores.readthedocs.io/en/stable/data.html) page and [this tutorial](https://scores.readthedocs.io/en/stable/tutorials/First_Data_Fetching.html) for more information on finding, downloading and working with different sources of data.
+All metrics, statistical techniques and data processing tools in `scores` work with [xarray](https://xarray.dev). [Some metrics](https://scores.readthedocs.io/en/stable/included.html#pandas) work with [pandas](https://pandas.pydata.org/). As such, `scores` works with any data source for which xarray or pandas can be used. See the [data sources](https://scores.readthedocs.io/en/stable/data.html) page and [this tutorial](https://scores.readthedocs.io/en/stable/tutorials/First_Data_Fetching.html) for more information on finding, downloading and working with different sources of data.
 
 ## Acknowledging This Work
 

docs/api.md

@@ -26,6 +26,11 @@
 .. autofunction:: scores.continuous.consistent_expectile_score
 .. autofunction:: scores.continuous.consistent_quantile_score
 .. autofunction:: scores.continuous.consistent_huber_score
+.. autofunction:: scores.continuous.tw_quantile_score
+.. autofunction:: scores.continuous.tw_absolute_error
+.. autofunction:: scores.continuous.tw_squared_error
+.. autofunction:: scores.continuous.tw_huber_loss
+.. autofunction:: scores.continuous.tw_expectile_score
 ```
 
 ## scores.probability

docs/conf.py

@@ -9,7 +9,7 @@
 
 project = "scores"
 copyright = "Licensed under Apache 2.0 - https://www.apache.org/licenses/LICENSE-2.0"
-release = "1.0.0"
+release = "1.1.0"
 
 version = __version__
 
@@ -54,29 +54,14 @@
 # -- nbsphinx ---------------------------------------------------------------
 # This is processed by Jinja2 and inserted after each notebook
 nbsphinx_prolog = r"""
-{% set docname = '' + env.doc2path(env.docname, base=False) %}
+{% set docname = '' + env.doc2path(env.docname, base=False)|string() %}
 
 .. raw:: html
 
     <div class="admonition note">
       Interactive online version:
       <span style="white-space: nowrap;"><a href="https://mybinder.org/v2/gh/nci/scores/main?labpath={{ docname|e }}"><img alt="Binder badge" src="https://mybinder.org/badge_logo.svg" style="vertical-align:text-bottom"></a>.</span>
       <a href="{{ env.docname.split('/')|last|e + '.ipynb' }}" class="reference download internal" download>Download notebook</a>.
-      <script>
-        if (document.location.host) {
-          let nbviewer_link = document.createElement('a');
-          nbviewer_link.setAttribute('href',
-            'https://nbviewer.org/url' +
-            (window.location.protocol == 'https:' ? 's/' : '/') +
-            window.location.host +
-            window.location.pathname.slice(0, -4) +
-            'ipynb');
-          nbviewer_link.innerHTML = 'Or view it on <em>nbviewer</em>';
-          nbviewer_link.classList.add('reference');
-          nbviewer_link.classList.add('external');
-          document.currentScript.replaceWith(nbviewer_link, '.');
-        }
-      </script>
     </div>
 
 .. raw:: latex
@@ -88,7 +73,7 @@
 
 # This is processed by Jinja2 and inserted after each notebook
 nbsphinx_epilog = r"""
-{% set docname = 'doc/' + env.doc2path(env.docname, base=None) %}
+{% set docname = 'doc/' + env.doc2path(env.docname, base=None)|string() %}
 .. raw:: latex
 
     \nbsphinxstopnotebook{\scriptsize\noindent\strut

docs/included.md

@@ -117,6 +117,26 @@
   - [API](api.md#scores.continuous.rmse)
   - [Tutorial](project:./tutorials/Root_Mean_Squared_Error.md)
   - [Wikipedia](https://en.wikipedia.org/wiki/Root-mean-square_deviation)
+* - Threshold Weighted Absolute Error
+  - [API](api.md#scores.continuous.tw_absolute_error)
+  - [Tutorial](project:./tutorials/Threshold_Weighted_Scores.md)
+  - [Taggart (2022)](https://doi.org/10.1002/qj.4206)
+* - Threshold Weighted Expectile Score
+  - [API](api.md#scores.continuous.tw_expectile_score)
+  - [Tutorial](project:./tutorials/Threshold_Weighted_Scores.md)
+  - [Taggart (2022)](https://doi.org/10.1002/qj.4206)
+* - Threshold Weighted Huber Loss
+  - [API](api.md#scores.continuous.tw_huber_loss)
+  - [Tutorial](project:./tutorials/Threshold_Weighted_Scores.md)
+  - [Taggart (2022)](https://doi.org/10.1002/qj.4206)
+* - Threshold Weighted Quantile Score
+  - [API](api.md#scores.continuous.tw_quantile_score)
+  - [Tutorial](project:./tutorials/Threshold_Weighted_Scores.md)
+  - [Taggart (2022)](https://doi.org/10.1002/qj.4206)
+* - Threshold Weighted Squared Error
+  - [API](api.md#scores.continuous.tw_squared_error)
+  - [Tutorial](project:./tutorials/Threshold_Weighted_Scores.md)
+  - [Taggart (2022)](https://doi.org/10.1002/qj.4206)
 ```
 
 ## Probability