oscarzhang/health-timeseries-story-generator

🌟 Health Data Story Visualization System

Transform abstract health metrics into vivid, interactive stories that reveal the hidden patterns of human wellness.

中文版 README | English README

🎯 Why This Project Matters

The Problem: Health data is often abstract, fragmented, and hard to understand. Researchers, developers, and healthcare professionals struggle to:

• —Visualize how health metrics change throughout a day
• —Test anomaly detection algorithms with realistic scenarios
• —Understand how data collection frequency affects detection accuracy
• —Demonstrate health insights to non-technical audiences

Our Solution: An AI-powered visualization system that generates realistic 24-hour health stories, complete with physiological data, visual scenes, and anomaly simulations. It's not just a tool—it's a research platform for advancing wearable health technology.

✨ What Makes This Special

🧬 Realistic Health Data Generation

• —Algorithmically generates 10 core health metrics (HR, HRV, RHR, RR, BT, Steps, Calories, SD, DSR, SL)
• —Based on scientifically-grounded models of human physiology
• —Supports custom user profiles (age, gender, activity level)

🎨 AI-Powered Story Generation

• —Generate personalized 24-hour activity stories using AI
• —Support multiple themes (e.g., "A Chef's Day", "A Doctor's Shift", "A Thief's Day")
• —Multi-language support (English & Chinese)
• —Each story segment includes detailed activity descriptions and visual characteristics

🖼️ Dynamic Scene Visualization

• —AI-generated images for each activity scene
• —Supports multiple AI providers (Google Gemini, 302.ai)
• —Default images for common scenarios
• —Real-time scene switching based on story timeline

📊 Interactive Data Exploration

• —Real-time health metric visualization with adjustable sampling rates
• —Test how different collection frequencies affect anomaly detection
• —Discover the critical relationship between data granularity and health insights

⚠️ Anomaly Simulation & Testing

• —Pre-defined anomaly types (M1: Severe Fatigue, M2: Heart Rate Abnormality, M3: Sleep Deprivation, S1: Persistent Stress, S2: Exercise Recovery, S3: Potential Infection)
• —One-click anomaly injection into stories
• —Validate detection algorithms with realistic scenarios
• —Understand the impact of sampling frequency on anomaly detection

🔬 Research Applications

For Researchers

• —Algorithm Validation: Test anomaly detection algorithms with controlled scenarios
• —Parameter Optimization: Find optimal data collection frequencies for different health conditions
• —Clinical Studies: Simulate patient scenarios for research and training
• —Dataset Generation: Generate synthetic health time series datasets for machine learning model training

For Developers

• —Product Development: Prototype health monitoring features
• —Quality Assurance: Test edge cases and rare scenarios
• —User Education: Create engaging demos for stakeholders
• —ML/DL Training Data: Create labeled datasets for health prediction models

For Healthcare Professionals

• —Patient Education: Visualize health data in an intuitive way
• —Training: Practice interpreting health metrics in various scenarios
• —Consultation: Demonstrate health insights to patients

📊 Dataset Generation for Health Time Series Models

🎯 The Challenge: Data Scarcity in Health ML

Training machine learning models for health time series analysis faces a critical challenge: real-world health data is scarce, expensive to collect, and often lacks ground truth labels. This project addresses this gap by generating high-quality, labeled synthetic health datasets.

✨ What You Can Generate

1. Normal Health Time Series Datasets

• —Multi-metric sequences: Generate 24-hour sequences with 10 synchronized health metrics
• —Diverse profiles: Create datasets for different age groups, genders, and activity levels
• —Realistic patterns: Data follows physiological models (circadian rhythms, activity-response curves)
• —Multiple scenarios: Generate data for various lifestyles (office workers, athletes, students, etc.)
• —Export formats: CSV, JSON for easy integration with ML frameworks (PyTorch, TensorFlow, scikit-learn)

Example Use Cases:

• —Train baseline models for normal health pattern recognition
• —Create reference datasets for anomaly detection
• —Generate training data for activity classification models

2. Anomaly Detection Datasets

• —Labeled anomalies: Each data point tagged with anomaly type and severity
• —6 anomaly types: M1 (Fatigue), M2 (HR Abnormality), M3 (Sleep Deprivation), S1 (Stress), S2 (Recovery), S3 (Infection)
• —Controlled injection: Precisely control when, where, and how anomalies occur
• —Ground truth labels: Know exactly which time periods contain anomalies
• —Multiple severity levels: Generate mild, moderate, and severe anomaly cases

Example Use Cases:

• —Train supervised anomaly detection models
• —Benchmark anomaly detection algorithms
• —Create evaluation datasets with known ground truth
• —Test model sensitivity to different anomaly types

3. Sampling Frequency Variants

• —Same story, different frequencies: Generate the same scenario at 5-min, 10-min, 30-min, 1-hour intervals
• —Impact analysis: Study how sampling frequency affects model performance
• —Real-world simulation: Mimic different wearable device capabilities
• —Missing data patterns: Simulate realistic data gaps and missing values

Example Use Cases:

• —Optimize data collection strategies
• —Test model robustness to different sampling rates
• —Simulate battery-constrained scenarios
• —Research trade-offs between data quality and device lifetime

4. Multi-Day Sequences

• —Extended timelines: Generate 7-30 day sequences (planned feature)
• —Long-term patterns: Capture weekly rhythms and trends
• —Progressive anomalies: Simulate conditions that develop over days
• —Baseline establishment: Generate sufficient data for baseline calculation

Example Use Cases:

• —Train models for long-term health trend prediction
• —Study recovery patterns after anomalies
• —Research circadian rhythm variations
• —Develop personalized health baselines

📈 Dataset Characteristics

Data Structure

{
  "timestamp": "2025-01-15T14:30:00Z",
  "user_profile": {
    "age": 28,
    "gender": "MALE",
    "activity_level": "MED"
  },
  "metrics": {
    "HR": 72,           // bpm
    "HRV": 45,          // ms
    "RHR": 65,          // bpm (daily)
    "RR": 16,           // brpm
    "BT": 36.5,         // °C
    "Steps": 8500,      // steps
    "Calories": 450,    // kcal
    "SD": 480,          // minutes (daily)
    "DSR": 15,          // % (daily)
    "SL": 12            // minutes (daily)
  },
  "activity": {
    "sceneId": "OFFICE",
    "activityType": "Working",
    "intensity": "LOW",
    "startTime": "09:00",
    "endTime": "18:00"
  },
  "anomaly": {
    "type": null,       // or "M1", "M2", etc.
    "severity": null,   // or "MILD", "MODERATE", "SEVERE"
    "start_time": null,
    "end_time": null
  }
}

Dataset Sizes

• —Single day: ~1,440 data points (1-minute resolution) or ~144 points (10-minute resolution)
• —7 days: ~10,080 data points (1-minute) or ~1,008 points (10-minute)
• —30 days: ~43,200 data points (1-minute) or ~4,320 points (10-minute)
• —With anomalies: Configurable anomaly injection rates (e.g., 5%, 10%, 20% of time periods)

🔧 How to Generate Datasets

Step 1: Create Stories

// Generate multiple stories with different profiles
const stories = [
  generateStory({ age: 25, gender: 'MALE', activity: 'HIGH' }),
  generateStory({ age: 35, gender: 'FEMALE', activity: 'MED' }),
  generateStory({ age: 45, gender: 'MALE', activity: 'LOW' }),
  // ... more variations
];

Step 2: Inject Anomalies (Optional)

// Inject different anomaly types
stories.forEach(story => {
  injectAnomaly(story, {
    type: 'M2',           // Heart rate abnormality
    startTime: '14:00',
    duration: 60,        // minutes
    severity: 'MODERATE'
  });
});

Step 3: Export Data

// Export to CSV/JSON
exportToCSV(stories, {
  samplingRate: '10min',  // or '5min', '30min', '1hour'
  includeLabels: true,    // include anomaly labels
  format: 'long'          // or 'wide' format
});

🎓 Research Applications

For ML Researchers

• —Model Training: Generate large-scale datasets for deep learning models (LSTM, Transformer, CNN)
• —Data Augmentation: Create synthetic data to augment small real-world datasets
• —Transfer Learning: Generate source domain data for domain adaptation
• —Few-Shot Learning: Create support sets for meta-learning approaches

For Health AI Developers

• —Algorithm Benchmarking: Standardized datasets for comparing detection algorithms
• —A/B Testing: Generate controlled scenarios for testing model improvements
• —Edge Case Testing: Create rare but critical scenarios (e.g., sudden cardiac events)
• —Privacy-Preserving Research: Use synthetic data instead of sensitive real patient data

For Data Scientists

• —Feature Engineering: Explore relationships between metrics in controlled settings
• —Model Validation: Test models on known ground truth before deploying on real data
• —Sampling Strategy Research: Optimize data collection frequency for cost-effectiveness
• —Anomaly Detection Research: Study detection algorithms with labeled anomalies

📊 Example Research Questions You Can Answer

1. 1."What's the minimum sampling frequency needed to detect a 60-minute tachycardia?"
2. 2.Generate M2 anomalies at different sampling rates
3. 3.Test detection accuracy
4. 4.Find the optimal trade-off

1. 1."How does model performance change with different anomaly severities?"
2. 2.Generate datasets with mild, moderate, severe anomalies
3. 3.Train models on each
4. 4.Compare F1-scores, precision, recall

1. 1."Can we detect exercise recovery patterns with 30-minute sampling?"
2. 2.Generate S2 anomalies
3. 3.Create datasets at 5-min, 10-min, 30-min intervals
4. 4.Evaluate model performance at each frequency

1. 1."What's the best architecture for multi-metric health anomaly detection?"
2. 2.Generate labeled datasets with multiple anomaly types
3. 3.Train different architectures (LSTM, Transformer, CNN)
4. 4.Compare performance

🚀 Future Dataset Features

• —[ ] Multi-day sequences (7-30 days) for long-term pattern learning
• —[ ] Batch generation API for large-scale dataset creation
• —[ ] Custom anomaly definitions via configuration files
• —[ ] Noise injection to simulate sensor errors
• —[ ] Missing data patterns to test robustness
• —[ ] Temporal alignment for multi-user datasets
• —[ ] Pre-computed datasets for common research scenarios

🚀 Key Features

1. Intelligent Story Generation

• —AI creates realistic 24-hour activity sequences
• —Each story includes:
• —Time-stamped activity segments
• —Activity types and intensities
• —Scene classifications (20+ scene types)
• —Multi-language descriptions

2. Physiological Data Modeling

• —Heart Rate (HR): 40-200 bpm, varies by activity intensity
• —Heart Rate Variability (HRV): 0-200 ms, reflects stress and recovery
• —Resting Heart Rate (RHR): Measured daily at 6:00 AM
• —Respiratory Rate (RR): 8-40 brpm, responds to activity and stress
• —Body Temperature (BT): 35-40°C, follows circadian rhythm
• —Steps & Calories: Activity-based calculations
• —Sleep Metrics (SD, DSR, SL): Measured daily, reflects sleep quality

3. Sampling Frequency Impact Analysis

• —Adjust collection frequency (5 min, 10 min, 30 min, 1 hour)
• —Observe how frequency affects:
• —Ability to detect short-term anomalies (e.g., M2: 60-minute tachycardia)
• —Accuracy of trend detection (e.g., S2: 24-hour recovery patterns)
• —Data visualization quality

4. Anomaly Detection Framework

• —M1 - Severe Fatigue: HRV < 30ms, RHR > 85bpm, DSR < 10% (3 days)
• —M2 - Heart Rate Abnormality: HR > 120bpm or < 50bpm in non-active state (60 min)
• —M3 - Sleep Deprivation: SD < 360 min (3 days)
• —S1 - Persistent Stress: HRV < 40ms, RHR > 80bpm (5 days)
• —S2 - Exercise Recovery: RHR ↑ > 10%, HRV ↓ > 20% after intense exercise (24 hours)
• —S3 - Potential Infection: BT > 37.3°C, RHR ↑ > 10%, RR > 20 brpm (24 hours)

🛠️ Technology Stack

• —Frontend: React 19 + TypeScript + Vite
• —Visualization: Recharts for data visualization
• —AI Integration:
• —Story Generation: 302.ai Chat API (Qwen/Qwen2.5-Coder-32B-Instruct)
• —Image Generation: Google Gemini API, 302.ai SDXL Lightning
• —UI Components: Lucide React Icons
• —Data Processing: Custom algorithms for health metric generation

📦 Quick Start

Prerequisites

• —Node.js 18+
• —API Keys (optional, for AI features):
• —Google Gemini API key (for image generation)
• —302.ai API key (for story and image generation)

Installation

# Clone the repository
git clone <repository-url>
cd health-data-story-visualization-system

# Install dependencies
npm install

# Set up environment variables (optional)
# Create .env.local file with:
# VITE_GEMINI_API_KEY=your_gemini_api_key
# VITE_API_302_KEY=your_302_api_key

# Start development server
npm run dev

Visit http://localhost:5173 to see the application.

🎓 Use Cases

Scenario 1: Testing Anomaly Detection Algorithm

1. 1.Generate a default 24-hour story
2. 2.Inject M2 anomaly (heart rate abnormality) at 14:00
3. 3.Adjust sampling frequency to 10 minutes
4. 4.Verify if the algorithm can detect the anomaly
5. 5.Compare results with 5-minute vs 30-minute sampling

Scenario 2: Demonstrating Health Insights

1. 1.Generate "A Chef's Day" story
2. 2.Show how heart rate varies during different activities
3. 3.Highlight the relationship between activity intensity and HRV
4. 4.Export data for presentation

Scenario 3: Research on Sampling Frequency

1. 1.Generate multiple stories with different activity patterns
2. 2.Inject the same anomaly (e.g., S2: Exercise Recovery)
3. 3.Test detection accuracy at different sampling frequencies
4. 4.Document findings for research paper

Scenario 4: Generating Training Datasets for ML Models

1. 1.Generate 100+ stories with diverse user profiles
2. 2.Inject various anomaly types at different severities
3. 3.Export data at multiple sampling frequencies (5-min, 10-min, 30-min)
4. 4.Use datasets to train LSTM/Transformer models for anomaly detection
5. 5.Benchmark model performance on synthetic vs. real data

🔮 Future Vision

This project is just the beginning. We envision:

Short-term Goals

• —[ ] Support multi-day stories (7-30 days)
• —[ ] Add more anomaly types and severity levels
• —[ ] Implement real-time anomaly detection algorithms
• —[ ] Export data in multiple formats (CSV, JSON, Excel)

Long-term Vision

• —[ ] Clinical Integration: Connect with real patient data (anonymized)
• —[ ] Machine Learning: Train models on generated scenarios
• —[ ] Collaborative Research: Open platform for researchers to share scenarios
• —[ ] Mobile App: Native mobile experience for on-the-go analysis
• —[ ] API Service: Provide health data generation as a service

🤝 How You Can Support

For Researchers

• —Use the platform for your research and share findings
• —Contribute scenarios and anomaly definitions
• —Provide feedback on data accuracy and realism
• —Collaborate on research papers and publications

For Developers

• —Contribute code to improve features and performance
• —Report bugs and suggest improvements
• —Build integrations with other health platforms
• —Create plugins for custom anomaly types

For Healthcare Professionals

• —Validate the physiological models
• —Suggest clinical scenarios to add
• —Test the system with real-world use cases
• —Share insights on health metric interpretation

For Everyone

• —Star the repository if you find it useful
• —Share the project with others who might benefit
• —Provide feedback on user experience
• —Support the project's continued development

📄 License

[Specify your license here]

🙏 Acknowledgments

• —Inspired by the need to make health data more accessible and understandable
• —Built with the goal of advancing wearable health technology research
• —Thanks to all contributors and supporters

📧 Contact & Collaboration

Interested in collaborating or have questions?

• —Open an issue for bug reports or feature requests
• —Start a discussion for research collaboration
• —Reach out for partnership opportunities

Together, we can make health data visualization more intuitive, research more accessible, and health insights more actionable.

This project represents a step forward in making health data meaningful. Your support helps us continue this important work.