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