NCKS(1) 						      General Commands Manual							   NCKS(1)

NAME

       ncks - netCDF Kitchen Sink

SYNTAX

       ncks  [-3]  [-4]  [-6] [-A] [-a] [-C] [-c] [--cnk_dmn nm,sz] [--cnk_map map] [--cnk_plc plc] [--cnk_scl sz] [-D] [-d dim,[ min][,[ max]][,[
       stride]]] [-F] [-H] [-h] [-L dfl_lvl] [-l path] [-M] [-m] [-O] [-p path] [-q] [-R] [-r] [-s format] [-u]  [-v  var[,...]]   [-X	box]  [-x]
       input-file [ output-file]

DESCRIPTION

       ncks  combines  selected  features of ncdump, ncextr, and the nccut and ncpaste specifications into one versatile utility.  ncks extracts a
       subset of the data from input-file and either prints it as ASCII text to stdout, or writes (or pastes) it to output-file, or both.

       ncks will print netCDF data in ASCII format to stdout, like ncdump, but with these differences:	ncks  prints  data  in	a  tabular  format
       intended  to  be  easy  to search for the data you want, one datum per screen line, with all dimension subscripts and coordinate values (if
       any) preceding the datum.  Option -s allows the user the format the data using C-style format strings.

       Options -a, -F, -H, -M, -m, -q, -s, and -u control the formatted appearance of the data.

       ncks will extract (and optionally create a new netCDF file comprised of) only selected variable from the input file, like ncextr  but  with
       these  differences: Only variables and coordinates may be specifically included or excluded---all global attributes and any attribute asso-
       ciated with an extracted variable will be copied to the screen and/or output netCDF file.  Options -c, -C, -v, and -x control  which  vari-
       ables are extracted.

       ncks  will  extract  hyperslabs from the specified variables.  In fact ncks implements the nccut specification exactly.	Option -d controls
       the hyperslab specification.

       Input dimensions that are not associated with any output variable will not appear in the output netCDF.	This feature  removes  superfluous
       dimensions from a netCDF file.

       ncks  will  append  variables and attributes from the input-file to output-file if output-file is a pre-existing netCDF file whose relevant
       dimensions conform to dimension sizes of input-file.  The append features of ncks are intended to provide a  rudimentary  means	of  adding
       data  from one netCDF file to another, conforming, netCDF file.	When naming conflicts exists between the two files, data in output-file is
       usually overwritten by the corresponding data from input-file.  Thus it is recommended that the user backup output-file	in  case  valuable
       data is accidentally overwritten.

       If  output-file	exists,  the  user  will  be  queried  whether to overwrite, append, or exit the ncks call completely.	Choosing overwrite
       destroys the existing output-file and create an entirely new one from the output of the ncks call.  Append has differing effects  depending
       on the uniqueness of the variables and attributes output by ncks: If a variable or attribute extracted from input-file does not have a name
       conflict with the members of output-file then it will be added to output-file without overwriting any of the existing contents  of  output-
       file.   In  this  case  the  relevant  dimensions  must agree (conform) between the two files; new dimensions are created in output-file as
       required.  When a name conflict occurs, a global attribute from input-file will overwrite the corresponding global attribute  from  output-
       file.   If  the	name conflict occurs for a non-record variable, then the dimensions and type of the variable (and of its coordinate dimen-
       sions, if any) must agree (conform) in both files.  Then the variable values (and any coordinate dimension  values)  from  input-file  will
       overwrite the corresponding variable values (and coordinate dimension values, if any) in output-file

       Since there can only be one record dimension in a file, the record dimension must have the same name (but not necessarily the same size) in
       both files if a record dimension variable is to be appended.  If the record dimensions are of differing sizes, the record dimension of out-
       put-file  will  become the greater of the two record dimension sizes, the record variable from input-file will overwrite any counterpart in
       output-file and fill values will be written to any gaps left in the rest of  the  record  variables  (I	think).   In  all  cases  variable
       attributes in output-file are superseded by attributes of the same name from input-file, and left alone if there is no name conflict.

       Some  users  may  wish to avoid interactive ncks queries about whether to overwrite existing data.  For example, batch scripts will fail if
       ncks does not receive responses to its queries.	Options -O and -A are available to force overwriting existing files and variables, respec-
       tively.

       Options specific to ncks

       The following list provides a short summary of the features unique to ncks.

       -a     Do  not  alphabetize  extracted  fields.	 By default, the specified output variables are extracted, printed, and written to disk in
	      alphabetical order.  This tends to make long output lists easier to search for particular variables.  Specifying -a results  in  the
	      variables  being	extracted,  printed, and written to disk in the order in which they were saved in the input file.  Thus -a retains
	      the original ordering of the variables.

       -d     dim,[ min][,[ max]][,[ stride]] Add stride argument to hyperslabber.

       -H     Print data to screen.  The default behavior is to print data to screen if no netCDF output file is specified.  Use -H to print  data
	      to screen if a netCDF output is specified (the same behavior applies to -m ).  Unless otherwise specified (with -s), each element of
	      the data hyperslab is printed on a separate line containing the names, indices, and, values, if any, of all of the variables  dimen-
	      sions.   The  dimension and variable indices refer to the location of the corresponding data element with respect to the variable as
	      stored on disk (i.e., not the hyperslab).
	      % ncks -H -C -v three_dmn_var in.nc
	      lat[0]=-90 lev[0]=100 lon[0]=0 three_dmn_var[0]=0
	      lat[0]=-90 lev[0]=100 lon[1]=90 three_dmn_var[1]=1
	      lat[0]=-90 lev[0]=100 lon[2]=180 three_dmn_var[2]=2
	       ...
	      lat[1]=90 lev[2]=1000 lon[1]=90 three_dmn_var[21]=21
	      lat[1]=90 lev[2]=1000 lon[2]=180 three_dmn_var[22]=22
	      lat[1]=90 lev[2]=1000 lon[3]=270 three_dmn_var[23]=23
       Printing the same variable with the -F option shows the same variable indexed with Fortran conventions
	      % ncks -F -H -C -v three_dmn_var in.nc
	      lon(1)=0 lev(1)=100 lat(1)=-90 three_dmn_var(1)=0
	      lon(2)=90 lev(1)=100 lat(1)=-90 three_dmn_var(2)=1
	      lon(3)=180 lev(1)=100 lat(1)=-90 three_dmn_var(3)=2
	       ...
       Printing a hyperslab does not affect the variable or dimension indices since these indices are relative to the full variable (as stored	in
       the  input  file), and the input file has not changed.  However, if the hypserslab is saved to an output file and those values are printed,
       the indices will change:
	      % ncks -H -d lat,90.0 -d lev,1000.0 -v three_dmn_var in.nc out.nc
	      lat[1]=90 lev[2]=1000 lon[0]=0 three_dmn_var[20]=20
	      lat[1]=90 lev[2]=1000 lon[1]=90 three_dmn_var[21]=21
	      lat[1]=90 lev[2]=1000 lon[2]=180 three_dmn_var[22]=22
	      lat[1]=90 lev[2]=1000 lon[3]=270 three_dmn_var[23]=23
	      % ncks -H out.nc
	      lat[0]=90 lev[0]=1000 lon[0]=0 three_dmn_var[0]=20
	      lat[0]=90 lev[0]=1000 lon[1]=90 three_dmn_var[1]=21
	      lat[0]=90 lev[0]=1000 lon[2]=180 three_dmn_var[2]=22
	      lat[0]=90 lev[0]=1000 lon[3]=270 three_dmn_var[3]=23

       -M     Print to screen the global metadata describing the file.	This includes file summary information and global attributes.

       -m     Print variable metadata to screen (similar to ncdump -h).  This displays all metadata pertaining to each variable, one variable at a
	      time.

       -q     Toggle  printing	of dimension indices and coordinate values when printing arrays.  The name of each variable will appear flush left
	      in the output.  This is useful when trying to locate specific variables when displaying many variables  with  different  dimensions.
	      The mnemonic for this option is "quiet".

       -s     format String format for text output. Accepts C language escape sequences and printf() formats.

       -u     Accompany the printing of a variable's values with its units attribute, if it exists.

EXAMPLES

       View all data in netCDF in.nc, printed with Fortran indexing conventions:
	      ncks -H -F in.nc

       Copy the netCDF file in.nc to file out.nc.
	      ncks -O in.nc out.nc
       Now  the  file  out.nc contains all the data from in.nc.  There are, however, two differences between in.nc and out.nc.	First, the history
       global attribute will contain the command used to create out.nc.  Second, the variables in out.nc will be defined  in  alphabetical  order.
       Of  course  the	internal  storage of variable in a netCDF file should be transparent to the user, but there are cases when alphabetizing a
       file is useful (see description of -a switch).

       Print variable three_dmn_var from file in.nc with default notations.  Next print three_dmn_var as an un-annotated text column.  Then  print
       three_dmn_var signed with very high precision.  Finally, print three_dmn_var as a comma-separated list.
	      % ncks -H -C -v three_dmn_var in.nc
	      lat[0]=-90 lev[0]=100 lon[0]=0 three_dmn_var[0]=0
	      lat[0]=-90 lev[0]=100 lon[1]=90 three_dmn_var[1]=1
	       ...
	      lat[1]=90 lev[2]=1000 lon[3]=270 three_dmn_var[23]=23
	      % ncks -s "%f
" -H -C -v three_dmn_var in.nc
	      0.000000
	      1.000000
	       ...
	      23.000000
	      % ncks -s "%+16.10f
" -H -C -v three_dmn_var in.nc
		 +0.0000000000
		 +1.0000000000
	       ...
		+23.0000000000
	      % ncks -s "%f, " -H -C -v three_dmn_var in.nc
	      0.000000, 1.000000,  ... , 23.000000,
       The second and third options are useful when pasting data into text files like reports or papers.

       One  dimensional  arrays  of characters stored as netCDF variables are automatically printed as strings, whether or not they are NUL-termi-
       nated, e.g.,
	      ncks -v fl_nm in.nc
       The %c formatting code is useful for printing multidimensional arrays of characters representing fixed length strings
	      ncks -H -s "%c" -v fl_nm_arr in.nc
       Using the %s format code on strings which are not NUL-terminated (and thus not technically strings) is likely to result in a core dump.

       Create netCDF out.nc containing all variables, and any associated coordinates, except variable time, from netCDF in.nc:
	      ncks -x -v time in.nc out.nc

       Extract variables time and pressure from netCDF in.nc.  If out.nc does not exist it will be created.  Otherwise the you	will  be  prompted
       whether to append to or to overwrite out.nc:
	      ncks -v time,pressure in.nc out.nc
	      ncks -C -v time,pressure in.nc out.nc
       The  first  version  of the command creates an out.nc which contains time, pressure, and any coordinate variables associated with pressure.
       The out.nc from the second version is guaranteed to contain only two variables time and pressure.

       Create netCDF out.nc containing all variables from file in.nc.  Restrict the dimensions of these variables to a hyperslab.  Print (with -H)
       the  hyperslabs	to the screen for good measure.  The specified hyperslab is: the sixth value in dimension time; the half-open range lat <=
       0.0 in coordinate lat; the half-open range lon >= 330.0 in coordinate lon; the closed interval 0.3 <= band <= 0.5 in coordinate	band;  and
       cross-section  closest  to 1000.0 in coordinate lev.  Note that limits applied to coordinate values are specified with a decimal point, and
       limits applied to dimension indices do not have a decimal point.
	      ncks -H -d time,5 -d lat,,0. -d lon,330., -d band,.3,.5 -d lev,1000. in.nc out.nc

       Assume the domain of the monotonically increasing longitude coordinate lon is 0 < lon < 360.  Here, lon is an example of a wrapped  coordi-
       nate.   ncks  will  extract  a hyperslab which crosses the Greenwich meridian simply by specifying the westernmost longitude as min and the
       easternmost longitude as max, as follows:
	      ncks -d lon,260.,45. in.nc out.nc

AUTHOR

       NCO manual pages written by Charlie Zender and Brian Mays.

REPORTING BUGS

       Report bugs to <http://sf.net/bugs/?group_id=3331>.

COPYRIGHT

       Copyright (C) 1995-2011 Charlie Zender
       This is free software; see the source for copying conditions.  There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICU-
       LAR PURPOSE.

SEE ALSO

       The  full  documentation for NCO is maintained as a Texinfo manual called the NCO User's Guide.	Because NCO is mathematical in nature, the
       documentation includes TeX-intensive portions not viewable on character-based displays.	Hence the only complete and authoritative versions
       of   the   NCO	User's	 Guide	 are   the   PDF   (recommended),   DVI,   and	 Postscript   versions	 at   <http://nco.sf.net/nco.pdf>,
       <http://nco.sf.net/nco.dvi>,   and   <http://nco.sf.net/nco.ps>,   respectively.    HTML   and	 XML	versions    are    available	at
       <http://nco.sf.net/nco.html> and <http://nco.sf.net/nco.xml>, respectively.

       If the info and NCO programs are properly installed at your site, the command

	      info nco

       should give you access to the complete manual, except for the TeX-intensive portions.

HOMEPAGE

       The NCO homepage at <http://nco.sf.net> contains more information.

																	   NCKS(1)