Examples of combinations of commands used to perform common calculations:

Please contribute to this WWW page. This file is /home/disk/margaret2/jisao/data/nco/index.html, and you should have write permission.

1) The usefulness of these routines is best demonstrated with an example. We get NCEP / NCAR reanalysis data from NOAA CDC in files where values of the variable, for example, geopotential height, are given for all 17 of the model levels. For simplicity it would be nice to have a file of just 500 mb geopotential height. Creating such a file can be done with:
ncea -d level,6,6 -F hgt.mon.mean.nc hgt500.mon.mean.nc
where:

Return

To sum over a dimension, for example to sum a file of daily precipitation to obtain an annual total
ncra -h -O -y ttl in.nc out.nc
will sum in time. I am not sure if this is because time is the record dimension in my file.

Return

ncdiff hgt300.mon.mean.nc hgt850.mon.mean.nc thickness300850.mon.mean.nc
hgt300 - hgt850 --> thickness

Return

With the exception of ncrcat, there are always only one input and one output file in a NCO operation. One way to include two or more input variables in a calculation is to append additional variable files to a file. The reanalysis daily-average data is stored as one year per file. Append vwnd to the uwnd file:
ncks -A vwnd.1948.nc uwnd.1948.nc

Calculate the product uv for a year of daily-average data.
ncap2 -s "uv=uwnd*vwnd" uwnd.1948.nc product.nc
where product.nc will contain uv, uwnd, and vwnd.

[ Brian Mapes provided another way to obtain the product in a file.
### rename variable vwnd to uwnd so ncbo will know to multiply them
ncrename -v vwnd,uwnd vwnd.1948.nc v.1948.nc

### now multiply
ncbo --op_typ=multiply uwnd.1948.nc v.1948.nc uvwnd.1948.nc

### rename the product back to uv, and put in file of same name uv
ncrename -v uwnd,uv uvwnd.1948.nc uv.1948.nc

### mop up
rm uvwnd.* v.*
]

Beginning of pentad loop:
Calculate the pentad means of uv.
ncra -O -F -d time,day1,day2 product.nc product.pentad.nc
where day1 and day2 are the first and last Julian days of the pentad, respectively.

Calculate u'v'.
ncap2 -s "upvp=uv-uwnd*vwnd" -v product.pentad.nc upvp.pentad.nc
where -v forces only upvp (and not uv, uwnd, or vwnd) to be output to upvp.pentad.nc
End of pentad loop

Concatenate the pentad files in a single file for the year.
ncrcat -h -O upvp.pentad.nc upvp.1948.nc

Dan Vimont, now at the University of Wisconson, figured out this calculation. His cshell script for calculating pentad means is linked here (Dan's WWW page).

Return

i) Suppose you want to perform simple math on a pair of variables. Put the two variables into a single file. This may require
ncks -h -A file_a file_b
which is described elsewhere on this page. Both variables, let's call them A and B, have to be in the same file.

ncap2 -s "AplusB=A+B" -v file_b out.nc
The "-v" option forces only AplusB to be output to out.nc, and the variables A and B are not included in out.nc.

ii) The NCEP / NCAR reanalysis comes as short integers, and NCO tends to write outputs as floating point numbers (which take up twice as much disk space). To convert the floating point numbers back to packed integers, first look at the packing in the original files from CDC, and use these as the add_offset and scale_factor for packing.

For air temperature the add_offset and scale_factor are 512.81 and 0.01, respectively:

ncap2 -O -s "air=(air-512.81)/0.01" filename.nc temp.nc
ncap2 -O -s "air=short(air);air@add_offset=512.81;air@scale_factor=0.01" temp.nc filename.nc

Return

ncatted -O -a units,air,c,c,"units goes here" filename.nc
where "-a" is followed by "attribute name, variable name, mode (append, create, delete, modify, overwrite), attribute variable type (float, character, ...), attribute value"
ncatted -O -a long_name,air,c,c,"long_name goes here" filename.nc
ncatted -O -h -a title,global,o,c,"title goes here" filename.nc
ncatted -O -h -a history,global,o,c,'history goes here' filename.nc
"\n" (no quotes) can be used to put in a carriage return.

Return

ncrename -h -O -v old_variable_name,new_variable_name filename.nc
-h: do not add to the history variable
-O: (upper case) overwrite the file.
-d oldname,newname: to change a dimension name
-a oldname,newname: to change an attribute name

Return

If you want to put two variables with the same time dimension into the same file, use
ncks -h -A file_a file_b
will put variables a and b into file file_b

If you have yearly files that you want to concatenate, use
ncrcat -h file_1979 file_1980 file_1981 file_197919801981
ncrcat -h file_1979 file_198[01] file_197919801981
should do the same thing.
-h: do not add to the history variable.*

* There is a special problem that can arise with the time dimension in the concatenated files. I write time as "so many units since some reference time" where the reference time is the first time period present in a file. ncrcat, at present, doesn't calculate the time correctly for files written with the above time prescription, and it provides a non-fatal error. I have come up with a matlab5 work-around where I write correct time values into the time variable inside a matlab session. For example,

f = netcdf( filename, 'write' )
f{'time'}(:) = correct_time_values;
f{'time'}(penultimate:last) = (penultimate and last correct_time_values);
% For reasons that make no sense to me I had to do the previous line.
ncclose( filename ) % You have to "ncclose" the file to write the changes.

Return

The first question you are asking is "what is a record dimension?" It is becoming common that netCDF files are written for individual months as opposed to larger files with data for a span of months or years. In order to concatenate the files into a single, larger file (see above) with the nco utilities, you need to add a "record dimension" to each file. The triplet of nco commands you need to do this are given on the NCO documentation WWW page (here).

The original file, "in.nc", does not have a record dimension.

ncks --mk_rec_dmn time in.nc out.nc
makes the dimension "time" the record dimension.

The old way to do this (pre 4.0.1) was:

ncecat -O -h in.nc out.nc
ncpdq -O -h -a time,record out.nc out.nc
ncwa -O -h -a record out.nc out.nc


Return

Sometimes the file has a time variable that has a value that you want to use in the fixed file. Consider the header and time value of the following file. As with Part I, you need to make time a "record dimension" so that NCOs will concatenate files.

netcdf filename {
dimensions:
        time = 1 ;
        lat = 89 ;
        lon = 180 ;
variables:
        float time(time) ;
                time:units = "days since 1854-01-15" ;
        float data(time,lat,lon)
        ...
data:
 time = 15 ;
}

set str1 = 'time = 1 ;'
set str2 = 'time = UNLIMITED ; // (1 currently)'
ncdump in.nc  | sed -e "s#^.$str1# $str2#" | ncgen -o out.nc

Return

Subsetting a region of an array is handled differently than subsetting time.

i) Subsetting a region

Say you have a global dataset, and you only want the data for the northeast portion of the Pacific Ocean.

ncea -d lat,minimum_lat,maximum_lat -d lon,minimum_lon,maximum_lon in.nc out.nc

where "lat" is what latitudes are called your file, and minimum_lat and maximum_lat are latitudes. Integer latitudes/longitudes are treated as indices, and floating point latitudes/longitudes are actual latitudes/longitudes. An example is in the NCO documentation.

If you are using a dateset with wrapped coordinates (sometimes called cyclical boundary conditions), for example the longitudes in a global dataset, and you want to subset across the step jump in the coordinate, ncks will perform the subsetting. An example is where the dataset longitudes span 0 to 360 degrees, and you want to subset a region that includes the Greenwich Meridian.

ncks -d lon,minimum_lon,maximum_lon in.nc out.nc

An example of the above would be a subset for the Sahel in a dataset where longitudes span 0 to 360:
ncks -d lon,340.0,10.0 -d lat,10.0,20.0 in.nc out.nc

ii) Subsetting time.

Subsetting in time can be performed by specifying the actual time written as floating point numbers or the time index values written as integers. Type "ncdump -v time filename.nc" (no quotes) to see what the time values are. If specifying time index values, you need to include the "-F" option if you are counting the first time value as "1". See the NCO documentation. [ Andres Roubicek pointed out the first method. ]

ncea -F -d time,first,last in.out out.nc

iii) Decimating in time or space.

One of the definitions of the word "decimate" is to remove every tenth member of a set, and in data processing the term has come to mean retaining only the n^th temporal or spatial gridploint of a dataset. An example of this is if the input file has 3-hourly data and you want to pick off the 00Z observations. This is accomplished with:

ncks -F -d time,1,,8 input.nc output.nc

where "-F" specificies that the counting begins with 1 as opposed to 0, and every 8th time record is kept, beginning with the first record.