This component provides means of selecting data for output using small segments of script code. This primarily takes the form of specifying a condition where data is included in or excluded from the output.
Usage
da.where [switches…] [[station] variables times [archive]|[file]]
Switches
- --fanout-archive[=BOOLEAN]
-
If set then the condition is instantiated uniquely for each archive (excluding metadata).
Default: Enabled
- --fanout-flavors[=BOOLEAN]
-
If set then the condition is instantiated uniquely for each combination of flavors (e.x. PM1 vs PM10). This also automatically excludes information flavors like statistics.
Default: Enabled
- --fanout-station[=BOOLEAN]
-
If set then the condition is instantiated uniquely for each station (exclude the default, if any).
Default: Enabled
- --fanout-variable[=BOOLEAN]
-
If set then the condition is instantiated uniquely for variable.
- --include=SCRIPT
-
This sets the code executed at each data step. The test is evaluated as segments called 'data', so to test a variable the syntax results in code like: 'return data.BsG_S11 > 2.0'
- --inputs=SELECTION
-
This option sets the inputs used in the script condition.
Default: Everything
- --invert[=BOOLEAN]
-
Invert the condition and apply the effect when it is not met.
- --outputs=SELECTION
-
This option sets the data that is removed or undefined when the condition is met.
Default: Everything
- --undefine[=BOOLEAN]
-
When set values that fail the conditions are set to undefined instead of being removed from the data stream entirely.
Arguments
If no bare word input specification is supplied then data are read from standard input.
- station
-
This argument is used to specify the station used to look up variables that do not include a station as part of an archive read specification. The station is the three letter GAW station code of the location, such as
BND
. The argument accepts multiple stations specified as regular expressions and separated by:
or;
or,
. For exampleBND,MLO
and(BND|MLO)
are two ways of selecting both the BND and MLO stations.The special value
allstations
may also be specified to select all stations. - variables
-
This argument may be split into multiple actual program arguments. Each part consists of one or more variable specifications separated by
,
(commas). The station and archive used if none are explicitly given are defined in the other arguments or inferred from system defaults. For example simplyBsB_S11
selects the blue scattering from the S11 instrument and returns all cut sizes and metadata. If instead::BsB_S11:pm10
is used then only PM10 scattering is returned. That is, the selection specifies "any" station and archive (the defaults are set in the other arguments) then requires that it has the "PM10" flavor. A specification such asbnd:BsB_S11,thd:BsB_S11
allows for data selection from multiple stations.This may also be used to select a "record" type alias such as "S11a". In this mode all the variables defined in the alias are returned.
Finally the special value
everything
can be used to select all available data for the given station(s) and archive(s). - times
-
This argument may be split into multiple actual program arguments. This full list of time arguments defines a time bounds list that sets the range of data queried. The final resulting data are clipped to the given time bounds but any values that intersect them are returned.
- archive
-
This argument is used to specify the archive used to look up variables that do not include an archive as part of an archive read specification. The archive is the internal name, such as
raw
orclean_meta
. The argument accepts multiple archives specified as regular expressions and separated by:
or;
or,
. For exampleraw(_meta)?
selects both theraw
andraw_meta
archives.The special value
allarchives
may also be used to select all available archives. - file
-
This argument is used to specify the the file to read data from. If it is present and exists then data is read from the given file name instead of from standard input. Alternatively
-
(a single dash) may be used to explicitly specify standard input.
Examples
- Simple condition
-
This selects all data for which BsG_S11 is greater than 2.0 and is greater than BsR_S11. If either are not defined then no output is produced.
da.where --include='return data.BsG_S11 > 2.0 and data.BsG_S11 > data.BsR_S11' bnd S11a 2015-05-01 2015-05-03
Or:
da.where --include='return data.BsG_S11 > 2.0 and data.BsG_S11 > data.BsR_S11' input_file.c3d
Or:
da.get bnd S11a 2015-05-01 2015-05-03 | da.where --include='return data.BsG_S11 > 2.0 and data.BsG_S11 > data.BsR_S11'
- Zero multiple
-
This selects all data for which either BsG_S11 or BsR_S11 is exactly zero. If one is undefined but the other is zero then output is still produced.
da.where --include='return data.BsG_S11 == 0 or data.BsR_S11 == 0' bnd S11a 2015-05-01 2015-05-03
- Time condition
-
This excludes all data between UTC hour 8 and 12.
da.where --include='hour = (data.START % 86400) / 3600; return hour >= 8 and hour < 12' --invert bnd S11a 2015-05-01 2015-05-03