1NCATTED(1)                  General Commands Manual                 NCATTED(1)
2
3
4

NAME

6       ncatted - netCDF Attribute Editor
7

SYNTAX

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

DESCRIPTION

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
23       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
28       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
37       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
43       att_dsc = att_nm, var_nm, mode, att_type, att_val
44
45       att_nm Attribute name.  Example: units
46
47       var_nm Variable name.  Example: pressure
48
49       mode   Edit mode abbreviation.  Example: a.   See  below  for  complete
50              listing of valid values of mode.
51
52       att_type
53              Attribute type abbreviation. Example: c.  See below for complete
54              listing of valid values of att_type.
55
56       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
61       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
65       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
77       The value of mode is a single character abbreviation ( a, c, d,  m,  or
78       o) standing for one of five editing modes:
79
80       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
84       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
88       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
93       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
97       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
101       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
105       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
108       f      Float.   Value(s)  specified in att_val will be stored as netCDF
109              intrinsic type NC_FLOAT.
110
111       d      Double.  Value(s) specified in att_val will be stored as  netCDF
112              intrinsic type NC_DOUBLE.
113
114       l      Long.   Value(s)  specified  in att_val will be stored as netCDF
115              intrinsic type NC_LONG.
116
117       s      Short.  Value(s) specified in att_val will be stored  as  netCDF
118              intrinsic type NC_SHORT.
119
120       c      Char.   Value(s)  specified  in att_val will be stored as netCDF
121              intrinsic type NC_CHAR.
122
123       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
127       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
141       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
155       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
162       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

EXAMPLES

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
175       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
179       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
185       Modify all existing units attributes to "meter second-1"
186              ncatted -O -a units,,m,c,"meter second-1" in.nc
187
188       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
192       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
196

AUTHOR

198       NCO  manual pages written by Charlie Zender and originally formatted by
199       Brian Mays.
200
201

REPORTING BUGS

203       Report bugs to <http://sf.net/bugs/?group_id=3331>.
204
205
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
212

SEE ALSO

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
224       If the info and NCO programs are properly installed at your  site,  the
225       command
226
227              info nco
228
229       should  give  you access to the complete manual, except for the TeX-in‐
230       tensive portions.
231
232       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
236

HOMEPAGE

238       The NCO homepage at <http://nco.sf.net> contains more information.
239
240
241
242                                                                    NCATTED(1)
Impressum