--- name: "ncatted" section: "1" platform: "linux" package: "nco" version: "5.3.3-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/ncatted" --- # ncatted(1) netCDF Attribute Editor ## NAME ncatted - netCDF Attribute Editor ## SYNTAX ncatted \[-a *att\_dsc*\] \[-a ...\] \[--bfr *sz\_byt*\]*\[-D* *dbg\_lvl\]* \[--glb *att\_name=* *att\_val*\]\] \[-H\] \[-h\] \[--hdr\_pad *sz\_byt*\] \[-l path\] \[-O\] \[-p path\] \[-R\] \[-r\] \[--ram\_all\] \[-t\] \[--uio\] *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*, *nappend*, 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*, it is created with value *att\_val.* - **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. - **n** *Nappend*. 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. - **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 See the manual for more complex examples, including how to input C-language escape sequences and other special characters like backslashes and question marks. ## AUTHOR **NCO** manual pages written by Charlie Zender and originally formatted by Brian Mays. ## REPORTING BUGS Report bugs to \. ## COPYRIGHT Copyright © 1995-present 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 Users 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 Users Guide** are the PDF (recommended), DVI, and Postscript versions at \, \, and \, respectively. HTML and XML versions are available at \ and \, 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. [**ncap2**(1)](/ncap2/1.md), [**ncatted**(1)](/ncatted/1.md), [**ncbo**(1)](/ncbo/1.md), [**ncclimo**(1)](/ncclimo/1.md), [**nces**(1)](/nces/1.md), [**ncecat**(1)](/ncecat/1.md), [**ncflint**(1)](/ncflint/1.md), [**ncz2psx**(1)](/ncz2psx/1.md), [**ncks**(1)](/ncks/1.md), [**nco**(1)](/nco/1.md), [**ncpdq**(1)](/ncpdq/1.md), [**ncra**(1)](/ncra/1.md), [**ncrcat**(1)](/ncrcat/1.md), [**ncremap**(1)](/ncremap/1.md), [**ncrename**(1)](/ncrename/1.md), [**ncwa**(1)](/ncwa/1.md) ## HOMEPAGE The **NCO** homepage at \ contains more information.