NAME
ncatted - netCDF Attribute Editor
SYNTAX
ncatted [-a att_dsc] [-a ...] [-D] [-h] [-l path] [-O] [-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, thus saving you time when you want to change attribute
conventions throughout a file. ncatted interprets character attributes
as strings.
Because repeated use of ncatted can considerably increase the size of
the history global 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.
The key to mastering ncatted is understanding the meaning of the
structure describing the attribute modification, att_dsc. 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
att_nm Attribute name. Example: units
var_nm Variable name. Example: pressure
mode Edit mode abbreviation. Example: a. See below for complete
listing of valid values of mode.
att_type
Attribute type abbreviation. Example: c. See below for complete
listing of valid values of att_type.
att_val
Attribute value. Example: pascal. There should be no empty
space between these five consecutive arguments. The description
of these arguments follows in their order of appearance.
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.
The value of var_nm is the name of the variable containing the
attribute (named att_nm) that you want to edit. There are two 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.
The value of mode is a single character abbreviation ( a, c, d, m, or
o) standing for one of five editing modes:
a Append. Append value att_val to current var_nm attribute att_nm
value att_val, if any. If var_nm does not have an attribute
att_nm, there is no effect.
c Create. Create variable var_nm attribute att_nm with att_val if
att_nm does not yet exist. If var_nm already has an attribute
att_nm, there is no effect.
d Delete. Delete current var_nm attribute att_nm. If var_nm does
not have an attribute att_nm, there is no effect. When Delete
mode is selected, the att_type and att_val arguments are
superfluous and may be left blank.
m Modify. Change value of current var_nm attribute att_nm to
value att_val. If var_nm does not have an attribute att_nm,
there is no effect.
o Overwrite. Write attribute att_nm with value att_val to
variable var_nm, overwriting existing attribute att_nm, if any.
This is the default mode.
The value of att_type is a single character abbreviation ( f, d, l, s,
c, or b) standing for one of the six primitive netCDF data types:
f Float. Value(s) specified in att_val will be stored as netCDF
intrinsic type NC_FLOAT.
d Double. Value(s) specified in att_val will be stored as netCDF
intrinsic type NC_DOUBLE.
l Long. Value(s) specified in att_val will be stored as netCDF
intrinsic type NC_LONG.
s Short. Value(s) specified in att_val will be stored as netCDF
intrinsic type NC_SHORT.
c Char. Value(s) specified in att_val will be stored as netCDF
intrinsic type NC_CHAR.
b Byte. Value(s) specified in att_val will be stored as netCDF
intrinsic type NC_BYTE. The specification of att_type is
optional in Delete mode.
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 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 double or single 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, 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 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. These sequences in
particular allow convenient editing of formatted text attributes. 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. 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 will not be filtered and
will be included in the attribute.
Note that the NUL character which terminates C language strings is
assumed and need not be explicitly specified. If NUL is input, it will
not be translated (because it would terminate the string in an
additional location). Because of these context-sensitive rules, if
wish to use an attribute of type NC_CHAR to store data, rather than
text strings, you should use ncatted with care.
EXAMPLES
Append the string "Data version 2.0.\n" to the global attribute
history:
ncatted -O -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 -O -a long_name,T,o,c,temperature in.nc
Delete all existing units attributes:
ncatted -O -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.
Modify all existing units attributes to "meter second-1"
ncatted -O -a units,,m,c,"meter second-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
Demonstrate input of C-language escape sequences and other special
characters
ncatted -h -a special,global,o,c, 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.
AUTHOR
NCO manual pages written by Charlie Zender and Brian Mays.
REPORTING BUGS
Report bugs to <http://sf.net/bugs/?group_id=3331>.
COPYRIGHT
Copyright © 1995-2010 Charlie Zender
This is free software; see the source for copying conditions. There is
NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.
SEE ALSO
The full documentation for NCO is maintained as a Texinfo manual called
the NCO User’s Guide. Because NCO is mathematical in nature, the
documentation includes TeX-intensive portions not viewable on
character-based displays. Hence the only complete and authoritative
versions of the NCO User’s Guide are the PDF (recommended), DVI, and
Postscript versions at <http://nco.sf.net/nco.pdf>,
<http://nco.sf.net/nco.dvi>, and <http://nco.sf.net/nco.ps>,
respectively. HTML and XML versions are available at
<http://nco.sf.net/nco.html> and <http://nco.sf.net/nco.xml>,
respectively.
If the info and NCO programs are properly installed at your site, the
command
info nco
should give you access to the complete manual, except for the TeX-
intensive portions.
HOMEPAGE
The NCO homepage at <http://nco.sf.net> contains more information.