xenial (1) ncdump.1.gz

Provided by: netcdf-bin_4.4.0-2_amd64 bug

NAME

       ncdump - Convert netCDF file to text form (CDL)

SYNOPSIS

       ncdump  [-chistxw]  [-v  var1,...]   [-b  lang] [-f lang] [-l len] [-n name] [-p f_digits[,d_digits]] [-g
              grp1,...]  file

       ncdump -k file

DESCRIPTION

       The ncdump utility generates a text representation  of  a  specified  netCDF  file  on  standard  output,
       optionally  excluding  some  or  all of the variable data in the output.  The text representation is in a
       form called CDL (network Common Data form Language) that can be viewed, edited,  or  serve  as  input  to
       ncgen,  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  text
       representations.  See ncgen documentation for a description of CDL and netCDF representations.

       ncdump  may  also be used to determine what kind of netCDF file is used (which variant of the netCDF file
       format) with the -k option.

       If DAP support was enabled when ncdump was built, the file name may specify a DAP URL. This allows ncdump
       to access data sources from DAP servers, including data in other formats than netCDF.  When used with DAP
       URLs, ncdump shows the translation from the DAP data model to the netCDF data model.

       ncdump may also be used as a simple browser for netCDF data files, to display  the  dimension  names  and
       lengths;  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.  For  netCDF-4  files,  groups  and  user-
       defined types are also included in ncdump output.

       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 variable has no  `_FillValue'  attribute,
       the default fill value for the variable type is used unless the variable is of byte type.

       ncdump  defines  a default display 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"

OPTIONS

       -c     Show the values of coordinate variables (1D variables with the same names as dimensions)  as  well
              as  the  declarations  of  all  dimensions,  variables, attribute values, groups, and user-defined
              types.  Data values of non-coordinate variables are not included in the output.  This  is  usually
              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, output only the declarations for the
              dimensions, variables, attributes, groups, and user-defined types of the input file, 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,...
              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  unescaped  blanks  or  other  white space characters.  The named
              variables must be valid netCDF variables in the input-file.   A  variable  within  a  group  in  a
              netCDF-4  file may be specified with an absolute path name, such as `/GroupA/GroupA2/var'.  Use of
              a relative path name such as `var' or `grp/var' specifies all matching variable names in the 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 [c|f]
              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 may be useful for browsing through large volumes of multidimensional data.

       -f [c|f]
              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.  If  lang
              begins  with `F' or `f', then Fortran language conventions will be used.  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. (At most one of '-b' or '-f' options may be present.)

       -l length
              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 file, for use by ncgen -b in generating a default netCDF file
              name.  By default, ncdump constructs this name from the last component of the  file  name  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 inadvertently 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
              double precision data values for attributes and variables.  If specified, this value overrides the
              value  of  the  C_format attribute, if any, for a variable.  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.  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 precisions are specified, the two values must appear separated  by  a  comma  (no
              blanks)  as  a single argument to the command.  (To represent every last bit of precision in a CDL
              file for all possible floating-point values would require -p 9,17.)

       -k     Show kind of netCDF file the pathname references, one of `classic', `64-bit offset',`netCDF-4', or
              `netCDF-4  classic model'.  Before version 3.6, there was only one kind of netCDF file, designated
              as `classic' (also know as format variant 1).  Large file support introduced  another  variant  of
              the  format,  designated  as  `64-bit offset' (known as format variant 2).  NetCDF-4, uses a third
              variant of the  format,  `netCDF-4'  (format  variant  3).   Another  format  variant,  designated
              `netCDF-4  classic  model' (format variant 4), is restricted to features supported by the netCDF-3
              data model but represented using the HDF5 format, so that an unmodified netCDF-3 program can  read
              or  write  the  file  just by relinking with the netCDF-4 library.  The string output by using the
              `-k' option may be provided as the value of the `-k' option to ncgen(1) to  specify  exactly  what
              kind of netCDF file to generate, when you want to override the default inferred from the CDL.

       -s     Output  special  virtual  attributes  that  provide performance-related information about the file
              format and variable properties for netCDF-4  data.   These  special  virtual  attributes  are  not
              actually part of the data, they are merely a convenient way to display miscellaneous properties of
              the  data  in  CDL  (and  eventually  NcML).    They   include   `_ChunkSizes',   `_DeflateLevel',
              `_Endianness',  `_Fletcher32', `_Format', `_NoFill', `_Shuffle', and `_Storage'.  `_ChunkSizes' is
              a list of chunk sizes for each dimension of the variable.  `_DeflateLevel' is an integer between 0
              and  9  inclusive  if  compression  has  been specified for the variable.  `_Endianness' is either
              `little' or `big', depending on how the variable was stored when first written.  `_Fletcher32'  is
              `true'  if  the  checksum  property  was  set  for  the variable.  `_Format' is a global attribute
              specifying the netCDF format variant, one of `classic', `64-bit offset', `netCDF-4', or  `netCDF-4
              classic  model'.   `_NoFill'  is `true' if the persistent NoFill property was set for the variable
              when it was defined.  `_Shuffle' is `true' if use of the shuffle  filter  was  specified  for  the
              variable.   `_Storage'  is  `contiguous'  or  `chunked',  depending  on how the variable's data is
              stored.

       -t     Controls display of time data, if stored  in  a  variable  that  uses  a  udunits  compliant  time
              representation  such as `days since 1970-01-01' or `seconds since 2009-03-15 12:01:17', a variable
              identified in a "bounds" attribute of such a time variable, or  a  numeric  attribute  of  a  time
              variable.  If this option is specified, time data values are displayed as human-readable date-time
              strings rather than numerical values, interpreted in terms of a `calendar' variable attribute,  if
              specified.   For  numeric attributes of time variables, the human-readable time value is displayed
              after the actual value, in an associated CDL comment.  Calendar attribute values interpreted  with
              this  option  include  the CF Conventions values `gregorian' or `standard', `proleptic_gregorian',
              `noleap' or `365_day', `all_leap' or `366_day', `360_day', and `julian'.

       -i     Same as the '-t' option, except output time data as date-time strings with ISO-8601  standard  'T'
              separator, instead of a blank.

       -g grp1,...
              For  netCDF-4  files,  the  output will include data values only for the specified groups.  One or
              more groups must be specified by name in the comma-delimited list following this option. The  list
              must  be  a  single  argument  to the command. The named groups must be valid netCDF groups in the
              input-file.  A group in a netCDF-4 file may be specified with an absolute or relative  path  name.
              Use  of a relative path name specifies all matching group names in the file.  The default, without
              this option and in the absence of the -c or -h options, is to include data values for  all  groups
              in the output.

       -w     For  file names that request remote access using DAP URLs, access data with client-side caching of
              entire variables.

       -x     Output XML (NcML) instead of CDL.  The NcML does not include data values.  The NcML output  option
              currently only works for netCDF classic model data.

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 -p 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

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.