scientific-viz/README.md

# scientific-viz

Claude Code skill for **publication-quality scientific visualizations** — charts (matplotlib/seaborn), neural-network architecture diagrams (matplotlib patches *or* Mermaid), block-scheme flowcharts, training-pipeline diagrams, and benchmark comparison figures. Tuned for the CVGL / NADEZHDA project but reusable for any deep-learning paper.

> Behaviour spec — see [`SKILL.md`](SKILL.md). This file is the human-facing entry point.

## When to use

- Need a figure for a paper / report / slide deck and want it consistent with project style.
- Want a Pareto plot (params vs R@1), grouped bar, radar, heatmap, or training curve.
- Need a Teacher–Student / multi-modal fusion architecture diagram.
- Need a Mermaid flowchart embeddable in Obsidian for an LUPI / KD pipeline.
- Want a quick comparison figure across CVGL benchmarks (University-1652, GeoText-1652, GTA-UAV, VisLoc).

## Invocation

```text
/scientific-viz <type> "<description>"
```

Where `<type> ∈ {chart, architecture, flowchart, comparison, pipeline}`.

**Examples**

```text
/scientific-viz chart        "R@1 comparison across methods on University-1652"
/scientific-viz architecture "Teacher-Student LUPI pipeline"
/scientific-viz flowchart    "Training progressive staging 3 phases"
/scientific-viz comparison   "Backbone candidates: params vs R@1"
/scientific-viz pipeline     "LUPI distillation flow with 7 losses"
```

## Five visualisation types

| Type | Output | Use for |
|------|--------|---------|
| `chart` | Python script (`.py`) **+** `.png` (300 DPI) **+** `.pdf` (vector) | metric comparisons, ablations, distributions, training curves |
| `architecture` | matplotlib patches Python (complex) **or** Mermaid (Obsidian-embeddable) | Teacher/Student, backbone stages, fusion modules, head designs |
| `flowchart` | Mermaid (`graph TD` / `graph LR`) + optional Python | training/inference pipeline, experimental workflow, data processing |
| `comparison` | Python `.py` + `.png/.pdf` | Pareto front, grouped bar, radar/spider, heatmap |
| `pipeline` | Mermaid + matplotlib | LUPI distillation flow, augmentation chain, edge deployment |

## Publication-quality defaults (charts)

Every generated `chart` / `comparison` / `pipeline` Python script starts with this rcParams block:

```python
import matplotlib
matplotlib.rcParams.update({
    'font.family': 'serif',
    'font.size': 11,
    'axes.labelsize': 12,
    'axes.titlesize': 13,
    'legend.fontsize': 10,
    'xtick.labelsize': 10,
    'ytick.labelsize': 10,
    'figure.dpi': 300,
    'savefig.dpi': 300,
    'savefig.bbox': 'tight',
    'axes.grid': True,
    'grid.alpha': 0.3,
})
```

Hard requirements baked in:

- ≥ 300 DPI, vector PDF + raster PNG saved side-by-side.
- Times New Roman / DejaVu Serif, ≥ 10 pt.
- Colorblind-safe palette (Okabe-Ito or `tab10`).
- English axis labels for publications, optional Russian for internal reports.
- Light-gray grid (`alpha=0.3`), tight layout, no clipped labels.

## NADEZHDA project palette (consistent across figures)

| Component | Colour | Hex |
|-----------|--------|-----|
| Teacher | Deep blue | `#1f77b4` |
| Student | Orange | `#ff7f0e` |
| Satellite modality | Green | `#2ca02c` |
| Drone modality | Red | `#d62728` |
| Street-view | Purple | `#9467bd` |
| Depth | Brown | `#8c564b` |
| Text | Pink | `#e377c2` |
| Loss / gradient | Gray | `#7f7f7f` |
| Edge / Jetson | Teal | `#17becf` |

## Mermaid conventions (architecture / flowchart / pipeline)

- `graph TD` — vertical flow (Teacher → Student stack).
- `graph LR` — horizontal pipeline (input → backbone → neck → heads).
- Thick arrows = main data flow · dashed arrows = gradient / loss signals.
- Loss labels on arrows: `L_task`, `L_LUPI`, `L_feat`, `L_RKD`, `L_seg`, `L_CVD_MI`, `L_CVD_Recon`.
- `style` / `classDef` to mark Teacher (blue), Student (orange), shared (green).

Ready-to-use templates: [`templates/architecture_nadezhda.md`](templates/architecture_nadezhda.md).

## Standard tensor shapes (for architecture annotations)

```
Input:      [B, 3, 256, 256]
Stage 1:    [B,  32,  96,  96]
Stage 2:    [B,  64,  48,  48]
Stage 3:    [B, 128,  24,  24]
Stage 4:    [B, 256,  12,  12]
Descriptor: [B, 512]   L2-normalized
```

## Installation

Drop this repo into your vault's Claude Code skills directory:

```bash
git clone https://git.lissad.keenetic.name/Pikaliov/scientific-viz.git \
    .claude/skills/scientific-viz
```

Or as a submodule:

```bash
git submodule add https://git.lissad.keenetic.name/Pikaliov/scientific-viz.git \
    .claude/skills/scientific-viz
```

Claude Code picks up the skill on the next session. Verify with `/help` — `/scientific-viz` should appear in the user-invocable list.

**Runtime dependencies** (charts & comparison types):

```bash
pip install matplotlib seaborn numpy
```

Mermaid output requires no Python — the diagram block embeds directly into Obsidian, GitHub-flavoured Markdown, or Quarto.

## File layout

```
scientific-viz/
├── README.md                                — this file
├── SKILL.md                                 — behaviour spec (5 types, generation pipeline)
├── reference/
│   └── chart_patterns.md                    — canonical Pareto/grouped-bar/radar/heatmap snippets
└── templates/
    └── architecture_nadezhda.md             — Mermaid templates for Teacher-Student / LUPI / fusion
```

## Hard constraints

- ❌ Никаких внешних API (OpenRouter, Gemini и т. п.) — только локальные библиотеки.
- ❌ Никакой растровой генерации архитектур через `PIL.ImageDraw` — только matplotlib `patches` или Mermaid.
- ✅ Всегда сохранять и `.py` скрипт, и результат (`.png`/`.pdf`) — рядом, рядом с заметкой / в `attachments/figures/`.
- ✅ Каждое значение в графике должно иметь источник (комментарий в коде или caption под фигурой).
- ✅ Для Obsidian — Mermaid-блок встраивается прямо в `.md`, без ссылок на внешние файлы.
- ✅ Для публикаций — английский язык подписей; для внутренних отчётов — RU допустим.

## Worked example

```text
/scientific-viz comparison "Pareto front: backbone params vs R@1 on University-1652, mark NADEZHDA target at 8.5M"
```

Expected output:

- `pareto_params_r1.py` — full matplotlib script with palette, grid, edge-budget shaded region, NADEZHDA marker as star.
- `pareto_params_r1.png` (300 DPI) + `pareto_params_r1.pdf` (vector) saved next to the script.
- Inline annotation list (Sample4Geo, VimGeo, QDFL, MobileGeo, (MGS)², NADEZHDA target).
- Source comment at the top of the script linking to `1_lit_research/СИНТЕЗ_всех_статей_для_LUPI_CVGL.md` rows.

See [`reference/chart_patterns.md`](reference/chart_patterns.md) for the canonical pattern this expands from.

## Allowed tools

`Read`, `Write`, `Edit`, `Bash`, `Glob`, `Grep` — the skill writes Python scripts and Mermaid blocks directly into the vault, then optionally executes the script via `Bash` to produce the rendered `.png`/`.pdf`.

## Related skills

- `/analyze-paper` — surfaces the numbers this skill plots.
- `/synthesize-review` — produces the cross-paper tables that feed `comparison` figures.
- `/generate-hypothesis` — the hypotheses whose evidence is plotted.