Next: , Previous: ncecat netCDF Ensemble Concatenator, Up: Operator Reference Manual


4.6 ncflint netCDF File Interpolator

SYNTAX

     ncflint [-3] [-4] [-6] [-A] [-C] [-c] [-D dbg]
     [-d dim,[min][,[max][,[stride]]] [-F] [-h] [-i var,val3]
     [-L dfl_lvl] [-l path] [-O] [-o file_3] [-p path] [-R] [-r]
     [-t thr_nbr] [-v var[,...]] [-w wgt1[,wgt2]] [-X ...] [-x]
     file_1 file_2 [file_3]

DESCRIPTION

ncflint creates an output file that is a linear combination of the input files. This linear combination is a weighted average, a normalized weighted average, or an interpolation of the input files. Coordinate variables are not acted upon in any case, they are simply copied from file_1.

There are two conceptually distinct methods of using ncflint. The first method is to specify the weight each input file contributes to the output file. In this method, the value val3 of a variable in the output file file_3 is determined from its values val1 and val2 in the two input files according to

val3 = wgt1*val1 + wgt2*val2

. Here at least wgt1, and, optionally, wgt2, are specified on the command line with the ‘-w’ (or ‘--weight’ or ‘--wgt_var’) switch. If only wgt1 is specified then wgt2 is automatically computed as wgt2 = 1 − wgt1. Note that weights larger than 1 are allowed. Thus it is possible to specify wgt1 = 2 and wgt2 = -3. One can use this functionality to multiply all the values in a given file by a constant.

The second method of using ncflint is to specify the interpolation option with ‘-i (or with the ‘--ntp’ or ‘--interpolate’ long options). This is really the inverse of the first method in the following sense. When the user specifies the weights directly, ncflint has no work to do besides multiplying the input values by their respective weights and adding the results together to produce the output values. It makes sense to use this when the weights are known a priori.

Another class of problems has the arrival value (i.e., val3) of a particular variable var known a priori. In this case, the implied weights can always be inferred by examining the values of var in the input files. This results in one equation in two unknowns, wgt1 and wgt2:

val3 = wgt1*val1 + wgt2*val2

. Unique determination of the weights requires imposing the additional constraint of normalization on the weights: wgt1 + wgt2 = 1. Thus, to use the interpolation option, the user specifies var and val3 with the ‘-i’ option. ncflint then computes wgt1 and wgt2, and uses these weights on all variables to generate the output file. Although var may have any number of dimensions in the input files, it must represent a single, scalar value. Thus any dimensions associated with var must be degenerate, i.e., of size one.

If neither ‘-i’ nor ‘-w’ is specified on the command line, ncflint defaults to weighting each input file equally in the output file. This is equivalent to specifying ‘-w 0.5’ or ‘-w 0.5,0.5’. Attempting to specify both ‘-i’ and ‘-w’ methods in the same command is an error.

ncflint does not interpolate variables of type NC_CHAR and NC_BYTE. This behavior is hardcoded.

Depending on your intuition, ncflint may treat missing values unexpectedly. Consider a point where the value in one input file, say val1, equals the missing value mss_val_1 and, at the same point, the corresponding value in the other input file val2 is not misssing (i.e., does not equal mss_val_2). There are three plausible answers, and this creates ambiguity.

Option one is to set val3 = mss_val_1. The rationale is that ncflint is, at heart, an interpolator and interpolation involving a missing value is intrinsically undefined. ncflint currently implements this behavior since it is the most conservative and least likely to lead to misinterpretation.

Option two is to output the weighted valid data point, i.e.,

val3 = wgt2*val2

. The rationale for this behavior is that interpolation is really a weighted average of known points, so ncflint should weight the valid point.

Option three is to return the unweighted valid point, i.e., val3 = val2. This behavior would appeal to those who use ncflint to estimate data using the closest available data. When a point is not bracketed by valid data on both sides, it is better to return the known datum than no datum at all.

The current implementation uses the first approach, Option one. If you have strong opinions on this matter, let us know, since we are willing to implement the other approaches as options if there is enough interest.

EXAMPLES

Although it has other uses, the interpolation feature was designed to interpolate file_3 to a time between existing files. Consider input files 85.nc and 87.nc containing variables describing the state of a physical system at times time = 85 and time = 87. Assume each file contains its timestamp in the scalar variable time. Then, to linearly interpolate to a file 86.nc which describes the state of the system at time at time = 86, we would use

     ncflint -i time,86 85.nc 87.nc 86.nc

Say you have observational data covering January and April 1985 in two files named 85_01.nc and 85_04.nc, respectively. Then you can estimate the values for February and March by interpolating the existing data as follows. Combine 85_01.nc and 85_04.nc in a 2:1 ratio to make 85_02.nc:

     ncflint -w 0.667 85_01.nc 85_04.nc 85_02.nc
     ncflint -w 0.667,0.333 85_01.nc 85_04.nc 85_02.nc

Multiply 85.nc by 3 and by −2 and add them together to make tst.nc:

     ncflint -w 3,-2 85.nc 85.nc tst.nc

This is an example of a null operation, so tst.nc should be identical (within machine precision) to 85.nc.

Add 85.nc to 86.nc to obtain 85p86.nc, then subtract 86.nc from 85.nc to obtain 85m86.nc

     ncflint -w 1,1 85.nc 86.nc 85p86.nc
     ncflint -w 1,-1 85.nc 86.nc 85m86.nc
     ncdiff 85.nc 86.nc 85m86.nc

Thus ncflint can be used to mimic some ncbo operations. However this is not a good idea in practice because ncflint does not broadcast (see ncbo netCDF Binary Operator) conforming variables during arithmetic. Thus the final two commands would produce identical results except that ncflint would fail if any variables needed to be broadcast.

Rescale the dimensional units of the surface pressure prs_sfc from Pascals to hectopascals (millibars)

     ncflint -C -v prs_sfc -w 0.01,0.0 in.nc in.nc out.nc
     ncatted -a units,prs_sfc,o,c,millibar out.nc