Overall Structure of YAML File

The yaml file can have the following top level keys

• geoms
• active_collections
• time_specs
• collections

Active collections list

All collections that you want to be written will be named under an active_collections list, for example, if you have collections named collection_1 and collection_2:

active_collections:
  - collection_1
  - collection_2

geoms

A one or more valid supported MAPL3 geometries can be specified here. These can be used to tell a collection an alternative geometry (such as another grid like a lat-lon or cubed sphere) other than the geometry of the component that produces the export to be written. WE RECOMMEND MAKING AND ANCHOR FOR EACH ENTRY Here are a few examples.

geoms:
   lat_lon_example:
       class: latlon
       im_world: 180
       jm_world: 91
       pole: PC
       dateline: DC

time_specs

The time_specs consists of a set of maps, each of which can be used in a collection to specify any temporal related information to use in the collection related to the frequency of output.

WE RECOMMEND MAKING AND ANCHOR FOR EACH ENTRY

Each map supports the following keywords

• frequency: this is the frequency of output as an ISO time internal
• ref_datetime: This is a ISO-like time template used to create the reference time (otherwise known as the first ring time) for the run alarm to control when the collection is written. See more details below. If not specified it defaults to 0z of any day, in other words, it would be 0z of the day your application started.

ref_datetime

This is an ISO-like time template that is used to create the reference time (or first ring time) for the alarm that in conjunction wit the frequency controls when a collection will write. It has the following form YYYY-MM-DDTHH:NN:SS and you substitute STARTING FROM THE RIGHT any values you want to use when the reference time is created. Any values not replaced are simply taken from the current time of the History clock when the application is started.

Let's go through a few examples that will hopefully make this clear.

Let's suppose you want output every 24 hours, relative to 21z. You would use the following for the ref_datetime YYYY-MM-DDT21:00:00. In others words you want the first ring time of the alarm to be on 21z of any day.

Now suppose you want a monthly average from the first of the month. The frequency would be P1M you want output once per calendar month. The ref_datetime would be YYYY-MM-01T00:00:00 so the alarm is relative to 0z of the first day of any month.

Finally suppose you wanted to do a DJF average and other 3 month periods such as MAM or JJA. You would set the frequency to P3M so 3 calendar months and the ref time to be YYYY-12-01T00:00:00, you want a starting time for the alarm to be December 1st at 0z of any year.

Note as was said above the default is YYYY-MM-DDT00:00:00 so by default the initial time for any collection is 0z of the day you start running the application.

collections

The collections section supports the following keywords

• template: this is a grads template. In addition we have added the a %c token which is the collection name
• geom: this is either a yaml map that defines the geometry or a reference to an anchor (see section on anchors)
• time_spec this is either a yaml map that specifies the time handling or a reference to an anchor (see section on anchors)
• var_list: The list of variables to be written, see section on the var_list

Use of Anchors in collections

We highly recommend using anchors for the geom and time_spec and using those. See the example at the end.

var_list

The var list consists of an entry for each item from a component you wish to write in the export. For each item you specify a map with the following format:

alias: {source: component_name.export_short_name}

The key is the alias you wish the variable to be named in the file. The expr is the expression you wish to write. If you just want a single variable you just put that variable. The variable follows the convention that you specify the short name, a dot, and the component_name

If you have a vector you do ...

Complete Example File

geoms:
  geom1: &geom1
    class: latlon
    im_world: 20
    jm_world: 15
    pole: PC
    dateline: DC

active_collections:
  - test

time_specs:
  three_hour: &six_hour
    frequency: PT6H
    ref_datetime: YYYY-MM-DDT21:00:00

collections:
  test:
    template: "%c_%y4%m2%d2_%h2%n2z.nc4"
    geom: *geom1
    time_spec: *six_hour
    var_list:
      QV: {source: Q.moist}