mne_hfo.HilbertDetector

class mne_hfo.HilbertDetector(threshold=3, filter_band=(30, 100), band_method='linear', n_bands=300, cycle_threshold=1, gap_threshold=1, n_jobs=-1, offset=0, scoring_func='f1', hfo_name='hfo', verbose=False)

2D HFO hilbert detection used in Kucewicz et al. 2014.

A multi-taper method with: 4 Hz bandwidth, 1 sec sliding window, stepsize 100 ms, for the 1-500 Hz range, no padding, 2 tapers. For full details, see [1].

Parameters:

thresholdfloat

Threshold for detection (default=3).

filter_bandtuple(float, float)

Low cut-off frequency at index 0 and high cut-off frequency at index 1. The default is (30, 100).

band_methodstr

Spacing of hilbert frequency bands - options: ‘linear’ or ‘log’ (default=’linear’). Linear provides better frequency resolution but is slower.

n_bandsint

Number of bands if band_spacing = log (default=300).

cycle_thresholdfloat

Minimum number of cycles to detect (default=1).

gap_thresholdfloat

Number of cycles for gaps (default=1).

n_jobsint

Number of cores to use (default=1).

offsetint

Offset which is added to the final detection. This is used when the function is run in separate windows. Default = 0.

scoring_funcstr

The scoring function to apply when trying to match HFOs with a different dataset, such as manual annotations.

hfo_namestr

What to name the events detected (i.e. fast ripple if freq_band is (250, 500)).

verbosebool

Verbosity of the detector.

References

[1]

Michal T Kucewicz, Jan Cimbalnik, Joseph Y Matsumoto, Benjamin H Brinkmann, Mark R Bower, Vincent Vasoli, Vlastimil Sulc, Fred Meyer, WR Marsh, SM Stead, and others. High frequency oscillations are associated with cognitive processing in human recognition memory. Brain, 137(8):2231–2244, 2014. doi:10.1093/brain/awu149.

Attributes:

h_freq

Higher frequency band for HFO definition.

hfo_annotations

HFO Annotations.

hfo_event_arr

HFO event array.

l_freq

Lower frequency band for HFO definition.

step_size

Step size of each window.

Methods

fit(X[, y])	Fit the model according to the optionally given training data.
fit_predict(X[, y])	Perform fit on X and returns labels for X.
get_metadata_routing()	Get metadata routing of this object.
get_params([deep])	Get parameters for this estimator.
predict(X)	Scikit-learn override predict function.
score(X, y[, sample_weight])	Return the score of the HFO prediction.
set_params(**params)	Set the parameters of this estimator.
set_score_request(*[, sample_weight])	Request metadata passed to the score method.
to_data_frame([format])	Export HFO annotations in tabular structure as a pandas DataFrame.

fit(X, y=None)

Fit the model according to the optionally given training data.

Parameters:

Xmne.io.Raw of shape (n_samples, n_features) | pd.DataFrame

Training vector, where n_samples is the number of samples and n_features is the number of features. In MNE-HFO, n_features are the number of time points in the EEG data, and n_samples are the number of channels.

yarray_like of shape (n_samples, n_output)

Target vector relative to X.

Returns:

selfDetector

Fitted estimator.

Notes

All detectors use a sliding window to compute HFOs in windows.

fit_predict(X, y=None)

Perform fit on X and returns labels for X.

Returns -1 for outliers and 1 for inliers.

Parameters:

X{array_like, sparse matrix, dataframe} of shape (n_samples, n_features)

The input data.

ynp.ndarray

Not used, present for API consistency by convention.

Returns:

yndarray of shape (n_samples,)

1 for inliers, -1 for outliers.

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.

property h_freq

Higher frequency band for HFO definition.

property hfo_annotations

HFO Annotations.

Returns:

hfo_annotationsinstance of Annotations

mne.Annotations object with onset, duration and specified ch_name for each HFO event detected.

property hfo_event_arr

HFO event array.

Returns:

hfo_event_arrnp.ndarray

Array that is (n_chs, n_samples), which has a value of 1 if there is an HFO in that sample.

property l_freq

Lower frequency band for HFO definition.

predict(X)

Scikit-learn override predict function.

Just directly computes HFOs using fit function.

Parameters:

Xmne.io.Raw | pd.DataFrame

Input data.

Returns:

ypredlist[list[tuple]]

List of HFO events per channel in order of ch_names of input data. HFO events are stored as list of tuples: onset and offset of the HFO event.

score(X, y, sample_weight=None)

Return the score of the HFO prediction.

Parameters:

Xnp.ndarray

Channel data to detect HFOs on.

yDataFrame

Event Dataframe of true labels.

sample_weightnp.ndarray

Not used.

Returns:

scorefloat

The score relative to true annotations we want.

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_score_request(*, sample_weight: bool | None | str = '$UNCHANGED$') → HilbertDetector

Request metadata passed to the score method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config()). Please see 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.

New in version 1.3.

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline. Otherwise it has no effect.

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.

property step_size

Step size of each window.

Window increment over the samples of signal.

to_data_frame(format=None)

Export HFO annotations in tabular structure as a pandas DataFrame.

Parameters:

formatstr | None

If None (default), will return a mne.Annotations object as a DataFrame. If ‘bids’, then will return a DataFrame formatted with columns names as an ‘annotations.tsv’ derivatve file.

Returns:

resultpandas.DataFrame

Returns a pandas DataFrame with onset, duration, and description columns. A column named ch_names is added if any annotations are channel-specific.