1NCDUMP(1) UNIDATA UTILITIES NCDUMP(1)
2
6 ncdump - Convert netCDF file to text form (CDL)
7
9 ncdump [-chistxwF] [-v var1,...] [-b lang] [-f lang] [-l len] [-n
10 name] [-p f_digits[,d_digits]] [-g grp1,...] file
11 ncdump -k file
13
15 The ncdump utility generates a text representation of a specified
16 netCDF file on standard output, optionally excluding some or all of the
17 variable data in the output. The text representation is in a form
18 called CDL (network Common Data form Language) that can be viewed,
19 edited, or serve as input to ncgen, a companion program that can gener‐
20 ate a binary netCDF file from a CDL file. Hence ncgen and ncdump can
21 be used as inverses to transform the data representation between binary
22 and text representations. See ncgen documentation for a description of
23 CDL and netCDF representations.
24 ncdump may also be used to determine what kind of netCDF file is used
26 (which variant of the netCDF file format) with the -k option.
27 If DAP support was enabled when ncdump was built, the file name may
29 specify a DAP URL. This allows ncdump to access data sources from DAP
30 servers, including data in other formats than netCDF. When used with
31 DAP URLs, ncdump shows the translation from the DAP data model to the
32 netCDF data model.
33 ncdump may also be used as a simple browser for netCDF data files, to
35 display the dimension names and lengths; variable names, types, and
36 shapes; attribute names and values; and optionally, the values of data
37 for all variables or selected variables in a netCDF file. For netCDF-4
38 files, groups and user-defined types are also included in ncdump out‐
39 put.
40 ncdump uses `_' to represent data values that are equal to the `_Fill‐
42 Value' attribute for a variable, intended to represent data that has
43 not yet been written. If a variable has no `_FillValue' attribute, the
44 default fill value for the variable type is used unless the variable is
45 of byte type.
46 ncdump defines a default display format used for each type of netCDF
48 data, but this can be changed if a `C_format' attribute is defined for
49 a netCDF variable. In this case, ncdump will use the `C_format' attri‐
50 bute to format each value. For example, if floating-point data for the
51 netCDF variable `Z' is known to be accurate to only three significant
52 digits, it would be appropriate to use the variable attribute
53 Z:C_format = "%.3g"
56
58 -c Show the values of coordinate variables (1D variables with the
59 same names as dimensions) as well as the declarations of all di‐
60 mensions, variables, attribute values, groups, and user-defined
61 types. Data values of non-coordinate variables are not included
62 in the output. This is usually the most suitable option to use
63 for a brief look at the structure and contents of a netCDF file.
64 -h Show only the header information in the output, that is, output
66 only the declarations for the dimensions, variables, attributes,
67 groups, and user-defined types of the input file, but no data
68 values for any variables. The output is identical to using the
69 -c option except that the values of coordinate variables are not
70 included. (At most one of -c or -h options may be present.)
71 -v var1,...
73 The output will include data values for the specified variables,
74 in addition to the declarations of all dimensions, variables,
75 and attributes. One or more variables must be specified by name
76 in the comma-delimited list following this option. The list
77 must be a single argument to the command, hence cannot contain
78 unescaped blanks or other white space characters. The named
79 variables must be valid netCDF variables in the input-file. A
80 variable within a group in a netCDF-4 file may be specified with
81 an absolute path name, such as `/GroupA/GroupA2/var'. Use of a
82 relative path name such as `var' or `grp/var' specifies all
83 matching variable names in the file. The default, without this
84 option and in the absence of the -c or -h options, is to include
85 data values for all variables in the output.
86 -b [c|f]
88 A brief annotation in the form of a CDL comment (text beginning
89 with the characters ``//'') will be included in the data section
90 of the output for each `row' of data, to help identify data val‐
91 ues for multidimensional variables. If lang begins with `C' or
92 `c', then C language conventions will be used (zero-based in‐
93 dices, last dimension varying fastest). If lang begins with `F'
94 or `f', then Fortran language conventions will be used (one-
95 based indices, first dimension varying fastest). In either
96 case, the data will be presented in the same order; only the an‐
97 notations will differ. This option may be useful for browsing
98 through large volumes of multidimensional data.
99 -f [c|f]
101 Full annotations in the form of trailing CDL comments (text be‐
102 ginning with the characters ``//'') for every data value (except
103 individual characters in character arrays) will be included in
104 the data section. If lang begins with `C' or `c', then C lan‐
105 guage conventions will be used. If lang begins with `F' or `f',
106 then Fortran language conventions will be used. In either case,
107 the data will be presented in the same order; only the annota‐
108 tions will differ. This option may be useful for piping data
109 into other filters, since each data value appears on a separate
110 line, fully identified. (At most one of '-b' or '-f' options may
111 be present.)
112 -l length
114 Changes the default maximum line length (80) used in formatting
115 lists of non-character data values.
116 -n name
118 CDL requires a name for a netCDF file, for use by ncgen -b in
119 generating a default netCDF file name. By default, ncdump con‐
120 structs this name from the last component of the file name of
121 the input netCDF file by stripping off any extension it has.
122 Use the -n option to specify a different name. Although the
123 output file name used by ncgen -b can be specified, it may be
124 wise to have ncdump change the default name to avoid inadver‐
125 tently overwriting a valuable netCDF file when using ncdump,
126 editing the resulting CDL file, and using ncgen -b to generate a
127 new netCDF file from the edited CDL file.
128 -p float_digits[,double_digits]
130 Specifies default precision (number of significant digits) to
131 use in displaying floating-point or double precision data values
132 for attributes and variables. If specified, this value over‐
133 rides the value of the C_format attribute, if any, for a vari‐
134 able. Floating-point data will be displayed with float_digits
135 significant digits. If double_digits is also specified, double-
136 precision values will be displayed with that many significant
137 digits. In the absence of any -p specifications, floating-point
138 and double-precision data are displayed with 7 and 15 signifi‐
139 cant digits respectively. CDL files can be made smaller if less
140 precision is required. If both floating-point and double preci‐
141 sions are specified, the two values must appear separated by a
142 comma (no blanks) as a single argument to the command. (To rep‐
143 resent every last bit of precision in a CDL file for all possi‐
144 ble floating-point values would require -p 9,17.)
145 -k Show kind of netCDF file the pathname references, one of `clas‐
147 sic', `64-bit offset',`netCDF-4', or `netCDF-4 classic model'.
148 Before version 3.6, there was only one kind of netCDF file, des‐
149 ignated as `classic' (also know as format variant 1). Large
150 file support introduced another variant of the format, designat‐
151 ed as `64-bit offset' (known as format variant 2). NetCDF-4,
152 uses a third variant of the format, `netCDF-4' (format variant
153 3). Another format variant, designated `netCDF-4 classic model'
154 (format variant 4), is restricted to features supported by the
155 netCDF-3 data model but represented using the HDF5 format, so
156 that an unmodified netCDF-3 program can read or write the file
157 just by relinking with the netCDF-4 library. The string output
158 by using the `-k' option may be provided as the value of the
159 `-k' option to ncgen(1) to specify exactly what kind of netCDF
160 file to generate, when you want to override the default inferred
161 from the CDL.
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 `com‐
182 pact' or `chunked', depending on how the variable's data is
183 stored.
184 -t Controls display of time data, if stored in a variable that uses
186 a udunits compliant time representation such as `days since
187 1970-01-01' or `seconds since 2009-03-15 12:01:17', a variable
188 identified in a "bounds" attribute of such a time variable, or a
189 numeric attribute of a time variable. If this option is speci‐
190 fied, time data values are displayed as human-readable date-time
191 strings rather than numerical values, interpreted in terms of a
192 `calendar' variable attribute, if specified. For numeric at‐
193 tributes of time variables, the human-readable time value is
194 displayed after the actual value, in an associated CDL comment.
195 Calendar attribute values interpreted with this option include
196 the CF Conventions values `gregorian' or `standard', `prolep‐
197 tic_gregorian', `noleap' or `365_day', `all_leap' or `366_day',
198 `360_day', and `julian'.
199 -i Same as the '-t' option, except output time data as date-time
201 strings with ISO-8601 standard 'T' separator, instead of a
202 blank.
203 -g grp1,...
205 For netCDF-4 files, the output will include data values only for
206 the specified groups. One or more groups must be specified by
207 name in the comma-delimited list following this option. The list
208 must be a single argument to the command. The named groups must
209 be valid netCDF groups in the input-file. A group in a netCDF-4
210 file may be specified with an absolute or relative path name.
211 Use of a relative path name specifies all matching group names
212 in the file. The default, without this option and in the ab‐
213 sence of the -c or -h options, is to include data values for all
214 groups in the output.
215 -w For file names that request remote access using DAP URLs, access
217 data with client-side caching of entire variables.
218 -x Output XML (NcML) instead of CDL. The NcML does not include da‐
220 ta values. The NcML output option currently only works for
221 netCDF classic model data.
222 -F Use _Filter and _Codecs attributes in place of _Fletcher32,
224 _Shuffle, and _Deflate.
225
227 Look at the structure of the data in the netCDF file `foo.nc':
228 ncdump -c foo.nc
230 Produce an annotated CDL version of the structure and data in the
232 netCDF file `foo.nc', using C-style indexing for the annotations:
233 ncdump -b c foo.nc > foo.cdl
235 Output data for only the variables `uwind' and `vwind' from the netCDF
237 file `foo.nc', and show the floating-point data with only three signif‐
238 icant digits of precision:
239 ncdump -v uwind,vwind -p 3 foo.nc
241 Produce a fully-annotated (one data value per line) listing of the data
243 for the variable `omega', using Fortran conventions for indices, and
244 changing the netCDF dataset name in the resulting CDL file to `omega':
245 ncdump -v omega -f fortran -n omega foo.nc > Z.cdl
247
249 ncgen(1), netcdf(3)
250
252 Character arrays that contain a null-byte are treated like C strings,
253 so no characters after the null byte appear in the output.
254 Multidimensional character string arrays are not handled well, since
256 the CDL syntax for breaking a long character string into several short‐
257 er lines is weak.
258 There should be a way to specify that the data should be displayed in
260 `record' order, that is with the all the values for `record' variables
261 together that have the same value of the record dimension.
262Release 4.2 2012-03-08 NCDUMP(1)