`sesameeg`.Sesame¶

class sesameeg.Sesame(source_space, lead_field, data, n_parts=100, s_min=None, s_max=None, n_matrix=None, np_matrix=None, noise_std=None, dip_mom_std=None, fixed_ori=False, radius=None, neigh_std=None, prior_locs=None, subsample=None, hyper_q=True, lam=0.25, max_n_dips=10, fourier=False, verbose=False, **kwargs)[source]¶

Sequential Semi-Analytic Monte-Carlo Estimator (SESAME).

Parameters:

source_spacendarray of float, shape (n_verts, 3): The coordinates of the points in the brain discretization.
lead_fieldndarray of float, shape (n_sens, n_comp*n_verts): The lead field matrix. (if fixed_ori=True it must be n_comp = 1; if fixed_ori=False it must be n_comp = 3)
datandarray of float, shape (n_sens, n_ist): The MEEG data; n_sens is the number of sensors and n_ist is the number of time-points or of frequencies.
n_partsint: The number of particles forming the empirical pdf.
s_minint: The first analyzed sample in the data array.
s_maxint: The last analyzed sample in the data array.
n_matrixndarray of int, shape (n_verts, n_max_neigh) | None: The set of neighbours of each point in the brain discretization. If None, it is automatically computed. n_max_neigh is the cardinality of the biggest set.
np_matrixndarray of float, shape (n_verts, n_max_neigh) | None: The neighbours’ probabilities. If None, it is automatically computed.
noise_stdfloat | None: The standard deviation of the noise distribution. If None, it is estimated from the data.
dip_mom_stdfloat | None: The standard deviation of the prior pdf on the dipole moment. If None, it is estimated from the forward model and the data.
fixed_oribool: If True, the forward solution is assumed to be computed in the surface-based source coordinate system.
radiusfloat | None: The maximum distance in cm between two neighbouring vertices of the brain discretization. If None, radius is set to 1 cm.
neigh_stdfloat | None: The standard deviation of the probability distribution of neighbours. If None, neighb_std is set to radius/2.
prior_locsndarray of float, shape (n_vert) | None: The prior probability of source location. If None, a uniform prior probability is used. Default is None.
subsampleint | None: The step used to subsample the data. If None no subsampling is applied.
hyper_qbool: If True, a hyperprior pdf on the dipole moment std will be used.
lamfloat: The parameter of the Poisson prior pdf on the number of dipoles.
max_n_dipsint: The maximum number of dipoles allowed in a particle.
fourierbool: If True, data are converted to the frequency domain.
verbosebool: If True, increase verbose level.
**kwargs: Additional keyword arguments are passed to the Sesame constructor.

Attributes:

dip_mom_stdfloat: The standard deviation of the prior on the dipole moment.
distance_matrixndarray of float, shape (n_verts x n_verts): The Euclidean distance between the points in the brain discretization.
est_dip_momsndarray of float, shape (n_ist x (n_comp*est_n_dips[-1])) | None: The sources’ moments estimated at the last iteration. (n_comp = 1, if fixed orientation, 3, if free orientation) If None, moments can be estimated by calling compute_dip_mom()
est_locslist of ndarray of int: The source space grid points indices in which a source is estimated.
est_n_dipslist of int: The estimated number of dipoles.
fourierbool: If True, data are in the frequency domain.
hyper_qbool: If True use hyperprior on dipole moment std.
lamfloat: The parameter of the Poisson prior pdf on the number of dipoles.
lead_fieldndarray of float, shape (n_sens x n_comp*n_verts): The leadfield matrix. (n_comp = 1 if fixed_ori=True; n_comp = 3 if fixed_ori=False)
max_n_dipsint: The maximum number of dipoles allowed in a particle.
model_sellist of ndarray of float: The model selection, i.e. the posterior distribution on the number of dipoles.
n_vertsint: The number of points forming the brain discretization.
n_partsint: The number of particles forming the empirical pdf.
neighndarray of int, shape (n_vert, n_max_neigh): The set of neighbours of each point in the brain discretization. n_max_neigh is the cardinality of the biggest set.
neigh_pndarray of float, shape (n_vert, n_max_neigh): The neighbours’ probabilities.
neigh_stdfloat: The standard deviation used to compute the neigh_p matrix.
noise_stdfloat: The standard deviation of the noise distribution.
pmaplist of ndarray of float, shape (est_n_dips, n_verts): Posterior probability map.
posteriorinstance of EmpPdf: The empirical pdf approximated by the particles at each iteration.
prior_locsndarray of float, shape (n_verts, ) | None: The prior probability of active source locations. If None, each source space grid point is assigned a uniform prior probability.
r_datandarray of float, shape (n_sens, n_ist): The real part of the data; n_sens is the number of sensors and n_ist is the number of time-points or of frequencies.
radiusfloat: The radius used to compute the neighbours.
_resample_itlist of int: The iterations during which a resampling step has been performed
s_minint: The first sample of the segment of data that are analyzed.
s_maxint: The last sample of the segment of data that are analyzed.
source_spacendarray of float, shape (n_verts, 3): The coordinates of the points in the brain discretization.
subsampleint | None: The step used to subsample the data.
data_timesndarray: Time vector in seconds. Only when instantiated by means of prepare_sesame() and when fourier=False
data_freqsndarray: Frequency vector in Hertz. Only when instantiated by means of prepare_sesame() and when fourier=True
forwardinstance of Forward: The forward solution. Only when instantiated by means of prepare_sesame()
subjectstr: Subject name in Freesurfer subjects dir. Only when instantiated by means of prepare_sesame().
subjects_dirstr | None: If not None, this directory will be used as the subjects directory instead of the value set using the SUBJECTS_DIR environment variable. Only when instantiated by means of prepare_sesame()
trans_matrixinstance of Transform: MRI<->Head coordinate transformation. Only when instantiated by means of prepare_sesame()

apply_sesame(estimate_all=False, estimate_dip_mom=True)[source]¶

Apply SESAME on MEEG data and compute point estimates.

Parameters:

estimate_allbool: If True compute the posterior probability map and estimate the number of dipoles and their locations at each iteration. If False compute the above quantities only at the last iteration.
estimate_dip_mombool: If True compute a point-estimate of the dipole moment at the last iteration.

compute_dip_mom(est_locs)[source]¶

Compute a point estimate for the dipole moments.

Parameters:

est_locslist of ndarray of int: The estimated source locations.

compute_stc()[source]¶

Compute and export in an .stc file the posterior pdf $p(r|\mathbf{y}, \hat{n}_D)$ , being $\hat{n}_D$ the estimated number of sources. For each point $r$ in the brain discretization, $p(r|\mathbf{y}, \hat{n}_D)$ is the probability of a source being located in $r$ .

Parameters:

subjectstr | None: The subject name.

Returns:

stcSourceEstimate | VolSourceEstimate: The source estimate object containing the posterior map of the dipoles’ location.

goodness_of_fit()[source]¶

Evaluate the estimated configuration of dipoles. The goodness of fit (GOF) with the recorded data is defined as

$GOF = \frac{\| \mathbf{y} - \hat{\mathbf{y}} \|} { \|\mathbf{y}\|}$

where $\mathbf{y}$ is the recorded data, $\hat{\mathbf{y}}$ is the field generated by the estimated configuration of dipoles, and $\| \cdot \|$ is the Frobenius norm.

Returns:

goffloat: The goodness of fit with the recorded data.

plot_source_amplitudes(n_sources=None)[source]¶

Plot the amplitude of the estimated sources as function of time.

Parameters:

n_sources: :py:class:`~int` | None: Set the number of sources of the alternative configuration to plot. If None, plot the configuration with the estimated number of sources.

plot_source_number(kind='bar')[source]¶

Plot the probability of number of sources.

Parameters:

kindstr: The kind of plot to draw. Options are: “bar”, “pie”.

plot_sources(n_sources=None, plot_kwargs=None, savepath=None, save_kwargs=None, true_sources=None, force_open=False)[source]¶

Plot the estimated sources. The default behaviour of the method is the following:

if Sesame has been instantiated through prepare_sesame(), it visualizes the posterior map of the dipoles’ location and the estimated sources
- on the inflated brain, if Sesame.forward is of kind surface;
- on the MRI, if Sesame.forward is of kind volume.
if Sesame has been instantiated through Sesame, it visualizes the posterior map of the dipoles’ location and the estimated sources as a PolyData object.

Parameters:

n_sources: :py:class:`~int` | None: Set the number of sources of the alternative configuration to plot. If None, plot the configuration with the estimated number of sources.
plot_kwargsdict | None: Additional arguments to plot_source_estimates() or plot_stat_map() (e.g., dict(surface=’white’)).
savepathstr | None: File path to write image to. If None, no image is written.
save_kwargsdict | None: Additional arguments to screenshot() or savefig().
true_sourcesndarray | None: In simulation settings, indexes of source space points in which true sources are located.
force_openbool: If True, force the image to stay open.

save_h5(fpath, sbj=None, sbj_viz=None, data_path=None, fwd_path=None, cov_path=None, src_path=None, lf_path=None)[source]¶

Save SESAME result to an HDF5 file.

Parameters:

fpathstr: The path to the save file.
sbjstr | None: The subject name.
sbj_vizstr | None: The name of the subject’s FreeSurfer folder.
data_pathstr | None: The path to the data file.
fwd_pathstr | None: The path to the forward solution file.
cov_pathstr | None: The path to the noise covariance file.
src_pathstr | None: The path to the source space file.
lf_pathstr | None: The path to the leadfield matrix file.

save_pkl(fpath, sbj=None, sbj_viz=None, data_path=None, fwd_path=None, cov_path=None, src_path=None, lf_path=None, save_all=False)[source]¶

Save SESAME result to a Python pickle file.

Parameters:

fpathstr: The path to the save file.
sbjstr | None: The subject name.
sbj_vizstr | None: The name of the subject’s FreeSurfer folder.
data_pathstr | None: The path to the data file.
fwd_pathstr | None: The path to the forward solution file.
cov_pathstr | None: The path to the noise covariance file.
src_pathstr | None: The path to the source space file.
lf_pathstr | None: The path to the leadfield matrix file.
save_allbool: If True, save the data and the forward model. Default to False.

source_dispersion()[source]¶

Compute the Source Dispersion measure to quantify the spatial dispersion of the posterior probability map. It is defined as

$SD = \sqrt{\frac{\sum_{j=1}^{N_v} \big(d_j |S_j|\big)^2}{\sum_{j=1}^{N_v}|S_j|^2}}$

where $N_v$ is the number of voxels, $d_j$ is the distance between the $j$ -th voxel and the nearest estimated dipole location and $S_j$ is the value of the cortical map at the $j$ -th voxel.