NCATTED(1)

📦
version 5.3.9 · 3 versions
, in fedora 44, nixpkgs unstable, opensuse-leap 16.0, ubuntu resolute, ubuntu stonking

✨ NCATTED — netCDF Attribute Editor ✨

okay bestie, sit down, hydrate, because this one is a whole vibe. this is the ncatted page from the General Commands Manual (section 1, obvs 💅). it's giving metadata-girlboss energy and honestly? we ate.

🎀 NAME 🎀

ncatted — netCDF Attribute Editor

no cap, that's the whole name section. short, sweet, iconic.

📜 SYNTAX 📜

ncatted [-a att_dsc] [-a ...] [--bfr sz_byt][-D dbg_lvl] [--gaa att_name= att_val]] [--gad att1[,...]]  [-H] [-h] [--hdr_pad sz_byt] [-l path] [-O] [-p path] [-R] [-r] [--ram_all] [-t] [--uio] input-file [output-file]

so like, here's the thing — this page does not spill extra tea on what each of these flags does. it just drops them and moves on, main character style. but for the record, every single one of them is right there in the synopsis, so here they all are, listed, nothing skipped, nothing invented:

  • -a att_dsc — the attribute descriptor. you can stack it: -a ... again and again. the whole meaning of att_dsc is unpacked way down in DESCRIPTION, keep scrolling 🫶
  • --bfr sz_byt
  • -D dbg_lvl
  • --gaa att_name= att_val (yes, that extra ] in the synopsis is in the original, don't @ me)
  • --gad att1[,...]
  • -H
  • -h — this one does get explained below, and it's important
  • --hdr_pad sz_byt
  • -l path
  • -O
  • -p path
  • -R
  • -r
  • --ram_all
  • -t
  • --uio
  • input-file — required, bestie
  • output-file — optional, in brackets, like a little bonus

🦋 DESCRIPTION 🦋

ncatted edits attributes in a netCDF file. and listen — if you're editing attributes then you are spending too much time in the world of metadata, and ncatted was literally written to get you back out as quickly and painlessly as possible. periodt. 💅

ncatted can append, create, delete, modify, nappend, and overwrite attributes — all of those are explained below, don't worry. and even better: ncatted lets you apply each editing operation to every variable in a file, so when you wanna change attribute conventions across a whole file you don't have to do it one by one like a peasant. 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. here's the drama: if the internal floating point representation of a missing value — like 1.0e36 — differs between two machines, then netCDF files produced on those machines will have incompatible missing values. this lets ncatted 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. slay 🧚

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.

🚨 bestie warning: that last bit is real. if you're using NC_CHAR to store actual data and not text, be careful. the rules are context-sensitive and they will humble you.

🌸 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 <http://sf.net/bugs/?group_id=3331>.

(not me asking you to file a bug report, but like, if it's broken, tell them 🫶)

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.

💀 yes, the all-caps "NO" is load-bearing. respect it.

🌈 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 <http://nco.sf.net/nco.pdf>, <http://nco.sf.net/nco.dvi>, and <http://nco.sf.net/nco.ps>, respectively. HTML and XML versions are available at <http://nco.sf.net/nco.html> and <http://nco.sf.net/nco.xml>, 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), ncatted(1), ncbo(1), ncclimo(1), nces(1), ncecat(1), ncflint(1), ncz2psx(1), ncks(1), nco(1), ncpdq(1), ncra(1), ncrcat(1), ncremap(1), ncrename(1), ncwa(1)

🌐 HOMEPAGE 🌐

The NCO homepage at <http://nco.sf.net> contains more information.

and that's the whole page, bestie 💜 it lives in the General Commands Manual as NCATTED(1), and the copyright has been running from 1995 to present, courtesy of Charlie Zender. go forth and edit those attributes, you absolute icon 🎀✨

📦 where this page comes from