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

pubfig API map (source-driven)

This guide maps the public pubfig API from pubfig/src/pubfig/__init__.py to the underlying modules.

1. Stable entrypoint

The public contract is defined by re-exports in pubfig.__init__.

For agents, this means:

• if a symbol is re-exported there, it is a good default public entrypoint;
• if a helper only exists in deep internal modules, treat it as implementation detail unless there is a strong reason not to.

2. Public API groups

Themes

Public re-exports:

• set_default_theme
• get_default_theme
• get_theme
• register_theme

Use these when the task is really about reusable visual policy. Do not hardcode theme assumptions if a registry call is more appropriate.

Colors and palettes

Public re-exports include:

• DEFAULT, NATURE, SCIENCE, LANCET, JAMA
• get_palette
• register_palette
• color_to_rgba
• darken_color
• show_palette

Source fact:

• palette registration and palette inspection are exposed from the package root.

Operational implication:

• treat palette selection and palette registration as public API usage, not as deep internal customization.

Export

Public re-exports:

• save_figure
• batch_export
• PanelExportRecord
• export_panel
• export_panels
• package_figma_bundle
• validate_figma_bundle
• inspect_figma_bundle

Skill implication:

• normal paper figures should usually stop at save_figure or batch_export
• panel workflows should use export_panel(s)
• bundle helpers are for bridge/Figma handoff, not the default answer

Figure specs

Public re-exports:

• FigureSpec
• get_figure_spec
• register_figure_spec
• list_figure_specs

Use this layer whenever the user asks for venue-aware width, journal defaults, or a custom export profile.

Plot families

The public plot surface is broad, but the source still clusters naturally.

Comparison / summary figures

Representative public calls:

• bar
• bar_scatter
• stacked_bar
• stacked_ratio_barh
• donut
• dumbbell
• forest_plot
• grouped_scatter
• upset

Use these for benchmark, ablation, summary, composition, and set-overlap tasks.

Distribution figures

Representative public calls:

• ecdf
• qq
• box
• density
• hexbin
• histogram
• raincloud
• strip
• ridgeline
• violin

Use these when the scientific claim is about spread, calibration of assumptions, or cohort structure.

Trend / profile figures

Representative public calls:

• line
• area
• parallel_coordinates
• radar
• radial_hierarchy
• circular_stacked_bar
• circular_grouped_bar

Not all of these are equally strong for publication use. The skill should still apply chart-selection discipline before calling them.

Relationship / embedding figures

Representative public calls:

• scatter
• volcano
• bubble
• contour2d
• paired
• heatmap
• corr_matrix
• clustermap
• dimreduce
• pca_biplot

Use these for association, error structure, feature layout, and representation views.

Evaluation figures

Representative public calls:

• roc
• pr_curve
• calibration
• bland_altman

This cluster matters because the source gives them dedicated implementation in plots/evaluation.py, which is a sign that evaluation charts are a first-class use case.

3. Return-value contract

The source in export/io.py makes a subtle but important contract explicit:

• export functions accept a Matplotlib Figure,
• or an Axes,
• or any object exposing a .figure attribute that resolves to a Figure.

Source fact:

• the export layer accepts standard Matplotlib figure objects or figure-bearing wrappers.

Operational implication:

• keep the Figure handle available and route export through the standard Matplotlib-facing export path.

For the skill, the safest phrasing is:

• create the figure,
• keep a handle to the Figure,
• then export explicitly.

4. What is not the main stable plotting interface

From the source tree, the CLI is not where normal chart creation happens. It is mostly an operational layer for Figma bundle and bridge actions.

So if a user says “generate a paper-ready figure,” the skill should not default to a CLI answer.

5. Safe public usage pattern

The most source-faithful pattern is:

1. choose a public plot function from pubfig
2. generate a Figure
3. export via save_figure(...) or batch_export(...)
4. only use panel/bundle helpers when composition is actually required

6. Source-guided caution points

• Do not mix up plot-time design sizing with export-time publication sizing.
• Do not use save_figure(...) as a multi-format exporter; the source now pushes that role to batch_export(...).
• Do not route ordinary figure-generation tasks through the Figma bridge CLI.
• Do not assume all public plot families are equally appropriate; the skill must still filter by scientific communication quality.