Metadata-Version: 2.4
Name: JarvisPLOT
Version: 2.1.9
Summary: Jarvis-PLOT: YAML-driven plotting engine
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: loguru
Requires-Dist: pyyaml
Requires-Dist: ruamel.yaml>=0.18
Requires-Dist: jsonschema
Requires-Dist: Jarvis-Operas>=1.1.4
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: polars
Requires-Dist: matplotlib
Requires-Dist: h5py
Requires-Dist: sympy
Requires-Dist: scipy
Requires-Dist: shapely
Requires-Dist: deepmerge
Requires-Dist: rich

# 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 release: **2.0.6** (`jplot -v` reports the installed version).

---

## Installation

```bash
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:

```python
import jarvisplot
```

```bash
jplot path/to/config.yaml
```

If you have an older environment that still uses a historical package name, replace:

```bash
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`:

```bash
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:

```bash
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:

```bash
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:

```bash
jplot validate plot.yaml            # schema + contracts, no data touched
jplot dryrun plot.yaml              # load data + transforms, row ledger, JP-VIZ health
jplot doctor plot.yaml              # validate + dryrun in one pass
```

Every one of these takes `--json`.

### 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.

```yaml
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 `docs/specs/STYLE_SCHEMA.md`.

> `Figures[].debug` is not the `jplot --debug` flag — 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:

```json
{"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:

1. `jplot data describe <file> --json` — column names from the real file. Never
   invent one; a wrong name is a hard error, not a warning.
2. `jplot cap methods|styles|cmaps|funcs|transforms|types --json` — the legal
   strings, read live from the registries rather than from documentation.
3. Edit the YAML in an editor (or `jplot config set … --write`). Reach for a
   `type:` macro first, drop to explicit `layers` when the macro cannot say it.
4. `jplot doctor <file> --json` — validate + dryrun in one pass. Diagnostics
   carry `JP-*` codes; `jplot explain JP-XXX-NNN` expands any of them.
5. `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](docs/specs/LEGEND.md) and the
[self-contained example](Example/compact_legend.yaml).

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](docs/specs/PDF_CDF_1D.md) and the
[runnable example](Example/pdf_cdf_1d.yaml).
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 validate` checks shape and contracts and never touches the data;
  `jplot dryrun` loads the data and reports the row ledger and JP-VIZ render
  health. Passing the first says nothing about the second.
- `docs/specs/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):

```bash
jplot flowchart path/to/scene.json
# optional output path:
jplot flowchart path/to/scene.json -o path/to/out.png
```

Library form:

```python
from jarvisplot import render_flowchart, render_flowchart_file
```

### Project Workdir and Cache

- You can set `project.workdir` in YAML.
- If `output.dir` is omitted, Jarvis-PLOT defaults to `<workdir>/plots/`.
- Data cache is stored in `<workdir>/.cache/`.
- `--print` accepts the current settings and renders final figures without the logo. It announces that, after all enabled figures are saved successfully, cache payloads used or created by this run will be deleted (pipeline data and metadata, named/shared data, summaries, and HDF5 materialization slots). Rendering failures or a run with no enabled figures keep the cache. Unrelated cache entries and the lightweight fingerprint manifest are retained; later renders rebuild deleted entries as needed.
- 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` + render `bin`) 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.

```bash
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
```

`--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 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. 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: SUSYRun2 Ternary Plots

```bash
jplot ./bin/SUSYRun2_EWMSSM.yaml
jplot ./bin/SUSYRun2_GEWMSSM.yaml
```

> **Note:** The data file paths inside the YAML files must be updated to match your local setup.

### 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:

```yaml
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 `docs/specs/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-HEP` and `Jarvis-PLOT version: X.Y.Z`; the PNG `Description` also 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
- `numpy`
- `pandas`
- `polars`
- `matplotlib`
- `pyyaml`
- `jsonschema`
- `scipy` — numerical utilities
- `h5py` — required for loading HDF5 data files
- `shapely`
- `sympy`
- `loguru`
- `deepmerge`
- `ruamel.yaml>=0.18` — round-trip YAML editing for `jplot config set`
- `rich` — the fixed-column help and manual panels
- `Jarvis-Operas>=1.1.4`

### Github Page
[https://github.com/Pengxuan-Zhu-Phys/Jarvis-PLOT](https://github.com/Pengxuan-Zhu-Phys/Jarvis-PLOT)

### Documentation
[https://pengxuan-zhu-phys.github.io/Jarvis-Docs/](https://pengxuan-zhu-phys.github.io/Jarvis-Docs/)

### Repository Docs

Tracked project docs live in `docs/`.

- `docs/README.md` - repo doc index
- `docs/context/JARVIS_PLOT_CONTEXT.md` - primary Codex-facing boundary doc
- `docs/context/CODE_MAP_JARVIS_PLOT.md` - concrete code owner map
- `docs/context/JARVIS_PLOT_FRAMEWORK_LOGIC.md` - runtime execution contract
- `docs/roadmap/IMPLEMENTATION_ROADMAP.md` - active backlog and future work list
- `docs/specs/AGENT_DATA_API.md` - planned numeric agent bridge (spec only, frozen — not the shipped CLI agent surface above)
- `docs/specs/STYLE_SCHEMA.md` - style card contract, including the `Debug` overlay block
- `docs/dev/DEVELOPER_RULES.md` - current pipeline and cache rules
- `docs/dev/MEMORY_OPTIMIZATION_GUIDE.md` - narrow-table memory notes

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 and optional point table. 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](docs/specs/FOREST.md), [native examples](Example/forest/README.md), or `jplot man forest --json`.
