Metadata-Version: 2.4
Name: molcrafts-molplot
Version: 0.1.2
Summary: Unified scientific charting: scienceplots + a matplotlib-portable Vega-Lite preset
Project-URL: Homepage, https://github.com/MolCrafts/molplot
Project-URL: Repository, https://github.com/MolCrafts/molplot
Author: MolCrafts Team
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: charting,matplotlib,science,scienceplots,vega-lite,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.6
Requires-Dist: numpy
Requires-Dist: scienceplots>=2.1
Provides-Extra: convert
Requires-Dist: vl-convert-python>=1.6; extra == 'convert'
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: hatchling; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: pyyaml>=6.0; extra == 'dev'
Provides-Extra: mdx
Requires-Dist: pyyaml>=6.0; extra == 'mdx'
Description-Content-Type: text/markdown

# molcrafts-molplot

Unified scientific charting for the MolCrafts stack — the **Python / matplotlib**
half of [MolPlot](https://github.com/MolCrafts/molplot).

It wraps [scienceplots](https://github.com/garrettj403/SciencePlots) and injects
MolPlot's **unified preset** (palette, type scale, grid, light/dark) so a figure
made here matches the same preset rendered in the browser by the TypeScript
package `@molcrafts/molplot`.

The bridge between the two renderers is the **Vega-Lite spec** — a portable JSON
intermediate language. Build a spec in Python and either ship it to the web or
render it to matplotlib for a publication figure.

## Install

```sh
pip install molcrafts-molplot
# optional exact web-parity export (real Vega engine → PNG/SVG):
pip install "molcrafts-molplot[convert]"
```

## Style — scienceplots + unified preset

```python
import matplotlib.pyplot as plt
import molplot

molplot.use("molplot")            # scienceplots base + MolPlot overlay
# or a publication variant (serif, high-DPI, scienceplots 'nature' base):
molplot.use("molplot-paper")

with molplot.style("molplot", mode="dark"):
    plt.plot(x, y)                # scoped; restores rcParams on exit

molplot.palette()[0]              # '#0c5da5' — same categorical colours as the web
```

`plt.style.use("molplot")` also works directly (the `.mplstyle` files are
registered on import) — but `molplot.use()` additionally layers the scienceplots
base styles named by the preset.

## Charts — one call, or via the portable spec

```python
# one call → (fig, ax)
fig, ax = molplot.line(
    [{"id": "E_total", "x": steps, "y": e_total},
     {"id": "E_kin",   "x": steps, "y": e_kin}],
    x_label="step", y_label="energy (kcal/mol)", show_legend=True,
)

# or build the Vega-Lite spec and choose a renderer:
spec = molplot.scatter_spec(pc1, pc2, color=cluster_id, colorscale="viridis")
fig, ax = molplot.render(spec)     # matplotlib (scienceplots)
molplot.to_png(spec, "fig.png")    # exact web parity via vl-convert (optional)
import json; json.dumps(spec)      # ship the same spec to the browser
```

`line_spec` / `scatter_spec` / `bar_spec` / `gantt_spec` emit the same Vega-Lite
shapes as the TypeScript `@molcrafts/molplot` builders.

## License

BSD-3-Clause
