vizzu_animations

What this skill does

# Vizzu Animated Data Visualizations

**Purpose:** Animated data visualizations for medical content using Vizzu-lib. Perfect for trial results, survival curves, and medical dashboards.

**Status:** ✅ Complete - Ready for use

**Priority:** P1 - Fills critical gap: animated data visualizations

---

## Quick Start

```python
from vizzu_animations.templates import (
    create_animated_kaplan_meier,
    create_animated_forest_plot,
    create_animated_bar_comparison,
)

# Kaplan-Meier survival curves
treatment = [(0, 100), (6, 94), (12, 88), (18, 83), (24, 78)]
control = [(0, 100), (6, 91), (12, 83), (18, 76), (24, 69)]

create_animated_kaplan_meier(
    treatment, control,
    treatment_name="Dapagliflozin",
    control_name="Placebo",
    hr_text="HR 0.74 (95% CI 0.65-0.85)",
    output="kaplan_meier.html"
)
```

---

## Why Vizzu?

| Feature | Benefit |
|---------|---------|
| **Seamless transitions** | Smooth chart morphing (perfect for trial results over time) |
| **Dependency-free JS** | No heavy frameworks, just HTML5 canvas |
| **Python bindings** | ipyvizzu for Jupyter, or direct HTML generation |
| **Apache 2.0 license** | Permissive, commercial-friendly |
| **Design token integration** | Uses visual-design-system colors automatically |

**Fills gap:** Manim does educational animations, Vizzu does data animations.

---

## Medical Use Cases

### 1. Animated Kaplan-Meier Curves
Show survival divergence unfolding over time.

```python
from vizzu_animations.templates import create_animated_kaplan_meier

treatment = [(0, 100), (6, 94), (12, 88), (18, 83), (24, 78)]
control = [(0, 100), (6, 91), (12, 83), (18, 76), (24, 69)]

create_animated_kaplan_meier(
    treatment, control,
    title="DAPA-HF: Event-Free Survival",
    hr_text="HR 0.74 (95% CI 0.65-0.85)",
)
```

**Use for:** Trial results, survival analysis, event-free survival

### 2. Animated Forest Plots
Studies accumulating in meta-analysis.

```python
from vizzu_animations.templates import create_animated_forest_plot

studies = [
    {"name": "DAPA-HF", "estimate": 0.74, "lower": 0.65, "upper": 0.85, "weight": 60},
    {"name": "EMPEROR-Reduced", "estimate": 0.75, "lower": 0.65, "upper": 0.86, "weight": 50},
    {"name": "SOLOIST-WHF", "estimate": 0.67, "lower": 0.52, "upper": 0.85, "weight": 30},
]

create_animated_forest_plot(
    studies,
    title="SGLT2 Inhibitors in Heart Failure",
    show_pooled=True,
)
```

**Use for:** Meta-analyses, systematic reviews, pooled estimates

### 3. Animated Bar Comparisons
Before/after or treatment vs control.

```python
from vizzu_animations.templates import create_animated_bar_comparison

create_animated_bar_comparison(
    categories=["Primary Endpoint", "CV Death", "HF Hospitalization"],
    group1_values=[16.3, 11.6, 10.0],
    group2_values=[21.2, 14.5, 15.6],
    group1_name="Dapagliflozin",
    group2_name="Placebo",
    title="DAPA-HF Trial Results",
)
```

**Use for:** Treatment comparisons, before/after outcomes, subgroup analyses

### 4. Animated Trend Lines
Outcomes progressing over time.

```python
from vizzu_animations.templates import create_animated_trend_line

data = {
    "2010-2015": [(2010, 28.5), (2012, 26.2), (2015, 23.8)],
    "2015-2020": [(2015, 23.8), (2017, 21.5), (2020, 19.2)],
}

create_animated_trend_line(
    data,
    title="Heart Failure Mortality Trends",
    x_label="Year",
    y_label="Mortality Rate (per 100,000)",
)
```

**Use for:** Epidemiological trends, longitudinal outcomes, temporal patterns

### 5. Animated Trial Enrollment
Patient recruitment dashboard.

```python
from vizzu_animations.templates import create_animated_trial_enrollment

enrollment = [
    ("Month 1", 142),
    ("Month 3", 456),
    ("Month 6", 1024),
    ("Month 12", 3456),
    ("Month 18", 4744),
]

create_animated_trial_enrollment(
    enrollment,
    target=4744,
    title="DAPA-HF Enrollment Progress",
)
```

**Use for:** Trial dashboards, recruitment tracking, site performance

---

## CLI Usage

```bash
cd skills/cardiology/visual-design-system/vizzu_animations

# List available templates
python vizzu_cli.py list

# Generate all demos
python vizzu_cli.py demo --template all

# Generate specific demo
python vizzu_cli.py demo --template kaplan-meier --output km.html

# Create from custom data
python vizzu_cli.py create \
  --template bar \
  --data trial_results.csv \
  --x Treatment \
  --y EventRate \
  --title "Trial Results"

# Export HTML to video
python vizzu_cli.py export animation.html --format mp4
python vizzu_cli.py export animation.html --format gif --fps 15
python vizzu_cli.py export animation.html --format webm
```

---

## Python API

### Using Templates (Recommended)

```python
from vizzu_animations.templates import (
    create_animated_kaplan_meier,
    create_animated_forest_plot,
    create_animated_bar_comparison,
    create_animated_trend_line,
    create_animated_trial_enrollment,
)

# Each template returns Path to HTML file
output_path = create_animated_kaplan_meier(...)
print(f"Animation saved to: {output_path}")
```

### Using Low-Level API

```python
from vizzu_animations import VizzuAnimator
import pandas as pd

animator = VizzuAnimator()

# Prepare data
df = pd.DataFrame({
    'Study': ['DAPA-HF', 'EMPEROR-Reduced', 'DELIVER'],
    'HR': [0.74, 0.75, 0.82],
    'Treatment': ['Dapagliflozin', 'Empagliflozin', 'Dapagliflozin']
})

# Create animated bar chart
animator.create_animated_bar(
    df,
    x_col='Study',
    y_col='HR',
    color_col='Treatment',
    title='SGLT2i Heart Failure Trials',
    output='trials.html',
    duration=3000,  # 3 seconds
)
```

### Available Methods

| Method | Description |
|--------|-------------|
| `create_animated_bar()` | Animated bar chart |
| `create_animated_line()` | Animated line chart |
| `create_animated_scatter()` | Animated scatter plot |
| `create_animated_area()` | Animated area chart |

---

## Export to Video

### MP4 (Best for YouTube, presentations)

```python
from vizzu_animations.export_utils import export_to_mp4

export_to_mp4(
    'animation.html',
    'animation.mp4',
    duration=5000,  # 5 seconds
    fps=30,
    width=1920,
    height=1080,
)
```

### GIF (Best for Twitter, social media)

```python
from vizzu_animations.export_utils import export_to_gif

export_to_gif(
    'animation.html',
    'animation.gif',
    duration=5000,
    fps=15,  # Lower FPS for smaller file
    width=800,
    height=600,
    optimize=True,
)
```

### WebM (Best for web embedding)

```python
from vizzu_animations.export_utils import export_to_webm

export_to_webm(
    'animation.html',
    'animation.webm',
    duration=5000,
    fps=30,
)
```

**Requirements:**
- Playwright: `pip install playwright && playwright install chromium`
- ffmpeg: `apt-get install ffmpeg` or `brew install ffmpeg`
- Optional: `gifsicle` for GIF optimization

---

## Integration with Visual Router

Vizzu is automatically routed when you request animated data visualizations:

**Keywords that route to Vizzu:**
- "animated data"
- "animated chart"
- "animated forest plot"
- "animated survival curve"
- "animated enrollment"
- "chart transition"
- "morphing chart"

**Example:**
```
User: "Create an animated Kaplan-Meier curve showing treatment vs control"
→ Routes to: vizzu_animations/templates/kaplan_meier.py
```

---

## Design Token Integration

Vizzu automatically uses colors from the visual-design-system:

| Token | Color | Usage |
|-------|-------|-------|
| `primary` | #2d6a9f | Main data series |
| `secondary` | #48a9a6 | Secondary series |
| `success` | #2e7d32 | Positive outcomes |
| `danger` | #c62828 | Adverse events |
| `treatment` | #0077bb | Treatment arm |
| `control` | #ee7733 | Control arm |

All visualizations are:
- ✅ Colorblind-safe (Paul Tol palette)
- ✅ WCAG AA compliant (4.5:1 contrast minimum)
- ✅ Publication-grade (Helvetica, proper spacing)

---

## Directory Structure

```
vizzu_animations/
├── SKILL.md                    # This file
├── __init__.py                 #