jamica.AmicaICA#

class jamica.AmicaICA(n_models=1, n_components=None, max_iter=2000, num_mix=3, random_state=None, picks=None, reject=None, flat=None, decim=None, fit_params=None, verbose=None)[source]#

Bases: object

Multi-model AMICA fit exposing one mne.preprocessing.ICA per model.

Parameters:

n_modelsint: Number of AMICA models. 1 reduces to an ordinary single-model fit.
n_componentsint | None: Number of PCA components. None uses the estimated numerical rank.
max_iterint: Maximum AMICA iterations.
num_mixint: Generalized-Gaussian mixture components per source.
random_stateint | None: Seed for the AMICA fit.
picksstr | array_like | None: Channels to use, following fit_ica().
rejectdict | None: MNE-style epoch amplitude rejection applied before fitting.
flatdict | None: Flat-channel rejection applied before fitting.
decimint | None: Decimation factor applied before fitting. See Notes on posteriors.
fit_paramsdict | None: Extra keywords forwarded to AmicaConfig.
verbosebool | None: Verbosity.

Attributes:

models_list of mne.preprocessing.ICA: List of per-model mne.preprocessing.ICA views (cached).
n_models_int: Number of fitted models.
model_weights_np.ndarray, shape (n_models,): Model priors (AMICA’s gm).
model_posteriors_np.ndarray: p(h | x_t) on the ORIGINAL input sampling grid: (n_models, n_times) for Raw and (n_models, n_epochs, n_times) for Epochs, regardless of any decimation used while fitting. Points excluded from the fit by epoch rejection are NaN.
fit_sample_mask_np.ndarray of bool: Which points of that same grid entered the optimisation – (n_times,) for Raw, (n_epochs, n_times) for Epochs. See _build_fit_sample_mask() for how decimation is treated.
amica_result_jamica.AmicaResult: The complete fit, including the density parameters per model.

Parameters:

n_models (int)
n_components (int | None)
max_iter (int)
num_mix (int)
random_state (int | None)
fit_params (dict | None)

Notes

model_weights_ and model_posteriors_ are different quantities: the former is a single global prior per model, the latter a per-sample responsibility that says which model is active when.

model_posteriors_ is always on the input grid. Because a genuine new-data evaluation exists, the fitted model is simply applied to every sample afterwards; nothing is interpolated or resampled from the fit-time array. Decimation therefore changes which samples drove the optimisation, not the shape of the reported posteriors.

__init__(n_models=1, n_components=None, max_iter=2000, num_mix=3, random_state=None, picks=None, reject=None, flat=None, decim=None, fit_params=None, verbose=None)[source]#

Parameters:

n_models (int)
n_components (int | None)
max_iter (int)
num_mix (int)
random_state (int | None)
fit_params (dict | None)

Methods

`__init__`([n_models, n_components, max_iter, ...])
`apply`(inst[, model_idx])	Remove excluded components using one model's decomposition.
`export_model_fifs`(fname[, overwrite])	Write each model as an ordinary `-ica.fif`.
`fit`(inst)	Fit AMICA on Raw or Epochs.
`get_model_probabilities`(inst)	Model posteriors `p(h \| x_t)` evaluated on new data.
`save`(fname[, overwrite])	Write the whole fit -- every model plus the mixture -- to HDF5.

Attributes

models_

List of per-model mne.preprocessing.ICA views (cached).

fit(inst)[source]#

Fit AMICA on Raw or Epochs.

Parameters:

instmne.io.Raw | mne.Epochs: Data to decompose.

Returns:

AmicaICA: The fitted instance.

property models_#: List of per-model mne.preprocessing.ICA views (cached).

get_model_probabilities(inst)[source]#

Model posteriors p(h | x_t) evaluated on new data.

Recomputed from the fitted parameters, not resampled from the fit-time posterior array.

Parameters:

instmne.io.Raw | mne.Epochs: Data with the same channels as the fit.

Returns:

np.ndarray: (n_models, n_times) for Raw, (n_models, n_epochs, n_times) for Epochs.

apply(inst, model_idx=None, **kwargs)[source]#

Remove excluded components using one model’s decomposition.

Parameters:

instmne.io.Raw | mne.Epochs: Data to clean, modified in place by MNE.
model_idxint | None: Which model to apply. Required when n_models_ > 1.
**kwargs: Passed through to mne.preprocessing.ICA.apply().

Returns:

inst: The cleaned instance.

Raises:

ValueError: When n_models_ > 1 and no model was named. A mixture has no single reconstruction until a combination rule is chosen, and silently taking the highest-weight model would hide that choice.

save(fname, overwrite=False)[source]#

Write the whole fit – every model plus the mixture – to HDF5.

A FIF file stores one unmixing matrix, so it cannot hold a mixture on its own. HDF5 is used here for the same reason EOGRegression uses it, and through the same MNE helper. Pair this with export_model_fifs() when the individual models should also be readable without jamica installed.

Parameters:

fnamepath-like: Destination, conventionally ending in .h5.
overwritebool: Overwrite an existing file.

export_model_fifs(fname, overwrite=False)[source]#

Write each model as an ordinary -ica.fif.

These are plain MNE ICA files: they open with mne.preprocessing.read_ica() on a machine that has never installed jamica, so a decomposition never becomes readable only through this package. What they cannot carry is the mixture itself, the priors and the posterior time course, which is what save() is for.

Parameters:

fnamepath-like: Template ending in -ica.fif. The model index is inserted before the suffix, so sub-01-ica.fif yields sub-01-model-0-ica.fif and so on.
overwritebool: Overwrite existing files.

Returns:

list of pathlib.Path: The files written, in model order.