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

FreeBSD Manual Pages

  
 
  

home | help 
MINCDUMP(1)			MINC User's Guide		     MINCDUMP(1)

NAME
     mincdump - Convert minc files to ASCII form (CDL)

SYNOPSIS
     mincdump  [-c]  [-h]  [-v var1,...]  [-b lang] [-f lang] [-l len] [-n name]
	    [-p f_digits[,d_digits]] file

DESCRIPTION
     mincdump is based upon the netCDF tool ncdump, modified to work  with  both
     MINC  1  (netCDF)	and  MINC 2 (HDF5) format files.  It is intended for use
     primarily with scripts such as mincdiff and mincheader.  Since it	was  not
     created  at  the  Montreal  Neurological  Insititute it does not follow the
     usual conventions for MINC programs.

     mincdump generates an ASCII representation of  a  specified  minc	file  on
     standard  output.	The ASCII representation is in a form called CDL (``net-
     work 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
     minc file from a CDL file.  Hence ncgen and mincdump can  be  used  as  in-
     verses to transform the data representation between binary and ASCII repre-
     sentations.  See ncgen for a description of CDL and netCDF representations.

     mincdump  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 vari-
     able.  In this case, mincdump 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"

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

     mincdump 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 if the variable  is  not	of  byte
     type.

OPTIONS
     -c     Show the values of coordinate variables (variables that are also di-
	    mensions)  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 declara-
	    tions  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 at-
	    tributes.  One or more variables must be specified by  name  in  the
	    comma-delimited list following this option.  The list must be a sin-
	    gle  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 langA 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 mul-
	    tidimensional variables.  If lang begins with `C'  or  `c',  then  C
	    language  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  dimen-
	    sion  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 langFull annotations in the form of trailing CDL comments  (text  begin-
	    ning  with the characters ``//'') for every data value (except indi-
	    vidual characters in character arrays) will be included in the  data
	    section.   If  lang  begins with `C' or `c', then C language conven-
	    tions 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 nameCDL  requires  a  name for a netCDF data set, for use by ncgen -b in
	    generating a default netCDF file name.  By	default,  mincdump  con-
	    structs this name from the last component of the pathname of the in-
	    put  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 mincdump
	    change the default name to avoid inadvertantly overwriting	a  valu-
	    able  netCDF  file	when  using  mincdump, 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 at-
	    tributes and variables.  If  specified,  this  value  overrides  the
	    value  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, double-pre-
	    cision  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 re-
	    spectively.  CDL files can be made smaller if less precision is  re-
	    quired.   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.mnc':

	    mincdump -c foo.mnc

     Produce  an  annotated  CDL version of the structure and data in the netCDF
     file `foo.mnc', using C-style indexing for the annotations:

	    mincdump -b c foo.mnc > foo.cdl

     Output data for only the variables `uwind' and `vwind' from the netCDF file
     `foo.mnc', and show the floating-point data  with	only  three  significant
     digits of precision:

	    mincdump -v uwind,vwind -p 3 foo.mnc

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

	    mincdump -v omega -f fortran -n omega foo.mnc > Z.cdl

AUTHOR
     Originally written by members of the Unidata Program at the University Cor-
     poration for Atmospheric Research.

     Modified by Bert Vincent (bert@bic.mni.mcgill.ca) for use with both  netCDF
     and HDF5 files.

COPYRIGHTS
     Copyright (C) University Corporation for Atmospheric Research

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
     ncdump(1), 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  to-
     gether that have the same value of the record dimension.

			  $Date: 2004-05-20 21:52:08 $		     MINCDUMP(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=mincdump&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>

home | help