1NCATTED(1) General Commands Manual NCATTED(1)
2
6 ncatted - netCDF Attribute Editor
7
9 ncatted [-a att_dsc] [-a ...] [-D] [-h] [-l path] [-O] [-p path] [-R]
10 [-r] input-file [ output-file]
11
13 ncatted edits attributes in a netCDF file. If you are editing
14 attributes then you are spending too much time in the world of meta‐
15 data, and ncatted was written to get you back out as quickly and pain‐
16 lessly as possible. ncatted can append, create, delete, modify, and
17 overwrite attributes (all explained below). Furthermore, ncatted
18 allows each editing operation to be applied to every variable in a
19 file, thus saving you time when you want to change attribute conven‐
20 tions throughout a file. ncatted interprets character attributes as
21 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
25 automatically appending the command to the history global attribute in
26 the output-file.
27 When ncatted is used to change the missing_value attribute, it changes
29 the associated missing data self-consistently. If the internal float‐
30 ing point representation of a missing value, e.g., 1.0e36, differs
31 between two machines then netCDF files produced on those machines will
32 have incompatible missing values. This allows ncatted to change the
33 missing values in files from different machines to a single value so
34 that the files may then be concatenated together, e.g., by ncrcat,
35 without losing 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
66 attribute (named att_nm) that you want to edit. There are two very
67 important and useful exceptions to this rule. The value of var_nm can
68 also be used to direct ncatted to edit global attributes, or to repeat
69 the editing operation for every variable in a file. A value of var_nm
70 of global” indicates that att_nm refers to a global attribute, rather
71 than a particular variable's attribute. This is the method ncatted
72 supports for editing global attributes. If var_nm is left blank, on
73 the other hand, then ncatted attempts to perform the editing operation
74 on every variable in the file. This option may be convenient to use if
75 you decide 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, there is no effect.
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 o Overwrite. Write attribute att_nm with value att_val to vari‐
98 able var_nm, overwriting existing attribute att_nm, if any.
99 This is the default mode.
100 The value of att_type is a single character abbreviation ( f, d, l, s,
102 c, or b) standing for one of the six primitive netCDF data types:
103 f Float. Value(s) specified in att_val will be stored as netCDF
105 intrinsic type NC_FLOAT.
106 d Double. Value(s) specified in att_val will be stored as netCDF
108 intrinsic type NC_DOUBLE.
109 l Long. Value(s) specified in att_val will be stored as netCDF
111 intrinsic type NC_LONG.
112 s Short. Value(s) specified in att_val will be stored as netCDF
114 intrinsic type NC_SHORT.
115 c Char. Value(s) specified in att_val will be stored as netCDF
117 intrinsic type NC_CHAR.
118 b Byte. Value(s) specified in att_val will be stored as netCDF
120 intrinsic type NC_BYTE. The specification of att_type is
121 optional in Delete mode.
122 The value of att_val is what you want to change attribute att_nm to
124 contain. The specification of att_val is optional in Delete mode.
125 Attribute values for all types besides NC_CHAR must have an attribute
126 length of at least one. Thus att_val may be a single value or one-
127 dimensional array of elements of type att_type. If the att_val is not
128 set or is set to empty space, and the att_type is NC_CHAR, e.g., -a
129 units,T,o,c,"" or -a units,T,o,c,, then the corresponding attribute is
130 set to have zero length. When specifying an array of values, it is
131 safest to enclose att_val in double or single quotes, e.g., -a lev‐
132 els,T,o,s,"1,2,3,4" or -a levels,T,o,s,'1,2,3,4'. The quotes are
133 strictly unnecessary around att_val except when att_val contains char‐
134 acters which would confuse the calling shell, such as spaces, commas,
135 and wildcard characters.
136 NCO processing of NC_CHAR attributes is a bit like Perl in that it
138 attempts to do what you want by default (but this sometimes causes
139 unexpected results if you want unusual data storage). If the att_type
140 is NC_CHAR then the argument is interpreted as a string and it may con‐
141 tain C-language escape sequences, which NCO will interpret before writ‐
142 ing anything to disk. NCO translates valid escape sequences and stores
143 the appropriate ASCII code instead. Since two byte escape sequences
144 represent one byte ASCII codes, e.g., ASCII 10 (decimal), the stored
145 string attribute is one byte shorter than the input string length for
146 each embedded escape sequence. These sequences in particular allow
147 convenient editing of formatted text attributes. See ncks netCDF
148 Kitchen Sink, for more examples of string formatting (with the ncks -s
149 option) with special characters.
150 Analogous to printf, other special characters are also allowed by ncat‐
152 ted if they are "protected" by a backslash. NCO simply strips away the
153 leading backslash from these characters before editing the attribute.
154 No other characters require protection by a backslash. Backslashes
155 which precede any other character will not be filtered and will be
156 included in the attribute.
157 Note that the NUL character which terminates C language strings is
159 assumed and need not be explicitly specified. If NUL is input, it will
160 not be translated (because it would terminate the string in an addi‐
161 tional location). Because of these context-sensitive rules, if wish to
162 use an attribute of type NC_CHAR to store data, rather than text
163 strings, you should use ncatted with care.
164
166 Append the string "Data version 2.0.\n" to the global attribute his‐
167 tory:
168 ncatted -O -a history,global,a,c,"Data version 2.0\n" in.nc
169 Note the use of embedded C language printf()-style escape sequences.
170 Change the value of the long_name attribute for variable T from what‐
172 ever it currently is to "temperature":
173 ncatted -O -a long_name,T,o,c,temperature in.nc
174 Delete all existing units attributes:
176 ncatted -O -a units,,d,, in.nc
177 The value of var_nm was left blank in order to select all variables in
178 the file. The values of att_type and att_val were left blank because
179 they are superfluous in Delete mode.
180 Modify all existing units attributes to "meter second-1"
182 ncatted -O -a units,,m,c,"meter second-1" in.nc
183 Overwrite the quanta attribute of variable energy to an array of four
185 integers.
186 ncatted -O -a quanta,energy,o,s,"010,101,111,121" in.nc
187 Demonstrate input of C-language escape sequences and other special
189 characters
190 ncatted -h -a special,global,o,c, Single quote: Beyond my shell
191 abilities!\nBackslash: \\n Two consecutive backslashes:
192 \\\nQuestion mark: \?\n' in.nc
193 Note that the entire attribute is protected from the shell by single
194 quotes. These outer single quotes are necessary for interactive use,
195 but may be omitted in batch scripts.
196
199 NCO manual pages written by Charlie Zender and Brian Mays.
200
203 Report bugs to <http://sf.net/bugs/?group_id=3331>.
204
207 Copyright © 1995-2004 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 User's 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 User's Guide are the PDF (recommended), DVI, and Postscript
219 versions at <http://nco.sf.net/nco.pdf>, <http://nco.sf.net/nco.dvi>,
220 and <http://nco.sf.net/nco.ps>, respectively. HTML and XML versions
221 are 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-
230 intensive portions.
231
234 The NCO homepage at <http://nco.sf.net> contains more information.
235 NCATTED(1)