API Reference#

class remode.ReMoDe(alpha: float = 0.05, alpha_correction: Literal['descriptive_peaks', 'max_modes', 'none'] | Callable = 'descriptive_peaks', statistical_test: Literal['bootstrap', 'binomial', 'fisher'] | Callable[[numpy.ndarray, int, int, int], Tuple[float, float]] = 'bootstrap', definition: Literal['shape_based', 'peak_based'] = 'shape_based', n_boot: int = 10000, random_state: int | None = None)#

ReMoDe (Robust Mode Detection) is a class for detecting modes in a dataset.

The class uses statistical tests to identify local maxima in the dataset that are statistically significant. The identified modes can then be used for further analysis.

alpha#

The significance level for the statistical tests. Default is 0.05.

Type:

float

alpha_correction#

The method for correcting the significance level for multiple comparisons. Options are “descriptive_peaks”, “max_modes”, and “none”. Default is “descriptive_peaks”.

Type:

str or function

statistical_test#

The statistical test to use for identifying local maxima. Options are “bootstrap”, “binomial”, “fisher”, or a custom callable. Default is “bootstrap”.

Type:

str or function

definition#

Underlying modality definition. If “shape_based”, a uniform distribution can be classified as unimodal. If “peak_based”, a non-significant chi-square uniformity test leads to zero detected modes.

Type:

str

format_data(xt: np.ndarray) → np.ndarray:#

Formats the input data for mode detection.

fit(xt: np.ndarray) → Dict[str, Union[int, np.ndarray]]:#

Fits the model to the input data and returns the detected modes.

remode_stability(iterations: int, percentage_steps: int) → Dict[str, Any]:#

Evaluates the stability of the detected modes using the jackknife resampling method.

format_data(xt: numpy.ndarray | list, levels: numpy.ndarray | None = None) → numpy.ndarray#

Formats the input data for mode detection.

Parameters:

  • xt (np.ndarray) – The input data array.

  • levels (np.ndarray, optional) – The levels at which to find the modes. If not provided, defaults to the range of the length of the input data.

Returns:

The formatted data array.

Return type:

np.ndarray

fit(xt: numpy.ndarray, set_data: bool = True, levels: numpy.ndarray = numpy.array) → Dict[str, Any]#

Fits the model to the input data and returns the detected modes.

This method first applies an alpha correction to the input data, then finds the local maxima (modes) in the data. If levels is not provided, it defaults to the range of the length of the input data. If set_data is True, the input data is stored in the xt attribute of the class instance.

Parameters:

  • xt (np.ndarray) – The input data array.

  • set_data (bool, optional) – Whether to store the input data in the xt attribute of the class instance. Default is True.

  • levels (np.ndarray, optional) – The levels at which to find the modes. If not provided, defaults to the range of the length of the input data.

Returns:

A dictionary containing the detected modes and their properties. The keys of the dictionary are the indices of the modes, and the values are the properties of the modes.

Return type:

Dict[str, Any]

plot_maxima(ax: Axes | None = None, format_plot: bool | None = True) → None#

Formats the input data for mode detection.

Parameters:

  • xt (np.ndarray) – The input data array.

  • format_plot (bool, optional) – Whether to format the plot. Default is True.

Returns:

The formatted data array.

Return type:

np.ndarray

remode_stability(iterations: int = 100, percentage_steps: int = 10, plot: bool = True) → Dict[str, Any]#

Evaluates the stability of the detected modes using the jackknife resampling method.

Parameters:

  • iterations (int) – The number of iterations to perform for the jackknife resampling.

  • percentage_steps (int) – The number of percentage steps to remove in the jackknife resampling.

  • plot (bool) – Whether to plot the stability analysis results.

Returns:

A dictionary containing the results of the stability evaluation.

Return type:

Dict[str, Any]

evaluate_stability(iterations: int = 100, percentage_steps: int = 10, plot: bool = True) → Dict[str, Any]#

Deprecated alias for remode_stability.

remode.perform_fisher_test(x: numpy.ndarray, candidate: int, left_min: int, right_min: int) → Tuple[float, float]#

Perform Fisher’s exact test on both sides of a candidate maximum to test if it is a true local maximum.

Parameters:

  • x (np.ndarray) – The input data array.

  • candidate (int) – The index of the candidate maximum.

  • left_min (int) – The index of the minimum value on the left side of the candidate maximum.

  • right_min (int) – The index of the minimum value on the right side of the candidate maximum.

Returns:

The p-values of the Fisher’s exact test for the left and right sides of the candidate maximum.

Return type:

Tuple[float, float]

remode.perform_binomial_test(x: numpy.ndarray, candidate: int, left_min: int, right_min: int) → Tuple[float, float]#

Perform binomial tests on both sides of a candidate maximum to test if it is a true local maximum.

Parameters:

  • x (np.ndarray) – The input data array.

  • candidate (int) – The index of the candidate maximum.

  • left_min (int) – The index of the minimum value on the left side of the candidate maximum.

  • right_min (int) – The index of the minimum value on the right side of the candidate maximum.

Returns:

The p-values of the binomial tests for the left and right sides of the candidate maximum.

Return type:

Tuple[float, float]

remode.perform_bootstrap_test(x: numpy.ndarray, candidate: int, left_min: int, right_min: int, n_boot: int = 10000, rng: numpy.random.Generator | None = None) → Tuple[float, float]#

Perform the ReMoDe bootstrap significance test for a candidate mode.

Parameters:

  • x (np.ndarray) – The input data array.

  • candidate (int) – The index of the candidate maximum.

  • left_min (int) – The index of the minimum value on the left side of the candidate maximum.

  • right_min (int) – The index of the minimum value on the right side of the candidate maximum.

  • n_boot (int, optional) – Number of bootstrap samples. Default is 10000.

  • rng (np.random.Generator, optional) – Random number generator to use. If omitted, a new generator is created.

Returns:

Bootstrap p-value duplicated for left/right slots for compatibility with the other significance test interfaces.

Return type:

Tuple[float, float]