Provided by: nco_4.4.2-1_amd64 bug

NAME

       ncks - netCDF Kitchen Sink

SYNTAX

       ncks  [-3] [-4] [-5] [-6] [-7] [-A] [-a] [-b bnr_fl] [--bfr sz][-C][-c] [--cdl] [--cnk_byt
       sz][--cnk_dmn nm,sz] [--cnk_map map] [--cnk_plc plc] [--cnk_scl sz] [-D dbg_lvl] [-d dim,[
       min][,[ max]][,[ stride]]] [-F] [--fix_rec_dmn dim] [-G gpe_dsc] [-g grp[,...]]  [-H] [-h]
       [--hdn]  [--hdr_pad  sz]  [-L  dfl_lvl]  [-l  path]  [-M]  [-m]   [--md5]    [--mk_rec_dmn
       dim][--msa][--no_blank][--no_tmp_fl][-O][-o  output-file]  [-P]  [-p  path] [-Q] [-q] [-R]
       [-r] [--ram_all] [-s format] [-u] [--unn] [-v var[,...]]  [-X box] [-x] [--xml] input-file
       [ output-file]

DESCRIPTION

       ncks combines every feature we could think of, except the kitchen sink, into one versatile
       utility to manipulate netCDF files.  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 associated with an extracted variable will be copied to the screen and/or output
       netCDF file.  Options -c, -C, -v, and -x control which variables 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  dimensions,  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 output-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, respectively.

       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  dimensions.   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\n" -H -C -v three_dmn_var in.nc
              0.000000
              1.000000
               ...
              23.000000
              % ncks -s "%+16.10f\n" -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-terminated, 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 coordinate.   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 originally formatted by Brian Mays.

REPORTING BUGS

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

COPYRIGHT

       Copyright © 1995-2012 Charlie Zender
       This is free software; see the source for copying conditions.  There is NO  warranty;  not
       even for MERCHANTABILITY or FITNESS FOR A PARTICULAR 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.

       ncap(1),   ncap2(1),  ncatted(1),  ncbo(1),  ncdiff(1),  nces(1),  ncecat(1),  ncflint(1),
       ncks(1), nco(1), ncpdq(1), ncra(1), ncrcat(1), ncrename(1), ncwa(1)

HOMEPAGE

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

                                                                                          NCKS(1)