ncks - Online in the Cloud

PROGRAM:

NAME

ncks - netCDF Kitchen Sink

SYNTAX

ncks [-3] [-4] [-5] [-6] [-7] [-A] [-a] [-b bnr_fl] [--bfr sz][-C][-c] [--cdl] [--cnk_byt
sz][--cnk_dmn nm,sz] [--cnk_map map] [--cnk_min sz] [--cnk_plc plc] [--cnk_scl sz] [-D
dbg_lvl] [-d dim,[ min][,[ max]][,[ stride]]] [-F] [--fix_rec_dmn dim] [-G gpe_dsc] [-g
grp[,...]] [--glb att_name= att_val]] [--grp_xtr_var_xcl] [-H] [-h] [--hdn] [--hdr_pad
sz] [-L dfl_lvl] [-l path] [-M] [-m] [--map map-file] [--md5] [--mk_rec_dmn dim] [--msa]
[--no_blank] [--no_tmp_fl] [-O] [-o output-file] [-P] [-p path] [--ppc var1[, var2[,...]]=
prc]] [-Q] [-q] [-R] [-r] [--rad] [--ram_all] [--rgr key= val]] [--rnr wgt][-s format][-t
thr_nbr][-u][--unn][-V][-v var[,...]] [-X box] [-x] [--xml] input-file [ output-file]

DESCRIPTION

ncks combines every feature we could think of, except the kitchen sink, into one versatile
utility to manipulate netCDF files. ncks extracts a subset of the data from input-file
and either prints it as ASCII text to stdout, or writes (or pastes) it to output-file, or
both.

ncks will print netCDF data in ASCII format to stdout, like ncdump, but with these
differences: ncks prints data in a tabular format intended to be easy to search for the
data you want, one datum per screen line, with all dimension subscripts and coordinate
values (if any) preceding the datum. Option -s allows the user the format the data using
C-style format strings.

Options -a, -F, -H, -M, -m, -Q, -q, -s, -u, and -V control the formatted appearance of the
data.

ncks will extract (and optionally create a new netCDF file comprised of) only selected
variable from the input file, like ncextr but with these differences: Only variables and
coordinates may be specifically included or excluded---all global attributes and any
attribute associated with an extracted variable will be copied to the screen and/or output
netCDF file. Options -c, -C, -v, and -x control which variables are extracted.

ncks will extract hyperslabs from the specified variables. In fact ncks implements the
nccut specification exactly. Option -d controls the hyperslab specification.

Input dimensions that are not associated with any output variable will not appear in the
output netCDF. This feature removes superfluous dimensions from a netCDF file.

ncks will append variables and attributes from the input-file to output-file if output-
file is a pre-existing netCDF file whose relevant dimensions conform to dimension sizes of
input-file. The append features of ncks are intended to provide a rudimentary means of
adding data from one netCDF file to another, conforming, netCDF file. When naming
conflicts exists between the two files, data in output-file is usually overwritten by the
corresponding data from input-file. Thus it is recommended that the user backup output-
file in case valuable data is accidentally overwritten.

If output-file exists, the user will be queried whether to overwrite, append, or exit the
ncks call completely. Choosing overwrite destroys the existing output-file and create an
entirely new one from the output of the ncks call. Append has differing effects depending
on the uniqueness of the variables and attributes output by ncks: If a variable or
attribute extracted from input-file does not have a name conflict with the members of
output-file then it will be added to output-file without overwriting any of the existing
contents of output-file. In this case the relevant dimensions must agree (conform)
between the two files; new dimensions are created in output-file as required. When a name
conflict occurs, a global attribute from input-file will overwrite the corresponding
global attribute from output-file. If the name conflict occurs for a non-record variable,
then the dimensions and type of the variable (and of its coordinate dimensions, if any)
must agree (conform) in both files. Then the variable values (and any coordinate
dimension values) from input-file will overwrite the corresponding variable values (and
coordinate dimension values, if any) in output-file

Since there can only be one record dimension in a file, the record dimension must have the
same name (but not necessarily the same size) in both files if a record dimension variable
is to be appended. If the record dimensions are of differing sizes, the record dimension
of output-file will become the greater of the two record dimension sizes, the record
variable from input-file will overwrite any counterpart in output-file and fill values
will be written to any gaps left in the rest of the record variables (I think). In all
cases variable attributes in output-file are superseded by attributes of the same name
from input-file, and left alone if there is no name conflict.

Some users may wish to avoid interactive ncks queries about whether to overwrite existing
data. For example, batch scripts will fail if ncks does not receive responses to its
queries. Options -O and -A are available to force overwriting existing files and
variables, respectively.

Options specific to ncks

The following list provides a short summary of the features unique to ncks.

-a Do not alphabetize extracted fields. By default, the specified output variables
are extracted, printed, and written to disk in alphabetical order. This tends to
make long output lists easier to search for particular variables. Specifying -a
results in the variables being extracted, printed, and written to disk in the order
in which they were saved in the input file. Thus -a retains the original ordering
of the variables.

-d dim,[ min][,[ max]][,[ stride]] Add stride argument to hyperslabber.

-H Print data to screen. The default behavior is to print data to screen if no netCDF
output file is specified. Use -H to print data to screen if a netCDF output is
specified (the same behavior applies to -m ). Unless otherwise specified (with
-s), each element of the data hyperslab is printed on a separate line containing
the names, indices, and, values, if any, of all of the variables dimensions. The
dimension and variable indices refer to the location of the corresponding data
element with respect to the variable as stored on disk (i.e., not the hyperslab).
% ncks -H -C -v three_dmn_var in.nc
lat[0]=-90 lev[0]=100 lon[0]=0 three_dmn_var[0]=0
lat[0]=-90 lev[0]=100 lon[1]=90 three_dmn_var[1]=1
lat[0]=-90 lev[0]=100 lon[2]=180 three_dmn_var[2]=2
...
lat[1]=90 lev[2]=1000 lon[1]=90 three_dmn_var[21]=21
lat[1]=90 lev[2]=1000 lon[2]=180 three_dmn_var[22]=22
lat[1]=90 lev[2]=1000 lon[3]=270 three_dmn_var[23]=23
Printing the same variable with the -F option shows the same variable indexed with Fortran
conventions
% ncks -F -H -C -v three_dmn_var in.nc
lon(1)=0 lev(1)=100 lat(1)=-90 three_dmn_var(1)=0
lon(2)=90 lev(1)=100 lat(1)=-90 three_dmn_var(2)=1
lon(3)=180 lev(1)=100 lat(1)=-90 three_dmn_var(3)=2
...
Printing a hyperslab does not affect the variable or dimension indices since these indices
are relative to the full variable (as stored in the input file), and the input file has
not changed. However, if the hyperslab is saved to an output file and those values are
printed, the indices will change:
% ncks -H -d lat,90.0 -d lev,1000.0 -v three_dmn_var in.nc out.nc
lat[1]=90 lev[2]=1000 lon[0]=0 three_dmn_var[20]=20
lat[1]=90 lev[2]=1000 lon[1]=90 three_dmn_var[21]=21
lat[1]=90 lev[2]=1000 lon[2]=180 three_dmn_var[22]=22
lat[1]=90 lev[2]=1000 lon[3]=270 three_dmn_var[23]=23
% ncks -H out.nc
lat[0]=90 lev[0]=1000 lon[0]=0 three_dmn_var[0]=20
lat[0]=90 lev[0]=1000 lon[1]=90 three_dmn_var[1]=21
lat[0]=90 lev[0]=1000 lon[2]=180 three_dmn_var[2]=22
lat[0]=90 lev[0]=1000 lon[3]=270 three_dmn_var[3]=23

-M Print to screen the global metadata describing the file. This includes file
summary information and global attributes.

-m Print variable metadata to screen (similar to ncdump -h). This displays all
metadata pertaining to each variable, one variable at a time.

-Q Toggle printing of dimension indices and coordinate values when printing arrays.
The name of each variable will appear flush left in the output. This is useful
when trying to locate specific variables when displaying many variables with
different dimensions. The mnemonic for this option is "quiet".

-s format String format for text output. Accepts C language escape sequences and
printf() formats.

-u Accompany the printing of a variable's values with its units attribute, if it
exists.

EXAMPLES

View all data in netCDF in.nc, printed with Fortran indexing conventions:
ncks -H -F in.nc

Copy the netCDF file in.nc to file out.nc.
ncks -O in.nc out.nc
Now the file out.nc contains all the data from in.nc. There are, however, two differences
between in.nc and out.nc. First, the history global attribute will contain the command
used to create out.nc. Second, the variables in out.nc will be defined in alphabetical
order. Of course the internal storage of variable in a netCDF file should be transparent
to the user, but there are cases when alphabetizing a file is useful (see description of
-a switch).

Print variable three_dmn_var from file in.nc with default notations. Next print
three_dmn_var as an un-annotated text column. Then print three_dmn_var signed with very
high precision. Finally, print three_dmn_var as a comma-separated list.
% ncks -H -C -v three_dmn_var in.nc
lat[0]=-90 lev[0]=100 lon[0]=0 three_dmn_var[0]=0
lat[0]=-90 lev[0]=100 lon[1]=90 three_dmn_var[1]=1
...
lat[1]=90 lev[2]=1000 lon[3]=270 three_dmn_var[23]=23
% ncks -s "%f\n" -H -C -v three_dmn_var in.nc
0.000000
1.000000
...
23.000000
% ncks -s "%+16.10f\n" -H -C -v three_dmn_var in.nc
+0.0000000000
+1.0000000000
...
+23.0000000000
% ncks -s "%f, " -H -C -v three_dmn_var in.nc
0.000000, 1.000000, ... , 23.000000,
The second and third options are useful when pasting data into text files like reports or
papers.

One dimensional arrays of characters stored as netCDF variables are automatically printed
as strings, whether or not they are NUL-terminated, e.g.,
ncks -v fl_nm in.nc
The %c formatting code is useful for printing multidimensional arrays of characters
representing fixed length strings
ncks -H -s "%c" -v fl_nm_arr in.nc
Using the %s format code on strings which are not NUL-terminated (and thus not technically
strings) is likely to result in a core dump.

Create netCDF out.nc containing all variables, and any associated coordinates, except
variable time, from netCDF in.nc:
ncks -x -v time in.nc out.nc

Extract variables time and pressure from netCDF in.nc. If out.nc does not exist it will
be created. Otherwise the you will be prompted whether to append to or to overwrite
out.nc:
ncks -v time,pressure in.nc out.nc
ncks -C -v time,pressure in.nc out.nc
The first version of the command creates an out.nc which contains time, pressure, and any
coordinate variables associated with pressure. The out.nc from the second version is
guaranteed to contain only two variables time and pressure.

Create netCDF out.nc containing all variables from file in.nc. Restrict the dimensions of
these variables to a hyperslab. Print (with -H) the hyperslabs to the screen for good
measure. The specified hyperslab is: the sixth value in dimension time; the half-open
range lat <= 0.0 in coordinate lat; the half-open range lon >= 330.0 in coordinate lon;
the closed interval 0.3 <= band <= 0.5 in coordinate band; and cross-section closest to
1000.0 in coordinate lev. Note that limits applied to coordinate values are specified
with a decimal point, and limits applied to dimension indices do not have a decimal point.
ncks -H -d time,5 -d lat,,0. -d lon,330., -d band,.3,.5 -d lev,1000. in.nc out.nc

Assume the domain of the monotonically increasing longitude coordinate lon is 0 < lon <
360. Here, lon is an example of a wrapped coordinate. ncks will extract a hyperslab
which crosses the Greenwich meridian simply by specifying the westernmost longitude as min
and the easternmost longitude as max, as follows:
ncks -d lon,260.,45. in.nc out.nc

Use ncks online using onworks.net services