evalrx 0.1.2__py3-none-any.whl

evalrx/agent_assets/skills/nature-figure/references/nature-2026-observations.md

@@ -0,0 +1,112 @@
+# 2026 Nature Sample Observations
+
+This note captures page-level figure patterns observed from a local 2026 sample of `Nature`
+papers, plus one `Nature Biomedical Engineering` paper used as a clinical / ML-adjacent
+cross-check.
+
+Sampled figure sources:
+
+- `s41586-026-10408-8` — wide schematic-led materials figure with supporting quant panels
+- `s41586-026-10426-6` — dark whole-brain image plate with repeated views
+- `s41586-026-10393-y` — clinical triptych: longitudinal lines, forest plots, summary bars
+- `s41586-026-10257-5` — dense categorical stacked-area panels with direct labels
+- `s41586-026-10439-1` — asymmetric genomics figure with one dominant circular panel
+- `Expert-level detection of pathologies...` — compact medical / ML figure conventions
+
+## Archetype 1: Schematic-led composite
+
+Seen in the printable meta-assemblies paper.
+
+Actionable rules:
+
+- Let the schematic occupy roughly `45–60%` of figure height.
+- Use the **same physical/material palette** in the supporting plots; do not switch to generic method colors below the schematic.
+- Zoom callouts should use one repeated accent style across the figure, for example a single dashed red outline family.
+- Reserve at least one supporting panel for a real-world photograph or experimental snapshot when the story needs scale validation.
+- Supporting quantitative panels should be smaller, cleaner and less saturated than the schematic so the eye reads the page in the intended order.
+
+## Archetype 2: Dark image plate
+
+Seen in the astrocyte brain-network figure.
+
+Actionable rules:
+
+- Use a black facecolor only for the image plate region, not for the whole page.
+- Pair grayscale context with one or two fluorescent channels; the sample repeatedly used cyan and magenta.
+- Keep crops, scale bars and view boxes geometrically consistent across rows and columns.
+- Use white gutters and white scale bars so the plate stays legible after print/export compression.
+- Put row labels and channel labels directly on the image plate; avoid detached legends.
+
+Recommended accent set for this modality:
+
+```python
+CYAN = "#22D7E6"
+MAGENTA = "#FF2AD4"
+GREY_CONTEXT = "#B8B8B8"
+```
+
+## Archetype 3: Clinical triptych
+
+Seen in the OTOF gene-therapy paper.
+
+Actionable rules:
+
+- Top row: line plots or longitudinal summaries, usually sharing one legend strip above the row.
+- Middle row: forest-plot style effects with a dashed vertical reference line and light category bands.
+- Bottom row: compact summary bars, often binary or stacked-percentage bars.
+- Keep columns semantically parallel. If the first column is `ABR`, the next columns should reuse the same row logic rather than introducing a new layout.
+- Baseline / reference series can be black or dark grey; follow-up or intervention groups can use a restrained warm/cool sequence.
+
+Recommended design signal:
+
+- Legends belong outside the data region when there are many timepoints.
+- Group bands in forest plots should be pale and subordinate, never more salient than the confidence intervals.
+
+## Archetype 4: Dense categorical physical-science panel
+
+Seen in the condensation-sequence figure.
+
+Actionable rules:
+
+- Direct-label regions when the plot has many semantically intrinsic categories.
+- Use hatching or texture overlays when neighboring fills are close in luminance or may print poorly.
+- Reuse the exact same axis limits and panel geometry across the full grid.
+- Prefer embedded labels over a detached mega-legend when each panel repeats the same categorical structure.
+
+## Archetype 5: Asymmetric mixed-modality figure
+
+Seen in the rediploidization genomics figure.
+
+Actionable rules:
+
+- Do not force equal panel sizes. Let the biologically central panel dominate.
+- Use small supporting plots around the hero panel to answer narrower questions.
+- Keep a tight, reused color mapping across all modalities, for example `wave 1 / wave 2 / wave 3` or `baseline / highlight / neutral`.
+- Use whitespace and alignment, not decorative frames, to signal grouping.
+
+## Cross-cutting Nature rules from the sample
+
+- Panel labels are small bold lowercase letters near the top-left corner, not large badges.
+- Figure pages are narrative, not dashboard-like. A dominant panel is normal.
+- Legends are often omitted if direct labeling is possible.
+- Background discipline matters more than ornament. White for charts, black only for image plates.
+- Saturated colors are used sparingly and usually mean either a true experimental channel or a highlighted subgroup.
+- When several modalities coexist, keep axis-heavy plots visually quieter than schematics or imaging panels.
+- Gutters are slightly larger when dark panels touch light panels or when modalities change.
+
+## Palette guidance by modality
+
+- Materials / mechanism pages:
+  `aqua`, `teal`, `lilac`, `soft violet`, with one red accent for callouts only.
+- Imaging plates:
+  `black` + `grey context` + `cyan` + `magenta`.
+- Clinical quantitative figures:
+  `black baseline`, then restrained warm/cool follow-up hues, with pale group shading.
+- Genomics / systems figures:
+  `neutral greys` plus one `red family` and one `blue family` for highlighted biological states.
+
+## What not to copy blindly
+
+- Do not import a bright multi-hue palette just because one sampled physical-science figure used many fills. That only works when the categories are intrinsic phases/materials and directly labeled.
+- Do not place all Nature figures on black backgrounds; that was specific to the imaging plate archetype.
+- Do not force a legend into every panel. Many sampled figures read better with direct labels or one shared legend strip.

evalrx/agent_assets/skills/nature-figure/references/qa-contract.md

@@ -0,0 +1,119 @@
+# QA Contract
+
+Use this before final delivery, before a revision package, and whenever the figure
+contains microscopy, blots, gels, clinical subgroup analysis, or statistical claims.
+Journal rules change, so verify the latest target journal author guide for final
+submission. The values below are conservative defaults for Nature-family style work.
+
+## Current official references to verify
+
+- Nature research figure guide: `https://research-figure-guide.nature.com/`
+- Nature building/exporting panels: `https://research-figure-guide.nature.com/figures/building-and-exporting-figure-panels/`
+- Nature preparing figures/specifications: `https://research-figure-guide.nature.com/figures/preparing-figures-our-specifications/`
+- Nature initial submission and statistics guidance: `https://www.nature.com/nature/for-authors/initial-submission`
+- Nature formatting guide: `https://www.nature.com/nature/for-authors/formatting-guide`
+- Journal of Cell Biology figure/video guidelines for microscopy-oriented image QA: `https://rupress.org/jcb/pages/fig-vid-guidelines`
+- Elsevier/Cell-family image-manipulation baseline: `https://www.sciencedirect.com/journal/the-cell-surface/publish/guide-for-authors`
+
+## Pre-submission checklist
+
+| Check | Pass condition |
+|---|---|
+| Core conclusion | One-sentence claim exists and every panel maps to it |
+| Archetype | Figure has a declared archetype and panel hierarchy |
+| Backend exclusivity | The selected backend produced all plotting, previews, exports, and visual QA renders |
+| Final size | Single-column about 89 mm or double-column about 183 mm, height not above target journal limit |
+| Text size | Body/tick/legend text is readable at final size, usually 5-7 pt for dense journal figures |
+| Panel labels | Lowercase, bold, near top-left, typically 8 pt at final size |
+| Editable text | SVG/PDF text remains editable; no outlined text unless unavoidable for special symbols |
+| Font | Arial/Helvetica/sans-serif fallback is used consistently |
+| Color | No rainbow color maps; red/green is not the only encoding; grayscale print remains interpretable |
+| Legend strategy | Shared or direct labels where possible; no repeated redundant legends |
+| Statistics | `n`, biological/technical repeat definition, center, spread, test, correction, and exact comparison are documented |
+| Source data | Quantitative panels can be traced to a clean CSV/TSV/XLSX or script output |
+| Raster resolution | Photos/microscopy are high-resolution enough for final size; line art uses vector where possible |
+| Microscopy scale | Scale bar is present, calibrated, and not only a magnification factor |
+| Image integrity | Crop, contrast, pseudo-color, stitching, reuse, and raw-file provenance are recorded |
+| Export bundle | Script, source data, SVG, PDF, TIFF/PNG preview, and QA notes are delivered together when requested |
+
+## Statistics legend minimum
+
+For each quantitative panel, capture:
+
+```text
+n definition:
+biological replicates:
+technical replicates:
+center statistic:
+spread/interval:
+test:
+multiple-comparison correction:
+p-value display:
+source-data file:
+```
+
+For machine-learning/model figures, also capture:
+
+```text
+train/validation/test split:
+number of seeds or folds:
+metric definition:
+confidence interval or variability definition:
+baseline definition:
+```
+
+## Image-integrity minimum
+
+For each image panel, capture:
+
+```text
+raw file:
+processed file:
+crop:
+brightness/contrast/gamma:
+pseudo-color:
+scale calibration:
+stitching:
+reuse in other figures:
+quantification link:
+```
+
+Global adjustments are generally safer than local selective edits. If an adjustment
+changes the visibility of relevant background or bands, flag it instead of silently
+normalizing it away.
+
+## Export checks
+
+Run only the export block for the selected backend. If that backend is unavailable,
+stop and report the missing runtime/package instead of producing a substitute export
+with the other language.
+
+### Python
+
+```python
+import matplotlib as mpl
+mpl.rcParams["svg.fonttype"] = "none"
+mpl.rcParams["pdf.fonttype"] = 42
+fig.savefig("figure.svg", bbox_inches="tight")
+fig.savefig("figure.pdf", bbox_inches="tight")
+fig.savefig("figure.tiff", dpi=600, bbox_inches="tight")
+```
+
+### R
+
+```r
+svglite::svglite("figure.svg", width = width_mm / 25.4, height = height_mm / 25.4)
+print(plot)
+dev.off()
+
+grDevices::cairo_pdf("figure.pdf", width = width_mm / 25.4, height = height_mm / 25.4, family = "Arial")
+print(plot)
+dev.off()
+
+ragg::agg_tiff("figure.tiff", width = width_mm / 25.4, height = height_mm / 25.4, units = "in", res = 600)
+print(plot)
+dev.off()
+```
+
+Open the SVG/PDF after export and verify that text can be selected, labels do not
+overlap, and the figure still reads at final printed size.

evalrx/agent_assets/skills/nature-figure/references/r-template-index.md

@@ -0,0 +1,66 @@
+# Private R Template Adaptation
+
+Use this reference when the user chooses R and provides or mentions an existing
+R plotting template collection. Treat such material as private working context.
+Do not reveal absolute paths, folder names, filenames, screenshots, provenance, or
+any identifying labels from the source collection in user-facing output.
+
+## Privacy rules
+
+- Never include absolute local paths in generated code, reports, comments, or final replies.
+- Never mention the original source file, folder, template number, course title, download
+  location, chat attachment, or private document name.
+- When a template is useful, describe it generically by chart family: "a grouped bar
+  template", "a ComplexHeatmap workflow", "a survival plotting workflow".
+- If a reusable idea is copied from a private template, rewrite the final code as a clean,
+  self-contained script with neutral function names and neutral comments.
+- If the user asks where a style came from, say it was adapted from the provided working
+  materials without identifying the path or source file.
+
+## Generic search strategy
+
+Search private materials by chart family and package names, not by exposing paths:
+
+```bash
+find <private-template-root> -type f \( -name '*.R' -o -name '*.Rmd' -o -name '*.r' \)
+rg -n "ggplot|patchwork|ComplexHeatmap|ggrepel|svglite|cairo_pdf|survminer|circlize" <private-template-root>
+```
+
+Keep these commands in internal working notes only. Do not paste the user's private
+root path into the final answer.
+
+## Chart-family map
+
+Use these generic families to decide what to inspect:
+
+| Need | Search targets |
+|---|---|
+| Bars and grouped comparisons | `geom_col`, `geom_bar`, `position_dodge`, `stat_compare_means` |
+| Error bars and point-interval plots | `geom_errorbar`, `geom_pointrange`, `mean_se`, `stat_summary` |
+| Stacked or bidirectional bars | `position_stack`, `coord_flip`, signed values, paired positive/negative bars |
+| Box, violin, paired, and raincloud-style distributions | `geom_boxplot`, `geom_violin`, `geom_jitter`, paired sample identifiers |
+| Heatmaps and annotated heatmaps | `ComplexHeatmap`, `HeatmapAnnotation`, `pheatmap`, `geom_tile` |
+| Correlation, scatter, bubble, and volcano plots | `geom_point`, `geom_smooth`, `ggrepel`, `logFC`, `pvalue`, bubble size scales |
+| PCA, PCoA, NMDS, tSNE, UMAP | `prcomp`, `cmdscale`, `vegan`, `Rtsne`, `Seurat`, embedding coordinates |
+| Survival, Cox, subgroup, ROC, forest | `survival`, `survminer`, `coxph`, `forestplot`, `timeROC`, hazard ratios |
+| Enrichment and pathway summaries | `clusterProfiler`, `GSEA`, `enrichGO`, `enrichKEGG`, dot plots, ridge plots |
+| Circular, genome, phylogeny, chromosome | `circlize`, `ggtree`, `karyoploteR`, genome interval tracks |
+| Single-cell and omics workflows | `Seurat`, marker genes, differential expression, cell-type annotation |
+| Maps, anatomy, and spatial summaries | `sf`, `maps`, `gganatogram`, spatial coordinates |
+| Radar, lollipop, dumbbell, UpSet, Venn, Sankey | `ggradar`, `geom_segment`, `UpSetR`, `ggalluvial`, set operations |
+
+## Adaptation checklist
+
+When adapting a private template:
+
+- Keep useful data wrangling, statistics, and geoms.
+- Replace template-specific colors with the figure-level semantic palette.
+- Normalize fonts to final-size 5-7 pt text and 8 pt bold lowercase panel labels.
+- Convert single-output PNG/PDF scripts to SVG/PDF/TIFF export.
+- Remove decorative elements that do not support the core conclusion.
+- Ensure each statistical comparison has `n`, center, spread, test, and correction
+  information in the legend or source-data notes.
+- For image panels, document raw file, crop, contrast, scale-bar calibration, and any
+  stitching or pseudo-coloring in private QA notes.
+- Final code should be self-contained and should not require the original private
+  folder structure unless the user explicitly asks to keep that workflow.

evalrx/agent_assets/skills/nature-figure/references/r-workflow.md

@@ -0,0 +1,161 @@
+# R Workflow
+
+Use this when the user chooses R, brings R data/scripts, or asks to reuse the local
+R plotting templates. The R track should still follow the same figure contract:
+claim first, evidence hierarchy second, plotting code third.
+
+## R-only execution rule
+
+When the user has selected R, do all figure drawing, previewing, exporting, and
+visual QA in R. Do not call Python/matplotlib/seaborn/plotly to create a temporary
+preview, fallback export, or layout approximation. If R, `Rscript`, or required R
+packages are missing, stop before rendering and report the missing dependency. You
+may still write the R script, provide `install.packages()` commands, or ask permission
+to install dependencies, but do not cross-render the figure in another language.
+
+Allowed non-R utilities are limited to non-visual tasks such as shell file inspection,
+CSV line counts, checksums, archive extraction, or text search. They must not create
+image/vector outputs or alter visual layout.
+
+## Required packages by task
+
+| Task | Preferred packages |
+|---|---|
+| Bars, boxplots, violins, dot plots, lines, volcano plots | `ggplot2`, `ggrepel`, `dplyr`, `tidyr` |
+| Multi-panel assembly | `patchwork`; use `cowplot` only when inset alignment requires it |
+| Rich omics heatmaps | `ComplexHeatmap`, `circlize`, `grid` |
+| Survival and clinical subgroup plots | `survival`, `survminer`, `forestplot`, `ggplot2` |
+| Circular/genome plots | `circlize`, `ggtree`, `gggenes`, domain-specific packages |
+| Export | `svglite`, `grDevices::cairo_pdf`, `ragg` |
+
+## Contract scaffold
+
+```r
+library(ggplot2)
+library(patchwork)
+
+palette_contract <- c(
+  neutral_dark = "#272727",
+  neutral_mid = "#767676",
+  neutral_light = "#D8D8D8",
+  signal_blue = "#3182BD",
+  signal_teal = "#33B5A5",
+  accent_red = "#D24B40",
+  accent_orange = "#E28E2C"
+)
+
+theme_nature_contract <- function(base_size = 6.5, base_family = "Arial") {
+  theme_classic(base_size = base_size, base_family = base_family) +
+    theme(
+      axis.line = element_line(linewidth = 0.35, colour = "black"),
+      axis.ticks = element_line(linewidth = 0.35, colour = "black"),
+      axis.title = element_text(size = base_size),
+      axis.text = element_text(size = base_size - 0.5),
+      legend.title = element_text(size = base_size - 0.3),
+      legend.text = element_text(size = base_size - 0.7),
+      strip.text = element_text(size = base_size - 0.3, face = "bold"),
+      plot.title = element_text(size = base_size + 0.5, face = "bold"),
+      panel.grid = element_blank()
+    )
+}
+
+theme_set(theme_nature_contract())
+
+save_pub_r <- function(plot, filename, width_mm = 183, height_mm = 120, dpi = 600) {
+  w <- width_mm / 25.4
+  h <- height_mm / 25.4
+
+  svglite::svglite(paste0(filename, ".svg"), width = w, height = h)
+  print(plot)
+  dev.off()
+
+  grDevices::cairo_pdf(paste0(filename, ".pdf"), width = w, height = h, family = "Arial")
+  print(plot)
+  dev.off()
+
+  ragg::agg_tiff(paste0(filename, ".tiff"), width = w, height = h, units = "in", res = dpi)
+  print(plot)
+  dev.off()
+}
+```
+
+## Panel labels in R
+
+Use patchwork tags for most multi-panel figures:
+
+```r
+fig <- (p_a | p_b) / (p_c | p_d) +
+  plot_annotation(tag_levels = "a") &
+  theme(plot.tag = element_text(size = 8, face = "bold"))
+```
+
+Use manual labels only when dark image plates or inset geometry make patchwork tags
+misalign.
+
+## Patchwork layout patterns
+
+### Quantitative grid
+
+```r
+fig <- (p_a | p_b | guide_area()) /
+       (p_c | p_d | p_e) +
+  plot_layout(guides = "collect", widths = c(1, 1, 0.45)) &
+  theme(legend.position = "right")
+```
+
+### Schematic-led composite
+
+```r
+design <- "
+AAAA
+BBCD
+"
+fig <- p_schematic + p_b + p_c + p_d +
+  plot_layout(design = design, heights = c(1.8, 1))
+```
+
+### Image plate plus quant
+
+Keep black backgrounds inside image panels only. Put scale bars on the image, then
+place quantification next to or below the representative image.
+
+```r
+p_img <- ggplot(img_df, aes(x, y, fill = intensity)) +
+  geom_raster() +
+  scale_fill_gradient(low = "black", high = "white") +
+  coord_fixed(expand = FALSE) +
+  annotate("segment", x = 10, xend = 40, y = 10, yend = 10,
+           linewidth = 0.6, colour = "white") +
+  theme_void() +
+  theme(legend.position = "none", plot.background = element_rect(fill = "black", colour = NA))
+```
+
+## ComplexHeatmap export
+
+`ComplexHeatmap` objects are grid objects, not ggplot objects. Export them by opening
+the graphics device, drawing, then closing it.
+
+```r
+library(ComplexHeatmap)
+library(circlize)
+
+pdf("heatmap.pdf", width = 7.2, height = 4.8, family = "Arial")
+draw(ht, heatmap_legend_side = "right", annotation_legend_side = "right")
+dev.off()
+
+svglite::svglite("heatmap.svg", width = 7.2, height = 4.8)
+draw(ht, heatmap_legend_side = "right", annotation_legend_side = "right")
+dev.off()
+```
+
+## Template reuse rule
+
+The local R materials are examples, not final style. When reusing them:
+
+1. Inspect only the nearest template folder.
+2. Keep useful data wrangling, statistics, and geoms.
+3. Replace ad hoc colors, oversized fonts, dense legends, and PNG-only export.
+4. Rebuild the final script around `theme_nature_contract()` and `save_pub_r()`.
+5. Add source-data output if the figure is manuscript-facing.
+
+Open `references/r-template-index.md` for the local template atlas.