Next: ncbo netCDF Binary Operator, Previous: ncap2 netCDF Arithmetic Processor, Up: Operator Reference Manual
ncatted [-a att_dsc] [-a ...] [-D dbg] [-h] [--hdr_pad nbr] [-l path] [-O] [-o output-file] [-p path] [-R] [-r] input-file [[output-file]]
DESCRIPTION
ncatted edits attributes in a netCDF file.
If you are editing attributes then you are spending too much time in the
world of metadata, and ncatted was written to get you back out as
quickly and painlessly as possible.
ncatted can append, create, delete,
modify, and overwrite attributes (all explained below).
Furthermore, ncatted allows each editing operation to be applied
to every variable in a file.
This saves time when changing attribute conventions throughout a file.
Note that ncatted interprets character attributes
(i.e., attributes of type NC_CHAR
) as strings.
Because repeated use of ncatted can considerably increase the size
of the history
global attribute (see History Attribute), the
‘-h’ switch is provided to override automatically appending the
command to the history
global attribute in the output-file.
When ncatted is used to change the _FillValue
attribute,
it changes the associated missing data self-consistently.
If the internal floating point representation of a missing value,
e.g., 1.0e36, differs between two machines then netCDF files produced
on those machines will have incompatible missing values.
This allows ncatted to change the missing values in files from
different machines to a single value so that the files may then be
concatenated together, e.g., by ncrcat, without losing any
information.
See Missing Values, for more information.
The key to mastering ncatted is understanding the meaning of
the structure that describes the attribute modification, att_dsc
specified by the required option ‘-a’ or ‘--attribute’.
Each att_dsc contains five elements, which makes using
ncatted somewhat complicated, but powerful.
The att_dsc argument structure contains five arguments in the
following order:
att_dsc = att_nm, var_nm, mode, att_type,
att_val
units
pressure
, '^H2O'
.
a
.
See below for complete listing of valid values of mode.
c
.
See below for complete listing of valid values of att_type.
pascal
.
The value of att_nm is the name of the attribute you want to edit. This meaning of this should be clear to all users of the ncatted operator. If att_nm is omitted (i.e., left blank) and Delete mode is selected, then all attributes associated with the specified variable will be deleted.
The value of var_nm is the name of the variable containing the attribute (named att_nm) that you want to edit. There are three very important and useful exceptions to this rule. The value of var_nm can also be used to direct ncatted to edit global attributes, or to repeat the editing operation for every variable in a file. A value of var_nm of “global” indicates that att_nm refers to a global attribute, rather than a particular variable's attribute. This is the method ncatted supports for editing global attributes. If var_nm is left blank, on the other hand, then ncatted attempts to perform the editing operation on every variable in the file. This option may be convenient to use if you decide to change the conventions you use for describing the data. Finally, as mentioned above, var_nm may be specified as a regular expression.
The value of mode is a single character abbreviation (a
,
c
, d
, m
, or o
) standing for one of
five editing modes:
a
c
d
m
o
The value of att_type is a single character abbreviation
(f
, d
, l
, i
, s
, c
,
b
, u
) or a short string standing for one of the twelve
primitive netCDF data types:
f
NC_FLOAT
.
d
NC_DOUBLE
.
i, l
NC_INT
.
s
NC_SHORT
.
c
NC_CHAR
.
b
NC_BYTE
.
ub
NC_UBYTE
.
us
NC_USHORT
.
u, ui, ul
NC_UINT
.
ll, int64
NC_INT64
.
ull, uint64
NC_UINT64
.
sng
NC_STRING
.
The value of att_val is what you want to change attribute
att_nm to contain.
The specification of att_val is optional in Delete (and is
ignored) mode.
Attribute values for all types besides NC_CHAR
must have an
attribute length of at least one.
Thus att_val may be a single value or one-dimensional array of
elements of type att_type
.
If the att_val is not set or is set to empty space,
and the att_type is NC_CHAR
, e.g., -a units,T,o,c,""
or -a units,T,o,c,
, then the corresponding attribute is set to
have zero length.
When specifying an array of values, it is safest to enclose
att_val in single or double quotes, e.g.,
-a levels,T,o,s,"1,2,3,4"
or
-a levels,T,o,s,'1,2,3,4'
.
The quotes are strictly unnecessary around att_val except
when att_val contains characters which would confuse the calling
shell, such as spaces, commas, and wildcard characters.
NCO processing of NC_CHAR
attributes is a bit like Perl in
that it attempts to do what you want by default (but this sometimes
causes unexpected results if you want unusual data storage).
If the att_type is NC_CHAR
then the argument is interpreted as a
string and it may contain C-language escape sequences, e.g., \n
,
which NCO will interpret before writing anything to disk.
NCO translates valid escape sequences and stores the
appropriate ASCII code instead.
Since two byte escape sequences, e.g., \n
, represent one-byte
ASCII codes, e.g., ASCII 10 (decimal), the stored
string attribute is one byte shorter than the input string length for
each embedded escape sequence.
The most frequently used C-language escape sequences are \n
(for
linefeed) and \t
(for horizontal tab).
These sequences in particular allow convenient editing of formatted text
attributes.
The other valid ASCII codes are \a
, \b
, \f
,
\r
, \v
, and \\
.
See ncks netCDF Kitchen Sink, for more examples of string formatting
(with the ncks ‘-s’ option) with special characters.
Analogous to printf
, other special characters are also allowed by
ncatted if they are "protected" by a backslash.
The characters "
, '
, ?
, and \
may be
input to the shell as \"
, \'
, \?
, and \\
.
NCO simply strips away the leading backslash from these
characters before editing the attribute.
No other characters require protection by a backslash.
Backslashes which precede any other character (e.g., 3
, m
,
$
, |
, &
, @
, %
, {
, and
}
) will not be filtered and will be included in the attribute.
Note that the NUL character \0
which terminates C language
strings is assumed and need not be explicitly specified.
If \0
is input, it is translated to the NUL character.
However, this will make the subsequent portion of the string, if any,
invisible to C standard library string functions.
And that may cause unintended consequences.
Because of these context-sensitive rules, one must use ncatted
with care in order to store data, rather than text strings, in an
attribute of type NC_CHAR
.
Append the string "Data version 2.0.\n" to the global attribute
history
:
ncatted -a history,global,a,c,"Data version 2.0\n" in.nc
Note the use of embedded C language printf()
-style escape
sequences.
Change the value of the long_name
attribute for variable T
from whatever it currently is to "temperature":
ncatted -a long_name,T,o,c,temperature in.nc
Delete all existing units
attributes:
ncatted -a units,,d,, in.nc
The value of var_nm was left blank in order to select all variables in the file. The values of att_type and att_val were left blank because they are superfluous in Delete mode.
Delete all attributes associated with the tpt
variable, and
delete all global attributes
ncatted -a ,tpt,d,, -a ,global,d,, in.nc
The value of att_nm was left blank in order to select all
attributes associated with the variable.
To delete all global attributes, simply replace tpt
with
global
in the above.
Modify all existing units
attributes to "meter second-1":
ncatted -a units,,m,c,"meter second-1" in.nc
Add a units
attribute of "kilogram kilogram-1" to all variables
whose first three characters are ‘H2O’:
ncatted -a units,'^H2O',c,c,"kilogram kilogram-1" in.nc
Overwrite the quanta
attribute of variable
energy
to an array of four integers.
ncatted -O -a quanta,energy,o,s,"010,101,111,121" in.nc
As of NCO 3.9.6 (January, 2009), variable names arguments
to ncatted may contain extended regular expressions.
Create isotope
attributes for all variables containing ‘H2O’
in their names.
ncatted -O -a isotope,'^H2O*',c,s,"18" in.nc
See Subsetting Variables for more details.
Demonstrate input of C-language escape sequences (e.g., \n
) and
other special characters (e.g., \"
)
ncatted -h -a special,global,o,c, '\nDouble quote: \"\nTwo consecutive double quotes: \"\"\n Single quote: Beyond my shell abilities!\nBackslash: \\\n Two consecutive backslashes: \\\\\nQuestion mark: \?\n' in.nc
Note that the entire attribute is protected from the shell by single quotes. These outer single quotes are necessary for interactive use, but may be omitted in batch scripts.