High Level Functions

From LIBISIS
Jump to navigation Jump to search

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, ...)
Retrieved from "http://libisis.org/index.php?title=High_Level_Functions&oldid=2018"