README.md

OCDetect 2.0 analysis

Scripts for wearable-based handwashing detection, event-level compulsive-versus-routine classification, and associations between motion characteristics and retrospective ratings.

Inputs are merged, annotated recordings. See DATA_FORMAT.md for columns and event definitions. Participant data, fitted models, and predictions are not included.

Setup

Dependency versions are listed in requirements.txt; the reference environment uses Python 3.8.19.

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

Run commands from the repository root and replace example paths with your local paths. Use a fresh output directory after changing input data because detection scripts cache extracted windows.

Event classification

python scripts/event_level_compulsive_routine.py --data-dir data/annotated --output-dir results/events

Runs logistic regression and a constrained random forest with full and reduced feature sets. Use --model logistic_regression --feature-set reduced to run only the reduced 14-feature logistic regression.

Evaluation uses repeated stratified five-fold cross-validation with 20 repeats and a decision threshold of 0.5. Held-out probabilities are averaged per event. Confidence intervals use 2,000 within-class bootstrap samples of those fixed predictions; models are not refitted during resampling. These intervals do not include model-selection uncertainty. Each class needs at least five events.

Correlations

python scripts/correlations.py --dataset-dir data/annotated --feature-table results/events/event_level_features.csv --output-dir results/correlations

Computes Pearson and Spearman correlations, duration-adjusted correlations, 1,000-resample bootstrap intervals, and Benjamini–Hochberg correction within each subset/outcome/method/analysis family. Partial-correlation tests controlling for duration use n - 3 degrees of freedom. Outputs are event_level_features.csv and correlations.csv.

Descriptive statistics

python scripts/descriptive_statistics.py --data-dir data/annotated --output-dir results/descriptive --naive-timezone UTC --display-timezone Europe/Berlin

Set --naive-timezone to the actual timezone of timestamps without offsets; UTC is an example. Participant reports and annotated episodes are counted separately. Add --event-features results/correlations/event_level_features.csv for duration and rating summaries of the analyzed events.

Handwashing detection and SHAP

python scripts/random_forest_grouped_cv.py --data-dir data/annotated --output-dir results/detection
python scripts/lstm_grouped_cv.py --data-dir data/annotated --output-dir results/detection

Uses 50 Hz recordings, 50-sample windows with 25-sample steps, episode groups, 60-second background groups, and five-fold stratified group cross-validation. Oversampling is confined to training folds. The RF script produces SHAP summaries; the LSTM defaults to ten training epochs.

Detection metrics and curves

python scripts/summarize_predictions.py --rf-results results/detection/model/random_forest/win50_step25_hz50_bg60_beacon1/results_rf_folds.json --lstm-results results/detection/model/lstm/win50_step25_bg60_beacon1_grouped_v2/results_lstm_grouped_cv.json --output-dir results/figures

Exports RF metrics by fold and as unweighted fold averages, plus pooled metrics for both models. PR/ROC curves use pooled held-out predictions. PR summaries use average precision, and the no-skill precision reference is the positive-class prevalence. Fold averages and pooled metrics are distinct summaries and should be labelled accordingly.

Activity similarity

python scripts/activity_similarity.py --trial-csv data/trial/merged.csv --natural-csv data/natural/merged.csv --natural-start-row 0 --natural-end-row 10000 --output-dir results/similarity

The row bounds are examples. Cropping precedes selection of annotation == 1; each selection must contain exactly one contiguous event with finite motion values.

Signals are standardized within event and axis. The analysis uses 100-sample windows with 50-sample steps at 50 Hz. Each window has 24 features: mean, population standard deviation, mean squared standardized values, and 30-bin histogram entropy for each motion axis. Outputs include the mean and maximum cosine similarity across all window pairs and per-axis DTW distances.

FastDTW uses radius 1, absolute sample differences, and its Python implementation to avoid installation-dependent changes in the approximate alignment. Accumulated distances depend on sequence length and scaling.

Generated features, event identifiers, models, and predictions should remain in local output directories. Exact retraining can depend on recording enumeration, numerical libraries, and CPU/GPU execution.