xenial (1) ncdump-hdf.1.gz

Provided by: hdf4-tools_4.2.10-3.2_amd64 bug

NAME

       ncdump - Convert netCDF files to ASCII form (CDL)

SYNOPSIS

       ncdump [-c] [-h] [-v var1,...]  [-b lang] [-f lang] [-l len] [-n name] [-d f_digits[,d_digits]] file

DESCRIPTION

       ncdump  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  Language'')  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 ncdump can be used as inverses to  transform  the  data  representation
       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' attribute 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 significant 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 data files, to display  the  dimension  names  and
       sizes;  variable names, types, and shapes; attribute names and values; and optionally, the values of data
       for all variables or selected variables in a netCDF file.

OPTIONS

       -c     Show the values of coordinate variables (variables that  are  also  dimensions)  as  well  as  the
              declarations  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 variables.  The output is  identical  to  using  the  -c
              option  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 specified 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 variables 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 comments (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 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
              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.

       -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.  Although 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.

       -d float_digits[,double_digits]
              Specifies  default  number  of  significant  digits  to use in displaying floating-point or double
              precision data values for variables that don't have a `C_format' attribute.   Floating-point  data
              will  be  displayed  with  float_digits  significant  digits.  If double_digits is also specified,
              double-precision values will be displayed with that many significant digits.  If a variable has  a
              `C_format'  attribute, that overrides any specified floating-point default.  In the absence of any
              -d  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 -d 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:

              ncdump -v uwind,vwind -d 3 foo.nc

       Produce a fully-annotated (one data value per line) listing 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 ALSO

       ncgen(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 values for `record' variables together that have the same value of the record dimension.