Difference between revisions of "High Level Functions"

From LIBISIS
Jump to navigation Jump to search
m
 
(9 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
Many powerful high level functions are provided. These manipulate datasets in a complicated manor.  
 
Many powerful high level functions are provided. These manipulate datasets in a complicated manor.  
  
These functions are
+
==Derrivative Functions==
<pre>>> wwout = deriv1x(ww)
 
>> wwout = deriv2x(ww)
 
>> wwout = deriv1y(ww)
 
>> wwout = deriv2y(ww)
 
>> wout = deriv1(w)
 
>> wout = deriv2(w)
 
>> wout = integrate_x(ww, xmin, xmax)
 
>> wout = integrate_y(ww, ymin, ymax)
 
>> dout = integrate_xy(ww, xmin, xmax, ymin, ymax)
 
>> dout = integrate(w, xmin, xmax)
 
>> wwout = smooth(ww)
 
>> wwout = smooth(w)
 
>> wwout = interp_x(ww, xarray, optional inputs)
 
>> wwout = interp_y(ww, yarray, optional inputs)
 
>> wout = interp(ww, xarray, optional inputs)
 
>> wwout = unspike(ww)
 
>> wwout = unspike(w)
 
>> [wwout fitdata] = fit(ww, func, pin, optional)
 
>> [wout fitdata] = fit(w, func, pin, optional)
 
>> wwout = func_eval(ww, func, args)
 
>> wout = func_eval(w, func, args)</pre>
 
  
  
==Derrivative Functions==
+
===First Derivative===
  
===First Derivative===
 
 
These functions take the derivatives of datasets.  
 
These functions take the derivatives of datasets.  
  
Line 42: Line 20:
 
* Output is an [[IXTdataset_1d]] object
 
* Output is an [[IXTdataset_1d]] object
 
* Calculates the first derivative of the dataset in the x direction
 
* Calculates the first derivative of the dataset in the x direction
 +
  
 
===Second Derivative===
 
===Second Derivative===
 +
 
These functions take the second derivatives of datasets.  
 
These functions take the second derivatives of datasets.  
  
Line 61: Line 41:
  
 
==Integral Functions==
 
==Integral Functions==
 +
 
These functions integrate a dataset between given limits using the trapezoid method.  
 
These functions integrate a dataset between given limits using the trapezoid method.  
  
Line 81: Line 62:
 
* Output is an [[IXTdatum]] object
 
* Output is an [[IXTdatum]] object
 
* Integral is evaluated between xmin and xmax
 
* Integral is evaluated between xmin and xmax
 +
  
 
==Smooth Functions==
 
==Smooth Functions==
 +
 
Smooth functions use an algorithm to smooth the data in a dataset to eliminate fluctuations.  
 
Smooth functions use an algorithm to smooth the data in a dataset to eliminate fluctuations.  
  
Line 91: Line 74:
 
* Output is the same object type as the input
 
* Output is the same object type as the input
 
* Options allow the user to set the method of smoothing and parameters
 
* Options allow the user to set the method of smoothing and parameters
 +
  
 
===Optional Inputs===
 
===Optional Inputs===
Line 102: Line 86:
  
 
* '''filter:''' May be 'box', 'gaussian', or the handle to a function that defines how the smoothing should occur. ''Default:'' 'box'
 
* '''filter:''' May be 'box', 'gaussian', or the handle to a function that defines how the smoothing should occur. ''Default:'' 'box'
* '''size:''' A vector indicating the size of the convolution kernel. '''Default:''' [3,3]
+
* '''size:''' A vector indicating the size of the convolution kernel. ''Default:'' [3,3]
 
* '''pars:''' are arguments required by filter if a function is given
 
* '''pars:''' are arguments required by filter if a function is given
 
* ''''nonorm:'''' turns off the normalisation in the kernel shell if filter is a user defined function
 
* ''''nonorm:'''' turns off the normalisation in the kernel shell if filter is a user defined function
  
 
See the Matlab online help for more information.
 
See the Matlab online help for more information.
 +
  
 
==Interpolate Functions==
 
==Interpolate Functions==
 +
 
These functions always return '''point''' datasets regardless of point or histogram input. It can be viewed as the point data equivilent to the [[Rebin Functions | rebin]] functions. A new set of x or y datapoints is given and the data interpolated accross them.  
 
These functions always return '''point''' datasets regardless of point or histogram input. It can be viewed as the point data equivilent to the [[Rebin Functions | rebin]] functions. A new set of x or y datapoints is given and the data interpolated accross them.  
  
Line 130: Line 116:
 
* ''Default'' method uses linear interpretation
 
* ''Default'' method uses linear interpretation
 
* Optional inputs allow control of method  
 
* Optional inputs allow control of method  
 +
  
 
=== Optional Inputs===
 
=== Optional Inputs===
Line 144: Line 131:
 
** 'cubic' - uses cubic interpolation  
 
** 'cubic' - uses cubic interpolation  
 
* '''Extrapval:''' value given to out of range points (usually NaN or 0)
 
* '''Extrapval:''' value given to out of range points (usually NaN or 0)
 +
  
 
==Unspike Functions==
 
==Unspike Functions==
 +
 
Used to remove spurious spikes from datasets
 
Used to remove spurious spikes from datasets
  
Line 156: Line 145:
 
* Spikes are replaced with an interpolated value
 
* Spikes are replaced with an interpolated value
 
* Optional inputs may be used to define what constitutes a spike (see Optional Inputs for definition of a spike)
 
* Optional inputs may be used to define what constitutes a spike (see Optional Inputs for definition of a spike)
 +
  
 
===Optional Inputs===
 
===Optional Inputs===
Line 167: Line 157:
 
* '''fac:''' If a signal point is within a factor FAC of both of its neighbours then is NOT a spike (''Default:'' 2)
 
* '''fac:''' If a signal point is within a factor FAC of both of its neighbours then is NOT a spike (''Default:'' 2)
 
* '''sfac:''' If the difference of a point w.r.t. both of its neighbours is less than SFAC standard deviations then the point is NOT a spike (''Default:'' 5)
 
* '''sfac:''' If the difference of a point w.r.t. both of its neighbours is less than SFAC standard deviations then the point is NOT a spike (''Default:'' 5)
 +
  
 
==Fitting Functions==
 
==Fitting Functions==
 +
 
These functions fit data to a function.
 
These functions fit data to a function.
  
Line 181: Line 173:
 
** '''func:''' Function to fit w to
 
** '''func:''' Function to fit w to
 
** '''pin:''' Starting parameters (a guess of what the best fit parameters will be) of the form [p1, p2, p3, ...]
 
** '''pin:''' Starting parameters (a guess of what the best fit parameters will be) of the form [p1, p2, p3, ...]
 +
  
 
===Function Format===
 
===Function Format===
 +
 +
The function used in the fitting must have a format compatable with the fitting algorithm, this means that to call the function the following syntax is used
 +
 +
 +
'''For one dimensional fitting'''
 +
<pre>>> y = func(x, pin, optional)  OR
 +
>> [y, name, pnames, pin] = func(x, pin, optional) </pre>
 +
 +
 +
'''For two dimensional fitting'''
 +
<pre>>> z = func(x, y, pin, optional)  OR
 +
>> [z, name, pnames, pin] = func(x, y, pin, optional) </pre>
 +
 +
* '''pin''' is a numeric array defining parameters of the function
 +
 +
The optional outputs are for advanced use of fit and mfit
 +
* '''name''' is the name of the function
 +
* '''pnames''' is a cell array containing the names of the parameters in pin
 +
* '''pin''' returns the input parameter values
 +
 +
 +
'''''EXAMPLE:'''''
 +
 +
 +
The following would be a suitable function to use with fit, where the fit is a simple polynomial one
 +
<pre> function y =  poly_func(x, pin)
 +
y = pin(1).*x.^2 + pin(2).*x + pin(3);</pre>
 +
  
 
===fitdata===
 
===fitdata===
 +
 +
fitdata is an optionally returned structure with the following fields
 +
 +
* '''fitdata.p:''' Parameter values
 +
* '''fitdata.sig:''' Estimated errors (=0 for fixed parameters)
 +
* '''fitdata.corr:''' Correlation matrix for free parameters
 +
* '''fitdata.chisq:''' Reduced Chi^2 of fit (i.e. divided by (no. of data points) - (no. free parameters))
 +
* '''fitdata.pnames:''' Parameter names (if func is mfit function; else named 'p1','p2',...)
 +
  
 
===Optional Inputs===
 
===Optional Inputs===
 +
 
These functions may also be called with the syntaxes
 
These functions may also be called with the syntaxes
  
Line 196: Line 227:
 
* '''pfree:''' A binary array the same size indicating which parameters are allowed to vary. For instance, if pin is [1, 2, 3, 4, 5] then pfree may be [0, 0, 1, 1, 1] meaning that the first two parameters are fixed at 1 and 2 respectively while the others will be varied to find the best fit.  
 
* '''pfree:''' A binary array the same size indicating which parameters are allowed to vary. For instance, if pin is [1, 2, 3, 4, 5] then pfree may be [0, 0, 1, 1, 1] meaning that the first two parameters are fixed at 1 and 2 respectively while the others will be varied to find the best fit.  
  
''' Properties that can be set:'''
 
  
 +
'''Properties that can be set:'''
 +
 +
* ''''list'''' - Controls the command window output, may be one of 3 values
 +
** 0 - No display in command window (''Default'')
 +
** 1 - Summary of each iteration
 +
** 2 - Parameter values as well as summary at each iteration
 +
* ''''fit'''' - Array of fit control parameters in the form of [fcp(1) fcp(2) fcp(3)]
 +
** fcp(1) is the step length when calculating partial derivatives for the fit
 +
** fcp(2) is the maximum number of iterations to perform
 +
** fcp(3) is a number such that once chi-squared is less than this, the fitting stops
 +
* ''''keep'''' - defines ranges of x and y to retain when fitting
 +
** syntax for the value: [xlo, xhi, ylo, yhi, xlo2, xhi2, ylo2, yhi2, ...] (in the 1 dimensional case only xlo and xhi are used)
 +
* ''''remove'''' - defines ranges of x and y to reject when fitting
 +
** syntax for the value: [xlo, xhi, ylo, yhi; xlo2, xhi2, ylo2, yhi2; ...] (in the 1 dimensional case only xlo and xhi are used)
 +
* ''''mask'''' - a binary array the same size as the number of points that defines which points should be kept for fitting
 +
** maskval = [0, 1, 0, 0, 0, 1, 1, 1, ...] if maskval(i) = 1 then the point at w.x(i) will be kept.
 +
* ''''select'''' - the values returned in the output are only those used for the fitting.
 +
 +
 +
'''''EXAMPLES:'''''
 +
 +
<pre>>> ht=100; x0=1; y0=3; sigx=2; sigy=1.5;
 +
>> [wwfit, fdata] = fit(ww, @gauss2d, [ht,x0,y0,sigx,0,sigy], [1,1,1,0,0,0])</pre>
  
 +
allows only the height ht and widths x0, y0 to vary when trying to fit a gaussian to ww.
  
 +
<pre>>> ht=100; x0=1; y0=3; sigx=2; sigy=1.5;
 +
>> [wfit, fdata] = fit(w, @gauss2d, [ht,x0,y0,sigx,0,sigy], 'remove', [0.2,0.5,2,0.7; 1,2,1.4,3])</pre>
  
 +
allows all the parameters to vary, but does not consider points in a rectangle between (0.2, 2) and (0.5, 0.7), or points in a rectangle between (1, 1.4) and (2, 3) in the fitting.
  
 
==Function Evaluation==
 
==Function Evaluation==
 +
 +
Functions may be evaluated at the x and y values of a dataset. The resultant dataset will contain the evaluated signal values, the input signal values will have no bearing on the output.
 +
 +
<pre>>> wwout = func_eval(ww, func, arg1, arg2, ...)
 +
>> wout = func_eval(w, func, arg1, arg2, ...)</pre>
 +
 +
* Input is an [[IXTdataset_1d]] or an [[IXTdataset_2d]] object
 +
* Output is the same object type as input
 +
* wout.signal will be the calculated dependent variable values from the function func
 +
* arg1, arg2, etc. are the arguments used by the function func and will usually consist of a single numerical array
 +
 +
 +
 +
The function func must be called in one of the following two ways (depending on whether an [[IXTdataset_1d]] or [[IXTdataset_2d]] is being evaluated)
 +
 +
<pre>>> signal = func(x, y, arg1, arg2, ...)
 +
>> signal = func(x, arg1, arg2, ...)</pre>

Latest revision as of 15:15, 20 March 2008

Many powerful high level functions are provided. These manipulate datasets in a complicated manor.

Derrivative Functions

First Derivative

These functions take the derivatives of datasets.

>> wwout = deriv1x(ww)
>> wwout = deriv1y(ww)
  • Input is an IXTdataset_2d object
  • Output is an IXTdataset_2d object
  • Calculates first derivative of the dataset in the x and y directions respectively
>> wout = deriv1(w)
  • Input is an IXTdataset_1d object
  • Output is an IXTdataset_1d object
  • Calculates the first derivative of the dataset in the x direction


Second Derivative

These functions take the second derivatives of datasets.

>> wwout = deriv2x(ww)
>> wwout = deriv2y(ww)
  • Input is an IXTdataset_2d object
  • Output is an IXTdataset_2d object
  • Calculates the second derivative of the dataset in the x and y directions respectively
>> wout = deriv2(w)
  • Input is an IXTdataset_1d object
  • Output is an IXTdataset_1d object
  • Calculates the second derivative of the dataset in the x direction.


Integral Functions

These functions integrate a dataset between given limits using the trapezoid method.

>> wwout = integrate_x(ww, xmin, xmax)
>> wout = integrate_y(ww, ymin, ymax)
  • Input is an IXTdataset_2d object
  • Output is an IXTdataset_1d object
  • Integral is evaluated between xmin and xmax in the x direction or ymin and ymax in the y direction
>> dout = integrate_xy(ww, xmin, xmax, ymin, ymax)
  • Input is an IXTdataset_2d object
  • Output is an IXTdatum object
  • Integral is evaluated between xmin and xmax in the x direction and ymin and ymax in the y direction
>> dout = integrate(w, xmin, xmax)
  • Input is an IXTdataset_2d object
  • Output is an IXTdatum object
  • Integral is evaluated between xmin and xmax


Smooth Functions

Smooth functions use an algorithm to smooth the data in a dataset to eliminate fluctuations.

>> wwout = smooth(ww, options)
>> wout = smooth(w, options)
  • Input may be IXTdataset_1d or IXTdataset_2d object
  • Output is the same object type as the input
  • Options allow the user to set the method of smoothing and parameters


Optional Inputs

The following syntaxes may be used

>> wout = smooth (w, filter)
>> wout = smooth (w, filter, size)
>> wout = smooth (w, filter, size, pars)
>> wout = smooth (w, filter, size, pars,'nonorm')
  • filter: May be 'box', 'gaussian', or the handle to a function that defines how the smoothing should occur. Default: 'box'
  • size: A vector indicating the size of the convolution kernel. Default: [3,3]
  • pars: are arguments required by filter if a function is given
  • 'nonorm:' turns off the normalisation in the kernel shell if filter is a user defined function

See the Matlab online help for more information.


Interpolate Functions

These functions always return point datasets regardless of point or histogram input. It can be viewed as the point data equivilent to the rebin functions. A new set of x or y datapoints is given and the data interpolated accross them.

>> wwout = interp_x(ww, xarray, optional)
>> wwout = interp_y(ww, yarray, optional)
>> wwout = interp(ww, xarray, yarray, optional)
  • Input is an IXTdataset_2d object
  • Output is an IXTdataset_2d object
  • wwout.x will be xarray, wwout.y will be yarray
  • Signal data will be interpolated accross the new x and y data points
  • Default method uses linear interpretation
  • Optional inputs allow control of method
>> wout = interp(w, xarray, optional)
  • Input is an IXTdataset_1d object
  • Output is an IXTdataset_1d object
  • wout.x will be xarray
  • Signal data will be interpolated accross the new x points
  • Default method uses linear interpretation
  • Optional inputs allow control of method


Optional Inputs

The following syntaxes may also be used:

>> wwout = interp(ww, xarray, yarray, Method)
>> wwout = interp(ww, xarray, yarray, Method, Extrapval)
  • Method: may be 'nearest', 'linear', 'spline', 'cubic'
    • 'nearest' - uses nearest neighbour interpolation
    • 'linear' - uses linear interpolation
    • 'spline' - uses cubic spline interpolation
    • 'cubic' - uses cubic interpolation
  • Extrapval: value given to out of range points (usually NaN or 0)


Unspike Functions

Used to remove spurious spikes from datasets

>> wwout = unspike(ww, optional)
>> wout = unspike(w, optional)
  • Input is an IXTdataset_1d or IXTdataset_2d object
  • Output is object of the same type as input
  • Removes any spikes in the dataset
  • Spikes are replaced with an interpolated value
  • Optional inputs may be used to define what constitutes a spike (see Optional Inputs for definition of a spike)


Optional Inputs

The following syntaxes may also be used:

>> wout = unspike(w, smin, smax, fac, sfac)
  • smin: If signal is < smin then the point is considered a spike (Default: NaN, i.e. ignored)
  • smax: If signal is > smax then the point is considered a spike (Default: NaN, i.e. ignored)
  • fac: If a signal point is within a factor FAC of both of its neighbours then is NOT a spike (Default: 2)
  • sfac: If the difference of a point w.r.t. both of its neighbours is less than SFAC standard deviations then the point is NOT a spike (Default: 5)


Fitting Functions

These functions fit data to a function.

>> [wwout fitdata]= fit(ww, func, pin, optional)
>> [wout fitdata] = fit(w, func, pin, optional)
  • Input may be an IXTdataset_1d object or IXTdataset_2d object
  • Output is an object of the same type as input and fitdata
  • wout will be a dataset with the same x and y values as w, but with the signal evaluated by the function, func, with parameters determined by the closest fit to the original dataset. i.e. a curve of best fit to the function func.
  • fitdata (explained below) contains information about the fit
  • Other Inputs:
    • func: Function to fit w to
    • pin: Starting parameters (a guess of what the best fit parameters will be) of the form [p1, p2, p3, ...]


Function Format

The function used in the fitting must have a format compatable with the fitting algorithm, this means that to call the function the following syntax is used


For one dimensional fitting

>> y = func(x, pin, optional)   OR
>> [y, name, pnames, pin] = func(x, pin, optional) 


For two dimensional fitting

>> z = func(x, y, pin, optional)   OR
>> [z, name, pnames, pin] = func(x, y, pin, optional) 
  • pin is a numeric array defining parameters of the function

The optional outputs are for advanced use of fit and mfit

  • name is the name of the function
  • pnames is a cell array containing the names of the parameters in pin
  • pin returns the input parameter values


EXAMPLE:


The following would be a suitable function to use with fit, where the fit is a simple polynomial one

 function y =  poly_func(x, pin)
y = pin(1).*x.^2 + pin(2).*x + pin(3);


fitdata

fitdata is an optionally returned structure with the following fields

  • fitdata.p: Parameter values
  • fitdata.sig: Estimated errors (=0 for fixed parameters)
  • fitdata.corr: Correlation matrix for free parameters
  • fitdata.chisq: Reduced Chi^2 of fit (i.e. divided by (no. of data points) - (no. free parameters))
  • fitdata.pnames: Parameter names (if func is mfit function; else named 'p1','p2',...)


Optional Inputs

These functions may also be called with the syntaxes

>> [yout, fitdata] = fit(win, func, pin, pfree)
>> [yout, fitdata] = fit(win, func, pin, pfree, property1, value1, property2, value2, ....)

Where property1 etc. represent some properties that can be altered (see below) and value1 etc. represent the values that these properties are to change to.

  • pfree: A binary array the same size indicating which parameters are allowed to vary. For instance, if pin is [1, 2, 3, 4, 5] then pfree may be [0, 0, 1, 1, 1] meaning that the first two parameters are fixed at 1 and 2 respectively while the others will be varied to find the best fit.


Properties that can be set:

  • 'list' - Controls the command window output, may be one of 3 values
    • 0 - No display in command window (Default)
    • 1 - Summary of each iteration
    • 2 - Parameter values as well as summary at each iteration
  • 'fit' - Array of fit control parameters in the form of [fcp(1) fcp(2) fcp(3)]
    • fcp(1) is the step length when calculating partial derivatives for the fit
    • fcp(2) is the maximum number of iterations to perform
    • fcp(3) is a number such that once chi-squared is less than this, the fitting stops
  • 'keep' - defines ranges of x and y to retain when fitting
    • syntax for the value: [xlo, xhi, ylo, yhi, xlo2, xhi2, ylo2, yhi2, ...] (in the 1 dimensional case only xlo and xhi are used)
  • 'remove' - defines ranges of x and y to reject when fitting
    • syntax for the value: [xlo, xhi, ylo, yhi; xlo2, xhi2, ylo2, yhi2; ...] (in the 1 dimensional case only xlo and xhi are used)
  • 'mask' - a binary array the same size as the number of points that defines which points should be kept for fitting
    • maskval = [0, 1, 0, 0, 0, 1, 1, 1, ...] if maskval(i) = 1 then the point at w.x(i) will be kept.
  • 'select' - the values returned in the output are only those used for the fitting.


EXAMPLES:

>> ht=100; x0=1; y0=3; sigx=2; sigy=1.5;
>> [wwfit, fdata] = fit(ww, @gauss2d, [ht,x0,y0,sigx,0,sigy], [1,1,1,0,0,0])

allows only the height ht and widths x0, y0 to vary when trying to fit a gaussian to ww.

>> ht=100; x0=1; y0=3; sigx=2; sigy=1.5;
>> [wfit, fdata] = fit(w, @gauss2d, [ht,x0,y0,sigx,0,sigy], 'remove', [0.2,0.5,2,0.7; 1,2,1.4,3])

allows all the parameters to vary, but does not consider points in a rectangle between (0.2, 2) and (0.5, 0.7), or points in a rectangle between (1, 1.4) and (2, 3) in the fitting.

Function Evaluation

Functions may be evaluated at the x and y values of a dataset. The resultant dataset will contain the evaluated signal values, the input signal values will have no bearing on the output.

>> wwout = func_eval(ww, func, arg1, arg2, ...)
>> wout = func_eval(w, func, arg1, arg2, ...)
  • Input is an IXTdataset_1d or an IXTdataset_2d object
  • Output is the same object type as input
  • wout.signal will be the calculated dependent variable values from the function func
  • arg1, arg2, etc. are the arguments used by the function func and will usually consist of a single numerical array


The function func must be called in one of the following two ways (depending on whether an IXTdataset_1d or IXTdataset_2d is being evaluated)

>> signal = func(x, y, arg1, arg2, ...)
>> signal = func(x, arg1, arg2, ...)