API Reference#

This page documents the stable public API of jamica.

Most users will interact with one of these interfaces:

jamica.Amica for fitting AMICA directly on NumPy arrays.
jamica.fit_ica() for single-model MNE-Python workflows.
jamica.AmicaICA for multi-model fits, which exposes one mne.preprocessing.ICA per model.
jamica.amica() as the stable single-model solver boundary for frameworks such as MNE that already whiten and PCA-reduce their data. See MNE single-model solver contract for its matrix and validation contract.

Core API#

Classes#

`Amica`	Native JAX implementation of AMICA algorithm.
`AmicaConfig`	Configuration for AMICA algorithm.
`AmicaResult`	Container for AMICA results.
`AmicaICA`	Multi-model AMICA fit exposing one `mne.preprocessing.ICA` per model.

Functions#

jamica.amica(X, n_components=None, whiten=False, return_n_iter=False, random_state=None, max_iter=2000, num_mix=3, *, num_models=1, min_dll=1e-09, do_newton=True, newt_start=50, chunk_size='auto')[source]#

Fit a single AMICA model through a Picard-compatible interface.

Returns the (K, W, Y) tuple MNE-Python’s ICA dispatch expects (the calling convention shared by its FastICA/Infomax/Picard methods).

With whiten=False, this function is a strict preprocessed-data boundary: JAMICA performs no centering, sphering, or PCA, and always fits exactly one model. In that mode the returned unmixing matrix operates directly on X, including when the solver applies its emergency scalar rescaling for numerical stability.

Parameters:

Xndarray, shape (n_features, n_samples): Pre-whitened data, features x samples. This matches MNE’s ICA-method convention; MNE passes data[:, sel].T which gives (n_components, n_samples).
n_componentsint | None: Number of components. With whiten=False, this must be None or equal to X.shape[0] because the input has already been reduced by the caller. With whiten=True, it controls JAMICA’s internal PCA.
whitenbool: If True, whiten the data internally. MNE always passes False (data is pre-whitened by MNE’s PCA step).
return_n_iterbool: If True, return n_iter as a fourth element: K, W, Y, n_iter.
random_stateint | numpy.random.RandomState | numpy.random.Generator | None: Random state controlling initialization. Integer seeds are repeatable across calls; NumPy RNG objects are consumed in place.
max_iterint: Maximum number of EM iterations.
num_mixint: Number of generalized Gaussian mixture components per source.
num_modelsint: Number of AMICA models. Only 1 is supported by this functional interface. Use jamica.AmicaICA for multiple models.
min_dllfloat: Minimum log-likelihood improvement used for convergence.
do_newtonbool: Whether to use Newton updates after the natural-gradient warm-up.
newt_startint: Iteration at which Newton updates may begin.
chunk_sizeint | ‘auto’ | None: Number of samples per E-step block. 'auto' selects a block size from the active backend and available memory.

Returns:

Kndarray, shape (n_components, n_features), or None: Pre-whitening matrix. Always None when whiten=False, which is the case for MNE (it pre-whitens itself and discards this value). When whiten=True this is the sphering matrix, including any scalar input rescaling applied by the solver.
Wndarray, shape (n_components, n_components): Unmixing matrix. With whiten=False, it operates directly on X. With whiten=True, it operates on the centered data transformed by K.
Yndarray, shape (n_components, n_samples): Source matrix. This is exactly W @ X when whiten=False; otherwise JAMICA’s centering and the returned K are also applied.
n_iterint: Number of iterations. Only returned when return_n_iter=True, as the fourth element.

`fit_ica`	Fit ICA using AMICA on MNE Raw or Epochs data.
`get_model_ica`	Return an `mne.preprocessing.ICA` for one model of a multi-model AMICA fit.
`read_amica_ica`	Read an `AmicaICA` written by `AmicaICA.save()`.

Warnings#

JamicaConvergenceWarning

Warning raised when JAMICA stops before convergence.