Examples

The beautifuljason.examples package contains demonstration scripts showcasing practical usage of the BeautifulJASON API. These scripts are intended as a starting point and reference for developers integrating JASON automation into their workflows.

quick_start.py

A minimal example that loads a 1D 1H spectrum, performs multiplet analysis, customizes the visual appearance, and saves the result as a PNG image.

Highlights:

  • Runs without user configuration using bundled test data.

  • Shows how to apply analysis and customize graphics items.

  • Demonstrates document rendering and export to image.

Source code:

 1##
 2##-----------------------------------------------------------------------------
 3##
 4## Copyright (c) 2023 JEOL Ltd.
 5## 1-2 Musashino 3-Chome
 6## Akishima Tokyo 196-8558 Japan
 7##
 8## This software is provided under the MIT License. For full license information,
 9## see the LICENSE file in the project root or visit https://opensource.org/licenses/MIT
10##
11##++---------------------------------------------------------------------------
12##
13## ModuleName : BeautifulJASON
14## ModuleType : Python API for JASON desktop application and JJH5 documents
15## Purpose : Automate processing, analysis, and report generation with JASON
16## Author : Nikolay Larin
17## Language : Python
18##
19####---------------------------------------------------------------------------
20##
21
22def main():
23    import os
24    import tempfile
25    import beautifuljason as bjason
26    from PIL import Image as PILImage
27
28    # Determine the path to the data directory inside the beautifuljason's tests subpackage
29    test_data_dir = os.path.join(os.path.dirname(bjason.__file__), 'tests', 'data')
30
31    # Specify input spectral file and define the path for the output PNG file
32    input_1H_file = os.path.join(test_data_dir, "Ethylindanone_Proton-13-1.jdf")
33    output_file = os.path.join(tempfile.gettempdir(), "Ethylindanone_Proton-13-1.png")
34
35    # Create an instance of the JASON application interface
36    jason = bjason.JASON()
37
38    # Define and customize the default font settings
39    font = bjason.base.Font.default_font()
40    font['family'] = 'Arial'
41    font['point_size'] = 12
42    
43    # Load the 1H spectral file, apply multiplet analysis, and customize its visual appearance
44    with jason.create_document(input_1H_file, actions=[{'name': 'multiplet_analysis'}]) as doc:
45        # Access the first spectral item and adjust its properties
46        spec_item = doc.nmr_items[0]
47        spec_item.header = 'Ethylindanone'
48        spec_item.header_font = font
49        spec_item.x_font = font
50        spec_item.mult_intg_label_font = font
51        spec_item.peak_label_font = font
52        spec_item.plot_1d_color = '#3556d8'
53        spec_item.show_y_axis = False
54
55        # Save the customized document to an image file
56        jason.save(doc, output_file)
57
58    # Display the generated image using the default image viewer
59    image = PILImage.open(output_file)
60    image.show()
61
62if __name__ == '__main__':
63    main()

analyze_and_report.py

A more advanced batch script for automated report generation. Processes multiple input spectra, applies conditional analysis, adds parameter/peak/multiplet tables, customizes layout and appearance, inserts logos, and saves results in various formats.

Highlights:

  • Handles both 1H, 13C, and 2D NMR spectra with context-sensitive logic.

  • Generates publication-style multiplet reports for 1H spectra.

  • Adds parameter and peak tables, headers, and corporate branding.

  • Accepts multiple input/output files via command-line arguments.

Source code:

  1##
  2##-----------------------------------------------------------------------------
  3##
  4## Copyright (c) 2023 JEOL Ltd.
  5## 1-2 Musashino 3-Chome
  6## Akishima Tokyo 196-8558 Japan
  7##
  8## This software is provided under the MIT License. For full license information,
  9## see the LICENSE file in the project root or visit https://opensource.org/licenses/MIT
 10##
 11##++---------------------------------------------------------------------------
 12##
 13## ModuleName : BeautifulJASON
 14## ModuleType : Python API for JASON desktop application and JJH5 documents
 15## Purpose : Automate processing, analysis, and report generation with JASON
 16## Author : Nikolay Larin
 17## Language : Python
 18##
 19####---------------------------------------------------------------------------
 20##
 21
 22import argparse
 23import os.path
 24import datetime
 25import beautifuljason as bjason
 26
 27# Custom column ID for the multiplet name column of the multiplet table.
 28# The value must be negative and unique.
 29ColID_NAME = -1
 30
 31def parse_arguments():
 32    """Parse command line arguments."""
 33    parser = argparse.ArgumentParser(description='Batch process and analyze spectral files. The script performs automatic analysis of spectra, creates tables, reports, and modifies visual properties. The results are saved in the specified output files.')
 34    parser.add_argument('input_files', nargs='+', help='List of spectral files to process.')
 35    parser.add_argument('-output_files', required=True, nargs='+', help='List of output files. Supported formats: .jjh5, .jjj, .jdx, and .pdf.')
 36    return parser.parse_args()
 37
 38def customize_layout(doc: bjason.Document):
 39    """Customize the layout of spectral items."""
 40    for spec_item in doc.nmr_items:
 41        old_item_pos = spec_item.pos
 42        old_item_size = spec_item.size
 43        spec_item.pos = (old_item_pos[0] + old_item_size[0] * 0.3, old_item_pos[1])
 44        spec_item.size = (old_item_size[0] * 0.7, old_item_size[1] * 0.9)
 45    
 46def customize_appearance(doc: bjason.Document):
 47    """Customize the appearance of spectral items."""
 48    for spec_item in doc.nmr_items:
 49        spec_data = spec_item.spec_data(0)
 50        spec_item.show_y_axis = spec_data.ndim != 1
 51        spec_item.plot_1d_color = '#006400'
 52
 53def add_parameter_tables(doc: bjason.Document):
 54    """Add parameter tables and adjust their layout."""
 55    for spec_item in doc.nmr_items:
 56        spec_data = spec_item.spec_data(0)
 57        params_item = doc.create_nmrparams_table(spec_item, spec_data)
 58        params_item.param_list.append([
 59            {'name': 'Filename', 'value': os.path.basename(spec_data.raw_data.spec_info.get_param('OrigFilename'))},
 60            {'name': 'Nuclide', 'value': spec_data.spec_info.nuclides[0] if len(spec_data.spec_info.nuclides) == 1 else ', '.join(spec_data.spec_info.nuclides)},
 61            {'name': 'Solvent', 'value': spec_data.raw_data.spec_info.get_param('Solvent')}
 62        ])
 63        spec_item_pos = spec_item.pos
 64        spec_item_size = spec_item.size
 65        new_x = spec_item_pos[0] - 3.0/7.0*spec_item_size[0]
 66        params_item.pos = (new_x, spec_item_pos[1])
 67        params_item.size = (spec_item_pos[0] - new_x, spec_item_size[1] * 0.3)
 68
 69def add_peak_and_multiplet_tables(doc: bjason.Document):
 70    """Add peak and/or multiplet tables and adjust their layout. The multilet tables are created for 1H spectra only."""
 71    for spec_item in doc.nmr_items:
 72        spec_data = spec_item.spec_data(0)
 73        table_item: bjason.NMRPeakTableGraphicsItem | bjason.NMRMultipletTableGraphicsItem = None
 74        if spec_data.ndim == 1:
 75            if spec_data.spec_info.nuclides[0] == '1H':
 76                table_item = doc.create_nmrmultiplets_table(spec_item, spec_data)
 77                ColID = bjason.NMRMultipletTableGraphicsItem.ColumnID
 78                # Define visible columns and their order. Negative numbers correspond to custom columns. 
 79                table_item.visual_column_ids = (ColID_NAME, ColID.START0, ColID.END0, ColID.PEAKS_VOLUME, ColID.NORMALIZED)
 80                # Customize standard columns view  
 81                table_item.customized_columns.append((
 82                    {'Type': ColID.START0, 'Digits': 2},
 83                    {'Type': ColID.END0, 'Digits': 2},
 84                    {'Type': ColID.NORMALIZED, 'Digits': 1},
 85                    {'Type': ColID_NAME, 'Digits': -1, 'CustomTitle': 'Name'}
 86                ))
 87        if not table_item:
 88            table_item = doc.create_nmrpeaks_table(spec_item, spec_data)
 89            ColID = bjason.NMRPeakTableGraphicsItem.ColumnID
 90            if spec_data.ndim == 1:
 91                table_item.visual_column_ids = [ColID.POS0, ColID.WIDTH0, ColID.HEIGHT, ColID.VOLUME]
 92            elif spec_data.ndim == 2:
 93                table_item.visual_column_ids = [ColID.POS0, ColID.POS1, ColID.HEIGHT, ColID.VOLUME]
 94        table_item.show_title = True
 95        table_item.alternating_row_colors = True
 96        spec_item_pos = spec_item.pos
 97        spec_item_size = spec_item.size
 98        new_x = spec_item_pos[0] - 3.0/7.0*spec_item_size[0]
 99        table_item.pos = (new_x, spec_item_pos[1] + spec_item_size[1] * 0.3)
100        table_item.size = (spec_item_pos[0] - new_x, spec_item_size[1] * 0.7)
101
102def add_headers_and_logos(doc: bjason.Document):
103    """Add headers and logos to the document."""
104    logo_width = 200.0
105    logo_image_data = None
106    for spec_item in doc.nmr_items:
107        spec_item.show_header = False
108        text_item = doc.create_text_item()
109        text_item.pos = spec_item.pos
110        text_item.size = (spec_item.size[0], 60.0)
111        text_item.text.html = '<b>{}</b><br/>Copyright (C) My Company. All rights reserved'.format(datetime.datetime.now().isoformat(timespec='seconds'))
112        spec_item.pos = (spec_item.pos[0], text_item.pos[1] + text_item.size[1])
113        if logo_image_data is None:
114            logo_image_data = doc.create_image_data(os.path.abspath(os.path.join(os.path.dirname(__file__), 'JEOL_company_logo.png')))
115        image_item = doc.create_image_item(logo_image_data.id)
116        image_item.pos = (text_item.pos[0] + text_item.size[0] - logo_width, text_item.pos[1])
117        image = image_item.image
118        image_item.size = (logo_width, logo_width * image.height / image.width)
119
120def add_multiplet_reports(doc):
121    """Add multiplet reports to the document. The multiplet reports are created for 1H spectra only."""
122    for spec_item in doc.nmr_items:
123        spec_data = spec_item.spec_data(0)
124        if spec_data.ndim == 1 and spec_data.spec_info.nuclides[0] == '1H':
125            report_item = doc.create_nmrmultiplet_report(spec_item, spec_data)
126            report_item.journal_format = 'Wiley'
127            report_item.pos = spec_item.pos
128            report_item.size = (0.5 * spec_item.size[0], 0.25 * spec_item.size[1])
129
130def apply_analysis(jason, doc):
131    """
132    Apply specific analysis techniques based on the type of spectrum.
133    Specifically, the script performs multiplet analysis for 1H spectra and peak picking for 13C and 2D spectra.
134    """
135    items_1H = []
136    items_13C = []
137    items_2D = []
138    for spec_item in doc.nmr_items:
139        spec_data = spec_item.spec_data(0)
140        if spec_data.ndim == 2:
141            items_2D.append(spec_item.id)
142        elif spec_data.ndim == 1:
143            if spec_data.spec_info.nuclides[0] == '1H':
144                items_1H.append(spec_item.id)
145            elif spec_data.spec_info.nuclides[0] == '13C':
146                items_13C.append(spec_item.id)
147
148    # Apply analysis actions to the document
149    jason.apply_actions(doc, [{'name': 'multiplet_analysis', 'items': items_1H}, {'name': 'peak_picking', 'items': items_13C + items_2D}])
150    for item in doc.items:
151        if item.type == bjason.GraphicsItem.Type.NMRMultipletTable:
152            # Add custom multiplet names to the Name column of the multiplet table
153            table_item: bjason.NMRMultipletTableGraphicsItem = item
154            for i, multiplet in enumerate(item.spec_data.multiplets):
155                table_item.set_custom_value(multiplet.id, ColID_NAME, f'M{i+1}')
156
157def main():
158    """Main entry point of the script."""
159    jason = bjason.JASON() # Create a JASON object 
160    args = parse_arguments() # Parse command line arguments
161
162    # Convert input and output file paths to absolute paths
163    absolute_input_files = [os.path.abspath(file) for file in args.input_files]
164    absolute_output_files = [os.path.abspath(file) for file in args.output_files]
165
166    with jason.create_document(absolute_input_files) as doc:  # Open and process the spectral files in JASON
167        customize_layout(doc) # Customize the layout of spectral items
168        customize_appearance(doc) # Customize the appearance of spectral items
169        add_parameter_tables(doc)  # Add parameter tables and adjust their layout
170        add_peak_and_multiplet_tables(doc) # Add peak and/or multiplet tables and adjust their layout
171        add_headers_and_logos(doc) # Add headers and logos to the document
172        add_multiplet_reports(doc) # Add multiplet reports to the document
173        apply_analysis(jason, doc) # Apply specific analysis techniques based on the type of spectrum
174        jason.save(doc, absolute_output_files)  # Save the document to the specified output files
175
176    # Optionally, open the resulting .jjh5 file in JASON for visual inspection
177    jjh5_files = [output_file for output_file in absolute_output_files if output_file.endswith('.jjh5')]
178    if jjh5_files:
179        jason.launch(jjh5_files)
180
181if __name__ == "__main__":
182    main()

These examples are intended to be self-contained and modifiable. Users are encouraged to adapt them to their own datasets and requirements.