.\" $Header$ -*-nroff-*- .\" Purpose: ROFF man page for ncbo .\" Usage: .\" nroff -man ~/nco/man/ncbo.1 | less .TH NCBO 1 .SH NAME ncbo \- netCDF Binary Operator .SH SYNTAX ncbo [\-3] [\-4] [\-5] [\-6] [\-7] [\-A] [\-\-bfr .IR sz_byt ] [\-C] [\-c] [\-\-cmp .IR cmp_sng ] [\-\-cnk_byt .IR sz_byt ] [\-\-cnk_csh .IR sz_byt ] [\-\-cnk_dmn .IR nm,sz_lmn ] [\-\-cnk_map .IR map ] [\-\-cnk_min .IR sz_byt ] [\-\-cnk_plc .IR plc ] [\-\-cnk_scl .IR sz_lmn ] [\-D .IR dbg_lvl ] [\-d .IR dim ,[ .IR min ][,[ .IR max ]]] [-F] [--fl_fmt=fmt] [\-G .IR gpe_dsc ] [\-g .IR grp [,...]] [\-\-glb .IR att_name= .IR att_val ]] [\-H] [\-h] [\-\-hdf] [\-\-hdr_pad .IR sz_byt ] [\-\-hpss_try] [\-L .IR dfl_lvl ] [\-l .IR path ] [\-\-msa] [\-\-no_cll_msr] [\-\-no_frm_trm] [\-\-no_tmp_fl] [\-O] [\-p .IR path ] [\-R] [\-r] [\-\-ram_all] [\-t .IR thr_nbr ] [\-\-uio] [\-\-unn] [\-v .IR var [,...]] [\-X .IR box ] [\-x] .I file_1 .I file_2 .I file_3 .SH DESCRIPTION .PP .B ncbo subtracts variables in .I file_2 from the corresponding variables (those with the same name) in .I file_1 and stores the results in .IR file_3 . Variables in .I file_2 are .I broadcast to conform to the corresponding variable in .I 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 .I file_2 can be subtracted from a four, three, or two (but not one or zero) dimensional variable (of the same name) in .BR file_1 . This functionality allows the user to compute anomalies from the mean. Note that variables in .I file_1 are .I not broadcast to conform to the dimensions in .IR file_2 . Thus, .BR ncbo , the number of dimensions, or .IR rank , of any processed variable in .I file_1 must be greater than or equal to the rank of the same variable in .IR file_2 . Furthermore, the size of all dimensions common to both .I file_1 and .I file_2 must be equal. .PP When computing anomalies from the mean it is often the case that .I file_2 was created by applying an averaging operator to a file with the same dimensions as .IR file_1 , if not .I file_1 itself. In these cases, creating .I file_2 with .B ncra rather than .B ncwa will cause the .B ncbo operation to fail. For concreteness say the record dimension in .B file_1 is .BR time . If .I file_2 were created by averaging .I file_1 over the .B time dimension with the .B ncra operator rather than with the .B ncwa operator, then .I file_2 will have a .B time dimension of size 1 rather than having no .B time dimension at all In this case the input files to .BR ncbo , .I file_1 and .IR file_2 , will have unequally sized .B time dimensions which causes .B ncbo to fail. To prevent this from occurring, use .B ncwa to remove the .B time dimension from .IR file_2 . An example is given below. .PP .B ncbo will never difference coordinate variables or variables of type .B NC_CHAR or .BR NC_BYTE . This ensures that coordinates like (e.g., latitude and longitude) are physically meaningful in the output file, .IR file_3 . This behavior is hardcoded. .B ncbo applies special rules to some NCAR CSM fields (e.g., .BR ORO ). See .I "NCAR CSM Conventions for a complete description. Finally, we note that .B ncflint (ncflint netCDF File Interpolator) can be also perform file subtraction (as well as addition, multiplication and interpolation). .PP .SH EXAMPLES .PP Say files .B 85_0112.nc and .B 86_0112.nc each contain 12 months of data. Compute the change in the monthly averages from 1985 to 1986: .RS ncbo 86_0112.nc 85_0112.nc 86m85_0112.nc .RE .PP The following examples demonstrate the broadcasting feature of .BR ncbo . Say we wish to compute the monthly anomalies of .B T from the yearly average of .B T for the year 1985. First we create the 1985 average from the monthly data, which is stored with the record dimension .BR time . .RS ncra 85_0112.nc 85.nc .br ncwa \-O \-a time 85.nc 85.nc .RE The second command, .BR ncwa , gets rid of the .B time dimension of size 1 that .B ncra left in .BR 85.nc . Now none of the variables in .B 85.nc has a .B time dimension. A quicker way to accomplish this is to use .B ncwa from the beginning: .RS ncwa \-a time 85_0112.nc 85.nc .RE We are now ready to use .B ncbo to compute the anomalies for 1985: .RS ncbo \-v T 85_0112.nc 85.nc t_anm_85_0112.nc .RE Each of the 12 records in .B t_anm_85_0112.nc now contains the monthly deviation of .B T from the annual mean of .B T for each gridpoint. .PP Say we wish to compute the monthly gridpoint anomalies from the zonal annual mean. A .I "zonal mean" is a quantity that has been averaged over the longitudinal (or .IR x ) direction. First we use .B ncwa to average over longitudinal direction .BR lon , creating .BR xavg_85.nc , the zonal mean of .BR 85.nc . Then we use .B ncbo to subtract the zonal annual means from the monthly gridpoint data: .RS ncwa \-a lon 85.nc xavg_85.nc .br ncbo 85_0112.nc xavg_85.nc tx_anm_85_0112.nc .RE Assuming .B 85_0112.nc has dimensions .B time and .BR lon , this example only works if .B xavg_85.nc has no .B time or .B lon dimension. .PP As a final example, say we have five years of monthly data (i.e., 60 months) stored in .B 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 .B ncwa to create the file containing the five-year mean: .RS ncwa \-a time 8501_8912.nc 8589.nc .RE Next use .B ncbo to create a file containing the difference of each month's data from the five-year mean: .RS ncbo 8501_8912.nc 8589.nc t_anm_8501_8912.nc .RE Now use .B ncks to group the five January anomalies together in one file, and use .B 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: .RS foreach idx (01 02 03 04 05 06 07 08 09 10 11 12) .br ncks \-F \-d time,,,12 t_anm_8501_8912.nc foo. .br ncra foo. t_anm_8589_.nc .br end .RE Note that .B ncra understands the .B stride argument so the two commands inside the loop may be combined into the single command .RS ncra \-F \-d time,,,12 t_anm_8501_8912.nc foo. .RE Finally, use .B ncrcat to concatenate the 12 average monthly anomaly files into one twelve-record file which contains the entire seasonal cycle of the monthly anomalies: .RS ncrcat t_anm_8589_??.nc t_anm_8589_0112.nc .RE .\" NB: Append man_end.txt here .\" $Header$ -*-nroff-*- .\" Purpose: Trailer file for common ending to NCO man pages .\" Usage: .\" Append this file to end of NCO man pages immediately after marker .\" that says "Append man_end.txt here" .SH AUTHOR .B NCO manual pages written by Charlie Zender and originally formatted by Brian Mays. .SH "REPORTING BUGS" Report bugs to . .SH COPYRIGHT Copyright \(co 1995-present Charlie Zender .br This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. .SH "SEE ALSO" The full documentation for .B NCO is maintained as a Texinfo manual called the .B NCO Users Guide. Because .B 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 .B NCO Users Guide are the PDF (recommended), DVI, and Postscript versions at , , and , respectively. HTML and XML versions are available at and , respectively. If the .B info and .B NCO programs are properly installed at your site, the command .IP .B info nco .PP should give you access to the complete manual, except for the TeX-intensive portions. .SH HOMEPAGE The .B NCO homepage at contains more information.