jarvisplot 2.1.11__tar.gz → 2.1.12__tar.gz

jarvisplot-2.1.12/CHANGELOG.md

@@ -0,0 +1,120 @@
+# Changelog
+
+Release history of the `JarvisPLOT` distribution (import package `jarvisplot`,
+CLI `jplot`). User guides and reference documentation are available in
+[Jarvis-Books `Docs/Jarvis-PLOT/`](https://github.com/Pengxuan-Zhu-Phys/Jarvis-Books/blob/main/Docs/Jarvis-PLOT/README.md).
+
+## 2.1.12 — 2026-10-19
+
+### Added
+
+- Automatically manage registered plot caches with a default 5 GiB total budget
+  and a 30-day idle limit. Configure `~/.jarvis/plot-cache.json` (under
+  `JARVIS_HOME` when set), `JP_CACHE_MAX_GIB` or `JP_CACHE_MAX_AGE_DAYS`.
+  `jplot cache list` reports the effective policy. Idle caches are reclaimed
+  toward 80% of the budget; active caches remain protected.
+- Show `-v` / `--version` without loading the plotting runtime. Structured
+  `--json` version output is also available through `Jarvis plot`.
+
+### Fixed
+
+- Draw `voronoif` and `triplot` layers. `voronoif` takes `x`, `y` and an
+  optional `where` mask for the selected region's hatched boundary; it has no
+  `z` or colorbar. `triplot` works on rectangular and ternary axes.
+- Evaluate built-in mathematical functions, including hyperbolic and inverse
+  trigonometric functions, `Gauss`, `Normal` and `Heaviside`, on whole columns.
+  Preserve the `Heaviside(x, H0=...)` keyword. Define `Pi`, `pi`, `E` and `Inf`,
+  and publish them through `jplot cap funcs`.
+- Avoid false missing-column errors for built-in functions, keyword argument
+  labels, YAML `Functions`, Operas namespaces and columns produced by
+  `significance` transforms.
+- Accept `voronoi` and `adaptive` in `make_density_core`, and recognize the
+  existing `profile_2d` reduction and grid options during YAML checks.
+- Restore usable full-width `[a4paper_1x1, Ternary]` and
+  `[gambit_1x1, Ternary]` cards. See the
+  [runnable example](https://github.com/Pengxuan-Zhu-Phys/Jarvis-PLOT/blob/main/Example/ternary_1x1.yaml).
+- Print mappings containing quoted YAML strings with `jplot config get`.
+- Keep `dynesty_runplot` y labels inside the page and the GAMBIT `rectcmap`
+  colorbar label clear of its tick numbers.
+- Protect caches used by concurrent plotting sessions. `--print` defers
+  cleanup until readers finish, and rebuilding a busy cache reports an error
+  without deleting it. Atomic writes prevent incomplete payloads and lost
+  registry updates; interrupted temporary files are reclaimed when idle.
+  Cache use reports an error if reliable locking is unavailable.
+- Report missing layer axes or data before rendering. A layer without a method
+  reports a warning and continues to use `scatter`.
+
+### Compatibility and upgrade notes
+
+- Use `jplot doctor <file>` in place of the removed `jplot validate <file>`
+  command. Automatic `--fix` / `--fix-unsafe` YAML rewriting has been removed.
+  `doctor` performs internal YAML checks and a light dryrun; configuration
+  editing and suggestions also retain their internal checks.
+- Remove boolean `frame.axlogo` entries from YAML. The field accepts a settings
+  mapping only, including for forest figures. Use `jplot <file> --print` for
+  final output without the badge.
+- Lists in `frame` now replace the style card's lists in full. Review text,
+  tick and other list overrides; include every entry you want to keep. This
+  also fixes four-element axes rectangles being appended to the card's rectangle.
+- `Min` / `Max` and their lowercase aliases are elementwise with multiple
+  arguments; a single column argument reduces the whole column to one value.
+  Lowercase `e` is a column name, not a built-in constant; use `E` for Euler's number.
+- Text and JSON version reports display `Jarvis-PLOT`. The PyPI distribution
+  name remains `JarvisPLOT`, and the import package remains `jarvisplot`.
+
+### Documentation
+
+- Include the public YAML examples and their supplied CSV data in the source
+  distribution, including the repaired full-width ternary example.
+
+## 2.1.11 — 2026-10-18
+
+### Added
+
+- Manage plot fonts with `jplot fonts show|list|resolve|check|set|reset` and
+  `jplot man fonts`. The default font card uses Helvetica sans, STIXGeneral serif
+  and STIX MathText. Explicit YAML fonts and sizes take precedence.
+- Save personal font overrides in `~/.jarvis/plot-fonts.json`; `JARVIS_HOME`
+  changes the configuration directory.
+- When Helvetica is unavailable, use the first installed font among Arial,
+  Liberation Sans, Nimbus Sans and DejaVu Sans. `check` and `resolve` report the
+  selected font and the reason for substitution.
+
+### Fixed
+
+- Remove empty registered cache directories whose marker is missing while
+  preserving unmarked directories that contain files.
+
+### Changed
+
+- Use the font card's MathText font for cut descriptions by default.
+- Find the plotting guides and reference documentation in
+  [Jarvis-Books](https://github.com/Pengxuan-Zhu-Phys/Jarvis-Books/blob/main/Docs/Jarvis-PLOT/README.md).
+  Public examples remain available in `Example/`.
+
+## 2.1.10 — 2026-10-13
+
+- Native forest figures read multi-interval CSV sources and mappings,
+  intervals-only rows, box/scatter coexistence and literal CSV value
+  annotations. Values are plotted as supplied, never computed.
+- Explicit shared x ticks, independent of grid divisions.
+- MathText needs `math: true`; formula fonts are STIX by default with DejaVu
+  Sans as an alternative, selected separately for legends and cut
+  descriptions. Header notes, paragraphs and formulas are preserved, and
+  layout uses the actual font, glyph and annotation bounds.
+- TTC faces keep their weight and slant; an explicit font size governs
+  measurement.
+- Show consistent versions in the CLI, manuals, render reports and image
+  metadata. SVG output includes Dublin Core metadata. Export reports drawing
+  and I/O failures and retries only when a backend rejects metadata support.
+- Packaged AI README (`jplot man agent-readme --json`), schema, manual and
+  example updates.
+- Include native forest examples in the source distribution.
+
+Existing forest YAML needs no migration. Custom export metadata must use keys
+the selected backend supports; invalid SVG keys are now reported.
+
+## Earlier releases
+
+See the [PyPI release history](https://pypi.org/project/JarvisPLOT/#history)
+and [GitHub Releases](https://github.com/Pengxuan-Zhu-Phys/Jarvis-PLOT/releases).

jarvisplot-2.1.12/Example/README.md

@@ -0,0 +1,102 @@
+# Jarvis-PLOT — design-reference debug examples
+
+One example per style card. The layout-reference figures set `debug: true`, which draws the
+**design-reference overlay**: every axis is outlined, while all axes'
+`rect = [left, bottom, width, height]` (figure fractions) and width/height in
+centimetres are listed sequentially in one panel inside the primary `ax`.
+The figure size and margin / colorbar-gap dimension lines remain on the outer
+overlay.
+
+Most figures have **no data layers** on purpose — they are pure layout references
+for each style card. `corrplot_matrix.yaml` is the exception: a correlation
+matrix has nothing to show without data, and its card solves the figure size
+*from* the data rather than fixing it.
+
+## Run
+
+```bash
+jplot Example/a4paper_2x1.yaml
+```
+
+(`plots/` and `.cache/` are created on the fly and are git-ignored.)
+
+## Styles covered
+
+Examples are grouped by geometry family and paper ratio:
+
+| YAML | Style `[family, variant]` |
+|------|---------------------------|
+| `ternary_1x1.yaml` | Full-width `[a4paper_1x1, Ternary]` and `[gambit_1x1, Ternary]` |
+| `a4paper_2x1.yaml` | All `a4paper_2x1` cards: `rect`, `rectRatio`, `rectMarginal`, `rectcmap`, `Ternary`, `TernaryCmap`, `rect_5x1`, `dynesty_runplot` |
+| `a4paper_4x1_rectcmap.yaml` | `[a4paper_4x1, rectcmap]` |
+| `gambit_2x1.yaml` | All `gambit_2x1` cards: `rectcmap`, `Ternary`, `TernaryCmap` |
+| `corrplot_matrix.yaml` | `[corrplot, matrix]` via `type: correlation_matrix` — a real correlation matrix, not a layout reference |
+| `corrplot_scales.yaml` | The same card at n = 6 … 100, one glyph method each — where the derivation stops working |
+| `generated_data.yaml` | `[a4paper_2x1, rect]` — named `DataSet.type: generated`, a private generated curve, transforms, and `combine: separate` |
+| `pdf_cdf_1d.yaml` | `[a4paper_2x1, rect]` — raw weighted samples, `PDF1D` repeat mean/std band, and pure `CDF1D` |
+| `compact_legend.yaml` | `[a4paper_2x1, rect]` — layer-declared compact legend objects with band/line overlays and stacked boundary/mean keys |
+| `legend_cards.yaml` | `[a4paper_2x1, rect]` — forward layer membership, object sorting, JSON card selection and a native line/errorbar composite |
+
+These are every style registered in `jarvisplot/cards/style_preference.json`.
+
+## The `corrplot` family is different
+
+`[corrplot, matrix]` is the only card whose **figure size is derived, not
+declared**. It carries a `Geometry` block in millimetres — cell size, padding,
+colorbar width, a 170 mm cap — and the figure size falls out of the matrix:
+`n` variables and the measured width of their names. Cell size and font size
+stay fixed as `n` grows; the figure grows instead, and only past the cap does
+the cell shrink (never the font).
+
+That is why the card has no `figsize` and no axes `rect`, why its panel and
+colorbar are called `axcorr` / `axccorr` rather than `ax` / `axc`, and why
+`jplot cap styles` reports it as `geometry: solved, requires_type:
+correlation_matrix`. Naming it in `style:` alone is an error, not a fallback.
+
+`corrplot_matrix.yaml` therefore states no `figsize`, no axes `rect`, no tick
+positions and no coordinates: `prebuild_correlations` measures the variable
+names and writes all of it into the config before the figure is built. Add a
+variable to the CSV and the figure grows — the cells and the type do not move.
+
+It is also the one example written as a **`type:` macro** rather than as
+layers, because the four reserved names here (`axcorr`, `axccorr`,
+`method: corrplot`, `[corrplot, matrix]`) are not choices — they are one thing
+spelled four times. `jplot config expand Example/corrplot_matrix.yaml --figure
+corrplot_matrix` shows the single layer it lowers to.
+
+Under it is **`method: corrplot`**, a drawing primitive of its own rather than a
+`scatter` layer with a computed marker size. That distinction is what makes
+`method: circle | square | ellipse | color | shade | pie | number` mean
+anything: only `circle` is expressible as a scatter marker. The `corrplot:`
+block takes R's own formals, spelled as R spells them.
+
+The one split worth knowing is where each formal is applied. `order`,
+`addrect`, `hclust.method`, `tl.pos` and `col` decide **which variable sits
+where** (or what the whole scale is), and the tick labels are written at config
+time — so those are resolved by `prebuild_correlations`, which writes the
+resolved order into the transform's `columns`. Everything else describes **one
+cell** and is applied at draw time. Nothing reorders a matrix after its labels
+exist. `jplot man type-correlation-matrix` and
+[CORRELATION_MATRIX.md](https://github.com/Pengxuan-Zhu-Phys/Jarvis-Books/blob/main/Docs/Jarvis-PLOT/specs/CORRELATION_MATRIX.md) carry the full crosswalk.
+
+### Where it stops working
+
+`corrplot_scales.yaml` is the experiment behind the claim above: one 100-column
+table, one card, seven values of `n`, a different glyph method each time. Up to
+`n = 33` the cell stays 4.20 mm and the figure grows to fill 170 mm. From
+`n = 40` the width is pinned and the **cell** shrinks — never the font, which
+is what lets two of these sit in one paper. At `n = 100` even the 1.60 mm cell
+floor does not fit: the solver keeps the floor, overruns the page by 13.8 mm,
+and says so. The two `corrplot_100_*` figures are included precisely because
+they are past the limit — the labelled one has 100 names colliding in 160 mm,
+which is what "past the limit" looks like.
+
+## Notes
+
+- Variant tokens are case-sensitive: `rect`, `rectcmap` (lower-case) and
+  `Ternary`, `TernaryCmap` (capitalized).
+- To turn the overlay off, set `debug: false` (or remove it).
+- To see the overlay on a real plot, add normal `layers` to any of these files.
+
+See the docs: **Jarvis-PLOT → Style Cards and Layout** for a full explanation of
+the card JSON structure and the overlay.

jarvisplot-2.1.12/Example/a4paper_2x1.yaml

@@ -0,0 +1,73 @@
+# Design-reference debug examples for all a4paper_2x1 style cards.
+#
+#   Run:    jplot Example/a4paper_2x1.yaml
+#
+# Each figure is a pure layout reference with debug overlay enabled.
+
+version: '0.3'
+project:
+  name: a4paper_2x1
+Functions: []
+DataSet: []
+Figures:
+  - name: a4paper_2x1_Ternary
+    debug: true                      # draw the design-reference dimension overlay
+    style: [a4paper_2x1, Ternary]
+    frame:
+      axtri: {labels: {left: "A", bottom: "B", right: "C"}}
+    layers: []                       # empty -- layout reference only
+
+  - name: a4paper_2x1_TernaryCmap
+    debug: true                      # draw the design-reference dimension overlay
+    style: [a4paper_2x1, TernaryCmap]
+    frame:
+      axtri: {labels: {left: "A", bottom: "B", right: "C"}}
+      axc: {label: {ylabel: "$z$"}}
+    layers: []                       # empty -- layout reference only
+
+  - name: a4paper_2x1_dynesty_runplot
+    debug: true                      # draw the design-reference dimension overlay
+    style: [a4paper_2x1, dynesty_runplot]
+    layers: []                       # empty -- layout reference only
+
+  - name: a4paper_2x1_rect
+    debug: true                      # draw the design-reference dimension overlay
+    style: [a4paper_2x1, rect]
+    frame:
+      ax: {labels: {x: "$x$", y: "$y$"}}
+    layers: []                       # empty -- layout reference only
+  - name: a4paper_2x1_rectRatio
+    debug: true                      # draw the design-reference dimension overlay
+    style: [a4paper_2x1, rectRatio]
+    layers: []                       # empty -- layout reference only
+
+  - name: a4paper_2x1_rectMarginal
+    debug: true                      # draw the design-reference dimension overlay
+    style: [a4paper_2x1, rectMarginal]
+    frame:
+      axl: {labels: {y: "$y$"}}      # the strips carry the shared axis' labels
+      axb: {labels: {x: "$x$"}}
+      axc: {label: {ylabel: "$z$"}}
+    layers: []                       # empty -- layout reference only
+
+
+
+  - name: a4paper_2x1_rect_5x1
+    debug: true                      # draw the design-reference dimension overlay
+    style: [a4paper_2x1, rect_5x1]
+    layers: []                       # empty -- layout reference only
+
+  - name: a4paper_2x1_rectcmap
+    debug: true                      # draw the design-reference dimension overlay
+    style: [a4paper_2x1, rectcmap]
+    frame:
+      ax: {labels: {x: "$x$", y: "$y$"}}
+      axc: {label: {ylabel: "$z$"}}
+    layers: []                       # empty -- layout reference only
+
+output:
+  dir: ./plots
+  dpi: 150
+  formats:
+    - png
+    - pdf

jarvisplot-2.1.12/Example/a4paper_4x1_rectcmap.yaml

@@ -0,0 +1,30 @@
+# Design-reference debug example  --  style [a4paper_4x1, rectcmap]
+#
+#   Run:    jplot Example/a4paper_4x1_rectcmap.yaml
+#   Shows:  the axes layout of this style card -- every axis box with its
+#           rect [left, bottom, width, height] and width/height in cm, the
+#           figure size, margins and colorbar gap -- drawn by `debug: true`.
+#
+# The figure has no data layers on purpose: this is a pure layout reference.
+
+version: "0.3"
+
+project:
+  name: design_a4paper_4x1_rectcmap
+
+Functions: []
+DataSet: []
+
+Figures:
+  - name: a4paper_4x1_rectcmap
+    debug: true                      # draw the design-reference dimension overlay
+    style: [a4paper_4x1, rectcmap]
+    frame:
+      ax: {labels: {x: "$x$", y: "$y$"}}
+      axc: {label: {ylabel: "$z$"}}
+    layers: []                       # empty -- layout reference only
+
+output:
+  dir: ./plots
+  dpi: 150
+  formats: [png]

jarvisplot-2.1.12/Example/compact_legend.yaml

@@ -0,0 +1,237 @@
+DataSet: []
+Figures:
+- name: compact_legend
+  style:
+  - a4paper_2x1
+  - rect
+  frame:
+    ax:
+      xlim:
+      - 0
+      - 1
+      ylim:
+      - 0
+      - 7
+      labels:
+        x: Score
+        y: Density
+      legend:
+        loc: upper left
+        ncols: 2
+        prop:
+          family: STIXGeneral
+          size: 4.6
+        card: compact
+        order:
+        - signal_train
+        - signal_test
+        - background_train
+        - background_test
+  layers:
+  - name: signal_train_band
+    axes: ax
+    method: fill_between
+    coordinates:
+      x: &id001
+      - 0
+      - 0.15
+      - 0.3
+      - 0.45
+      - 0.6
+      - 0.75
+      - 1
+      y1: &id003
+      - 0.0
+      - 0.16000000000000003
+      - 1.6
+      - 3.2
+      - 1.6
+      - 0.4
+      - 0.0
+      y2: &id002
+      - 0.0
+      - 0.24
+      - 2.4
+      - 4.8
+      - 2.4
+      - 0.6
+      - 0.0
+    style:
+      color: '#56B4E9'
+      alpha: 0.3
+      linewidth: 0
+    legend:
+      object: signal_train
+      label: Signal train
+      role: band
+  - name: signal_train
+    axes: ax
+    method: plot
+    coordinates:
+      x: *id001
+      y:
+      - 0
+      - 0.2
+      - 2
+      - 4
+      - 2
+      - 0.5
+      - 0
+    style:
+      color: '#56B4E9'
+      linewidth: 0.7
+    legend:
+      object: signal_train
+      label: Signal train
+      role: line
+  - name: signal_test_high
+    axes: ax
+    method: plot
+    coordinates:
+      x: *id001
+      y: *id002
+    style:
+      color: '#005A8D'
+      alpha: 0.3
+      linewidth: 0.4
+    legend:
+      object: signal_test
+      label: Signal test
+      role: upper
+  - name: signal_test_low
+    axes: ax
+    method: plot
+    coordinates:
+      x: *id001
+      y: *id003
+    style:
+      color: '#005A8D'
+      alpha: 0.3
+      linewidth: 0.4
+    legend:
+      object: signal_test
+      label: Signal test
+      role: lower
+  - name: signal_test
+    axes: ax
+    method: plot
+    coordinates:
+      x: *id001
+      y:
+      - 0.0
+      - 0.20600000000000002
+      - 2.06
+      - 4.12
+      - 2.06
+      - 0.515
+      - 0.0
+    style:
+      color: '#005A8D'
+      linewidth: 0.7
+    legend:
+      object: signal_test
+      label: Signal test
+      role: line
+  - name: background_train_band
+    axes: ax
+    method: fill_between
+    coordinates:
+      x: *id001
+      y1: &id005
+      - 0.0
+      - 0.8
+      - 3.2
+      - 1.6
+      - 0.4
+      - 0.08000000000000002
+      - 0.0
+      y2: &id004
+      - 0.0
+      - 1.2
+      - 4.8
+      - 2.4
+      - 0.6
+      - 0.12
+      - 0.0
+    style:
+      color: '#E69F00'
+      alpha: 0.3
+      linewidth: 0
+    legend:
+      object: background_train
+      label: Background train
+      role: band
+  - name: background_train
+    axes: ax
+    method: plot
+    coordinates:
+      x: *id001
+      y:
+      - 0
+      - 1
+      - 4
+      - 2
+      - 0.5
+      - 0.1
+      - 0
+    style:
+      color: '#E69F00'
+      linewidth: 0.7
+    legend:
+      object: background_train
+      label: Background train
+      role: line
+  - name: background_test_high
+    axes: ax
+    method: plot
+    coordinates:
+      x: *id001
+      y: *id004
+    style:
+      color: '#A23E00'
+      alpha: 0.3
+      linewidth: 0.4
+    legend:
+      object: background_test
+      label: Background test
+      role: upper
+  - name: background_test_low
+    axes: ax
+    method: plot
+    coordinates:
+      x: *id001
+      y: *id005
+    style:
+      color: '#A23E00'
+      alpha: 0.3
+      linewidth: 0.4
+    legend:
+      object: background_test
+      label: Background test
+      role: lower
+  - name: background_test
+    axes: ax
+    method: plot
+    coordinates:
+      x: *id001
+      y:
+      - 0.0
+      - 1.03
+      - 4.12
+      - 2.06
+      - 0.515
+      - 0.10300000000000001
+      - 0.0
+    style:
+      color: '#A23E00'
+      linewidth: 0.7
+    legend:
+      object: background_test
+      label: Background test
+      role: line
+output:
+  dir: ./plots
+  formats:
+  - png
+  - pdf
+  dpi: 300