Surgical Cognitive Dashboard 🧠

A professional, enterprise-grade real-time surgical cognitive monitoring system with evidence-based biosignal simulation, comprehensive ML diagnostics, and clinical-quality visualization. Features literature-validated parameters from 20+ peer-reviewed studies with full model interpretability and interactive reference ranges.

➡️ Live Demo (coming soon)
🏠 Local Development: make app → http://localhost:3838
📚 Evidence Base | Recent Updates

✨ Latest Version (October 2025): Stability improvements with opacity fix, enhanced biosignal suite (HRV, blink rate, ambient noise), GT live table with reference ranges, and pure CSS implementation. Running successfully on localhost:3838.

🆚 Which Tool Should I Use?

Use Case	👉 Recommended Tool
Clinical/Production Monitoring	🏥 This Dashboard (surgical-cognitive-dashboard)
Research & Exploration	🧪 Training Lab
Teaching Cognitive Theory	🧪 Training Lab
Real-time Patient Safety	🏥 This Dashboard (surgical-cognitive-dashboard)
Algorithm Prototyping	🧪 Training Lab
Deployment to Hospitals	🏥 This Dashboard (surgical-cognitive-dashboard)

🧪 Surgical Training Lab (Companion Tool)

An interactive research and educational tool featuring three cognitive theory paradigms:

Inverted-U Zone Adjuster (Adaptive Gain Theory)
Unified Sensitivity (Resource Competition Model)
Fatigue-Adaptive Thresholds (Vigilance Decrement)

Perfect for: Graduate courses, research labs, hypothesis testing, and understanding cognitive mechanisms.

Status: Experimental - May have opacity issues, prioritizes features over optimization.

📖 Detailed Comparison Table | Project Ecosystem Overview

🚀 Project Overview

This project implements a complete machine learning system for monitoring surgical cognitive states, featuring:

Evidence-Based Simulation: 6 biosignals with parameters from 20+ peer-reviewed studies
Causal Feature Engineering: 57 strictly causal features with segment-aware baselines
Multi-Model Architecture: XGBoost classifier + Isolation Forest anomaly detection + Platt scaling
LOSO Cross-Validation: Leave-One-Surgeon-Out validation for generalizability
Real-time Streaming: 5Hz updates with GT live table and reference ranges
Comprehensive Diagnostics: 6-tab diagnostic interface with calibration analysis
Pure CSS Implementation: Zero opacity issues, no unstable dependencies (shinyjs/cicerone removed)
Deployment Ready: Multiple deployment options (ShinyApps.io, Docker, self-hosted)
iframe Embedding: Ready for Netlify/Quarto integration

✨ Latest Improvements

Stability & Performance (October 2025)

✅ Opacity Fix: Removed shinyjs and cicerone dependencies causing UI overlay issues
✅ Pure CSS Implementation: All animations using standard Shiny + CSS (no JavaScript overlays)
✅ Zero Runtime Errors: Eliminated all package loading errors and warnings
✅ Localhost Deployment: Successfully running on http://localhost:3838/

Enhanced Biosignal Suite

✅ HRV (RMSSD): 40ms baseline, -35% under high load (De Louche et al. 2024)
✅ Blink Rate: 17 blinks/min with load/fatigue modulation (Marquart et al. 2015)
✅ Ambient Noise: 60dB OR baseline with random spike events
✅ Improved TEPR: Task-evoked pupillary response with 1.2s rise time (Wu et al. 2019)
✅ Fatigue-Driven CV: Grip force variability 8% → 12% over 30 minutes (Araki et al. 2021)

GT Live Table Features

✅ 12 Real-Time Features: Comprehensive biosignal monitoring with sparkline trends
✅ Reference Ranges: Literature-based normal/caution/alert zones
✅ Color Coding: Visual indicators based on evidence-based thresholds
✅ Toggleable Display: ConditionalPanel for show/hide without performance impact

UI/UX Enhancements

✅ Stacked Probability Chart: True stacked area plot with 10-point smoothing
✅ Animated Status Indicators: Purpose-driven CSS animations (slow/warning/urgent pulse)
✅ Professional Typography: Clean, clinical-grade design suitable for medical environments

📁 Project Structure

Why Two Directories?
This repository separates the complete development pipeline from the deployment-ready app for clarity and maintainability.

surgical-cognitive-dashboard/
├── surgical-cognitive-dashboard-1/     # 🔬 Development Pipeline
│   ├── Complete ML pipeline (scripts 01-05)
│   ├── Test suite (25 tests passing)
│   ├── Makefile automation
│   ├── Shiny app with diagnostics
│   └── Full development environment
│
└── surgical-cognitive-dashboard-app/   # 🚀 Deployment Package
    ├── Standalone Shiny app
    ├── Docker + nginx setup
    ├── ShinyApps.io deployment
    └── iframe embedding utilities

🛠️ Tech Stack

Language: R 4.x
Visualization: shiny, bslib, plotly, ggplot2, gt (professional tables), DT
Data Processing: tidyverse, data.table, zoo
Machine Learning: xgboost, yardstick, slider, solitude, fastshap, pdp
Development: renv for package management, testthat for testing
Build System: Makefile for automated pipeline execution
Deployment: Docker, nginx, ShinyApps.io
Quality: Zero unstable dependencies (removed shinyjs, cicerone)

🧪 Data & Features

Raw Sensor Data (Simulated):

Pupil Diameter (mm): Continuous pupillometry measurements
Grip Force (Newtons): Surgical instrument grip pressure
Instrument Tremor (Hz): High-frequency tremor measurements
Ambient Noise (dB): Operating room noise levels
Blink Events: Eye blink detection
Tool Usage: Surgical instrument tracking

8 Causal Engineered Features:

Tonic Pupil Level (30s): Rolling mean baseline pupil size
Grip Force Variability (15s): Rolling standard deviation of grip pressure
Tremor Trend (10s): Rolling mean of tremor frequency
Phasic Pupil Change (5s): Segment-aware pupil responses
Blink Rate (60s): Rolling sum of blink events
Tool Switch Rate (120s): Instrument change frequency
Noise Mean (60s): Rolling mean ambient noise
Noise Spike Count (60s): High-noise event detection

Key Properties:

✅ Strictly Causal: No future data leakage
✅ Segment-Aware: Baselines reset on tool switches
✅ Real-time Legal: Suitable for live streaming

📊 Model Performance (LOSO on Simulated Surgeons)

Primary Safety Class: Attentional Lapse

PR-AUC (LOSO): [Value from data/diagnostics/loso_eval.rds]
Calibration: ECE=0.000296, Brier=0.00192
Prevalence: 0.4% (rare event detection)

Multi-Class Performance

4 Cognitive States: Optimal, High Load, Fatigued, Attentional Lapse
Validation: Leave-One-Surgeon-Out cross-validation
Calibration: Platt scaling for reliable probability estimates
Threshold Trade-offs: Interactive sandbox shows precision/recall vs θ

Note: All performance metrics are on synthetic data. This is a proof-of-concept for causal ML architecture.

🏁 Getting Started

Development Environment

Clone and Setup:

git clone https://github.com/mohdasti/surgical-cognitive-dashboard.git
cd surgical-cognitive-dashboard/surgical-cognitive-dashboard-1
make setup

Run Complete Pipeline:

make simulate    # Generate synthetic data
make features    # Compute causal features
make train       # Train XGBoost model
make anomaly     # Train Isolation Forest
make shap        # Generate explainability plots
make eval        # LOSO evaluation
make diagnostics # Calibration artifacts

Run Tests:

Rscript -e "library(testthat); test_dir('tests')"

Launch Development App:
```
make app
```

Deployment

ShinyApps.io Deployment:

cd surgical-cognitive-dashboard-app
export SHINYAPPS_ACCOUNT="your-account"
export SHINYAPPS_TOKEN="your-token"
export SHINYAPPS_SECRET="your-secret"
Rscript deploy.R

Docker Deployment:

cd surgical-cognitive-dashboard-app
docker build -t cogbb .
docker run -p 8080:80 cogbb

💻 Application Features

Real-time Dashboard:

Enhanced Biosignal Suite:
- Pupil Diameter (3.5mm baseline, TEPR peaks, hippus oscillation)
- Grip Force (4.5N baseline with 8-12 Hz tremor)
- Tremor Amplitude (90µm RMS at 10 Hz)
- HRV RMSSD (40ms baseline, -35% under load)
- Blink Rate (17 blinks/min with modulation)
- Ambient Noise (60dB OR environment)
GT Live Table: 12 real-time features with sparklines and literature reference ranges
Live HUD: 5Hz updates with cognitive state, probabilities, and animated indicators
Interactive Controls: Silent mode, threshold sliders, display toggles
Alert System: Real-time alerts with threshold-based notifications
Event Logging: Optional CSV logging for post-hoc analysis

ML Model Diagnostics (6 Tabs):

Overview: Model card, feature list, hyperparameters
Cross-Validation: Confusion matrix, PR curves, LOSO results
Calibration: Reliability plots, calibration statistics, probability histograms
Threshold Sandbox: Interactive threshold tuning with real-time metrics
Feature Importance: XGBoost importance and SHAP plots
Partial Dependence: Interactive PD plots for all features

🔗 Embedding on Netlify/Quarto

The app includes iframe-safe headers for embedding in websites:

<iframe 
  src="https://your-shinyapps-url/" 
  width="100%" 
  height="820" 
  loading="lazy"
  style="border:1px solid #ddd;border-radius:12px">
</iframe>

Headers configured:

Content-Security-Policy: frame-ancestors 'self' https://mdastgheib.com https://*.netlify.app
X-Frame-Options: ALLOWALL

Embed Check: Visit /embed-check.html to verify iframe compatibility.

🎯 Use Cases

Clinical Applications:

Surgical Safety: Real-time cognitive state monitoring and early warning systems
Training & Assessment: Objective measurement of surgical skill development
Quality Improvement: Data-driven insights into surgical performance patterns

Research Applications:

Cognitive Load Studies: Platform for studying attentional demands during procedures
Model Validation: Framework for testing new physiological biomarkers
Anomaly Detection: Research into rare but critical attentional lapses

Technical Applications:

Real-time ML: Causal feature engineering for streaming applications
Model Explainability: SHAP and partial dependence for clinical interpretability
Calibration Research: Probability calibration for safety-critical decisions

🔬 Research Background

Technical Innovations:

Causal Feature Engineering: Strict temporal causality for real-time applications
LOSO Cross-Validation: Surgeon-independent model validation
Anomaly Fusion: Combining supervised and unsupervised approaches
Probability Calibration: Reliable uncertainty quantification for safety-critical decisions

Scientific Foundation (20+ Peer-Reviewed Studies):

Pupillometry & Eye Tracking:

Wu et al. (2019) - Arousal-performance relationship (PMC7672675)
Beatty (1982) - Task-evoked pupillary responses
Kahneman & Beatty (1966) - Pupil diameter and cognitive load
Marquart et al. (2015) - Blink rate and cognitive load

Motor Control & Grip Force:

Araki et al. (2021) - Robotic surgery grip force (PMID 27572059)
Olig et al. (2023) - Force control in minimally invasive surgery
Johansson & Westling (1984) - Grip force coordination

Tremor Analysis:

Wells (2013) - Physiological tremor (PMC3989364)
Becker (2008) - Tremor in surgical performance (PMC3032442)
Riviere et al. (1997) - Surgical tremor analysis

Heart Rate Variability:

De Louche et al. (2024) - HRV in surgical stress (BJS Open)
Böhm et al. (2001) - HRV and cognitive load

Cognitive Performance:

Warm et al. (2008) - Vigilance requires hard work
Hockey (1997) - Compensatory control model

📖 Full methodology: BIOSIGNAL_EVIDENCE_SUMMARY.md

📈 Future Directions

Technical Enhancements:

Real Sensor Integration: Connect with actual pupillometry and force sensors
Deep Learning Models: Explore LSTM/Transformer architectures for temporal data
Multi-Modal Fusion: Integrate additional physiological signals (heart rate, EEG)
Edge Computing: Deploy models for real-time inference on surgical devices

Clinical Validation:

Real-World Testing: Partner with surgical training centers for validation studies
Multi-Surgeon Studies: Extend to team-based surgical environments
Longitudinal Studies: Track cognitive state changes over extended procedures
Clinical Trials: Randomized controlled trials for safety and efficacy

📜 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the LICENSE file for details.

Why AGPL v3? This license ensures that any modifications to this surgical safety monitoring system remain open source, even when deployed as a web service. This is critical for patient safety - all improvements must be shared with the medical and research community.

👨‍💻 Author

Mohammad Dastgheib
PhD Candidate, Cognitive Neuroscience
Portfolio: mdastgheib.com
LinkedIn: mohdasti

🙏 Acknowledgments

This project synthesizes findings from 20+ peer-reviewed studies in cognitive neuroscience, motor control, cardiac physiology, and human factors engineering. The work represents a comprehensive implementation of evidence-based machine learning for real-time cognitive state monitoring, combining causal feature engineering, multi-model architecture, and deployment-ready applications for both research and clinical use.

Key Literature Sources:

Pupillometry: Wu et al. (2019), Beatty (1982), Kahneman & Beatty (1966)
Motor Control: Araki et al. (2021), Wells (2013), Becker (2008)
Cardiac Physiology: De Louche et al. (2024), Böhm et al. (2001)
Cognitive Load: Marquart et al. (2015), Warm et al. (2008), Hockey (1997)

All data used in this project is synthetic. No real patient data or PHI is involved.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
case_study/images		case_study/images
data/processed		data/processed
scripts		scripts
shiny_app		shiny_app
surgical-cognitive-dashboard-1		surgical-cognitive-dashboard-1
surgical-cognitive-dashboard-app		surgical-cognitive-dashboard-app
.gitignore		.gitignore
EMBED_SETUP.md		EMBED_SETUP.md
LICENSE		LICENSE
README.md		README.md
iframe_snippet_example.html		iframe_snippet_example.html
netlify_headers_example		netlify_headers_example
quarto_yml_patch_example		quarto_yml_patch_example

Latest commit

History

Folders and files

Repository files navigation