NCBO(1)

💖 NCBO — netCDF Binary Operator 💖

okay so bestie, pull up a chair 🪑 because this is ncbo(1), the netCDF Binary Operator, and she is that girl. she does subtraction and she does it with main character energy. let's go ✨

---

✨ SYNTAX ✨

here's the whole vibe, verbatim, don't skip a single bracket bestie i'm serious:

ncbo [-3] [-4] [-5] [-6] [-7] [-A] [--bfr sz_byt][-C][-c] [--cmp
cmp_sng] [--cnk_byt sz_byt][--cnk_csh sz_byt][--cnk_dmn nm,sz_lmn]
[--cnk_map map] [--cnk_min sz_byt] [--cnk_plc plc] [--cnk_scl sz_lmn][-D
dbg_lvl] [-d dim,[ min][,[ max]]] [-F] [--fl_fmt=fmt] [-G gpe_dsc] [-g
grp[,...]]  [--gaa att_name= att_val]] [--gad att1[,...]]  [-H] [-h]
[--hdf] [--hdr_pad sz_byt][--hpss_try] [-L dfl_lvl] [-l path] [--msa]
[--no_cll_msr] [--no_frm_trm] [--no_tmp_fl] [-O] [-p path] [--qnt var1[,
var2[,...]]= prc]] [--qnt_alg alg_nm] [-R] [-r] [--ram_all] [-t thr_nbr]
[--uio] [--unn] [-v var[,...]]  [-X box] [-x] file_1 file_2 file_3

three files, always three files: file_1, file_2, file_3. the holy trinity fr 🙏

---

🌸 DESCRIPTION 🌸

so what does she actually do. ncbo takes the variables in file_2 and subtracts them from the corresponding variables (aka the ones with the same name) in file_1, and drops the results into file_3. that's it. that's the whole personality. subtraction girlie 💅

now here's the fun part — broadcasting. if the variables in file_2 don't match up dimension-wise, they get broadcast to conform to the corresponding variable in file_1. and what does "broadcasting a variable" mean, you ask? it means creating data in dimensions that don't exist yet, using the data from the dimensions that do exist. iconic behavior honestly. ✨

for example (this is literally the example from the page, no cap): a two-dimensional variable in file_2 can be subtracted from a four-, three-, or two-dimensional variable (of the same name) in file_1. but not one or zero dimensional. nope. not happening. 🙅‍♀️

this functionality is what lets you compute anomalies from the mean, which is the whole point, the moment, the slay. 🌈

⚠️ okay but listen: variables in file_1 are NOT broadcast to conform to the dimensions in file_2. it only goes one way bestie. so the number of dimensions — the rank — of any processed variable in file_1 must be greater than or equal to the rank of the same variable in file_2. and on top of that, the size of all dimensions common to both file_1 and file_2 must be equal. no exceptions. the vibe check is strict. 💀

so when you're computing anomalies from the mean, it's often the case that file_2 was made by applying an averaging operator to a file with the same dimensions as file_1, or even file_1 itself. and in those cases, making file_2 with ncra instead of ncwa will make the ncbo operation fail. 😭

let's get concrete, because concreteness is key. say the record dimension in file_1 is time. if file_2 was created by averaging file_1 over the time dimension with the ncra operator instead of with the ncwa operator, then file_2 will have a time dimension of size 1 instead of having no time dimension at all. and then the input files to ncbo, file_1 and file_2, have unequally sized time dimensions, which causes ncbo to fail. 💀💀

to prevent this from happening, use ncwa to remove the time dimension from file_2. there's an example below. you're welcome. 🫶

a couple more things, and these are hardcoded so don't @ me:

• ncbo will never difference coordinate variables. ever. 🚫
• ncbo will never difference variables of type NC_CHAR or NC_BYTE. also never.

this ensures that coordinates like (e.g., latitude and longitude) stay physically meaningful in the output file, file_3. and ncbo applies special rules to some NCAR CSM fields (e.g., ORO). see NCAR CSM Conventions for a complete description. 📖

and finally, a lil psa: ncflint (ncflint netCDF File Interpolator) can also perform file subtraction (as well as addition, multiplication and interpolation). so like. options, bestie. ✨

---

🦋 EXAMPLES 🦋

okay this is the part where it all comes together, get your notebooks out 📓✨

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

slay. now 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. literally what we wanted. 💖

---

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. remember the rule bestie!! 🫶

---

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

periodt. that's the whole workflow. you did it. 🎀

---

👑 AUTHOR 👑

NCO manual pages written by Charlie Zender and originally formatted by Brian Mays. absolute legends, both of them. 💜

---

🙈 REPORTING BUGS 🙈

found a bug? report it to <http://sf.net/bugs/?group_id=3331>. don't be shy, they wanna know. 🐛

---

🌈 COPYRIGHT 🌈

Copyright © 1995-present 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.

⚠️ that's the legal bit bestie, i'm not paraphrasing that. no warranty, none, zero, zilch. 💀

---

💅 SEE ALSO 💅

The full documentation for NCO is maintained as a Texinfo manual called the NCO Users 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 Users 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. go look, it's giving resourceful. 🦋

---

and that's the whole page bestie!! 🎀 this was NCBO(1) from the General Commands Manual, and yeah she's literally iconic. go subtract some variables. no cap. 💖✨👑