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