Add conda install instructions to installation.md and README.md, plus…

… various updates to README.md (#627) * Add conda installation instructions to installation.md among other updates * Change path to environment to named environment * Updated installation instructions in README.md among other updates --------- Signed-off-by: Stephanie Chong <[email protected]> Co-authored-by: Nicholas Loveday <[email protected]>
nci · Aug 9, 2024 · 18eaf90 · 18eaf90
1 parent e72e1e8
commit 18eaf90
Show file tree

Hide file tree

Showing 2 changed files with 55 additions and 37 deletions.
diff --git a/README.md b/README.md
@@ -25,28 +25,40 @@ Here is a **curated selection** of the metrics, tools and statistical tests incl
 | **[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:
 
@@ -59,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
 

diff --git a/docs/installation.md b/docs/installation.md
@@ -5,7 +5,7 @@
 This page describes:
 
 - Setting up a virtual environment.
-- The most common installation options for `scores`. (Expert users of pip and conda will note that more variations are possible).
+- The most common installation options for `scores`. (Expert users of pip and conda will note that more variations are possible.)
 - An advanced installation option for Jupyter Notebook, for users who wish to separate the Jupyter environment and the `scores` execution environment.
 
 ## Setting up a Virtual Environment
@@ -25,76 +25,87 @@ source <path_to_environment>/bin/activate
 
 Here is a command to create and activate a new virtual environment with *conda*
 ```py
-conda create -p <path_to_enviroment> python=3
-conda activate <path_to_environment>
-
+conda create --name <my-env>
+conda activate <my-env>
 ```
 
 ## Installation Options
 
-Most users will want the "all" installation option. There are also more specialised options for those who need them.  
+There are multiple installation options. Most users currently want the "all" installation option. 
 
 The 4 supported installation options are:
 
-- all: contains mathematical functions, tutorials and development libraries. Excludes maintainer requirements.
-- minimal: ONLY contains mathematical functions (so has limited dependencies).
-- tutorial: ONLY contains mathematical functions and tutorials.
-- maintainer: ONLY contains tools for building the documentation and building for PyPI.
+- all: contains mathematical functions, tutorial dependencies and development libraries. 
+- minimal: ONLY contains mathematical functions (so has limited dependencies). 
+- tutorial: ONLY contains mathematical functions and tutorial dependencies. 
+- maintainer: contains tools for building the documentation and building releases. 
+
+Each of the above installation options are available on PyPI. "Minimal" is also available on conda-forge. (In time, we intend to add more installation options to conda-forge.)
 
 ### 1. "All" Dependencies (excludes some maintainer-only packages)
 
 Use this for `scores` development and general use.
 
 Installs:
-* Mathematical API code and libraries
-* Everything needed to run the tutorial notebooks
-* Testing, static analysis and other developer libraries
-* Does **not** install tools for making packages and releasing new versions
+* Mathematical API code and libraries.
+* Everything needed to run the tutorial notebooks.
+* Testing, static analysis and other developer libraries.
+* Does **not** install tools for making packages and releasing new versions.
 
-#### From a Local Checkout of the Git Repository
+#### With pip
 
 ```bash
+# From a local checkout of the Git repository
 pip install -e .[all]
 ```
 
 ### 2. "Minimal" Dependencies (Mathematical API Functions Only)
 Use this to install the `scores` code into another package or system.
 
 Installs:
-* Mathematical API functions and libraries
+* Mathematical API functions and libraries.
 * Only the required core dependencies. Nothing extra - no tutorials, no developer requirements.
-* (Note for high-performance users - dask is not included by default in the minimal install, but will be used if installed into the environment)
+* (Note for high-performance users - dask is not included by default in the minimal install, but will be used if installed into the environment.)
 
 #### From PyPI
 
 ```bash
 pip install scores
 ```
+#### With conda
+
+```bash
+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.)
 
 ### 3. "Tutorial" Dependencies
 Use this for running tutorials using `scores`, but when you don't need or want developer tools.
 
 Installs:
-* Mathematical API functions and libraries
-* JupyterLab, Plotly, and libraries for reading data, so that the tutorial notebooks can be run
+* Mathematical API functions and libraries.
+* JupyterLab, Plotly, and libraries for reading data, so that the tutorial notebooks can be run.
 
-#### From a Local Git Repository
+#### With pip 
 
 ```bash
+# From a local checkout of the Git repository
 pip install .[tutorial]
 ```
 
 ### 4. "Maintainer" Dependencies
 Use this to build the docs, create packages and prepare new versions for release.
 
 Installs:
-* Mathematical API functions and libraries
-* Dependencies for building new versions of the `scores` package
-* Dependencies for building the documentation as HTML
+* Mathematical API functions and libraries.
+* Dependencies for building new versions of the `scores` package.
+* Dependencies for building the documentation as HTML.
 
-#### From a Local Git Repository
+#### With pip
 
 ```bash
+# From a local checkout of the Git repository
 pip install -e .[maintainer]
 ```