ClinicalScope

Multi-source time-series signal visualization for research, mainly in ICU and Machine Learning
Format · Visualize · Annotate · Export — no code required

ClinicalScope is an open-source, browser-based dashboard for visualizing, annotating, and extracting time-series data. Its primary domain is ICU monitoring — loading recordings from multiple clinical devices simultaneously (Servo-U ventilators, EIT systems, FluxMed, Mindray, EDF recorders, plus a generic reader for any tabular export — monitors, syringe pumps, and the like) — but its annotation and extraction pipeline is designed for any time-series data, making it equally useful for machine learning workflows that require labeled datasets.

Installation

Pre-built application (recommended)

Download the latest release for your platform from the Releases page:

Unzip and run the ClinicalScope executable — no Python installation required. Each bundle includes the user guide PDF and a demo database to get started immediately.

From PyPI (Python users)

pip install clinical-scope
clinical-scope          # opens http://127.0.0.1:8050

Requires Python 3.11–3.13.

To upgrade an existing install to the newest release:

pip install -U clinical-scope

From source (developers)

git clone https://github.com/larib-data/clinical-scope.git
cd clinical-scope
python -m venv .venv              # create a virtual environment
source .venv/bin/activate         # Windows: .venv\Scripts\activate
pip install -e .
clinical-scope

For the full developer setup (tests, linting, adding a datasource), see CONTRIBUTING.md.

Demo

Quickstart

1. Install and run — see Installation above; your browser opens at http://127.0.0.1:8050
2. Load config — click Default visualization (all sources) to use built-in defaults, or upload a database_options.json / .xlsx config file
3. Set data folder — enter the path to your patient folder. No data of your own yet? See Trying the demo below (for the demo, set the EIT day to 2004-09-15 and the EDF recording start to 2004-09-15 10:12:33 — neither file carries its own recording date)
4. Process — click Process visualization; interactive plots appear in the browser
5. Annotate — draw time events, windows, or point annotations, then click Save

Trying the demo

ClinicalScope ships a small demo recording — one patient, every supported data source — so you can see a full visualization before preparing any data of your own.

A pip install does not include it, so download it once:

clinical-scope --demo

That prints the folder it landed in, plus the demo_patient/ path to paste into the app's Data folder field. A source checkout already carries the same data under example/demo_database/; the standalone application puts it in demo_database/, next to the executable.

Run clinical-scope --help for the full list of commands.

Documentation

The user guide is the primary reference for everything beyond the Quickstart: data folder layout, database_options config files, annotation tools, inspection view, CLI scripts, and the Python API.

Supported Data Sources

Each patient folder should contain one subfolder per data source. The user guide → Patient Data & Supported Data Sources gives the folder keyword for each source, the naming rules, and the configuration details.

Standalone Data Processing

ClinicalScope can run the full find → load → format pipeline without opening the UI, either via Python or command-line scripts. Raw parquet caches are always written to <data_folder>/clinical_scope_output/ automatically; pass save_folder to also save formatted output elsewhere.

Python API

from pathlib import Path
from clinical_scope import extract_datasource, extract_patient, batch_extract
from clinical_scope.config.parsing import load_database_options_from_path

db_options = load_database_options_from_path(Path("database_options.json"))
# No config of your own yet? The demo config works as-is, no UI needed — run
# `clinical-scope --demo`, then point at the database_options.json it reports.

# 1. Single datasource subfolder (auto-detects type from folder name)
df = extract_datasource(
    Path("/data/Patient01/servo_u"),
    database_options_specific=db_options.get("servo_u"),
    patient_options={"datetime_start": "2024-01-15 08:00:00"},
    save_path="/output/servo_u.parquet",  # optional
)

# 2. All datasources for one patient
results = extract_patient(
    Path("/data/Patient01"),
    db_options,
    patient_options={"datetime_start": "2024-01-15 08:00:00"},
    save_folder="/output/Patient01",  # optional
)
# results = {"servo_u": DataFrame | None, "eit": DataFrame | None, ...}
# Note: the generic "other" source is visualization-only — extraction returns None for it.

# 3. Multiple patients — pass a root directory or an explicit list
batch = batch_extract(
    Path("/data"),  # root whose subdirs are patients
    db_options,
    save_folder="/output",  # optional; each patient gets a subfolder
)
# batch = {"Patient01": {"servo_u": DataFrame, ...}, "Patient02": {...}, ...}

# Explicit list variant
batch = batch_extract(["/data/Patient01", "/data/Patient02"], db_options)

Set "quick_load": true in patient_options to reuse previously cached parquet files on subsequent runs.

CLI Scripts

All three scripts share the same pattern: a required patient_folder positional argument plus optional --database-options, --patient-options, and --verbose flags.

# Extract (find + load + format) without plots
python scripts/process_patient_data.py patient /data/Patient01 --verbose
python scripts/process_patient_data.py patient /data/Patient01 --database-options db.json
python scripts/process_patient_data.py batch /data/patients --output-folder /out

# Inspect available columns per datasource
python scripts/inspect_patient_data.py /data/Patient01 --verbose
python scripts/inspect_patient_data.py /data/Patient01 --database-options db.json --output-csv out.csv

# Visualize (generates HTML)
python scripts/visualization_patient_data.py /data/Patient01 --verbose
python scripts/visualization_patient_data.py /data/Patient01 --database-options db.json

Omit --database-options to use all available datasources with their defaults. Use --patient-options opts.json to pass datetime range, time shift, quick_load, etc.

Contributing

Contributions are welcome — bug reports, new data sources, and documentation improvements. See CONTRIBUTING.md.

Citation

If you use ClinicalScope in academic work, please cite:

@software{clinicalscope2026,
  author    = {Janin, Alexis},
  title     = {{ClinicalScope}: Interactive Visualization Dashboard for Clinical Physiological Signals},
  url       = {https://github.com/larib-data/clinical-scope},
  version   = {1.3.0},
  year      = {2026},
  doi       = {10.5281/zenodo.20830140},
}

A CITATION.cff file is also provided for GitHub's Cite this repository button.

Disclaimer

Research Use Only — Not a Medical Device

This software is provided exclusively for scientific research purposes. It is not a medical device within the meaning of Regulation (EU) 2017/745 (MDR) and has not undergone CE marking, conformity assessment, or any regulatory authorization (CE, FDA, or other).

It must not be used for the diagnosis, monitoring, treatment, or prevention of disease, nor for any clinical decision concerning a patient. The visualizations, annotations, and formats it produces are not validated for clinical purposes, and any use beyond research is the sole responsibility of the user, who must carry out their own validation.

Personal Data and GDPR

This software processes physiological signals that may constitute health data — i.e. personal data falling within the special categories of Article 9 of Regulation (EU) 2016/679 (GDPR). By deploying or using this software on data, you act as the data controller and assume all corresponding obligations.

License

ClinicalScope is licensed under the Apache License 2.0.

Copyright © 2026 Assistance Publique – Hôpitaux de Paris. Developed by Alexis Janin.