CommunityBildgithub.com

research-figure-builder

Erstellt aus wissenschaftlichen Datentabellen publikationsfertige Abbildungen: deklarative Datenbereinigung mit Zeilen-Herkunft, automatische Diagrammauswahl nach Daten und Forschungsziel, statistische Grafiken mit R/ggplot2 sowie Export als PDF, 600-dpi-PNG und editierbares SVG – inklusive unabhängiger numerischer Prüfung, easyplot-Metadaten-/Palettenaudit, echtem Rendering-Beschnitt und zweifacher vollständiger Wiederholungsvalidierung.

Was ist research-figure-builder?

Dieses Skill wandelt wissenschaftliche Datentabellen in publikationsreife Abbildungen um, wobei jedes Daten-Element auf der Grafik auf die Quelldaten zurückverfolgt werden kann. Es unterstützt deklarative Datenbereinigung mit Herkunftsnachweis auf Zeilenebene, die automatische Auswahl des geeignetsten Diagrammtyps basierend auf Datenstruktur und Forschungsziel (z.B. Vergleich, Korrelation, Trend, Verteilung, Zusammensetzung) sowie die statistische Auswertung und grafische Umsetzung mittels R/ggplot2. Die Ausgabe erfolgt standardmäßig in drei Formaten: PDF, 600-dpi-PNG und editierbares SVG. Ein mehrstufiges Qualitätssicherungssystem umfasst eine unabhängige numerische Neuberechnung statistischer Kennzahlen, ein easyplot-basiertes Audit von Metadaten und Farbpaletten, eine Überprüfung der tatsächlichen Rendering-Ränder sowie eine zweifache vollständige Wiederholung der gesamten Pipeline zur Sicherstellung der Reproduzierbarkeit. Das Skill ist für den Einsatz in containerisierten Umgebungen (z.B. Harbor) konzipiert und wird über eine Kommandozeilen-Pipeline gesteuert: Datenvorbereitung in Python, statistische Grafik in R, Export und Validierung. Es behandelt Ausnahmen wie fehlende Pakete, nicht unterstützte Exportformate und Datenqualitätsprobleme transparent und protokolliert alle Anpassungen für maximale Nachvollziehbarkeit.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Hao-IANWY/research-figure-builder/tree/HEAD

Installed? Explore more Bild skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Wissenschaftliche Datenvisualisierung (research-figure-builder)

Ziel ist nicht „eine Grafik zu zeichnen“, sondern jedes Daten-Element in der Grafik auf die Quelldaten zurückführen zu können und anderen zu ermöglichen, mit beigelegten Schnappschüssen und Skripten dasselbe Artefakt neu zu erstellen.

Wann verwenden

  • Eingabe von wissenschaftlichen Datentabellen und Abbildungsaufgaben, die echte Grafiken, statistische Kennzahlen, Legenden und Reproduzierbarkeitsnachweise erfordern.
  • Benötigt werden Vergleiche, Korrelationen, Trends, Verteilungen, Zusammensetzungen, Kategorienzählungen oder Korrelations-Hitzekarten.
  • Es müssen Zeitschriften-Spaltenbreite, Leinwand, DPI, Schriftart oder Exportformat festgelegt werden.
  • Es müssen fehlende, nicht-endliche, duplizierte, kleine Stichproben und zu viele Kategorien identifiziert werden – ohne stillschweigendes Löschen von Daten.

Nicht geeignet für: Versuchsdesign, statistische Methodenentwicklung, nachträgliche Bildverschönerung oder interaktive Dashboards. Signifikanzmarkierungen werden nur akzeptiert, wenn sie bereits mit Angabe der statistischen Methode/Korrekturmethode geliefert werden; automatisch generierte Sternchen sind nicht erlaubt.

Eingabe

  1. Lese das tatsächliche /input/case.json, /input/task.md und die Fallmaterialien; die Aufgabe wird nicht anhand des Datensatznamens erraten.

  2. Daten unterstützen Inline-dataset.rows, CSV, TSV, JSON und schreibgeschütztes SQLite. Relative Pfade werden relativ zum Verzeichnis des Falls aufgelöst; wenn der Fall in Verzeichnisse wie /app/work verschoben wird, erfolgt eine automatische Rückfallsuche in den input/-Verzeichnissen aller übergeordneten Ebenen, dem aktuellen Verzeichnis und /input (Harbor-Layout). Wenn alles fehlschlägt, werden die vollständigen versuchten Pfade gemeldet; der Dateninhalt wird nicht erraten.

  3. Die Abbildungsaufträge figure_requests[] unterstützen:

    • figure_id, purpose, chart_hint/chart_type
    • x, y, group, variables, unit_id/replicate_unit, label
    • x_label, y_label, x_unit, unit/y_unit, title, panel
    • error_bar=sd|se|ci95|none, fit_group, significance
    • venue, width_mm, height_mm, dpi, format/formats
  4. Aus dem data_dictionary fließen label/type/unit/missing_values/sentinels in die Beschriftung, den Typ und die Bereinigungsregeln ein. Sentinel-Werte wie -999 bei numerischen Typen müssen explizit deklariert werden; es wird nicht global geraten. Der kurze label aus dem Datenwörterbuch hat Vorrang als Anzeigename auf Achsen (z.B. bei Hitzekarten); die ursprünglichen Spaltennamen bleiben in der Herkunft und Analyse erhalten.

  5. Wenn der Fall nur eine natürlichsprachliche Aufgabe ohne figure_requests enthält, erzeugt der Agent zunächst im /app/work einen Arbeitsfall, der die ursprüngliche case_id, die Datenreferenz und den output_contract beibehält, und ergänzt nur die strukturierten Aufträge. Relative Datenpfade müssen nicht umgeschrieben werden (Rückfallauflösung gemäß Punkt 2). Diese Umwandlung wird im Evidenznachweis dokumentiert; es werden keine Daten gefälscht. Beispiele für Auftragszuordnung (Bedeutung der ursprünglichen Aufgabe beibehalten, keine Schlussfolgerungen hinzufügen, die die Aufgabe nicht erwähnt):

    Aufgabe: „Vergleiche die Expressionsunterschiede von drei Genotypen, Fehlerbalken mit Standardfehler“ →

    {"figure_id":"F1","purpose":"comparison","x":"Genotyp","y":"Expression","error_bar":"se",
     "x_label":"Genotyp","y_label":"Expression","title":"Vergleich der Expression von drei Genotypen"}
    

    Begründung der Diagrammauswahl in den Auftragsumwandlungsnotizen: purpose=comparison und explizite Fehlerbalken → bar_with_error_points (Mittelwertbalken + alle Rohdatenpunkte); Kreisdiagramm abgelehnt (ungeordnete Kategorien ohne Winkelkodierung).

    Aufgabe: „Zusammenhang zwischen Blütenblattlänge und -breite, farbcodiert nach Art, mit Anpassung und Konfidenzband“ →

    {"figure_id":"F2","purpose":"correlation","x":"petal_length_cm","y":"petal_width_cm",
     "group":"species","fit_group":true,"x_label":"Blütenblattlänge","y_label":"Blütenblattbreite"}
    

    Liniendiagramm abgelehnt (ungeordnete Beobachtungen werden nicht verbunden); fit_group=true erst ermöglicht gruppierte Anpassung.

    Aufgabe: „Explorativ die Korrelationsstruktur aller Variablen ansehen“ → {"figure_id":"F3","purpose":"correlation","chart_hint":"heatmap"} (Wenn Variablen nicht aufgelistet sind, werden sie automatisch anhand der kontinuierlichen Spalten im Datenwörterbuch erkannt; diese Entscheidung wird dokumentiert).

Ausführung

Direkt in der Produktionsumgebung ausführen:

python3 -B /skills/weekly-skill/scripts/pipeline.py \
  --case /input/case.json --task /input/task.md --out /app/output
python3 -B /skills/weekly-skill/scripts/validate.py \
  --case /input/case.json --result /app/output/result.json
python3 -B /skills/weekly-skill/scripts/validate_figures.py \
  --result /app/output/result.json

Abhängigkeiten: Rscript + ggplot2 + ggprism + svglite + jsonlite + systemfonts; Python-Audit verwendet Pillow und pypdf. Fehlende Abhängigkeiten: Es werden Schnappschüsse, Ausführungspläne und Skripte gespeichert; der Status wird als teilweise abgeschlossen markiert und die fehlenden Elemente aufgelistet. Falls dem Container R-Pakete fehlen und Netzwerk vorhanden ist, kann zunächst eine Kaltstartinstallation und dann eine Wiederholung erfolgen:

Rscript -e 'install.packages(c("ggplot2","ggprism","svglite","jsonlite","systemfonts"), repos="https://cloud.r-project.org")'
python3 -m pip install --user Pillow pypdf

Fehlgeschlagene Installationen blockieren nicht: Die Ergebnisse der Abhängigkeitserkennung werden in dependencies.json geschrieben; die gelieferten Materialien werden ehrlich entsprechend dem teilweise abgeschlossenen Umfang herabgestuft.

Ablauf

1. Eingabe und Vertrag einfrieren

source_data.tsv, ursprüngliche Quelle/Hash, run_plan.json, Bereinigungsregeln und Abhängigkeitsversionen speichern. Den output_contract des Falls dynamisch binden; nicht erzeugte Felder werden explizit in status.unmet aufgeführt.

2. Shell/Python nur zur Datenaufbereitung

data_prep.sh ruft scripts/prepare_data.py auf, erzeugt eine saubere TSV-Datei, zeichnet keine Grafiken:

  • Standard-Fehlermarkierungen: Leerwerte, NA, N/A, NaN, null, None, .
  • Nicht-endliche und nicht parsbare numerische Werte werden ausgeschlossen; die ursprüngliche Zeilennummer und der Grund werden protokolliert.
  • Vollständig doppelte Zeilen werden standardmäßig beibehalten und gemeldet; nur bei explizitem drop_duplicates=true werden sie gelöscht.
  • Kategorien werden nicht auf die ersten N beschränkt; bei vielen Kategorien werden alle beibehalten und das Layout angepasst.
  • Ausgabe: cleaned_data.tsv, figure_N.tsv, figure_N_lineage.json, data_quality.json.

3. R/ggplot2 Statistik und Grafik

plot.R liest nur TSV und Ausführungsplan, ruft theme.R auf:

RouteTatsächliche Darstellung
bar_with_error_pointsOriginale Jitter-Punkte + Mittelwertbalken + explizite SD/SE/95%-CI
comparison_auton<3 nur Punkte; 3–9 Punkte mit deklarierter Zusammenfassung; je Gruppe n≥10 Boxplot + Jitter
boxplot_points / violin_pointsExpliziter Boxplot/Violin + Jitter; bei n<3 pro Gruppe Herabstufung zu Punktdiagramm mit Protokollierung
scatter_with_fitStreudiagramm + globale OLS mit 95%-Konfidenzband; fit_group=true erst ermöglicht gruppierte Anpassung; doppelte Kodierung (Farbe + Form)
line_seriesSortiert nach echter Zeit/geordnetem numerischen Wert; Farbe + Linientyp; bei doppelten Punkten Mittelwerttrend, Originalpunkte beibehalten
histogramSturges-Bin-Einteilung, optional facettiert nach Gruppe
stacked_barExplizite Gesamt-/Gruppenfelder; Skala an der Oberseite der Balken basierend auf kumulativer Summe; bei keiner Gruppe sortierte horizontale Balken
category_countKategorienzählung, sortierte horizontale Balken
correlation_heatmapPairwise-complete Pearson; konstante Spalten/zu wenige gültige Paare → NA; divergierende Farbskala fest auf [-1,1] mit Farbbalken

SD/SE/CI bei n=1, Korrelationen mit konstanten Variablen und Anpassungen mit Null-X-Varianz sind alle null, werden nicht als 0 geschrieben. Balken beginnen bei 0; die maximale Skala überdeckt die Balkenoberkante und Fehlerbalken.

Automatische Lesbarkeitsverteidigung (keine Datenbeschneidung): Die Basisschriftgröße der gesamten Grafik wird durch min(Breite, 1,55×Höhe) gesteuert; breite/flache Leinwände vergrößern die Schrift nicht proportional. Der Punktdurchmesser von Streudiagrammen/Liniendiagrammen wird basierend auf der Dichte „verfügbare Zeichenfläche / Punktanzahl“ skaliert (untere Grenze 0,9 mm). Bei mehr als 8 Kategorien wird auf horizontales Layout umgestellt und die Leinwandhöhe automatisch basierend auf der Zeilenanzahl erhöht (gedeckelt bei max_height_mm); bei unzureichendem Zeilenabstand wird die Kategoriebeschriftungsgröße verkleinert (untere Grenze 6 pt). Bei vorhergesagter Überlappung vertikaler Layouts wird auf 45°-Drehung umgestellt. Die Hitzekartenhöhe wird basierend auf Variablenanzahl und Breite erhöht; Achsenbeschriftungen bevorzugen den kurzen Namen aus dem Datenwörterbuch und entfernen Klammern mit Einheiten; wenn die horizontale Projektion nicht passt, wird auf 90° hochgestuft; die Schriftgröße wird basierend auf der Zellenbreite skaliert; Zahlen in den Zellen werden basierend auf der Zellenbreite dimensioniert (obere Grenze ~9 pt, bei Zellen <5,5 mm oder >12 Variablen weggelassen). Die Zeitachse wird basierend auf der Leinwandbreite gedeckelt und ausgedünnt, mit zweizeiligen „MM-DD / YYYY“-Beschriftungen. Titel werden basierend auf der Leinwandbreite umgebrochen. Jede Anpassung wird in layout_adjustment, sowie in den Notes und Warnings der Analyse protokolliert und ist nachvollziehbar.

4. Export in drei Formaten

Standardmäßig werden für jede Grafik erzeugt:

  • figure_N.pdf: Cairo PDF, Prüfung der tatsächlichen Seitengröße und Schriftarteinbettungsnachweise.
  • figure_N.png: Standard 600 dpi, Aufgabe kann höhere/niedrigere anfordern, jedoch nicht unter 300 dpi.
  • figure_N.svg: svglite, behält bearbeitbaren <text> bei.
  • figure_N.tsv + figure_N.csv, figure_N_spec.json, figure_N_analysis.json, figure_N_lineage.json.

Auch wenn der Benutzer nur PDF anfordert, werden PNG-Vorschau und SVG-Bearbeitungsdatei beibehalten. Exportformat-Stufen: Wenn ein angefordertes und unterstütztes Format (PDF/PNG/SVG) fehlt, darf diese Grafik nicht als vollständig markiert werden; wenn ein nicht unterstütztes Format (z.B. EMF) angefordert wird, wird dies als format_gaps-Lücke außerhalb des Bereichs protokolliert, die Standard-Drei-Formate werden geliefert; es wird weder ignoriert noch gefälscht.

5. Vierstufige Qualitätssicherung

  1. Wissenschaftliche Darstellung: Konsistenz von Diagrammtyp, Gruppierung, Einheit, Fehlerbalken, Signifikanz und Legendenbeschriftung.
  2. Numerische Überprüfung: Unabhängige Python-Neuberechnung von Mittelwert/SD/SE, OLS/Pearson und Korrelationsmatrix; Abgleich mit R-Ergebnissen.
  3. Datei- und visuelle Prüfung: easyplot-Prüfung von Größe/DPI/PDF-Schriftart/SVG-Text; Prüfung von PNG auf Nicht-Leerheit, tatsächliche Ränder und Palettenkontext. Rand-Semantik: Leere Grafik oder Inhalte, die den Rand berühren/beschnitten sind (<0,02 Zoll vom Leinwandrand) gelten als Fehlschlag; ein Rand unter 0,1 Zoll wird nur mit dem Flag tight markiert, eine ansonsten korrekte Grafik wird nicht als teilweise abgeschlossen eingestuft.
  4. Ende-zu-Ende-Reproduktion: Erneute Ausführung von data_prep.sh + plot.R + normalize_pdf.py aus dem beigelegten Original-Schnappschuss; Vergleich der SHA-256 von Plot-TSV/CSV, Lineage, Statistik-JSON, PDF, PNG, SVG. Die PDF-Normalisierung setzt nur die CreationDate/ModDate von Cairo/pypdf auf Unix-Epoche fest; Seite, Schriftart oder Grafikinhalt werden nicht geändert.

Nach Abschluss der automatischen Prüfung muss der Agent das tatsächliche PNG ansehen (und bei Bedarf PDF rendern), um Beschriftungsüberlappungen, verstümmelten Text, Überdeckungen und wissenschaftliche Semantik zu prüfen. Die Pixelrandprüfung ist kein Ersatz für eine menschliche/multimodale visuelle Überprüfung.

Ausgabe

result.json behält case_id und den ursprünglichen Ausgabevertrag bei und enthält:

  • figures: Pro-Grafik-Route, tatsächlicher Diagrammtyp, Vorbereitungsprotokoll, R-Analyse, unabhängige Legende, Dateimetadaten/Hash, QA, Ergebnis der vollständigen Pipeline-Wiederholung, layout_adjustment (Layout-Anpassungsprotokoll) und format_gaps (Lücken bei nicht unterstützten Formaten).
  • data_to_visual_map: Quellspalten → visueller Kanal, Plot-TSV und Zeilen-Herkunft.
  • baseline_comparison: Siebendimensionale deterministische Sicherheitsabwehr im Vergleich zu Basis-Agenten/Allzweck-Plot-Lösungen (Diagrammauswahl/Achsen/Kodierungslesbarkeit/Beschriftung und Legende/Exportspezifikation/Reproduktionsnachweise/Ausnahmebehandlung); jeder Punkt enthält typische Fehlermodi, Behandlung durch dieses Skill und Evidenzposition. Der plattformseitige faire Vergleich wird von der Organisation selbst durchgeführt; diese Tabelle erfindet keine Basislinienzahlen.
  • evidence_map: Quellschnappschuss, Ausführungsplan, Regel-Hash, Abhängigkeiten, Skripte und Reproduktionsbefehle.
  • Statusbeschreibung: Konsistent mit status.overall: Lücken, Erläuterungen und Unsicherheiten.

Alle Lieferdateien befinden sich in /app/output. Unabhängige Wiederholung möglich:

cd /app/output
bash data_prep.sh
Rscript plot.R
python3 -B scripts/normalize_pdf.py --plan run_plan.json --out .
python3 -B scripts/audit_outputs.py --plan run_plan.json --out .

Ausnahmebehandlung

SituationVerhalten
Fall nicht parsbar, doppelte Spaltennamen, fehlende FelderEhrlichen Fehler/Teilergebnis und Lücken schreiben; keine Grafiken fälschen
Fehlende/NaN/Inf/deklarierte Sentinel-WerteDiese Beobachtung aus der Grafik ausschließen; ursprüngliche Zeilennummer und Grund beibehalten
Vollständige DuplikateStandardmäßig beibehalten und melden; nur bei expliziter Regel deduplizieren
Eine Gruppe mit n=1Originalpunkte zeichnen; SD/SE/CI sind null
Konstante Korrelation/Null-X-VarianzNur verfügbare Punkte zeichnen; Korrelation/Anpassung ist null
Zu viele Kategorien oder SerienNicht beschneiden; Leinwand automatisch erhöhen/horizontales Layout/Schriftgröße verkleinern/Facetten anwenden und layout_adjustment protokollieren; bei Überschreitung der maximalen Höhe explizit darauf hinweisen, dass Beschriftungen möglicherweise noch dicht sind
Hitzekarte: viele Variablen/lange BeschriftungenLeinwand basierend auf Variablenanzahl und Breite erhöhen; kurzen Namen aus Datenwörterbuch verwenden + Klammern mit Einheiten entfernen; Winkel 45°→90° automatisch anpassen; Schriftgröße basierend auf Zellenbreite skalieren (≥6 pt); bei >12 Variablen Zahlen in Zellen weglassen
Datumsskala dichtSkala basierend auf Leinwandbreite gedeckelt und ausgedünnt; zweizeilige MM-DD/YYYY-Beschriftungen
Anforderung eines nicht unterstützten Exportformats (z.B. EMF)format_gaps-Lücke außerhalb des Bereichs protokollieren und Standard-Drei-Formate liefern; nicht als teilweise abschließen oder stillschweigend ignorieren
Aufgabe liefert SignifikanzergebnisseDurchreichen und rendern: gepaart → Klammerlinie + Annotation; einzelne Kategorie → Buchstaben am Gruppenende; Legende erwähnt Methode und „keine Tests berechnet“; niemals selbst Sternchen erzeugen
Fehlende R-Pakete, Schriftarten, Pillow, pypdfWiederholbare Materialien speichern und nicht abgeschlossene Elemente klar benennen; bei Netzwerk können Pakete mit Kaltstartbefehlen installiert und neu ausgeführt werden; wenn matplotlib verfügbar ist, echte PNGs rendern (300 dpi+, nur PNG; Lücken bei PDF/SVG ehrlich protokollieren, nicht fälschen)
Datenpfad ungültigRückfallsuche über mehrere Basisverzeichnisse; bei weiterem Fehlschlag alle versuchten Pfade melden
Einzelne Grafik schlägt fehlAndere Grafiken fortsetzen; für diese Grafik status=error und echten Grund schreiben
Irgendeine Grafik- oder QA-FehlschlägeGesamtstatus = partial, nicht complete schreiben

Selbsttest

# Vom Repository-Stammverzeichnis aus ausführen
python3 -B answer/060_科研数据可视化/scripts/test_pipeline.py
python3 answer/_shared/verify.py --only 060

Das Mindestbeispiel muss bestehen: Allgemeiner Vertrag PASS, Grafikspezifisch PASS, jede Grafik in drei Formaten vorhanden, QA vollständig bestanden, SHA-256-Hash zweier vollständiger Durchläufe identisch. Bei wiederholter Ausführung darf sich nur generated_at ändern.

Methodenquellen und Lizenz

  • Dieses sci-plot: R/ggplot2, ggprism-Theme, Arial/Cairo, svglite, Sturges, Skalenüberdeckung und visuelle QA-Regeln.
  • Rimagination/easyplot Commit d150e01: Wiederverwendung von easyplot_metadata.py und easyplot_palette_audit.py; MIT-Original in scripts/easyplot-LICENSE.txt.
  • Chinesische Beschriftungen sind eine Anforderung an die Eingabetreue dieses Problems: Standardmäßig Arial; nur wenn tatsächliche Beschriftungen CJK erfordern, wird eine echte chinesische Schriftart ausgewählt und protokolliert; ein Rückfall auf fehlende Zeichen wird nicht als Erfolg gewertet.

Minimales Ausführungsbeispiel

cd answer/060_科研数据可视化
python3 -B scripts/pipeline.py \
  --case examples/min_example/input/case.json --out /tmp/figure060-demo
python3 -B scripts/validate.py \
  --case examples/min_example/input/case.json --result /tmp/figure060-demo/result.json
python3 -B scripts/validate_figures.py --result /tmp/figure060-demo/result.json

Das Beispiel verwendet 24 synthetische Datenzeilen und enthält einen Gruppenvergleich und eine Korrelationsgrafik; die Beispielausgabe dient nur zur Regression und ist kein offizielles Fallergebnis.

Verwandte Skills