pepbench 0.1.0__py3-none-any.whl

pepbench/__init__.py

@@ -0,0 +1,7 @@
+"""Top-level module for the PEPBench package."""
+
+from pepbench import algorithms, datasets, evaluation, pipelines
+
+__version__ = "0.1.0"
+
+__all__ = ["algorithms", "datasets", "pipelines", "evaluation"]

pepbench/_docutils.py

@@ -0,0 +1,64 @@
+"""Some small utilities to improve writing docstrings.
+
+For now, this just exports some functions from scipy._lib.doccer, to have only one place to import from.
+While, the ``doccer`` submodule of scip[y is not part of the public API, it seems to be stable enough to use it here.
+"""
+
+from collections.abc import Callable
+
+from scipy._lib.doccer import filldoc, inherit_docstring_from
+
+
+def filldoc_with_better_error(docdict: dict[str, str]) -> filldoc:
+    def inner(func: Callable) -> str:
+        try:
+            return filldoc(docdict)(func)
+        except ValueError as e:
+            if "unsupported format character" in str(e):
+                raise ValueError(
+                    "Your docstring contains a single '%' character. "
+                    "This is not supported by this decorator. "
+                    "If you want to type a '%' character, you need to type '%%'."
+                ) from e
+            raise
+
+    return inner
+
+
+def make_filldoc(docdict: dict[str, str], *, doc_summary: str | None = None) -> filldoc:
+    """Create a new doc-filler from a dictionary.
+
+    This can be applied to a function, method, or class to substitute ``%(key)s`` occurrences in its docstring.
+
+    Parameters
+    ----------
+    docdict
+        Dictionary with docstring keys and values.
+        These can be multiline strings and will be dedented before substitution.
+    doc_summary
+        An optional summary line for the docstring of the returned decorator function.
+        This is only relevant for inclusion in the documentation.
+
+    Note
+    ----
+    If you use this decorator, your docstrings can not contain a single ``%`` character.
+    If you want to type a ``%`` character, you need to type ``%%``.
+    """
+    inner = filldoc_with_better_error(docdict)
+
+    if doc_summary is None:
+        doc_summary = "Fill docstring from dictionary."
+
+    full_doc = f"""{doc_summary}
+
+    Available keys for the substitution::
+
+    {list(docdict.keys())}
+
+    """
+    inner.__doc__ = full_doc
+    inner._dict = docdict
+    return inner
+
+
+__all__ = ["make_filldoc", "inherit_docstring_from"]

pepbench/algorithms/__init__.py

@@ -0,0 +1,16 @@
+"""Individual algorithms for extracting fiducial points from ECG and ICG signals.
+
+Together, these algorithms can be combined into a PEP extraction pipeline
+(e.g., :class:`~pepbench.pipelines.PepExtractionPipeline`).
+
+The following categories of algorithms are available:
+    * :mod:`~pepbench.algorithms.heartbeat_segmentation` - Algorithms for heartbeat segmentation
+    * :mod:`~pepbench.algorithms.ecg` - Algorithms for ECG fiducial point extraction
+    * :mod:`~pepbench.algorithms.icg` - Algorithms for ICG fiducial point extraction
+    * :mod:`~pepbench.algorithms.outlier_correction` - Algorithms for outlier correction of ICG fiducial points
+
+"""
+
+from pepbench.algorithms import ecg, heartbeat_segmentation, icg, outlier_correction
+
+__all__ = ["heartbeat_segmentation", "ecg", "icg", "outlier_correction"]

pepbench/algorithms/ecg.py

@@ -0,0 +1,13 @@
+"""Module for ECG event extraction algorithms."""
+
+from biopsykit.signals.ecg.event_extraction import (
+    QPeakExtractionForouzanfar2018,
+    QPeakExtractionMartinez2004Neurokit,
+    QPeakExtractionVanLien2013,
+)
+
+__all__ = [
+    "QPeakExtractionForouzanfar2018",
+    "QPeakExtractionMartinez2004Neurokit",
+    "QPeakExtractionVanLien2013",
+]

pepbench/algorithms/heartbeat_segmentation.py

@@ -0,0 +1,5 @@
+"""Module for heartbeat segmentation algorithms based on ECG data."""
+
+from biopsykit.signals.ecg.segmentation import HeartbeatSegmentationNeurokit
+
+__all__ = ["HeartbeatSegmentationNeurokit"]

pepbench/algorithms/icg.py

@@ -0,0 +1,29 @@
+"""Module for ICG event extraction algorithms."""
+
+from biopsykit.signals.icg.event_extraction import (
+    BPointExtractionArbol2017IsoelectricCrossings,
+    BPointExtractionArbol2017SecondDerivative,
+    BPointExtractionArbol2017ThirdDerivative,
+    BPointExtractionDebski1993SecondDerivative,
+    BPointExtractionDrost2022,
+    BPointExtractionForouzanfar2018,
+    BPointExtractionLozano2007LinearRegression,
+    BPointExtractionLozano2007QuadraticRegression,
+    BPointExtractionSherwood1990,
+    BPointExtractionStern1985,
+    CPointExtractionScipyFindPeaks,
+)
+
+__all__ = [
+    "CPointExtractionScipyFindPeaks",
+    "BPointExtractionStern1985",
+    "BPointExtractionLozano2007LinearRegression",
+    "BPointExtractionLozano2007QuadraticRegression",
+    "BPointExtractionArbol2017IsoelectricCrossings",
+    "BPointExtractionArbol2017ThirdDerivative",
+    "BPointExtractionArbol2017SecondDerivative",
+    "BPointExtractionSherwood1990",
+    "BPointExtractionDrost2022",
+    "BPointExtractionDebski1993SecondDerivative",
+    "BPointExtractionForouzanfar2018",
+]

pepbench/algorithms/outlier_correction.py

@@ -0,0 +1,9 @@
+"""Module for ICG outlier correction algorithms."""
+
+from biopsykit.signals.icg.outlier_correction import (
+    OutlierCorrectionDummy,
+    OutlierCorrectionForouzanfar2018,
+    OutlierCorrectionLinearInterpolation,
+)
+
+__all__ = ["OutlierCorrectionDummy", "OutlierCorrectionLinearInterpolation", "OutlierCorrectionForouzanfar2018"]

pepbench/data_handling/__init__.py

@@ -0,0 +1,33 @@
+"""Module for various data handling helper functions."""
+
+from pepbench.data_handling import utils
+from pepbench.data_handling._data_handling import (
+    add_unique_id_to_results_dataframe,
+    compute_improvement_outlier_correction,
+    compute_improvement_pipeline,
+    compute_pep_performance_metrics,
+    correlation_reference_pep_heart_rate,
+    describe_pep_values,
+    get_data_for_algo,
+    get_error_by_group,
+    get_pep_for_algo,
+    get_reference_data,
+    get_reference_pep,
+    rr_interval_to_heart_rate,
+)
+
+__all__ = [
+    "get_reference_pep",
+    "get_error_by_group",
+    "describe_pep_values",
+    "get_pep_for_algo",
+    "get_reference_data",
+    "get_data_for_algo",
+    "rr_interval_to_heart_rate",
+    "compute_pep_performance_metrics",
+    "correlation_reference_pep_heart_rate",
+    "utils",
+    "add_unique_id_to_results_dataframe",
+    "compute_improvement_outlier_correction",
+    "compute_improvement_pipeline",
+]

pepbench/data_handling/_data_handling.py

@@ -0,0 +1,388 @@
+from collections.abc import Sequence
+
+import numpy as np
+import pandas as pd
+import pingouin as pg
+
+from pepbench.utils._types import str_t
+
+__all__ = [
+    "get_error_by_group",
+    "get_reference_data",
+    "get_reference_pep",
+    "get_pep_for_algo",
+    "get_data_for_algo",
+    "describe_pep_values",
+    "compute_pep_performance_metrics",
+    "rr_interval_to_heart_rate",
+    "correlation_reference_pep_heart_rate",
+    "add_unique_id_to_results_dataframe",
+    "compute_improvement_outlier_correction",
+    "compute_improvement_pipeline",
+]
+
+
+_algo_levels = ["q_peak_algorithm", "b_point_algorithm", "outlier_correction_algorithm"]
+
+_pep_error_metric_map = {
+    "absolute_error_per_sample_ms": "Mean Absolute Error [ms]",
+    "error_per_sample_ms": "Mean Error [ms]",
+    "absolute_relative_error_per_sample_percent": "Mean Absolute Relative Error [%]",
+}
+_pep_number_map = {
+    "num_pep_valid": "Valid PEPs",
+    "num_pep_invalid": "Invalid PEPs",
+    "num_pep_total": "Total PEPs",
+}
+
+
+def get_reference_data(results_per_sample: pd.DataFrame) -> pd.DataFrame:
+    """Extract the reference data from the *results-per-sample* dataframe.
+
+    Parameters
+    ----------
+    results_per_sample : :class:`pandas.DataFrame`
+        The results-per-sample dataframe.
+
+    Returns
+    -------
+    :class:`pandas.DataFrame`
+        The reference data.
+
+    """
+    reference_pep = results_per_sample.xs("reference", level=-1, axis=1)
+    reference_pep = reference_pep.groupby(_algo_levels)
+    reference_pep = reference_pep.get_group(next(iter(reference_pep.groups))).droplevel(_algo_levels)
+
+    return reference_pep
+
+
+def get_reference_pep(results_per_sample: pd.DataFrame) -> pd.DataFrame:
+    """Extract the reference PEP values from the *results-per-sample* dataframe.
+
+    Parameters
+    ----------
+    results_per_sample : :class:`pandas.DataFrame`
+        The results-per-sample dataframe.
+
+    Returns
+    -------
+    :class:`pandas.DataFrame`
+        The reference PEP values.
+
+    """
+    return get_reference_data(results_per_sample)[["pep_ms"]]
+
+
+def get_data_for_algo(results_per_sample: pd.DataFrame, algo_combi: str_t) -> pd.DataFrame:
+    """Extract the data for a specific algorithm combination from the *results-per-sample* dataframe.
+
+    Parameters
+    ----------
+    results_per_sample : :class:`pandas.DataFrame`
+        The results-per-sample dataframe.
+    algo_combi : str or tuple of str
+        The algorithm combination for which the data should be extracted.
+
+    Returns
+    -------
+    :class:`pandas.DataFrame`
+        The data for the specified algorithm combination.
+
+    """
+    algo_levels = [s for s in results_per_sample.index.names if s in _algo_levels]
+    if isinstance(algo_combi, str):
+        algo_combi = (algo_combi,)
+    data = results_per_sample.xs(tuple(algo_combi), level=algo_levels)
+    return data
+
+
+def get_pep_for_algo(results_per_sample: pd.DataFrame, algo_combi: Sequence[str]) -> pd.DataFrame:
+    """Extract the PEP values for a specific algorithm combination from the *results-per-sample* dataframe.
+
+    Parameters
+    ----------
+    results_per_sample : :class:`pandas.DataFrame`
+        The results-per-sample dataframe.
+    algo_combi : str or tuple of str
+        The algorithm combination for which the PEP values should be extracted.
+
+    Returns
+    -------
+    :class:`pandas.DataFrame`
+        The PEP values for the specified algorithm combination.
+
+    """
+    pep = get_data_for_algo(results_per_sample, algo_combi)
+    pep = pep[[("pep_ms", "estimated")]].droplevel(level=-1, axis=1)
+
+    return pep
+
+
+def describe_pep_values(
+    data: pd.DataFrame, group_cols: str_t | None = None, metrics: Sequence[str] | None = None
+) -> pd.DataFrame:
+    """Compute the descriptive statistics for the PEP values using the :meth:`pandas.DataFrame.describe` method.
+
+    Parameters
+    ----------
+    data : :class:`pandas.DataFrame`
+        The PEP values.
+    group_cols : str or list of str, optional
+        The column(s) to group the data by, if any. Default: "phase".
+    metrics : list of str, optional
+        List of metrics to display from the descriptive statistics. Default: ["mean", "std", "min", "max"].
+
+    """
+    if group_cols is None:
+        group_cols = ["phase"]
+    if metrics is None:
+        metrics = ["mean", "std", "min", "max"]
+
+    return data.groupby(group_cols).describe().reindex(metrics, level=-1, axis=1)
+
+
+def compute_pep_performance_metrics(
+    results_per_sample: pd.DataFrame,
+    *,
+    num_heartbeats: pd.DataFrame | None = None,
+    metrics: Sequence[str] | None = None,
+    sortby: str_t | None = ("absolute_error_per_sample_ms", "mean"),
+    ascending: bool | None = True,
+) -> pd.DataFrame:
+    """Compute the performance metrics for the PEP values.
+
+    Parameters
+    ----------
+    results_per_sample : :class:`pandas.DataFrame`
+        The results-per-sample dataframe.
+    num_heartbeats : :class:`pandas.DataFrame`, optional
+        Dataframe containing the number of heartbeats (to include in the output). Default: None.
+    metrics : list of str, optional
+        List of metrics to compute. Default: ["mean", "std"].
+    sortby : str, optional
+        The column to sort the results by. Default: ("absolute_error_per_sample_ms", "mean").
+    ascending : bool, optional
+        Whether to sort the results in ascending order. Default: True.
+
+    """
+    if metrics is None:
+        metrics = ["mean", "std"]
+    results_per_sample = results_per_sample.copy()
+    algo_levels = [s for s in results_per_sample.index.names if s in _algo_levels]
+    results_per_sample = results_per_sample[_pep_error_metric_map.keys()].droplevel(level=-1, axis=1)
+    results_per_sample = results_per_sample.groupby(algo_levels)
+    results_per_sample = results_per_sample.agg(metrics)
+
+    num_heartbeats = num_heartbeats.unstack().swaplevel(axis=1)
+    results_per_sample = results_per_sample.join(num_heartbeats)
+
+    if sortby is not None:
+        results_per_sample = results_per_sample.sort_values(sortby, ascending=ascending)
+
+    rename_map = _pep_error_metric_map.copy()
+    rename_map.update(_pep_number_map)
+    results_per_sample = results_per_sample.rename(rename_map, level=0, axis=1)
+    results_per_sample = results_per_sample.reindex(rename_map.values(), level=0, axis=1)
+
+    return results_per_sample
+
+
+def get_performance_metric(results_per_sample: pd.DataFrame, metric: str) -> pd.DataFrame:
+    """Extract a specific performance metric from the *results-per-sample* dataframe.
+
+    Parameters
+    ----------
+    results_per_sample : :class:`pandas.DataFrame`
+        The results-per-sample dataframe.
+    metric : str
+
+    Returns
+    -------
+    :class:`pandas.DataFrame`
+        The extracted performance metric.
+
+    """
+    return results_per_sample[[metric]].droplevel(level=-1, axis=1)
+
+
+def rr_interval_to_heart_rate(data: pd.DataFrame) -> pd.DataFrame:
+    """Convert RR intervals in milliseconds to heart rate in beats per minute.
+
+    Parameters
+    ----------
+    data : :class:`pandas.DataFrame`
+        The data containing the RR intervals in milliseconds. The column name must be "rr_interval_ms".
+
+    Returns
+    -------
+    :class:`pandas.DataFrame`
+        The data with the heart rate in beats per minute
+
+    """
+    heart_rate_bpm = 60 * 1000 / data[["rr_interval_ms"]]
+    heart_rate_bpm = heart_rate_bpm.rename(columns={"rr_interval_ms": "heart_rate_bpm"})
+    return data.join(heart_rate_bpm)
+
+
+def correlation_reference_pep_heart_rate(data: pd.DataFrame) -> dict[str, pd.DataFrame]:
+    """Compute the correlation between the reference PEP values and the heart rate.
+
+    Parameters
+    ----------
+    data : :class:`pandas.DataFrame`
+        The data containing the reference PEP values and the heart rate.
+
+    Returns
+    -------
+    dict
+        A dictionary containing the linear regression model and the correlation coefficient.
+
+    """
+    data = get_reference_data(data)
+
+    # compute a linear regression model
+    linreg = pg.linear_regression(X=data["heart_rate_bpm"], y=data["pep_ms"], remove_na=True)
+    corr = pg.corr(data["heart_rate_bpm"], data["pep_ms"], method="pearson")
+
+    return {"linear_regression": linreg, "correlation": corr}
+
+
+def get_error_by_group(
+    results_per_sample: pd.DataFrame, error_metric: str = "absolute_error_per_sample_ms", grouper: str_t = "participant"
+) -> pd.DataFrame:
+    """Compute mean and standard deviation of the error metric by group.
+
+    Parameters
+    ----------
+    results_per_sample : :class:`pandas.DataFrame`
+        The results-per-sample dataframe.
+    error_metric : str, optional
+        The error metric to extract. Default: "absolute_error_per_sample_ms".
+    grouper : str or list of str, optional
+        The column(s) to group the data by. Default: "participant".
+
+    Returns
+    -------
+    :class:`pandas.DataFrame`
+        The error metric aggregated by group.
+
+    """
+    algo_levels = [s for s in results_per_sample.index.names if s in _algo_levels]
+    if isinstance(grouper, str):
+        grouper = [grouper]
+
+    error = results_per_sample[[error_metric]].groupby([*algo_levels, *grouper]).agg(["mean", "std"])
+    error = (
+        error.droplevel(1, axis=1)
+        .unstack(algo_levels)
+        .reorder_levels([0, *range(2, 2 + len(algo_levels)), 1], axis=1)
+        .sort_index(axis=1)
+    )
+    error.columns = error.columns.set_names("metric", level=0)
+    return error
+
+
+def add_unique_id_to_results_dataframe(data: pd.DataFrame, algo_levels: Sequence[str] | None = None) -> pd.DataFrame:
+    """Add a unique ID to the results dataframe.
+
+    The unique ID is created by concatenating the values of the specified algorithm levels and the heartbeat IDs.
+    This is then added as a new index level named "id_concat".
+
+    Parameters
+    ----------
+    data : :class:`pandas.DataFrame`
+        The results dataframe.
+    algo_levels : list of str, optional
+        The algorithm levels to use for the unique ID. If None, the default algorithm levels
+        (["q_peak_algorithm", "b_point_algorithm", "outlier_correction_algorithm"]) are used.
+
+    Returns
+    -------
+    :class:`pandas.DataFrame`
+        The results dataframe with the unique IDs added as new index level.
+
+    """
+    data = data.copy()
+    data = data.droplevel(axis=1, level=-1).rename(index=str)
+    if algo_levels is None:
+        algo_levels = _algo_levels
+    if isinstance(algo_levels, str):
+        algo_levels = [algo_levels]
+
+    algo_levels = [s for s in data.index.names if s in algo_levels]
+    data = data.reset_index(level=algo_levels)
+    id_concat = pd.Index(["_".join(i) for i in data.index], name="id_concat")
+    data = data.assign(id_concat=id_concat)
+    data = data.set_index([*algo_levels, "id_concat"])
+    return data
+
+
+def compute_improvement_outlier_correction(data: pd.DataFrame, outlier_algos: Sequence[str]) -> pd.DataFrame:
+    """Compute the percentage of samples which improved, deteriorated, or remained unchanged after outlier correction.
+
+    Parameters
+    ----------
+    data : :class:`pandas.DataFrame`
+        The data containing the PEP values before and after outlier correction.
+    outlier_algos : list of str
+        The outlier correction algorithms to consider.
+
+    Returns
+    -------
+    :class:`pandas.DataFrame`
+        The percentage of samples which improved, deteriorated, or remained unchanged after outlier correction.
+
+    """
+    data = data.copy()
+    if "outlier_correction_algorithm" not in data.columns.names:
+        data = data.unstack("outlier_correction_algorithm")
+    data = data.reindex(outlier_algos, axis=1, level="outlier_correction_algorithm")
+    data = data.diff(axis=1).dropna(how="all", axis=1)
+    data = np.sign(data)
+    data.columns = ["improvement_percent"]
+    # negative values = improvement through outlier correction
+    # count the number of positive and negative values
+    improvement_percent = data.value_counts(normalize=True) * 100
+    improvement_percent = improvement_percent.rename({-1: "improvement", 1: "deterioration", 0: "no change"})
+    improvement_percent = improvement_percent.to_frame().reindex(["improvement", "no change", "deterioration"], level=0)
+    improvement_percent.columns = ["improvement_percent"]
+    improvement_percent.index.names = [None]
+    improvement_percent = improvement_percent.T
+    return improvement_percent
+
+
+def compute_improvement_pipeline(data: pd.DataFrame, pipelines: Sequence[str]) -> pd.DataFrame:
+    """Compute the percentage of samples which showed sign changes in the error metric between two pipelines.
+
+    Parameters
+    ----------
+    data : :class:`pandas.DataFrame`
+        The data containing the PEP extraction results from different pipelines.
+    pipelines : list of str
+        The pipelines to compare.
+
+    Returns
+    -------
+    :class:`pandas.DataFrame`
+        Overview of the percentage of samples which showed a change in the sign of the error metric
+        (i.e., either positive to negative, vice versa, or no change) between two pipelines.
+
+    """
+    data = data.copy()
+    pipelines = ["_".join(i) for i in pipelines]
+
+    data = data.unstack("pipeline").reindex(pipelines, level="pipeline", axis=1)
+    # compute the percentage of sample which have a positive value in the first column
+    # and a negative value in the second column
+    data = data.assign(change_pos_neg=(data.iloc[:, 0] > 0) & (data.iloc[:, 1] < 0))
+    data = data.assign(change_pos_pos=(data.iloc[:, 0] > 0) & (data.iloc[:, 1] > 0))
+    data = data.assign(change_neg_pos=(data.iloc[:, 0] < 0) & (data.iloc[:, 1] > 0))
+    data = data.assign(change_neg_neg=(data.iloc[:, 0] < 0) & (data.iloc[:, 1] < 0))
+    data = data.assign(change_diff=data["change_pos_neg"] | data["change_neg_pos"])
+    data = data.assign(change_same=data["change_pos_pos"] | data["change_neg_neg"])
+
+    data = data.filter(like="change", axis=1)
+    data = data.apply(pd.Series.value_counts, normalize=True) * 100
+
+    return data

pepbench/data_handling/utils.py

@@ -0,0 +1,116 @@
+"""Utility functions for data handling."""
+
+import pandas as pd
+
+__all__ = ["reindex_empkins", "rename_empkins", "reindex_guardian", "rename_guardian"]
+
+condition_mapping_empkins = {"tsst": "TSST", "ftsst": "f-TSST"}
+phase_mapping_empkins = {
+    "Prep": "Preparation",
+    "Pause_1": "Pause 1",
+    "Talk": "Talk",
+    "Math": "Math",
+    "Pause_5": "Pause 5",
+}
+phase_mapping_guardian = {
+    "Pause": "Pause",
+    "Valsalva": "Valsalva",
+    "HoldingBreath": "Apnea",
+    "TiltUp": "Tilt-Up",
+    "TiltDown": "Tilt-Down",
+}
+
+
+def reindex_empkins(data: pd.DataFrame, after_rename: bool = False) -> pd.DataFrame:
+    """Reindex data from the *EmpkinSDataset*.
+
+    The reindexing is performed according to the condition (tsst, ftsst) and phase (Prep, Pause_1, Talk, Math, Pause_5)
+    mappings. The reindexing can be performed *before* or *after* the data has been renamed
+    (using :func:`rename_empkins`).
+
+    Parameters
+    ----------
+    data : :class:`pandas.DataFrame`
+        Data from the *EmpkinSDataset*.
+    after_rename : bool, optional
+        ``True`` if the data has already been renamed using :func:`rename_empkins`, ``False`` otherwise.
+        Default: ``False``
+
+    Returns
+    -------
+    :class:`pandas.DataFrame`
+        Reindexed data from the *EmpkinSDataset*.
+
+    """
+    if after_rename:
+        return data.reindex(condition_mapping_empkins.values(), level="condition").reindex(
+            phase_mapping_empkins.values(), level="phase"
+        )
+    return data.reindex(condition_mapping_empkins.keys(), level="condition").reindex(
+        phase_mapping_empkins.keys(), level="phase"
+    )
+
+
+def rename_empkins(data: pd.DataFrame) -> pd.DataFrame:
+    """Rename the data from the *EmpkinSDataset*.
+
+    The renaming is performed according to the condition (tsst -> TSST, ftsst -> f-TSST) and phase
+    (Prep -> Preparation, Pause_1 -> Pause 1, Talk -> Talk, Math -> Math, Pause_5 -> Pause 5) mappings.
+
+    Parameters
+    ----------
+    data : :class:`pandas.DataFrame`
+        Data from the *EmpkinSDataset*.
+
+    Returns
+    -------
+    :class:`pandas.DataFrame`
+        Renamed data from the *EmpkinSDataset*.
+
+    """
+    return data.rename(condition_mapping_empkins, level="condition").rename(phase_mapping_empkins, level="phase")
+
+
+def reindex_guardian(data: pd.DataFrame, after_rename: bool | None = False) -> pd.DataFrame:
+    """Reindex data from the *GuardianDataset*.
+
+    The reindexing is performed according to the phase (Pause, Valsalva, HoldingBreath, TiltUp, TiltDown) mappings.
+    The reindexing can be performed *before* or *after* the data has been renamed (using :func:`rename_guardian`).
+
+    Parameters
+    ----------
+    data : :class:`pandas.DataFrame`
+        Data from the *GuardianDataset*.
+    after_rename : bool, optional
+        ``True`` if the data has already been renamed using :func:`rename_guardian`, ``False`` otherwise.
+        Default: ``False``
+
+    Returns
+    -------
+    :class:`pandas.DataFrame`
+        Reindexed data from the *GuardianDataset*.
+
+    """
+    if after_rename:
+        return data.reindex(phase_mapping_guardian.values(), level="phase")
+    return data.reindex(phase_mapping_guardian.keys(), level="phase")
+
+
+def rename_guardian(data: pd.DataFrame) -> pd.DataFrame:
+    """Rename the data from the *GuardianDataset*.
+
+    The renaming is performed according to the phase (Pause -> Pause, Valsalva -> Valsalva, HoldingBreath -> Apnea,
+    TiltUp -> Tilt-Up, TiltDown -> Tilt-Down) mappings.
+
+    Parameters
+    ----------
+    data : :class:`pandas.DataFrame`
+        Data from the *GuardianDataset*.
+
+    Returns
+    -------
+    :class:`pandas.DataFrame`
+        Renamed data from the *GuardianDataset*.
+
+    """
+    return data.rename(phase_mapping_guardian, level="phase")