JASON Module

This module provides an interface to the JASON application, allowing users to automate processing, analysis, and report generation. It includes functionality for creating and manipulating JASON documents, applying actions, and saving results in various formats.

Note

The JASON application must be installed and have a valid license. If necessary, use the jason_config tool to set the path to the JASON application.
While BeautifulJASON is designed to be OS Independent, it’s important to note that the jason module 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 module will not.

class beautifuljason.jason.Config

Bases: object

Represents the configuration settings for the JASON application. This class handles loading, saving, and managing the paths to the JASON application instances. It also provides methods to add, delete, and set preferred paths for JASON instances.

The configuration is stored in a file named config.ini located in the user’s home directory under .beautifuljason. The configuration file contains paths to different JASON instances and a preferred path key.

The configuration file is created with default values if it does not exist. The default paths are set based on the operating system (Windows or macOS).

Note

Don’t use the Config class directly. Use the jason_config tool for configuring the JASON application path.

_load_config(): Load the JASON application path from the config.ini.

add_path(new_path: str) → int

Add a new JASON instance path to the config.

Parameters:: new_path (str) – The new path to add for the JASON instance.
Returns:: The index of the new path or the existing index if the path already exists.
Return type:: int

property all_paths: list[tuple[int, str]]

Returns:: A list of all JASON application paths from the config.
Return type:: list[tuple[int, str]]

property config_path: str

Returns:: The path to the config.ini file.
Return type:: str

delete_path_by_index(index)

Delete a JASON instance path by its index.

Parameters:: index (int) – The index of the path to delete.

find_path(path: str) → int | None

Find the index of a JASON instance path in the config.

Parameters:: path (str) – The path to find in the JASON instance config.
Returns:: The index of the path if found, otherwise None.
Return type:: int | None

property preferred_path_index: int | None

Returns:: The index of the preferred JASON instance path.
Return type:: int | None

reset(): Reset the configuration to the default settings.

set_preferred_path_index(path_index: int)

Set a new preferred JASON instance path index.

Parameters:: path_index (int) – The new path to set as preferred for the JASON instance.

class beautifuljason.jason.JASON(app_path: str | None = None, plugins: list[str] = ['off'])

Bases: object

This class provides methods to interact with the JASON application. It allows users to create documents, apply actions, and save results in various formats.

Parameters:

app_path (str | None) – The path to the JASON application. If not provided, it will be fetched from the configuration, which is the recommended way.
plugins (list[str] | None) – Defines the plugins to load. [‘off’] skips loading, while ‘None’ or [] loads all.

Raises:

JASONException – If the JASON app path is not specified or does not exist.

JASON Class Example Usage

from beautifuljason import JASON

# Initialize the JASON interface
jason = JASON()

# Create a document for the specified file using the rules
with jason.create_document(
        file_names=["example.jdf"],
        rules="example_rules.jjr"  # Use the rules file for processing, analysis and layout
    ) as doc:

    # Save the document
    jason.save(doc, file_names="output.pdf")

_create_actions_file(actions): Creates a temporary actions file based on the provided actions.

_run(args: list[str]) → CompletedProcess

Run the JASON application with the specified arguments. This method is used internally. However, it can be used to run JASON in headless mode in complex scenarios. It is recommended to use the create_document() method instead.

Parameters:: args (list[str]) – The arguments to pass to the JASON application.
Returns:: The result of the subprocess run.
Return type:: subprocess.CompletedProcess

apply_actions(doc: Document, actions: list[dict])

Applies the specified actions to a JASON document. This is useful for automating the processing and analysis of existing JASON .jjh5 documents.

Parameters:

doc (Document) – The JASON document to which the actions should be applied.
actions (list[dict]) – The actions to apply. This argument is similar to the actions parameter in the create_document() method. Refer to the create_document() documentation for details on the structure and examples of actions.

Example usage:

from beautifuljason import JASON, Document

# Initialize the JASON interface
jason = JASON()

# Open an existing JASON document
with Document("example.jjh5") as doc:
    # Categorize NMR items by their dimensionality and nucleus type
    items_1H = []
    items_13C = []
    items_2D = []
    for spec_item in doc.nmr_items:
        spec_data = spec_item.spec_data(0)
        if spec_data.ndim == 2:
            items_2D.append(spec_item.id)
        elif spec_data.ndim == 1:
            if spec_data.spec_info.nuclides[0] == '1H':
                items_1H.append(spec_item.id)
            elif spec_data.spec_info.nuclides[0] == '13C':
                items_13C.append(spec_item.id)

    # Apply analysis actions to the document
    jason.apply_actions(doc, [
        {'name': 'multiplet_analysis', 'items': items_1H},
        {'name': 'peak_picking', 'items': items_13C + items_2D}
    ])

create_document(file_names: list[str] | str, actions: list[dict] = [], rules: str = 'off') → Document

Creates a JASON document based on provided files and actions.

Parameters:

file_names (list[str] | str) – List of file names or a single file name to be processed.

actions (list[dict], optional) –

Actions to apply to the files. Defaults to an empty list. Each action is a dictionary with the action name and parameters. Actions include:

’peak_picking’
’integration’
’multiplet_analysis’
’processing’

Simple examples:

[{'name': 'peak_picking'}]

or

[{'name': 'integration'}]

or

[{'name': 'multiplet_analysis'}]

These imply that the default JASON parameters are used.

More complex example:

[
    {
        "name": "processing",
        "params": "proton.jjp"
    },
    {
        "name": "multiplet_analysis",
        "params": {
            "normalize": {
                "units": [3],
                "position": [1.009],
                "value": 3.0
            }
        }
    }
]

The actions are applied in the order they are provided.

Note

It is recommended to use the rules argument to pass the corresponding processing and analysis instead of specifying actions manually.

rules (str, optional) – “on”, “off”, library name, or rule library file path. Defaults to “off”. If you want to apply specific processing and analysis, use the rules feature instead of actions.

Returns:

The created JASON document.

Return type:

document.Document

Example usage: See JASON Class Example Usage.

launch(args)

Launches the JASON GUI application with the provided arguments. For headless mode, use the _run() method, or preferably, the create_document() method.

Parameters:: args (list[str]) – The arguments to pass to the JASON application.

save(doc: Document, file_names: list[str] | str, actions: list[dict] = [])

Saves the JASON document to the specified file names after applying the given actions. The file format is determined by the file extension.

The extensions supported are:

.jjh5 (JASON HDF5 format) - recommended for JASON documents
.jjj (JASON JSON format)
.jdx (JCAMP-DX format)
.pdf (PDF format) - recommended for reports
.jdf (JEOL Delta Format)
.png, .jpg, .jpeg, .tiff (Raster image formats)
.svg (Scalable Vector Graphics)
.mol (Molfiles)
Check the “Save As” dialog in JASON for additional supported formats.

Parameters:

doc (Document) – The JASON document to save.
file_names (list[str] | str) – List of file names or a single file name to save the document to. JASON will determine the format based on the file extension.
actions (list[dict], optional) – Actions to apply to the document before saving. Defaults to an empty list.

Example usage: See JASON Class Example Usage.

property version: tuple[int, int, int] | None

Returns:: The JASON version as a tuple of integers. Empty tuple if the version cannot be determined.
Return type:: tuple of int | tuple

exception beautifuljason.jason.JASONException

Bases: Exception

Exception raised for errors specific to the JASON application.