import ocean_model_skill_assessor as omsa
import cf_pandas as cfp
import xroms

How to use ocean-model-skill-assessor

… as a Python package. Other notebooks describe its command line interface uses.

But, this is written in parallel to the CLI demo, but will be more brief.

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, along with a log. A project directory can be checked on the command line with omsa proj_path --project_name PROJECT_NAME.

project_name = "demo_local_package"

Make model catalog

We’re using example ROMS model output that is available through xroms for our model.

url = xroms.datasets.CLOVER.fetch("ROMS_example_full_grid.nc")
kwargs = {
    "filenames": [url],
    "skip_entry_metadata": True,
}
cat_model = omsa.main.make_catalog(
                        catalog_type="local",
                        project_name=project_name,
                        catalog_name="model",
                        kwargs=kwargs,
                        return_cat=True,
)

Downloading file 'ROMS_example_full_grid.nc' from 'https://github.com/xoceanmodel/xroms/raw/main/xroms/data/ROMS_example_full_grid.nc' to '/home/docs/.cache/xroms'.

cat_model

model:
  args:
    description: Catalog of type local.
    name: model
  description: Catalog of type local.
  driver: intake.catalog.base.Catalog
  metadata: {}

Make data catalog

Set up a catalog of the datasets with which you want to compare your model output. In this example, we use only known data file locations to create our catalog.

Note that we need to include the “featuretype” and “maptype” in the metadata for the data sources. More information can be found on these items in the docs.

filenames = ["https://erddap.sensors.axds.co/erddap/tabledap/gov_ornl_cdiac_coastalms_88w_30n.csvp?time%2Clatitude%2Clongitude%2Cz%2Csea_water_temperature&time%3E=2009-11-19T012%3A00%3A00Z&time%3C=2009-11-19T16%3A00%3A00Z",]

cat_data = omsa.make_catalog(project_name="demo_local_package",
                             catalog_type="local",
                             catalog_name="local",
                             kwargs=dict(filenames=filenames),
                             metadata={"featuretype": "timeSeries", "maptype": "point"})

---------------------------------------------------------------------------
AttributeError                            Traceback (most recent call last)
Cell In[5], line 3
      1 filenames = ["https://erddap.sensors.axds.co/erddap/tabledap/gov_ornl_cdiac_coastalms_88w_30n.csvp?time%2Clatitude%2Clongitude%2Cz%2Csea_water_temperature&time%3E=2009-11-19T012%3A00%3A00Z&time%3C=2009-11-19T16%3A00%3A00Z",]
----> 3 cat_data = omsa.make_catalog(project_name="demo_local_package",
      4                              catalog_type="local",
      5                              catalog_name="local",
      6                              kwargs=dict(filenames=filenames),
      7                              metadata={"featuretype": "timeSeries", "maptype": "point"})

File ~/checkouts/readthedocs.org/user_builds/ocean-model-skill-assessor/checkouts/stable/ocean_model_skill_assessor/main.py:372, in make_catalog(catalog_type, project_name, catalog_name, description, metadata, kwargs, kwargs_search, kwargs_open, skip_strings, vocab, return_cat, save_cat, verbose, mode, testing, cache_dir)
    370     filenames = kwargs["filenames"]
    371     kwargs.pop("filenames")
--> 372     cat = make_local_catalog(
    373         astype(filenames, list),
    374         name=catalog_name,
    375         description=description,
    376         metadata=metadata,
    377         kwargs_open=kwargs_open,
    378         skip_strings=skip_strings,
    379         logger=logger,
    380         **kwargs,
    381     )
    383 elif catalog_type == "erddap":
    384     catalog_name = "erddap_cat" if catalog_name is None else catalog_name

File ~/checkouts/readthedocs.org/user_builds/ocean-model-skill-assessor/checkouts/stable/ocean_model_skill_assessor/main.py:162, in make_local_catalog(filenames, filetype, name, description, metadata, metadata_catalog, skip_entry_metadata, skip_strings, kwargs_open, logger)
    159     sources.append(source)
    161 # create dictionary of catalog entries
--> 162 entries = {
    163     PurePath(source.urlpath).stem: LocalCatalogEntry(
    164         name=PurePath(source.urlpath).stem,
    165         description=source.description if source.description is not None else "",
    166         driver=source._yaml()["sources"][source.name]["driver"],
    167         args=source._yaml()["sources"][source.name]["args"],
    168         metadata=source.metadata,
    169         direct_access="allow",
    170     )
    171     for i, source in enumerate(sources)
    172 }
    174 # create catalog
    175 cat = Catalog.from_dict(
    176     entries,
    177     name=name,
    178     description=description,
    179     metadata=metadata_catalog,
    180 )

File ~/checkouts/readthedocs.org/user_builds/ocean-model-skill-assessor/checkouts/stable/ocean_model_skill_assessor/main.py:163, in <dictcomp>(.0)
    159     sources.append(source)
    161 # create dictionary of catalog entries
    162 entries = {
--> 163     PurePath(source.urlpath).stem: LocalCatalogEntry(
    164         name=PurePath(source.urlpath).stem,
    165         description=source.description if source.description is not None else "",
    166         driver=source._yaml()["sources"][source.name]["driver"],
    167         args=source._yaml()["sources"][source.name]["args"],
    168         metadata=source.metadata,
    169         direct_access="allow",
    170     )
    171     for i, source in enumerate(sources)
    172 }
    174 # create catalog
    175 cat = Catalog.from_dict(
    176     entries,
    177     name=name,
    178     description=description,
    179     metadata=metadata_catalog,
    180 )

AttributeError: 'CSVSource' object has no attribute 'urlpath'

cat_data

Run comparison

Now that the model output and dataset catalogs are prepared, we can run the comparison of the two.

At this point we need to select a single variable to compare between the model and datasets, and this requires a little extra input. Because we don’t know specifics about the format of any given input data file, variables will be interpreted with some flexibility in the form of a set of regular expressions. In the present case, we will compare the water temperature between the model and the datasets (the model output and datasets selected for our catalogs should contain the variable we want to compare). Several sets of regular expressions, called “vocabularies”, are available with the package to be used for this purpose, and in this case we will use one called “general” which should match many commonly-used variable names. “general” is selected under vocab_names, and the particular key from the general vocabulary that we are comparing is selected with key.

See the vocabulary here.

paths = omsa.paths.Paths()
cfp.Vocab(paths.VOCAB_PATH("general"))

Now we run the model-data comparison. Check the API docs for details about the keyword inputs. Also note that the data has filler numbers for this time period which is why the comparison is so far off.

omsa.run(project_name="demo_local_package", catalogs=cat_data, model_name=cat_model,
         vocabs="general", key_variable="temp", interpolate_horizontal=False,
         check_in_boundary=False, plot_map=True, dd=5, alpha=20)

The plots show the time series comparisons for sea water temperatures of the model output and data at one location. Also shown is a map of the Mississippi river delta region where the model is located. An approximation of the numerical domain is shown along with the data location. Note that the comparison is poor because the data is missing for this time period.