JASON Document Module

class beautifuljason.document.Document(file_name: str, is_temporary=False, mode='a')

Bases: object

This class is used to create, read, and modify JASON documents. It provides methods to create various types of graphics items, including text items, image items, NMR peaks tables, multiplet tables, assignment tables, and multiplet reports.

It consists of two logical parts: data and graphics items. Data are the actual data objects (e.g., NMR spectra, molecules, images, texts, etc) that are stored in the document. Graphics items are the visual representations of these data objects in the document. The graphics items are linked to the data objects, allowing for easy access and manipulation of the data.

Key Features:

  1. Access NMR spectra, molecules, images, and text data stored in the document.
  2. Access graphics items representing data visually.

    • items: List of all graphics items.

    • nmr_items: List of NMR spectrum graphics items.

    • mol_items: List of molecule graphics items.

    • items_by_type(): Returns a list of graphics items of the specified type.

  3. New graphics items creation.
Parameters:

  • file_name (str) – The file name of the JASON document. The absolute path is recommended.

  • is_temporary (bool) – Whether the document is temporary. If True, the document will be deleted when the Document object is destroyed.

  • mode (str) – The mode in which the file should be opened. Defaults to ‘a’ (append mode). Use ‘r’ for read-only mode.

_create_item_elem(item_type)
property all_logfile_paths: Iterable[str]

Added in version 1.2.0.

Returns paths to all non-primary log files that were associated with the document during its lifetime.

See also

Returns:

Paths to all non-primary log files associated with the document.

Return type:

Iterable of str

close()

Closes the document file.

copy(file_name: str | bytes)

Copies the JASON document to a new file.

Note

Starting from h5py v3.4, it’s essential to close the h5py.File object before using the ‘copy’ method. This constraint diminishes the utility of the ‘copy’ method. Intentionally, the self.close() line is omitted in this method, delegating the responsibility of calling ‘close’ to the programmer.

Parameters:

file_name (str | bytes) – The destination file name.

create_chart_item() → ChartGraphicsItem

Added in version 1.1.0.

Creates a new chart item in the document. Requires the document to be opened in append mode (‘a’).

Returns:

The created chart graphics item.

Return type:

graphics.ChartGraphicsItem

Example Usage:

import beautifuljason as bjason

with bjason.Document('example.jjh5') as doc:
    new_chart_item = doc.create_chart_item()
    # In the code below we assume that doc.items[1] is a NMRPeakTableGraphicsItem
    series = new_chart_item.add_series(doc.items[1].id, bjason.NMRPeakTableGraphicsItem.ColumnID.POS0, bjason.NMRPeakTableGraphicsItem.ColumnID.VOLUME)
    series.name = "My Series"
    new_chart_item.pos = (doc.page_margin, doc.page_margin)
    new_chart_item.size = (400, 300)
create_document_id() → bool

Added in version 1.2.0.

Creates and assigns a new persistent UUID to the document.

This method is mainly intended for documents created with JASON versions prior to 6.1 that do not contain a DocumentID.

Returns:

True if a new UUID was created. False if the document already has an ID or the file is opened in read-only mode.

Return type:

bool

create_image_data(image_file: str) → Image

Creates a new image data in the document. Requires the document to be opened in append mode (‘a’). The image data is created from the specified image file. It’s necessary to create ImageGraphicsItem items in the document to display the image data. Multiple image items can be linked to the same image data.

See also

Parameters:

image_file (str) – The path to the image file.

Returns:

The created image data object.

Return type:

Image

Example Usage:

import beautifuljason as bjason

with bjason.Document('example.jjh5') as doc:
    image_data = doc.create_image_data('example.png')
    new_image_item = doc.create_image_item(image_data.id)
    new_image_item.pos = (0, 0)
    new_image_item.size = (100, 100)
create_image_item(data_id: str) → ImageGraphicsItem

Creates a new image item in the document. Requires the document to be opened in append mode (‘a’).

See also

Parameters:

data_id (str) – The ID of the image data object.

Returns:

The created image graphics item.

Return type:

graphics.ImageGraphicsItem

Example Usage:

import beautifuljason as bjason

with bjason.Document('example.jjh5') as doc:
    image_data = doc.create_image_data('example.png')
    new_image_item = doc.create_image_item(image_data.id)
    new_image_item.pos = (0, 0)
    new_image_item.size = (100, 100)
create_mscentroid_table(spec_item: MSSpectrumGraphicsItem, spec_data: MSEntry) → MSCentroidTableGraphicsItem

Added in version 1.2.0.

Creates a new MS centroid table in the document. Requires the document to be opened in append mode (‘a’).

Parameters:

  • spec_item (graphics.MSSpectrumGraphicsItem) – The spectrum graphics item to which the table is linked.

  • spec_data (data.MSEntry) – The MS entry data for the table.

Returns:

The created MS centroid table graphics item.

Return type:

graphics.MSCentroidTableGraphicsItem

Example Usage:

import beautifuljason as bjason

with bjason.Document('example.jjh5') as doc:
    ms_item = doc.ms_items[0]
    centroid_table = doc.create_mscentroid_table(ms_item, ms_item.spec_data_list[0])
    centroid_table.pos = (ms_item.pos[0], ms_item.pos[1] + ms_item.size[1] + 2*doc.page_margin)
    centroid_table.size = ms_item.size
create_mspeaks_table(spec_item: MSSpectrumGraphicsItem, spec_data: MSEntry) → MSPeakTableGraphicsItem

Added in version 1.2.0.

Creates a new MS peaks table in the document. Requires the document to be opened in append mode (‘a’).

Parameters:

  • spec_item (graphics.MSSpectrumGraphicsItem) – The spectrum graphics item to which the table is linked.

  • spec_data (data.MSEntry) – The MS entry data for the table.

Returns:

The created MS peaks table graphics item.

Return type:

graphics.MSPeakTableGraphicsItem

Example Usage:

import beautifuljason as bjason

with bjason.Document('example.jjh5') as doc:
    ms_item = doc.ms_items[0]
    peaks_table = doc.create_mspeaks_table(ms_item, ms_item.spec_data_list[0])
    peaks_table.pos = (ms_item.pos[0] + 2*doc.page_margin, ms_item.pos[1] + 5*doc.page_margin)
    peaks_table.size = tuple(dim / 3 for dim in ms_item.size)
create_nmrassignments_table(mol_item: MoleculeGraphicsItem, mol_data: Molecule) → AssignmentTableGraphicsItem

Added in version 1.1.0.

Creates a new NMR assignments table in the document. Requires the document to be opened in append mode (‘a’).

Parameters:

  • mol_item (MoleculeGraphicsItem) – The molecule graphics item to which the table is linked.

  • mol_data (data.Molecule) – The molecule data for the table.

Returns:

The created NMR assignments table graphics item.

Return type:

graphics.AssignmentTableGraphicsItem

Example Usage:

import beautifuljason as bjason

with bjason.Document('example.jjh5') as doc:
    mol_item = doc.mol_items[0]
    assignments_table = doc.create_nmrassignments_table(mol_item, mol_item.mol_data())
    assignments_table.pos = (mol_item.pos[0] + 2*doc.page_margin, mol_item.pos[1] + 5*doc.page_margin)
    assignments_table.size = tuple(dim / 3 for dim in mol_item.size)
create_nmrmultiplet_report(spec_item: NMRSpectrumGraphicsItem, spec_data: NMRSpectrum) → NMRMultipletReportGraphicsItem

Creates a new NMR multiplet report in the document. Requires the document to be opened in append mode (‘a’).

Parameters:

  • spec_item (graphics.NMRSpectrumGraphicsItem) – The spectrum graphics item to which the report is linked.

  • spec_data (data.NMRSpectrum) – The NMR spectrum data for the report.

Returns:

The created NMR multiplet report graphics item.

Return type:

graphics.NMRMultipletReportGraphicsItem

Example Usage:

import beautifuljason as bjason

with bjason.Document('example.jjh5') as doc:
    nmr_item = doc.nmr_items[0]
    multiplet_report = doc.create_nmrmultiplet_report(nmr_item, nmr_item.spec_data_list[0])
    multiplet_report.pos = (nmr_item.pos[0] + 2*doc.page_margin, nmr_item.pos[1] + 5*doc.page_margin)
    multiplet_report.size = tuple(dim / 3 for dim in nmr_item.size)
create_nmrmultiplets_table(spec_item: NMRSpectrumGraphicsItem, spec_data: NMRSpectrum) → NMRMultipletTableGraphicsItem

Creates a new NMR multiplets table in the document. Requires the document to be opened in append mode (‘a’).

Parameters:

  • spec_item (NMRSpectrumGraphicsItem) – The spectrum graphics item to which the table is linked.

  • spec_data (data.NMRSpectrum) – The NMR spectrum data for the table.

Returns:

The created NMR multiplets table graphics item.

Return type:

graphics.NMRMultipletTableGraphicsItem

Example Usage:

import beautifuljason as bjason

with bjason.Document('example.jjh5') as doc:
    mol_item = doc.mol_items[0]
    assignments_table = doc.create_nmrassignments_table(mol_item, mol_item.mol_data())
    assignments_table.pos = (mol_item.pos[0], mol_item.pos[1] + mol_item.size[1] + 2*doc.page_margin)
    assignments_table.size = mol_item.size
create_nmrparams_table(spec_item: NMRSpectrumGraphicsItem, spec_data: NMRSpectrum) → ParamTableGraphicsItem

Same as create_params_table(). Kept for backward compatibility.

create_nmrpeaks_table(spec_item: NMRSpectrumGraphicsItem, spec_data: NMRSpectrum) → NMRPeakTableGraphicsItem

Creates a new NMR peaks table in the document. Requires the document to be opened in append mode (‘a’).

Parameters:

  • spec_item (NMRSpectrumGraphicsItem) – The spectrum graphics item to which the table is linked.

  • spec_data (data.NMRSpectrum) – The NMR spectrum data for the table.

Returns:

The created NMR peaks table graphics item.

Return type:

graphics.NMRPeakTableGraphicsItem

Example Usage:

import beautifuljason as bjason

with bjason.Document('example.jjh5') as doc:
    nmr_item = doc.nmr_items[0]
    peaks_table = doc.create_nmrpeaks_table(nmr_item, nmr_item.spec_data_list[0])
    peaks_table.pos = (nmr_item.pos[0], nmr_item.pos[1] + nmr_item.size[1] + 2*doc.page_margin)
    peaks_table.size = nmr_item.size
create_params_table(spec_item: GraphicsItem, spec_data: IDedObject) → ParamTableGraphicsItem

Added in version 1.2.0.

Creates a new parameters table in the document. Requires the document to be opened in append mode (‘a’).

Parameters:

  • spec_item (graphics.GraphicsItem) – The spectrum graphics item to which the table is linked.

  • spec_data (base.IDedObject) – The spectrum data for the table.

Returns:

The created parameters table graphics item.

Return type:

graphics.ParamTableGraphicsItem

Example Usage:

import beautifuljason as bjason

with bjason.Document('example.jjh5') as doc:
    nmr_item = doc.nmr_items[0]
    params_table = doc.create_params_table(nmr_item, nmr_item.spec_data_list[0])
    params_table.pos = (nmr_item.pos[0], nmr_item.pos[1] + nmr_item.size[1] + 2*doc.page_margin)
    params_table.size = nmr_item.size
create_text_item(html_str: str = '') → TextGraphicsItem

Creates a new text item in the document. Requires the document to be opened in append mode (‘a’).

Parameters:

html_str (str) – The HTML text to be added.

Returns:

The created text graphics item.

Return type:

graphics.TextGraphicsItem

Example Usage:

import beautifuljason as bjason

with bjason.Document('example.jjh5') as doc:
    new_text_item = doc.create_text_item("<h1>Hello, World!</h1>")
    print(new_text_item.text.html)
    # Make sure the text item is available in the list of text items
    for text_item in doc.items_by_type(bjason.graphics.GraphicsItem.Type.Text):
        if text_item.id == new_text_item.id:
            print(bjason.utils.ensure_str(text_item.text.html))
property custom_data: Iterable[CustomData]

Added in version 1.2.0.

Returns:

Custom data objects stored in the document.

Return type:

Iterable of data.CustomData

Example Usage:

import beautifuljason as bjason

with bjason.Document('example.jjh5', mode='r') as doc:
    for cd in doc.custom_data:
        print(cd.data_type_id)
property document_id: str | None

Added in version 1.2.0.

Returns the persistent UUID of the document.

The DocumentID attribute was introduced in JASON 6.1. Documents created with earlier versions do not contain this attribute, in which case None is returned.

If needed, a new ID can be created explicitly using create_document_id(). This is intentionally a separate operation to avoid side effects.

Returns:

The UUID if it exists, otherwise None.

Return type:

str | None

property image_data: Iterable[Image]
Returns:

A list of all image data objects in the document.

Return type:

Iterable of data.Image

Example Usage: .. code-block:: python

import beautifuljason as bjason

with bjason.Document(‘example.jjh5’, mode=’r’) as doc:
for image in doc.image_data:

print(bjason.utils.ensure_str(image.id))

property items: list[GraphicsItem]
Returns:

A list of all graphics items in the document.

Return type:

list of graphics.GraphicsItem

Example Usage:

import beautifuljason as bjason

with bjason.Document('example.jjh5', mode='r') as doc:
    for item in doc.items:
        print(item.type.name, item.pos, item.size)
items_by_type(item_type: Type | GraphicsItem) → list

Added in version 1.1.0.

Returns a list of graphics items of the specified type.

Parameters:

item_type (GraphicsItem.Type) – The type of graphics item to filter by.

Returns:

A list of graphics items of the specified type.

Return type:

list

load(mode='a')

Loads the JASON document file.

Parameters:

mode (str) – The mode in which the file should be opened. Defaults to ‘a’ (append mode). Use ‘r’ for read-only mode.

property logfile_path: str

Added in version 1.2.0.

Each JASON instance generates a single log file at startup. All documents created within that instance are linked to this log file.

The log file is a plain text file that records the full history of operations performed in the instance, including timestamps, user name, and the “before” and “after” states of modified parameters. It also captures warnings and critical error messages.

Because of this detailed tracking, JASON log files serve as an audit trail for the associated documents.

JASON itself only stores the path to the log file in the document. It is the responsibility of the system into which JASON is integrated to retrieve and store the log file using the provided path.

See also

Returns:

The path to the log file.

Return type:

str

Example Usage:

import beautifuljason as bjason

with bjason.Document('example.jjh5') as doc:
    print(doc.logfile_path)
property mol_data: Iterable[Molecule]

Added in version 1.1.0.

Returns:

A list of all molecule data objects in the document.

Return type:

Iterable of data.Molecule

Example Usage:

import beautifuljason as bjason

with bjason.Document('example.jjh5', mode='r') as doc:
    for mol in doc.mol_data:
        for atom in mol.atoms:
            print(atom.type.name, atom.x, atom.y, atom.z if atom.z else '')
property mol_items: list[MoleculeGraphicsItem]

Added in version 1.1.0.

A convenience property to get all molecule graphics items in the document.

Returns:

A list of all molecule graphics items in the document.

Return type:

list of graphics.MoleculeGraphicsItem

Example Usage:

import beautifuljason as bjason

with bjason.Document('example.jjh5', mode='r') as doc:
    for mol_item in doc.mol_items:
        for atom in mol_item.mol_data().atoms:
            print(atom.type.name, atom.x, atom.y, atom.z if atom.z else '')
property ms_data: Iterable[MSEntry]

Added in version 1.2.0.

Returns:

A list of all MS data entries in the document.

Return type:

Iterable of MSEntry

Example Usage:

import beautifuljason as bjason

with bjason.Document('example.jjh5', mode='r') as doc:
    for ms in doc.ms_data:
        print(bjason.utils.ensure_str(ms.spec_info.get_param("Title")))
property ms_items: list[MSSpectrumGraphicsItem]

Added in version 1.2.0.

A convenience property to get all MS spectrum graphics items in the document.

Returns:

A list of all MS spectrum graphics items in the document.

Return type:

list of graphics.MSSpectrumGraphicsItem

Example Usage:

import beautifuljason as bjason

with bjason.Document('example.jjh5', mode='r') as doc:
    for ms_item in doc.ms_items:
        print(ms_item.header)
        for spec in ms_item.spec_data_list:
            print("  ", bjason.utils.ensure_str(spec.spec_info.get_param("Title")))
property nmr_data: Iterable[NMRSpectrum]
Returns:

A list of all NMR data objects (spectra) in the document.

Return type:

Iterable of NMRSpectrum

Example Usage:

import beautifuljason as bjason

with bjason.Document('example.jjh5', mode='r') as doc:
    for spec in doc.nmr_data:
        print(bjason.utils.ensure_str(spec.spec_info.get_param("Title")))
property nmr_items: list[NMRSpectrumGraphicsItem]

A convenience property to get all NMR spectrum graphics items in the document.

Returns:

A list of all NMR spectrum graphics items in the document.

Return type:

list of graphics.NMRSpectrumGraphicsItem

Example Usage:

import beautifuljason as bjason

with bjason.Document('example.jjh5', mode='r') as doc:
    for nmr_item in doc.nmr_items:
        print(nmr_item.header)
        for spec in nmr_item.spec_data_list:
            print("  ", spec.spec_info.nuclides[0], bjason.utils.ensure_str(spec.spec_info.get_param("Title")))
remove()

Closes and removes the document file if it’s marked as temporary.

property text_data: Iterable[Text]
Returns:

A list of all text data objects in the document.

Return type:

Iterable of data.Text

Example Usage:

import beautifuljason as bjason

with bjason.Document('example.jjh5', mode='r') as doc:
    for text in doc.text_data:
        print(bjason.utils.ensure_str(text.html))