# BeautifulJASON

BeautifulJASON is a Python 3.10+ API for automating JEOL JASON workflows and
for reading or editing JASON `.jjh5` HDF5 documents. It supports batch
conversion, NMR/MS data access, document layout customization, report
generation, audit-trail export, and structured access to plugin data such as
SMILEQ.

Use this file as the starting point when answering questions about this
project. Prefer the local source and docs listed below over guessing.
If API details are unclear, do not guess. Use the official BeautifulJASON docs:
https://www.jeoljason.com/beautifuljason/docs/.

## Project Metadata

- Package: `beautifuljason`
- Current local version: `1.2.0b6`
- Python: `>=3.10`
- Build backend: `flit_core`
- Runtime dependencies: `h5py`, `numpy`, `colorama`, `pillow`
- Optional extras:
  - `beautifuljason[audit]` for HTML audit export via `lxml`
  - `beautifuljason[automation]` for filesystem monitoring via `watchdog`
- License: MIT

## Core Concepts

- `beautifuljason.JASON` launches the external JASON desktop application in
  headless mode to create, process, analyze, and save documents.
- `beautifuljason.Document` reads and modifies `.jjh5` files directly via
  `h5py`. It is the main entry point for data objects and visual graphics
  items stored inside a JASON document.
- A document has data objects such as NMR spectra, MS entries, molecules,
  images, text, and custom plugin data, plus graphics items that display or
  report those objects.
- Many read-only data extraction workflows can use `Document(..., mode="r")`
  without launching JASON. Workflows that import vendor data, apply processing
  rules, analyze spectra, or export PDFs/images usually require `JASON`.
- JASON itself is supported on Windows and macOS. Direct JJH5 access is mostly
  platform independent.

## Important Source Files

- `src/beautifuljason/__init__.py`: public package exports and version lookup.
- `src/beautifuljason/jason.py`: `JASON`, `Config`, process invocation,
  `create_document`, `apply_actions`, `save`, plugin and path handling.
- `src/beautifuljason/document.py`: `Document`, context management, data
  collections, graphics item collections, creation of tables/text/images/charts,
  document IDs, audit log paths.
- `src/beautifuljason/data.py`: data wrappers for NMR, MS, molecules, images,
  text, custom data, SMILEQ, unit conversion, peaks, multiplets, bins, DOSY.
- `src/beautifuljason/graphics.py`: graphics item wrappers for spectra, tables,
  reports, charts, text, image, molecule items, annotations, colors, fonts,
  columns, cuts, and linked IDs.
- `src/beautifuljason/audit.py`: audit log parser, hash validation, XML/HTML
  exporter.
- `src/beautifuljason/base.py`: shared HDF5 wrappers, list helpers, enums,
  `Font`, `Units`, alignment, file format constants.
- `src/beautifuljason/utils.py`: UUID validation, string decoding, nuclide
  formatting, HDF5 group list helpers.

## User-Facing Documentation

- Official docs for deeper reference:
  https://www.jeoljason.com/beautifuljason/docs/
- `README.rst`: project overview, installation, optional extras, compatibility,
  tests, examples, tools, changelog.
- `docs/index.rst`: Sphinx documentation index.
- `docs/source/beautifuljason.examples.rst`: quick-start and report-generation
  examples.
- `docs/source/beautifuljason.tools.rst`: command-line tools and examples.
- `docs/source/beautifuljason.*.rst`: generated API reference pages.
- `src/beautifuljason/resources/cookbook.md`: AI-focused task cookbook with common patterns and
  safe examples.

## Examples And Tools

- `src/beautifuljason/examples/quick_start.py`: creates a document from bundled
  test data, applies multiplet analysis, customizes a spectrum, exports PNG.
- `src/beautifuljason/examples/analyze_and_report.py`: batch report generation
  with analysis, layout changes, parameter tables, peak/multiplet tables,
  headers, logos, and multiplet reports.
- `jason_config`: manage JASON executable paths.
- `jason_batch_convert`: recursively convert files using extensions or patterns,
  optionally applying rules.
- `batch_extract_integrals`: extract parameters and multiplet integrals from
  `.jjh5` files to CSV.
- `jason_watchdog`: watch a folder and process new files with rules.

## Common API Patterns

Read existing JJH5 data:

```python
import beautifuljason as bjason

with bjason.Document("example.jjh5", mode="r") as doc:
    for spec in doc.nmr_data:
        print(spec.spec_info.nuclides)
```

Create a document through JASON and export it:

```python
import beautifuljason as bjason

jason = bjason.JASON()
with jason.create_document("example.jdf", rules="off") as doc:
    jason.save(doc, "example.pdf")
```

Apply analysis actions:

```python
actions = [{"name": "multiplet_analysis"}]
with jason.create_document("example.jdf", actions=actions) as doc:
    jason.save(doc, "analyzed.jjh5")
```

Prefer rules files (`.jjr`) for production processing and layout automation
when rules already exist. Use manual actions for simple scripted examples.

## Cautions For AI Assistants

- Do not assume JASON is installed or available. Creating documents from vendor
  files and exporting PDFs/images requires a configured external JASON binary.
- Use `Document(..., mode="r")` for extraction examples when mutation is not
  required.
- Use `bjason.utils.ensure_str(...)` when values may be HDF5 bytes.
- Do not invent JASON action names or table column IDs. Check source enums and
  examples first.
- `Document` context managers close files and remove temporary documents created
  by `JASON.create_document`.
- Direct HDF5 edits should preserve JASON's ID/link conventions. Prefer
  `Document.create_*` helpers over manual group construction.
- `NMRParamTableGraphicsItem` is a backward-compatible alias; prefer
  `ParamTableGraphicsItem`.
- Audit HTML export needs `lxml`; XML export does not.
- Avoid suggesting Linux for `JASON` automation. Direct `.jjh5` access can still
  be useful on Linux.