Creating Linear Fit Plugins

Two header files are provided for performing linear fits, linear.h (for unweighted linear fits) and linear_weighted.h (for weighted linear fits). They are both located under kst/plugins/fits/ in the Kst source tarball. To use these files, include only one of them in the source code for your plugin:

#include <../linear.h>

or

#include <../linear_weighted.h>

(by convention, we will place the source code for the plugin one directory below where the header files are).

Given a general linear model:

where y is a vector of n observations, X is an n by p matrix of predictor variables, and c is the vector of p best-fit parameters that are to be estimated, the header files provide functions for estimating c for a given y and X. To provide X, the following function needs to be implemented in the source code for the plugin:

This function should return the value of the entry in column iPos of the matrix of predictor variables, using x value dX. This function will be called by linear.h or linear_weighted.h. The implementation of this function depends on the model you wish to use for the fit, and is unique to each linear fit plugin. For example, to fit to a polynomial model, calculate_matrix_entry could be implemented as follows:

double calculate_matrix_entry( double dX, int iPos ) {
  double dY;
  dY = pow( dX, (double)iPos );
  return dY;
}

Once the appropriate header file has been included and calculate_matrix_entry has been implemented, call the appropriate fitting function included from the header file:

kstfit_linear_unweighted( inArrays, inArrayLens,
                          outArrays, outArrayLens,
                          outScalars, iNumParams );

or

kstfit_linear_weighted( inArrays, inArrayLens,
                        outArrays, outArrayLens,
                        outScalars, iNumParams );

Each function will return 0 on success, or -1 on error, so it is a good idea to set the return value of the exported C function to be equal to the return value of the fitting function. To maintain simplicity, the code for the plugin can simply pass the arguments given to the exported C function to the fitting function. Note, however, that inArrays must be structured as follows:

The easiest way to ensure that inArrays is structured correctly is to specify the correct order of input vectors in the XML file for the plugin.

iNumParams is the number of parameters in the fitting model used, which should be equal to the number of columns in the matrix X of predictor variables. iNumParams must be set correctly before the fitting function is called.

After kstfit_linear_unweighted or kstfit_linear_weighted is called, outArrays and outScalars will be set as follows:

outArrayLens will be correctly set to indicate the length of each output array.

Ensure that the specified outputs in the XML file match those that the exported C function returns (which in most cases will simply be the outputs returned by the fitting function).

The following is an example of the source code for a linear fit plugin.

/*
 *  Polynomial fitting plugin for KST.
 *  Copyright 2004, The University of British Columbia
 *  Released under the terms of the GPL.
 */

#include "../linear.h"

double calculate_matrix_entry( double dX, int iPos ) {
  double dY;

  dY = pow( dX, (double)iPos );

  return dY;
}

extern "C" int kstfit_polynomial_unweighted(
  const double *const inArrays[],
  const int inArrayLens[],
  const double inScalars[],
  double *outArrays[], int outArrayLens[],
  double outScalars[]);

int kstfit_polynomial_unweighted(
  const double *const inArrays[],
  const int inArrayLens[],
	const double inScalars[],
	double *outArrays[], int outArrayLens[],
	double outScalars[])
{
  int iRetVal = -1;
  int iNumParams;

  iNumParams = 1 + (int)floor( inScalars[0] );
  if( iNumParams > 0 ) {
    iRetVal = kstfit_linear_unweighted( inArrays, inArrayLens,
                                        outArrays, outArrayLens,
                                        outScalars, iNumParams );
  }

  return iRetVal;
}