ssci-plots

# SSCI Academic Figure Style ## 1. Core Principles Three design commitments guide every figure this Skill produces: 1. **Data-ink ratio**: Every pixel should convey data. Remove gridlines, 3D effects, and decorative elements -- they add visual noise without information value (Tufte, 1983). Use clean L-shaped axes (top and right spines off). 2. **Colorblind-safe and grayscale-compatible**: About 8% of male readers have red-green color vision deficiency. Categorical palettes default to validated CVD-safe sets (Tol, 2021; Wong, 2011; Okabe & Ito, 2008) and pair color with a redundant channel (line style, marker shape, or hatching) so every figure remains readable in grayscale print. Journal-anchored palettes (NPG, AAAS, NEJM, Lancet, BMJ, JAMA) are provided to match house style at submission and are flagged with their CVD grade in `list_palettes()`. 3. **Clean figure + separate text**: The saved image contains only the data visualization (axes, data, legend). Figure number, title, and Note are output as standalone Markdown text for the user to place in the manuscript. This matches APA 7th Edition requirements and most journal submission guidelines where captions are supplied separately from image files. Initialize the style system at the start of every figure: ```python from scripts.ssci_style import * apply_style() # 70+ rcParams, colormaps, fonts apply_style(journal='nejm') # Auto-loads matching palette + sizes apply_style(journal='psych_science', mode='slides') # Larger fonts for talks ``` --- ## 2. Workflow ### Step 1 -- Confirm Requirements Before writing code, identify: - (a) Chart type from the decision table below (or its chart-family reference file) - (b) Target journal, if the user specifies one (12 presets available) - (c) Number of groups or conditions (determines palette size) - (d) Error metric: SE, SD, or 95% CI ### Step 2 -- Initialize Style Run `apply_style()` to set all rcParams, register colormaps, and embed fonts. If the user specifies a target journal, pass it as an argument and read `references/journal-presets.md` for details: ```python # Available journal keys (12): # apa, elsevier, wiley, sage, psych_science, asa, # nature, science, nejm, lancet, bmj, jama apply_style(journal='lancet') ``` `apply_style(journal=...)` also auto-loads the matching default palette via `axes.prop_cycle` (e.g. `journal='nejm'` activates the `nejm` palette). For slide / poster usage, add `mode='slides'` to bump font sizes without touching the underlying preset. ### Step 3 -- Build the Figure Open `references/chart-type-guide.md` first. It is the **Index** to the 55-chart catalog and routes you to one of the four chart-family files (`chart-types-core.md`, `chart-types-models.md`, `chart-types-causal-econ.md`, `chart-types-applied.md`) or the quick-reference file. Follow the design elements, parameters, and code patterns documented there. Color selection: - Categorical data: `get_palette(n)` returns n CVD-safe hex colors (default: Tol Bright). Use `category=` / `name=` for discipline- or journal-anchored alternatives. - Emphasis focal + reference pair: `get_emphasis_pair(focal=..., reference=...)` returns two colors for "focal series vs neutral reference" patterns (treatment vs control, event-study, simple slopes). - Heatmap: `get_diverging_cmap('BuRd')` with `TwoSlopeNorm(vcenter=0)` for zero-centered diverging data. - Sequential data: `get_sequential_cmap('viridis')` (perceptually uniform); also `cividis / plasma / inferno / magma / Blues / Oranges / tailwind_slate`. - Multi-panel composition: see `references/multi-panel.md` for `compose_grid` / `small_multiples` / `add_inset` / shared legend & colorbar / marginal histogram. - Always pair color with redundant coding (`LINE_STYLES`, `MARKERS`, or `HATCHES` from `ssci_style`). ### Step 4 -- Validate Check every item in the Quality Checklist (Section 6 below) before saving. If the figure includes statistical annotations (p-values, effect sizes, CI, inline statistics), read `references/statistical-annotations.md` for exact formatting rules. For APA figure text formatting details (number, title, Note, multi-panel conventions, mediation diagram conventions), read `references/apa-figure-standards.md`. ### Step 5 -- Save and Output Save the figure in multiple formats using `save_figure()`: ```python save_figure(fig, 'fig_1') # Default: PDF + PNG (600 DPI) save_figure(fig, 'fig_1', formats=('pdf', 'tiff')) # Journal submission (RGB TIFF) ``` Then output the figure description text separately as Markdown, using `format_apa_figure_text()`: ```python text = format_apa_figure_text( figure_number=1, title="Mean Anxiety Scores by Treatment Condition and Time Point", note_text="N = 354. PSS = perceived stress scale; SWB = subjective well-being.", p_levels=[("*", ".05"), ("**", ".01"), ("***", ".001")], error_bar_type="95ci", # auto-emits standard error-bar statement ) ``` Output format: **Figure 1** *Mean Anxiety Scores by Treatment Condition and Time Point* *Note.* N = 354. Error bars represent 95% confidence intervals. PSS = perceived stress scale; SWB = subjective well-being. \*p < .05. \*\*p < .01. \*\*\*p < .001. --- ## 3. Chart Type Selection The full catalog has **55 chart types** organized by family. Use this top-level table for routing; then load the chart-family file for the detailed 6-section spec. ### 3.1 By chart family | Family | File | Chart sections (representative) | |---|---|---| | **Core distribution & relationship** | `chart-types-core.md` | §1 Grouped Bar, §2 Error Bar, §3 Line, §3.1 Annotated Time Series, §4 Scatter+Regression, §4.1 Scatter with Marginal Histogram, §5 Box, §6 Violin, §7 Correlation Heatmap | | **Statistical model output** | `chart-types-models.md` | §8 Forest, §8.1 Coefficient/Dot-Whisker, §9 Path/SEM, §9.1 IV Diagram, §10 Mediation (incl. §10.1 Serial, §10.2 Parallel), §11 Interaction, §11.1 Categorical Moderator, §11.2 Continuous Marginal Effect, §12 Simple Slopes, §17 Scree+Parallel Analysis, §18 Profile (LPA/LCA), §19 Growth Curve, §32 Specification Curve, §33 Causal DAG | | **Causal inference / econometrics** | `chart-types-causal-econ.md` | §22 Event-Study Coefficient Plot, §23 DID Parallel Trends, §24 Regression Discontinuity, §25 Binned Scatter (Binscatter), §26 Coefficient Plot multi-model, §38 IV Diagram | | **Applied / specialty** | `chart-types-applied.md` | §14 Raincloud, §16 Funnel, §20 Kaplan-Meier (with at-risk table), §21 Bland-Altman, §27 Ridgeline/Joy, §28 Choropleth, §29 ROC + Calibration, §30 Mobility Transition Matrix, §31 Marginal Effects | | **Quick reference (one-page each)** | `chart-types-quick-reference.md` | §15.1 Histogram, §15.2 Density (KDE), §15.3 Swarm/Beeswarm, §15.4 Factor Loading, §15.5 Johnson-Neyman, §15.6 CONSORT, §15.7 Lollipop, §15.8 Slope/Bump, §15.9 Dumbbell, §15.10 Population Pyramid, §15.11 Tornado/Butterfly | | **Multi-panel composition** | `multi-panel.md` | `compose_grid`, `small_multiples`, `add_inset`, shared legend/colorbar, marginal histogram, subfigures | ### 3.2 By discipline (decision shortcut) | Discipline | Primary chart-family file | |---|---| | Psychology — descriptive | `chart-types-core.md` | | Psychology — modeling (SEM, mediation, forest, simple slopes, growth) | `chart-types-models.md` | | Economics — causal (event-study, DID, RD, IV, binscatter) | `chart-types-causal-econ.md` | | Public health & medicine (KM, ROC, funnel, Bland-Altman) | `chart-types-applied.md` | | Sociology (mobility matrix, ridgeline) | `chart-types-applied.md` | | Political science (annotated time series, ideological scaling, choropleth) | `chart-types-applied.md` + `chart-types-core.md` §3.1 | | Geography (choropleth, spatial overlays) | `chart-types-applied.md` | | Methodology / robustness (specification curve, DAG) | `chart-types-models.md` | ### 3.3 Cross-cutting routing table | Data / Analysis | Recommended chart | Section anchor | |---|---|---| | Group mean comparison (t-test, ANOVA) | Grouped bar + error bars | core §1 | | Group means with uncertainty (cleaner than bars) | Error bar / dot-and-whisker | core §2 | | Trend over time / repeated measures | Line chart with CI bands | core §3 | | Time series with event markers (policy, intervention) | Annotated time series | core §3.1 | | Two continuous variables (r, regression) | Scatter + regression line | core §4 | | Distribution shape comparison | Box plot | core §5 | | Distribution with density | Violin plot | core §6 | | Multi-variable correlation matrix | Lower-triangle heatmap | core §7 | | Meta-analysis effect sizes | Forest plot | models §8 | | Multi-model coefficients side-by-side | Coefficient / dot-whisker plot | models §8.1, econ §26 | | SEM / CFA path structure | Path diagram | models §9 | | Instrumental variable identification | IV diagram | models §9.1 / econ §38 | | Mediation pathway (a, b, c') | Mediation diagram | models §10 | | Moderation / interaction | Interaction / simple slopes | models §11, §12 | | Continuous moderator marginal effect | Marginal effects plot | applied §31 | | Factor structure (EFA/PCA) | Scree + parallel analysis | models §17 | | Latent profile / class structure | Profile plot (LPA/LCA) | models §18 | | Individual trajectories | Growth curve | models §19 | | Robustness across specifications | Specification curve | models §32 | | Causal assumptions diagram | DAG | models §33 | | Difference-in-differences design | Event-study or DID parallel trends | econ §22, §23 | | Sharp cutoff design | Regression discontinuity plot | econ §24 | | Large-N continuous-X relationship | Binned scatter (binscatter) | econ §25 | | Full distribution + mean + density | Raincloud plot | applied §14 | | Publication bias / small-study effects | Funnel plot | applied §16 | | Time-to-event analysis | Kaplan-Meier survival curve | applied §20 | | Method comparison agreement | Bland-Altman plot | applied §21 | | Multi-group distribution stack | Ridgeline / joy plot | applied §27 | | Geographic distribution | Choropleth map | applied §28 | | Diagnostic / prediction performance | ROC + calibration | applied §29 | | Categorical transition / mobility | Mobility transition matrix | applied §30 | | Multi-panel composite | Multi-panel composition | `multi-panel.md` | When NOT to use: - Bar chart for continuous distributions -- use violin, box, or raincloud instead (Weissgerber et al., 2015) - Rainbow / jet colormap -- use viridis, cividis, or Tol diverging schemes - Pie chart -- use grouped bar chart (APA does not define pie chart standards) - 3D charts -- use 2D with faceting or color encoding - Sankey -- use mobility transition matrix (zero new deps; sociology-standard alternative) --- ## 4. Quick Reference: Core Style Parameters Set automatically by `apply_style()`. Override via `plt.rcParams[...]` after the call. **All numeric defaults live in `scripts/ssci_style.py`; never copy them across docs (SSOT).** | Parameter | Rationale | |---|---| | `font.family` (sans-serif) | APA 7th recommends sans-serif for figures | | `font.size` (8 pt body) | APA range 8--14 pt; 8 pt is legible at print column width | | `axes.spines.top / right = False` | L-shaped axes maximize data-ink ratio | | `axes.linewidth` | Exceeds APA minimum 0.5 pt; clear at print | | `savefig.dpi` | Meets APA, Wiley, OUP, ASA line-art requirements | | `pdf.fonttype = 42` | TrueType embedding; journals reject Type 3 fonts | | `mathtext.fontset = 'custom'` (Arial italic) | Render *r*, *t*, *F*, *p* in body font (P0 fix) | | `errorbar.capsize` | Visible cap without visual clutter | | `constrained_layout` enabled | Prevents label clipping in multi-panel figures | Full parameter set: `scripts/ssci.mplstyle` (loaded by `apply_style()`). ### Color Palettes **21 categorical palettes are registered** (`_PALETTE_REGISTRY` in `scripts/ssci_style.py`). HEX values live exclusively in the SSOT; the table below references palettes by **name** only. Discover at runtime via `list_palettes(category=..., publication_grade=...)`. | Category | Palettes | |---|---| | **General CVD-safe** (default) | `tol_bright` (default), `okabe_ito`, `high_contrast`, `ibm`, `tol_vibrant` | | **Journal-anchored** (ggsci R, GPL-3 credit) | `nature_npg`, `science_aaas`, `nejm`, `lancet`, `jama`, `bmj` | | **Discipline-anchored** | `economics` (Stata s2color), `tailwind_slate` (modern slate scale) | | **Aesthetic publication-grade** | `tol_muted`, `tol_light`, `tol_medium_contrast`, `metbrewer_hiroshige`, `metbrewer_cassatt2`, `uk_gov_af`, `economist_chart`, `bbc_bbplot` | | **Aesthetic supplement (deferred, opt-in)** | 17 candidates in `AESTHETIC_PALETTES`; opt-in via `register_aesthetic_palette(name)` which emits a warning that they are not publication-grade | | Colormap | Use | API | |---|---|---| | `ssci_BuRd` | Correlation heatmap (blue-white-red, zero-anchored) | `get_diverging_cmap('BuRd')` | | `ssci_PRGn` | CVD-safer diverging alternative | `get_diverging_cmap('PRGn')` | | `ssci_sunset` | Tol Sunset diverging | `get_diverging_cmap('sunset')` | | `viridis / cividis / plasma / inferno / magma` | Sequential (perceptually uniform) | `get_sequential_cmap('viridis')` etc. | | `ssci_Blues / ssci_Oranges / ssci_tailwind_slate` | Single-hue sequential | `get_sequential_cmap('Blues')` etc. | | Grayscale | B&W-only output | `get_grayscale(n)` (n ∈ {2,3,4,5}) | Pair every color encoding with a redundant channel: line style (`LINE_STYLES`), marker shape (`MARKERS`), or hatching (`HATCHES`). Full palette catalog, academic citations, license credits, decision tree, and journal/discipline anchoring: `references/color-system.md`. ### Figure Sizes