SIMBIO/Releasenotes/Inverse Toolbox/Implementation Classes: Continuous Parameter Space

From SimBio - A generic environment for bio-numerical simulations

Jump to: navigation, search

Contents

Analyzer for Dipole Fit:

Class Name: anAnalyzerInverseDipoleFit_c

Inverse method derived from anAbstractAnalyzerInverseContinuous_c to carry out non-linear dipole fit. The type of dipole fit (fixed, rotating moving) is determined by the goal function of the optimizer. The class has references to two other classes: (1) anAbstractInitialGuess_c determines the start values of the target parameters (e.g. the dipole positions), and (2) anAbstractOptimizerContinuous_c yields the method to optimize these parameters. The latter has in turn references to a goal function, the forward solution, etc.

How to create a dipole fit analyzer?

anAnalyzerInverseDipoleFit_c(

int& NumDip,
anAbstractInitialGuess_c& inInitialGuess,
anAbstractOptimizerContinuous_c& inOptimizer);

Important public interface functions

  • perform dipole fit.

void run();

  • extract resulting parameter matrix

bool getResult(utMatrix_t<double>& outParameters);

  • set settings

void setSettings(const utVector_t<double>& inSettings);

The parameter vector contains parameters which can be transferred to the referenced anAbstractOptimizerContinuous_c. Thus it contains a concatenation of parameters to set the stopping criteria and other parameters of the optimizer. These vectors are specific for the particular optimization procedure and therefore its members have a different meaning for different optimizers.

Initial Guess

Standard

Class Name: anInitialGuessStandard_c

Provides initial guess parameters for an optimization procedure. For dipole fit methods needing position parameters it provides dipole positions in the following way: For even numbers of dipoles, initial positions are placed symmetric in both hemispheres. For odd numbers an additional dipole is set on the z-axes. Dipole fit methods needing a additional start values for the direction are additionally provided with two start values describing the direction in polar coordinates.

Important public interface functions

  • generate an initial guess

utMatrix_t<double> getInitialGuessParameters(

int InitialGuessParamaters_height ,
intInitialGuessParamaters_length);

If InitialGuessParamaters_height is 3, the matrix which is returned contains three rows with x, y, z position parameters. If InitialGuessParamaters_height is 5, the matrix which is returned contains three rows with x, y, z position parameters and two additional rows containing direction parameters (polar coordinates). For other values of InitialGuessParamaters_height a matrix is returned with all parameters equal to 0.001.

  • set initial guess from outside

bool setInitialGuessPositions(utMatrix_t<double>& inPositions);

Requires a matrix with 3 rows to set initial guess positions.


Best of Grid

Class Name: anInitialGuessBestofGrid_c

For a set of regular placed dipoles a goal function is computed. Dipole parameters of the dipole with the highest goal function value are then used as initial guess parameters. This procedure leads only to results if the number of dipoles is one. If the number of dipoles is greater then one, the same initial guess parameters are created as by using the anInitialGuessStandard_c.

How to create an initial guess: best of grid?

anInitialGuessBestofGrid_c( anAbstractGoalFunctionEEGMEG_c& inGoalFunction);

Parameters:

inGoalFunction

Goal Function for EEG/MEG returns value, which has to be

optimized by changing dipole positions. Penalties included in the goal function ensure that restrictions of the parameter space are fulfilled.

Important public interface functions

  • generate an initial guess

utMatrix_t<double> getInitialGuessParameters(

int InitialGuessParamaters_height ,
int InitialGuessParamaters_length );

If InitialGuessParamaters_height is 3, the matrix which is returned contains three rows with x,y,z position parameters. Position parameters are determined as described above. If InitialGuessParamaters_height is 5, the matrix which is returned contains three rows with x,y,z position parameters and two additional rows containing direction parameters (polar coordinates). For other values of InitialGuessParamaters_height a matrix is returned with all parameters equal to 0.001.

  • set initial guess from outside

bool setInitialGuessPositions(utMatrix_t<double>& inPositions);

Requires a matrix with 3 rows to set initial guess positions.


Optimizer

Marquardt

Class Name: anOptimizerMarquardt_c

For the optimization of nonlinear parameters the Levenberg Marquardt optimizer is realized [2],[3]. Stopping criteria of the algorithm, which can be set are: minimum descent of the goal function, minimum shift of the position between to iterations, minimum rotation between to iterations and maximum number of iterations. The absolute value of the goal function is not used as a criterion to stop the optimization procedure. Parameters, which influence the behavior of the optimization algorithm are lambda, ny and a factor to increase lambda, after one unsuccessful iteration step. Both stopping criteria and parameters influencing the optimization process can be set, but values, which are proven to be satisfactory to determine parameters of dipoles, are used by default.

How to create a marquardt optimizer?

anOptimizerMarquardt_c(anAbstractGoalFunction_c& inGoalFunction);

Parameters:

inGoalFunction

Parameters have to be optimized w.r.t to a goal function. A goal function may also include penalties to limit the search space for parameters.

Important public interface functions

  • perform parameter optimization

run( utMatrix_t<double>& inParameter, utMatrix_t<double>& outParameter);

Parameters:

inParameter

Start parameters for optimization procedure

outParameter

Resulting optimized parameters
  • set optimization procedure settings

bool setSettings(utVector_t<double> inSettings);

The settings vector contains following items: initial lambda, factor to increase lambda, ny

  • set default procedure settings (approved for source localization)

bool setDefaultSettings();

  • set stop criteria of optimization procedure

bool setStopCriteria(utVector_t<double> inStopCriteria);

The stop criteria vector contains following items: Goodness of fit (%) (not used as a stopping criterion !!), minimal descent of the goal function value between to optimization steps, maximum number of iterations, minimum position shift between two iterations, minimum rotation of the direction between two iterations

  • set default stopping criteria (approved for source localization)

bool setDefaultStopCriteria();

  • define only a subset of the parameters to be used for optimization. The other parameters, are kept constant, but will be used for the determination of the goal function.

void setUsedParametersDefinition(utMatrix_t<bool> UsedParamters)

  • compute additional parameters which can be determined by linear estimation

void linearEstimation(

utMatrix_t<double>& OptimizedParameters,
utMatrix_t<double>& linearParameters);

Parameters: OptimizedParameters

Parameters determined by Marquardt optimizer

linearParameters

Resulting parameters of linear estimation procedure. The linear estimation procedure is defined inside the respective goal function.


Simplex

Class Name: anOptimizerSimplex_c

For the optimization of nonlinear parameters the Simplex algorithm is realized [3] as an alternative to the Levenberg Marquardt optimizer. Stopping criteria of the algorithm, which can be set are: minimum descent of the goal function, minimum shift of the position between to iterations, minimum rotation between to iterations and maximum number of iterations. The absolute value of the goal function is not used as a criterion to stop the optimization procedure. Parameters, which influence the behavior of the optimization algorithm are a factor to reflect the simplex from the high point and two extrapolation factors. Both stopping criteria and parameters influencing the optimization process can be set, but values, which are proven to be satisfactory to determine parameters of dipoles, are used by default.

How to create a simplex optimizer?

anOptimizerSimplex_c(anAbstractGoalFunction_c& inGoalFunction);

Parameters:

inGoalFunction

Parameters have to be optimized w.r.t to a goal function. A goal function may also include penalties to limit the search space for parameters.

Important public interface functions

  • perform parameter optimization

run( utMatrix_t<double>& inParameter, utMatrix_t<double>& outParameter);

Parameters:

inParameter

Start parameters for optimization procedure

outParameter

Resulting optimized parameters
  • set optimization procedure settings

bool setSettings(utVector_t<double> inSettings);

The settings vector contains following items: factor to reflect the simplex from the high point two extrapolation factors and a value for the displacement of initial simplex nodes

  • set default procedure settings (approved for source localization)

bool setDefaultSettings();

  • set stop criteria of optimization procedure

bool setStopCriteria(utVector_t<double> inStopCriteria);

The stop criteria vector contains following items: Goodness of fit (%) (not used as a stopping criterion !!), minimal descent of the goal function value between to optimization steps, maximum number of iterations, minimum position shift between two iterations, minimum rotation of the direction between two iterations

  • set default stopping criteria (approved for source localization)

bool setDefaultStopCriteria();

  • compute additional parameters which can be determined by linear estimation

void linearEstimation(

utMatrix_t<double>& OptimizedParameters,
utMatrix_t<double>& linearParameters);

Parameters:

OptimizedParameters

Parameters determined by Marquardt optimizer

linearParameters

Resulting parameters of linear estimation procedure. The linear estimation procedure is defined inside the respective goal function.


Goalfunctions

Rotating Dipole Fit

Class Name: anGoalFunctionDipoleRotating_c

Serves as goal function for rotating dipole fit procedures. For all time steps one position is determined for each dipole by the non-linear optimization procedure. The class contains further a method to determine directions and magnitudes for each time step for each dipole by linear estimation.

The goal function of the rotating dipole fit can also be used for a moving dipole fit by using the anAnalyzerInverseDipoleFit_c with a rotating goal function feeding the method for each time step separately with measured data.

How to create a goal function for a rotating dipole fit ?

anGoalFunctionDipoleRotating_c(

const utMatrix_t<double>& inReferenceData,
anAbstractSimulatorEEGMEG_c& inSimulator,
anAbstractCriteria_c& inCriteria,
anAbstractSearchVolume_c& inSearchVolume,
anAnalyzerInverseLinear_c& nLinearEstimator);

For a description of parameters have a look at an anAbstractGoalFunctionEEGMEG_c.

Important public interface functions

  • perform computation of goal function value

double computeGoalFunction(utMatrix_t<double>& inParameter);

Paramters:

inParameter

Parameters, for which goal function value is computed.
  • get number of parameters, which have to be determined by non-linear optimization procedure for a dipole (returns 3)

GetNumberOfParametersPerDip()

  • compute projection matrix (specific for goal function type)

ProjectionMatrix(

const utMatrix_t<double>& inParameter,
utMatrix_t<double>& outProjectionMatrix);
  • compute dipole parameters which can be determined by linear estimation (direction and magnitude)

linearEstimation(

utMatrix_t<double>& inParameter ,
utMatrix_t<double>& linearParameters);

Parameters:

inParameter

Parameters determined by non linear optimizer

linearParameters

Resulting parameters of linear estimation procedure.

Fixed Dipole Fit

Class Name: anGoalFunctionDipoleFixed_c

Serves as goal function for fixed dipole fit procedures. For all time steps one position and one direction is determined for each dipole by the non-linear optimization procedure. The class contains further a method to determine the magnitudes for each time step for each dipole by linear estimation.

How to create a goal function for a fixed dipole fit?

anGoalFunctionDipoleFixed_c( (

const utMatrix_t<double>& inReferenceData,
anAbstractSimulatorEEGMEG_c& inSimulator,
anAbstractCriteria_c& inCriteria,
anAbstractSearchVolume_c& inSearchVolume,
anAnalyzerInverseLinear_c& inLinearEstimator);

For a description of parameters have a look at an anAbstractGoalFunctionEEGMEG_c.

Important public interface functions

  • perform computation of goal function value

double computeGoalFunction(utMatrix_t<double>& inParameter);

Parameters:

inParameter

Parameters, for which goal function value is computed.
  • get number of parameters, which have to be determined by non-linear optimization procedure for a dipole (returns 5).

GetNumberOfParametersPerDip()

  • compute projection matrix (specific for goal function type)

ProjectionMatrix(

const utMatrix_t<double>& inParameter,
utMatrix_t<double>& outProjectionMatrix);
  • compute dipole parameters which can be determined by linear estimation (direction and magnitude).

linearEstimation(

utMatrix_t<double>& inParameter ,
utMatrix_t<double>& linearParameters);

Parameters:

inParameter

Parameters determined by non linear optimizer

linearParameters

Resulting parameters of linear estimation procedure.
  • Compute penalty to prevent radial sources for MEG.

double computePenalty_NotRadial(

const utMatrix_t<double>& inPos,
const utMatrix_t<double>& inDir);

Criteria

Minimum Square Error

Class Name: anCriteriumMinimumSquareError_c

Determines the Euclidean norm between two arrays as return value for the criterion:

</math> Value = \sum\limits_{i,j=0}^{n-1,m-1} (data1[i][j]-data2[i][j])^2 </math>

How to create a criterion: minimum square error?

anCriteriaMinimumSquareError_c();

Important public interface functions

  • compute criteria :

double computeCriteria(

utMatrix_t<double>& inData1,
const utMatrix_t<double>& inData2);

Parameters:

inData1

Values of first data set

inData2

Values of second data set

Search Volumes

Infinite

Class Name: anSearchVolumeInfinite_c

Parameters are always inside of the search volume.

How to create a infinite search volume?

anSearchVolumeInfinite_c();

Important public interface functions

  • check whether parameters are inside search volume (always returns true)

bool isInsideSearchVolume(const utVector_t<double>& inParameters);

  • get distance to surface (returns always -10E35)

double DistanceToSurface(const utVector_t<double>& inParameters);

Sphere

Class Name: anSearchVolumeSphere_c

For points inside a sphere, which is determined by its center and its radius, the isInsideSearchVolume() method returns true. The DistanceToSurface() method returns the distance between a point and the surface of the sphere. The distance is negative for points inside of the sphere.

How to create a spherical search volume?

anSearchVolumeSphere_c(utVector_t<double> inCenter, double inRadius);

Parameters:

inCenter

Center of spherical search volume (x,y,z)

inRadius

Radius of spherical search volume

Important public interface functions

  • check whether parameters are inside spherical search volume

bool isInsideSearchVolume(const utVector_t<double>& inParameters);

  • get distance to surface

double DistanceToSurface(const utVector_t<double>& inParameters);

  • set center of sphere

bool setCenter(utVector_t<double>& inCenter);

  • set radius of spheres

bool setRadius(double& inRadius);

  • set settings

bool setSettings(const utVector_t<double>& inSettings);

The settings vector contains the following items: radius, center x, center y, center z


Sphere with Boundaries

Class Name: anSearchVolumeWithBoundariesSpheres_c

A set of spheres around one point can be defined. It can be defined for each spacing between the spheres whether it belongs to the search volume or not. The isInsideSearchVolume() method returns true if a point lies between the surfaces of two spheres, for which the spacing is set as a valid search volume. The DistanceToSurface() method returns the smallest distance to the nearest surface of a bounding sphere.

How to create a search volume with several spherical boundaries?

anSearchVolumeWithBoundariesSpheres_c (

utVector_t<double> in_Center,
utVector_t<double> in_Radii,
utVector_t<int> inValidSearchVolumes);

Parameters:

inCenter

Center of spherical search volume (x,y,z)

inRadii

Radii of spheres

inValidSearchVolumes

every spacing between to spheres can be set as a valid or invalid search volume by setting values to one or zero.

Important public interface functions

  • check whether parameters are inside spherical search volume

bool isInsideSearchVolume(const utVector_t<double>& inParameters);

  • get distance to surface

double DistanceToSurface(const utVector_t<double>& inParameters);

  • set center of sphere

bool setCenter(utVector_t<double>& inCenter);

  • set radii of spheres

bool setRadii(utVector_t<double>& inRadii);

  • set spaces between spheres as valid or invalid search volumes

bool setValidSearchBoundaries(utVector_t<int>& ininsideValidSearchBoundaries);

Personal tools