Matplotlib MSSP Scientific Plotting Skill

中文说明

A guided Codex skill for creating, recommending, auditing, and precisely refining publication-ready Matplotlib figures. It combines reusable runnable demos with the MSSP Compact Dynamics style and a conversational plotting wizard.

The examples use synthetic data. Replace the arrays or data-loading section with your own CSV, TXT, NPY, or DataFrame without changing the plotting structure.

Example Gallery by Type

Jump to: relations · distributions · fields · signals · dynamics · machine learning

1. Relations and categorical comparisons

Show or hide two examples: relations and categorical comparisons

Relations and uncertainty	Categorical comparisons

2. Distributions and model validation

Show or hide two examples: distributions and validation

Distribution and uncertainty	Experiment-versus-model validation

3. 2D fields and 3D surfaces

Show or hide two examples: fields, vector flows, and response surfaces

2D fields and vector flows	3D response surfaces

4. Frequency response and time-frequency analysis

Show or hide two examples: FRFs and time-frequency fields

Frequency-response comparison	Time-frequency field

5. Nonlinear dynamics

Show or hide two examples: phase geometry and attraction basins

Phase portrait and Poincaré section	Basin of attraction

6. Machine-learning diagnostics

Show or hide two examples: confusion matrices and evaluation curves

Classification confusion matrix	Classification evaluation curves

These twelve figures are generated directly by the included demos. The full local suite currently contains 30 demo scripts and produces 54 checked PNG outputs. README previews are web-sized; running the demos retains the publication export settings.

What It Does

• Recommends one conventional figure and one more innovative alternative from the scientific purpose and data geometry.
• Creates new Matplotlib programs or refines existing figures property by property.
• Covers lines, scatter, bars, distributions, 2D fields, 3D surfaces, machine-learning diagnostics, nonlinear dynamics, FRFs, and time-frequency plots.
• Standardizes fonts, axes, ticks, legends, colorbars, panel labels, layouts, physical dimensions, and export settings.
• Saves reusable project defaults in the plotting workspace so confirmed choices are not asked again.
• Audits existing images and notebook savefig calls before refactoring them.

Install

git clone https://github.com/FFFxueGawaine/sci-paper-plot-skill.git ~/.codex/skills/matplotlib-mssp-skill
cd ~/.codex/skills/matplotlib-mssp-skill
python -m pip install -r requirements.txt

To update an existing installation:

cd ~/.codex/skills/matplotlib-mssp-skill
git pull

Fastest Usage

Invoke the skill and describe the scientific message rather than guessing a Matplotlib API:

$matplotlib-mssp-skill Compare the error distributions of three methods.

$matplotlib-mssp-skill Plot a 2D time-frequency spectrum and recommend the normalization.

$matplotlib-mssp-skill Inspect this existing script and change only the line width,
legend arrangement, and double-column dimensions.

For a new figure, the wizard asks only for missing information, then presents one common and one innovative option. For an existing figure, it inspects the code and rendered image first and exposes seven edit groups: dimensions/export, plot elements, axes/ticks, text, visual enhancement/data treatment, layout, and fonts.

Useful Commands

Run these from the skill folder:

# Show the beginner route and interactive wizard
python scripts/scimplstyle_mssp_cli.py beginner-guide --lang en
python scripts/scimplstyle_mssp_cli.py run-brief --lang en

# Find or inspect demos
python scripts/scimplstyle_mssp_cli.py list-demos
python scripts/scimplstyle_mssp_cli.py recommend "time-frequency validation" --lang en
python scripts/audit_figures.py "path/to/paper/figures" --markdown

# Generate a checked preview gallery outside the installed skill
python scripts/scimplstyle_mssp_cli.py check-demos paper-plot-preview --set curated

# Copy runnable demos into a project workspace
python scripts/scimplstyle_mssp_cli.py copy-demos paper-plot-workspace

Simple Tips

1. Start with the conclusion the figure must communicate, such as “compare uncertainty” or “show resonance drift.”
2. Reply use the recommendation to accept the suggested chart, palette, dimensions, or normalization.
3. Give exact properties when known, for example linewidth=1.6, ncols=2, or PDF only.
4. Keep project data and generated figures outside the installed skill. The normal final directory is figures/.
5. Confirm interpolation, smoothing, and outlier treatment explicitly because they change the data representation.
6. Use the adaptive PNG preview during iteration; export only the saved final PNG, PDF, SVG, or JPEG choice.

Demo Families

The 30 runnable demos are grouped by purpose:

• General Matplotlib and Seaborn: line, relation, categorical, distribution, 2D field, 3D surface, and tidy-DataFrame galleries.
• MSSP and engineering validation: FRF, time-frequency, experiment/model validation, inset zoom, three-column response, and the Fig. 1–Fig. 18 hierarchical-Bayesian template set.
• Nonlinear dynamics and identification: Duffing identification, bifurcation, basin of attraction, phase/Poincaré, nonlinear systems, and sparse candidate libraries.
• Machine learning: performance bars, ROC/PR/calibration curves, confusion matrices, embeddings, feature importance, hyperparameter heatmaps, prediction/truth, radar summaries, and residual KDEs.
• Error and uncertainty: boxplots, histograms, KDEs, violins, ECDFs, posterior densities, and confidence bands.

The machine-readable catalog is references/demo-index.json; the runnable sources are in scripts/demos/.

MSSP Defaults

• Single-column width: approximately 85 mm; double-column width: approximately 178 mm.
• English text: Times New Roman when available; formulas: STIX; CJK fonts use a tested fallback chain.
• Panel labels: bold lowercase (a), (b), and so on; MSSP subplots omit descriptive titles.
• Tick labels are slightly smaller than axis labels; legend text matches the axis-label size.
• Units use quantity (unit) by default; unknown or dimensionless units are omitted.
• Final filenames are short and date-free, such as Fig.1_Error_V1.

Built-In Reference Paper

The project includes a complete reusable figure map for:

Yusheng Wang, Hui Qian, Qinghua Liu, Yinhang Ma, and Dong Jiang, “Hierarchical Bayesian model for identifying clearance-type nonlinear system,” Mechanical Systems and Signal Processing, 235, 112891, 2025. DOI: 10.1016/j.ymssp.2025.112891

See references/hb-clearance-paper-figure-templates.md and demo_hb_clearance_templates.py.

Validation

python scripts/package_check.py .
python scripts/scimplstyle_mssp_cli.py check-demos paper-plot-preview --set all

The first command checks the skill package and documentation. The second executes every registered demo and checks that its PNG outputs are nonempty and have valid dimensions.