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