4.11 ncrename netCDF Renamer

SYNTAX

     ncrename [-a old_name,new_name] [-a ...] [-D dbg]
     [-d old_name,new_name] [-d ...] [-h] [--hdr_pad nbr] [-l path]
     [-O] [-o output-file] [-p path] [-R] [-r]
     [-v old_name,new_name] [-v ...]
     input-file [[output-file]]

DESCRIPTION

ncrename renames dimensions, variables, and attributes in a netCDF file. Each object that has a name in the list of old names is renamed using the corresponding name in the list of new names. All the new names must be unique. Every old name must exist in the input file, unless the old name is preceded by the period (or “dot”) character ‘.’. The validity of old_name is not checked prior to the renaming. Thus, if old_name is specified without the the ‘.’ prefix and is not present in input-file, ncrename will abort. The new_name should never be prefixed by a ‘.’ (or else the period will be included as part of the new name). The OPTIONS and EXAMPLES show how to select specific variables whose attributes are to be renamed.

ncrename is the exception to the normal rules that the user will be interactively prompted before an existing file is changed, and that a temporary copy of an output file is constructed during the operation. If only input-file is specified, then ncrename will change the names of the input-file in place without prompting and without creating a temporary copy of input-file. This is because the renaming operation is considered reversible if the user makes a mistake. The new_name can easily be changed back to old_name by using ncrename one more time.

Note that renaming a dimension to the name of a dependent variable can be used to invert the relationship between an independent coordinate variable and a dependent variable. In this case, the named dependent variable must be one-dimensional and should have no missing values. Such a variable will become a coordinate variable.

According to the netCDF User's Guide, renaming properties in netCDF files does not incur the penalty of recopying the entire file when the new_name is shorter than the old_name.

OPTIONS

‘-a old_name,new_name’

Attribute renaming. The old and new names of the attribute are specified with ‘-a’ (or ‘--attribute’) by the associated old_name and new_name values. Global attributes are treated no differently than variable attributes. This option may be specified more than once. As mentioned above, all occurrences of the attribute of a given name will be renamed unless the ‘.’ form is used, with one exception. To change the attribute name for a particular variable, specify the old_name in the format old_var_name@old_att_name. The ‘@’ symbol delimits the variable and attribute names. If the attribute is uniquely named (no other variables contain the attribute) then the old_var_name@old_att_name syntax is redundant. The var_name@att_name syntax is accepted, but not required, for the new_name.

‘-d old_name,new_name’

Dimension renaming. The old and new names of the dimension are specified with ‘-d’ (or ‘--dmn’, ‘--dimension’) by the associated old_name and new_name values. This option may be specified more than once.

‘-v old_name,new_name’

Variable renaming. The old and new names of the variable are specified with ‘-v’ (or ‘--variable’) by the associated old_name and new_name values. This option may be specified more than once.

EXAMPLES

Rename the variable p to pressure and t to temperature in netCDF in.nc. In this case p must exist in the input file (or ncrename will abort), but the presence of t is optional:

     ncrename -v p,pressure -v .t,temperature in.nc

Rename the attribute long_name to largo_nombre in the variable u, and no other variables in netCDF in.nc.

     ncrename -a u:long_name,largo_nombre in.nc

ncrename does not automatically attach dimensions to variables of the same name. If you want to rename a coordinate variable so that it remains a coordinate variable, you must separately rename both the dimension and the variable:

     ncrename -d lon,longitude -v lon,longitude in.nc

Create netCDF out.nc identical to in.nc except the attribute _FillValue is changed to missing_value, the attribute units is changed to CGS_units (but only in those variables which possess it), the attribute hieght is changed to height in the variable tpt, and in the variable prs_sfc, if it exists.

     ncrename -a _FillValue,missing_value -a .units,CGS_units \
       -a tpt@hieght,height -a prs_sfc@.hieght,height in.nc out.nc

The presence and absence of the ‘.’ and ‘@’ features cause this command to execute successfully only if a number of conditions are met. All variables must have a _FillValue attribute and _FillValue must also be a global attribute. The units attribute, on the other hand, will be renamed to CGS_units wherever it is found but need not be present in the file at all (either as a global or a variable attribute). The variable tpt must contain the hieght attribute. The variable prs_sfc need not exist, and need not contain the hieght attribute.