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