Differences

This shows you the differences between two versions of the page.

--- bufr.pm:bufrdump.pl_help [2010-02-02 15:19:34]
pals created
+++ bufr.pm:bufrdump.pl_help [2022-05-31 09:29:31] (current)
@@ Line 1: / Line 1: @@
 <code>
-Usage: /metno/local/bin/bufrdump.pl <bufr file(s)> [options]
+Usage:
+      bufrdump.pl <bufr file(s)>
+          [--filter <filter file | filter list>]
+          [--param <parameter file | parameter list> [--csv [--delimiter <del>]]
+          [--sort]
+          [--sort_on <parameter>[-]]
+          [--station <station list>]
+          [--transform <transformation file>]
+          [--lon1 <x1>]
+          [--lat1 <y1>]
+          [--lon2 <x2>]
+          [--lat2 <y2>]
+          [--obstype <amdar|ocea|surface|sounding|sounding->]
+          [--tablepath <path to BUFR tables>]
+          [--help]
-Will print section 4 in BUFR messages in <bufr file(s)> as "parameter=value" lines.
+Options:
+      --filter <filter file | filter list>
+                      Decode observations meeting criteria in filter file or
+                      filter list only
+      --param <parameter file | parameter list> [--csv [--delimiter <del>]]
+                      Print parameters in parameter file or comma
+                      separated list (e.g. wmonr,TA) only, in same order
+                      as they occur there. If using --csv possibly
+                      followed by --delimiter <del>, the parameters vill
+                      be printed using the CSV (comma-separated values)
+                      format, with the delimiter del (default is ';')
+      --sort          Sort the decoded observations on station identification;
+                      first stations with wmonr, then stations with nationalnr,
+                      call sign, buoy_id or aircraft (others left out)
+      --sort_on <parameter>[-] Sort the decoded observations on increasing
+                      values of parameter, or decreasing values if a '-'
+                      follows the parameter name. E.g. --sort_on TA- will
+                      sort on decreasing temperatures. Observations not
+                      containing the parameter at all will be printed lastly,
+                      except when --sort_on is combined with --sort (in which
+                      case sorting is done firstly on station identification,
+                      secondly on parameter with missing values printed first)
+      --station <station list>
+                      Print observations for stations in station list only,
+                      e.g. wmonr=01384,01492
+      --transform <transformation file>
+                      Do the transformations of parameter values listed in
+                      transformation file
+      --lon1 <x1>     Decode observations with longitude >= x1 only
+      --lat1 <y1>     Decode observations with latitude >= y1 only
+      --lon2 <x2>     Decode observations with longitude <= x2 only
+      --lat2 <y2>     Decode observations with latitude <= y2 only
+                      x1,y1,x2,y2 should be decimal degrees
+      --obstype <amdar|ocea|surface|sounding|sounding->]
+                      Force observation type. If this option is not set,
+                      will make an educated guess of observation type
+                      based on metadata in section 1 of each BUFR message
+      --tablepath <path to BUFR tables>
+                      Set path to BUFR tables (overrides ENV{BUFR_TABLES})
+      --help          Print this Usage (but you might instead prefer to use
+                      perldoc bufrdump.pl)
-Options (may be abbreviated, e.g. --h for --help) are:
+    Options may be abbreviated, e.g. --h or -h for --help.
-        --filter <filter file>
+    To avoid having to use the "--tablepath" option, you are adviced to set
-                        Decode observations meeting criteria in <filter file> only
+    the environment variable BUFR_TABLES to the directory where your BUFR
-        --param <parameter file>
+    tables are located (unless the default path provided by bufrdump.pl
-                        Print parameters in <parameter file> only, in same order
+    works for you).
-                        as they occur in <parameter file>
-        --lon1 x1       Decode observations with longitude >= x1 only
-        --lat1 y1       Decode observations with latitude >= y1 only
-        --lon2 x2       Decode observations with longitude <= x2 only
-        --lat2 y2       Decode observations with latitude <= y2 only
-                        x1,y1,x2,y2 should be decimal degrees
-        --tablepath <path to BUFR tables>
-                        Set path to BUFR tables (overrides ENV{BUFR_TABLES})
-        --help          Print this Usage
+    The lines in <parameter file>, or the comma separated values in
+    <parameter list>, should be name of the parameters you want to be
+    printed. For example, if you want only station identification and
+    temperature to be printed for a BUFR SYNOP file, either supply
-You should probably set
+      wmonr,nationalnr,call_sign,TA
-        export BUFR_TABLES=/usr/local/lib/bufrtables
-or use the --tablepath option.
-The lines in <parameter file> should be name of the parameters you
+    as argument to --params, or supply a <parameter file> which should look
-want to be printed. For example, if you want only station
+    like this:
-identification and temperature to be printed for a BUFR SYNOP file,
-the <parameter file> should look like this:
-wmonr
+      wmonr
-DDDD
+      nationalnr
-TA
+      call_sign
+      TA
-If you want "parameter=value" to be printed also when value is missing
+    If you want "parameter=value" to be printed also when value is missing
-in BUFR message, precede the parameter name with an exclamation mark
+    in BUFR message, precede the parameter name with an exclamation mark
-(e.g. '!TA').  Missing values will then be displayed as -32767.
+    (e.g. '!TA'). Missing values will then be displayed as -32767. If the
+    argument to --param is a parameter list, you must prevent the shell from
+    attaching special meaning to the exclamation mark by enclosing the list
+    in single quotes.
-Using --filter will decode only those observations that meet at least
+    If the parameter list consists of one parameter only, a comma must be
-one of the BUFR descriptor criteria and all of the parameter criteria
+    appended (e.g. 'wmonr,') because bufrdump.pl uses the appearence of
-in <filter file>, where the BUFR descriptor criteria should come first
+    comma to signal that this is not a filename but parameter name(s).
-in filter file followed by a blank line, then comes the parameter
-criteria which should match <param> <operator> <value> where operator
-is one of =, !=, <, <=, > and >=. An example filter file is
-D: 001001 I2.2
+    If --csv is used in conjunction with --param, all values will be printed
+    using the CSV format, with first line listing the parameters, and with
-D: 001001 I2.2 001002 I3.3
+    missing fields printed as -32767 if the parameter is marked with '!' in
-895
+    parameter file or list. With the parameter file above, the listing may
-252
+    for example start like
-D: 001011 A9
-LDWR
-NN != 0
+      wmonr;nationalnr;call_sign;TA
-TA >= 5
+;;;-1.5
-TA < 9.5
+      ;;LF5U;9.0
+    You can choose another delimiter than semicolon by use of option
+    --delimiter <del>, e.g. --csv --delimiter ','
+    Using --filter will decode only those observations that meet at least
+    one of the BUFR descriptor criteria and all of the parameter criteria in
+    <filter file>, where the BUFR descriptor criteria should come first in
+    filter file followed by a blank line, then comes the parameter criteria
+    which should match <param> or !<param> or <param> <operator> <value>
+    where operator is one of =, !=, =~, !~, <, <=, > and >=. What follows =~
+    and !~ should be a Perl match regular expression. The parameter criteria
+    may be phrased as alternatives by separating them with '|' on a single
+    line. An example filter file is
+      D: 001001 I2.2
+
+      D: 001001 I2.2 001002 I3.3
+895
+252
+      D: 001011 A9
+      LF5U
+      type = Manned
+      NN != 8
+      TA >= 5
+      TA < 9.5
+      RR_24
+    which decodes all observations with block number 01, two other specific
+    wmo stations and one specific ship, where stations should be manned and
+    have cloud cover with a value different from 8, and have temperature
+    between 5 and 9.5 degrees Celsius, and contain precipitation for last 24
+    hours. Comment lines starting with # will be ignored.
+    Another example: the filter file (starting with a blank line!)
+      call_sign =~ /^L[A-N]..$/
+      obstime >= '2012-02-10 06:00:00'
+      HW | HWA | PW | PWA
+      FF > 10 | FG_010 > 10
+    will print only those ship observations for which the 4 character
+    call_sign starts with 2 letters in the interval LA-LN, and having
+    obstime larger or equal to the datetime given, and containing wave data
+    (specifically: height or period of waves, manually or automatically
+    measured), and with wind or 10 minutes gust more than 10 m/s.
+    For convenience, when there are no BUFR descriptor criteria, you might
+    provide the filter criteria on the command line. Example:
+    --filter 'wmonr,TA > 0,RR_12 | RR_24, !FF'
+    will decode only observations with wmonr, having positive temperature
+    and containing precipitation for 12 or 24 hours and not reporting wind.
+    If (like for --param) the filter list consists of one criterium only, a
+    comma must be appended.
+    To avoid the need of creating a filter file when observations for some
+    few stations are requested, you can provide the stations in a comma
+    separated list after option --station. Some examples:
+      --station wmonr=01001,01152,01492
+      --station nationalnr=614_0050410003,637_108
+      --station call_sign=LF5U
+      --station buoyid=64607,64609
+      --station aircraft=EU3421,JHCWUURA
+    You cannot mix different kinds of stations this way (before '=' you must
+    choose either wmonr, nationalnr, call_sign, buoy_id or aircraft). Note
+    also that providing the stations in the BUFR descriptor part (first
+    part) of the filter file will speed up execution time considerably,
+    compared to using option --station. It is possible to combine --filter
+    with --station if done with some care, e.g. specifying WMO block 01 and
+    the required parameters in filter file, then the requested stations in
+    station list.
+    The --transform option is provided mainly to be able to use other units
+    than what is default in bufrdump.pl. The transformation file should list
+    the transformations wanted, one per line as
+      <parameter> = <perl expression involving $x>
+    where $x is original value of the parameter.
+    For example, the following transformation file will display wind speed
+    FF and wind gust FG in knots instead of m/s, rounded to one decimal, and
+    cloud cover NN in % (instead of the default which is using WMO code
+    table 2700, roughly counting octas):
+      FF = sprintf("%.1f", $x*1.9438)
+      FG = sprintf("%.1f", $x*1.9438)
+      NN = int($x*12.5 + .5)
+    If --transform is combined with --filter, the filter criteria should
+    refer to the transformed values. E.g. if the above NN transform to % is
+    to be applied for sky not all covered by clouds, you should use NN !=
+instead of NN != 8 in filter file.
+    The --obstype option might be handy in some special cases, like when you
+    are interested only in the surface part of oceanographic data (then use
+    '--obstype surface'), or when you want to see only levels with vss>0 in
+    high resolution radiosonde data (then use '--obstype sounding-'), or
+    when data category and/or data sub-category in the BUFR messages have
+    unusual values.
-which decodes all observations with block number 01, two other
-specific wmo stations and one specific ship, having cloud cover
-different from 0 (but NN must be part of the message) and temperature
-between 5 and 9.5 degrees Celsius. Comment lines starting with #
-will be ignored.
 </code>