NAME
ncbo - netCDF Binary Operator
SYNTAX
ncbo [-3] [-4] [-6] [-A] [-C] [-c] [-D dbg] [-d dim,[ min][,[ max]]]
[-F] [-h] [-L dfl_lvl] [-l path] [-O] [-p path] [-R] [-r] [-t thr_nbr]
[-v var[,...]] [-X box] [-x] file_1 file_2 file_3
DESCRIPTION
ncbo subtracts variables in file_2 from the corresponding variables
(those with the same name) in file_1 and stores the results in file_3.
Variables in file_2 are broadcast to conform to the corresponding
variable in file_1 if necessary. Broadcasting a variable means
creating data in non-existing dimensions from the data in existing
dimensions. For example, a two dimensional variable in file_2 can be
subtracted from a four, three, or two (but not one or zero) dimensional
variable (of the same name) in file_1. This functionality allows the
user to compute anomalies from the mean. Note that variables in file_1
are not broadcast to conform to the dimensions in file_2. Thus, ncbo,
the number of dimensions, or rank, of any processed variable in file_1
must be greater than or equal to the rank of the same variable in
file_2. Furthermore, the size of all dimensions common to both file_1
and file_2 must be equal.
When computing anomalies from the mean it is often the case that file_2
was created by applying an averaging operator to a file with the same
dimensions as file_1, if not file_1 itself. In these cases, creating
file_2 with ncra rather than ncwa will cause the ncbo operation to
fail. For concreteness say the record dimension in file_1 is time. If
file_2 were created by averaging file_1 over the time dimension with
the ncra operator rather than with the ncwa operator, then file_2 will
have a time dimension of size 1 rather than having no time dimension at
all In this case the input files to ncbo, file_1 and file_2, will have
unequally sized time dimensions which causes ncbo to fail. To prevent
this from occuring, use ncwa to remove the time dimension from file_2.
An example is given below.
ncbo will never difference coordinate variables or variables of type
NC_CHAR or NC_BYTE. This ensures that coordinates like (e.g., latitude
and longitude) are physically meaningful in the output file, file_3.
This behavior is hardcoded. ncbo applies special rules to some NCAR
CSM fields (e.g., ORO). See NCAR CSM Conventions for a complete
description. Finally, we note that ncflint (ncflint netCDF File
Interpolator) can be also perform file subtraction (as well as
addition, multiplication and interpolation).
EXAMPLES
Say files 85_0112.nc and 86_0112.nc each contain 12 months of data.
Compute the change in the monthly averages from 1985 to 1986:
ncbo 86_0112.nc 85_0112.nc 86m85_0112.nc
The following examples demonstrate the broadcasting feature of ncbo.
Say we wish to compute the monthly anomalies of T from the yearly
average of T for the year 1985. First we create the 1985 average from
the monthly data, which is stored with the record dimension time.
ncra 85_0112.nc 85.nc
ncwa -O -a time 85.nc 85.nc
The second command, ncwa, gets rid of the time dimension of size 1 that
ncra left in 85.nc. Now none of the variables in 85.nc has a time
dimension. A quicker way to accomplish this is to use ncwa from the
beginning:
ncwa -a time 85_0112.nc 85.nc
We are now ready to use ncbo to compute the anomalies for 1985:
ncbo -v T 85_0112.nc 85.nc t_anm_85_0112.nc
Each of the 12 records in t_anm_85_0112.nc now contains the monthly
deviation of T from the annual mean of T for each gridpoint.
Say we wish to compute the monthly gridpoint anomalies from the zonal
annual mean. A zonal mean is a quantity that has been averaged over
the longitudinal (or x) direction. First we use ncwa to average over
longitudinal direction lon, creating xavg_85.nc, the zonal mean of
85.nc. Then we use ncbo to subtract the zonal annual means from the
monthly gridpoint data:
ncwa -a lon 85.nc xavg_85.nc
ncbo 85_0112.nc xavg_85.nc tx_anm_85_0112.nc
Assuming 85_0112.nc has dimensions time and lon, this example only
works if xavg_85.nc has no time or lon dimension.
As a final example, say we have five years of monthly data (i.e., 60
months) stored in 8501_8912.nc and we wish to create a file which
contains the twelve month seasonal cycle of the average monthly anomaly
from the five-year mean of this data. The following method is just one
permutation of many which will accomplish the same result. First use
ncwa to create the file containing the five-year mean:
ncwa -a time 8501_8912.nc 8589.nc
Next use ncbo to create a file containing the difference of each
month’s data from the five-year mean:
ncbo 8501_8912.nc 8589.nc t_anm_8501_8912.nc
Now use ncks to group the five January anomalies together in one file,
and use ncra to create the average anomaly for all five Januarys.
These commands are embedded in a shell loop so they are repeated for
all twelve months:
foreach idx (01 02 03 04 05 06 07 08 09 10 11 12)
ncks -F -d time,,,12 t_anm_8501_8912.nc foo.
ncra foo. t_anm_8589_.nc
end
Note that ncra understands the stride argument so the two commands
inside the loop may be combined into the single command
ncra -F -d time,,,12 t_anm_8501_8912.nc foo.
Finally, use ncrcat to concatenate the 12 average monthly anomaly files
into one twelve-record file which contains the entire seasonal cycle of
the monthly anomalies:
ncrcat t_anm_8589_??.nc t_anm_8589_0112.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 © 1995-2010 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.
HOMEPAGE
The NCO homepage at <http://nco.sf.net> contains more information.