Merge pull request #44 from kthyng/fixes

Fixes

.github/workflows/test.yaml

@@ -23,7 +23,9 @@ jobs:
       - uses: conda-incubator/setup-miniconda@v2
         with:
           # mamba-version: "*" # activate this to build with mamba.
-          # channels: conda-forge, defaults # These need to be specified to use mamba
+          python-version: ${{ matrix.python-version }}
+          miniforge-variant: Mambaforge
+          channels: conda-forge, defaults # These need to be specified to use mamba
           channel-priority: true
           environment-file: ci/environment-py${{ matrix.python-version }}.yml
 

.gitignore

@@ -1,3 +1,4 @@
+_build
 __pycache__/
 .ipynb_checkpoints/
 .DS_Store

.pre-commit-config.yaml

@@ -51,7 +51,7 @@ repos:
   rev: v0.982
   hooks:
   - id: mypy
-    additional_dependencies: [types-setuptools, types-PyYAML]
+    additional_dependencies: [types-setuptools, types-PyYAML, types-requests]
     exclude: docs/source/conf.py
     args: [--ignore-missing-imports]
 

.readthedocs.yml

@@ -1,5 +1,9 @@
 version: 2
 
+# Build PDF only
+formats:
+  - pdf
+
 build:
   os: "ubuntu-20.04"
   tools:

README.md

@@ -12,24 +12,21 @@ ocean-model-skill-assessor
 
 A package to fully run the comparison between data and model to assess model skill.
 
---------
+You can run the analysis as a Python package or with a command-line interface.
 
-<p><small>Project based on the <a target="_blank" href="https://github.com/jbusecke/cookiecutter-science-project">cookiecutter science project template</a>.</small></p>
+There are three steps to follow for a set of model-data validation, which is for one variable:
+1. Make a catalog for your model output.
+2. Make a catalog for your data.
+3. Run the comparison.
 
+These steps will save files into a user application directory cache. See the demos for more details.
 
-## Installation
+--------
 
-### Install into existing environment
+<p><small>Project based on the <a target="_blank" href="https://github.com/jbusecke/cookiecutter-science-project">cookiecutter science project template</a>.</small></p>
 
-From `conda-forge`:
-``` base
-$ conda install -c conda-forge ocean-model-skill-assessor
-```
 
-From PyPI:
-``` base
-$ pip install ocean-model-skill-assessor
-```
+## Installation
 
 ### Set up environment
 
@@ -47,6 +44,32 @@ Activate your new Python environment to use it with
 $ conda activate omsa
 ```
 
+Also install `cartopy` to be able to plot maps:
+``` base
+$ conda install -c conda-forge cartopy
+```
+
+
+### Install into existing environment
+
+From `conda-forge`:
+``` base
+$ conda install -c conda-forge ocean-model-skill-assessor
+```
+
+From PyPI:
+``` base
+$ pip install ocean-model-skill-assessor
+```
+
+To plot a map of the model domain with data locations, you'll need to additionally install `cartopy`. If you used `conda` above:
+``` base
+$ conda install -c conda-forge cartopy
+```
+
+If you installed from PyPI, check out the instructions for installing `cartopy` [here](https://scitools.org.uk/cartopy/docs/latest/installing.html#building-from-source).
+
+
 ### Extra packages for development
 
 To also develop this package, install additional packages with:

docs/add_vocab.md

@@ -0,0 +1,139 @@
+---
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.14.4
+kernelspec:
+  display_name: Python 3.10.8 ('omsa')
+  language: python
+  name: python3
+---
+
+# How to make and work with vocabularies
+
+This page demonstrates the workflow of making a new vocabulary, saving it to the user application cache, and reading it back in to use it. The vocabulary created is the exact same as the "general" vocabulary that is saved with the OMSA package, though here it is given another name to demonstrate that you could be making any new vocabulary you want.
+
+Here is the list of variables of interest (with "nickname"), aimed at a physical oceanographer, which are built into the vocabulary:
+
+* water temperature "temp"
+* salinity "salt"
+* sea surface height "ssh"
+* u velocity "u"
+* v velocity "v"
+* w upward velocity "w"
+* direction of water velocity "water_dir"
+* magnitude of water velocity "water_speed"
+* wind direction "wind_dir"
+* wind speed "wind_speed"
+* sea ice velocity u "sea_ice_u"
+* sea ice velocity v "sea_ice_v"
+* sea ice area fraction "sea_ice_area_fraction"
+
+```{code-cell} ipython3
+import cf_pandas as cfp
+import ocean_model_skill_assessor as omsa
+import pandas as pd
+```
+
+## Vocabulary workflow
+
+### Make vocabulary
+
+Here we show making the "general" vocabulary that is saved into the repository. This is a more general vocabulary to identify variables from sources that don't use exact CF standard_names.
+
+```{code-cell} ipython3
+nickname = "temp"
+vocab = cfp.Vocab()
+
+# define a regular expression to represent your variable
+reg = cfp.Reg(include_or=["temp","sst"], exclude=["air","qc","status","atmospheric","bottom"])
+
+# Make an entry to add to your vocabulary
+vocab.make_entry(nickname, reg.pattern(), attr="name")
+
+vocab.make_entry("salt", cfp.Reg(include_or=["sal","sss"], exclude=["soil","qc","status","bottom"]).pattern(), attr="name")
+vocab.make_entry("ssh", cfp.Reg(include_or=["sea_surface_height","surface_elevation"], exclude=["qc","status"]).pattern(), attr="name")
+
+reg = cfp.Reg(include=["east", "vel"])
+vocab.make_entry("u", "u$", attr="name")
+vocab.make_entry("u", reg.pattern(), attr="name")
+
+reg = cfp.Reg(include=["north", "vel"])
+vocab.make_entry("v", "v$", attr="name")
+vocab.make_entry("v", reg.pattern(), attr="name")
+
+reg = cfp.Reg(include=["up", "vel"])
+vocab.make_entry("w", "w$", attr="name")
+vocab.make_entry("w", reg.pattern(), attr="name")
+
+vocab.make_entry("water_dir", cfp.Reg(include=["dir","water"], exclude=["qc","status","air","wind"]).pattern(), attr="name")
+
+vocab.make_entry("water_speed", cfp.Reg(include=["speed","water"], exclude=["qc","status","air","wind"]).pattern(), attr="name")
+
+vocab.make_entry("wind_dir", cfp.Reg(include=["dir","wind"], exclude=["qc","status","water"]).pattern(), attr="name")
+
+vocab.make_entry("wind_speed", cfp.Reg(include=["speed","wind"], exclude=["qc","status","water"]).pattern(), attr="name")
+
+reg1 = cfp.Reg(include=["sea","ice","u"], exclude=["qc","status"])
+reg2 = cfp.Reg(include=["sea","ice","x","vel"], exclude=["qc","status"])
+reg3 = cfp.Reg(include=["sea","ice","east","vel"], exclude=["qc","status"])
+vocab.make_entry("sea_ice_u", reg1.pattern(), attr="name")
+vocab.make_entry("sea_ice_u", reg2.pattern(), attr="name")
+vocab.make_entry("sea_ice_u", reg3.pattern(), attr="name")
+
+reg1 = cfp.Reg(include=["sea","ice","v"], exclude=["qc","status"])
+reg2 = cfp.Reg(include=["sea","ice","y","vel"], exclude=["qc","status"])
+reg3 = cfp.Reg(include=["sea","ice","north","vel"], exclude=["qc","status"])
+vocab.make_entry("sea_ice_v", reg1.pattern(), attr="name")
+vocab.make_entry("sea_ice_v", reg2.pattern(), attr="name")
+vocab.make_entry("sea_ice_v", reg3.pattern(), attr="name")
+
+vocab.make_entry("sea_ice_area_fraction", cfp.Reg(include=["sea","ice","area","fraction"], exclude=["qc","status"]).pattern(), attr="name")
+
+vocab
+```
+
+### Save it
+
+This exact vocabulary was previously saved as "general" and is available under that name, but this page demonstrates saving a new vocabulary and so we use the name "general2" to differentiate.
+
+```{code-cell} ipython3
+vocab.save(omsa.VOCAB_PATH("general2"))
+```
+
+```{code-cell} ipython3
+omsa.VOCAB_PATH("general2")
+```
+
+### Use it later
+
+Read the saved vocabulary back in to use it:
+
+```{code-cell} ipython3
+vocab = cfp.Vocab(omsa.VOCAB_PATH("general2"))
+
+df = pd.DataFrame(columns=["sst", "time", "lon", "lat"], data={"sst": [1,2,3]})
+with cfp.set_options(custom_criteria=vocab.vocab):
+    print(df.cf["temp"])
+```
+
+## Combine vocabularies
+
+A user can add together vocabularies. For example, here we combine the built-in "standard_names" and "general" vocabularies.
+
+```{code-cell} ipython3
+v1 = cfp.Vocab(omsa.VOCAB_PATH("standard_names"))
+v2 = cfp.Vocab(omsa.VOCAB_PATH("general"))
+
+v = v1 + v2
+v
+```
+
+## Using the `cf-pandas` widget
+
++++
+
+.. raw:: html
+   <iframe src="vocab_widget.html" height="500px" width="100%"></iframe>

docs/api.rst

@@ -10,6 +10,7 @@ API
 
    main
    utils
+   paths
    accessor
    stats
    plot.map