BZJZ_Material/文档润色流和知识库构建流/claude-scholar/skills/publication-chart-skill/references/source-guides/pubfig-architecture.md

pubfig architecture (source-driven)

This guide reads pubfig from the source tree rather than from high-level overview material.

Source root:

• pubfig/src/pubfig/__init__.py
• pubfig/src/pubfig/plots/
• pubfig/src/pubfig/export/
• pubfig/src/pubfig/specs.py
• pubfig/src/pubfig/themes/
• pubfig/src/pubfig/colors/
• pubfig/src/pubfig/cli.py

1. Start at pubfig.__init__

The stable user-facing surface is re-exported from __init__.py.

That file tells you the package is organized into five main layers:

1. plot constructors from plots/
2. export helpers from export/
3. publication sizing from specs.py
4. theme and palette registries from themes/ and colors/
5. Figma/bridge helpers and related CLI support

For skill design, this is the most important architectural fact:

• figure generation lives in plots/
• figure export lives in export/
• venue sizing lives in specs.py
• multi-panel/Figma handoff is a separate downstream layer

The default mental model is plot first, export second, compose third.

2. Package boundaries

plots/

This is the core figure-construction layer.

Representative files:

• plots/line.py
• plots/comparison.py
• plots/evaluation.py
• plots/_grouped_scatter.py

From the source, plot functions usually do the same sequence:

1. normalize/coerce input data,
2. enter theme_context(theme),
3. resolve design-time size via resolve_design_dpi(...),
4. allocate figure/axes via get_fig_ax(...),
5. style axes/legends through helpers in _style.py,
6. return a Matplotlib Figure.

Interpretation from source:

• pubfig behaves as a Matplotlib-first figure factory layer, not as a separate scene-graph runtime.

export/

This is intentionally separated from plotting.

Important files:

• export/io.py
• export/panels.py

export/io.py handles normal figure export:

• coerce Figure/Axes into a real Figure
• enforce explicit suffixes
• apply publication width/height rules
• write vector or raster output

Current source implication:

• batch_export(...) now belongs to the same publication-aware export layer, rather than to a simple multi-format savefig wrapper.

export/panels.py handles panel-level export for composite or Figma-oriented workflows:

• one panel at a time or many panels together
• optional publication-aware sizing
• optional title stripping
• metadata index generation (panel-index.json)

specs.py

This file is the publication-sizing contract.

FigureSpec defines:

• font_family
• design_dpi
• single_column_mm
• double_column_mm
• default_raster_dpi
• background_color

Built-in registry entries include:

• nature
• science
• cell

The source shows a strong split between:

• design size used when constructing interactive figures,
• physical export size used when saving publication figures.

That split is why the skill should not treat width in plot calls and width in export calls as the same semantic layer.

themes/ and colors/

These are registries, not plain constants.

From __init__.py, the public surface includes:

• get_theme, register_theme, set_default_theme
• get_palette, register_palette, show_palette

Operational implication:

• treat theme and palette selection as first-class API configuration rather than as hardcoded styling trivia.

cli.py

The current CLI is not the main figure-generation interface.

From the source, cli.py is mainly about:

• Figma bridge serving
• bundle packaging/inspection/validation
• sync job submission and waiting
• local bridge auto-start logic

So for this skill:

• Python API is the primary route for figure generation
• pubfig.cli is a secondary operational layer for bridge/Figma workflows

3. Plotting architecture pattern

From line.py, comparison.py, and evaluation.py, the recurring internal pattern is:

• input normalization is local to the chart family,
• shared visual behavior is delegated to internal helpers,
• returned artifact is still a standard Matplotlib figure.

This is why the skill should map requests to a chart family first, instead of jumping directly to export or panel assembly.

Examples from source:

• line.py groups time/trend style plots
• comparison.py groups comparison-style statistical displays like dumbbell and forest_plot
• evaluation.py groups metric/evaluation plots like roc, pr_curve, and calibration
• _grouped_scatter.py contains the more specialized placement/jitter/annotation logic behind grouped scatter layouts

4. Export architecture pattern

From export/io.py and export/panels.py, pubfig uses three distinct output modes:

1. single explicit artifact via save_figure(...)
2. publication-aware multi-format artifact set via batch_export(...)
3. panel bundle workflow via export_panel(...) / export_panels(...)

Those are different contracts, and the skill should keep them separate in its recommendations.

5. Reading order for deep debugging

When a skill or agent needs source-level certainty, use this order:

1. pubfig/src/pubfig/__init__.py
2. relevant chart-family module in plots/
3. pubfig/src/pubfig/specs.py
4. pubfig/src/pubfig/export/io.py
5. pubfig/src/pubfig/export/panels.py
6. pubfig/src/pubfig/cli.py only if the task involves bridge/Figma sync

6. Implications for this skill

This source layout implies the skill should:

• default to Python plot API + explicit export call,
• treat publication sizing as an export concern,
• treat panel/Figma work as optional downstream composition,
• avoid presenting the CLI as the main path for ordinary figure generation,
• keep chart selection logically ahead of export tuning.