NCDUMP(1) UNIDATA UTILITIES NCDUMP(1)NAMEncdump - Convert netCDF files to ASCII form (CDL)
SYNOPSISncdump [-c] [-h] [-v var1,...] [-b lang] [-f lang] [-l
len] [-n name] [-p f_digits[,d_digits]] file
DESCRIPTIONncdump generates an ASCII representation of a specified
netCDF file on standard output. The ASCII representation
is in a form called CDL (``network Common Data form Lan
guage'') that can be viewed, edited, or serve as input to
ncgen. ncgen is a companion program that can generate a
binary netCDF file from a CDL file. Hence ncgen and nc
dump can be used as inverses to transform the data repre
sentation between binary and ASCII representations. See
ncgen for a description of CDL and netCDF representations.
ncdump defines a default format used for each type of
netCDF data, but this can be changed if a `C_format' at
tribute is defined for a netCDF variable. In this case,
ncdump will use the `C_format' attribute to format each
value. For example, if floating-point data for the netCDF
variable `Z' is known to be accurate to only three signif
icant digits, it would be appropriate to use the variable
attribute
Z:C_format = "%.3g"
ncdump may also be used as a simple browser for netCDF da
ta files, to display the dimension names and sizes; vari
able names, types, and shapes; attribute names and values;
and optionally, the values of data for all variables or
selected variables in a netCDF file.
ncdump uses `_' to represent data values that are equal to
the `_FillValue' attribute for a variable, intended to
represent data that has not yet been written. If a vari
able has no `_FillValue' attribute, the default fill value
for the variable type is used if the variable is not of
byte type.
OPTIONS-c Show the values of coordinate variables (variables
that are also dimensions) as well as the declara
tions of all dimensions, variables, and attribute
values. Data values of non-coordinate variables
are not included in the output. This is the most
suitable option to use for a brief look at the
structure and contents of a netCDF file.
-h Show only the header information in the output,
that is the declarations of dimensions, variables,
and attributes but no data values for any vari
Printed: 101-10-25 $Date: 1996/10/08 18:48:09 $ 1
NCDUMP(1) UNIDATA UTILITIES NCDUMP(1)
ables. The output is identical to using the -c op
tion except that the values of coordinate variables
are not included. (At most one of -c or -h options
may be present.)
-v var1,...,varn
The output will include data values for the speci
fied variables, in addition to the declarations of
all dimensions, variables, and attributes. One or
more variables must be specified by name in the
comma-delimited list following this option. The
list must be a single argument to the command,
hence cannot contain blanks or other white space
characters. The named variables must be valid
netCDF variables in the input-file. The default,
without this option and in the absence of the -c or
-h options, is to include data values for all vari
ables in the output.
-b lang
A brief annotation in the form of a CDL comment
(text beginning with the characters ``//'') will be
included in the data section of the output for each
`row' of data, to help identify data values for
multidimensional variables. If lang begins with
`C' or `c', then C language conventions will be
used (zero-based indices, last dimension varying
fastest). If lang begins with `F' or `f', then
Fortran language conventions will be used (one-
based indices, first dimension varying fastest).
In either case, the data will be presented in the
same order; only the annotations will differ. This
option is useful for browsing through large volumes
of multidimensional data.
-f lang
Full annotations in the form of trailing CDL com
ments (text beginning with the characters ``//'')
for every data value (except individual characters
in character arrays) will be included in the data
section. If lang begins with `C' or `c', then C
language conventions will be used (zero-based in
dices, last dimension varying fastest). If lang
begins with `F' or `f', then Fortran language con
ventions will be used (one-based indices, first di
mension varying fastest). In either case, the data
will be presented in the same order; only the anno
tations will differ. This option may be useful for
piping data into other filters, since each data
value appears on a separate line, fully identified.
-l len Changes the default maximum line length (80) used
in formatting lists of non-character data values.
Printed: 101-10-25 $Date: 1996/10/08 18:48:09 $ 2
NCDUMP(1) UNIDATA UTILITIES NCDUMP(1)-n name
CDL requires a name for a netCDF data set, for use
by ncgen -b in generating a default netCDF file
name. By default, ncdump constructs this name from
the last component of the pathname of the input
netCDF file by stripping off any extension it has.
Use the -n option to specify a different name. Al
though the output file name used by ncgen -b can be
specified, it may be wise to have ncdump change the
default name to avoid inadvertantly overwriting a
valuable netCDF file when using ncdump, editing the
resulting CDL file, and using ncgen -b to generate
a new netCDF file from the edited CDL file.
-p float_digits[,double_digits]
Specifies default precision (number of significant
digits) to use in displaying floating-point or dou
ble precision data values for attributes and vari
ables. If specified, this value overrides the val
ue of the `C_format' attribute for any variable
that has such an attribute. Floating-point data
will be displayed with float_digits significant
digits. If double_digits is also specified, dou
ble-precision values will be displayed with that
many significant digits. In the absence of any -p
specifications, floating-point and double-precision
data are displayed with 7 and 15 significant digits
respectively. CDL files can be made smaller if
less precision is required. If both floating-point
and double-presision precisions are specified, the
two values must appear separated by a comma (no
blanks) as a single argument to the command. If
you really want every last bit of precision from
the netCDF file represented in the CDL file for all
possible floating-point values, you will have to
specify this with -p 9,17 (according to Theorem 15
of the paper listed under REFERENCES).
EXAMPLES
Look at the structure of the data in the netCDF file
`foo.nc':
ncdump-c foo.nc
Produce an annotated CDL version of the structure and data
in the netCDF file `foo.nc', using C-style indexing for
the annotations:
ncdump-b c foo.nc > foo.cdl
Output data for only the variables `uwind' and `vwind'
from the netCDF file `foo.nc', and show the floating-point
data with only three significant digits of precision:
Printed: 101-10-25 $Date: 1996/10/08 18:48:09 $ 3
NCDUMP(1) UNIDATA UTILITIES NCDUMP(1)ncdump-v uwind,vwind -p 3 foo.nc
Produce a fully-annotated (one data value per line) list
ing of the data for the variable `omega', using Fortran
conventions for indices, and changing the netCDF dataset
name in the resulting CDL file to `omega':
ncdump-v omega -f fortran -n omega foo.nc > Z.cdl
REFERENCES
What Every Computer Scientist should Know About Floating-
Point Arithmetic, D. Goldberg, ACM Computing Surveys,
Vol. 23, No. 1, March 1991, pp. 5-48.
SEE ALSOncgen(1), netcdf(3)BUGS
Character arrays that contain a null-byte are treated like
C strings, so no characters after the null byte appear in
the output.
Multidimensional character string arrays are not handled
well, since the CDL syntax for breaking a long character
string into several shorter lines is weak.
There should be a way to specify that the data should be
displayed in `record' order, that is with the all the val
ues for `record' variables together that have the same
value of the record dimension.
Printed: 101-10-25 $Date: 1996/10/08 18:48:09 $ 4
