Customizing your installation with the ‘local’ site

About the ‘local’ site

The --site command-line flag is used to implement plug-in functionality for site-specific code, (eg, enabling data search from a lab’s internally-accessible filesystem.) The default value for this flag is local: code and configuration files placed in the sites/local/ directory will be used to customize the general-purpose framework code in src/.

The most important use case for this functionality is allowing you to set default values for command-line flags, as described in the next section. This lets you set configuration options that are the same for each run (e.g., <OBS_DATA_ROOT>, the path to your local copy of the observational data used by the diagnostics) once, in a file in this directory, without having to remember to include the corresponding command-line flag every time you run the package.

This function only sets default values: any value may be overridden for any run of the package by specifying it explicitly on the command line (or in an input file). Regardless of where they originate, the complete list of configuration settings used in a run of the package is saved in the output, so you can always recreate a run of the package even if you change these defaults.

The full API for the --site functionality, as well as instructions on how to develop your own site-specific data sources and other code plug-ins, will be documented in an upcoming release.

How to set default values

When run, the framework looks for a file named defaults.jsonc in the directory for the chosen site. An example of the format for this file is provided in src/default_tests.jsonc, which we encourage you to make a copy of, rename, and edit.

More specifically, the defaults.jsonc file should be a JSON file (with //-comments allowed) listing <key>:<value> pairs. The <key> should be the long name of one of the command-line flags, with hyphens replaced by underscores. The <value> should be the desired default value. <key>s which don’t correspond to recognized command-line flags, such as the caselist in src/default_tests.jsonc, are ignored.

You can test the settings in your defaults.jsonc file by running % mdtf --help. The beginning of the help text will list the path to the default settings files being used, and the help text for each command-line flag will note its default value.

Switching between multiple defaults with multiple sites

A site is simply a subdirectory of the sites/ directory. You can manage and easily switch between multiple sets of default values by creating additional subdirectories within sites/, along with a defaults.jsonc file for each, and selecting one at runtime with the --site flag.

This can be useful if you frequently need to analyze data from a variety of different data sources: you can create one site per data source, and add the settings specifying the desired data set from that source at runtime.