upgraded scales and reports rtd

Author: Lucia-Poma

docs/conf.py

@@ -15,13 +15,22 @@
 
 _DIST_NAME = "dbs-annotator"
 
-from dbs_annotator.config import APP_LEAD_AUTHOR, ORGANIZATION_PUBLISHER
+from dbs_annotator.config import APP_LEAD_AUTHOR, UPDATE_FEEDBACK_EMAIL
 
 project = "DBS Annotator"
 author = APP_LEAD_AUTHOR
 release = metadata.version(_DIST_NAME)
 version = ".".join(release.split(".")[:2])
-copyright = f"2025-{datetime.now().year}, {ORGANIZATION_PUBLISHER}"
+_DOCS_COPYRIGHT_HOLDERS = (
+    "Massachusetts General Hospital, "
+    "Wyss Center for Bio and Neuroengineering, "
+    "and Charité Universitätsmedizin Berlin"
+)
+copyright = f"2025-{datetime.now().year}, {_DOCS_COPYRIGHT_HOLDERS}"
+
+html_context = {
+    "contact_email": UPDATE_FEEDBACK_EMAIL,
+}
 
 extensions = [
     "sphinx.ext.autodoc",

docs/contributing.rst

@@ -467,7 +467,8 @@ Clinical Domain Experts
 If you are a clinician or DBS specialist:
 
 - Share real-world session workflows and edge cases.
-- Review and suggest improvements to clinical scale presets.
+- Review and suggest improvements to clinical and session scale presets
+  (``CLINICAL_SCALES_PRESETS`` / ``SESSION_SCALES_PRESETS`` in ``config.py``).
 - Provide feedback on electrode model definitions and contact diagrams.
 - Help validate clinical accuracy of exported reports.
 

docs/faq.rst

@@ -92,19 +92,26 @@ The application highlights the "best" stimulation configuration in green in the
 Session Data table.  The scale optimisation dialog lets you define what "best"
 means for each scale:
 
-* **Min** — the entry with the lowest value is best (e.g. UPDRS — lower motor
-  score = better).
-* **Max** — the entry with the highest value is best (e.g. Mood VAS — higher
-  mood = better).
+* **Min** — the entry with the lowest value is best (e.g. UPDRS-III, Tremor).
+* **Max** — the entry with the highest value is best (e.g. Mood, Energy).
 * **Custom** — the entry closest to a target value you specify.
 
 Uncheck a scale to exclude it from the calculation.
 
 **The report sections dialog appeared but I only want a summary table.
 Which sections should I check?**
 
-Check only **Sessions Overview** (for a quick one-table overview) or
-**Programming Summary** (for parameter ranges).  Uncheck the others.
+Check only **Sessions Overview** (summary table plus clinical-scales chart) or
+**Programming Summary** (parameter ranges).  Uncheck the others.  For a chart
+without the full entry table, select **Session Data Graph** only.
+
+**Where do the timeline charts in reports come from?**
+
+Session and longitudinal exporters build PNG charts with matplotlib
+(``report_chart_utils``).  **Session Data Graph** plots session-scale values
+(0–10) against configuration block index.  **Sessions Overview** in the
+longitudinal report adds a separate chart of baseline clinical scales across
+loaded session files.
 
 **Word export works but PDF export fails.**
 
@@ -159,5 +166,7 @@ Contact & Support
 
 For bug reports, feature requests, or questions:
 
+| **Massachusetts General Hospital** (Brain Modulation Lab)
 | **Wyss Center for Bio and Neuroengineering**
+| **Charité Universitätsmedizin Berlin**
 | **Lucia Poma** — lucia.poma@wysscenter.ch

docs/index.rst

@@ -16,12 +16,13 @@ clinician or researcher through the full session workflow — from initial
 electrode configuration and baseline scales, through real-time stimulation
 adjustments, to the automatic generation of structured Word and PDF reports.
 
-Developed at the **Brain Modulation Lab, Massachusetts General Hospital** in Boston, USA
-and at the **Wyss Center for Bio and Neuroengineering** in Geneva, Switzerland.
+Developed at the **Brain Modulation Lab, Massachusetts General Hospital** (Boston, USA),
+the **Wyss Center for Bio and Neuroengineering** (Geneva, Switzerland), and
+**Charité Universitätsmedizin Berlin** (Germany).
 
 .. note::
    | Version |release|.
-   | Publisher: Wyss Center for Bio and Neuroengineering.
+   | Copyright © Massachusetts General Hospital, Wyss Center for Bio and Neuroengineering, and Charité Universitätsmedizin Berlin.
    | Contact: lucia.poma@wysscenter.ch
 
 ----
@@ -68,10 +69,12 @@ Quick Overview
 
    * - **Single-session workflow**
      - Record stimulation parameters, clinical scales, and notes step-by-step.
-       Export a structured report (Word / PDF) at the end.
+       Export a structured report (Word / PDF) with tables, electrode diagrams,
+       and session-scale timeline charts.
    * - **Longitudinal report**
      - Combine multiple session files into a single comparative document with
-       overview tables, electrode configuration diagrams, and timeline charts.
+       overview tables, clinical and session-scale charts, electrode diagrams,
+       and programming summaries.
    * - **Free annotations**
      - Quick timestamped text notes without the full stimulation workflow.
    * - **BIDS-compliant output**

docs/longitudinal_report.rst

@@ -78,17 +78,17 @@ Three dialogs appear before the file-save dialog:
 Step 1 — Scale Optimisation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Choose the optimisation target for each clinical scale found across all loaded
-files.
+Choose the optimisation target for each **session scale** and, when present,
+each **clinical (baseline) scale** found across all loaded files.
 
 .. image:: _static/scale_optimization_dialog.png
    :alt: Scale optimisation dialog
    :width: 500px
 
 For each scale, select:
 
-* **Min** — lower values are better (e.g. UPDRS, Y-BOCS).
-* **Max** — higher values are better (e.g. Mood VAS).
+* **Min** — lower values are better (e.g. UPDRS-III, Tremor, Y-BOCS).
+* **Max** — higher values are better (e.g. Mood, Energy).
 * **Custom** — enter a specific target value; the entry closest to that value
   is highlighted.
 
@@ -97,7 +97,8 @@ Uncheck a scale to exclude it entirely from best-entry highlighting.
 Step 2 — Report Sections
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Choose which sections to include.  By default only the first two are checked:
+Choose which sections to include.  By default **Sessions Overview** and
+**Session Data Graph** are checked:
 
 .. list-table::
    :widths: 35 15 50
@@ -108,13 +109,18 @@ Choose which sections to include.  By default only the first two are checked:
      - Description
    * - Sessions Overview
      - ✓
-     - Summary table listing all loaded sessions with date, number of entries,
-       and final scale values.
-   * - Session Data
+     - Summary table of all loaded sessions (date, entry count, baseline
+       clinical scales) plus a **clinical scales timeline chart** across
+       sessions.
+   * - Session Data → Graph
      - ✓
-     - Detailed table of all recorded entries across all sessions, with
-       stimulation parameters, scale values, and notes.  The best entry per
-       session is highlighted.
+     - **Session-scale timeline chart** across all configurations in all files
+       (one subplot per scale; best entries highlighted).
+   * - Session Data → Table
+     - ☐
+     - Combined table of all recorded entries across sessions (date column,
+       stimulation parameters, scale values, notes).  Best entry per session
+       highlighted.
    * - Electrode Configuration
      - ☐
      - Per-file Initial / Final electrode diagrams (Left and Right hemispheres).
@@ -140,7 +146,8 @@ Report Contents
 Sessions Overview
 ^^^^^^^^^^^^^^^^^^
 
-A table with one row per loaded file:
+A **clinical scales timeline chart** (baseline ``is_initial = 1`` values per
+session file) followed by a summary table with one row per loaded file:
 
 .. list-table::
    :widths: 30 70
@@ -155,17 +162,21 @@ A table with one row per loaded file:
    * - Entries
      - Number of stimulation configurations recorded
    * - Clinical scales
-     - Final scale values from the last recorded entry
+     - Names of baseline clinical scales recorded in Step 1
+   * - Values
+     - Corresponding baseline scores
 
 Session Data
 ^^^^^^^^^^^^^
 
-A combined table of all session entries across all files.  The first column
-shows the **date** of each entry (from the ``date`` field in the TSV).
-Columns include laterality (L/R), stimulation frequency, contacts (+/−),
-amplitude, pulse width, scale values, and notes.
+Depending on your section selection, the report includes a **session-scale
+timeline chart** (values across programming blocks in all files), a **combined
+data table**, or both.
 
-The best entry per session is highlighted in **green**.
+The table's first column shows the **date** of each entry (from the ``date``
+field in the TSV).  Other columns include laterality (L/R), stimulation
+frequency, contacts (+/−), amplitude, pulse width, session scale values, and
+notes.  The best entry per session is highlighted in **green**.
 
 .. image:: _static/longitudinal_session_data.png
    :alt: Session data table in longitudinal report

docs/output_format.rst

@@ -45,9 +45,9 @@ Example rows
 .. code-block:: text
 
    date	time	timezone	block_id	session_ID	is_initial	scale_name	scale_value	electrode_model	program_ID	left_stim_freq	left_anode	left_cathode	left_amplitude	left_pulse_width	right_stim_freq	right_anode	right_cathode	right_amplitude	right_pulse_width	notes
-   2025-03-15	10:02:31	UTC-04:00	0	0	1	UPDRS-III	42	SenSight B33015	A	130	Case	1C	0.0	60	130	Case	9C	0.0	60	Baseline pre-stim
-   2025-03-15	10:15:44	UTC-04:00	1	1	0	UPDRS-III	38	SenSight B33015	A	130	Case	1C	2.5	60	130	Case	9C	2.0	60	Config 1
-   2025-03-15	10:28:12	UTC-04:00	2	2	0	UPDRS-III	34	SenSight B33015	B	130	Case	2A,2B	3.0	90	130	Case	10A,10B	2.5	90	Config 2 - wider contacts
+   2025-03-15	10:02:31	UTC-04:00	0	0	1	MDS-UPDRS\nUPDRS-III	28\n32	SenSight B33005	A	130	Case	E1a	0.0	90	130	Case	E2	0.0	90	Baseline pre-stim
+   2025-03-15	10:15:44	UTC-04:00	1	1	0	Tremor\nRigidity\nBradykinesia	6.0\n5.0\n4.0	SenSight B33005	A	130	Case	E1a,E1b	2.0	90	130	Case	E2	2.0	90	Config 1
+   2025-03-15	10:28:12	UTC-04:00	2	2	0	Tremor\nRigidity\nBradykinesia	4.0\n3.0\n3.0	SenSight B33005	B	130	Case	E2A,E2B	2.5	90	130	Case	E3	2.5	90	Config 2
 
 ----
 
@@ -65,11 +65,15 @@ Sections (in order):
 
 1. **Title** — "Clinical DBS Session Report", generated date, patient ID,
    session number.
-2. **Initial Clinical Notes** *(optional)* — baseline scale scores and any
-   initial notes recorded in Step 1.
-3. **Session Data** *(optional)* — lateral table (L/R rows per configuration)
-   with all recorded stimulation parameters, scale values, and notes.  The
-   best entry is highlighted in green.
+2. **Initial Clinical Notes** *(optional)* — baseline clinical scale scores
+   and any initial notes recorded in Step 1.
+3. **Session Data** *(optional)* — one or both of:
+
+   * **Session Data Graph** — matplotlib timeline chart of session-scale
+     values vs configuration block (best entry per scale highlighted).
+   * **Session Data Table** — lateral table (L/R rows per configuration) with
+     stimulation parameters, scale values, and notes.
+
 4. **Electrode Configurations** *(optional)* — a borderless 4-column table:
 
    +-------------------+-------------------+-------------------+-------------------+
@@ -88,11 +92,12 @@ Sections (in order, selected at export time):
 
 1. **Title** — "Longitudinal DBS Report", generated date, patient ID,
    list of included files.
-2. **Sessions Overview** *(optional)* — one-row-per-session summary table
-   with date, number of entries, and final scale values.
-3. **Session Data** *(optional)* — combined table across all sessions.
-   First column is the entry **date**; the best entry per session is
-   highlighted.
+2. **Sessions Overview** *(optional)* — clinical-scales timeline chart across
+   sessions plus a one-row-per-session summary table (date, entry count,
+   baseline scale names and values).
+3. **Session Data** *(optional)* — session-scale timeline chart and/or
+   combined table across all sessions.  The table's first column is the entry
+   **date**; the best entry per session is highlighted.
 4. **Electrode Configuration** *(optional)* — per-file Initial/Final diagrams
    separated by page breaks.
 5. **Programming Summary** *(optional)* — per-session parameter ranges.

docs/workflow_session.rst

@@ -121,9 +121,20 @@ Both the **Left** and **Right** hemispheres have independent parameter panels.
 Baseline Clinical Scales
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Below the stimulation parameters you will find a panel for baseline clinical
-scale scores (e.g. UPDRS, MADRS, Y-BOCS).  These are populated from the
-scale preset you selected in the previous step.
+Below the stimulation parameters you will find a panel for **baseline clinical
+scales** (validated rating instruments recorded once at the start of the
+session).  Click a **preset button** (OCD, MDD, PD, ET, Dystonia, TS) to load
+the standard scale set for that indication, or use the settings control to
+customise presets.
+
+Built-in clinical presets (Step 1):
+
+* **OCD** — Y-BOCS, Y-BOCS-o, Y-BOCS-c, MADRS, OCI-R
+* **MDD** — MADRS, HAM-D, BDI-II
+* **PD** — MDS-UPDRS, UPDRS-III, PDQ-39, UDysRS
+* **ET** — FTM-TRS, TETRAS
+* **Dystonia** — BFMDRS, TWSTRS
+* **TS** — YGTSS, PUTS, TS-CGI, Y-BOCS
 
 Each scale has a **slider** with arrow buttons and a numeric display.  Press
 the **✕** button on a slider to mark that scale as "not assessed" (stored as
@@ -148,19 +159,25 @@ stimulation configuration tested).
 Built-in presets
 ^^^^^^^^^^^^^^^^
 
-Use the preset buttons to load a standard scale set for your clinical
-indication:
+Use the preset buttons to load a standard **session scale** set (rated at each
+stimulation configuration during programming).  All built-in session scales use
+a **0–10** numeric range with slider controls.
 
-* **OCD** — Y-BOCS, Anxiety VAS, Mood VAS
-* **MDD** — MADRS, Anxiety VAS, Mood VAS, Energy VAS
-* **PD** — UPDRS-III, Dyskinesia VAS, Mood VAS
-* **ET** — Tremor VAS, Mood VAS
+* **OCD** — Obsessions, Compulsions, Anxiety, Mood, Energy
+* **MDD** — Rumination, Anxiety, Mood, Energy
+* **PD** — Tremor, Rigidity, Bradykinesia, Dyskinesia, Gait / balance,
+  Paresthesia, Speech difficulty
+* **ET** — Action tremor, Resting tremor, Paresthesia, Speech difficulty
+* **Dystonia** — Muscle contractions, Abnormal posture, Pain
+* **TS** — Tic severity, Premonitory urge, Control over tics, Anxiety,
+  Impulsivity
 
 Custom scales
 ^^^^^^^^^^^^^
 
 Click **+ Add scale** to define a custom scale with a name and a numeric
-range.  Custom scales are saved for the current session.
+range (min / max).  Custom scales are saved for the current session via the
+session-scales settings dialog.
 
 ----
 
@@ -225,12 +242,19 @@ Before the file-save dialog appears, two dialogs will be shown:
       :width: 500px
 
 2. **Report Sections** — choose which sections to include in the report.
-   All four sections are checked by default:
+   By default all main sections are checked.  Under **Session Data** you can
+   include the timeline chart, the lateral data table, or both:
+
+   * **Initial Clinical Notes** — baseline scores and Step 1 notes
+   * **Session Data** — parent section; expand to choose:
+
+     * **Session Data Graph** — timeline chart of session-scale values across
+       recorded configurations (best entry highlighted per scale)
+     * **Session Data Table** — lateral table (L/R rows) with stimulation
+       parameters, scale values, and notes
 
-   * Initial Clinical Notes
-   * Session Data
-   * Electrode Configurations
-   * Programming Summary
+   * **Electrode Configurations** — initial vs final contact diagrams
+   * **Programming Summary** — session duration and parameter ranges
 
    .. image:: _static/report_sections_dialog.png
       :alt: Report sections dialog
@@ -243,9 +267,12 @@ Report Contents
 
 The generated report includes (depending on the selected sections):
 
-* **Initial Clinical Notes** — baseline scale scores and initial notes.
-* **Session Data** — table of all recorded entries with stimulation
-  parameters, scale values, and notes.  The best entry is highlighted.
+* **Initial Clinical Notes** — baseline clinical scale scores and initial
+  notes from Step 1.
+* **Session Data** — optional **timeline chart** (one line per session scale,
+  x-axis = configuration block) and/or **data table** of all recorded entries
+  with stimulation parameters, scale values, and notes.  The best entry per
+  scale is highlighted in green according to your optimisation choices.
 * **Electrode Configurations** — visual diagrams showing the initial and
   final electrode contact selection (Left and Right hemispheres).
 * **Programming Summary** — session duration, number of configurations