1NCDUMP(1) UNIDATA UTILITIES NCDUMP(1)
2
6 ncdump - Convert netCDF file to text form (CDL)
7
9 ncdump [-c] [-h] [-v var1,...] [-b lang] [-f lang] [-l len] [-n name]
10 [-p f_digits[,d_digits]] [-k] [-x] [-s] [-t] file
11
13 ncdump generates a text representation of a specified netCDF file on
14 standard output. The text representation is in a form called CDL
15 (``network Common Data form Language'') that can be viewed, edited, or
16 serve as input to ncgen. ncgen is a companion program that can gener‐
17 ate a binary netCDF file from a CDL file. Hence ncgen and ncdump can
18 be used as inverses to transform the data representation between binary
19 and text representations. See ncgen for a description of CDL and
20 netCDF representations.
21 As of NetCDF version 4.1, and if DAP support was enabled when ncdump
23 was built, the file name may specify a DAP URL. This allows ncdump to
24 print out data sources from DAP servers. When used with the -h option,
25 ncdump can be used to show the translation from the DAP DDS data model
26 to the NetCDF data model.
27 ncdump defines a default display format used for each type of netCDF
29 data, but this can be changed if a `C_format' attribute is defined for
30 a netCDF variable. In this case, ncdump will use the `C_format' at‐
31 tribute to format each value. For example, if floating-point data for
32 the netCDF variable `Z' is known to be accurate to only three signifi‐
33 cant digits, it would be appropriate to use the variable attribute
34 Z:C_format = "%.3g"
36 ncdump may also be used as a simple browser for netCDF data files, to
38 display the dimension names and sizes; variable names, types, and
39 shapes; attribute names and values; and optionally, the values of data
40 for all variables or selected variables in a netCDF file.
41 ncdump uses `_' to represent data values that are equal to the `_Fill‐
43 Value' attribute for a variable, intended to represent data that has
44 not yet been written. If a variable has no `_FillValue' attribute, the
45 default fill value for the variable type is used if the variable is not
46 of byte type.
47 ncdump may also be used to determine what kind of netCDF file is used
49 (which variant of the netCDF file format) with the -k option.
50
52 -c Show the values of coordinate variables (variables that are also
53 dimensions) as well as the declarations of all dimensions, vari‐
54 ables, and attribute values. Data values of non-coordinate
55 variables are not included in the output. This is the most
56 suitable option to use for a brief look at the structure and
57 contents of a netCDF file.
58 -h Show only the header information in the output, that is the dec‐
60 larations of dimensions, variables, and attributes but no data
61 values for any variables. The output is identical to using the
62 -c option except that the values of coordinate variables are not
63 included. (At most one of -c or -h options may be present.)
64 -v var1,...,varn
66 The output will include data values for the specified variables,
67 in addition to the declarations of all dimensions, variables,
68 and attributes. One or more variables must be specified by name
69 in the comma-delimited list following this option. The list
70 must be a single argument to the command, hence cannot contain
71 blanks or other white space characters unless escaped. The
72 named variables must be valid netCDF variables in the input-
73 file. A variable within a group in a netCDF-4 file may be spec‐
74 ified with an absolute pathname, such as `/GroupA/GroupA2/var'.
75 Use of a relative pathname such as `var' or `grp/var' specifies
76 all matching variable names in the file. The default, without
77 this option and in the absence of the -c or -h options, is to
78 include data values for all variables in the output.
79 -b lang
81 A brief annotation in the form of a CDL comment (text beginning
82 with the characters ``//'') will be included in the data section
83 of the output for each `row' of data, to help identify data val‐
84 ues for multidimensional variables. If lang begins with `C' or
85 `c', then C language conventions will be used (zero-based in‐
86 dices, last dimension varying fastest). If lang begins with `F'
87 or `f', then Fortran language conventions will be used (one-
88 based indices, first dimension varying fastest). In either
89 case, the data will be presented in the same order; only the an‐
90 notations will differ. This option is useful for browsing
91 through large volumes of multidimensional data.
92 -f lang
94 Full annotations in the form of trailing CDL comments (text be‐
95 ginning with the characters ``//'') for every data value (except
96 individual characters in character arrays) will be included in
97 the data section. If lang begins with `C' or `c', then C lan‐
98 guage conventions will be used (zero-based indices, last dimen‐
99 sion varying fastest). If lang begins with `F' or `f', then
100 Fortran language conventions will be used (one-based indices,
101 first dimension varying fastest). In either case, the data will
102 be presented in the same order; only the annotations will dif‐
103 fer. This option may be useful for piping data into other fil‐
104 ters, since each data value appears on a separate line, fully
105 identified.
106 -l len Changes the default maximum line length (80) used in formatting
108 lists of non-character data values.
109 -n name
111 CDL requires a name for a netCDF data set, for use by ncgen -b
112 in generating a default netCDF file name. By default, ncdump
113 constructs this name from the last component of the pathname of
114 the input netCDF file by stripping off any extension it has.
115 Use the -n option to specify a different name. Although the
116 output file name used by ncgen -b can be specified, it may be
117 wise to have ncdump change the default name to avoid inadver‐
118 tantly overwriting a valuable netCDF file when using ncdump,
119 editing the resulting CDL file, and using ncgen -b to generate a
120 new netCDF file from the edited CDL file.
121 -p float_digits[,double_digits]
123 Specifies default precision (number of significant digits) to
124 use in displaying floating-point or double precision data values
125 for attributes and variables. If specified, this value over‐
126 rides the value of the `C_format' attribute for any variable
127 that has such an attribute. Floating-point data will be dis‐
128 played with float_digits significant digits. If double_digits
129 is also specified, double-precision values will be displayed
130 with that many significant digits. In the absence of any -p
131 specifications, floating-point and double-precision data are
132 displayed with 7 and 15 significant digits respectively. CDL
133 files can be made smaller if less precision is required. If
134 both floating-point and double-presision precisions are speci‐
135 fied, the two values must appear separated by a comma (no
136 blanks) as a single argument to the command. If you really want
137 every last bit of precision from the netCDF file represented in
138 the CDL file for all possible floating-point values, you will
139 have to specify this with -p 9,17 (according to Theorem 15 of
140 the paper listed under REFERENCES).
141 -k Show what kind of netCDF file the pathname references, one of
143 `classic', `64-bit offset',`netCDF-4', or `netCDF-4 classic mod‐
144 el'. Before version 3.6, there was only one kind of netCDF
145 file, designated as `classic' (also know as format variant 1).
146 Large file support introduced another variant of the format,
147 designated as `64-bit offset' (known as format variant 2).
148 NetCDF-4, uses a third variant of the format, `netCDF-4' (format
149 variant 3). Another format variant, designated `netCDF-4 clas‐
150 sic model' (format variant 4), is restricted to features sup‐
151 ported by the netCDF-3 data model but represented using the HDF5
152 format, so that an unmodified netCDF-3 program can read or write
153 the file just by relinking with the netCDF-4 library. The
154 string output by using the `-k' option may be provided as the
155 value of the `-k' option to ncgen(1) to specify exactly what
156 kind of netCDF file to generate, when you want to override the
157 default inferred from the CDL.
158 -x Output XML (NcML) instead of CDL. The NcML does not include da‐
160 ta values. The NcML output option doesn't yet display netCDF-4
161 data correctly.
162 -s Output special virtual attributes that provide performance-re‐
164 lated information about the file format and variable properties
165 for netCDF-4 data. These special virtual attributes are not ac‐
166 tually part of the data, they are merely a convenient way to
167 display miscellaneous properties of the data in CDL (and eventu‐
168 ally NcML). They include `_ChunkSizes', `_DeflateLevel', `_En‐
169 dianness', `_Fletcher32', `_Format', `_NoFill', `_Shuffle', and
170 `_Storage'. `_ChunkSizes' is a list of chunk sizes for each di‐
171 mension of the variable. `_DeflateLevel' is an integer between
172 0 and 9 inclusive if compression has been specified for the
173 variable. `_Endianness' is either `little' or `big', depending
174 on how the variable was stored when first written. `_Fletch‐
175 er32' is `true' if the checksum property was set for the vari‐
176 able. `_Format' is a global attribute specifying the netCDF
177 format variant, one of `classic', `64-bit offset', `netCDF-4',
178 or `netCDF-4 classic model'. `_NoFill' is `true' if the persis‐
179 tent NoFill property was set for the variable when it was de‐
180 fined. `_Shuffle' is `true' if use of the shuffle filter was
181 specified for the variable. `_Storage' is `contiguous' or
182 `chunked', depending on how the variable's data is stored.
183 -t Controls display of time data, if stored in a variable that uses
185 a udunits compliant time representation such as `days since
186 1970-01-01' or `seconds since 2009-03-15 12:01:17'. If this op‐
187 tion is specified, time values are displayed as human-readable
188 date-time strings rather than numerical values, interpreted in
189 terms of a `calendar' variable attribute, if specified. Calen‐
190 dar attribute values interpreted with this option include the CF
191 Conventions values `gregorian' or `standard', `proleptic_grego‐
192 rian', `noleap' or `365_day', `all_leap' or `366_day',
193 `360_day', or `julian'.
194
196 Look at the structure of the data in the netCDF file `foo.nc':
197 ncdump -c foo.nc
199 Produce an annotated CDL version of the structure and data in the
201 netCDF file `foo.nc', using C-style indexing for the annotations:
202 ncdump -b c foo.nc > foo.cdl
204 Output data for only the variables `uwind' and `vwind' from the netCDF
206 file `foo.nc', and show the floating-point data with only three signif‐
207 icant digits of precision:
208 ncdump -v uwind,vwind -p 3 foo.nc
210 Produce a fully-annotated (one data value per line) listing of the data
212 for the variable `omega', using Fortran conventions for indices, and
213 changing the netCDF dataset name in the resulting CDL file to `omega':
214 ncdump -v omega -f fortran -n omega foo.nc > Z.cdl
216
218 What Every Computer Scientist should Know About Floating-Point Arith‐
219 metic, D. Goldberg, ACM Computing Surveys, Vol. 23, No. 1, March 1991,
220 pp. 5-48. Climate and Forecast Metadata Conventions, http://www.cf‐
221 conventions.org.
222
224 ncgen(1), netcdf(3)
225
227 Character arrays that contain a null-byte are treated like C strings,
228 so no characters after the null byte appear in the output.
229 Multidimensional character string arrays are not handled well, since
231 the CDL syntax for breaking a long character string into several short‐
232 er lines is weak.
233 There should be a way to specify that the data should be displayed in
235 `record' order, that is with the all the values for `record' variables
236 together that have the same value of the record dimension.
237Printed: 119-6-22 $Date: 2009/07/28 14:48:36 $ NCDUMP(1)