Next: , Previous: Missing values ncap2, Up: ncap2 netCDF Arithmetic Processor


4.1.11 Methods and functions

The convention within this document is that methods can be used as functions. However, functions are not and cannot be used as methods. Methods can be daisy changed together and their syntax is cleaner than functions. Method names are reserved words and CANNOT be used as variable names. The command ncap2 -f shows the complete list of methods available on your build.

     n2=sin(theta)
     n2=theta.sin()
     n2=sin(theta)^2 + cos(theta)^2
     n2=theta.sin().pow(2) + theta.cos()^2

This statement chains methods together to convert three_dmn_var_sht to type double, average it, then convert this back to type short:

     three_avg=three_dmn_var_sht.double().avg().short();

Aggregate Methods
These methods mirror the averaging types available in ncwa. The arguments to the methods are the dimensions to average over. Specifying no dimensions is equivalent to specifying all dimensions i.e., averaging over all dimensions. A masking variable and a weighting variable can be manually created and applied as needed.
avg()
Mean value
sqravg()
Square of the mean
avgsqr()
Mean of sum of squares
max()
Maximum value
min()
Minimum value
rms()
Root-mean-square (normalize by N)
rmssdn()
Root-mean square (normalize by N-1)
ttl() or total()
Sum of values
     // Average a variable over time
     four_time_avg=four_dmn_rec_var($time);

Packing Methods
For more information see see Packed data and see ncpdq netCDF Permute Dimensions Quickly
pack() & pack_short()
The default packing algorithm is applied and variable is packed to NC_SHORT
pack_byte()
Variable is packed to NC_BYTE
pack_short()
Variable is packed to NC_SHORT
pack_int()
Variable is packed to NC_INT
unpack()
The standard unpacking algorithm is applied.

Basic Methods
These methods work with variables and attributes. They have no arguments

size()
Total number of elements
ndims()
Number of dimensions in variable
type()
Returns the netcdf type (see previous section)

Utility Methods
These functions are used to manipulate missing values and RAM variables. see Missing values ncap2
set_miss(expr)
Takes one argument the missing value. Sets or overwrites the existing missing value. The argument given is converted if necessary to the variable type
change_miss(expr)
Changes the missing value elements of the variable to the new missing value (n.b. an expensive function).
get_miss()
Returns the missing value of a variable in Input or Output
delete_miss()
Deletes the missing value associated with a variable.
ram_write()
Writes a RAM variable to disk i.e., converts it to a regular disk type variable
ram_delete()
Deletes a RAM variable or an attribute

PDQ Methods
See see ncpdq netCDF Permute Dimensions Quickly
reverse(dim args)
Reverses the dimension ordering of elements in a variable.
permute(dim args)
Re-shapes variables by re-ordering the dimensions. All the dims of the variable must be specified in the arguments. A limitation of this permute (unlike ncpdq) is that the record dimension cannot be re-assigned.
// Swap dimensions about and reorder along lon
     lat_2D_rrg_new=lat_2D_rrg.permute($lon,$lat).reverse($lon);
     lat_2D_rrg_new=0,90,-30,30,-30,30,-90,0

Type Conversion Methods
These methods allow ncap2 to convert variables and attributes to the different netcdf types. For more details on automatic and manual type conversion see (see Type Conversion). You can only use the new netCDF4 types if you have compiled/links NCO with the netCDF4 library and the Output file is HDF5.
netCDF3/4 Types
byte()
convert to NC_BYTE, a signed 1-byte integer
char()
convert to NC_CHAR, an ISO/ASCII character
short()
convert to NC_SHORT, a signed 2-byte integer
int()
convert to NC_INT, a signed 4-byte integer
float()
convert to NC_FLOAT, a single-precision (4-byte) floating point number
double()
convert to NC_DOUBLE, a double-precision (8-byte) floating point number

netCDF4 Types
ubyte()
convert to NC_UBYTE, an unsigned 1-byte integer
ushort()
convert to NC_USHORT, an unsigned 2-byte integer
uint()
convert to NC_UINT, an unsigned 4-byte integer
int64()
convert to NC_INT64, a signed 8-byte integer
uint64()
convert to NC_UINT64, an unsigned 8-byte integer

Intrinsic Mathematical Methods
The list of mathematical methods is system dependant. For the full list see Intrinsic mathematical methods

All the mathematical methods take a single operand ,with the exception of atan2 and pow which take two. If the operand type is less than float then the result will be of type float. If the operand is type double then the result will be type double. Like the other methods, you are free to use the mathematical methods as functions.

     n1=pow(2,3.0f)    // n1 type float
     n2=atan2(2,3.0)   // n2 type double
     n3=1/(three_dmn_var_dbl.cos().pow(2))-tan(three_dmn_var_dbl)^2; // n3 type double