pyriemann.artifact_detection.PotatoField¶

class pyriemann.artifact_detection.PotatoField(n_potatoes=1, p_threshold=0.01, z_threshold=3, metric='riemann', n_iter_max=10, pos_label=1, neg_label=0, method_combination='fisher')[source]¶

Artifact detection with the Riemannian Potato Field.

The Riemannian Potato Field [1] is a clustering method used to detect artifact in multichannel signals. Processing SPD/HPD matrices, the algorithm combines several potatoes of low dimension, each one being designed to capture specific artifact typically affecting specific subsets of channels and/or specific frequency bands.

Parameters:

n_potatoesint, default=1

Number of potatoes in the field.

p_thresholdfloat, default=0.01

Threshold on probability to being clean, in (0, 1), combining probabilities of potatoes using method_combination.

z_thresholdfloat, default=3

Threshold on z-score of distance to reject artifacts. It is the number of standard deviations from the mean of distances to the centroid.

metricstring | dict | list, default=”riemann”

Metric used for mean estimation (for the list of supported metrics, see pyriemann.geometry.mean.gmean()) and for distance estimation (see pyriemann.geometry.distance.distance()). The metric can be a single str; or a dict with two keys, “mean” and “distance”, in order to pass different metrics for mean and distance; or a list of n_potatoes str or dict, in order to pass different metrics for each potato [2].

Changed in version 0.11: Allow a different metric per potato.

n_iter_maxint, default=10

The maximum number of iteration to reach convergence.

pos_labelint, default=1

The positive label corresponding to clean data.

neg_labelint, default=0

The negative label corresponding to artifact data.

method_combination{“fisher”, “stouffer”} | callable, default=”fisher”

Method to combine probabilities from the different potatoes:

fisher: Fisher’s method;
stouffer: Stouffer’s z-score method;
callable: for a custom combination function, with an axis argument.

Added in version 0.11.

See also

Potato

Notes

Added in version 0.3.

Changed in version 0.12: Move from clustering to artifactdetection.

References

[1]

The Riemannian Potato Field: A Tool for Online Signal Quality Index of EEG Q. Barthélemy, L. Mayaud, D. Ojeda, and M. Congedo. IEEE Transactions on Neural Systems and Rehabilitation Engineering, 2019

[2]

Improved Riemannian potato field: an Automatic Artifact Rejection Method for EEG D. Hajhassani, Q. Barthélemy, J. Mattout & M. Congedo. Biomedical Signal Processing and Control, 2026

__init__(n_potatoes=1, p_threshold=0.01, z_threshold=3, metric='riemann', n_iter_max=10, pos_label=1, neg_label=0, method_combination='fisher')[source]¶: Init.

fit(X, y=None, sample_weight=None)[source]¶

Fit the potato field.

Fit the potato field from SPD/HPD matrices, with iterative outlier removal to obtain reliable potatoes.

Parameters:

Xlist of n_potatoes ndarrays of shape (n_matrices, n_channels, n_channels) with same n_matrices but potentially different n_channels: List of sets of SPD/HPD matrices, each corresponding to a different subset of channels and/or filtering with a specific frequency band.
yNone | ndarray, shape (n_matrices,), default=None: Labels corresponding to each matrix: positive (resp. negative) label corresponds to a clean (resp. artifact) matrix. If None, all matrices are considered as clean.
sample_weightNone | ndarray, shape (n_matrices,), default=None: Weights for each matrix. If None, it uses equal weights.

Returns:

selfPotatoField instance: The PotatoField instance.

fit_transform(X, y=None, sample_weight=None)[source]¶

Fit and transform in a single function.

Parameters:

Xlist of n_potatoes ndarrays of shape (n_matrices, n_channels, n_channels) with same n_matrices but potentially different n_channels: List of sets of SPD/HPD matrices, each corresponding to a different subset of channels and/or filtering with a specific frequency band.
yNone | ndarray, shape (n_matrices,), default=None: Labels corresponding to each matrix: positive (resp. negative) label corresponds to a clean (resp. artifact) matrix. If None, all matrices are considered as clean.
sample_weightNone | ndarray, shape (n_matrices,), default=None: Weights for each matrix. If None, it uses equal weights.

Returns:

zndarray, shape (n_matrices, n_potatoes): Standardized log-distances to the centroids.

get_metadata_routing()¶

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:

routingMetadataRequest: A MetadataRequest encapsulating routing information.

get_params(deep=True)¶

Get parameters for this estimator.

Parameters:

deepbool, default=True: If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

paramsdict: Parameter names mapped to their values.

partial_fit(X, y=None, *, sample_weight=None, alpha=0.1)[source]¶

Partially fit the potato field.

This partial fit can be used to update dynamic or semi-dymanic online potatoes with clean matrices.

Parameters:

Xlist of n_potatoes ndarrays of shape (n_matrices, n_channels, n_channels) with same n_matrices but potentially different n_channels: List of sets of SPD/HPD matrices, each corresponding to a different subset of channels and/or filtering with a specific frequency band.
yNone | ndarray, shape (n_matrices,), default=None: Labels corresponding to each matrix: positive (resp. negative) label corresponds to a clean (resp. artifact) matrix. If None, all matrices are considered as clean.
sample_weightNone | ndarray, shape (n_matrices,), default=None: Weights for each matrix. If None, it uses equal weights.
alphafloat, default=0.1: Update rate in [0, 1] for the centroid, and mean and standard deviation of log-distances: 0 for no update, 1 for full update.

Returns:

selfPotatoField instance: The PotatoField instance.

predict(X)[source]¶

Predict artifact from data.

Parameters:

Xlist of n_potatoes ndarrays of shape (n_matrices, n_channels, n_channels) with same n_matrices but potentially different n_channels: List of sets of SPD/HPD matrices, each corresponding to a different subset of channels and/or filtering with a specific frequency band.

Returns:

predndarray of bool, shape (n_matrices,): The artifact detection: True if the matrix is clean, and False if the matrix contains an artifact.

predict_proba(X)[source]¶

Predict probability combining probabilities of potatoes.

Predict probability combining probabilities of the different potatoes using method_combination. With Fisher’s method, a threshold of 0.01 can be used.

Parameters:

Xlist of n_potatoes ndarrays of shape (n_matrices, n_channels, n_channels) with same n_matrices but potentially different n_channels: List of sets of SPD/HPD matrices, each corresponding to a different subset of channels and/or filtering with a specific frequency band.

Returns:

probandarray, shape (n_matrices,): Matrix is considered as normal/clean for high value of proba. It is considered as abnormal/artifacted for low value of proba.

score(X, y, sample_weight=None)¶

Return the mean accuracy on the given test data and labels.

Parameters:

Xndarray, shape (n_matrices, n_channels, n_channels): Test set of SPD matrices.
yndarray, shape (n_matrices,): True labels for each matrix.
sample_weightNone | ndarray, shape (n_matrices,), default=None: Weights for each matrix.

Returns:

scorefloat: Mean accuracy of clf.predict(X) wrt. y.

set_fit_request(*, sample_weight: bool | None | str = '$UNCHANGED$') → PotatoField¶

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

True: metadata is requested, and passed to fit if provided. The request is ignored if metadata is not provided.
False: metadata is not requested and the meta-estimator will not pass it to fit.
None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:

sample_weightstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED: Metadata routing for sample_weight parameter in fit.

Returns:

selfobject: The updated object.

set_output(*, transform=None)¶

Set output container.

See Introducing the set_output API for an example on how to use the API.

Parameters:

transform{“default”, “pandas”, “polars”}, default=None

Configure output of transform and fit_transform.

“default”: Default output format of a transformer
“pandas”: DataFrame output
“polars”: Polars output
None: Transform configuration is unchanged

Added in version 1.4: “polars” option was added.

Returns:

selfestimator instance: Estimator instance.

set_params(**params)¶

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:

**paramsdict: Estimator parameters.

Returns:

selfestimator instance: Estimator instance.

set_partial_fit_request(*, alpha: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → PotatoField¶

Configure whether metadata should be requested to be passed to the partial_fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

True: metadata is requested, and passed to partial_fit if provided. The request is ignored if metadata is not provided.
False: metadata is not requested and the meta-estimator will not pass it to partial_fit.
None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:

alphastr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED: Metadata routing for alpha parameter in partial_fit.
sample_weightstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED: Metadata routing for sample_weight parameter in partial_fit.

Returns:

selfobject: The updated object.

set_score_request(*, sample_weight: bool | None | str = '$UNCHANGED$') → PotatoField¶

Configure whether metadata should be requested to be passed to the score method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

True: metadata is requested, and passed to score if provided. The request is ignored if metadata is not provided.
False: metadata is not requested and the meta-estimator will not pass it to score.
None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:

sample_weightstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED: Metadata routing for sample_weight parameter in score.

Returns:

selfobject: The updated object.

transform(X)[source]¶

Return the standardized log-distances to the centroids.

Return the standardized log-distances to the centroids, ie geometric z-scores of distances.

Parameters:

Xlist of n_potatoes ndarrays of shape (n_matrices, n_channels, n_channels) with same n_matrices but potentially different n_channels: List of sets of SPD/HPD matrices, each corresponding to a different subset of channels and/or filtering with a specific frequency band.

Returns:

zndarray, shape (n_matrices, n_potatoes): Standardized log-distances to the centroids.

Examples using `pyriemann.artifact_detection.PotatoField`¶

Online Artifact Detection with Riemannian Potato Field

Online Artifact Detection with Riemannian Potato Field