Michael Thomas Flanagan's Java Scientific Library

ImmunoAssay Class:      Immunoassay curve fitting

      

Last update: 2 April 2012                                                                                                                              PERMISSION TO COPY
Main Page of Michael Thomas Flanagan's Java Scientific Library

This class contains the constructor and methods for fitting immunoassay response curves to one of a range of equations, constructing a standard curve based on the fitting to the equation and obtaining the analyte concentration for a given response, i.e. of a sample of unknown analyte concentration.
A method is available for comparing the goodness of fit to the different equations.

Methods for fitting immunoassay response (r) versus analyte concentration (a) data are available for the following equations and interpolation procedures:
If weighting factors are known for the entered data these may also be entered with the analyte concentratrions and assay responses and the regression procedures will be performed as weighted regressions. The weighting factors may also be set to be proportional to the resopnse values or to the square root of the response values.
The linear and non-linear (Nelder and Mead simplex minimisation) regression procedures used in this class are described in the Regression class documentation. ImmunoAssay is a subclass of the Regression class.
The assay data may read from a text file or entered as values stored as double[] arrays.

import directive: import flanagan.physchem.ImmunoAssay;

SUMMARY OF CONSTRUCTORS AND METHODS
Constructors public ImmunoAssay()
public ImmunoAssay(String title)
public ImmunoAssay(double[] analyteConcns, double[] responses)
public ImmunoAssay(double[] analyteConcns, double[] responses, String title)
public ImmunoAssay(double[] analyteConcns, double[] responses, double[] weights)
public ImmunoAssay(double[] analyteConcns, double[] responses, double[] weights, String title)
public ImmunoAssay(double[] analyteConcns, double[] responses, double[] xErrors, double[] yErrors)
public ImmunoAssay(double[] analyteConcns, double[] responses, double[] xErrors, double[] yErrors, String title)
Enter the analyte concentrations public void enterAnalyteConcns(double[] analyteConcns)
public void enterAnalyteConcnsAsLog10(double[] analyteConcns)
public void enterAnalyteConcnsAsLogE(double[] analyteConcns)
public double[] getAnalyteConcns()
Enter the responses public void enterResponses(double[] responses)
public void enterResponsesAsLog10(double[] responses)
public void enterResponsesAsLogE(double[] responses)
public double[] getResponses()
Weighting factors Enter as uncertaintities public void enterWeights(double[] weights)
public void enterWeightsAsLog10(double[] weights)
public void enterWeightsAsLogE(double[] weights)
Enter as multiplicative factors public void enterMultiplicativeWeights(double[] weights)
public void enterMultiplicativeWeightsAsLog10(double[] weights)
public void enterMultiplicativeWeightsAsLogE(double[] weights)
Calculate from the response values public void setWeightsAsResponses()
public void setWeightsAsSqrtResponses()
Set weights as true errors public void setErrorsAsSD();
public void setErrorsAsScaled();
Return the weighting factors public double[] getWeights()
Read assay curve data from a text file public void readFromFile()
public void readFromFile(String filename)
Enter a title public void enterTitle(String title)
public String getTitle()
Reset plotting option public void resetPlotOption(int option)
Set data public void setData()
Curve fitting Fit to an equation Five parameter logistic function public void fiveParameterLogisticFit()
public void fiveParameterLogisticFit(double bottom, double top)
Four parameter logistic function public void fourParameterLogisticFit()
public void fourParameterLogisticFit(double bottom, double top)
Best fit polynomial public int bestPolynomialFit()
Polynomial of given degree public void polynomialFit(int degree)
Non-integer polynomial public void nonIntegerPolynomialFit(int nTerms)
Sigmoid threshold function public void sigmoidThresholdFit()
Sips sigmoid function public void sipsSigmoidFit()
Shifted rectangular hyperbola public void shiftedRectangularHyperbolaFit()
Rectangular hyperbola public void rectangularHyperbolaFit()
Mass action model ‘Amersham’ model public void amershamFit()
public void amershamFit(double[] estimates)
Interpolation Cubic spline interpolation public void cubicSpline()
Linear interpolation public void linearInterpolation()
Select a fitting method via a dialogue box public void selectEquation()
Print an analysis of the goodness of fit public void print(String filename)
public void print()
Compare goodness of fit to two equations The pair of equations entered within the program coding public double compare(int equationIndex1, int equationIndex2)
public double compare(int equationIndex1, int equationIndex2, double significance)
public double compare(int equationIndex1, int equationIndex2, String filename)
public double compare(int equationIndex1, int equationIndex2, double significance, String filename)
The pair of equations selected via a dialogue box public double compare()
public double compare(double significance)
public double compare(String filename)
public double compare( double significance, String filename)
Return the concentration for a given response value Return the concentration public double getSampleConcn(double response)
Return the estimated error public double getSampleConcnError()
Model parameter estimates Parameter values public double[] getModelParameterValues()
Estimated parameter errors public double[] getModelParameterErrors()
Outlier detection Confidence interval public void[] setNintyNineLevel()
public void[] setNintyFiveLevel()
Fitted standard curve Reset number of points public void resetNfittedCurve(int nPoints)
Return working concentration range public double[] getWorkingConcentrationRange()
Return working response range public double[] getWorkingResponseRange()
Return fitted curve concentrations public double[] getFittedStandardCurveConcns()
Return fitted curve responses public double[] getFittedStandardCurveResponses()
Return number of turning points public int getNumberOfTurningPoints()
Return turning point concentrations public double[] getTurningPointConcns()
Return turning point responses public double[] getTurningPointResponses()
Ancillary methods Monotonicity Check monotonicity public static boolean isMonotonic(double[] data)
Surface concentrations Surface molar concentration public static double surfaceMolarConcn(double effectiveRadius)
public static double surfaceMolarConcn(double molWeight, double specVolume)
Surface number concentration public static double surfaceNumberConcn(double effectiveRadius)
public static double surfaceNumberConcn(double molWeight, double specVolume)
Equivalent molar volume concentration public static double equivalentVolumeConcn(double effectiveRadius, double area, double volume)
public static double equivalentVolumeConcn(double molWeight, double area, double volume, double specVolume)
public static double convertSurfaceToVolumeConcn(double surfaceConcn, double area, double volume)
Molecular radius public static double molecularRadius(double molWeight, double specVol)
public static double molecularRadius(double molWeight)
public static double effectiveRadius(double diffusionCoefficient, double viscosity, double temperature)
Molecular weights IgG1 public static double getMolWeightIgG1()
IgG2 public static double getMolWeightIgG2()
IgG3 public static double getMolWeightIgG3()
IgG4 public static double getMolWeightIgG4()
IgM public static double getMolWeightIgM()
IgA1 public static double getMolWeightIgA1()
IgA2 public static double getMolWeightIgA2()
IgD public static double getMolWeightIgD()
IgE public static double getMolWeightIgE()


CONSTRUCTOR

CONSTRUCTORS
public ImmunoAssay()
public ImmunoAssay(String title)
public ImmunoAssay(double[] analyteConcns, double[] responses)
public ImmunoAssay(double[] analyteConcns, double[] responses, String title)
public ImmunoAssay(double[] analyteConcns, double[] responses, double[] weights)
public ImmunoAssay(double[] analyteConcns, double[] responses, double[] weights, String title)
public ImmunoAssay(double[] analyteConcns, double[] responses, double[] xErrors, double[] yErrors)
public ImmunoAssay(double[] analyteConcns, double[] responses, double[] xErrors, double[] yErrors, String title)
Usage:                      ImmunoAssay assay = new ImmunoAssay();
Creates an instance of ImmunoAssay. The analyte concentrations, responses etc. must be entered via the appropriate methods described below. If no title is entered plots and text outputs will be entitled ‘Program ImmunoAssay’.

Usage:                      ImmunoAssay assay = new ImmunoAssay(title);
Creates an instance of ImmunoAssay. The analyte concentrations, responses etc. must be entered via the appropriate methods described below. The entered title will head plots and text outputs.

Usage:                      ImmunoAssay assay = new ImmunoAssay(analyteConcentrations, responses);
Creates an instance of ImmunoAssay. This constructor allows the analyte concentrations and responses to be entered. If they are entered via this constructor they will be treated as total analyte concentrations and as responses as arbitrary units. See methods described below for entering these using alternative units, e.g. free analyte concentrations.

Usage:                      ImmunoAssay assay = new ImmunoAssay(analyteConcentrations, responses, title);
Creates an instance of ImmunoAssay. This constructor allows the analyte concentrations and responses to be entered. The entered title will head plots and text outputs.

Usage:                      ImmunoAssay assay = new ImmunoAssay(analyteConcentrations, responses, weights);
Creates an instance of ImmunoAssay. This constructor allows the analyte concentrations, responses and weighting factors to be entered. The weighting factors ideally should be the uncertainty of the corresponding data point, e.g. the standard deviations of the responses calculated for several measurements at each analyte concentration. More commonly they are simply entered as arbitrary weights, i.e. as scaled estimates of the standard deviations. This constructor treats them as scaled weights and, if a regression procedure is called, adjusts them to give approximations to the standard deviations using the variance of the observations. Call the method setErrorsAsSD() if you wish to fix the weights entered via this constructor as true approximations to the standard deviations of the response measurements. See below for further discussion of weighting factors.

Usage:                      ImmunoAssay assay = new ImmunoAssay(analyteConcentrations, responses, weights, title);
Creates an instance of ImmunoAssay. This constructor allows the analyte concentrations, responses and weighting factors to be entered. The weighting factors ideally should be the uncertainty of the corresponding data point, e.g. the standard deviations of the responses calculated for several measurements at each analyte concentration. More commonly they are simply entered as arbitrary weights, i.e. as scaled estimates of the standard deviations. This constructor treats them as scaled weights and, if a regression procedure is called, adjusts them to give approximations to the standard deviations using the variance of the observations. Call the method setErrorsAsSD() if you wish to fix the weights entered via this constructor as true approximations to the standard deviations of the response measurements. See below for further discussion of weighting factors.
The entered title will head plots and text outputs.

Usage:                      ImmunoAssay assay = new ImmunoAssay(analyteConcentrations, responses, analyteErrors, responseErrors);
Creates an instance of ImmunoAssay. This constructor allows the analyte concentrations, responses, analyte measurement errors and response measurements errors to be entered. The analyte and response errors must be estimates of the standand deviations of the analyte concentration and of the response measurements. If a regression method is called the weighting factors will be calculated from these errors as described in the Regression documentation. See below for further discussion of weighting factors.

Usage:                      ImmunoAssay assay = new ImmunoAssay(analyteConcentrations, responses, analyteErrors, responseErrors, title);
Creates an instance of ImmunoAssay. This constructor allows the analyte concentrations, responses, analyte measurement errors and response measurements errors to be entered. The analyte and response errors must be estimates of the standand deviations of the analyte concentration and of the response measurements. If a regression method is called the weighting factors will be calculated from these errors as described in the Regression documentation. See below for further discussion of weighting factors.
The entered title will head plots and text outputs.


METHODS

ENTER ANALYTE CONCENTRATIONS
Enter the analyte concentrations
public void enterAnalyteConcns(double[] analyteConcns)
public void enterAnalyteConcnsAsLog10(double[] analyteConcns)
public void enterAnalyteConcnsAsLogE(double[] analyteConcns)
Usage:                      assay.enterAnalyteConcns(analyteConcentrations);
This method allows the analyte concentrations to be entered as an array of type double[]. The analyte concentrations may also be entered from a text file (see below).

Usage:                      assay.enterAnalyteConcnsAsLog10(analyteConcentrations);
This method allows the analyte concentrations to be entered as log10[analyte concentration].

Usage:                      assay.enterAnalyteConcnsAsLogE(analyteConcentrations);
This method allows the analyte concentrations to be entered as loge[analyte concentration].

Return the entered analyte concentrations
public double[] getAnalyteConcns()
Usage:                      concns = assay.getAnalyteConcns();
This method returns the entered analyte concentrations. It may be useful if the concentrations have been entered as log values or by a read from a text file method.


ENTER ASSAY RESPONSES
Enter the assay responses
public void enterResponses(double[] responses)
public void enterResponsesAslog10(double[] responses)
public void enterResponsesAsLogE(double[] responses)
Usage:                      assay.enterResponses(responses);
This method allows the allows the assay reponses to be entered as an array of type double[]. The responses may also be entered from a text file (see below).

Usage:                      assay.enterResponsesAsLog10(responses);
This method allows the allows the assay reponses to be entered as log10[response].

Usage:                      assay.enterResponsesAsLogE(responses);
This method allows the allows the assay reponses to be entered as loge[response].

Return the assay responses
public double[] getResponses()
Usage:                      responses = assay.getResponses();
This method returns the entered assay responses. It may be useful if the responses have been entered as log values or by a read from a text file method.


ENTER WEIGHTING FACTORS
Enter the weighting factors as uncertaintities
public void enterWeights(double[] weights)
public void enterWeightsAslog10(double[] weights)
public void enterWeightsAslogE(double[] weights)
Usage:                      assay.enterWeights(weights);
The weighted regression procedures minimise
    
where w[i] is the weighting factor. The weighting factors ideally should be the uncertainty of the corresponding data point, e.g. the standard deviations of the responses calculated for several measurements at each analyte concentration. More commonly they are simply entered as arbitrary weights, i.e. as scaled estimates of the standard deviations. This method treats them as scaled weights and, if a regression procedure is called, adjusts them to give approximations to the standard deviations using the variance of the observations. Call the method setErrorsAsSD() if you wish to fix the weights entered via this methodr as true approximations to the standard deviations of the response measurements. If your weighting factors, in contrast, decrease with increasing uncertainty in the response see below.
If no weights are entered all w[i] are set to unity
The weighting factors may also be entered from a text file or calculated from the response values.

Usage:                      assay.enterWeightsAsLog10(weights);
This method allows the above described weights to be entered as log10[weights].

Usage:                      assay.enterWeightsAsLogE(weights);
This method allows the above described weights to be entered as loge[weights].

Enter the weighting factors as multiplicative factors
public void enterMultiplicativeWeights(double[] weights)
public void enterMultiplicativeWeightsAslog10(double[] weights)
public void enterMultiplicativeWeightsAslogE(double[] weights)
Usage:                      assay.enterMultiplicativeWeights(weights);
If your weights decrease with increasing uncertainty in the response, i.e. require that the regression procedures minimise
    
enter your weighting factors via this method. It will convert your big W[i] to their reciprocals, i.e. little w[i], before assigning them to the relevant class variable.
If no weights are entered all w[i] are set to unity.
This, and the following two methods, are the only methods by which multiplicative weighting factors may be entered.

Usage:                      assay.enterMultiplicativeWeightsAsLog10(weights);
This method allows the above described multiplicative weights to be entered as log10[weights].

Usage:                      assay.enterMultiplicativeWeightsAsLogE(weights);
This method allows the above described multiplicative weights to be entered as loge[weights].

Calculate the weighting factors from the response values
public void setWeightsAsResponses()
public void setWeightsAsSqrtResponses()
Usage:                      assay.setWeightsAsResponses();
Calling this method causes the program to automatically set the weighting factors as proportional to the response values. This method is useful if it is known that the uncertaintity in the measured responses is proportional to the responses, i.e. is a constant percentage of the measured responses.

Usage:                      assay.setWeightsAsSqrtResponses();
Calling this method causes the program to automatically set the weighting factors as proportional to the square root of the response values. This method is useful if, for example, the errors are known to follow a Poisson distribution.

Return the weighting factors
public double[] getWeights()
Usage:                      responses = assay.getWeights();
This method returns the weighting factors. It may be useful if the weighting factors have been entered as multiplicative factors (see immediately above) or by a read from a text file method.

Set weights as true errors
public void setErrorsAsSD()
Usage:                      reg.setErrorsAsSD();
The weights entered via a constructor are used as weights in the weighted regressions and in the calculation of the errors associated with the best estimates of the unknown parameters. Ideally they should be estimates of the standard deviation of the corresponding y or x data value. If they are simply entered not as estimates of the standard deviation but as arbitrary weights that are internally consistent, i.e. as scaled estimates of the standard deviations, any regression will be unaffected by the scaling factor but the best estimate standard errors would be calculated incorrectly. The default method of this class is to assume the entered errors are not estimates of the standard deviations, are entered as scaled weights. The weights are then rescaled to approximate to standard deviation estimates, using the variance of the obsesrvation. If you know that your wights are good estimatedof the standard deviations of the measurements you can call this method and the weights will then be fixed at the values entered.

public void setErrorsAsScaled()
Usage:                      reg.setErrorsAsScaled();
This method resets the best estimate error calculation option to the default option, i.e. assuming entered experimental errors are arbitrary weights.


ENTER ASSAY DATA FROM A TEXT FILE
public void readFromFile()
public void readFromFile(String filename)
Usage:                      assay.readFromFile();
If this method is called a file selection window will open allowing the input data file to be selected. The window will open displaying the contents of the current directory but also allowing browsing of all non-hidden directories.
The text file must be one of the two following formats:

Weighted data
If weighting factors are also to be entered the following format is required:

Title
AnalyteConcn1    Response1    Weight1
AnalyteConcn2    Response2    Weight2
AnalyteConcn3    Response3    Weight3
....
....
....
AnalyteConcnn    Response1n    Weightn

 where AnalyteConcni is the ith analyte concentration, Responsei is the ith response and Weighti is the ith weighting factor.
The weigting factors must be estimates of the response uncertainties and not multiplicative factors. See entering weighting factors (above) for a discussion of weighting factors.
The AnalyteConcni, Responsei and Weighti values should be separated by a space, a tab, a comma, a semicolon or a colon.
Once the file is selected the data will be automatically read into the program.
See ImmunoAssayData.txt for an example data input file.

Unweighted data
If no weighting factors are also to be entered the following format is required:

Title
AnalyteConcn1    Response1
AnalyteConcn2    Response2
AnalyteConcn3    Response3
....
....
....
AnalyteConcnn    Response1n

 where AnalyteConcni is the ith analyte concentration and Responsei is the ith response.
The AnalyteConcni and Responsei values should be separated by a space, a tab, a comma, a semicolon or a colon.
Once the file is selected the data will be automatically read into the program.
See ImmunoAssayDataTwo.txt for an example data input file.

Usage:                      assay.readFromFile(filename);
As immediately above (readFromFile()) with the exception that the input data file name is supplied as the method's argument [filename] and is not selected via a file chooser window.

Both methods automatically enter the read data into the appropriate arrays. However, if the entered data is also required for other calculations not supplied by this class, the entered data may be accessed through the following methods:

Return the entered analyte concentrations
public double[] getAnalyteConcns()
Usage:                      concns = assay.getAnalyteConcns();
This method returns the entered analyte concentrations.

Return the assay responses
public double[] getResponses()
Usage:                      responses = assay.getResponses();
This method returns the entered assay responses.

Return the title
public String getTitle()
Usage:                      title = assay.getTitle();
This method returns the entered or default title.


ENTER TITLE
Enter a title
public void enterTitle(String title)
Usage:                      assay.enterTitle(title);
If this method is called plots and output text will be headed by the title entered by his method. Otherwise they will be headed by the simple title ‘Program ImmunoAssay’

Return the title
public String getTitle()
Usage:                      title = assay.getTitle();
This method returns the entered or default title.


RESET PLOT OPTION
public void resetPlotOption(int option)
Usage:                      assay.resetPlotOption(option);
All the fitting methods display a plot of the entered assay data and the best fit curve. The default option for these plots is concentration of analyte and assay response. This method allows one of the following alternatives to be chosen.

SET THE DATA ARRAYS IN THE SUPERCLASS
public void setData()
Usage:                      assay.setData();
If this method should ONLY be called if a superclass method is to be called before any of this subclass's fitting methods are called. Otherwise superclass data array setting occurs automatically.


FITTING DATA TO AN EQUATION

FIVE PARAMETER LOGISTIC FUNCTION [5PL]
public void fiveParameterLogisticFunctionFit()
public void fiveParameterLogisticFit(double bottom, double top)
Usage:                      assay.fiveParameterLogisticFunctionFit();
Calling this method fits the entered analyte concentrations and responses to a five parameter logistic function,
                  
where a is the analyte concentration and r is the response. The parameters to be estimated are bottom, top, C50, HillSlope and asymm. This method displays a plot of the best fit curve and of the entered data. A constrained non-linear regression (Nelder and Mead simplex procedure) is used to fit the data to the model equation. The value of C50 is constrained to positive values.
This method requires at least six, and preferably more, data points.

Usage:                      assay.fiveParameterLogisticFunctionFit(bottom, top);
Calling this method fits the entered analyte concentrations and responses to a five parameter logistic function,
                  
where a is the analyte concentration and r is the response. The parameters to be estimated are C50, HillSlope and asymm. The parametres bottom and top are fixed and are entered as the method's arguments, top and bottom. This method displays a plot of the best fit curve and of the entered data. A constrained non-linear regression (Nelder and Mead simplex procedure) is used to fit the data to the model equation. The value of C50 is constrained to positive values.
This method requires at least four, and preferably more, data points.

FOUR PARAMETER LOGISTIC FUNCTION [4PL, EC50 DOSE RESPONSE CURVE]
public void fourParameterLogisticFunctionFit()
public void fourParameterLogisticFit(double bottom, double top)
Usage:                      assay.fourParameterLogisticFunctionFit();
Calling this method fits the entered analyte concentrations and responses to four parameter logistic function also referred to as a EC50 dose response curve,
                  
where a is the analyte concentration and r is the response. The parameters to be estimated are bottom, top, C50 and HillSlope. This method displays a plot of the best fit curve and of the entered data. A constrained non-linear regression (Nelder and Mead simplex procedure) is used to fit the data to the model equation. The value of C50 is constrained to positive values.
This method requires at least five, and preferably more, data points.

Usage:                      assay.fourParameterLogisticFunctionFit(bottom, top);
Calling this method fits the entered analyte concentrations and responses to a five parameter logistic function,
                  
where a is the analyte concentration and r is the response. The parameters to be estimated are C50 and HillSlope. The parametres bottom and top are fixed and are entered as the method's arguments, top and bottom. This method displays a plot of the best fit curve and of the entered data. A constrained non-linear regression (Nelder and Mead simplex procedure) is used to fit the data to the model equation. The value of C50 is constrained to positive values.
This method requires at least three, and preferably more, data points.

BEST FIT POLYNOMIAL
public int bestPolynomialFit()
Usage:                      deg = assay.bestPolynomialFit();
Calling this method fits the entered analyte concentrations and responses to a polynomial,
     r = c0 + c1.a + c2.a2 + . . . + cn.an
where a is the analyte concentration, r is the response and that statistically gives the best fit. The best fit polynomial as determined by comparing the extra sum of squares F-ratio probabilities of successive pairs of polynomials of increasing degree. This method displays a plot of the best fit curve and of the entered data. It also returns the degree, n, of the best fit polynomial. Linear regression is used to fit the data to the tested polynomial equations.
The maximum degree that will be examined is two less than the number of data points.

POLYNOMIAL OF A USER SUPPLIED DEGREE
public void polynomialFit(int degree)
Usage:                      assay.polynomialFit(degree);
Calling this method fits the entered analyte concentrations and responses to a polynomial,
     r = c0 + c1.a + c2.a2 + . . . + cn.an
where a is the analyte concentration, r is the response and for which the user supplied value of the degree, n, is passed as the argument of the method. This method displays a plot of the best fit curve and of the entered data. Linear regression is used to fit the data to the model equation.
The maximum degree that can be entered is two less than the number of data points.

NON-INTEGER POLYNOMIAL
public void nonIntegerPolynomialFit(int nTerms)
Usage:                      assay.nonIntegerPolynomialFit();
Calling this method fits the entered analyte concentrations and responses to a non-integer polynomial,
    
where a is the analyte concentration, r is the response and nTerms is the number of terms and equals n + 1. This method displays a plot of the best fit curve and of the entered data. Non-linear regression (Nelder and Mead simplex procedure) is used to fit the data to the model equation.
This method requires at least 2n+2, i.e. 2nTerms, and preferably more, data points.

SIGMOID THRESHOLD FUNCTION
public void sigmoidThresholdFit()
Usage:                      assay.sigmoidThresholdFit();
Calling this method fits the entered analyte concentrations and responses to the sigmoid threshold function,
    
where a is the analyte concentration and r is the response. This method displays a plot of the best fit curve and of the entered data. Non-linear regression (Nelder and Mead simplex procedure) is used to fit the data to the model equation.
This method requires at least four, and preferably more, data points.

SIPS SIGMOID FUNCTION
public void sipsSigmoidFit()
Usage:                      assay.sipsSigmoidFit();
Calling this method fits the entered analyte concentrations and responses to the Sips sigmoid function,
    
where a is the analyte concentration and r is the response. This method displays a plot of the best fit curve and of the entered data. A constrained non-linear regression (Nelder and Mead simplex procedure) is used to fit the data to the model equation. The value of θ is constrained to positive values. This method has a high failure to fit rate with sigmoid curves with a negative gradient.
This method requires at least four, and preferably more, data points.

SHIFTED RECTANGULAR HYPERBOLA
public void shiftedRectangularHyperbolaFit()
Usage:                      assay.shiftedRectangularHyperbolaFit();
Calling this method fits the entered analyte concentrations and responses to a shifted rectangular hyperbola,
    
where a is the analyte concentration and r is the response. This method displays a plot of the best fit curve and of the entered data. Non-linear regression (Nelder and Mead simplex procedure) is used to fit the data to the model equation.
This method requires at least four, and preferably more, data points.

RECTANGULAR HYPERBOLA
public void rectangularHyperbolaFit()
Usage:                      assay.rectangularHyperbolaFit();
Calling this method fits the entered analyte concentrations and responses to a rectangular hyperbola,
    
where a is the analyte concentration and r is the response. This method displays a plot of the best fit curve and of the entered data. Non-linear regression (Nelder and Mead simplex procedure) is used to fit the data to the model equation.
This method requires at least three, and preferably more, data points.

‘AMERSHAM’ MASS ACTION MODEL
public void amershamFit() public void amershamFit(double[] estimates)
Usage:                      assay.amershamFit();
Calling this method fits the entered analyte concentrations and responses to the modified ‘Amersham’ mass action model,
    
where a is the analyte concentration and r is the response. This equation is derived from a model of a simple competitive assay equilibrium where K is the dissociation constant, c is the labeled analyte concentration, p is the antibody concentration and b is the non-specifically bound concentration of labelled analyte. This model is usually too simple to correspond to reality and this equation is, essentially, used as an empirical fitting equation. Pairs of the parameters, K, c p and b, are so highly correlated that even if the model does correspond to the actual assay equilibrium a very good best fit may be reached in which the best estimates of these parameters do not match the true values. The original equation was derived for a response that was the signal representing the bound label divided by the total signal, i.e. the concentration of labelled material added to the assay mixture. The scaling parameter S has been added to enable responses of arbitrary units to be fitted.

This model is applicable only to data conforming to that of a competitive assay and the method checks whether this is the case. Data that is highly divergent from a competitive curve will not be fitted, a message to that effect will be displayed, and data that is partially divergent from a competitive curve will be fitted but with a displayed warning.

This method displays a plot of the best fit curve and of the entered data. A constrained non-linear regression (Nelder and Mead simplex procedure) is used to fit the data to the model equation. The values of K, c p, b and S are constrained to positive values.

This method requires at least six, and preferably more, data points.

Usage:                      assay.amershamFit(estimates);
This method performs the same fitting as described for amershamFit() immediately above. The only difference is that the above method calculates the initial estimates of the parameters to be estimated required by the non-linear regression method. This calculation is based on an examination of the data. This approach may well lead to an inappropriate set of initial estimates when the parameters to be estimated are as correlated as are those of this model. This method allows a set of initial estimates [method argument estimates] to be entered which may be more appropriate than those that would have been calculated internally.

CUBIC SPLINE INTERPOLATION
public void cubicSpline()
Usage:                      assay.cubicSpline();
Calling this method constructs a standard curve using cubic spline interpolations of the entered data.
This method displays a plot of the interpolated curve and of the entered analyte concentrations and responses.
This method requires at least three, and preferably more, data points.

LINEAR INTERPOLATION
public void linearInterpolation()
Usage:                      assay.linearInterpolation();
Calling this method constructs a standard curve using a linear interpolations of the entered data
    
where a is the analyte concentration and r is the response. This method displays a plot of the interpolated curve and of the entered analyte concentrations and responses.
This method requires at least two, and preferably more, data points.


SELECT AN EQUATION VIA A DIALOGUE BOX
public void selectEquation()
Usage:                      assay.selectEquation();
If this method is called the program displays a dialogue box listing all the above fitting equations with a set of click boxes. The required equation can be chosen by clicking the appropriate click box. If a polynomial fitting of user supplied degree is chosen a further dialogue box will appear requesting the value of the polynomial degree.


RETURN THE ANALYTE CONCENTRATION FOR A GIVEN RESPONSE
Return an estimate of the unknown concentration
public double getSampleConcn(double response)
Usage:                      concn = assay.getSampleConcn(response);
This method returns the analyte concentration for the response value passed as the method's argument. The value is obtained as a cubic spline interpolation of the calculated responses versus the concentrations used to fitted standard curve. If the entered response lies outside the working range of the fitted standard assay curve a warning is displayed and NaN is returned.

Return an estimate of the uncertainty of the estimate of the unknown concentration
public double getSampleConcnError()
Usage:                      concn = assay.getSampleConcnError();
This method returns an estimate of the uncertainty of the analyte concentration returned for the last response value passed as the getSampleConcn method's argument. The value is a relatively crude estimate calculated as a standard error based on the overall variance of the fit, scaled by the weights if these have been entered.


PRINT AN ANALYSIS OF THE FITTED STANDARD CURVE
public void print(String filename)
public void print()
Usage:                      assay.print(filename);
This method prints to a file, named as the method's argument filename, an analysis of the fitted standard curve.
The analysis contains
* Possible outliers are defined as those points at which the residual falls outside the 95% confidence interval assuming that the residuals are normally distributed. Consequently the presence of possible outliers may depend on the equation chosen in the curve fitting and the quality of the goodness of fit. The 95% confidence interval may be reset to a 99% interval (see below for this resetting method and for comments on the outlier test used).

There is no output file associated with the cubic spline method [CubicSplineFit()].
The file is printed as a text file so it is sensible to end the filename with the extension .txt or a text file readable equivalent. If the filename has no extension .txt is added to the filename by this method.

WARNING: In the case of a non-linear regression the statistics are calculated assuming that the model behaves as a linear model close to the minimum in the sum of squares surface and that linear statistical formulae will be a good approximation and have been used. As no serious estimation of non-linearity is made the non-linear statistical values should be teated with great caution.

Usage:                      assay.print();
This method is similar to that described immediately above with the exception that the output file is always called ‘ImmunoAssayOutput.txt’.

An example, ImmunoAssayOneOutput.txt, of a print method output file may be found in the Example Program Section.


OUTLIER DETECTION

Each unweighted residual is examined, using a discordancy test, as to whether it may be classed as an outlier. Strictly this dicordancy test should be applied only to the most extreme potential outlier. Consequently this use of the test simply gives a crude indication of possible outliers and if they are indicated the data should be revisited using a more rigorous approach to outlier elimination. If outliers are suggested the most extreme outlier is indicated in the output text file. A discussion of outlier detection may be found in
Vic Barnett and Toby Lewis (1984), Outliers in Statistical Data, 2nd Ed., John Wiley and Sons, Chichester and New York.
The data needed to calculate the test's critical value has been taken from this work, pages 163-168 and 377 [test N1].

Reset outlier confidence interval
public void setNintyNineLevel()
public void setNintyFiveLevel()
Usage:                      assay.setNintyNineLevel();
This method resets to 99% the limits of the confidence interval outside which an unweighted residual suggests the data point be considered as an outlier. The default value is 95%.

Usage:                      assay.setNintyFiveLevel();
This method resets to 95% the limits of the confidence interval outside which an unweighted residual suggests the data point be considered as an outlier. This method need only be called if this value has been reset to 99% and a return to the default value of 95% is required.


COMPARE THE GOODNESS OF FIT TO TWO EQUATIONS

public double compare(int equationIndex1, int equationIndex2)
public double compare(int equationIndex1, int equationIndex2, double significance)
public double compare(int equationIndex1, int equationIndex2, String filename)
public double compare(int equationIndex1, int equationIndex2, double significance, String filename)
public double compare()
public double compare(double significance)
public double compare(String filename)
public double compare( double significance, String filename)

Usage:                      assay.compare(equationIndex1, equationIndex2, significance, filename);
This method compares the goodness of fit of the fitting of the entered data to two models, equation one and equation two, where these models are indicated by the int arguments, equationIndex1 and equationIndex2. The values of these two int arguments, i.e the entered indices, indicate the following equations:
The argument, significance, is the significance level used in the F-test analysis described below, e.g. if a 0.1 (10%) significance is required enter 0.1. The default value is 0.05 (5%) [for default method see below].
The argument, filename, is the name of the file to which an analysis of the comparison is printed. The default value is ‘ImmunoAssayComparison.txt’ [for default method see below].
The printed analysis contains
A comparison of the two F-ratio values or the calculated probabilty and the significance probabilty allows an assessment as to whether one can conclude that one fit is better than the other.
The analysis print out then contains the analysis of the fitting to both equations as described under the analysis and print methods.
If further data is required, e.g. the degree of the polynomial if one or both of the equationIndex arguments is that of the fit to a polynomial method the further data will be requested via a dialogue box.
An example, ImmunoAssayfourOutput.txt, of the output file provided by this method can be found in the Example Programs Section.

Usage:                      assay.compare(equationIndex1, equationIndex2, significance);
This method is as described above for compare(equationIndex1, equationIndex2, significance, filename) with the exception that the default analysis outut file name ‘ImmunoAssayComparison.txt’ is used.
Usage:                      assay.compare(equationIndex1, equationIndex2, filename);
This method is as described above for compare(equationIndex1, equationIndex2, significance, filename) with the exception that the default significance, 0.05 (5%), is used.
Usage:                      assay.compare(equationIndex1, equationIndex2);
This method is as described above for compare(equationIndex1, equationIndex2, significance, filename) with the exception that both the default significance, 0.05 (5%), and the default analysis outut file name ‘ImmunoAssayComparison.txt’ are used.
Select the equations via a dialogue box
public double compare()
public double compare(double significance)
public double compare(String filename)
public double compare( double significance, String filename)
Usage:                      assay.compare(significance, filename);
If this method is called the program displays, consecutively, two dialogue boxes, each listing all the above fitting equations with a set of click boxes. The required two equation can be chosen by clicking the appropriate click box. If a polynomial fitting of user supplied degree is chosen a further dialogue box will appear requesting the value of the polynomial degree. The method then performs all the same functions as described above for compare(equationIndex1, equationIndex2, significance, filename).

Usage:                      assay.compare(significance);
This method is as described above for compare(significance, filename) with the exception that the default analysis outut file name ‘ImmunoAssayComparison.txt’ is used.
Usage:                      assay.compare(filename);
This method is as described above for compare(significance, filename) with the exception that the default significance, 0.05 (5%), is used.
Usage:                      assay.compare();
This method is as described above for compare(significance, filename) with the exception that both the default significance, 0.05 (5%), and the default analysis outut file name ‘ImmunoAssayComparison.txt’ are used.

MODEL PARAMETER ESTIMATES

PARAMETER VALUES

public double[] getModelParameterValues()
Usage:                      param = assay.getModelParameterValues();
This method returns the best estimates of the model parameters. They are returned in the following orders:
ESTIMATED PARAMETER ERRORS

public double[] getModelParameterErrors()
Usage:                      param = assay.getModelParameterErrors();
This method returns the estimated standard errors of the estimated best fit values of the model parameters. These are returned in the same order as are the parameters as listed above.
In non-linear regression methods the pseudo-linear approximation (see Warning) may occasionally fail and a standard error may not be calculable. Either NaN may be returned for individual parameters or the whole array may be returned as null. In such cases more details will be available in the analysis in the text file produced by the print method.


FITTED STANDARD CURVE

RESET THE NUMBER OF PLOTTING POINTS

public void resetNfittedCurve(int nPoints)
Usage:                      assay.resetNfittedCurve(nPoints);
This method allows the number of points used in plotting the standard curve and providing data points for interpolating an analyte concentration for a given response to be reset. The default value, if this method is not called, is 1000.


RETURN THE WORKING CONCENTRATION RANGE

public double[] getWorkingConcentrationRange()
Usage:                      range = assay.getWorkingConcentrationRange();
This method returns an array of two elements. The first is the lowest concentration and the second is the highest concentration defining the working range of the standard curve constructed by fitting the entered data to a model. These values may not correspond to the lowest and highest analyte concentrations entered. If the constructed standard curve contains turning points leading to regions in which there is an ambiguous relationship between concentration and response the standard curve is truncated to leave the largest non-ambiguous working range.


RETURN THE WORKING RESPONSE RANGE

public double[] getWorkingResponseRange()
Usage:                      range = assay.getWorkingResponseRange;
This method returns an array of two elements. The first is the response at the lowest concentration and the second is response at the highest concentration defining the working range of the standard curve constructed by fitting the entered data to a model. These values may not correspond to the responses at the lowest and highest analyte concentrations entered. If the constructed standard curve contains turning points leading to regions in which there is an ambiguous relationship between concentration and response the standard curve is truncated to leave the largest non-ambiguous working range.

RETURN THE FITTED STANDARD CURVE CONCENTRATIONS

public double[] getFittedStandardCurveConcns()
Usage:                      concns = assay.getFittedStandardCurveConcns()
This method returns the analyte concentrations used to construct the fitted standard curve. This is a large array; default length is 1000 elements.

RETURN THE FITTED STANDARD CURVE RESPONSES

public double[] getFittedStandardCurveResponses()
Usage:                      responses = assay.getFittedStandardCurveResponses()
This method returns the responses used to construct the fitted standard curve. This is a large array; default length is 1000 elements.

RETURN THE NUMBER OF TURNING POINTS IN THE FITTED STANDARD CURVE

public int getNumberOfTurningPoints()
Usage:                      nturn = assay.getNumberOfTurningPoints()
This method returns the number of turning points in the fitted standard curve.

RETURN THE ANALYTE CONCENTRATIONS AT THE TURNING POINTS IN THE FITTED STANDARD CURVE

public double[] getTurningPointConcns()
Usage:                      cturn = assay.getTurningPointConcns()
This method returns the analyte concentrations at the turning points in the fitted standard curve. If there are no turning points null is returned.

RETURN THE RESPONSES AT THE TURNING POINTS IN THE FITTED STANDARD CURVE

public double[] getTurningPointResponses()
Usage:                      rturn = assay.getTurningPointResponses()
This method returns the responses at the turning points in the fitted standard curve. If there are no turning points null is returned.


ANCILLARY METHODS

See ImmunoChemistry for a further ancillary methods.

MONOTONICITY

Check monotonicity
public static boolean isMonotonic(double[] data)
Usage:                      flag = ImmunoAssay.isMonotonic(data);
This method returns true if the data array, data, is monotonic and returns false if it is not.
Monotonicity is defined as all data[i] are either strictly increasing, i.e. all data[i+1]>data[i], or strictly deacreasing, i.e. all data[i+1]<data[i].
NOTE ONE: this is a very strict definition of monotonicity, i.e. any data[i+1] equal to data[i] leads to the data being classed as non-monotonic, as is appropriate for assay curves.
NOTE TWO: The responses entered by either the above constructors or enter methods is automatically checked for monotonicity and appropriate details of any non-monotonicity are displayed.


SURFACE CONCENTRATIONS

The following surface concentration calculation methods assume ideal spherical molecules and return approximations that may be useful in simple modelling and in setting intial estimates for non-linear regression procedures.

Surface molar concentration
public static double surfaceMolarConcn(double effectiveRadius)
public static double surfaceMolarConcn(double molWeight, double specVolume)
Usage:                      sconcn = ImmunoAssay.surfaceMolarConcn(effectiveRadius);
This method returns an approximate surface concentration, as moles per square metre, of a tightly packed surface monolayer of a molecule of effective molecular radius, e.g. hydrodynamic radius, effectiveRadius, in metres. The method assumes spherical molecules and hexagonal close packing.

Usage:                      sconcn = ImmunoAssay.surfaceMolarConcn(molWeight, specVolume);
This method returns an approximate surface concentration, as moles per square metre, of a tightly packed surface monolayer of a molecule of molecular weight, molWeight, and specific volume, specVolume, entered as cubic metres per kilogram. The method assumes spherical molecules and hexagonal close packing.

Surface number concentration
public static double surfaceNumberConcn(double effectiveRadius)
public static double surfaceNumberConcn(double molWeight, double specVolume)
Usage:                      sconcn = ImmunoAssay.surfaceNumberConcn(effectiveRadius);
This method returns an approximate surface concentration, as number of molecues per square metre, of a tightly packed surface monolayer of a molecule of effective molecular radius, e.g. hydrodynamic radius, effectiveRadius, in metres. The method assumes spherical molecules and hexagonal close packing.

Usage:                      sconcn = ImmunoAssay.surfaceNumberConcn(molWeight, specVolume);
This method returns an approximate surface concentration, as number of molecues per square metre, of a tightly packed surface monolayer of a molecule of molecular weight, molWeight, and specific volume, specVolume, entered as cubic metres per kilogram. The method assumes spherical molecules and hexagonal close packing.

Equivalent molar volume concentration
public static double equivalentVolumeConcn(double effectiveRadius, double area, double volume)
public static double equivalentVolumeConcn(double molWeight, double area, double volume, double specVolume)
public static double convertSurfaceToVolumeConcn(double surfaceConcn, double area, double volume)
Usage:                      vconcn = ImmunoAssay.equivalentVolumeConcn(effectiveRadius, area, volume);
This method returns an approximate equivalent volume molar concentration in a volume of liquid, volume entered as cubic metres, above an area, area entered as square metres, of a tightly packed surface monolayer of a molecule of molecular weight, molWeight. The method assumes hexagonal close packing and spherical molecules of specific volume 0.74x10-3 m/kg (0.74 cm3/gm).

Usage:                      vconcn = ImmunoAssay.equivalentVolumeConcn(molWeight, area, volume, specVolume);
This method returns an approximate equivalent volume molar concentration in a volume of liquid, volume entered as cubic metres, above an area, area entered as square metres, of a tightly packed surface monolayer of a molecule of effective molecular radius, e.g. hydrodynamic radius, effectiveRadius, in metres. The method assumes spherical molecules and hexagonal close packing.

Usage:                      vconcn = ImmunoAssay.convertSurfaceToVolumeConcn(surfaceConcn, area, volume);
This method converts a surface concentration, surfaceConcn in moles per square metre, to an equivalent molar volume concentration for a molecule immobilised on a surface area, area in square metres, in contact with a volume, volume in cubic metres.

MOLECULAR RADIUS

public static double molecularRadius(double molWeight, double specVol)
public static double molecularRadius(double molWeight)
public static double effectiveRadius(double diffusionCoefficient, double viscosity, double temperature)
Usage:                      radius = ImmunoAssay.molecularRadius(molWt, specVol);
This method returns an approximate molecular radius, as metres, of a molecule of molecular weight, molWeight and a specific volume, specVol in metres per kilogram. The method assumes a spherical molecule.

Usage:                      radius = ImmunoAssay.molecularRadius(molWt);
This method returns an approximate molecular radius, as metres, of a molecule of molecular weight, molWeight. The method assumes a spherical molecule and a specific volume of 0.74E-3 m/kg (0.74 ml/gm).

Usage:                      radius = ImmunoChemistry.effectiveRadius(diffusionCoefficient, viscosity, temperature);
This method returns an effective radius, r,

as metres, where D is the solute diffusion coefficient [diffusionCoefficient in square metres per second], η is the viscosity of the solution [viscosity in Pascal seconds], T is the temperature of the solution [temperature in degrees Celsius] and kB is Boltzmann's constant. The method assumes a spherical molecule. See Water for methods returning the viscosity of water, Saline for methods returning the viscosity of aqueous saline solutions and Sucrose for methods returning the viscosity of aqueous sucrose solutions.


ANTIBODY MOLECULAR WEIGHTS
public static double getMolWeightIgG1()
public static double getMolWeightIgG2()
public static double getMolWeightIgG3()
public static double getMolWeightIgG4()
public static double getMolWeightIgM()
public static double getMolWeightIgA1()
public static double getMolWeightIgA2()
public static double getMolWeightIgD()
public static double getMolWeightIgE()
Usage:                      molwt = ImmunoAssay.getMolWeightIgG1();
This method returns the molecular weight of IgG1.

Usage:                      molwt = ImmunoAssay.getMolWeightIgG2();
This method returns the molecular weight of IgG2.

Usage:                      molwt = ImmunoAssay.getMolWeightIgG3();
This method returns the molecular weight of IgG3.

Usage:                      molwt = ImmunoAssay.getMolWeightIgG4();
This method returns the molecular weight of IgG4.

Usage:                      molwt = ImmunoAssay.getMolWeightIgM();
This method returns the molecular weight of IgM.

Usage:                      molwt = ImmunoAssay.getMolWeightIgA1();
This method returns the molecular weight of IgA1.

Usage:                      molwt = ImmunoAssay.getMolWeightIgA2();
This method returns the molecular weight of IgA2.

Usage:                      molwt = ImmunoAssay.getMolWeightIgD();
This method returns the molecular weight of IgD.

Usage:                      molwt = ImmunoAssay.getMolWeightIgE();
This method returns the molecular weight of IgE.


EXAMPLE PROGRAMS

Example Program One
ImmunoAssayExampleOne illustrates the following

Example Program Two
ImmunoAssayExampleTwo illustrates the following

Example Program Three
ImmunoAssayExampleThree illustrates the following

Example Program Four
ImmunoAssayExampleFour illustrates the following

Example Program Five
ImmunoAssayExampleFive illustrates the following


OTHER CLASSES USED BY THIS CLASS

 This class uses the following classes in this library:

PERMISSION TO COPY

Permission to use, copy and modify this software and its documentation for NON-COMMERCIAL purposes is granted, without fee, provided that an acknowledgement to the author, Dr Michael Thomas Flanagan at www.ee.ucl.ac.uk/~mflanaga, appears in all copies and associated documentation or publications. Dr Michael Thomas Flanagan makes no representations about the suitability or fitness of the software for any or for a particular purpose. Dr Michael Thomas Flanagan shall not be liable for any damages suffered as a result of using, modifying or distributing this software or its derivatives.

Redistributions of the source code of this class, or parts of the source codes, must retain the copyright notice, this list of conditions and the following disclaimer (all at the top of the source code) and requires written permission from the Michael Thomas Flanagan:

Redistribution in binary form of all or parts of this class must reproduce the copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution and requires written permission from the Michael Thomas Flanagan:
.


This page was prepared by Dr Michael Thomas Flanagan