RAP MUSIC (Recursively Applied and Projected Multiple Signal Classification) source localization algorithm. More...

#include <inv_rap_music.h>

Public Types
typedef QSharedPointer< InvRapMusic >	SPtr
typedef QSharedPointer< const InvRapMusic >	ConstSPtr
typedef Eigen::Matrix< double, Eigen::Dynamic, Eigen::Dynamic >	MatrixXT
typedef Eigen::Matrix< double, Eigen::Dynamic, 6 >	MatrixX6T
typedef Eigen::Matrix< double, 6, Eigen::Dynamic >	Matrix6XT
typedef Eigen::Matrix< double, 6, 6 >	Matrix6T
typedef Eigen::Matrix< double, Eigen::Dynamic, 1 >	VectorXT
typedef Eigen::Matrix< double, 6, 1 >	Vector6T

Public Member Functions
	InvRapMusic ()
	InvRapMusic (MNELIB::MNEForwardSolution &p_pFwd, bool p_bSparsed, int p_iN=2, double p_dThr=0.5)
virtual	~InvRapMusic ()
bool	init (MNELIB::MNEForwardSolution &p_pFwd, bool p_bSparsed=false, int p_iN=2, double p_dThr=0.5)
virtual InvSourceEstimate	calculateInverse (const FIFFLIB::FiffEvoked &p_fiffEvoked, bool pick_normal=false)
virtual InvSourceEstimate	calculateInverse (const Eigen::MatrixXd &data, float tmin, float tstep, bool pick_normal=false) const
virtual InvSourceEstimate	calculateInverse (const Eigen::MatrixXd &p_matMeasurement, QList< InvDipolePair< double > > &p_RapDipoles) const
virtual const char *	getName () const
virtual const MNELIB::MNESourceSpaces &	getSourceSpace () const
void	setStcAttr (int p_iSampStcWin, float p_fStcOverlap)

Protected Member Functions
int	calcPhi_s (const MatrixXT &p_matMeasurement, MatrixXT *&p_pMatPhi_s) const
void	calcOrthProj (const MatrixXT &p_matA_k_1, MatrixXT &p_matOrthProj) const
void	calcPairCombinations (const int p_iNumPoints, const int p_iNumCombinations, std::vector< Pair > &p_pairIdxCombinations) const

Static Protected Member Functions
static double	subcorr (MatrixX6T &p_matProj_G, const MatrixXT &p_pMatU_B)
static double	subcorr (MatrixX6T &p_matProj_G, const MatrixXT &p_matU_B, Vector6T &p_vec_phi_k_1)
static void	calcA_k_1 (const MatrixX6T &p_matG_k_1, const Vector6T &p_matPhi_k_1, const int p_iIdxk_1, MatrixXT &p_matA_k_1)
static void	getPointPair (const int p_iPoints, const int p_iCurIdx, int &p_iIdx1, int &p_iIdx2)
static void	getGainMatrixPair (const MatrixXT &p_matGainMarix, MatrixX6T &p_matGainMarix_Pair, int p_iIdx1, int p_iIdx2)
static void	insertSource (int p_iDipoleIdx1, int p_iDipoleIdx2, const Vector6T &p_vec_phi_k_1, double p_valCor, QList< InvDipolePair< double > > &p_RapDipoles)
static int	getRank (const MatrixXT &p_matSigma)
static int	useFullRank (const MatrixXT &p_Mat, const MatrixXT &p_matSigma_src, MatrixXT &p_matFull_Rank, int type=NOT_TRANSPOSED)
static MatrixXT	makeSquareMat (const MatrixXT &p_matF)

Protected Attributes
MNELIB::MNEForwardSolution	m_ForwardSolution
int	m_iN
double	m_dThreshold
int	m_iNumGridPoints
int	m_iNumChannels
int	m_iNumLeadFieldCombinations
std::vector< Pair >	m_ppPairIdxCombinations
int	m_iMaxNumThreads
bool	m_bIsInit
int	m_iSamplesStcWindow
float	m_fStcOverlap

Detailed Description

RAP MUSIC (Recursively Applied and Projected Multiple Signal Classification) source localization algorithm.

Implements the RAP MUSIC scanning algorithm which iteratively identifies correlated source pairs by projecting the signal subspace and re-scanning the lead field. Each iteration finds one dipole (or dipole pair), projects it out of the signal subspace, and repeats until the desired number of sources is found or the residual correlation drops below threshold.

Reference: Mosher & Leahy, IEEE Trans. Signal Process. 47(2), 332-340, 1999.

Definition at line 89 of file inv_rap_music.h.

Inheritance diagram for INVLIB::InvRapMusic:

Member Typedef Documentation

◆ ConstSPtr

typedef QSharedPointer<const InvRapMusic> INVLIB::InvRapMusic::ConstSPtr

Const shared pointer type for InvRapMusic.

Definition at line 93 of file inv_rap_music.h.

◆ Matrix6T

typedef Eigen::Matrix<double, 6, 6> INVLIB::InvRapMusic::Matrix6T

Defines Eigen::Matrix<T, 6, 6> as Matrix6T type.

Definition at line 106 of file inv_rap_music.h.

◆ Matrix6XT

typedef Eigen::Matrix<double, 6, Eigen::Dynamic> INVLIB::InvRapMusic::Matrix6XT

Defines Eigen::Matrix<T, 6, Eigen::Dynamic> as Matrix6XT type.

Definition at line 104 of file inv_rap_music.h.

◆ MatrixX6T

typedef Eigen::Matrix<double, Eigen::Dynamic, 6> INVLIB::InvRapMusic::MatrixX6T

Defines Eigen::Matrix<T, Eigen::Dynamic, 6> as MatrixX6T type.

Definition at line 102 of file inv_rap_music.h.

◆ MatrixXT

typedef Eigen::Matrix<double, Eigen::Dynamic, Eigen::Dynamic> INVLIB::InvRapMusic::MatrixXT

Defines Eigen::Matrix<T, Eigen::Dynamic, Eigen::Dynamic> as MatrixXT type.

Definition at line 100 of file inv_rap_music.h.

◆ SPtr

typedef QSharedPointer<InvRapMusic> INVLIB::InvRapMusic::SPtr

Shared pointer type for InvRapMusic.

Definition at line 92 of file inv_rap_music.h.

◆ Vector6T

typedef Eigen::Matrix<double, 6, 1> INVLIB::InvRapMusic::Vector6T

Defines Eigen::Matrix<T, 6, 1> as Vector6T type.

Definition at line 110 of file inv_rap_music.h.

◆ VectorXT

typedef Eigen::Matrix<double, Eigen::Dynamic, 1> INVLIB::InvRapMusic::VectorXT

Defines Eigen::Matrix<T, Eigen::Dynamic, 1> as VectorXT type.

Definition at line 108 of file inv_rap_music.h.

Constructor & Destructor Documentation

◆ InvRapMusic() [1/2]

InvRapMusic::InvRapMusic ( )

Default constructor creates an empty InvRapMusic algorithm which still needs to be initialized.

Definition at line 48 of file inv_rap_music.cpp.

◆ InvRapMusic() [2/2]

InvRapMusic::InvRapMusic	(	MNELIB::MNEForwardSolution &	p_pFwd,
		bool	p_bSparsed,
		int	p_iN = 2,
		double	p_dThr = 0.5 )

Constructor which initializes the InvRapMusic algorithm with the given model.

Parameters

[in]	p_Fwd	The model which contains the gain matrix and its corresponding grid matrix.
[in]	p_bSparsed	True when sparse matrices should be used.
[in]	p_iN	The number (default 2) of uncorrelated sources, which should be found. Starting with. the strongest.
[in]	p_dThr	The correlation threshold (default 0.5) at which the search for sources stops.

Definition at line 63 of file inv_rap_music.cpp.

◆ ~InvRapMusic()

InvRapMusic::~InvRapMusic ( )

virtual

Definition at line 80 of file inv_rap_music.cpp.

Member Function Documentation

◆ calcA_k_1()

void InvRapMusic::calcA_k_1	(	const MatrixX6T &	p_matG_k_1,
		const Vector6T &	p_matPhi_k_1,
		const int	p_iIdxk_1,
		MatrixXT &	p_matA_k_1 )

staticprotected

Calculates the accumulated manifold vectors A_{k1}

Parameters

[in]	p_matG_k_1	The Lead Field combination for the currently best correlated pair.
[in]	p_matPhi_k_1	Is equal to u_k_1 in the paper and it is the direction of the currently best. correlated pair.
[in]	p_iIdxk_1	The current position in the manifold vector array A_k_1.
[out]	p_matA_k_1	The array of the manifold vectors.

Definition at line 718 of file inv_rap_music.cpp.

◆ calcOrthProj()

void InvRapMusic::calcOrthProj	(	const MatrixXT &	p_matA_k_1,
		MatrixXT &	p_matOrthProj ) const

protected

Calculates the orthogonal projector Phi_A_k_1 like in the paper Mosher 1999 (13)

Parameters

[in]	p_matA_k_1	The array of the manifold vectors.
[out]	p_matOrthProj	The orthogonal projector.

Definition at line 733 of file inv_rap_music.cpp.

◆ calcPairCombinations()

void InvRapMusic::calcPairCombinations	(	const int	p_iNumPoints,
		const int	p_iNumCombinations,
		std::vector< Pair > &	p_pairIdxCombinations ) const

protected

Pre-Calculates the gain matrix index combinations to search for a two dipole independent topography (IT = source).

Parameters

[in]	p_iNumPoints	The number of Lead Field points -> for dimension check.
[in]	p_iNumCombinations	The number of pair index combinations.
[out]	p_ppPairIdxCombinations	The destination which contains pointer to pointer of index. combinations of Lead Field indices -> Number of pointers = Combination (number of grid points over 2 = Num + 1 C 2)

Definition at line 771 of file inv_rap_music.cpp.

◆ calcPhi_s()

int InvRapMusic::calcPhi_s	(	const MatrixXT &	p_matMeasurement,
		MatrixXT *&	p_pMatPhi_s ) const

protected

Computes the signal subspace Phi_s out of the measurement F.

Parameters

[in]	p_pMatMeasurement	The current measured data to process (for best performance it should have. the dimension channels x samples with samples = number of channels)
[out]	p_pMatPhi_s	The calculated signal subspace.

Returns: The rank of the measurement F (named r lt. Mosher 1998, 1999).

Definition at line 562 of file inv_rap_music.cpp.

◆ calculateInverse() [1/3]

virtual InvSourceEstimate INVLIB::InvRapMusic::calculateInverse	(	const Eigen::MatrixXd &	data,
		float	tmin,
		float	tstep,
		bool	pick_normal = false ) const

virtual

◆ calculateInverse() [2/3]

virtual InvSourceEstimate INVLIB::InvRapMusic::calculateInverse	(	const Eigen::MatrixXd &	p_matMeasurement,
		QList< InvDipolePair< double > > &	p_RapDipoles ) const

virtual

Reimplemented in INVLIB::InvPwlRapMusic.

◆ calculateInverse() [3/3]

InvSourceEstimate InvRapMusic::calculateInverse	(	const FIFFLIB::FiffEvoked &	p_fiffEvoked,
		bool	pick_normal = false )

virtual

Reimplemented in INVLIB::InvPwlRapMusic.

Definition at line 183 of file inv_rap_music.cpp.

◆ getGainMatrixPair()

void InvRapMusic::getGainMatrixPair	(	const MatrixXT &	p_matGainMarix,
		MatrixX6T &	p_matGainMarix_Pair,
		int	p_iIdx1,
		int	p_iIdx2 )

staticprotected

Returns a gain matrix pair for the given indices

Parameters

[in]	p_matGainMarix	The Lead Field matrix.
[out]	p_matGainMarix_Pair	Lead Field combination (dimension: m x 6).
[in]	p_iIdx1	first Lead Field index point.
[in]	p_iIdx2	second Lead Field index point.

Definition at line 813 of file inv_rap_music.cpp.

◆ getName()

const char * InvRapMusic::getName ( ) const

virtual

Reimplemented in INVLIB::InvPwlRapMusic.

Definition at line 169 of file inv_rap_music.cpp.

◆ getPointPair()

void InvRapMusic::getPointPair	(	const int	p_iPoints,
		const int	p_iCurIdx,
		int &	p_iIdx1,
		int &	p_iIdx2 )

staticprotected

Calculates the combination indices Idx1 and Idx2 of n points.
[ (0,0) (0,1) (0,2) ... (0,n-1) (0,n)
(1,1) (1,2) ... (1,n-1) (1,n)
(2,2) ... (2,n-1) (2,n)

(n-1,n-1) (n-1,n)
(n,n)]

Parameters

[in]	p_iPoints	The number of points n which are combined with each other.
[in]	p_iCurIdx	The current combination index (between 0 and nchoosek(n+1,2)).
[out]	p_iIdx1	The resulting index 1.
[out]	p_iIdx2	The resulting index 2.

Definition at line 801 of file inv_rap_music.cpp.

◆ getRank()

int INVLIB::InvRapMusic::getRank ( const MatrixXT & p_matSigma )

inlinestaticprotected

Returns the rank r of a singular value matrix based on non-zero singular values (singular value > epsilon = 10^-5)

Parameters

[in] p_matSigma diagonal matrix which contains the Singular values (Dimension n x n).

Returns: The rank r.

Definition at line 355 of file inv_rap_music.h.

◆ getSourceSpace()

const MNESourceSpaces & InvRapMusic::getSourceSpace ( ) const

virtual

Definition at line 176 of file inv_rap_music.cpp.

◆ init()

bool InvRapMusic::init	(	MNELIB::MNEForwardSolution &	p_pFwd,
		bool	p_bSparsed = false,
		int	p_iN = 2,
		double	p_dThr = 0.5 )

Initializes the RAP MUSIC algorithm with the given model.

Parameters

[in]	p_Fwd	The model which contains the gain matrix and its corresponding Grid matrix.
[in]	p_bSparsed	True when sparse matrices should be used.
[in]	p_iN	The number (default 2) of uncorrelated sources, which should be found. Starting with. the strongest.
[in]	p_dThr	The correlation threshold (default 0.5) at which the search for sources stops.

Returns: true if successful initialized, false otherwise.

Definition at line 86 of file inv_rap_music.cpp.

◆ insertSource()

void InvRapMusic::insertSource	(	int	p_iDipoleIdx1,
		int	p_iDipoleIdx2,
		const Vector6T &	p_vec_phi_k_1,
		double	p_valCor,
		QList< InvDipolePair< double > > &	p_RapDipoles )

staticprotected

Adds a new correlated dipole pair to th RapDipoles. This function is called by the RAP MUSIC Algorithm.

Parameters

[in]	p_iDipoleIdx1	Index (Lead Field grid index) of the first dipole.
[in]	p_iDipoleIdx2	Index (Lead Field grid index) of the second dipole.
[in]	p_vec_phi_k_1	Array of the dipole directories (phi_x1, phi_y1, phi_z1, phi_x2, phi_y2, phi_z2).
[in]	p_valCor	Correlation value of the dipole pair.
[out]	p_RapDipoles	the list of dipole pairs.

Definition at line 824 of file inv_rap_music.cpp.

◆ makeSquareMat()

InvRapMusic::MatrixXT INVLIB::InvRapMusic::makeSquareMat ( const MatrixXT & p_matF )

inlinestaticprotected

Performs F * F^Transposed, is used when n > m

Parameters

[in] p_matF The matrix which should be transformed.

Returns: F * F^Transposed (we call it FFT ;)).

Definition at line 388 of file inv_rap_music.h.

◆ setStcAttr()

void InvRapMusic::setStcAttr	(	int	p_iSampStcWin,
		float	p_fStcOverlap )

Sets the source estimate attributes.

Parameters

[in]	p_iSampStcWin	Samples per source localization window (default - 1 = not set).
[in]	p_fStcOverlap	Percentage of localization window overlap.

Definition at line 857 of file inv_rap_music.cpp.

◆ subcorr() [1/2]

double InvRapMusic::subcorr	(	MatrixX6T &	p_matProj_G,
		const MatrixXT &	p_matU_B,
		Vector6T &	p_vec_phi_k_1 )

staticprotected

Computes the subspace correlation between the projected G_rho and the projected signal subspace Phi_s, as well as the resulting direction. For speed-up: we calculate the decomposition of the projected Phi_s before this function. So the argument for this function is U_B instead of Phi_s.

Parameters

[in]	p_matProj_G	The projected Lead Field combination. This is a m x 6 matrix composed of the. Lead Field combination of two Points for all m channels and 3 orthogonal components (x y z).
[in]	p_matU_B	The matrix U is the subspace projection of the orthogonal projected Phi_s.
[out]	p_vec_phi_k_1	Returns the orientation for a correlated dipole pair. (phi_x1, phi_y1, phi_z1, phi_x2, phi_y2, phi_z2)

Returns: The maximal correlation c_1 of the subspace correlation of the current projected Lead Field. combination and the projected measurement.

Definition at line 643 of file inv_rap_music.cpp.

◆ subcorr() [2/2]

double InvRapMusic::subcorr	(	MatrixX6T &	p_matProj_G,
		const MatrixXT &	p_pMatU_B )

staticprotected

Computes the subspace correlation between the projected G_rho and the projected signal subspace Phi_s. For speed-up: we calculate the decomposition of the projected Phi_s before this function. So the argument for this function is U_B instead of Phi_s.

Parameters

[in]	p_matProj_G	The projected Lead Field combination. This is a m x 6 matrix composed of the. Lead Field combination of two Points for all m channels and 3 orthogonal components (x y z).
[in]	p_matU_B	The matrix U is the subspace projection of the orthogonal projected Phi_s.

Returns: The maximal correlation c_1 of the subspace correlation of the current projected Lead Field. combination and the projected measurement.

Definition at line 590 of file inv_rap_music.cpp.

◆ useFullRank()

int INVLIB::InvRapMusic::useFullRank	(	const MatrixXT &	p_Mat,
		const MatrixXT &	p_matSigma_src,
		MatrixXT &	p_matFull_Rank,
		int	type = NOT_TRANSPOSED )

inlinestaticprotected

lt. Mosher 1998 -> Only Retain those Components of U_A and U_B that correspond to nonzero singular values for U_A and U_B the number of columns corresponds to their ranks

Parameters

[in]	p_Mat	The Matrix which should be reduced to its rank.
[in]	p_matSigma_src	The singular values of the matrix.
[out]	p_matFull_Rank	The corresponding full rank matrix.
[in]	type	Whether p_Mat is transposed, than rows and columns are changed.

Definition at line 371 of file inv_rap_music.h.

Member Data Documentation

◆ m_bIsInit

bool INVLIB::InvRapMusic::m_bIsInit

protected

Whether the algorithm is initialized.

Definition at line 310 of file inv_rap_music.h.

◆ m_dThreshold

double INVLIB::InvRapMusic::m_dThreshold

protected

Threshold which defines the minimal correlation. Is the correlation of the found dipole pair smaller as this threshold than the RAP MUSIC calculation is stopped.

Definition at line 298 of file inv_rap_music.h.

◆ m_ForwardSolution

MNELIB::MNEForwardSolution INVLIB::InvRapMusic::m_ForwardSolution

protected

The Forward operator which should be scanned through

Definition at line 295 of file inv_rap_music.h.

◆ m_fStcOverlap

float INVLIB::InvRapMusic::m_fStcOverlap

protected

Percentage of localization window overlap.

Definition at line 314 of file inv_rap_music.h.

◆ m_iMaxNumThreads

int INVLIB::InvRapMusic::m_iMaxNumThreads

protected

Number of available CPU threads.

Definition at line 308 of file inv_rap_music.h.

◆ m_iN

int INVLIB::InvRapMusic::m_iN

protected

Number of Sources to find

Definition at line 297 of file inv_rap_music.h.

◆ m_iNumChannels

int INVLIB::InvRapMusic::m_iNumChannels

protected

Number of channels.

Definition at line 303 of file inv_rap_music.h.

◆ m_iNumGridPoints

int INVLIB::InvRapMusic::m_iNumGridPoints

protected

Number of Grid points.

Definition at line 302 of file inv_rap_music.h.

◆ m_iNumLeadFieldCombinations

int INVLIB::InvRapMusic::m_iNumLeadFieldCombinations

protected

Number of Lead Filed combinations (grid points + 1 over 2)

Definition at line 304 of file inv_rap_music.h.

◆ m_iSamplesStcWindow

int INVLIB::InvRapMusic::m_iSamplesStcWindow

protected

Number of samples per localization window.

Definition at line 313 of file inv_rap_music.h.

◆ m_ppPairIdxCombinations

std::vector<Pair> INVLIB::InvRapMusic::m_ppPairIdxCombinations

protected

Index combination vector with grid pair indices.

Definition at line 306 of file inv_rap_music.h.

The documentation for this class was generated from the following files:

src/libraries/inv/rap_music/inv_rap_music.h
src/libraries/inv/rap_music/inv_rap_music.cpp

Public Types

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ ConstSPtr

◆ Matrix6T

◆ Matrix6XT

◆ MatrixX6T

◆ MatrixXT

◆ SPtr

◆ Vector6T

◆ VectorXT

Constructor & Destructor Documentation

◆ InvRapMusic() [1/2]

◆ InvRapMusic() [2/2]

◆ ~InvRapMusic()

Member Function Documentation

◆ calcA_k_1()

◆ calcOrthProj()

◆ calcPairCombinations()

◆ calcPhi_s()

◆ calculateInverse() [1/3]

◆ calculateInverse() [2/3]

◆ calculateInverse() [3/3]

◆ getGainMatrixPair()

◆ getName()

◆ getPointPair()

◆ getRank()

◆ getSourceSpace()

◆ init()

◆ insertSource()

◆ makeSquareMat()

◆ setStcAttr()

◆ subcorr() [1/2]

◆ subcorr() [2/2]

◆ useFullRank()

Member Data Documentation

◆ m_bIsInit

◆ m_dThreshold

◆ m_ForwardSolution

◆ m_fStcOverlap

◆ m_iMaxNumThreads

◆ m_iN

◆ m_iNumChannels

◆ m_iNumGridPoints

◆ m_iNumLeadFieldCombinations

◆ m_iSamplesStcWindow

◆ m_ppPairIdxCombinations