Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
NCDUMP(1)		       UNIDATA UTILITIES		     NCDUMP(1)

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	gener-
       ate  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 out-
       put.

       ncdump uses `_' to represent data values	that are equal to the  `_Fill-
       Value'  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'	attri-
       bute 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 di-
	      mensions,	 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 val-
	      ues for multidimensional variables.  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	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 an-
	      notations	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 be-
	      ginning 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  lan-
	      guage 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 annota-
	      tions 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 con-
	      structs 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  inadver-
	      tently  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 over-
	      rides the	value of the C_format attribute, if any, for  a	 vari-
	      able.   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 signifi-
	      cant digits respectively.	 CDL files can be made smaller if less
	      precision	is required.  If both floating-point and double	preci-
	      sions are	specified, the two values must appear separated	 by  a
	      comma (no	blanks)	as a single argument to	the command.  (To rep-
	      resent every last	bit of precision in a CDL file for all	possi-
	      ble floating-point values	would require -p 9,17.)

       -k     Show  kind of netCDF file	the pathname references, one of	`clas-
	      sic', `64-bit offset',`netCDF-4',	or `netCDF-4  classic  model'.
	      Before version 3.6, there	was only one kind of netCDF file, des-
	      ignated as `classic' (also know as  format  variant  1).	 Large
	      file support introduced another variant of the format, designat-
	      ed 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-re-
	      lated  information about the file	format and variable properties
	      for netCDF-4 data.  These	special	virtual	attributes are not ac-
	      tually  part  of	the  data, they	are merely a convenient	way to
	      display miscellaneous properties of the data in CDL (and eventu-
	      ally  NcML).  They include `_ChunkSizes',	`_DeflateLevel', `_En-
	      dianness', `_Fletcher32',	`_Format', `_NoFill', `_Shuffle',  and
	      `_Storage'.  `_ChunkSizes' is a list of chunk sizes for each di-
	      mension 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.  `_Fletch-
	      er32' is `true' if the checksum property was set for  the	 vari-
	      able.   `_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 persis-
	      tent NoFill property was set for the variable when  it  was  de-
	      fined.   `_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	speci-
	      fied, 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  at-
	      tributes	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',  `prolep-
	      tic_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 ab-
	      sence 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 da-
	      ta  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 signif-
       icant 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	short-
       er 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.

Release	4.2			  2012-03-08			     NCDUMP(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | SEE ALSO | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ncdump&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help