1NCATTED(1) General Commands Manual NCATTED(1)
2
6 ncatted - netCDF Attribute Editor
7
9 ncatted [-a att_dsc] [-a ...] [--bfr sz_byt][-D dbg_lvl] [--glb
10 att_name= att_val]] [-H] [-h] [--hdr_pad sz_byt] [-l path] [-O] [-p
11 path] [-R] [-r] [--ram_all] [-t] [--uio] input-file [ output-file]
12
14 ncatted edits attributes in a netCDF file. If you are editing at‐
15 tributes then you are spending too much time in the world of metadata,
16 and ncatted was written to get you back out as quickly and painlessly
17 as possible. ncatted can append, create, delete, modify, nappend, and
18 overwrite attributes (all explained below). Furthermore, ncatted al‐
19 lows each editing operation to be applied to every variable in a file,
20 thus saving you time when you want to change attribute conventions
21 throughout a file. ncatted interprets character attributes as strings.
22 Because repeated use of ncatted can considerably increase the size of
24 the history global attribute, the -h switch is provided to override au‐
25 tomatically appending the command to the history global attribute in
26 the output-file.
27 When ncatted is used to change the _FillValue attribute, it changes the
29 associated missing data self-consistently. If the internal floating
30 point representation of a missing value, e.g., 1.0e36, differs between
31 two machines then netCDF files produced on those machines will have in‐
32 compatible missing values. This allows ncatted to change the missing
33 values in files from different machines to a single value so that the
34 files may then be concatenated together, e.g., by ncrcat, without los‐
35 ing any information.
36 The key to mastering ncatted is understanding the meaning of the struc‐
38 ture describing the attribute modification, att_dsc. Each att_dsc con‐
39 tains five elements, which makes using ncatted somewhat complicated,
40 but powerful. The att_dsc argument structure contains five arguments
41 in the following order:
42 att_dsc = att_nm, var_nm, mode, att_type, att_val
44 att_nm Attribute name. Example: units
46 var_nm Variable name. Example: pressure
48 mode Edit mode abbreviation. Example: a. See below for complete
50 listing of valid values of mode.
51 att_type
53 Attribute type abbreviation. Example: c. See below for complete
54 listing of valid values of att_type.
55 att_val
57 Attribute value. Example: pascal. There should be no empty
58 space between these five consecutive arguments. The description
59 of these arguments follows in their order of appearance.
60 The value of att_nm is the name of the attribute you want to edit.
62 This meaning of this should be clear to all users of the ncatted opera‐
63 tor.
64 The value of var_nm is the name of the variable containing the attri‐
66 bute (named att_nm) that you want to edit. There are two very impor‐
67 tant and useful exceptions to this rule. The value of var_nm can also
68 be used to direct ncatted to edit global attributes, or to repeat the
69 editing operation for every variable in a file. A value of var_nm of
70 global” indicates that att_nm refers to a global attribute, rather than
71 a particular variable's attribute. This is the method ncatted supports
72 for editing global attributes. If var_nm is left blank, on the other
73 hand, then ncatted attempts to perform the editing operation on every
74 variable in the file. This option may be convenient to use if you de‐
75 cide to change the conventions you use for describing the data.
76 The value of mode is a single character abbreviation ( a, c, d, m, or
78 o) standing for one of five editing modes:
79 a Append. Append value att_val to current var_nm attribute att_nm
81 value att_val, if any. If var_nm does not have an attribute
82 att_nm, it is created with value att_val.
83 c Create. Create variable var_nm attribute att_nm with att_val if
85 att_nm does not yet exist. If var_nm already has an attribute
86 att_nm, there is no effect.
87 d Delete. Delete current var_nm attribute att_nm. If var_nm does
89 not have an attribute att_nm, there is no effect. When Delete
90 mode is selected, the att_type and att_val arguments are super‐
91 fluous and may be left blank.
92 m Modify. Change value of current var_nm attribute att_nm to
94 value att_val. If var_nm does not have an attribute att_nm,
95 there is no effect.
96 n Nappend. Append value att_val to current var_nm attribute
98 att_nm value att_val, if any. If var_nm does not have an attri‐
99 bute att_nm, there is no effect.
100 o Overwrite. Write attribute att_nm with value att_val to vari‐
102 able var_nm, overwriting existing attribute att_nm, if any.
103 This is the default mode.
104 The value of att_type is a single character abbreviation ( f, d, l, s,
106 c, or b) standing for one of the six primitive netCDF data types:
107 f Float. Value(s) specified in att_val will be stored as netCDF
109 intrinsic type NC_FLOAT.
110 d Double. Value(s) specified in att_val will be stored as netCDF
112 intrinsic type NC_DOUBLE.
113 l Long. Value(s) specified in att_val will be stored as netCDF
115 intrinsic type NC_LONG.
116 s Short. Value(s) specified in att_val will be stored as netCDF
118 intrinsic type NC_SHORT.
119 c Char. Value(s) specified in att_val will be stored as netCDF
121 intrinsic type NC_CHAR.
122 b Byte. Value(s) specified in att_val will be stored as netCDF
124 intrinsic type NC_BYTE. The specification of att_type is op‐
125 tional in Delete mode.
126 The value of att_val is what you want to change attribute att_nm to
128 contain. The specification of att_val is optional in Delete mode. At‐
129 tribute values for all types besides NC_CHAR must have an attribute
130 length of at least one. Thus att_val may be a single value or one-di‐
131 mensional array of elements of type att_type. If the att_val is not
132 set or is set to empty space, and the att_type is NC_CHAR, e.g., -a
133 units,T,o,c,"" or -a units,T,o,c,, then the corresponding attribute is
134 set to have zero length. When specifying an array of values, it is
135 safest to enclose att_val in double or single quotes, e.g., -a lev‐
136 els,T,o,s,"1,2,3,4" or -a levels,T,o,s,'1,2,3,4'. The quotes are
137 strictly unnecessary around att_val except when att_val contains char‐
138 acters which would confuse the calling shell, such as spaces, commas,
139 and wildcard characters.
140 NCO processing of NC_CHAR attributes is a bit like Perl in that it at‐
142 tempts to do what you want by default (but this sometimes causes unex‐
143 pected results if you want unusual data storage). If the att_type is
144 NC_CHAR then the argument is interpreted as a string and it may contain
145 C-language escape sequences, which NCO will interpret before writing
146 anything to disk. NCO translates valid escape sequences and stores the
147 appropriate ASCII code instead. Since two byte escape sequences repre‐
148 sent one byte ASCII codes, e.g., ASCII 10 (decimal), the stored string
149 attribute is one byte shorter than the input string length for each em‐
150 bedded escape sequence. These sequences in particular allow convenient
151 editing of formatted text attributes. See ncks netCDF Kitchen Sink,
152 for more examples of string formatting (with the ncks -s option) with
153 special characters.
154 Analogous to printf, other special characters are also allowed by ncat‐
156 ted if they are "protected" by a backslash. NCO simply strips away the
157 leading backslash from these characters before editing the attribute.
158 No other characters require protection by a backslash. Backslashes
159 which precede any other character will not be filtered and will be in‐
160 cluded in the attribute.
161 Note that the NUL character which terminates C language strings is as‐
163 sumed and need not be explicitly specified. If NUL is input, it will
164 not be translated (because it would terminate the string in an addi‐
165 tional location). Because of these context-sensitive rules, if wish to
166 use an attribute of type NC_CHAR to store data, rather than text
167 strings, you should use ncatted with care.
168
170 Append the string "Data version 2.0.\n" to the global attribute his‐
171 tory:
172 ncatted -O -a history,global,a,c,"Data version 2.0\n" in.nc
173 Note the use of embedded C language printf()-style escape sequences.
174 Change the value of the long_name attribute for variable T from what‐
176 ever it currently is to "temperature":
177 ncatted -O -a long_name,T,o,c,temperature in.nc
178 Delete all existing units attributes:
180 ncatted -O -a units,,d,, in.nc
181 The value of var_nm was left blank in order to select all variables in
182 the file. The values of att_type and att_val were left blank because
183 they are superfluous in Delete mode.
184 Modify all existing units attributes to "meter second-1"
186 ncatted -O -a units,,m,c,"meter second-1" in.nc
187 Overwrite the quanta attribute of variable energy to an array of four
189 integers.
190 ncatted -O -a quanta,energy,o,s,"010,101,111,121" in.nc
191 See the manual for more complex examples, including how to input C-lan‐
193 guage escape sequences and other special characters like backslashes
194 and question marks.
195
198 NCO manual pages written by Charlie Zender and originally formatted by
199 Brian Mays.
200
203 Report bugs to <http://sf.net/bugs/?group_id=3331>.
204
207 Copyright © 1995-present Charlie Zender
208 This is free software; see the source for copying conditions. There is
209 NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
210 PURPOSE.
211
214 The full documentation for NCO is maintained as a Texinfo manual called
215 the NCO Users Guide. Because NCO is mathematical in nature, the docu‐
216 mentation includes TeX-intensive portions not viewable on character-
217 based displays. Hence the only complete and authoritative versions of
218 the NCO Users Guide are the PDF (recommended), DVI, and Postscript ver‐
219 sions at <http://nco.sf.net/nco.pdf>, <http://nco.sf.net/nco.dvi>, and
220 <http://nco.sf.net/nco.ps>, respectively. HTML and XML versions are
221 available at <http://nco.sf.net/nco.html> and
222 <http://nco.sf.net/nco.xml>, respectively.
223 If the info and NCO programs are properly installed at your site, the
225 command
226 info nco
228 should give you access to the complete manual, except for the TeX-in‐
230 tensive portions.
231 ncap2(1), ncatted(1), ncbo(1), ncclimo(1), nces(1), ncecat(1),
233 ncflint(1), ncz2psx(1), ncks(1), nco(1), ncpdq(1), ncra(1), ncrcat(1),
234 ncremap(1), ncrename(1), ncwa(1)
235
238 The NCO homepage at <http://nco.sf.net> contains more information.
239 NCATTED(1)