1NCKS(1) General Commands Manual NCKS(1)
2
6 ncks - netCDF Kitchen Sink
7
9 ncks [-A] [-a] [-C] [-c] [-D] [-d dim,[ min][,[ max]][,[ stride]]] [-F]
10 [-H] [-h] [-l path] [-M] [-m] [-O] [-p path] [-q] [-R] [-r] [-s format]
11 [-u] [-v var[,...]] [-x] input-file [ output-file]
12
14 ncks combines selected features of ncdump, ncextr, and the nccut and
15 ncpaste specifications into one versatile utility. ncks extracts a
16 subset of the data from input-file and either prints it as ASCII text
17 to stdout, or writes (or pastes) it to output-file, or both.
18 ncks will print netCDF data in ASCII format to stdout, like ncdump, but
20 with these differences: ncks prints data in a tabular format intended
21 to be easy to search for the data you want, one datum per screen line,
22 with all dimension subscripts and coordinate values (if any) preceding
23 the datum. Option -s allows the user the format the data using C-style
24 format strings.
25 Options -a, -F, -H, -M, -m, -q, -s, and -u control the formatted
27 appearance of the data.
28 ncks will extract (and optionally create a new netCDF file comprised
30 of) only selected variable from the input file, like ncextr but with
31 these differences: Only variables and coordinates may be specifically
32 included or excluded---all global attributes and any attribute associ‐
33 ated with an extracted variable will be copied to the screen and/or
34 output netCDF file. Options -c, -C, -v, and -x control which variables
35 are extracted.
36 ncks will extract hyperslabs from the specified variables. In fact
38 ncks implements the nccut specification exactly. Option -d controls
39 the hyperslab specification.
40 Input dimensions that are not associated with any output variable will
42 not appear in the output netCDF. This feature removes superfluous
43 dimensions from a netCDF file.
44 ncks will append variables and attributes from the input-file to out‐
46 put-file if output-file is a pre-existing netCDF file whose relevant
47 dimensions conform to dimension sizes of input-file. The append fea‐
48 tures of ncks are intended to provide a rudimentary means of adding
49 data from one netCDF file to another, conforming, netCDF file. When
50 naming conflicts exists between the two files, data in output-file is
51 usually overwritten by the corresponding data from input-file. Thus it
52 is recommended that the user backup output-file in case valuable data
53 is accidentally overwritten.
54 If output-file exists, the user will be queried whether to overwrite,
56 append, or exit the ncks call completely. Choosing overwrite destroys
57 the existing output-file and create an entirely new one from the output
58 of the ncks call. Append has differing effects depending on the
59 uniqueness of the variables and attributes output by ncks: If a vari‐
60 able or attribute extracted from input-file does not have a name con‐
61 flict with the members of output-file then it will be added to output-
62 file without overwriting any of the existing contents of output-file.
63 In this case the relevant dimensions must agree (conform) between the
64 two files; new dimensions are created in output-file as required. When
65 a name conflict occurs, a global attribute from input-file will over‐
66 write the corresponding global attribute from output-file. If the name
67 conflict occurs for a non-record variable, then the dimensions and type
68 of the variable (and of its coordinate dimensions, if any) must agree
69 (conform) in both files. Then the variable values (and any coordinate
70 dimension values) from input-file will overwrite the corresponding
71 variable values (and coordinate dimension values, if any) in output-
72 file
73 Since there can only be one record dimension in a file, the record
75 dimension must have the same name (but not necessarily the same size)
76 in both files if a record dimension variable is to be appended. If the
77 record dimensions are of differing sizes, the record dimension of out‐
78 put-file will become the greater of the two record dimension sizes, the
79 record variable from input-file will overwrite any counterpart in out‐
80 put-file and fill values will be written to any gaps left in the rest
81 of the record variables (I think). In all cases variable attributes in
82 output-file are superseded by attributes of the same name from input-
83 file, and left alone if there is no name conflict.
84 Some users may wish to avoid interactive ncks queries about whether to
86 overwrite existing data. For example, batch scripts will fail if ncks
87 does not receive responses to its queries. Options -O and -A are
88 available to force overwriting existing files and variables, respec‐
89 tively.
90 Options specific to ncks
92 The following list provides a short summary of the features unique to
94 ncks.
95 -a Do not alphabetize extracted fields. By default, the specified
97 output variables are extracted, printed, and written to disk in
98 alphabetical order. This tends to make long output lists easier
99 to search for particular variables. Specifying -a results in
100 the variables being extracted, printed, and written to disk in
101 the order in which they were saved in the input file. Thus -a
102 retains the original ordering of the variables.
103 -d dim,[ min][,[ max]][,[ stride]] Add stride argument to hyper‐
105 slabber.
106 -H Print data to screen. The default behavior is to print data to
108 screen if no netCDF output file is specified. Use -H to print
109 data to screen if a netCDF output is specified (the same behav‐
110 ior applies to -m ). Unless otherwise specified (with -s), each
111 element of the data hyperslab is printed on a separate line con‐
112 taining the names, indices, and, values, if any, of all of the
113 variables dimensions. The dimension and variable indices refer
114 to the location of the corresponding data element with respect
115 to the variable as stored on disk (i.e., not the hyperslab).
116 % ncks -H -C -v three_dmn_var in.nc
117 lat[0]=-90 lev[0]=100 lon[0]=0 three_dmn_var[0]=0
118 lat[0]=-90 lev[0]=100 lon[1]=90 three_dmn_var[1]=1
119 lat[0]=-90 lev[0]=100 lon[2]=180 three_dmn_var[2]=2
120 lat[1]=90 lev[2]=1000 lon[1]=90 three_dmn_var[21]=21
121 lat[1]=90 lev[2]=1000 lon[2]=180 three_dmn_var[22]=22
122 lat[1]=90 lev[2]=1000 lon[3]=270 three_dmn_var[23]=23
123 Printing the same variable with the -F option shows the same variable
124 indexed with Fortran conventions
125 % ncks -F -H -C -v three_dmn_var in.nc
126 lon(1)=0 lev(1)=100 lat(1)=-90 three_dmn_var(1)=0
127 lon(2)=90 lev(1)=100 lat(1)=-90 three_dmn_var(2)=1
128 lon(3)=180 lev(1)=100 lat(1)=-90 three_dmn_var(3)=2
129 Printing a hyperslab does not affect the variable or dimension indices
130 since these indices are relative to the full variable (as stored in the
131 input file), and the input file has not changed. However, if the
132 hypserslab is saved to an output file and those values are printed, the
133 indices will change:
134 % ncks -H -d lat,90.0 -d lev,1000.0 -v three_dmn_var in.nc
135 out.nc
136 lat[1]=90 lev[2]=1000 lon[0]=0 three_dmn_var[20]=20
137 lat[1]=90 lev[2]=1000 lon[1]=90 three_dmn_var[21]=21
138 lat[1]=90 lev[2]=1000 lon[2]=180 three_dmn_var[22]=22
139 lat[1]=90 lev[2]=1000 lon[3]=270 three_dmn_var[23]=23
140 % ncks -H out.nc
141 lat[0]=90 lev[0]=1000 lon[0]=0 three_dmn_var[0]=20
142 lat[0]=90 lev[0]=1000 lon[1]=90 three_dmn_var[1]=21
143 lat[0]=90 lev[0]=1000 lon[2]=180 three_dmn_var[2]=22
144 lat[0]=90 lev[0]=1000 lon[3]=270 three_dmn_var[3]=23
145 -M Print to screen the global metadata describing the file. This
147 includes file summary information and global attributes.
148 -m Print variable metadata to screen (similar to ncdump -h). This
150 displays all metadata pertaining to each variable, one variable
151 at a time.
152 -q Toggle printing of dimension indices and coordinate values when
154 printing arrays. The name of each variable will appear flush
155 left in the output. This is useful when trying to locate spe‐
156 cific variables when displaying many variables with different
157 dimensions. The mnemonic for this option is "quiet".
158 -s format String format for text output. Accepts C language escape
160 sequences and printf() formats.
161 -u Accompany the printing of a variable's values with its units
163 attribute, if it exists.
164
166 View all data in netCDF in.nc, printed with Fortran indexing conven‐
167 tions:
168 ncks -H -F in.nc
169 Copy the netCDF file in.nc to file out.nc.
171 ncks -O in.nc out.nc
172 Now the file out.nc contains all the data from in.nc. There are, how‐
173 ever, two differences between in.nc and out.nc. First, the history
174 global attribute will contain the command used to create out.nc. Sec‐
175 ond, the variables in out.nc will be defined in alphabetical order. Of
176 course the internal storage of variable in a netCDF file should be
177 transparent to the user, but there are cases when alphabetizing a file
178 is useful (see description of -a switch).
179 Print variable three_dmn_var from file in.nc with default notations.
181 Next print three_dmn_var as an un-annotated text column. Then print
182 three_dmn_var signed with very high precision. Finally, print
183 three_dmn_var as a comma-separated list.
184 % ncks -H -C -v three_dmn_var in.nc
185 lat[0]=-90 lev[0]=100 lon[0]=0 three_dmn_var[0]=0
186 lat[0]=-90 lev[0]=100 lon[1]=90 three_dmn_var[1]=1
187 lat[1]=90 lev[2]=1000 lon[3]=270 three_dmn_var[23]=23
188 % ncks -s "%f\n" -H -C -v three_dmn_var in.nc
189 0.000000
190 1.000000
191 23.000000
192 % ncks -s "%+16.10f\n" -H -C -v three_dmn_var in.nc
193 +0.0000000000
194 +1.0000000000
195 +23.0000000000
196 % ncks -s "%f, " -H -C -v three_dmn_var in.nc
197 0.000000, 1.000000, ..., 23.000000,
198 The second and third options are useful when pasting data into text
199 files like reports or papers.
200 One dimensional arrays of characters stored as netCDF variables are
202 automatically printed as strings, whether or not they are NUL-termi‐
203 nated, e.g.,
204 ncks -v fl_nm in.nc
205 The %c formatting code is useful for printing multidimensional arrays
206 of characters representing fixed length strings
207 ncks -H -s "%c" -v fl_nm_arr in.nc
208 Using the %s format code on strings which are not NUL-terminated (and
209 thus not technically strings) is likely to result in a core dump.
210 Create netCDF out.nc containing all variables, and any associated coor‐
212 dinates, except variable time, from netCDF in.nc:
213 ncks -x -v time in.nc out.nc
214 Extract variables time and pressure from netCDF in.nc. If out.nc does
216 not exist it will be created. Otherwise the you will be prompted
217 whether to append to or to overwrite out.nc:
218 ncks -v time,pressure in.nc out.nc
219 ncks -C -v time,pressure in.nc out.nc
220 The first version of the command creates an out.nc which contains time,
221 pressure, and any coordinate variables associated with pressure. The
222 out.nc from the second version is guaranteed to contain only two vari‐
223 ables time and pressure.
224 Create netCDF out.nc containing all variables from file in.nc.
226 Restrict the dimensions of these variables to a hyperslab. Print (with
227 -H) the hyperslabs to the screen for good measure. The specified
228 hyperslab is: the fifth value in dimension time; the half-open range
229 lat > 0. in coordinate lat; the half-open range lon < 330. in coordi‐
230 nate lon; the closed interval .3 < band < .5 in coordinate band; and
231 cross-section closest to 1000. in coordinate lev. Note that limits
232 applied to coordinate values are specified with a decimal point, and
233 limits applied to dimension indices do not have a decimal point.
234 ncks -H -d time,5 -d lat,,0. -d lon,330., -d band,.3,.5 -d
235 lev,1000. in.nc out.nc
236 Assume the domain of the monotonically increasing longitude coordinate
238 lon is 0 < lon < 360. Here, lon is an example of a wrapped coordinate.
239 ncks will extract a hyperslab which crosses the Greenwich meridian sim‐
240 ply by specifying the westernmost longitude as min and the easternmost
241 longitude as max, as follows:
242 ncks -d lon,260.,45. in.nc out.nc
243
246 NCO manual pages written by Charlie Zender and Brian Mays.
247
250 Report bugs to <http://sf.net/bugs/?group_id=3331>.
251
254 Copyright © 1995-2004 Charlie Zender
255 This is free software; see the source for copying conditions. There is
256 NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
257 PURPOSE.
258
261 The full documentation for NCO is maintained as a Texinfo manual called
262 the NCO User's Guide. Because NCO is mathematical in nature, the docu‐
263 mentation includes TeX-intensive portions not viewable on character-
264 based displays. Hence the only complete and authoritative versions of
265 the NCO User's Guide are the PDF (recommended), DVI, and Postscript
266 versions at <http://nco.sf.net/nco.pdf>, <http://nco.sf.net/nco.dvi>,
267 and <http://nco.sf.net/nco.ps>, respectively. HTML and XML versions
268 are available at <http://nco.sf.net/nco.html> and
269 <http://nco.sf.net/nco.xml>, respectively.
270 If the info and NCO programs are properly installed at your site, the
272 command
273 info nco
275 should give you access to the complete manual, except for the TeX-
277 intensive portions.
278
281 The NCO homepage at <http://nco.sf.net> contains more information.
282 NCKS(1)