PySpecTools

A Python library for analysis of rotational spectroscopy and beyond

Introduction

PySpecTools is a library written to help with analyzing rotational
spectroscopy data. The main functions of this library are:

1. Wrapper for SPFIT and SPCAT programs of Herb Pickett, with YAML/JSON
   interpretation
2. Generating specific figure types using matplotlib, such as polyads and
   potential energy diagrams
3. Parsing and filtering of Fourier-transform centimeter-wave and
   millimeter-wave absorption data. This includes:
   • Fitting of lineshapes (e.g. Lorentizan second-derivative profiles)
   • Fourier-filtering
   • Double resonance fitting
4. Analysis of broad band spectra with the AssignmentSession and Transition classes.
   These classes, combined with Jupyter notebooks, provide a way to assign spectra
   reproducibly; astronomical and laboratory broadband spectra are supported.
5. Autofit routines are available for a set of special cases, like linear/prolate
   molecules. Eventually, SPFIT will be a backend option.
6. Molecule identity inference (NEW!)—this uses a pre-trained probabilistic deep
   learning model that allows users to perform inference on experimental constants
   and expected composition to predict the most likely molecular formula and possible
   functional groups present. See our paper on the development of the first generation of this model. An example of how to run this analysis
   can be found here.

The documentation for PySpecTools can be found here.

If you use PySpecTools for research, please cite use the DOI badge below to cite the version
of the package; this is not to track adoption, but rather for the sake of reproducibility!

Installation

With version 5.0.0, major changes have been introduced in order to make
the installation functional with the current state of Python build tools.

The provided conda.yml should be a one-stop shop install:

# recommended to use mamba instead of conda, but both work
git clone https://github.com/laserkelvin/PySpecTools.git && cd PySpecTools
mamba env create -n pst -f conda.yml

This should install a recent version of Python, and all of the dependencies
along with PySpecTools itself.

PyPickett

PySpecTools includes a set of routines for wrapping SPFIT/SPCAT. The design
philosophy behind these functions is that the formatting and running of
SPFIT/SPCAT can be a little tricky, in terms of reproducibility, parameter
coding, and visualization. These problems are solved by wrapping and managing
input files in an object-oriented fashion:

1. Able to serialize SPFIT/SPCAT files from more human-friendly formats like
   YAML and JSON.
2. Automatic file/folder management, allowing the user to go back to an earlier
   fit/parameters. Ability to “finalize” the fit so the final parameter set is
   known.
3. Display the predicted spectrum using matplotlib in a Jupyter notebook,
   which could be useful for analysis and publication.
4. A parameter scan mode, allowing the RMS to be explored as a function of
   whatever parameter.

There is still much to do for this module, including a way of managing experimental lines.

Notes on release

PySpecTools is currently being released on a irregular schedule, using a sequence-based version numbering system.
The numbering works as X.Y.Z, where X denotes huge changes that are backwards incompatible, Y are significant changes
(typically new features) and Z are minor bug fixes. A freeze and release will typically occur when
a new version with potentially backwards breaking changes are about to be made. The large changes typically occur once a year (based on the trend so far).

Currently, PySpecTools is under the MIT license, which allows anyone to freely use and modify as you wish!

Planned features

1. Integration of deep learning tools for molecule identifiction and spectral assignment
2. Probability-based assignment routines - rather than single assignments.
3. Revamp of codebase - needs a substantial re-organization that will likely result in backwards compatibility breaking.
4. Additional Cython routines - many functions within PySpecTools are fast enough, but we can always go faster 😀
5. Better abstraction in the spectra.assignment modules - need to move a lot of the complicated routines into subclasses (especially for transitions and line lists), although there is a case to be made for a simpler user interface (only have to deal with LineList, instead of three subclasses of LineList)

Contributing

If you have features you think would benefit other spectroscopists, you can raise an issue in the repo. Alternatively (and even better) would be to fork the repo, and submit a pull request!

The only comments on coding style are:

1. Documentation is written in NumPy style
2. Object-oriented Python
3. Formatted with black

There are a set of unit tests that can be run to ensure the most complicated routines in the
library are working as intended. Right now coverage is poor, and so the tests I’ve written
focus on the assignment module. There is a script contained in the tests folder that will
generate a synthetic spectrum to test functionality on. To run these tests:

cd tests
python generate_test_spectrum.py
pytest

You will need to have pytest installed. These tests are designed to raise errors when there
are huge errors; some tolerance is included for imperfect peak detection, for example. These
are defined as constants within the test_assignment.py testing script.

Questions? Comments?

If you have features you would like to have added, please raise an issue on the repo, or
feel free to send me an email at kinlee_at_cfa.harvard.edu.

Also, please feel free to fork and contribute! The code is being formatted with black,
and uses NumPy-style docstrings. If you have any questions about contributing, drop me an
email!