Package: beautifuljason
Table of ContentsBeautifulJASONInstallationOperating System CompatibilityConfiguring the JASON PathRunning Unit TestsQuick StartJASON Analyze and Report ScriptOverviewUsageNotesJASON Batch Convert ToolOverviewUsageNotesAPI ReferenceSupport & FeedbackLicenseChangelogVersion 1.0.1 (2023-11-17)Version 1.0.0 (2023-10-26)BeautifulJASONBeautifulJASON is a Python API designed to seamlessly interface with NMR data generated by theJASON 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 theh5pylibrary, which is adept at handling NumPy data structures. However, BeautifulJASON abstracts away the complexities of the raw data structures provided byh5py. 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.InstallationYou can install BeautifulJASON viapip. Depending on your setup and environment, you might use different commands:Using `pip`:For most users, installing viapipis the standard method.pipinstallbeautifuljasonUsing `pip` for Python 3:If you have both Python 2 and Python 3 installed, you might need to usepip3to ensure the package is installed for Python 3.pip3installbeautifuljasonUsing Python’s `-m` option:In some environments, it’s beneficial to use Python’s-mswitch.python-mpipinstallbeautifuljasonUsing Python 3’s `-m` option:If you want to ensure you’re installing for Python 3, use the-mswitch withpython3.python3-mpipinstallbeautifuljasonOperating System CompatibilityWhile 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 PathFor most users who have installed JASON in a standard manner, there’s no need for manual configuration and you can likely skip this section.BeautifulJASONwill 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 ofBeautifulJASON,You may need to specify or update the path to the JASON application.TheBeautifulJASONpackage is equipped with a tool,jason_config, to assist with this:Display the Current Configuration:To view the current path settings for the JASON application:jason_config--displayAdd 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/applicationBe sure to replace/path/to/your/jason/applicationwith the actual path to your JASON executable.For Additional Commands and Options:If you need more details about available commands or want to explore other options:jason_config--helpAlways ensure that the specified path points directly to the JASON executable forBeautifulJASONto function correctly.Running Unit TestsTo ensure the functionality and correctness ofBeautifulJASONin 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-munittestdiscoverbeautifuljason.testsThis command will discover and run all the tests inside thebeautifuljason.testspackage. If all tests pass, it indicates thatBeautifulJASONis 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-munittestdiscoverbeautifuljason.tests-vThis will display a more detailed log of each test being run, along with its result.Quick StartFor those who prefer diving right into code, a fully runnable example is provided in theBeautifulJASONlibrary. You can find the script in the ‘examples’ subpackage under the namequick_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 thequick_start.pyscript contains:importosimporttempfileimportbeautifuljasonasbjasonfromPILimportImageasPILImage# Determine the path to the data directory inside the beautifuljason's tests subpackagetest_data_dir=os.path.join(os.path.dirname(bjason.__file__),'tests','data')# Specify input spectral file and define the path for the output PNG fileinput_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 interfacejason=bjason.JASON()# Define and customize the default font settingsfont=bjason.base.Font.default_font()font['family']='Arial'font['point_size']=12# Load the 1H spectral file, apply multiplet analysis, and customize its visual appearancewithjason.create_document(input_1H_file,actions=[{'name':'multiplet_analysis'}])asdoc:# Access the first spectral item and adjust its propertiesspec_item=doc.nmr_items[0]spec_item.header='Ethylindanone'spec_item.header_font=fontspec_item.x_font=fontspec_item.mult_intg_label_font=fontspec_item.peak_label_font=fontspec_item.plot_1d_color='#3556d8'spec_item.show_y_axis=False# Save the customized document to an image filejason.save(doc,output_file)# Display the generated image using the default image viewerimage=PILImage.open(output_file)image.show()JASON Analyze and Report ScriptOverviewTheanalyze_and_report.pyscript showcases the capabilities ofBeautifulJASONby 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.UsageExecute the script by running:python-mbeautifuljason.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 onproton.jdf,carbon.jdf, andhsqc.jdf, and save the combined results incombined_results.jjh5, you would execute:python-mbeautifuljason.examples.analyze_and_reportproton.jdfcarbon.jdfhsqc.jdf-output_filesresult.jjh5NotesThe 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.jjh5file is the output, the script can optionally launch JASON for visual inspection of the results.This script serves as a showcase ofBeautifulJASON’s capabilities. It can be modified or used as a foundation for more complex workflows.JASON Batch Convert ToolOverviewThejason_batch_converttool 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.UsageTo use thejason_batch_converttool, 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.jdffiles in thedatadirectory tojjh5andpdf, you would run:jason_batch_convertdataconverted-formatsjjh5pdf-extensionsjdfNotesThe tool is designed to handle file-based formats.Folder-based formats are not supported in this version.API ReferenceFor a comprehensive API reference, please refer to theofficial BeautifulJASON documentation pageon the JASON project website.Support & FeedbackFor support, questions, or to provide feedback on BeautifulJASON, please contactJASON’s supporton the JASON project website.LicenseBeautifulJASON is provided under the MIT License. For full license details, please refer to theLICENSEfile included with this distribution or visitMIT License on OSI.ChangelogVersion 1.0.1 (2023-11-17)Added relative path support to thejason_batch_convertandanalyze_and_reportscripts for enhanced file path flexibility.Version 1.0.0 (2023-10-26)Initial release: CoreBeautifulJASONframework for JEOL JASON interactions.