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)
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

New 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_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_nmrassignments_table(mol_item: MoleculeGraphicsItem, mol_data: Molecule) → AssignmentTableGraphicsItem

New 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) → NMRParamTableGraphicsItem

Creates a new NMR parameters table 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 table is linked.

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

Returns:

The created NMR parameters table graphics item.

Return type:

graphics.NMRParamTableGraphicsItem

Example Usage:

import beautifuljason as bjason

with bjason.Document('example.jjh5') as doc:
    nmr_item = doc.nmr_items[0]
    params_table = doc.create_nmrparams_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_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_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 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

New 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 mol_data: Iterable[Molecule]

New 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]

New 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 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))