1NCKS(1)                     General Commands Manual                    NCKS(1)
2
3
4

NAME

6       ncks - netCDF Kitchen Sink
7

SYNTAX

9       ncks   [-3]   [-4]   [-5]  [-6]  [-7]  [-A]  [-a]  [-b  bnr_fl]  [--bfr
10       sz_byt][-C][-c]   [--cal]    [--cdl]    [--cnk_byt    sz_byt][--cnk_csh
11       sz_byt][--cnk_dmn   nm,sz_lmn]   [--cnk_map   map]  [--cnk_min  sz_byt]
12       [--cnk_plc plc] [--cnk_scl  sz_lmn]  [-D  dbg_lvl]  [-d  dim,[  min][,[
13       max]][,[  stride]]]  [-F]  [--fl_fmt=fmt] [--fix_rec_dmn dim][--fmt_val
14       fmt][-G   gpe_dsc]   [-g   grp[,...]]    [--glb   att_name=   att_val]]
15       [--grp_xtr_var_xcl]  [-H]  [-h]  [--hdn]  [--hdr_pad  sz_byt]  [--json]
16       [--jsn_fmt  lvl]  [-l  path]  [-M]  [-m]   [--map   map-file]   [--md5]
17       [--mk_rec_dmn  dim]  [--msa] [--no_blank] [--no_cll_msr] [--no_frm_trm]
18       [--no_tmp_fl] [-O]  [-o  output-file]  [-P]  [-p  path]  [--ppc  var1[,
19       var2[,...]]=  prc]][--prn_fl  print-file]  [-Q]  [-q] [-R] [-r] [--rad]
20       [--ram_all]   [--rgr    key=    val]    [--rnr    wgt][-s    format][-t
21       thr_nbr][-u][--unn][-V][-v var[,...]]  [-X box] [-x] [--xml] input-file
22       [ output-file]
23

DESCRIPTION

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
30       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
37       Options -a, -F, -H, -M, -m, -Q, -q, -s, -u, and -V control the  format‐
38       ted appearance of the data.
39
40       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
48       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
52       Input  dimensions that are not associated with any output variable will
53       not appear in the output  netCDF.   This  feature  removes  superfluous
54       dimensions from a netCDF file.
55
56       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
66       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
85       Since there can only be one record dimension  in  a  file,  the  record
86       dimension  must  have the same name (but not necessarily the same size)
87       in 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
96       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
102       Options specific to ncks
103
104       The  following  list provides a short summary of the features unique to
105       ncks.
106
107       -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
115       -d     dim,[ min][,[ max]][,[ stride]] Add stride  argument  to  hyper‐
116              slabber.
117
118       -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
145       hyperslab  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
159       -M     Print  to  screen the global metadata describing the file.  This
160              includes file summary information and global attributes.
161
162       -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
166       -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
172       -s     format String format for text output. Accepts C language  escape
173              sequences and printf() formats.
174
175       -u     Accompany  the  printing  of  a variable's values with its units
176              attribute, if it exists.
177

EXAMPLES

179       View all data in netCDF in.nc, printed with  Fortran  indexing  conven‐
180       tions:
181              ncks -H -F in.nc
182
183       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
193       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
217       One  dimensional  arrays  of  characters stored as netCDF variables are
218       automatically printed as strings, whether or not  they  are  NUL-termi‐
219       nated, 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
227       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
231       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
241       Create   netCDF  out.nc  containing  all  variables  from  file  in.nc.
242       Restrict the dimensions of these variables to a hyperslab.  Print (with
243       -H)  the  hyperslabs  to  the  screen  for good measure.  The specified
244       hyperslab is: the sixth value in dimension time;  the  half-open  range
245       lat <= 0.0 in coordinate lat; the half-open range lon >= 330.0 in coor‐
246       dinate 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
253       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
260

AUTHOR

262       NCO manual pages written by Charlie Zender and originally formatted  by
263       Brian Mays.
264
265

REPORTING BUGS

267       Report bugs to <http://sf.net/bugs/?group_id=3331>.
268
269
271       Copyright © 1995-2018 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
276

SEE ALSO

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
288       If  the  info and NCO programs are properly installed at your site, the
289       command
290
291              info nco
292
293       should give you access to the complete  manual,  except  for  the  TeX-
294       intensive portions.
295
296       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
300

HOMEPAGE

302       The NCO homepage at <http://nco.sf.net> contains more information.
303
304
305
306                                                                       NCKS(1)
Impressum