plots.conf

The configuration file used by data.plots.update. It is located in $DB/etc/$STATION/plots.$STATION.conf or in the default location $DB/etc/plots.conf. The default one is loaded first, then the station specific one on top of it. This causes any archive definitions from the default one to be overwritten if they exist in the station specific one, but global keys to be directly overlaid.

See also CPX2. Plots are configured with CPX2 XML files in a specific location (see below).

Lines beginning with '#' are treated as comments. The format consists of a CSV separated list of key and optional value pairs. Keys are case insensitive. There are several block types. When a plot is being generated the lookups start at the innermost block and work outward.

In all string valued keys the string “${STATION}” will be replaced with the lower case station code.

These keys are valid in any block scope except the innermost graph or tab, the innermost one with respect to a plot is used.

• SizeX - The horizontal size of the output in pixels.
• SizeY - The vertical size of the output in pixels.
• Start - The start time for absolute plot intervals. Any convertible time format is accepted. Before parsing the string “${END}” is replaced with the epoch time of the end.
• Source - The source archive to get data from, passed to cpx2 with the –source switch.
• CPX2Config - The configuration file base (see below) to get the plot definitions from.
• CPX2Average - The value of the --dbavg switch passed to CPX2.
• CPX2Contam - If “true” passes --contam to CPX2, which makes it included contaminated data even in edited sourced data.
• OutputDirectory - Base output directory to place output in. May be specified multiple times to mirror the output.
• Annotate and NoAnnotate - Enable or disable the generation time and time spanned annotation generation.
• Graphs - A list of graph names (references into the CPX2 XML file) to generate additionally.
• Tabs - A list of tab names (references into the CPX2 XML file) to generate additionally.
• NoGraphs - Clear the graph list.
• NoTab - Clear the tab list.

The outermost scope. All global keys are valid in addition to the following:

• Graph - Begins a graph block scope. The first field is the graph name (references into the CPX2 XML file).
• Tab - Begins a tab block scope. The first field is the tab name (references into the CPX2 XML file).
• Archive - Begins an archive block scope. Replaces any existing definition for that archive. The first field is the archive type, one of “raw”, “rawnrt”, “clean” or “avgH”.

Defines a graph or tab in more detail, the following keys are valid:

• End - End the scope.
• SizeX - The horizontal size of the output in pixels.
• SizeY - The vertical size of the output in pixels.
• Annotate and NoAnnotate - Enable or disable the generation time and time spanned annotation generation.
• OutputName - The output name for the graph, defaults to the graph name.

Defines the sets of plots to be generated when an archive is updated. All global keys are valid in addition to the following:

• End - End the scope.
• Graph - Begins a graph block scope. The first field is the graph name (references into the CPX2 XML file).
• Tab - Begins a tab block scope. The first field is the tab name (references into the CPX2 XML file).
• Set - Begins a scope for a set of graphs. The first field is the interval type, and any additional ones are arguments for it. See below

Valid set interval types are:

• Yearly - Generate plots up to the end of the most recent complete year. Optionally takes a current extend argument (see below).
• Monthly - Generate plots up to the end of the most recent complete month. Optionally takes a current extend argument (see below).
• Weekly - Generate plots up to the end of the most recent complete week. Optionally takes a current extend argument (see below).
• Daily - Generate plots up to the end of the most recent complete day. Optionally takes a current extend argument (see below).
• Hourly - Generate plots up to the end of the most recent complete hour. Optionally takes a current extend argument (see below).
• ByMinute - Generate plots up to the end of the most recent complete minute. Optionally takes a current extend argument (see below).
• BySecond - Generate plots up to the end of the most recent complete second. Optionally takes a current extend argument (see below).
• Latest - Generate plots for the latest amount of time for some specified interval. The second argument is the interval (see below for specification). For example, specifying “24h” would cause data to be plotted for the latest (unaligned) 24 hours available, updated as it comes in.
• Prior - Generate plots aligned to the latest complete interval. The second argument is the interval (see below for specification). For example, specifying “24h” would cause plots to be updated generated on the day boundary for the latest complete day. The second (optional) argument is the generation interval, defaulting to the interval. Specifying an interval of “6h” and a generation interval of “24h” would make plots aligned to six hours spanning 24 hours, updated as six hour blocks complete.

Time interval specifications may be either of the form “[[hours:]minutes:]seconds” or a number followed by a multiplier character. The multiplier is one of “d” for days, “h” for hours, “m” for minutes. So one hour can be specified by any of “01:00:00”, “1h”, “60m” or “3600”.

Then entire archive update interval specifications optionally take an argument that extends the “current” time passed to CPX2 (see below). The “update” time remains the start of the latest complete interval, while the current time is moved backwards by the amount specified. The specification is one of the following:

• “Ny” or “N years” - Move the time backwards the integer N years.
• “Nmon” or “N months” - Move the time backwards the integer N months.
• “Nweek” or “N weeks” - Move the time backwards the integer N weeks (re-aligning if needed).
• “Nd” or “N days” - Move the time backwards the integer N days.
• “Nh” or “N hours” - Move the time backwards the integer N hours.
• “Nm” or “N seconds” - Move the time backwards the integer N seconds.
• [[hours:]minutes:]second - Move the time backwards by exactly the given amount.

For example, to create a set of plots updated on each complete month, that includes the last 12 months in the “current” time, the specification would be “Montly,11 months”.

Defines a set of plots to be generated with one call to CPX2. All global keys are valid in addition to the following:

• End - End the scope.
• Graph - Begins a graph block scope. The first field is the graph name (references into the CPX2 XML file).
• Tab - Begins a tab block scope. The first field is the tab name (references into the CPX2 XML file).

Each set of plots requires a corresponding CPX2 configuration file. The set (or some enclosing scope) specifies a CPX2Config value, which corresponds to the base name of the file used. If the file $DB/etc/$STATION/plots/$BASE.$STATION.xml exists it is used, otherwise the file $DB/etc/plots/$BASE.xml is. If neither exists, then no plots for that set can be generated.

Within the file the internal names of graphs and/or tabs are used to lookup them for generation. So a graph with an internal name (“name=…”) tag will be references by that name for generation purposes. The output file name may be specified as above with a graph block otherwise it defaults to the internal name. If the output name does not end in “.png” is it appended.

Before calling CPX2, data.plots.update will set some environment variables that relate to the generation interval that the call reflects. It sets UPDATE_START to be equal to the epoch time of the start of the “update” interval. This is generally the very latest interval of completion that triggered the call. CURRENT_START is set to the epoch time of the start of the “current” interval. This is the time this update considers to be “current” data. The two may be equal if the call does not distinguish or they may be undefined if the call does not have a notion of the interval.