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

FreeBSD Manual Pages

  
 
  

home | help
NCMPIDUMP(1)			   UTILITIES			  NCMPIDUMP(1)

NAME
       ncmpidump - Convert netCDF files	to ASCII form (CDL)

SYNOPSIS
       ncmpidump  [-ch]	 [-v var1,...]	[-b lang] [-f lang] [-l	len] [-n name]
	      [-p f_digits[,d_digits]] file

       ncmpidump -k file

DESCRIPTION
       ncmpidump 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 ncmpigen.  ncmpigen is a companion program that can
       generate	a binary netCDF	file from a  CDL  file.	  Hence	 ncmpigen  and
       ncmpidump  can be used as inverses to transform the data	representation
       between binary and ASCII	representations.  See ncmpigen for a  descrip-
       tion of CDL and netCDF representations.

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

       ncmpidump 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, ncmpidump will use the  `C_format'  at-
       tribute	to format each value.  For example, if floating-point data for
       the netCDF variable `Z' is known	to be accurate to only three  signifi-
       cant digits, it would be	appropriate to use the variable	attribute

	      Z:C_format = "%.3g"

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

       ncmpidump 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 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 declarations of all dimensions, vari-
	      ables, 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 dec-
	      larations	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 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  is	 useful	 for  browsing
	      through large volumes of multidimensional	data.

       -f lang
	      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 (zero-based indices, last	dimen-
	      sion 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 dif-
	      fer.  This option	may be useful for piping data into other  fil-
	      ters,  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 ncmpigen
	      -b in generating	a  default  netCDF  file  name.	  By  default,
	      ncmpidump	 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 ncmpigen -b  can  be	speci-
	      fied,  it	 may be	wise to	have ncmpidump change the default name
	      to avoid inadvertantly overwriting a valuable netCDF  file  when
	      using  ncmpidump,	 editing  the  resulting  CDL  file, and using
	      ncmpigen -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  for	 any  variable
	      that  has	 such  an attribute.  Floating-point data will be dis-
	      played 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-presision precisions  are	speci-
	      fied,  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).

       -k     Reports the kind of netCDF  file:	 classic,  64-bit  offset,  or
	      64-bit data.  Before netCDF version 3.6, there was only one kind
	      of netCDF	file, designated as `classic'  (also  know  as	format
	      variant  1  or  CDF-1).	Large  file support introduced another
	      variant of the format, designated	as `64-bit offset'  (known  as
	      format  variant  2 or CDF-2).  Large data	support	introduced an-
	      other variant of the format, designated as `64-bit data'	(known
	      as format	variant	5 or CDF-5).

EXAMPLES
       Look at the structure of	the data in the	netCDF file `foo.nc':

	      ncmpidump	-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:

	      ncmpidump	-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:

	      ncmpidump	-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':

	      ncmpidump	-v omega -f fortran -n omega foo.nc > Z.cdl

REFERENCES
	What Every Computer Scientist should Know About	Floating-Point	Arith-
       metic, D.  Goldberg, ACM	Computing Surveys, Vol.	23, No.	1, March 1991,
       pp. 5-48.

SEE ALSO
       ncmpigen(1), pnetcdf(3)

DATE
       $Date: 2013-11-17 00:21:28 -0600	(Sun, 17 Nov 2013) $

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.

Printed: 2019-11-21		  2013-11-17			  NCMPIDUMP(1)

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

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

home | help