Jarvis-PLOT
Jarvis-PLOT is a lightweight, Python/Matplotlib-based plotting framework developed for Jarvis-HEP,
but it can also be used as a standalone scientific plotting tool.
It provides a simple command-line interface (CLI) to generate publication-quality figures from YAML configuration files, with most layout and style decisions handled by predefined profiles and style cards.
Current source candidate: 2.1.12 (jplot -v reports the installed version).
Release history: CHANGELOG.md. Design documents and specifications: Jarvis-Books Docs/Jarvis-PLOT/.
Installation
pip install JarvisPLOT
The PyPI / distribution name is JarvisPLOT (normalized wheel name: jarvisplot).
The product name remains Jarvis-PLOT.
The Python import package and entrypoint remain unchanged:
import jarvisplot
jplot path/to/config.yaml
If you have an older environment that still uses a historical package name, replace:
pip uninstall jarvisplot Jarvis-PLOT JarvisPLOT
pip install JarvisPLOT
Command-Line Usage
Human help uses the same fixed-column Rich panels as Jarvis-HEP V2 / Portal;
jplot -h prints the verb map, and jplot <verb> -h opens one verb.
Render with a bare path — there is no jplot run:
jplot path/to/config.yaml
jplot path/to/config.yaml --rebuild-cache
jplot path/to/config.yaml --print
Everything else is discovery and judgement, in three groups.
Discover — find out what is legal before writing anything:
jplot data describe samples.csv # columns, dtypes, ranges (HDF5 tree too)
jplot data head samples.csv -n 5 # real sample rows
jplot data eval 'exp(LogL)' --data samples.csv # sandbox an expr
jplot data suggest-axes samples.csv # scale / lim hints for frame.ax
jplot cap # section index
jplot cap methods # all | methods | transforms | types
jplot cap styles # | styles | cmaps | funcs | cli
jplot man # manual index
jplot man workflow # topic page
jplot man scatter # one method's contract
jplot explain JP-COL-001 # a diagnostic code
Draft & edit — scaffold or address a YAML by name:
jplot template list # template kinds
jplot template show posterior_2d # one template + its slots
jplot suggest --data samples.csv --kind posterior_2d
jplot config paths plot.yaml # named addresses in this file
jplot config get plot.yaml 'Figures[p].style'
jplot config set plot.yaml 'Figures[p].frame.ax.xlim' '[0, 10]' --write
jplot config expand plot.yaml --figure p --write # type: → layers
Judge — check without rendering:
jplot dryrun plot.yaml # load data + transforms, row ledger, JP-VIZ health
jplot doctor plot.yaml # internal YAML checks + light dryrun in one pass
Every one of these takes --json.
Default fonts
The bundled font card recommends Helvetica for sans text and STIXGeneral
for serif text, with STIX MathText formulas. Normal YAML rendering applies
the card automatically; explicit YAML fonts and sizes take precedence.
When Helvetica is absent, Jarvis-PLOT selects the first installed similar family:
Arial, Liberation Sans, Nimbus Sans, then DejaVu Sans. check and resolve
report the actual font and substitution reason.
jplot fonts # role card: title, labels, ticks, legend, text, annotations, caption
jplot fonts show title --json # current defaults for one role
jplot fonts show --recommended --json
jplot fonts list --filter Helvetica --json
jplot fonts list --refresh --json # rescan after installing fonts
jplot fonts resolve Helvetica --weight bold --json
jplot fonts check --json # actual installed faces used by the card
jplot fonts set roles.title.family sans
jplot fonts set roles.legend.family serif
jplot fonts set roles.title.size_pt 9
jplot fonts set roles.title.size_pt null # inherit the plot style's size
jplot fonts reset roles.title.size_pt
jplot fonts reset # remove all personal overrides
jplot man fonts --json
Personal overrides persist in ~/.jarvis/plot-fonts.json (JARVIS_HOME overrides
the directory). Queries never create that file. size_pt: null preserves the
plot style's canvas-specific size; recommended_size_pt is drafting advice.
Font discovery uses Matplotlib's cached system and bundled font index, while
TTC face selection preserves the requested weight and slant. $...$ uses
MathText; an external LaTeX compiler has its own font configuration.
Design-Reference Overlay
Set debug: true on a figure and Jarvis-PLOT draws a dimension overlay on top
of it: every axes box labelled with its rect and its size in centimetres, page
margins, the colorbar gap, and an "axes layout" panel. It is meant for checking
a layout, so a figure with layers: [] is a legitimate use.
Figures:
- name: layout_check
debug: true
style: [a4paper_2x1, rectcmap]
layers: []
The style card's Debug block decides what the annotations look like and which
of them appear; a per-figure debug: mapping overrides the card for that figure
only. See jplot man debug-overlay and STYLE_SCHEMA.md.
Figures[].debugis not thejplot --debugflag — the flag only raises the log level.
For Coding Agents
Jarvis-PLOT is built so a coding agent can drive it without ever seeing a rendered figure. The rule is the agent writes the YAML itself; the CLI's job is to say what is legal and to judge what was written. There is no verb that generates a finished config for you.
Every discovery and judging verb prints one JSON envelope on stdout, with humans and logs on stderr:
{"api_version": 1, "kind": "cap.methods", "ok": true,
"data": {...}, "diagnostics": [], "error": null}
--json turns it on, and it is already the default when stdout is not a
TTY — piping is enough.
The loop jplot man prints is:
Before drafting, inspect jplot fonts show --json and jplot fonts check --json
for the typography defaults and actual installed font choices.
jplot data describe <file> --json— column names from the real file. Never invent one; a wrong name is a hard error, not a warning.jplot cap methods|styles|cmaps|funcs|transforms|types --json— the legal strings, read live from the registries rather than from documentation.- Edit the YAML in an editor (or
jplot config set … --write). Reach for atype:macro first, drop to explicitlayerswhen the macro cannot say it. jplot doctor <file> --json— YAML checks + light dryrun in one pass. Diagnostics carryJP-*codes;jplot explain JP-XXX-NNNexpands any of them.jplot <file>— render, only when the figure itself is needed.
jplot man --json is the machine-readable manual: a topic index, plus
live pages for every registered layer method and transform step
(jplot man scatter, jplot man transform.profile, jplot man PDF1D). Method contracts come from
the same registry jplot cap methods reads, so a man page cannot drift from the
code.
For compact legends and keys composed from real layers, use
jplot man legend --json. Declare legend: {object, label, role} on each drawing layer; components
with the same object regroup automatically using card templates such as
band_line, line_errorbar and error_bounds. The role is optional for a
single-component object. frame.<axes>.legend owns card selection, order,
ncols, position and spacing. JSON cards provide
reusable defaults, and YAML can override them. See
the legend contract and the
self-contained example.
For continuous one-dimensional distributions from raw samples, use PDF1D
(CDF plus PDF) or CDF1D in a data transform. coordinates.x owns expr,
lim, and grid; optional repeat computes independent batch means and
standard deviations. See the contract and the
runnable example.
Reconstruction defaults to adaptive true CDF anchors and monotone_c2
interpolation (C2 CDF / C1 PDF). Set anchors: all and interpolation: pchip
to reproduce the original all-node reconstruction.
Two things worth knowing before trusting a config:
jplot doctorchecks YAML contracts, source paths and column headers, then performs a light dryrun. Heavy transforms and final layout require rendering the YAML and inspecting the figures.- AGENT_DATA_API.md describes a different, still-frozen bridge (a numeric digest channel for Jarvis-Agent). The surface above is what ships today.
Flowchart Rendering
Render a Jarvis-HEP flowchart scene JSON (produced by HEP scan tooling — this is not general plot YAML):
jplot flowchart path/to/scene.json
# optional output path:
jplot flowchart path/to/scene.json -o path/to/out.png
Library form:
from jarvisplot import render_flowchart, render_flowchart_file
Project Workdir and Cache
- You can set
project.workdirin YAML. - If
output.diris omitted, Jarvis-PLOT defaults to<workdir>/plots/. - Data cache is stored in
<workdir>/.cache/. --printaccepts the current settings and renders final figures without the logo. After all enabled figures are saved successfully, it requests deletion of this run's cache payloads. Cleanup waits until every reader of the workdir has finished. Rendering failures or a run with no enabled figures do not request immediate cleanup; ordinary age and capacity limits still apply. Unrelated entries and source fingerprints are retained unless the whole idle cache is evicted.- Profiling pipelines are prebuilt once and reused from cache when source fingerprint and profile settings are unchanged.
- Profiling uses a fast two-stage grid reduction (
pregrid+ renderbin) for large datasets.
Plot caches are automatically registered in ~/.jarvis/plot.json (or
$JARVIS_HOME/plot.json). The registry groups caches by workdir and records
associated YAML paths and last use; payloads stay in their original directories.
This includes caches created by data describe and default dryrun --with-data
exports. Sizes are calculated when listing, rather than stored in the registry.
jplot cache list
jplot cache scan ~/Jarvis-Workshop # register existing plot caches
jplot cache clean --workdir /path/to/project # this directory and all nested projects; repeatable
jplot cache clean --all --older-than 30 # unused for at least 30 days
jplot cache clean --all --dry-run # preview; no deletion/index changes
jplot cache clean --all # clean all registered inactive caches
jplot cache -h
jplot man cache
Automatic maintenance runs when a cache session starts and closes. The default
global budget is 5 GiB of registered cache file sizes; idle workdirs unused
for 30 days expire. Above the budget, the least recently used idle workdirs
are removed until usage falls to 80% of the limit (4 GiB by default). Active
workdirs may temporarily exceed the budget and are reconsidered after closing.
Eviction works on whole workdirs; it does not track each file's access time.
There is no background timer, and unregistered caches require cache scan first.
Configure positive finite limits in ~/.jarvis/plot-cache.json
($JARVIS_HOME/plot-cache.json when overridden):
{"max_size_gib": 5, "max_age_days": 30}
JP_CACHE_MAX_GIB and JP_CACHE_MAX_AGE_DAYS override the corresponding file
settings. For example, JP_CACHE_MAX_GIB=10 JP_CACHE_MAX_AGE_DAYS=14 jplot plot.yaml.
jplot cache list shows the effective policy; its JSON adds data.policy.
Invalid limits fail before rendering or automatic deletion.
--rebuild-cache requires exclusive access for the entire session and reports
an error if the workdir is active. A normal session also reports an error if a
rebuild holds the exclusive lease. Rebuild and cleanup remove only owned cache
components, preserving source files, figures, and unrelated .cache content.
Interrupted temporary writes and superseded HDF5 generations are reclaimed
when the workdir becomes idle. Failure to acquire a lifetime lock stops cache
use; index-registration failures with a valid lock remain warnings.
--workdir PATH selects registered caches in PATH itself and all of its
subdirectories, even when PATH has no cache of its own. Repeat it to select
multiple directory trees; overlapping selections are deduplicated. Use
cache scan PATH first for old caches that have not been registered.
All cache subcommands accept --json and use the existing CLI envelope and
exit codes (0 success/partial, 1 failure, 2 usage). Non-TTY stdout defaults to
JSON; human results go to stderr. Active caches are skipped (ok: null when
the remaining operation succeeds), and records for missing paths or unmarked
.cache directories containing only empty Jarvis-PLOT component directories
are pruned during cleanup. Only marked
Jarvis-PLOT components are removed; source data,
plots, and unrelated .cache content are retained. Failed deletions retain
their registry entries; nonempty unmarked directories remain invalid and are
not deleted. Scanning adopts legacy caches only when the four
pipeline directories and a compatible manifest.json identify them; old
unmarked twin-only directories need a new dryrun --with-data run to register.
An explicitly supplied --out-dir is an export directory and is not registered.
Concurrent registry writes use a lock and atomic replacement. Registration
failures warn without preventing rendering.
Example: Ternary Layouts
jplot ./Example/gambit_2x1.yaml
This layout reference uses bundled style cards and renders without external data.
Example: Dynesty Runplot
Jarvis-PLOT includes a reusable dynesty runplot format. With a dataset named
dynesty, the figure can use the built-in card without writing axes or layer
details:
DataSet:
- name: dynesty
path: path/to/dynesty_result.csv
type: csv
Figures:
- name: dynesty_logL_vs_logX
enable: true
style:
- a4paper_2x1
- dynesty_runplot
See DYNESTY_RUNPLOT.md for the default axes, KDE, scatter overlay, and evidence summary behavior.
Notes
- Figures are saved automatically to the output paths defined in the YAML configuration.
- Common output formats include PNG and PDF (backend-dependent).
- Saved figures include file metadata such as
Creator: Jarvis-PLOT, powered by Jarvis-HEPandJarvis-PLOT version: X.Y.Z; the PNGDescriptionalso includes both fields for macOS Finder compatibility. - Jarvis-PLOT works in headless environments (SSH, batch jobs) without any GUI backend.
Requirements
Python
- Python ≥ 3.10 (tested on 3.10–3.13)
Required Packages
numpypandaspolarsmatplotlibpyyamljsonschemascipy— numerical utilitiesh5py— required for loading HDF5 data filesshapelysympylogurudeepmergeruamel.yaml>=0.18— round-trip YAML editing forjplot config setrich— the fixed-column help and manual panelsJarvis-Operas>=1.1.4
Github Page
https://github.com/Pengxuan-Zhu-Phys/Jarvis-PLOT
Documentation
https://pengxuan-zhu-phys.github.io/Jarvis-Docs/
Project Docs
This repository keeps only README.md and CHANGELOG.md. Design documents,
specifications and the roadmap live in Jarvis-Books:
- Doc index
- JARVIS_PLOT_CONTEXT.md - project boundary; read before changing code
- CODE_MAP_JARVIS_PLOT.md - code owner map
- JARVIS_PLOT_FRAMEWORK_LOGIC.md - runtime execution contract
- IMPLEMENTATION_ROADMAP.md - open work
- RELEASING.md - versioning,
tools/check_release.pyand CI verification - STYLE_SCHEMA.md - style card contract, including the
Debugoverlay block - DEVELOPER_RULES.md - pipeline and cache rules
Read the context docs and roadmap before changing parsing, transforms, rendering, or layout-related behavior.
License
MIT License
Create a continuous forest figure with type: forest, a generic row table, optional points and multiple supplied intervals per row. Native YAML supports class-specific interval lanes, CSV value annotations, explicit x.ticks, opt-in MathText, header notes and a shared-format legend. The default Swiss-column card uses 82.5 mm width and 5.5 mm row pitch; every row shares one numerical x domain. See the forest contract, native examples, or jplot man forest --json.
AI agents: start with jplot man agent-readme --json for the official-package YAML workflow and missing-feature reporting instructions. Feature requests include the installed version from jplot --version; the CLI does not send email automatically.
Releasing
Maintainer release instructions are maintained in Jarvis-Books. The root CHANGELOG.md provides the public English release notes.
Metadata
Release files for JarvisPLOT 2.1.12
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| jarvisplot-2.1.12.tar.gz | 4.0 MB | Without provenance | Details for jarvisplot-2.1.12.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| jarvisplot-2.1.12-py3-none-any.whl | Python 3 | none | any | Details for jarvisplot-2.1.12-py3-none-any.whl |
Total release size: 7.9 MB
Release files / jarvisplot-2.1.12.tar.gz
| Download URL | jarvisplot-2.1.12.tar.gz |
|---|---|
| Size | 4.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
99612d9400b36d6e29c65423f8961a315f4a1c5ff6da53c80891503c16e82003
|
|
BLAKE2b-256 checksum How to use checksums |
2b1f95878ee64a23afa80c450ab99d0368f4074269467723f24386f505bf596e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.13
|
Release files / jarvisplot-2.1.12-py3-none-any.whl
| Download URL | jarvisplot-2.1.12-py3-none-any.whl |
|---|---|
| Size | 3.9 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
afc0dd9eedd0bfda720e550d2e97b0d62c4141496b1272c9abe8d79b85f8ef72
|
|
BLAKE2b-256 checksum How to use checksums |
4d723daf96e8c65809b8fb602020dc82117ec384809766a9490e98265a20ba3f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.13
|
Security for JarvisPLOT 2.1.12
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.