MINCDUMP(1)

🎀 MINCDUMP(1) 🎀

okay bestie, welcome to the MINC User's Guide corner of the internet, where we're talking about mincdump — the little icon that turns your minc files into ASCII. let's get into it 💅

---

✨ 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 💖

so mincdump is literally built on top of the netCDF tool ncdump, but it got modified so it works with both MINC 1 (netCDF) and MINC 2 (HDF5) format files. it's mostly meant to be used with scripts like mincdiff and mincheader (iykyk). and because it wasn't created at the Montreal Neurological Institute, it does not follow the usual conventions for MINC programs. not like other girls, periodt.

mincdump generates an ASCII representation of a specified minc file on standard output. that ASCII representation is in a form called CDL (aka ``network Common Data form Language'') that you can view, edit, or feed straight into ncgen. and ncgen is the companion program that can generate a binary minc file from a CDL file. so like… ncgen and mincdump can be used as inverses of each other to transform the data representation back and forth between binary and ASCII. it's giving main characters in a buddy movie 🫶. for a description of CDL and netCDF representations, go check out ncgen.

mincdump defines a default format for each type of netCDF data, but you can change that if a C_format attribute is defined for a netCDF variable. in that case, mincdump will use the C_format attribute to format each value. example time: if floating-point data for the netCDF variable Z is known to be accurate to only three significant digits, you'd want to use the variable attribute

              Z:C_format = "%.3g"

mincdump can also just be a lil simple browser for netCDF data files, showing you the dimension names and sizes; variable names, types, and shapes; attribute names and values; and optionally the values of data for all variables, or just the variables you picked. lowkey a whole tour guide 🌈

about fill values: mincdump uses _ to represent data values that are equal to the NC_FillValue attribute for a variable — that's the vibe for data that hasn't been written yet. if a variable has no NC_FillValue attribute, the default fill value for the variable type is used, as long as the variable is not of byte type. 💜

---

💅 OPTIONS 💅

• -c — show the values of the coordinate variables (those are variables that are also dimensions) plus the declarations of all dimensions, variables, and attribute values. data values of non-coordinate variables are not included. this is the most suitable option for a quick lil peek at the structure and contents of a netCDF file. it's giving "just the highlights" ✨
• -h — only show the header info in the output, meaning the declarations of dimensions, variables, and attributes, but no data values for any variables. the output is identical to using the -c option, except the values of coordinate variables are not included. (heads up: at most one of -c or -h may be present. pick one. choose your fighter.)
• -v var1,...,varn — the output will include data values for the specified variables, on top of the declarations of all dimensions, variables, and attributes. you must name one or more variables in the comma-delimited list following this option. important: the list has to be a single argument to the command, so it cannot contain blanks or any other white space characters. also the named variables must be valid netCDF variables in the input-file. the default, when you don't use this option and there's no -c or -h, is to include data values for all variables in the output. go big or go partial 🍓
• -b lang — a brief annotation, formatted as a CDL comment (text starting with the characters ``//''), gets 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 Corc, then C language conventions are used (zero-based indices, last dimension varying fastest). if *lang* begins with Forf`, then Fortran language conventions are used (one-based indices, first dimension varying fastest). either way, the data is presented in the same order — only the annotations 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) get included in the data section. if lang begins with C or c, C language conventions are used (zero-based indices, last dimension varying fastest). if lang begins with F or f, Fortran language conventions are used (one-based indices, first dimension varying fastest). again: the data is presented in the same order in either case, only the annotations differ. this one's great for piping data into other filters, since each data value appears on its own separate line, fully identified. so organized of it 😭
• -l len — changes the default maximum line length (which is 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, mincdump constructs this name from the last component of the pathname of the input netCDF file, stripping off any extension it has. use the -n option to specify a different name. even though the output file name used by ncgen -b can be specified, it may be wise to have mincdump change the default name so you avoid inadvertently overwriting a valuable netCDF file when you use mincdump, edit the resulting CDL file, and then use ncgen -b to generate a new netCDF file from that edited CDL file. protect your files bestie 🫶
• -p float_digits[,double_digits] — specifies the default precision (number of significant digits) to use when displaying floating-point or double precision data values for attributes 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-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 you specify both the floating-point and double-precision precisions, the two values must appear separated by a comma (no blanks) as a single argument to the command. and if you truly want every last bit of precision from the netCDF file represented in the CDL file for all possible floating-point values, you'll have to specify it with -p 9,17 (according to Theorem 15 of the paper listed under REFERENCES, no cap 📚).

---

🌸 EXAMPLES 🌸

wanna look at the structure of the data in the netCDF file foo.mnc? say less:

              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 Corporation for Atmospheric Research. 💖

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

---

⭐ COPYRIGHTS ⭐

Copyright © 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. it's giving flop syntax ngl
• there should be a way to specify that the data should be displayed in record' order — that is, with all the values for record' variables together that have the same value of the record dimension. we're manifesting this feature 🙈

---

and that's the whole page, bestie! this one's from the MINC User's Guide, stamped $Date: 2004-05-20 21:52:08 $, and it is, of course, MINCDUMP(1). slay 💅✨