scores

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

★ 229 Open GitHub ↗

scores: Metrics for the verification, evaluation and optimisation of forecasts, predictions or models.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# scores: Verification and Evaluation for Forecasts and Models

[![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=docs/tutorials/Tutorial_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 75 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: [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 paper: [*scores: A Python package for verifying and evaluating models and predictions with xarray*](https://doi.org/10.21105/joss.06889)

**If you use `scores` for your work or a publication, [please cite](https://github.com/nci/scores#acknowledging-or-citing-scores) both our [paper](https://doi.org/10.21105/joss.06889) and the [Zenodo record](https://doi.org/10.5281/zenodo.12697241) for the version of `scores` that you use.**

## Overview

Below is a **curated selection** of the metrics, tools and statistical tests included in `scores`. [(Click here for the full list.)](https://scores.readthedocs.io/en/stable/included.html)

|                       	| **Description** 	| **Selection of Included Functions** 	|
|-----------------------	|-----------------	|--------------	|
| **[Continuous](https://scores.readthedocs.io/en/stable/included.html#continuous)**        	|Scores for evaluating single-valued continuous forecasts.                  	|E.g. MAE, MSE, RMSE, Bias, Pearson's Correlation Coefficient, Kling-Gupta Efficiency, NSE, Flip-Flop Index, Quantile Loss, Quantile Interval Score, Interval Score, and threshold weighted scores for expectiles, quantiles and Huber Loss. [See all.](https://scores.readthedocs.io/en/stable/included.html#continuous)             	|
| **[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.                   |E.g. Brier Score, PIT, CRPS for CDFs and ensembles (including threshold weighted versions), and Isotonic Regression (reliability diagrams). [See all.](https://scores.readthedocs.io/en/stable/included.html#probability)               |
| **[Categorical](https://scores.readthedocs.io/en/stable/included.html#categorical)**       	|Scores for evaluating forecasts of categories.                	|E.g. 18 binary contingency table (confusion matrix) metrics, the FIxed Risk Multicategorical (FIRM) Score, the SEEPS score and the Risk Matrix Score. [See all.](https://scores.readthedocs.io/en/stable/included.html#categorical)               	|
| **[Spatial](https://scores.readthedocs.io/en/stable/included.html#spatial)** 	|Scores that take into account spatial structure.                 	|Fractions Skill Score. [See all.](https://scores.readthedocs.io/en/stable/included.html#spatial)              	|
| **[Dynamics](https://scores.readthedocs.io/en/stable/included.html#dynamics)** 	|Compute diagnostics based on dynamical properties.                 	|Energetics budget and Energetics exchanges. [See all.](https://scores.readthedocs.io/en/stable/included.html#dynamics)             	|
| **[Statistical Tests](https://scores.readthedocs.io/en/stable/included.html#statistical-tests)** 	|Tools to conduct statistical tests and generate confidence intervals.                 	|Diebold Mariano. [See all.](https://scores.readthedocs.io/en/stable/included.html#statistical-tests)             	|
| **[Processing Tools](https://scores.readthedocs.io/en/stable/included.html#processing-tools-for-preparing-data)**        	|Tools to pre-process data.                 	|E.g. Data matching, Discretisation, Block Bootstrapping, and Cumulative Density Function Manipulation. [See all.](https://scores.readthedocs.io/en/stable/included.html#processing-tools-for-preparing-data)              	|
| **[Plotting Data](https://scores.readthedocs.io/en/stable/included.html#plotting-data)**        	|Tools to generate data for plotting.	|ROC curves, Murphy diagrams, Q-Q plots, rank histograms, and relative economic value. [See all.](https://scores.readthedocs.io/en/stable/included.html#plotting-data)             	|
| **[Emerging](https://scores.readthedocs.io/en/stable/included.html#emerging)**        	|Emerging scores that are still undergoing mathematical peer review. They may change in line with the peer review process.                 	| *Note - the Risk Matrix Score has recently been moved to 'categorical' following peer-reviewed publication*.            	|

`scores` not only includes common scores (e.g., MAE, RMSE), it also includes novel scores not commonly found elsewhere (e.g., FIRM, Flip-Flop Index), complex scores (e.g., threshold weighted CRPS), and statistical tests (e.g., 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 formats 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 and software review. Every score has a companion Jupyter Notebook tutorial that demonstrates its use in practice.

## Contributing

Contributions from the community are warmly welcomed. To find out more, 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.

## 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 dependencies and development libraries.

```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
# 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`:

```py
> import scores
> forecast = scores.sample_data.simple_forecast()
> observed = scores.sample_data.simple_observations()
> mean_absolute_error = scores.continuous.mae(forecast, observed)
> print(mean_absolute_error)
<xarray.DataArray ()>
array(2.)
```
[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)).

To watch a PyCon AU 2024 conference presentation about `scores` [click here](https://youtu.be/jyq2jOqtXe0?si=HYoW1cNiplbb3R0c).

## 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.

## Archives of `scores` on Zenodo

`scores` is archived on Zenodo. [Click here](https://doi.org/10.5281/zenodo.12697241) to see the latest version on Zenodo.

## Acknowledging or Citing `scores`

**If you use `scores` for your work or a publication, we would appreciate you citing both our [paper](https://doi.org/10.21105/joss.06889) and also the [Zenodo record](https://doi.org/10.5281/zenodo.12697241) for the version of `scores` that you used.**

- **Our [paper](https://doi.org/10.21105/joss.06889) can be cited as follows:**
	- Leeuwenburg, T., Loveday, N., Ebert, E. E., Cook, H., Khanarmuei, M., Taggart, R. J., Ramanathan, N., Carroll, M., Chong, S., Griffiths, A., & Sharples, J. (2024). scores: A Python package for verifying and evaluating models and predictions with xarray. *Journal of Open Source Software, 9*(99), 6889. [https://doi.org/10.21105/joss.06889](https://doi.org/10.21105/joss.06889)
	- BibTeX:
		```
		@article{Leeuwenburg_scores_A_Python_2024,
		author      = {Leeuwenburg, Tennessee and Loveday, Nicholas and Ebert, Elizabeth E. and Cook, Harrison and Khanarmuei, Mohammadreza and Taggart, Robert J. and Ramanathan, Nikeeth and Carroll, Maree and Chong, Stephanie and Griffiths, Aidan and Sharples, John},
		doi         = {10.21105/joss.06889},
		journal     = {Journal of Open Source Software},
		month       = jul,
		number      = {99},
		pages       = {6889},
		title       = {{scores: A Python package for verifying and evaluating models and predictions with xarray}},
		url         = {https://joss.theoj.org/papers/10.21105/joss.06889},
		volume      = {9},
		year        = {2024}
		}
		```
- **Please also cite the [Zenodo record](https://doi.org/10.5281/zenodo.12697241) for the version of `scores` that you used.**
	- Where possible, please include the version number, e.g. (Version 2.6.0), and the publisher (Zenodo).
    - For example, below is the citation for Version 2.6.0 of `scores`:  
	- Leeuwenburg, T., Loveday, N., Ramanathan, N., Chong, S., Taggart, R. J., Shrestha, D., Khanarmuei, M., Cook, H., Bluett, L., Ebert, E. E., Carroll, M., Trotta, B., Sharples, J., Bishop, S., Squire, D. T., Griffiths, A., Pagano, T. C., Fisher, A. J., Mandelbaum, T., … Morrison, O. M. (2026). *scores: Metrics for the verification, evaluation and optimisation of forecasts, predictions or models* (Version 2.6.0) [Computer software]. Zenodo. [https://doi.org/10.5281/zenodo.21403944](https://doi.org/10.5281/zenodo.21403944)
	- BibTeX:
		```
		@software{leeuwenburg_2026_21403944,
  		author      = {Leeuwenburg, Tennessee and Loveday, Nicholas and Ramanathan, Nikeeth and Chong, Stephanie and Taggart, Robert J. and Shrestha, Durga and Khanarmuei, Mohammadreza and Cook, Harrison and Bluett, Liam and Ebert, Elizabeth E. and Carroll, Maree and Trotta, Belinda and Sharples, John and Bishop, Sam and Squire, Dougal T. and Griffiths, Aidan and Pagano, Thomas C. and Fisher, A.J. and Mandelbaum, Taylor and Jinghan, Fu and Smith, Paul R. and Abellan, Esteban and Beunk, Jurian and Esperson, Felix and Smallwood, J. and Wu, Xiaoxi and Karney, Daniel and Morrison, Oisín M.},
  		title       = {{scores: Metrics for the verification, evaluation and optimisation of forecasts, predictions or models}},
  		month       = jul,
  		year        = 2026,
  		publisher   = {Zenodo},
  		version     = {2.6.0},
  		doi         = {10.5281/zenodo.21403944},
  		url         = {https://doi.org/10.5281/zenodo.21403944},
		}
		```

scores

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README