6. POD settings file summary¶

This page gives a quick introduction to how to write the settings file for your POD. See the full documentation on this file format for a complete list of all the options you can specify.

6.1. Overview¶

The MDTF framework can be viewed as a “wrapper” for your code that handles data fetching and munging. Your code communicates with this wrapper in two ways:

The settings file is where your code talks to the framework: when you write your code, you document what model data your code uses and what format it expects it in. When the framework is run, it will fulfill the requests you make here (or tell the user what went wrong).
When your code is run, the framework talks to it by setting environment variables containing paths to the data files and other information specific to the run.

In the settings file, you specify what model data your diagnostic uses in a vocabulary you’re already familiar with:

The CF conventions for standardized variable names and units.
The netCDF4 (classic) data model, in particular the notions of variables and dimensions as they’re used in a netCDF file.

6.2. Example¶

// Any text to the right of a '//' is a comment
{
  "settings" : {
    "long_name": "My example diagnostic",
    "driver": "example_diagnostic.py",
    "realm": "atmos",
    "runtime_requirements": {
      "python": ["numpy", "matplotlib", "netCDF4"]
    }
  },
  "data" : {
    "frequency": "day"
  },
  "dimensions": {
    "lat": {
      "standard_name": "latitude"
    },
    "lon": {
      "standard_name": "longitude"
    },
    "plev": {
      "standard_name": "air_pressure",
      "units": "hPa",
      "positive": "down"
    },
    "time": {
      "standard_name": "time",
      "units": "day"
    }
  },
  "varlist" : {
    "my_precip_data": {
      "standard_name": "precipitation_flux",
      "path_variable": "PATH_TO_PR_FILE",
      "units": "kg m-2 s-1",
      "dimensions" : ["time", "lat", "lon"]
    },
    "my_3d_u_data": {
      "standard_name": "eastward_wind",
      "path_variable": "PATH_TO_UA_FILE",
      "units": "m s-1",
      "dimensions" : ["time", "plev", "lat", "lon"]
    }
  }
}

6.3. Settings section¶

This is where you describe your diagnostic and list the programs it needs to run.

long_name:

Display name of your diagnostic, used to describe your diagnostic on the top-level index.html page. Can contain spaces.

driver:

Filename of the driver script the framework should call to run your diagnostic.

realm:

One or more of the eight CMIP6 modeling realms (aerosol, atmos, atmosChem, land, landIce, ocean, ocnBgchem, seaIce) describing what data your diagnostic uses. This is give the user an easy way to, eg, run only ocean diagnostics on data from an ocean model.

runtime_requirements:

This is a list of key-value pairs describing the programs your diagnostic needs to run, and any third-party libraries used by those programs.

The key is program’s name, eg. languages such as “python” or “ncl” etc. but also any utilities such as “ncks”, “cdo”, etc.
The value for each program is a list of third-party libraries in that language that your diagnostic needs. You do not need to list built-in libraries: eg, in python, you should to list numpy but not math. If no third-party libraries are needed, the value should be an empty list.

6.4. Data section¶

This section contains settings that apply to all the data your diagnostic uses. Most of them are optional.

frequency:: The time frequency the model data should be provided at, eg. “1hr”, “6hr”, “day”, “mon”, …

6.5. Dimensions section¶

This section is where you list the dimensions (coordinate axes) your variables are provided on. Each entry should be a key-value pair, where the key is the name your diagnostic uses for that dimension internally, and the value is a list of settings describing that dimension. In order to be unambiguous, all dimensions must specify at least:

standard_name:: The CF standard name for that coordinate.
units:: The units the diagnostic expects that coordinate to be in (using the syntax of the UDUnits library). This is optional: if not given, the framework will assume you want CF convention canonical units.

In addition, any vertical (Z axis) dimension must specify:

positive:: Either "up" or "down", according to the CF conventions. A pressure axis is always "down" (increasing values are closer to the center of the earth).

6.6. Varlist section¶

This section is where you list the variables your diagnostic uses. Each entry should be a key-value pair, where the key is the name your diagnostic uses for that variable internally, and the value is a list of settings describing that variable. Most settings here are optional, but the main ones are:

standard_name:: The CF standard name for that variable.
path_variable:: Name of the shell environment variable the framework will use to pass the location of the file containing this variable to your diagnostic when it’s run. See the environment variable documentation for details.
units:: The units the diagnostic expects the variable to be in (using the syntax of the UDUnits library). This is optional: if not given, the framework will assume you want CF convention canonical units.
dimensions:: List of names of dimensions specified in the “dimensions” section, to specify the coordinate dependence of each variable.
modifier (optional):: Descriptor to distinguish variables with identical standard names and different dimensionalities or realms. See modifiers.jsonc for supported modfiers. Open an issue to request the addition of a new modifier to the modifiers.jsonc file, or submit a pull request that includes the new modifier in the modifiers.jsonc file and the necessary POD settings.jsonc file(s).