MobGap

https://mobgap.readthedocs.io/en/stable/
Admin
MobGap is a Python implementation of the Mobilise-D algorithm pipeline for gait analysis using IMU...
Tokens:674,063
Snippets:6,618
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Setup Python Environment with uv

Source: https://mobgap.readthedocs.io/en/stable/_sources/guides/developer_guide.md.txt

Install uv and then use it to pin a Python version and sync dependencies. This creates a virtual environment with Python 3.11 and installs all dependencies from pyproject.toml.

```bash
uv python pin 3.11
uv sync
```

--------------------------------

### Setup Python Environment with uv

Source: https://mobgap.readthedocs.io/en/stable/guides/developer_guide.html

Installs Python 3.11 and all project dependencies using uv. Rerun with a different version for alternative Python testing.

```bash
uv python pin 3.11
uv sync

```

--------------------------------

### Load Example Data and Calculate GSD

Source: https://mobgap.readthedocs.io/en/stable/auto_examples/gait_sequences/_03_gsd_evaluation.html

Loads example dataset, applies the GsdIluz algorithm, and retrieves reference gait sequences. Ensure the 'mobgap' library is installed.

```python
import pandas as pd
from mobgap.data import LabExampleDataset
from mobgap.gait_sequences import GsdIluz
from mobgap.utils.conversions import to_body_frame

def load_data():
    lab_example_data = LabExampleDataset(reference_system="INDIP")
    single_test = lab_example_data.get_subset(
        cohort="MS", participant_id="001", test="Test11", trial="Trial1"
    )
    return single_test

def calculate_gsd_iluz_output(single_test_data):
    """Calculate the GSD Iluz output for one sensor from the test data."""
    det_gsd = (
        GsdIluz()
        .detect(
            to_body_frame(single_test_data.data_ss),
            sampling_rate_hz=single_test_data.sampling_rate_hz,
        )
        .gs_list_
    )
    return det_gsd

def load_reference(single_test_data):
    """Load the reference gait sequences from the test data."""
    ref_gsd = single_test_data.reference_parameters_.wb_list
    return ref_gsd

test_data = load_data()
detected_gsd_list = calculate_gsd_iluz_output(test_data)
reference_gsd_list = load_reference(test_data)
```

--------------------------------

### Example Data Load Functions

Source: https://mobgap.readthedocs.io/en/stable/modules/data.html

Functions for retrieving paths to example data.

```APIDOC
## get_all_lab_example_data_paths

### Description
Get the paths to all lab example data.

### Function Signature
`get_all_lab_example_data_paths()`
```

--------------------------------

### Get All Lab Example Data Paths

Source: https://mobgap.readthedocs.io/en/stable/_sources/modules/data.rst.txt

Retrieves the file paths for all available lab example datasets. This is helpful for accessing sample data for testing or demonstration purposes.

```APIDOC
## get_all_lab_example_data_paths

### Description
Retrieves the file paths for all available lab example datasets.

### Parameters
This function does not explicitly list parameters in the source documentation.
```

--------------------------------

### Load Example Data

Source: https://mobgap.readthedocs.io/en/stable/_downloads/ce729bd3ba1e25d822e2174042b69c4a/_01_sl_zijlstra.ipynb

Loads example data from the LabExampleDataset, specifically for a single short-trial from the 'HA' participant.

```python
from mobgap.data import LabExampleDataset

lab_example_data = LabExampleDataset(reference_system="INDIP")
short_trial = lab_example_data.get_subset(
    cohort="HA", participant_id="001", test="Test5", trial="Trial2"
)
```

--------------------------------

### Load and Prepare Example Data

Source: https://mobgap.readthedocs.io/en/stable/_downloads/40babb30e122f9b54343a85b89d4ca90/_01_lrc_mccamley.ipynb

Loads example data from the LabExampleDataset, transforms it to body frame coordinates, and extracts initial contact information and reference gait sequences.

```python
from mobgap.utils.conversions import to_body_frame

example_data = LabExampleDataset(
    reference_system="INDIP", reference_para_level="wb"
)
single_test = example_data.get_subset(
    cohort="MS", participant_id="001", test="Test11", trial="Trial1"
)

imu_data = to_body_frame(single_test.data_ss)
reference_wbs = single_test.reference_parameters_.wb_list

sampling_rate_hz = single_test.sampling_rate_hz
ref_ics = single_test.reference_parameters_.ic_list
ref_ics_rel_to_gs = single_test.reference_parameters_relative_to_wb_.ic_list

reference_wbs
```

--------------------------------

### Load and Prepare Example Data

Source: https://mobgap.readthedocs.io/en/stable/_downloads/414901e2102a6c02096c63f7566afd6d/_02_step_by_step_mobilised_pipeline.ipynb

Loads example IMU data from the LabExampleDataset and converts it to the body frame. Ensures data is aligned with sensor frame conventions before processing.

```python
import pandas as pd
from mobgap.data import LabExampleDataset
from mobgap.utils.conversions import to_body_frame
from mobgap.utils.interpolation import naive_sec_paras_to_regions

lab_example_data = LabExampleDataset(reference_system="INDIP")
long_trial = lab_example_data.get_subset(
    cohort="MS", participant_id="001", test="Test11", trial="Trial1"
)
imu_data = to_body_frame(long_trial.data_ss)
sampling_rate_hz = long_trial.sampling_rate_hz
participant_metadata = long_trial.participant_metadata
```

--------------------------------

### Load Example Dataset and Datapoint

Source: https://mobgap.readthedocs.io/en/stable/_downloads/4ab1e8a1c378dd789cf0bc1914e7372e/_02_working_with_ref_data.ipynb

Loads an example dataset and extracts a specific datapoint. This is the initial step to access reference data.

```python
from mobgap.data import LabExampleDataset

dataset = LabExampleDataset(reference_system="INDIP")
datapoint = dataset.get_subset(
    cohort="HA", participant_id="001", test="Test11", trial="Trial1"
)
data = datapoint.data_ss
data
```

--------------------------------

### Load Lab Example Dataset with Reference System

Source: https://mobgap.readthedocs.io/en/stable/_downloads/300ef7e51b922ef93adcd56710bf8046/_01_loading_example_data.ipynb

Load an example dataset specifying a reference system. Access raw reference parameters for walking and level-walking bouts.

```python
example_data_with_reference = LabExampleDataset(reference_system="Stereophoto")
single_trial_with_reference = example_data_with_reference.get_subset(
    cohort="HA", participant_id="002", test="Test5", trial="Trial2"
)
single_trial_with_reference.raw_reference_parameters_
```

--------------------------------

### Load Example Dataset

Source: https://mobgap.readthedocs.io/en/stable/auto_examples/gait_sequences/_04_gsd_evaluation_challenges.html

Loads the example dataset for GSD evaluation. Ensure the reference system is correctly specified.

```python
from mobgap.data import LabExampleDataset

long_test = LabExampleDataset(reference_system="INDIP").get_subset(
    test="Test11"
)

```

--------------------------------

### Setup Performance Metrics and Formatting

Source: https://mobgap.readthedocs.io/en/stable/_downloads/abde3688a61166ab0f76e06cdf9a6f15/_01_lrc_analysis.ipynb

Defines custom aggregations, format transformations, and final column names for performance metrics. Use this setup to prepare data for analysis and reporting.

```python
from functools import partial

from mobgap.pipeline.evaluation import CustomErrorAggregations as A
from mobgap.utils.df_operations import (
    CustomOperation,
    apply_aggregations,
    apply_transformations,
)
from mobgap.utils.tables import FormatTransformer as F
from mobgap.utils.tables import RevalidationInfo, revalidation_table_styles

custom_aggs = [
    CustomOperation(
        identifier=None,
        function=A.n_datapoints,
        column_name=[("n_datapoints", "all")],
    ),
    ("accuracy", ["mean", A.conf_intervals]),
    ("accuracy_pairwise", ["mean", A.conf_intervals]),
]

format_transforms = [
    CustomOperation(
        identifier=None,
        function=lambda df_: df_[("n_datapoints", "all")].astype(int),
        column_name="n_datapoints",
    ),
    CustomOperation(
        identifier=None,
        function=partial(
            F.value_with_metadata,
            value_col=("mean", "accuracy"),
            other_columns={"range": ("conf_intervals", "accuracy")},
        ),
        column_name="accuracy",
    ),
    CustomOperation(
        identifier=None,
        function=partial(
            F.value_with_metadata,
            value_col=("mean", "accuracy_pairwise"),
            other_columns={"range": ("conf_intervals", "accuracy_pairwise")},
        ),
        column_name="accuracy_pairwise",
    ),
]


final_names = {
    "n_datapoints": "# participants",
    "accuracy": "Accuracy",
    "accuracy_pairwise": "Accuracy IC-pairs",
}

validation_thresholds = {
    "Accuracy": RevalidationInfo(threshold=0.7, higher_is_better=True),
}


def format_tables(df: pd.DataFrame) -> pd.DataFrame:
    return (
        df.pipe(apply_transformations, format_transforms)
        .rename(columns=final_names)
        .loc[:, list(final_names.values())]
    )
```

--------------------------------

### Load Example Data

Source: https://mobgap.readthedocs.io/en/stable/_downloads/717d48e84a883fd6d02c1de6959b124c/_01_cad_from_ic.ipynb

Loads example data from the lab dataset, specifically a short trial for analysis.

```python
from mobgap.data import LabExampleDataset

lab_example_data = LabExampleDataset(reference_system="INDIP")
short_trial: LabExampleDataset = lab_example_data.get_subset(
    cohort="HA", participant_id="001", test="Test5", trial="Trial2"
)
```

--------------------------------

### Load example data

Source: https://mobgap.readthedocs.io/en/stable/auto_examples/initial_contacts/_04_icd_evaluation.html

Loads a subset of example data from LabExampleDataset, specifically for a single participant and trial, for demonstration purposes.

```python
def load_data():
    """Load example data and extract a single trial for demonstration purposes."""
    example_data = LabExampleDataset(
        reference_system="INDIP", reference_para_level="wb"
    )
    single_test = example_data.get_subset(
        cohort="HA", participant_id="001", test="Test11", trial="Trial1"
    )
    return single_test
```

--------------------------------

### Loading Example Data and MATLAB Output

Source: https://mobgap.readthedocs.io/en/stable/_downloads/e58d68d95f8642a0fb003d7003ea2b51/_02_gsd_ionescu.ipynb

Loads example data from the LabExampleDataset and a helper function to load original MATLAB results for the adaptive GSD algorithm.

```python
from mobgap.data import LabExampleDataset

lab_example_data = LabExampleDataset(reference_system="INDIP")


def load_matlab_output(datapoint):
    p = datapoint.group_label
    with (
        PROJECT_ROOT
        / f"example_data/original_results/gsd_adaptive_ionescu/lab/{p.cohort}/{p.participant_id}/GSDB_Output.json"
    ).open() as f:
        original_results = json.load(f)["GSDB_Output"][p.time_measure][p.test][
            p.trial
        ]["SU"]["LowerBack"]["GSD"]

    if not isinstance(original_results, list):
        original_results = [original_results]
    return (
        (
            pd.DataFrame.from_records(original_results).rename(
                {"Start": "start", "End": "end"}, axis=1
            )[["start", "end"]]
            * datapoint.sampling_rate_hz
        )
        .round()
        .astype("int64")
    )
```

--------------------------------

### Load Example Data

Source: https://mobgap.readthedocs.io/en/stable/_sources/auto_examples/laterality/_02_lrc_ullrich.rst.txt

Loads example data from the LabExampleDataset, including IMU data and reference parameters. Ensures data is in body frame coordinates.

```Python
from mobgap.data import LabExampleDataset
from mobgap.utils.conversions import to_body_frame

example_data = LabExampleDataset(
    reference_system="INDIP", reference_para_level="wb"
)
single_test = example_data.get_subset(
    cohort="MS", participant_id="001", test="Test11", trial="Trial1"
)

imu_data = to_body_frame(single_test.data_ss)
reference_wbs = single_test.reference_parameters_.wb_list

sampling_rate_hz = single_test.sampling_rate_hz
ref_ics = single_test.reference_parameters_.ic_list
ref_ics_rel_to_gs = single_test.reference_parameters_relative_to_wb_.ic_list
```

--------------------------------

### Load Example Data

Source: https://mobgap.readthedocs.io/en/stable/auto_examples/cadence/_01_cad_from_ic.html

Loads example data from the lab dataset, specifically a short trial from participant 'HA' for the 'INDIP' reference system. This data is used for cadence algorithm demonstrations.

```python
from mobgap.data import LabExampleDataset

lab_example_data = LabExampleDataset(reference_system="INDIP")
short_trial: LabExampleDataset = lab_example_data.get_subset(
    cohort="HA", participant_id="001", test="Test5", trial="Trial2"
)

```

--------------------------------

### Load example data and reference values

Source: https://mobgap.readthedocs.io/en/stable/_downloads/cb423c1a7a70cab7d05def11fe82b936/_02_cad_evaluation.ipynb

Loads example data from the lab dataset for a specific participant and trial, and extracts reference gait sequences and initial contacts.

```python
def load_data():
    """Load example data from the lab dataset."""
    lab_example_data = LabExampleDataset(reference_system="INDIP")
    long_trial = lab_example_data.get_subset(
        cohort="MS", participant_id="001", test="Test11", trial="Trial1"
    )
    sampling_rate_hz = long_trial.sampling_rate_hz
    return long_trial, sampling_rate_hz


def load_reference(data):
    """Load reference from the INDIP reference system."""
    reference_gs = data.reference_parameters_.wb_list
    reference_ic = data.reference_parameters_relative_to_wb_.ic_list
    return reference_gs, reference_ic


test_data, sampling_rate_hz = load_data()
reference_gs, reference_ic = load_reference(test_data)
```

--------------------------------

### Load Example Dataset and Preprocess Data

Source: https://mobgap.readthedocs.io/en/stable/auto_examples/laterality/_01_lrc_mccamley.html

Loads the lab example dataset and transforms IMU data to body frame coordinates. This is a prerequisite for applying most MoBaGait algorithms.

```python
from mobgap.data import LabExampleDataset
from mobgap.utils.conversions import to_body_frame

example_data = LabExampleDataset(
    reference_system="INDIP", reference_para_level="wb"
)
single_test = example_data.get_subset(
    cohort="MS", participant_id="001", test="Test11", trial="Trial1"
)

imu_data = to_body_frame(single_test.data_ss)
reference_wbs = single_test.reference_parameters_.wb_list

sampling_rate_hz = single_test.sampling_rate_hz
ref_ics = single_test.reference_parameters_.ic_list
ref_ics_rel_to_gs = single_test.reference_parameters_relative_to_wb_.ic_list

reference_wbs
```

--------------------------------

### Load Example Data and Reference

Source: https://mobgap.readthedocs.io/en/stable/_sources/auto_examples/cadence/_02_cad_evaluation.rst.txt

Loads example data from the lab dataset, including participant data and reference initial contacts. This is used to prepare data for cadence evaluation.

```python
from pprint import pprint

import numpy as np
import pandas as pd
from mobgap.data import LabExampleDataset
```

```python
def load_data():
    """Load example data from the lab dataset."""
    lab_example_data = LabExampleDataset(reference_system="INDIP")
    long_trial = lab_example_data.get_subset(
        cohort="MS", participant_id="001", test="Test11", trial="Trial1"
    )
    sampling_rate_hz = long_trial.sampling_rate_hz
    return long_trial, sampling_rate_hz


def load_reference(data):
    """Load reference from the INDIP reference system."""
    reference_gs = data.reference_parameters_.wb_list
    reference_ic = data.reference_parameters_relative_to_wb_.ic_list
    return reference_gs, reference_ic


test_data, sampling_rate_hz = load_data()
reference_gs, reference_ic = load_reference(test_data)
```

--------------------------------

### Loading Example Data and MATLAB Output

Source: https://mobgap.readthedocs.io/en/stable/auto_examples/gait_sequences/_02_gsd_ionescu.html

Loads example data from the lab dataset with the INDIP reference system and defines a function to load original MATLAB results for the adaptive GSD algorithm.

```python
from mobgap.data import LabExampleDataset

lab_example_data = LabExampleDataset(reference_system="INDIP")


def load_matlab_output(datapoint):
    p = datapoint.group_label
    with (
        PROJECT_ROOT
        / f"example_data/original_results/gsd_adaptive_ionescu/lab/{p.cohort}/{p.participant_id}/GSDB_Output.json"
    ).open() as f:
        original_results = json.load(f)["GSDB_Output"][p.cohort][p.participant_id][p.time_measure][p.test][
            p.trial
        ]["SU"]["LowerBack"]["GSD"]

    if not isinstance(original_results, list):
        original_results = [original_results]
    return (
        (
            pd.DataFrame.from_records(original_results).rename(
                {"Start": "start", "End": "end"}, axis=1
            )[["start", "end"]]
            * datapoint.sampling_rate_hz
        )
        .round()
        .astype("int64")
    )

```

--------------------------------

### Access Healthy Example IMU Data

Source: https://mobgap.readthedocs.io/en/stable/_sources/guides/developer_guide.md.txt

Import and use this function to get healthy example IMU data within scripts or examples.

```python
from mobgap.example_data import get_healthy_example_imu_data
```

--------------------------------

### Preview Documentation

Source: https://mobgap.readthedocs.io/en/stable/guides/developer_guide.html

Builds and opens the project's HTML documentation in a browser. Displays a URL in the terminal for access.

```bash
uv run poe docs_preview

```

--------------------------------

### Preview Documentation

Source: https://mobgap.readthedocs.io/en/stable/_sources/guides/developer_guide.md.txt

After building, use this command to preview the documentation. A URL will be displayed in the terminal to open in a browser.

```bash
uv run poe docs_preview
```

--------------------------------

### Setup Evaluation Pipeline and Run

Source: https://mobgap.readthedocs.io/en/stable/auto_revalidation/laterality/_02_lrc_result_generation_no_exc.html

Initializes the Evaluation class with a dataset and scoring function, then runs the evaluation pipeline. This is a foundational step for any evaluation process.

```python
import matplotlib.pyplot as plt
import pandas as pd
import seaborn as sns
from joblib import Parallel, delayed
from mobgap.laterality.evaluation import lrc_score
from mobgap.utils.evaluation import Evaluation

n_jobs = int(get_env_var("MOBGAP_N_JOBS", 3))
results_base_path =
    (Path(get_env_var("MOBGAP_VALIDATION_DATA_PATH"))) / "results/lrc"


def run_evaluation(name, pipeline, ds):
    eval_pipe = Evaluation(
        ds,
        scoring=lrc_score,
    ).run(pipeline)
    return name, eval_pipe

```

--------------------------------

### Get Example CSV Data Path

Source: https://mobgap.readthedocs.io/en/stable/_downloads/80aa48cc5ac60dda0ee3e3b6f4b2a71b/_05_custom_datasets.ipynb

Retrieves the path to example CSV data included with the Mobgap package. This is useful for understanding the expected data structure and for testing.

```python
from mobgap.data import get_example_csv_data_path

path = get_example_csv_data_path()
all_data_files = sorted(list(path.rglob("*.csv")))
all_data_files
```

--------------------------------

### Load and prepare example data

Source: https://mobgap.readthedocs.io/en/stable/_sources/auto_examples/data_transform/_06_savgol_filter.rst.txt

Loads a subset of the LabExampleDataset and selects a specific trial's accelerometer and gyroscope data.

```Python
example_data = LabExampleDataset()
ha_example_data = example_data.get_subset(cohort="HA")
single_test = ha_example_data.get_subset(
    participant_id="002", test="Test5", trial="Trial2"
)
data = single_test.data_ss
```

--------------------------------

### Get Challenge Runtime Information

Source: https://mobgap.readthedocs.io/en/stable/_downloads/288b12f843e3a94b26dfc7480dad37a0/_04_gsd_evaluation_challenges.ipynb

Retrieves the start and end datetimes of the challenge evaluation.

```python
eval_challenge.perf_["start_datetime"], eval_challenge.perf_["end_datetime"]
```

--------------------------------

### Build Documentation

Source: https://mobgap.readthedocs.io/en/stable/_sources/guides/developer_guide.md.txt

Execute this command to build the project's HTML documentation using Sphinx.

```bash
uv run poe docs
```

--------------------------------

### Get All Lab Example Data Paths

Source: https://mobgap.readthedocs.io/en/stable/_downloads/300ef7e51b922ef93adcd56710bf8046/_01_loading_example_data.ipynb

Retrieve all available lab example data paths using the get_all_lab_example_data_paths function. This function returns a dictionary mapping cohort and participant IDs to their respective data paths.

```python
from mobgap.data import (
    get_all_lab_example_data_paths,
    load_mobilised_matlab_format,
)

all_example_data_paths = get_all_lab_example_data_paths()
list(all_example_data_paths.keys())
```

--------------------------------

### Setup and Evaluation Functions

Source: https://mobgap.readthedocs.io/en/stable/_downloads/463c3038784878d43846b029407a19d3/_02_sl_result_generation_no_exc.ipynb

Imports necessary libraries and defines helper functions for running and visualizing evaluations. This includes setting up parallel processing and defining a function to plot evaluation results.

```python
import seaborn as sns
from mobgap.utils.evaluation import Evaluation

n_jobs = int(get_env_var("MOBGAP_N_JOBS", 3))
results_base_path = (
    Path(get_env_var("MOBGAP_VALIDATION_DATA_PATH")) / "results/sl"
)


def run_evaluation(name, pipeline, ds):
    eval_pipe = Evaluation(
        ds,
        scoring=sl_score,
    ).run(pipeline)
    return name, eval_pipe


def eval_debug_plot(
    results: dict[str, Evaluation[SlEmulationPipeline]],
) -> None:
    results_df_wb = (
        pd.concat(
            {
                k: v.get_raw_results()["wb_level_values_with_errors"]
                for k, v in results.items()
            }
        )
        .reset_index()
        .rename(columns={"level_0": "algo_name"})
    )
    results_df_measurement = (
        pd.concat({k: v.get_single_results_as_df() for k, v in results.items()})
        .filter(like="wb__")
        .rename(columns=lambda x: x.strip("wb__"))
        .reset_index()
        .rename(columns={"level_0": "algo_name"})
    )

    metrics = [
        "error",
        "abs_error",
        "abs_rel_error",
    ]
    results = [
        ("wb_level", results_df_wb),
        ("measurement_level", results_df_measurement),
    ]
    combinations = [(n, c, m) for n, c in results for m in metrics]
    fig, axes = plt.subplots(2, 3, figsize=(12, 6))

    for ax, (n, c, m) in zip(axes.flatten(), combinations):
        sns.boxplot(
            data=c,
            x="cohort",
            y=m,
            hue="algo_name",
            ax=ax,
            showmeans=True,
        )
        ax.set_title(f"{m} {n}")

    plt.tight_layout()
    plt.show()
```

--------------------------------

### Access Aggregated Results

Source: https://mobgap.readthedocs.io/en/stable/_downloads/4ab1e8a1c378dd789cf0bc1914e7372e/_02_working_with_ref_data.ipynb

Access the aggregated results after iterating. This example shows how to retrieve the `ic_list` which contains transformed initial contacts relative to the recording start.

```python
gs_iterator.results_.ic_list
```

--------------------------------

### Get Reference Gait Sequence

Source: https://mobgap.readthedocs.io/en/stable/_sources/auto_examples/cadence/_01_cad_from_ic.rst.txt

Extracts the reference gait sequence parameters from the trial data. This is used to identify the start and end points of a gait sequence for further analysis.

```Python
reference_gs = short_trial.reference_parameters_relative_to_wb_.wb_list
reference_gs
```

--------------------------------

### Setup Export Directory

Source: https://mobgap.readthedocs.io/en/stable/_downloads/cd7ebbe2ca85bd495444df1305644985/_99_cvs_agg_pipeline_no_exc.ipynb

Prepares the output directory for exporting data. It creates a timestamped directory based on the current date to organize exported files.

```python
from datetime import datetime

current_date = datetime.now().strftime("%Y_%m_%d")

outdir = Path(path_config["outpath"]) / f"export_{current_date}"
outdir.mkdir(exist_ok=True, parents=True)
```

--------------------------------

### Load Example DMO Data

Source: https://mobgap.readthedocs.io/en/stable/auto_examples/pipeline/_03_dmo_evaluation_on_wb_level.html

Loads detected and reference DMO data from CSV files. The data is indexed by visit type, participant ID, measurement date, and WB ID. Ensure the data has 'start' and 'end' columns representing WB boundaries in samples.

```python
from pprint import pprint

import numpy as np
import pandas as pd
from mobgap import PROJECT_ROOT

DATA_PATH = PROJECT_ROOT / "example_data/dmo_data/dummy_dmo_data"

detected_dmo = pd.read_csv(DATA_PATH / "detected_dmo_data.csv").set_index(
    ["visit_type", "participant_id", "measurement_date", "wb_id"]
)

reference_dmo = pd.read_csv(DATA_PATH / "reference_dmo_data.csv").set_index(
    ["visit_type", "participant_id", "measurement_date", "wb_id"]
)

```

--------------------------------

### Access Example IMU Data

Source: https://mobgap.readthedocs.io/en/stable/guides/developer_guide.html

Imports a function to retrieve example IMU data. This is useful for testing and examples.

```python
from mobgap.example_data import get_healthy_example_imu_data


```

--------------------------------

### Load and prepare example data

Source: https://mobgap.readthedocs.io/en/stable/_downloads/e9dc439ef9aa9abfefbdcc8b07fc5e0b/_03_hklee_algo.ipynb

Loads example lab data, extracts a specific trial, transforms it to body frame coordinates, and retrieves reference parameters. The data is prepared for algorithm application.

```python
example_data = LabExampleDataset(
    reference_system="INDIP", reference_para_level="wb"
)

single_test = example_data.get_subset(
    cohort="HA", participant_id="001", test="Test11", trial="Trial1"
)
imu_data = to_body_frame(single_test.data_ss)
reference_wbs = single_test.reference_parameters_.wb_list

sampling_rate_hz = single_test.sampling_rate_hz
ref_ics = single_test.reference_parameters_.ic_list

reference_wbs
```

--------------------------------

### Install MobGap using pip

Source: https://mobgap.readthedocs.io/en/stable/README.html

Install the MobGap package using pip. Ensure you have a supported Python version (3.9 or higher) installed.

```bash
pip install mobgap

```

--------------------------------

### Install MobGap Locally from Cloned Repository

Source: https://mobgap.readthedocs.io/en/stable/_sources/README.md.txt

Clone the MobGap repository and install it locally using pip. This method is recommended if you encounter installation issues or want to contribute to the project.

```bash
git clone https://github.com/mobilise-d/mobgap.git
cd mobgap
pip install .
```

--------------------------------

### Setup Stride Length Emulation Pipelines

Source: https://mobgap.readthedocs.io/en/stable/auto_revalidation/stride_length/_02_sl_result_generation_no_exc.html

Configure and instantiate `SlEmulationPipeline` for different stride length algorithms. This setup is used to identify algorithms and store results in designated folders. Ensure environment variables for data paths are correctly set.

```python
from mobgap.utils.misc import get_env_var
from pathlib import Path

from mobgap.algorithms.stride_length import SlEmulationPipeline, DummySlAlgo, SlZijlstra


matlab_algo_result_path = (
    Path(get_env_var("MOBGAP_VALIDATION_DATA_PATH")) / "_extracted_results/sl"
)

pipelines = {}
for matlab_algo_name in [
    "zjilsV3__MS_ALL",
    "zjilsV3__MS_MS",
]:
    pipelines[f"matlab_{matlab_algo_name}"] = SlEmulationPipeline(
        DummySlAlgo(
            matlab_algo_name, base_result_folder=matlab_algo_result_path
        )
    )
pipelines["SlZjilstra__MS_ALL"] = SlEmulationPipeline(
    SlZijlstra(
        **SlZijlstra.PredefinedParameters.step_length_scaling_factor_ms_all
    )
)
pipelines["SlZjilstra__MS_MS"] = SlEmulationPipeline(
    SlZijlstra(
        **SlZijlstra.PredefinedParameters.step_length_scaling_factor_ms_ms
    )
)

```

--------------------------------

### Install MobGap from Source using pip

Source: https://mobgap.readthedocs.io/en/stable/README.html

Install the latest unreleased version of MobGap directly from its GitHub repository using pip. This command upgrades the installation if MobGap is already present.

```bash
pip install "git+https://github.com/mobilise-d/mobgap.git" --upgrade

```

--------------------------------

### Setup GsdEmulationPipeline with Dummy Algorithms

Source: https://mobgap.readthedocs.io/en/stable/_downloads/8fb7b9d4bd80168a56de1a48347bc9ee/_02_gsd_result_generation_no_exc.ipynb

Initializes GsdEmulationPipeline instances for various MATLAB algorithms using DummyGsdAlgo. Requires environment variables for data paths.

```python
from pathlib import Path

from mobgap.gait_sequences.pipeline import GsdEmulationPipeline
from mobgap.utils.misc import get_env_var

matlab_algo_result_path = (
    Path(get_env_var("MOBGAP_VALIDATION_DATA_PATH")) / "_extracted_results/gsd"
)

pipelines = {}
for matlab_algo_name in [
    "EPFL_V1-improved_th",
    "EPFL_V1-original",
    "EPFL_V2-original",
    # "Gaitpy",
    # "Hickey-original",
    # "Rai",
    "TA_Iluz-original",
    # "TA_Wavelets_v2",
]:
    pipelines[f"matlab_{matlab_algo_name}"] = GsdEmulationPipeline(
        DummyGsdAlgo(
            matlab_algo_name, base_result_folder=matlab_algo_result_path
        )
    )
```

--------------------------------

### Initialize and Run GenericMobilisedPipeline

Source: https://mobgap.readthedocs.io/en/stable/auto_examples/pipeline/_02_step_by_step_mobilised_pipeline.html

Instantiate the GenericMobilisedPipeline with all necessary detection and calculation modules, then execute the pipeline on a trial.

```python
from mobgap.pipeline import GenericMobilisedPipeline

pipeline = GenericMobilisedPipeline(
    gait_sequence_detection=gsd,
    initial_contact_detection=icd,
    laterality_classification=lrc,
    cadence_calculation=cad,
    stride_length_calculation=sl,
    turn_detection=turn,
    walking_speed_calculation=ws,
    stride_selection=ss,
    wba=wba,
    dmo_thresholds=thresholds,
    dmo_aggregation=agg,
)

pipeline.safe_run(long_trial)

```

--------------------------------

### Example Data Dataset Classes

Source: https://mobgap.readthedocs.io/en/stable/modules/data.html

Dataset classes for accessing example data.

```APIDOC
## LabExampleDataset

### Description
A dataset containing all lab example data provided with mobgap.

### Class Signature
`LabExampleDataset(*[, raw_data_sensor, ...])`
```

--------------------------------

### Install MobGap Locally from Cloned Repository

Source: https://mobgap.readthedocs.io/en/stable/README.html

Clone the MobGap repository and install the package locally using pip. This method is useful if you encounter issues with direct installation or wish to work with the source code.

```bash
git clone https://github.com/mobilise-d/mobgap.git
cd mobgap
pip install .

```

--------------------------------

### Initialize LabExampleDataset

Source: https://mobgap.readthedocs.io/en/stable/_downloads/300ef7e51b922ef93adcd56710bf8046/_01_loading_example_data.ipynb

Instantiate the LabExampleDataset class to load the example data. This class provides an easy way to access and iterate over the data.

```python
from mobgap.data import LabExampleDataset

example_data = LabExampleDataset()
```

--------------------------------

### Initialize GsdIluz with Default Parameters

Source: https://mobgap.readthedocs.io/en/stable/modules/generated/gait_sequences/mobgap.gait_sequences.GsdIluz.html

Instantiate the GsdIluz algorithm with its default configuration. This is useful for a quick start or when the default parameters are suitable for the analysis.

```python
from mobgap.gait_sequences.mobgap import GsdIluz

# Initialize with default parameters
gait_detector = GsdIluz()

# You can also explicitly set parameters if needed
# gait_detector = GsdIluz(window_length_s=5, allowed_steps_per_s=(0.5, 2.5))

```

--------------------------------

### Setup Cadence Emulation Pipelines

Source: https://mobgap.readthedocs.io/en/stable/_downloads/a64e349c64b867d36803da2f491731b8/_02_cadence_result_generation_no_exc.ipynb

Configures emulation pipelines for Cadence algorithms, including MATLAB algorithm emulation and reimplemented versions with different presets. Uses dummy algorithms and IC detectors for emulation.

```python
from mobgap.utils.misc import get_env_var

matlab_algo_result_path = (
    Path(get_env_var("MOBGAP_VALIDATION_DATA_PATH")) / "_extracted_results/cad"
)

pipelines = {}
for matlab_algo_name in [
    "HKLee_Imp2",
    "Shin_Imp",
]:
    pipelines[f"matlab_{matlab_algo_name}"] = CadEmulationPipeline(
        DummyCadAlgo(
            matlab_algo_name, base_result_folder=matlab_algo_result_path
        )
    )
pipelines["HKLeeImproved"] = CadEmulationPipeline(
    CadFromIcDetector(IcdHKLeeImproved())
)
pipelines["ShinImproved"] = CadEmulationPipeline(
    CadFromIcDetector(IcdShinImproved())
)
```

--------------------------------

### Load Lab Example Data

Source: https://mobgap.readthedocs.io/en/stable/_downloads/a8fe2c5f0fb7b35da343d6f2a3a57834/_01_icd_ionescu.ipynb

Loads example data from the lab dataset, specifying the reference system and parameter level.

```python
example_data = LabExampleDataset(
    reference_system="INDIP", reference_para_level="wb"
)
```

--------------------------------

### Access Metadata from Example Data

Source: https://mobgap.readthedocs.io/en/stable/_downloads/300ef7e51b922ef93adcd56710bf8046/_01_loading_example_data.ipynb

Retrieve metadata associated with the loaded example data. This can include information about the test or recording.

```python
test_11_data.metadata
```

--------------------------------

### Load Lab Example Dataset

Source: https://mobgap.readthedocs.io/en/stable/_downloads/288b12f843e3a94b26dfc7480dad37a0/_04_gsd_evaluation_challenges.ipynb

Loads the LabExampleDataset with a specified reference system and retrieves a subset for testing.

```python
from mobgap.data import LabExampleDataset

long_test = LabExampleDataset(reference_system="INDIP").get_subset(
    test="Test11"
)
```

--------------------------------

### Install MobGap using pip

Source: https://mobgap.readthedocs.io/en/stable/_sources/README.md.txt

Install the latest stable version of the MobGap package from the Python Package Index (PyPI).

```bash
pip install mobgap
```

--------------------------------

### Placeholder for WB Assembly Example

Source: https://mobgap.readthedocs.io/en/stable/_sources/auto_examples/wba/_01_assembling_wbs.rst.txt

This is a placeholder for the main WB assembly example. It is currently not implemented and requires further development with real stride values and rules.

```Python
# TODO: Update the example with real stride values and rules
```

--------------------------------

### Build Documentation

Source: https://mobgap.readthedocs.io/en/stable/guides/developer_guide.html

Builds the project's HTML documentation using Sphinx. This command generates the documentation files.

```bash
uv run poe docs

```

--------------------------------

### Setup GridSearch Optimizer

Source: https://mobgap.readthedocs.io/en/stable/_sources/auto_examples/gait_sequences/_04_gsd_evaluation_challenges.rst.txt

Configure `GridSearch` with a parameter grid and a scoring function. Specify the result to optimize for. This setup is used within a cross-validation challenge.

```Python
from sklearn.model_selection import ParameterGrid
from tpcp.optimize import GridSearch

para_grid = ParameterGrid({"algo__window_length_s": [2, 3, 4]})
optimizer = GridSearch(
    pipe,
    para_grid,
    scoring=gsd_evaluation_scorer,
    return_optimized="precision"
)
```
Tokens:
Raw