beautifuljason 1.1.1rc1
A Python Interface for JASON Software by JEOL
Requires Python: >=3.10

Project description
===================

.. contents:: Table of Contents
   :local:

BeautifulJASON
--------------

BeautifulJASON is a Python API designed to seamlessly interface with NMR data generated by the `JASON desktop application <https://www.jeoljason.com/>`_. Developed by JEOL, JASON represents one of the company's latest additions to its suite of NMR software, available for both Windows and macOS. JASON, an acronym for JEOL Analytical Software Network, showcases JEOL's ongoing dedication to advancing analytical solutions.

With its intuitive design, BeautifulJASON simplifies and enhances the user experience with JASON. It empowers users by automating a range of routine tasks, from loading and saving data to intricate spectral analysis and report generation.

Diving deeper, BeautifulJASON introduces a specialized suite of tools designed for the HDF5-based file format, JJH5. Under the hood, this format leverages the power of the `h5py` library, which is adept at handling NumPy data structures. However, BeautifulJASON abstracts away the complexities of the raw data structures provided by `h5py`. Instead, users interact with high-level, intuitive data structures tailored specifically for handling spectral data and molecular structures. This means that rather than wrestling with generic groups, attributes, and data cubes, users can seamlessly work with familiar and intuitive data structures tailored to their scientific needs. This design choice not only simplifies the user experience but also makes BeautifulJASON especially attractive for AI and ML tasks. Remarkably, these tools have the capability to function independently of the JASON application, even on platforms where JASON isn't available, offering users unparalleled flexibility and extended utility.

Given its comprehensive features and adaptability, BeautifulJASON emerges as an indispensable tool for researchers spanning the fields of chemistry, biochemistry, and materials science. It's particularly beneficial for professionals and enthusiasts navigating NMR data from a variety of vendor formats.

Installation
------------

You can install BeautifulJASON via `pip`. Depending on your setup and environment, you might use different commands:

#. **Using `pip`**:

   For most users, installing via `pip` is the standard method.

   .. code-block:: bash

      pip install beautifuljason

#. **Using `pip` for Python 3**:

   If you have both Python 2 and Python 3 installed, you might need to use `pip3` to ensure the package is installed for Python 3.

   .. code-block:: bash

      pip3 install beautifuljason

#. **Using Python's `-m` option**:

   In some environments, it's beneficial to use Python's `-m` switch.

   .. code-block:: bash

      python -m pip install beautifuljason

#. **Using Python 3's `-m` option**:

   If you want to ensure you're installing for Python 3, use the `-m` switch with `python3`.

   .. code-block:: bash

      python3 -m pip install beautifuljason

Operating System Compatibility
------------------------------

While this package is designed to be OS Independent, it's important to note that the JASON class relies on the JASON program, which is currently built and supported only for Windows and macOS. As a result, while most of the package functions will work on Linux, the JASON class will not.

Configuring the JASON Path
---------------------------

For most users who have installed JASON in a standard manner, there's no need for manual configuration and you can likely skip this section. `BeautifulJASON` will automatically attempt to locate JASON using common default paths.

However, in certain scenarios, such as when:

- JASON is installed in a non-standard location,
- Multiple instances of JASON exist and a specific one needs to be chosen,
- The path to JASON has changed after the installation of `BeautifulJASON`,

For detailed usage instructions, configuration steps, and examples, refer to the 
`jason_config documentation <https://www.jeoljason.com/beautifuljason/docs/source/beautifuljason.tools.html#jason-config>`_.

Running Unit Tests
------------------

To ensure the functionality and correctness of `BeautifulJASON` in your environment, the package comes bundled with a suite of unit tests. These tests provide a way to validate that everything is working as expected.

To run the unit tests, use the following command:

.. code-block:: bash

   python -m unittest discover beautifuljason.tests

This command will discover and run all the tests inside the `beautifuljason.tests` package. If all tests pass, it indicates that `BeautifulJASON` is functioning correctly in your environment. If any tests fail, please review the error messages for insights into potential issues.

For a more detailed output, you can run the tests in verbose mode:

.. code-block:: bash

   python -m unittest discover beautifuljason.tests -v

This will display a more detailed log of each test being run, along with its result.

Examples
--------

For usage examples, including a quick start and a batch report generation script, please visit the
`BeautifulJASON Examples Documentation <https://www.jeoljason.com/beautifuljason/docs/source/beautifuljason.examples.html>`_.

Command Line Tools
------------------

BeautifulJASON includes several command-line tools for batch conversion, configuration, and data extraction.

For full details, usage instructions, and examples, please visit the
`BeautifulJASON Tools Documentation <https://www.jeoljason.com/beautifuljason/docs/source/beautifuljason.tools.html>`_.

API Reference
-------------

For a comprehensive API reference, please refer to the `official BeautifulJASON documentation page <https://www.jeoljason.com/beautifuljason/docs>`_ on the JASON project website.

Support & Feedback
------------------

For support, questions, or to provide feedback on BeautifulJASON, please contact `JASON's support <https://www.jeoljason.com/support-and-faqs/>`_ on the JASON project website.

License
-------

BeautifulJASON is provided under the MIT License. For full license details, please refer to the `LICENSE` file included with this distribution or visit `MIT License on OSI <https://opensource.org/licenses/MIT>`_.

Changelog
---------

Version 1.1.1 (2025-10-03)
^^^^^^^^^^^^^^^^^^^^^^^^^^

* Extended the JASON class constructor with an `extra_args` parameter for fixed command-line arguments and improved plugin name handling.
* Added the `_run_background` method for server-like JASON execution.
* Added the `_wait_for_file` helper for automation scenarios in server-like mode.
* Enhanced docstrings and usage examples for the JASON class.
* Added tests for `_run` and `_run_background`.

Version 1.1.0 (2025-05-22)
^^^^^^^^^^^^^^^^^^^^^^^^^^

- Added `ChartGraphicsItem` to handle JASON charts.
- Enhanced `TableGraphicsItem` with support for titles and grid visibility (`title`, `show_title`, `show_grid`, `title_plain_text`).
- Extended `MoleculeGraphicsItem` with `mol_data_list`, `mol_data` and the `LabelType` enum.
- Introduced `Molecule.List` class for structured molecule data.
- Extended `Document` with new methods: `create_nmrassignments_table`, `mol_data`, `mol_items`, `items_by_type`, and `create_chart_item`.
- Added new CLI tool `batch_extract_integrals.py` for exporting integrals and spectral parameters to CSV.
- Enhanced CLI tool `jason_batch_convert.py` with `\--rules`, `\--patterns`, and `\--execute` options.
- Introduced CLI tool `jason_watchdog.py` for automated folder monitoring and processing.
- Expanded API Reference with usage examples and improved docstrings.
- Added multiple `.jjh5` files for testing and feature demonstration.

Version 1.0.4 (2024-10-03)
^^^^^^^^^^^^^^^^^^^^^^^^^^

- Implemented `area` and `area_sigma` properties in the `NMRPeak` class for accessing the values calculated by JASON.

Version 1.0.3 (2024-07-15)
^^^^^^^^^^^^^^^^^^^^^^^^^^

- Fixed issue where an unintended image item was added to the top-left corner of the first page by `analyze_and_report.py`.
- Addressed BeautifulJASON incompatibility with NumPy 2.0.0.
- Added a `__version__` attribute to BeautifulJASON package.

Version 1.0.2 (2024-04-01)
^^^^^^^^^^^^^^^^^^^^^^^^^^

- Enhanced the JASON class constructor with a `plugins` parameter to manage plugin loading. It defaults to `['off']`, signifying that plugins are not automatically loaded.
- Improved the `Config` class in the `jason.py` module by introducing a `find_path` method. The `add_path` method now returns the index of an existing path instead of triggering an exception. Furthermore, the `add_path_to_config` function in the `jason_config.py` module has been adapted to incorporate the `find_path` method.
- All instances of 'Jason' have been updated to 'JASON' across the application, aligning with case-sensitive naming standards and the name of the binary.

Version 1.0.1 (2023-11-17)
^^^^^^^^^^^^^^^^^^^^^^^^^^

- Added relative path support to the `jason_batch_convert` and `analyze_and_report` scripts for enhanced file path flexibility.

Version 1.0.0 (2023-10-26)
^^^^^^^^^^^^^^^^^^^^^^^^^^

- Initial release: Core `BeautifulJASON` framework for JEOL JASON interactions.