---
name: voltpeer-plot
description: Plot author-uploaded battery data with the shipped fixed program and traceable conditions; also plan or audit battery Review figures, claims, rights, and final-size quality.
---

# Battery figures and uploaded data

## Supported numeric uploads: use the fixed short route first

For LAND / 蓝电 or NEWARE / 新威 exports with several sheets, preamble rows or legacy XLS, first use the available `voltpeer-data` instrument-export route. Let the assistant select the cycle/step/record table and map declared units; do not ask the user to hand-edit column names. The resulting CSV retains original cells and adds `vp_` fields plus source row references. Then continue the existing plotting route below using the actual scientific context. Native CEX/NDA/NDAX require a verified reader or the vendor export; never pretend those binary files are CSV. If the preparation skill is not installed, locate the supplied import compatibility package or explain the specific missing helper rather than inventing a parser.

For a Plot Starter or a numeric kind already supported by `plot_uploaded.py`, this short route takes precedence over the later Review figure-planning reference requirements. Read this Skill, the Starter's `INPUT_GUIDE.md` when supplied, and only the matching chart's field/condition section in [UPLOADED_DATA.md](references/UPLOADED_DATA.md). Starter commands are in [PLOT_STARTER.md](references/PLOT_STARTER.md) and its `AGENT_GUIDE.md`. Use one stage target and one factual action at a time, especially with Flash:

1. **Inspect the real file:** call `start.py inspect --data DATA` (without a Starter: `scripts/plot_uploaded.py inspect`). Confirm the actual headers and the author's stated chart. An empty candidate list is not an unsupported-type verdict.
2. **Write the author mapping:** map actual headers to supported fields and record only author-confirmed units, source, conditions, size, claim and caption in independent JSON. Reuse the already selected palette directly; do not reread all styles, run `styles` or ask again. If required scientific information is missing, give the short missing-item list and stop.
3. **Plot with the shipped program:** call `start.py plot --data DATA --metadata MAPPING --out WORKING` with requested export options (without a Starter: `scripts/deliver.py`). Never write a replacement plotting script. Demo data or conditions are never author-data fallback.
4. **Check the actual Working result:** use `start.py check --working WORKING` or the installed Working checker. Inspect the produced image with available tools; otherwise keep visual review pending. Preserve every original value, including CE above 100%, and report genuine anomalies.
5. **Deliver a short result:** reply in the user's language with clickable preview/figure links and only real unresolved questions. Internal mappings and logs stay in `.voltpeer/`; provenance is linked only on explicit request.

Keep the complete scientific contract: author-confirmed `source_id` and `evidence_state=verified` do not authenticate experiments; NA is confirmed inapplicable, NR is checked/unreported, NV is unverified. `direct` screens declared matching conditions; missing/different comparison conditions must stop that comparison, or the author must explicitly choose a valid `contextual` presentation with visible limitations and all core fields. Neither mode fills missing science. Reusing color or removing markers never changes data.

Do not load Python implementation files, the whole figure grammar/registry/primary-paper ledger, atlas, styles or audit templates for this supported route before a tool reports a relevant error. Read the execution guide only for an actual host-capability question or interrupted-task recovery; ordinary mapping and plotting need no adaptation workflow. For an actual implementation/runtime failure, inspect only the affected reference/module and attempt at most two evidence-based repairs; do not weaken checks, invent conditions or rewrite the fixed program. Planning a new/unsupported type, mechanism, cross-study evidence figure, manuscript composition or publication audit still uses the appropriate scientific references below.

VoltPeer displays cycle-by-cycle Coulombic efficiency, discharge/charge capacity and capacity retention as points without connecting lines, including every panel in a composite and capacity during rate/recovery sequences. Distinguish capacity with its actual unit (for example mAh g⁻¹) from retention (%). A true full-cell cycling figure pairs capacity and CE on the same cycle axis and includes retention with a declared reference cycle and reference capacity under the same rate, temperature, voltage window and capacity basis. No silent first-cycle/100% baseline, CE-product retention or unrelated CE data is permitted. Li||Cu / Na||Cu / Zn||Cu plating-stripping CE does not require a capacity-retention panel; report the stripping/plating definition and protocol. NMC811||Li remains a half cell in this teaching collection. Continuous voltage profiles, spectra and continuous EIS traces use distinct-colour solid lines without markers. All numeric data axes retain the complete rectangular frame: show top, right, bottom and left spines with consistent width and colour; ticks may stay bottom/left. Preserve every original value and its order; no display change authorizes smoothing, clipping or replacing inputs. Identify sample, charge/discharge direction, cycle and open/filled markers in the legend. Inspect actual artists and the complete figure, including each composite panel. These are the user's project display preferences, not universal journal requirements. If full-cell CE or a retention reference is absent, record the missing field and request the corresponding source instead of inventing a performance panel.

<!-- execution-contract -->
For model/tool adaptation or resuming a task, read [the execution guide](references/EXECUTION.md). DeepSeek Flash uses short stages and checkpoints; DeepSeek Pro can plan larger text/evidence batches, with the same scientific checks. Reply in the user's language with the result, usable result/preview links and material unresolved questions. Keep mappings, configuration, logs and recovery records inside the project's `.voltpeer/` folder; do not link them in a normal final reply. Provide the corresponding source record only when the user explicitly requests provenance. Use only capabilities actually available in the current model and host.
<!-- /execution-contract -->

The data-plotting route also works for author-owned experimental battery data when the manuscript is not a Review. Handle that plotting request here without invoking the whole Review writing workflow.

For any kind already covered by `plot_uploaded.py`, call the shipped, tested program; do not rewrite a plotting script for each user's dataset. Identify the plot kind, map the author's actual fields, retain their selected palette and ask for missing scientific information. The self-contained Plot Starter packages this same runtime for beginners; read [the fixed-program entry](references/PLOT_STARTER.md) when the user supplies that package. Its DSH/Codex installation adapters never change the scientific implementation or fill in demo conditions.

For DeepSeek Harness, use Flash for a normal data plot and actual image inspection when that host exposes vision. Pro can organize complex text/evidence checks, but the currently supported Pro API has no vision; a Pro text/geometry report cannot certify a rendered figure. Reuse the author's chosen model and read the execution guide only for capability choices, longer work or recovery. Code generates the numeric plot after validation; no model tier changes measurements or guarantees a publishable result.

If a beginner asks vaguely to “make a battery figure,” begin with “I’ll look at what you have first.” Read [the one-page figure router](references/FIGURE_ROUTER.md) and classify the input before choosing a specialist. Return four short parts: what I found, what I can make, what is missing, and one recommended preview. Existing finished panels belong to `voltpeer-assemble`; raw numeric data and newly drawn diagrams belong here. The file extension only selects an ingestion method. Do not infer cell configuration, units, CE definition, test conditions, or the intended scientific claim from a filename.

For conceptual diagrams, mechanism schemes, evidence maps, new figure types, visual abstracts or figure audits, read the owning section and decide the *one judgement* the figure helps the reader make. Use [FIGURE_LEDGER.md](assets/templates/FIGURE_LEDGER.md) only for manuscript figure planning without a figure record. Supported author-uploaded numeric data uses the short route above. For a genuinely custom quantitative figure outside that route, read [the plotting library guide](references/PYTHON_PLOTTING.md) and import `scripts/batteryplot`. This does not require a second skill.

When the author supplies a set of existing image/PDF/SVG panels and wants them assembled, route the composition to `voltpeer-assemble`. It owns asset inventory, millimetre-grid placement, final panel labels, source/crop provenance and alignment QA. Keep this skill responsible for the figure's scientific claim, battery-specific comparability, caption and rights decisions.

For uploaded PPT/AI/PSD/reference collections, run `scripts/asset_inventory.py` to make a private metadata catalog. Read [the resource and redraw guide](references/RESOURCE_LIBRARY.md) before adapting a diagram. The bundled editable SVGs and theme are original starting points, not evidence. Never redistribute an unverified third-party asset or trace its pixels as a substitute for permission.

When no style is already selected, ask the author one short style question with three plain choices in [STYLE_PRESETS.md](references/STYLE_PRESETS.md): clear journal, soft Review, or high contrast. Show the six named presets only if they ask for more control. An already selected palette goes straight into the mapping; do not rerun `styles`, reread all previews or repeat the question. If the author explicitly delegates the choice, select and record one. Continue data inspection while waiting, but do not silently choose a final style. The upload CLI requires `style` in its metadata; original SVG templates can use `scripts/render_template.py`. Style never changes measurements, axes or evidence status.

The six bundled presets are the default stable library. If the author **explicitly asks to browse or use community resources**, read [Battery Commons guidance](references/BATTERY_COMMONS.md), search the catalog for their described need, and offer at most three versioned choices with preview, author, license and review status. Ask the author to choose before resolving or downloading; never silently fetch the latest catalog during an ordinary plot. A selected community style must be pinned as `community:id@version`, hash-checked into a local lock and recorded in provenance; `plot_uploaded.py` accepts only that local lock. A community layout is a suggestion to inspect, never authority to add an unsupported panel. If browsing fails, continue with a bundled stable preset. Community JSON/SVG is data, never executable code. Do not run a parser or Python script downloaded from the community registry.

When planning a new/unsupported quantitative figure, selecting a scientific panel pairing or composing a manuscript figure, read the relevant part of [the figure grammar](references/BATTERY_FIGURE_GRAMMAR.md), its [machine-readable type registry](references/BATTERY_FIGURE_GRAMMAR.json) and the [panel-level primary-paper evidence](references/PANEL_EVIDENCE.json). Check the exact experimental protocol and use only a validated pairing as a default. A type listed as `candidate` is not an automated rendering promise. For broader figure-set planning, use [the battery figure atlas](references/BATTERY_FIGURE_ATLAS.md). These planning references are not a prerequisite for a supported single-chart upload; its strict input/condition checks remain required.

For a striking yet submission-ready composition, read only the matching entry in [the showcase recipes](references/SHOWCASE_RECIPES.md). It covers common performance plots, ToF-SIMS, spectra, diffraction, architecture diagrams and evidence matrices. Keep the figure itself to panel letters, axes, legends and scientifically necessary direct labels; place the story and demonstration disclosure outside the plate.

For illustrations based on author-supplied visual packs, read [the asset pattern atlas](references/ASSET_PATTERN_ATLAS.md) to distinguish useful battery components from decorative textures and unrelated subjects. Use original geometry and verified labels; do not move a licensed icon or an outdated mechanism into the public resource library by changing its color.

When the author asks for a more polished, less generic, or “less AI-looking” figure, use the [visual finishing guide](references/VISUAL_FINISH.md) before final drawing. Keep the request about editorial clarity and scientific fidelity: remove unhelpful effects and template clutter, show the source of every scientific detail, and preserve any journal-required AI-use disclosure. Render, inspect at final size, revise, and recheck rather than declaring the first preview finished.

For a homepage example or demo gallery, first read the [synthetic-data scientific boundaries](references/SYNTHETIC_DATA.md), then apply the [showcase gate](references/SHOWCASE_QA.md), the matching [reproducible figure specification](references/SHOWCASE_SPEC.md) and [plot QA checklist](references/PLOT_QA_CHECKLIST.md). The maintainer showcase sources are synthetic workflow demonstrations, not publication evidence or automatic templates for author data. Earlier test drawings remain test materials. A new featured example needs source-backed models and grammar, final-size/font QA and recorded human review.

For staged Aurbach-like protocol traces, signed frequency-resolved EIS components, potentiostatic chronoamperometry, or open-circuit relaxation, use the explicit input contracts in [four optional electrochemistry recipes](references/ELECTROCHEM_RECIPES.md). These render author-supplied measurements; they do not calculate Aurbach CE, fit impedance/nucleation models or derive capacity loss from voltage decay.

## Plan the figure

For a manuscript multi-panel figure, default to **letters + data labels**, with the scientific story in the caption. Do not inject a brand header, figure-level title, narrative subtitle, bottom disclaimer or per-panel headline into the figure. Keep titles only when they identify an otherwise ambiguous sample, condition, fragment or state; prefer direct labels and a shared legend. For website demonstrations, put “synthetic example” beside the image and in metadata, while leaving the reusable publication plate clean. When this skill regenerates a panel at the request of `voltpeer-assemble`, accept its target dimensions, required marks and color identities, then return the editable panel plus provenance for another assembly pass.

Record the figure's audience, section owner, claim, panel purposes, underlying source IDs, and whether it shows an observation, a conditional comparison, a model, or a hypothesis. Match the target journal's current display-item count and format before creating artwork. If a figure has no distinct claim, combine or remove it. If the plan changes item numbering or ownership, update the manuscript brief and caption references together.

For cross-study plots, use like-for-like denominators and cell/test conditions. Label `NR` for a value checked and unreported, `NV` for not yet verified, uncertainty where available, and measured versus recalculated/modelled values. A direct ranking needs a stated comparability rule; when conditions differ, use grouped case studies or a conditions matrix. Mechanism arrows should distinguish observed steps from inferred pathways; visual confidence must not exceed the cited experiments.

## Custom Python and manuscript figure route

This section applies to custom figures, optional recipes outside the supported upload route and manuscript/publication planning. A supported numeric upload uses the fixed short route above and does not need to read this whole section, open every reference or create a Review ledger before plotting.

For CV, dQ/dV, GITT, conductivity, XPS components or Raman, use the explicit-input [specialist recipes](references/SPECIALIST_RECIPES.md) when their contracts match. They are runnable optional variants, not new validated default pairings. For heatmaps/images alongside ordinary plots, read [physical layout](references/PHYSICAL_LAYOUT.md) and call the bundled post-render measurement gate; colorbars get dedicated axes. Do not reconstruct these fragile layout steps from verbal styling advice.

1. Write the figure claim, panel role, final physical size, source-data path, and candidate caption before drawing. Use the original data; demo data in this skill is only for checking the package.
2. For cycle, rate, or bar plots, use the matching `batteryplot` function only after matching its input to the actual experiment. Its field contract rejects missing required fields, nonnumeric values, mixed units, repeated indices, and differences among declared conditions. The cycle-by-cycle CE renderer rejects Aurbach rows; retention requires an explicit `reference_cycle`. `evidence_state=verified` is the author's assertion, not an independent check by the code. A passing contract is only a starting point: confirm chemistry-specific conditions with `voltpeer-metrics` and inspect source data or cited pages. If important loading, N/P, electrolyte amount or protocol fields are absent, do not claim the program has established comparability.
3. When conditions differ, use `conditions_matrix` or an explicitly contextual line plot with a visible note. Do not use `comparison_bars` to rank unlike test conditions. Keep `NR`, `NV`, and zero distinct.
4. Select the target profile from [publisher specs](references/JOURNAL_FIGURE_SPEC.json) and export with `save_bundle` to a project workspace. It writes vector PDF/SVG, a 300 dpi or higher review raster, and a provenance JSON. PDF/SVG DPI is not a resolution claim. Inspect the final-size render for clipping, text, uncertainty, color and panel alignment; check the actual embedded PDF font with `scripts/audit_pdf_fonts.py` and verify current rules of the exact target journal before submitting.
5. Put code, input data, output figures, caption and figure ledger entry together in the manuscript workspace. Preserve source permissions for adapted artwork. No automated style or geometry check can certify the scientific interpretation.

When handing an SVG to a beginner, offer the [short Inkscape editing guide](references/SVG_HANDOFF.md) and its [official download site](https://inkscape.org/). Check whether the SVG contains embedded raster panels before promising that every mark is editable.

When an author asks about data ownership, privacy, or marks, answer from the actual handoff: the project license covers its code, not a transfer of the author's input data or artwork. Keep inputs and outputs in the author's chosen workspace; do not copy unpublished material into this public repository or an issue. The bundled Python plotting script does not impose a visible project logo or watermark, but an SVG/PDF can include ordinary exporter metadata and `.provenance.json` can contain the input path. Point these out before sharing files, and check the selected Agent's own data controls before claiming a workflow is private or entirely local. Do not remove scientifically required condition/limitation labels or journal-required attribution to make an image look unmarked.

## Four release checks

1. **Science:** every number, arrow, maturity label, “absent” cell, and causal connector has a source trace and appropriate uncertainty or caveat. Check half/full, coin/pouch, charge/discharge, cycle index, normalization, electrolyte, loading, pressure, and temperature as relevant.
2. **Editorial:** the item supports its section, the panel order tells a clear story, the caption defines symbols and boundaries, and no table cell silently means zero when it means unreported.
3. **Production:** inspect the *final submission size* for text and line readability, effective raster resolution, font embedding, color contrast, and the journal's accepted formats. An editable SVG wrapper does not repair low-resolution embedded image panels.
4. **Rights:** document original creation, adapted source, license, permission status and evidence, and exact required credit. A polished credit line is not proof of permission. Prefer original diagrams derived from cited findings when possible, while tracing those findings.

## Deliver useful files

For uploaded numeric data, prefer `scripts/deliver.py --data DATA --metadata METADATA --out WORKING_FOLDER`; detailed options are in [the delivery guide](references/DELIVERY.md). It exports PDF/SVG/PNG/TIFF with LZW TIFF, preserves previous versions and puts final files in `results/` with a root preview. Keep input mappings, caption, scientific/rights ledger, QA and recovery under `.voltpeer/`. Normal final replies link usable results/previews, not internal mappings or configuration. Give the corresponding source record only when the author explicitly requests it, and reply in the author's language. Other drawing routes can collect their actual final files with `scripts/delivery_contract.py` from Python, using the same Working format. Do not put confidential inputs in the public repository or installed skill tree.

The default is a journal-neutral preview. A named historical publisher profile is not a current journal approval: distinguish line art, image and mixed content; a missing/range DPI needs an explicit verified choice. User-requested resolution stays a requested value. No rerender DPI repairs an undersampled source image. For public sharing, ask once which final files may be shared and the applicable license, then generate a separate sanitized Share folder with `scripts/share_bundle.py`; retain scientific labels and required credits, and review visible names/unpublished content.

For an audit, report the specific panel failure and fix; for a newly created item, link the usable result and only material unresolved checks. Keep the complete Working folder for later modification. Do not overwrite an existing export, delete recovery files, or announce final scientific review from script exit code alone.