Skip to main content

A Python Interface for JASON Software by JEOL

Project description

BeautifulJASON

BeautifulJASON is a Python API designed to seamlessly interface with NMR data generated by the JASON desktop application. 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:

  1. Using `pip`:

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

    pip install beautifuljason
  2. 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.

    pip3 install beautifuljason
  3. Using Python’s `-m` option:

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

    python -m pip install beautifuljason
  4. Using Python 3’s `-m` option:

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

    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,

You may need to specify or update the path to the JASON application.

The BeautifulJASON package is equipped with a tool, jason_config, to assist with this:

  1. Display the Current Configuration:

    To view the current path settings for the JASON application:

    jason_config --display
  2. Add a New JASON Path:

    If the JASON application resides in a different location than the detected default paths:

    jason_config --add_path /path/to/your/jason/application

    Be sure to replace /path/to/your/jason/application with the actual path to your JASON executable.

  3. For Additional Commands and Options:

    If you need more details about available commands or want to explore other options:

    jason_config --help

Always ensure that the specified path points directly to the JASON executable for BeautifulJASON to function correctly.

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:

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:

python -m unittest discover beautifuljason.tests -v

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

Quick Start

For those who prefer diving right into code, a fully runnable example is provided in the BeautifulJASON library. You can find the script in the ‘examples’ subpackage under the name quick_start.py.

The example demonstrates:

  • Loading a 1H spectral file.

  • Applying multiplet analysis on it.

  • Customizing the appearance of the spectral data.

  • Saving the processed results as an image.

  • Finally, viewing the generated image using Python.

Here’s a look at what the quick_start.py script contains:

import os
import tempfile
import beautifuljason as bjason
from PIL import Image as PILImage

# Determine the path to the data directory inside the beautifuljason's tests subpackage
test_data_dir = os.path.join(os.path.dirname(bjason.__file__), 'tests', 'data')

# Specify input spectral file and define the path for the output PNG file
input_1H_file = os.path.join(test_data_dir, "Ethylindanone_Proton-13-1.jdf")
output_file = os.path.join(tempfile.gettempdir(), "Ethylindanone_Proton-13-1.png")

# Create an instance of the JASON application interface
jason = bjason.JASON()

# Define and customize the default font settings
font = bjason.base.Font.default_font()
font['family'] = 'Arial'
font['point_size'] = 12

# Load the 1H spectral file, apply multiplet analysis, and customize its visual appearance
with jason.create_document(input_1H_file, actions=[{'name': 'multiplet_analysis'}]) as doc:
   # Access the first spectral item and adjust its properties
   spec_item = doc.nmr_items[0]
   spec_item.header = 'Ethylindanone'
   spec_item.header_font = font
   spec_item.x_font = font
   spec_item.mult_intg_label_font = font
   spec_item.peak_label_font = font
   spec_item.plot_1d_color = '#3556d8'
   spec_item.show_y_axis = False

   # Save the customized document to an image file
   jason.save(doc, output_file)

# Display the generated image using the default image viewer
image = PILImage.open(output_file)
image.show()

JASON Analyze and Report Script

Overview

The analyze_and_report.py script showcases the capabilities of BeautifulJASON by automating various tasks related to NMR data analysis and reporting. This script is designed to:

  • Load multiple spectra files.

  • Perform automatic analysis of spectra (e.g., multiplet analysis for 1H, peak picking for other types).

  • Generate tables of peaks, parameters, and multiplet reports.

  • Adjust the layout and graphical properties of spectral items.

  • Save the combined results of the input spectra in a specified format, including .jjh5, .jjj, .jdx, and .pdf.

While this script serves as an example, it can also be used as a starting point for creating custom scripts tailored to specific needs.

Usage

Execute the script by running:

python -m beautifuljason.examples.analyze_and_report [input_files] -output_files [output_file]

Where: - input_files: One or more spectra files you wish to analyze and report on. - output_file: The file where the combined results of the input spectra will be saved. Supported formats include .jjh5, .jjj, .jdx, and .pdf.

For example, to analyze and report on proton.jdf, carbon.jdf, and hsqc.jdf, and save the combined results in combined_results.jjh5, you would execute:

python -m beautifuljason.examples.analyze_and_report proton.jdf carbon.jdf hsqc.jdf -output_files result.jjh5

Notes

  • The script is designed to handle multiple file inputs and outputs them as a combined result, making it ideal for batch processing.

  • At the end of the operation, if a .jjh5 file is the output, the script can optionally launch JASON for visual inspection of the results.

  • This script serves as a showcase of BeautifulJASON’s capabilities. It can be modified or used as a foundation for more complex workflows.

JASON Batch Convert Tool

Overview

The jason_batch_convert tool provides a convenient way to batch convert files that are openable by JASON into various formats. This utility is especially useful for converting large datasets or for automating repetitive conversion tasks.

Usage

To use the jason_batch_convert tool, navigate to the directory containing the tool and run:

jason_batch_convert [input_directory] [output_directory] -formats [desired_formats] -extensions [file_extensions]
  • input_directory: The directory containing the files you wish to convert.

  • output_directory: The directory where the converted files will be saved.

  • desired_formats: The formats you wish to convert the files to. Available choices are: jjh5, jjj, jdx, jdf, pdf, png, jpg, svg.

  • file_extensions: The extension of the files you wish to convert (e.g., jdf, jdx, 1).

For example, to convert all .jdf files in the data directory to jjh5 and pdf, you would run:

jason_batch_convert data converted -formats jjh5 pdf -extensions jdf

Notes

  • The tool is designed to handle file-based formats.

  • Folder-based formats are not supported in this version.

API Reference

For a comprehensive API reference, please refer to the official BeautifulJASON documentation page on the JASON project website.

Support & Feedback

For support, questions, or to provide feedback on BeautifulJASON, please contact JASON’s support 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.

Changelog

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

beautifuljason-1.0.4.tar.gz (53.8 MB view details)

Uploaded Source

Built Distribution

beautifuljason-1.0.4-py3-none-any.whl (53.8 MB view details)

Uploaded Python 3

File details

Details for the file beautifuljason-1.0.4.tar.gz.

File metadata

  • Download URL: beautifuljason-1.0.4.tar.gz
  • Upload date:
  • Size: 53.8 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.3

File hashes

Hashes for beautifuljason-1.0.4.tar.gz
Algorithm Hash digest
SHA256 b6ef3284609098dfb8b115d6c547d026787a150e9c085da07db66289d20ad83b
MD5 39c49fb2f0c789750511b0548906db4c
BLAKE2b-256 d882d876535ca0546caa5f5053f9e44d6153b4f66f7e6e174fe06f3739912dbb

See more details on using hashes here.

File details

Details for the file beautifuljason-1.0.4-py3-none-any.whl.

File metadata

File hashes

Hashes for beautifuljason-1.0.4-py3-none-any.whl
Algorithm Hash digest
SHA256 64b87f98b363e89a453410a2b130ae4efee4d98cf892377b497361b9bb8bb801
MD5 7eb3833eeb20c1d06d5ead8cb9b822cc
BLAKE2b-256 ad4fe71dc293dc682a9e392c0651c233f5ffa96acd725e1c433f5e2b7a84d95d

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page