Skip to content

complexity-elements-catalog.md

Latest commit

 

History

History
780 lines (625 loc) · 29.8 KB

complexity-elements-catalog.md

File metadata and controls

780 lines (625 loc) · 29.8 KB
Raw

Complexity Elements Catalog

The 30 visual-complexity elements that distinguish "basic compliant" figures from "top-journal grade" figures. Compiled from A0-6 inventory and A0-9 replication-package audit (15+ top-SSCI replication archives: Chetty et al., Card et al., Calonico-Cattaneo-Titiunik, etc.).

This file is the reference index:

  • Each element has 8 fields: name, priority, frequency, function, visual signature, demonstration examples (reverse index), when to use / when to avoid, implementation + ROI.
  • The "Journal-grade upgrade checklist (5 moves)" subsections at the end of each chart in chart-types-core.md, chart-types-models.md, chart-types-causal-econ.md, and chart-types-applied.md cite back into this catalog.

§0. Overview & How to Read This File

The 30 elements are partitioned into 4 priority tiers:

Tier Count Description
P0 14 High-frequency cross-discipline; every top-grade figure has 4-5 of these
P1 7 Discipline-specific; the right ones depending on chart type and target journal
P2 6 Documented in chart-type-guide.md and demonstrated in 1-2 examples
P3 3 Mentioned only; not implemented as a helper, included for completeness

Reverse index convention: each element lists the example figures in examples/generate_examples.py where it appears. The format is fig_01..18. When you want to see an element, search the example codebase for the figure IDs listed under that element.

Evidence source convention: A0-9 = real top-SSCI replication package audit; A1-5 = visual signature spec; A0-6 = element inventory. When an element's ROI is rated "high", it means the A0-9 audit found the move to be reliably present in publication-grade figures across multiple disciplines.

§1. P0 Elements (14) -- High-Frequency Cross-Discipline

Every top-grade figure should apply at least 4 of these. The five "upgrade moves" subsections in chart-type guides are constructed from these elements.

§1.1 E-03 Inline Statistical Annotation Cluster

The single highest-leverage move (A0-9 finding #5). Top-journal figures embed key statistics inside the panel rather than burying them in the caption -- it tells the reader "here are the numbers" at a glance.

  • A0-6 ID: E-03
  • Visual signature: 3-6 lines of inline text in the top-left or top-right corner; 8 pt font; Latin stat keys (n, r, p) italicized via $\mathit{...}$; Greek keys (tau, eta, beta) upright; 95% CI in brackets [lo, hi].
  • Demonstration in figs: 01, 02, 03, 05, 06, 07, 09, 10, 13, 14, 17, 18
  • Helper: add_inline_stats (10 cookbook patterns in §5 below).
  • When to use: any figure with reportable statistics (correlation, regression coefficient, effect size, sample size). Default to using it -- skipping it is what makes figures look "course-assignment grade".
  • When to avoid: pure descriptive panels (no statistics to report), illustrative diagrams (e.g., the X-M-Y boxes of a mediation diagram).
  • ROI: highest. A0-9 confirms this is the single move most reliably present in top-SSCI publication-grade figures.

§1.2 E-04 Reference Lines + Shaded Regions

Dashed gray reference lines at theoretically meaningful values (zero, chance level, null effect, treatment onset).

  • A0-6 ID: E-04
  • Visual signature: dashed NEUTRAL['reference'] gray, linewidth 0.6-0.8, alpha 0.7, optional inline label in matching color at line's right-top position; default zorder 0.5 (behind data).
  • Demonstration in figs: 01, 02, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 16, 17
  • Helper: add_reference_line(ax, value, orientation='h'|'v', label='...').
  • When to use: any figure where the data carries a meaningful zero, chance level, threshold, or null reference. Forest plots, event-study coefficient plots, ROC curves (diagonal), Bland-Altman LOA.
  • When to avoid: nothing meaningful at any reference value (rare).
  • ROI: high.

§1.3 E-07 Two-Tone Emphasis Pair

One saturated focal color + one muted reference gray. The dominant publication-feel signal in top SSCI journals.

  • A0-6 ID: E-07
  • Visual signature: focal color from the active palette's saturated family (navy, NEJM red, lancet blue, etc.); reference NEUTRAL['reference'] gray; focal at linewidth 1.5; reference at 1.0.
  • Demonstration in figs: 01, 03, 05, 06, 08, 09, 10, 11, 13, 14, 17, 18
  • Helper: focal, ref = get_emphasis_pair('blue') (8 named focals
    • custom hex + palette-name).
  • When to use: treatment vs control; intervention arm vs reference; highlighted study in a forest plot; focal cluster in a heatmap.
  • When to avoid: 3+ equally important groups (use full categorical palette); diverging data around zero (use diverging cmap).
  • ROI: high. Pair this with E-03 for the strongest single "publication-ready" effect.

§1.4 E-08 Line Weight Hierarchy

Multiple line weights within a single panel: focal trace at 1.5-2.0; secondary at 1.0; reference / minor at 0.6-0.8.

  • A0-6 ID: E-08
  • Visual signature: linewidth ratios approximately 2.5 : 1.7 : 1.0 for primary : secondary : reference; differences must be visible at print resolution.
  • Demonstration in figs: 03, 06, 08, 09, 11, 17
  • Helper: no helper; pass lw= to plotting calls. Convention: focal trace lw=1.5, reference / ribbon edge lw=0.8.
  • When to use: multi-line plots; trajectory plots; multiple arms in a clinical trial figure.
  • When to avoid: single-line plots; small multiples where each panel has only one line.
  • ROI: medium.

§1.5 E-15 Small Multiples / Faceting

3+ panels of the same chart type with different data slices.

  • A0-6 ID: E-15
  • Visual signature: small_multiples(n_rows, n_cols) with share='all' by default; panel labels A/B/... or a/b/... per active preset; constrained_layout for spacing; inner tick labels auto-hidden.
  • Demonstration in figs: 08, 13, 16, 17, 18
  • Helper: small_multiples or compose_grid (see multi-panel.md).
  • When to use: comparing the same DV across subgroups (SES quartiles, cohorts); comparing the same chart type across DVs (9-gene UMAP grid); sensitivity analyses on a primary model.
  • When to avoid: 1-2 panels (just use a single Figure with two axes); >9 panels at print width (consider splitting into supplementary).
  • ROI: high (when applicable).

§1.6 E-19 Heterogeneity / Context Annotation

Annotations that surface heterogeneity statistics (I^2, tau^2, k) or contextual notes about a panel.

  • A0-6 ID: E-19
  • Visual signature: text annotation in upper or lower corner; 8 pt; multi-line; same italic Latin / upright Greek convention as E-03.
  • Demonstration in figs: 05 (forest with I^2 / tau^2), 18 (Panel B contextual stats)
  • Helper: add_inline_stats with the meta-analysis cookbook pattern (see §5 Pattern 2).
  • When to use: meta-analysis / forest plots (heterogeneity is expected); event-study plots (pre-trend p-value); any panel that benefits from a one-line caveat.
  • When to avoid: panels where the in-text caption already carries this information.
  • ROI: medium.

§1.7 E-20 Embedded In-Figure Table

A small numerical table inside the figure (study summary in a forest plot; at-risk numbers below a KM curve; effect-size table below a violin plot).

  • A0-6 ID: E-20
  • Visual signature: monospace-aligned text grid; 7-8 pt; placed below the main panel or to the right; cell padding tight (no matplotlib table() default styling -- those tend to look like Excel).
  • Demonstration in figs: 04, 05, 11, 12, 18
  • Helper: no dedicated helper; ax.text(...) aligned via tab-stops or via a secondary axes positioned below the main one.
  • When to use: forest plots (study names, n, weight); KM curves (at-risk numbers per time point); mobility transition matrix.
  • When to avoid: when the figure is already crowded; when the table is large enough to warrant its own Table N in the manuscript.
  • ROI: medium.

§1.8 E-23 Tick Density Calibration

Tick density appropriate to data range (no over-dense ticks; no sparse-tick "telegraph poles").

  • A0-6 ID: E-23
  • Visual signature: 5-7 major ticks per axis as a rule; minor ticks off by default; tick labels at preset font size (typically 7-8 pt).
  • Demonstration in figs: ALL 18 (controlled by apply_style globally)
  • Helper: implicit in apply_style(); no per-figure code needed.
  • When to use: always; this is a global setting.
  • When to avoid: never disable unless you explicitly need minor ticks (rare; e.g., on a log-scale axis where major ticks are at powers of 10).
  • ROI: low (always-on; no per-figure decision).

§1.9 E-24 Font Hierarchy

Three font sizes in clear ratios: panel labels / suptitle (~12-14 pt); axis labels / title (~9-10 pt); tick labels / inline stats (~7-8 pt).

  • A0-6 ID: E-24
  • Visual signature: controlled per-preset; APA uses 10/8/8; Nature uses 9/8/7; psych_science uses 18/9/9 etc.
  • Demonstration in figs: ALL 18 (controlled by apply_style per preset)
  • Helper: implicit in apply_style(journal=...) and _ACTIVE_PRESET.
  • When to use: always.
  • ROI: low (always-on).

§1.10 E-26 Cross-Panel Consistency

Identical font sizes, palettes, axis label phrasing across all panels of a multi-panel figure.

  • A0-6 ID: E-26
  • Visual signature: see multi-panel.md §11 checklist.
  • Demonstration in figs: 08, 13, 17, 18
  • Helper: enforced by apply_style (font sizes), get_palette (one palette per figure), and compose_grid / small_multiples (shared layout).
  • When to use: every multi-panel figure.
  • ROI: low (always-on if you use the helper chain correctly).

§1.11 E-28 Theoretical Reference Markers

Marker(s) at theoretically meaningful values that the figure compares against (e.g., 50% baseline in a behavioral experiment; null effect in a forest plot).

  • A0-6 ID: E-28
  • Visual signature: dashed gray reference line with an inline label ("Chance", "Null effect", "Treatment onset"); often paired with a shaded region for the comparison interval.
  • Demonstration in figs: 09, 11, 17
  • Helper: add_reference_line(ax, value, label='Chance') (same helper as E-04 with a label).
  • When to use: experiments with a theoretical baseline; treatments with a defined "no effect" value.
  • When to avoid: descriptive panels without a theoretical reference.
  • ROI: medium.

§1.12 E-29 Greek Letter Inline Annotation

Greek letters for statistics rendered upright (not italicized) per APA 7.

  • A0-6 ID: E-29
  • Visual signature: $\eta$, $\tau$, $\beta$, $\chi$, $\sigma$, etc. -- rendered via mathtext custom fontset using the active preset's body font (Arial / Helvetica). Italicized Latin keys but upright Greek.
  • Demonstration in figs: 02, 03, 05, 09
  • Helper: add_inline_stats automatically handles Latin/Greek italic policy via _LATIN_STATS and _GREEK_STATS registries.
  • When to use: any figure citing Greek-letter statistics (effect sizes eta^2, tau, beta; Greek-letter parameters).
  • When to avoid: figures that don't cite Greek statistics.
  • ROI: low (automatic).

§1.13 E-30 Paper / Slides Dual Output Mode

The figure renders at print-grade for paper submission and at a slides-appropriate scale (wider, larger fonts) for presentation.

  • A0-6 ID: E-30
  • Visual signature: apply_style(mode='slides') scales body fonts ~30% up, increases line widths, widens figure to a 16:9-friendly aspect ratio.
  • Demonstration in figs: 18 (demonstrated -- the dashboard renders in both modes from the same code).
  • Helper: apply_style(mode='paper') (default) / apply_style(mode='slides').
  • When to use: any figure that will be used both in a manuscript and in a talk -- write once, render twice.
  • When to avoid: paper-only or slides-only figures (skip the dual mode for one-shot use).
  • ROI: medium.

§1.14 E-25 White-Space Rhythm

Generous margins and inter-panel spacing; uncluttered backgrounds.

  • A0-6 ID: E-25
  • Visual signature: constrained_layout=True default; wspace and hspace not manually tightened below preset defaults; spines removed by remove_spines(ax) (keeping bottom + left); no gridlines unless explicitly requested.
  • Demonstration in figs: ALL 18 (controlled by apply_style and the multi-panel helpers).
  • Helper: constrained_layout (default in all helpers); remove_spines.
  • When to use: always.
  • ROI: low (always-on).

§2. P1 Elements (7) -- Discipline-Specific

These appear in subsets of disciplines. Use them when chart type and target journal call for them.

§2.1 E-01 Inset Zoom Axes

A small inset showing a zoomed region of the main axes.

  • A0-6 ID: E-01
  • Visual signature: bbox in upper-right or lower-left of parent axes; optional connector lines (zoom_indicator=True) drawing the zoom region in the main axes; smaller tick label font (labelsize=5-6).
  • Demonstration in figs: 10 (RD McCrary inset), 11 (NEJM KM early-zoom), 15 (choropleth AK/HI), 18 (Panel B spotlight)
  • Helper: add_inset(ax, bbox, xlim, ylim, zoom_indicator=True).
  • When to use: NEJM KM curves (early period); RD plots (McCrary density); choropleth maps (AK/HI); bivariate density (peak detail).
  • When to avoid: when the main axes already shows the detail clearly; when the inset would clutter the main panel.
  • ROI: medium (essential for NEJM-style submissions; optional otherwise).

§2.2 E-02 Marginal Histogram on Scatter

Top and right marginal histograms or KDEs attached to a scatter.

  • A0-6 ID: E-02
  • Visual signature: top hist height 18-20% of main axes height; right hist width similar; shared bin orientation; inner tick labels hidden via hide_inner=True.
  • Demonstration in figs: 18 (Panel B only)
  • Helper: add_marginal_hist(ax, x, y, kind='hist'|'kde').
  • When to use: cognitive psych RT x accuracy; when both marginal distributions are themselves interpretable.
  • When to avoid: when the marginals are not informative (most multi-panel grids); on KM curves, time-series, or forest plots.
  • ROI: low (niche; A0-9 confirms rare in top SSCI).

§2.3 E-17 Multi-Tier Pairwise Significance Brackets

Stacked horizontal brackets above grouped bars / boxes showing pairwise test results.

  • A0-6 ID: E-17
  • Visual signature: brackets at multiple heights (one tier per comparison); bracket height ~0.02 of axes; text offset above bracket; significance markers (*, **, ***, n.s.) or effect-size text (d = .42); first-row tier touches the highest bar, second tier above it, etc.
  • Demonstration in figs: 02, 07
  • Helper: add_significance_bracket(ax, x1, x2, y, p_value, ...), called once per comparison. Stack manually by incrementing y.
  • When to use: psychology bar / box / violin / raincloud plots with explicit pairwise tests.
  • When to avoid: forest plots (use I^2 inline), KM curves (use log-rank inline), regression coefficient panels.
  • ROI: high (psychology), low (other disciplines).

§2.4 E-18 3-Layer Raw + Mean + CI

The Weissgerber 2015 idiom: individual data points + group mean + error bar / CI all on one axes.

  • A0-6 ID: E-18
  • Visual signature: raw scatter at alpha 0.3, marker size 5; bold mean marker at lw 1.0, capsize 3; 95% CI / SE error bar.
  • Demonstration in figs: 02, 06 (interaction with raw overlay), 08 Panel A, 17
  • Helper: no dedicated helper; layer manually: ax.scatter(..., alpha=0.3) then ax.errorbar([x], [mean], yerr=...).
  • When to use: small-N (n < 40) group comparison; when individual variation is interpretable (e.g., heterogeneous treatment response).
  • When to avoid: large-N (raw points overplot); when the message is the mean (not the variation).
  • ROI: high (matches Weissgerber 2015's "show the data" call).

§2.5 E-10 Highlighted Region / Spotlight axvspan

A semi-transparent rectangle highlighting a region of interest (RD bandwidth, event window, time-of-interest).

  • A0-6 ID: E-10
  • Visual signature: ax.axvspan(x1, x2, alpha=0.15, color=ref); optional inline label naming the region.
  • Demonstration in figs: 06 (interaction high-stress zone), 09 (event-study treatment onset window)
  • Helper: matplotlib ax.axvspan / ax.axhspan directly. Or add_reference_line for a one-sided emphasis.
  • When to use: RD plot bandwidth visualization; event-study effective treatment window; experimental phases on a time-series.
  • When to avoid: panels without a meaningful range to highlight.
  • ROI: medium.

§2.6 E-11 Bidirectional Anchors ("Favors A <-> B")

Inline directional anchors on a forest plot or coefficient plot indicating "left = favors control / right = favors treatment".

  • A0-6 ID: E-11
  • Visual signature: italic gray text below the x-axis with an arrow (or implicit by position relative to the null line); 7 pt; positioned at left and right axis tails.
  • Demonstration in figs: 05 (forest), 13 (coefficient plot)
  • Helper: no dedicated helper; ax.text(...) with ax.transData
    • transform=ax.transAxes.
  • When to use: forest plots; coefficient plots where direction has semantic meaning (e.g., a ratio above 1 means treatment effect).
  • When to avoid: when "favors X" is meaningless (a slope coefficient is not a 1-vs-other comparison).
  • ROI: medium.

§2.7 E-27 White-Halo Line Technique

A 2-pass plot: first a thicker white line, then the actual colored line on top. The white halo separates overlapping traces visually.

  • A0-6 ID: E-27
  • Visual signature: white line at lw 2.5 (background), colored line at lw 1.0 on top. Used in event-study coefficient plots where multiple treatment-time traces overlap.
  • Demonstration in figs: 09 (event-study DID, unique use)
  • Helper: no helper; manual 2-pass: 
    ax.plot(t, y, color='white', lw=2.5, zorder=2)
ax.plot(t, y, color=focal,   lw=1.0, zorder=3)
  • When to use: dense overlapping line plots, esp. event-study DID with multiple cohorts.
  • When to avoid: single-trace or sparsely overlapping plots.
  • ROI: low (single-discipline use; only in econ event-study).

§3. P2 Elements (6) -- Documented but Not Helper-Wrapped

Documented in chart-type-guide.md; demonstrated in 1-2 examples. These are normal matplotlib operations that don't need a Skill helper.

§3.1 E-05 Bubble Size Encoding

Marker size encoding a third variable (population size in choropleth, study weight in forest, exposure intensity in scatter).

  • A0-6 ID: E-05
  • Visual signature: ax.scatter(x, y, s=variable * scale_factor); size range ~20-200 px^2 for paper-size figures.
  • Demonstration in figs: 05 (forest weight); preserved in existing examples
  • Implementation: matplotlib s= parameter; no Skill helper needed.
  • Decision: keep as documented pattern; do not wrap in a helper.

§3.2 E-06 Continuous Color Gradient

Continuous data encoded as cmap value (correlation as color, age as color, time as color).

  • A0-6 ID: E-06
  • Visual signature: ax.scatter(..., c=variable, cmap=cmap, vmin=, vmax=) with an explicit colorbar.
  • Demonstration in figs: 04 (correlation heatmap), 15 (choropleth)
  • Implementation: get_sequential_cmap(name) for cmap selection.

§3.3 E-09 Connector / Callout Boxes

Annotated text boxes with arrows pointing to specific data points.

  • A0-6 ID: E-09
  • Visual signature: ax.annotate(text, xy=(x,y), xytext=(x_off, y_off), arrowprops=dict(arrowstyle='->', lw=0.5, color=NEUTRAL['axis'])).
  • Demonstration in figs: 14 (politicized scaling KDE with named callouts)
  • Implementation: matplotlib ax.annotate(arrowprops=...); no Skill helper.

§3.4 E-12 Means + Individual Trajectories

Light gray individual trajectories + bold mean trajectory overlay (developmental trajectories; multi-arm trial outcomes over time).

  • A0-6 ID: E-12
  • Visual signature: gray lines at lw 0.4, alpha 0.15; mean line at lw 1.5; optional CI fill.
  • Demonstration in figs: 17 (developmental trajectories grouped by SES quartile)
  • Implementation: manual layering with for sid in subjects: ax.plot(...).

§3.5 E-13 Dual / Twin Axes

Two y-axes on the same x range (e.g., raw counts on left, percentage on right).

  • A0-6 ID: E-13
  • Visual signature: ax2 = ax.twinx(); second y-axis label color matches the second trace's color for visual binding.
  • Demonstration in figs: 16 (specification curve, optional)
  • Implementation: matplotlib ax.twinx(). Warning: dual axes are widely considered an anti-pattern in data viz unless the two scales are truly necessary. See chart-type-guide.md §dual-axes warning before using.

§3.6 E-14 Panel Schematic / Illustration

Mild schematic element inside a panel (a labeled box, a flow arrow, a small icon).

  • A0-6 ID: E-14
  • Visual signature: matplotlib.patches.FancyBboxPatch(...) for rounded rectangles; ax.annotate(arrowprops=dict(arrowstyle='-|>')) for flow arrows.
  • Demonstration in figs: 03 (mediation X-M-Y boxes), 18 (Panel C schematic header)
  • Implementation: matplotlib patches directly; no Skill helper.

§4. P3 Elements (3) -- Mentioned, Not Implemented

These are documented in the chart-type guides as alternatives or warnings, but the Skill does not provide example figures for them.

§4.1 E-16 Bootstrap Path Visualization

A "fan" of bootstrap replicates around a focal trace.

  • A0-6 ID: E-16
  • Decision: documented as a code snippet in chart-type-guide.md §line; no example figure. Reason: rare in top SSCI; takes several hundred lines of code to do well; manual case-by-case.

§4.2 E-21 Stacked / Joy Plot

Density plots stacked vertically, each baseline offset.

  • A0-6 ID: E-21
  • Decision: ridgeline plot in §14 of chart-types-applied.md partially covers this. Pure joy plots are documented as an alternative; no separate example figure.

§4.3 E-22 Axis Break / Discontinuity Markers

Broken-axis figures (the // slash marks on an axis).

  • A0-6 ID: E-22
  • Decision: documented as a warning in chart-type-guide.md and in apa-figure-standards.md -- broken axes obscure data shape and are widely discouraged. Recommended alternative: log-scale axis or facet split into two panels.

§5. Cookbook -- 10 inline-stats Patterns

These match add_inline_stats(ax, items, position) cookbook patterns from chart-type-guide.md §16 / statistical-annotations.md. The helper auto-formats: Latin keys italic, Greek upright, p-value via format_p_value, r / d / R^2 with no leading zero, n with thousands separators.

Pattern 1: Regression (simple linear)

add_inline_stats(ax, [
    ('slope', 0.42, (0.38, 0.46)),
    ('intercept', 32.5),
    ('n', 4200),
    ('R-squared', 0.61),
], position='upper_left')

Pattern 2: Meta-analysis (forest, heterogeneity cluster)

add_inline_stats(ax, [
    ('k', 10),
    ('I-squared', '42%'),
    ('tau-squared', 0.018),
    ('Q', 18.4),
    ('p_Q', '= .037'),
], position='lower_left')

Pattern 3: Survival (Kaplan-Meier)

add_inline_stats(ax, [
    ('HR', 0.65, (0.48, 0.88)),
    ('log-rank p', '= .006'),
    ('n', 1240),
], position='upper_right')

Pattern 4: ANOVA

add_inline_stats(ax, [
    ('F(2, 207)', 14.2),
    ('p', '< .001'),
    ('eta-squared', 0.12),
    ('n', 210),
], position='upper_left')

Pattern 5: Forest pooled (d + p + k + I^2)

add_inline_stats(ax, [
    ('d', -0.71, (-0.85, -0.57)),
    ('p', '< .001'),
    ('k', 10),
    ('I-squared', '42%'),
], position='upper_left')

Pattern 6: Correlation

add_inline_stats(ax, [
    ('r', 0.34, (0.21, 0.46)),
    ('p', '< .001'),
    ('n', 412),
], position='upper_left')

Pattern 7: Mediation

add_inline_stats(ax, [
    ('a', 0.34),
    ('b', 0.42),
    ('ab', 0.14, (0.08, 0.21)),
    ("c'", 0.08),
    ('n', 312),
], position='upper_left')

Pattern 8: Interaction

add_inline_stats(ax, [
    ('Stress x Support b', 0.39, (0.27, 0.51)),
    ('p', '< .001'),
    ('Delta-R-squared', 0.04),
    ('n', 248),
], position='upper_left')

Pattern 9: Event-study DID

add_inline_stats(ax, [
    ('beta-hat', -0.067, (-0.089, -0.045)),
    ('Pre-trend p', '> .15'),
    ('n', 50000),
], position='upper_right')

Pattern 10: RD

add_inline_stats(ax, [
    ('tau-hat', 0.148, (0.108, 0.188)),
    ('Bandwidth', 18.5),
    ('McCrary p', '> .20'),
    ('n', 1500),
], position='lower_right')

Rendering details (automatic)

  • Latin stat keys (slope, intercept, n, r, p, F, R) auto-italicized via $\mathit{...}$.
  • Greek keys (tau, eta, beta, chi, sigma, alpha) rendered upright via mathtext custom font.
  • p-value formatting via format_p_value(p) -- no leading zero, < .001 for p < .001, = .037 otherwise.
  • r / d / R^2 default to 2 decimals, no leading zero (for |value| < 1).
  • 95% CI displayed as [lo, hi] after the value when the third tuple element is a (lo, hi) pair.
  • Line spacing 0.06 axes-fraction per line (visually comfortable at 8 pt).
  • Italic Latin can be disabled via italic_latin=False (rare; only when the chart already has italic display elsewhere).

§6. How to Use This Catalog

§6.1 Building a top-grade figure from scratch

  1. Open the relevant chart type's "Journal-grade upgrade checklist" in chart-types-core.md / chart-types-models.md / chart-types-causal-econ.md / chart-types-applied.md.
  2. Apply the 5 moves listed there. Each move cites a P0 element from this catalog.
  3. Add P1 elements specific to your chart type / discipline as needed.
  4. Skip P2 / P3 unless you have a specific reason.

§6.2 Auditing an existing figure

Use the reverse index in this file. For each panel of your figure:

  1. Ask "which P0 elements are visible?" Count them. Top-grade figures typically show 4+.
  2. Check the example figures listed for each element to see how it appears in practice.
  3. The most reliable single upgrade move: add inline statistics (E-03). If your figure does not yet have an add_inline_stats call, that is the first thing to add.

§6.3 Discipline-by-discipline default elements

Discipline Default P0 elements Default P1 elements
Psychology E-03, E-04, E-07, E-23, E-24, E-25, E-29 E-17 (pairwise brackets), E-18 (raw + mean overlay)
Economics E-03, E-04, E-07, E-08, E-15, E-23, E-24 E-10 (axvspan for treatment window), E-27 (white-halo)
Clinical / NEJM E-03, E-04, E-07, E-20 (at-risk), E-23, E-24 E-01 (inset zoom)
Public health E-03, E-04, E-07, E-15, E-19, E-23, E-24 E-11 (Favors A/B anchors)
Methodology E-03, E-15, E-19, E-23, E-24, E-25, E-26 E-17, E-18

These are defaults, not requirements. Specific journals or specific manuscripts may shift them.

§7. Quick reference: element to helper mapping

Element A0-6 ID Helper
Inline statistical annotation E-03 add_inline_stats
Reference lines E-04 add_reference_line
Two-tone emphasis pair E-07 get_emphasis_pair
Small multiples E-15 small_multiples
Cross-panel consistency E-26 compose_grid, small_multiples, apply_style
Inset zoom axes E-01 add_inset
Marginal histogram E-02 add_marginal_hist
Pairwise significance brackets E-17 add_significance_bracket
Theoretical reference markers E-28 add_reference_line (with label)
Paper / slides dual mode E-30 apply_style(mode='paper'/'slides')
Panel labels (uniform) implicit in E-26 add_panel_labels, panel_labels='auto'
Multi-panel composition implicit in E-15 compose_grid, compose_subfigures
Shared colorbar implicit in E-26 add_shared_colorbar
Shared legend implicit in E-26 add_shared_legend
Effect-size annotation (single) E-03 variant annotate_effect_size (legacy single-stat)

All helpers defined in scripts/ssci_style.py. See scripts/ssci_style.py for the complete signature of each helper.

§8. Element-to-Example Reverse Index

If you want to see an element in code, use this table to find the example figure that demonstrates it.

Element Demonstrated in figures
E-01 Inset zoom 10, 11, 15, 18
E-02 Marginal hist 18 (Panel B only)
E-03 Inline statistical annotation 01, 02, 03, 05, 06, 07, 09, 10, 13, 14, 17, 18
E-04 Reference lines 01, 02, 04-13, 16, 17
E-05 Bubble size encoding 05 (forest weight)
E-06 Continuous color gradient 04, 15
E-07 Two-tone emphasis pair 01, 03, 05, 06, 08-11, 13, 14, 17, 18
E-08 Line weight hierarchy 03, 06, 08, 09, 11, 17
E-09 Connector / callout boxes 14
E-10 Highlighted region (axvspan) 06, 09
E-11 Bidirectional anchors 05, 13
E-12 Means + individual trajectories 17
E-13 Dual axes 16 (optional)
E-14 Panel schematic 03, 18
E-15 Small multiples / faceting 08, 13, 16-18
E-16 Bootstrap path (P3) -- (snippet only)
E-17 Multi-tier pairwise brackets 02, 07
E-18 Raw + mean + CI 3-layer 02, 06, 08 (Panel A), 17
E-19 Heterogeneity / context annotation 05, 18
E-20 Embedded in-figure table 04, 05, 11, 12, 18
E-21 Stacked / joy plot (P3) -- (mentioned in ridgeline)
E-22 Axis break (P3) -- (warning only)
E-23 Tick density calibration ALL 18
E-24 Font hierarchy ALL 18
E-25 White-space rhythm ALL 18
E-26 Cross-panel consistency 08, 13, 17, 18
E-27 White-halo line 09 (unique)
E-28 Theoretical reference markers 09, 11, 17
E-29 Greek letter inline annotation 02, 03, 05, 09
E-30 Paper / slides dual mode 18 (demonstrated dual-output)

To inspect an example: open examples/generate_examples.py and search for # Figure NN: or def fig_NN(...).