pyspectools package

Submodules

pyspectools.autofit module

Routines for performing automatic fitting using SPFIT/SPCAT.

class pyspectools.autofit.Autofit(input_dict)[source]

Bases: object

Class for an Autofit object which handles all of the formatting and executable calls.

class Line(frequency, unc=0.002)[source]

Bases: object

Line object that holds the frequency and assignments. Has access to methods for formatting.

format_lin()[source]

Function for formatting the line into a .lin file format. 12I3,freeform QN,Freq,Err,Wt

set_assignments(assignment)[source]

Function for setting up the quantum number assignments.

The assignments come in an OrderedDict such that when we pipe the data back out we want the upper levels to come out first.

assignment- key/value pairs correspond to the quantum

number and value. Must be an OrderedDict

delta_no(value, N=False)[source]

Simple function to generate a lower state quantum number based on the selection rule provided.

The value must also be greater or equal to zero.

For example, delta N = -1/0 delta K = -1, 0, 1 delta F = -1, 0, 1

value - integer value of upper state quantum number N - bool arg specifying whether the quantum number is N

lower_qno - value for lower quantum number

classmethod from_yaml(filepath)[source]

Class method to initialize an Autofit obj by reading in a YAML syntax file.

filepath - str specifying path to yaml file

autofit obj

generate_qnos()[source]

Function for generating random quantum numbers based on what is allowed.

These rules are hardcoded because certain aspects are already pre-ordained: e.g.

Builtin database module

database.py

Routines for managing a spectral line database.

TODO - set up routines for a persistent database

class pyspectools.database.SpectralCatalog(dbpath=None)[source]

Bases: tinydb.database.TinyDB

Grand unified experimental catalog. Stores assignment and uline information across the board.

add_catalog(catalog_path, name, formula, **kwargs)[source]

Load a SPCAT catalog file into the database. Creates independent Transition objects from each line of the catalog file. Kwargs are passed into the Transition object, which will allow additional settings for the Transition object to be accessed. :param catalog_path: :param name: :param formula: :param kwargs: :return:

add_entry(assignment, dup_check=True)[source]

This function adds an Transition object to an existing database. The method will check for duplicates before adding.

Parameters
  • - Transition object (assignment) – Reference to an Transition object

  • - bool, optional (dup_check) – If True (default), will check to make sure the Transition object doesn’t already exist in the database.

remove_experiment(exp_id)[source]

Remove all entries based on an experiment ID. :param exp_id: int, experiment ID

remove_molecule(name)[source]
search_experiment(exp_id, dataframe=True)[source]
search_formula(formula, dataframe=True)[source]
search_frequency(frequency, freq_prox=0.1, freq_abs=True, dataframe=True)[source]
Parameters
  • frequency – float, center frequency to search for in the database

  • freq_prox – float, search range tolerance. If freq_abs is True, the absolute value is used (in MHz). Otherwise, freq_prox is a decimal percentage of the frequency.

  • freq_abs – bool, dictates whether the absolute value of freq_prox is used.

Returns

search_molecule(name, dataframe=True)[source]

Search for a molecule in the database based on its name (not formula!). Wraps the _search_field method, which will return None if nothing is found, or either a pandas dataframe or a list of Transition objects :param name: str, name (not formula) of the molecule to search for :param dataframe: bool, if True, returns a pandas dataframe :return: matches: a dataframe or list of Transition objects that match the search name

class pyspectools.database.TheoryCatalog(dbpath=None)[source]

Bases: tinydb.database.TinyDB

Grand unified theory catalog.

Double resonance analysis

Routines for fitting double resonance data

pyspectools.doubleresonance.fit_dr(dataframe, col='Average', baseline=True, guess=None)[source]

Function for fitting double resonance data.

dataframe - pandas dataframe containing

col - str denoting which column to use for fitting. baseline - boolean denoting whether a linear baseline is fit guess - dict for fitting parameters; this is passed into

the fit directly and so must match the lmfit convention.

pyspectools.doubleresonance.init_dr_model(baseline=False, guess=None)[source]

Function to serialize a Model object for DR fits. Defaults to a Gaussian line shape, but the option to include a linear offset is available.

Additionally, if a guess is provided in the lmfit convention then it will be incorporated.

baseline - boolean indicating if linear offset is included guess - nested dict with keys corresponding to parameter name

and values corresponding to dicts with key/value indicating the parameter value, range, and constraints

pyspectools.doubleresonance.parse_data(filepath)[source]

Function to read in a DR file. When there are multiple columns present in the file, this is interpreted as multiple channels being used to monitor during the DR experiment. In this case, we do the analysis on the co-average of these columns.

pyspectools.doubleresonance.peak_detect(dataframe, col='Average', interpolate=True)[source]

Routine for peak detection to provide an initial guess for the center frequency.

The algorithm assumes that the ten smallest intensities corresponds to where the depletion approximately is.

By default, a cubic spline is performed on the intensities so that a finer grid of points gives a better determination of the center frequency.

Figure factory module

pyspectools.figurefactory.add_image(axis, filepath, zoom=0.15, position=[0.0, 0.0])[source]

Function to add an image annotation to a specified axis.

Takes the matplotlib axis and filepath to the image as input, and optional arguments for the scaling (zoom) and position of the image in axis units.

pyspectools.figurefactory.calc_vibE(quant_nums, vibrations)[source]

Function that will calculate a 1D array of vibrational energies, based on a nested list of quantum numbers and a list of vibrational frequencies.

pyspectools.figurefactory.cfa_cmap(nsteps=100)[source]

Generate a Matplotlib colormap with the CfA branding colors. Performs a linear interpolation from the CfA red to the so-called CfA violet.

Parameters

- int (nsteps) – Number of steps to take in the interpolation; i.e. number of colors to return

Returns

Return type

LinearSegementedColormap instance

pyspectools.figurefactory.color_iterator(n, **kwargs)[source]

Simple generator that will yield a different color each time. This is primarily designed when multiple plot types are expected.

Input arguements: n - number of plots Optional kwargs are passed into generate_colors

pyspectools.figurefactory.define_layout(xlabel='', ylabel='')[source]

Function for generating a layout for plotly. Some degree of customization is provided, but generally sticking with not having to fuss around with plots.

Input arguments: x/ylabel - str for what the x and y labels are to be

pyspectools.figurefactory.dr_network_diagram(connections, **kwargs)[source]

Use NetworkX to create a graph with nodes corresponding to cavity frequencies, and vertices as DR connections. The color map can be specified by passing kwargs. :param connections: list of 2-tuples corresponding to pairs of connections :return

pyspectools.figurefactory.format_ticklabels(axis)[source]
pyspectools.figurefactory.generate_colors(n, cmap=<matplotlib.colors.LinearSegmentedColormap object>, hex=True)[source]

Generate a linearly spaced color series using a colormap from Matplotlib. The colors can be returned as either RGB values or as hex-codes using the hex flag.

Parameters
  • n (int) – Number of colours to generate

  • cmap (str or matplotlib.colors.LinearSegementedColomap, optional) – Specified colormap to interpolate. If a str is provided, the function will try to look for it in the available matplotlib colormaps.

  • hex (bool, optional) – If True, hex colors are returned. Otherwise, RGB values.

Returns

List of hex or RGB codes

Return type

colors

pyspectools.figurefactory.generate_x_coord(quant_nums, energies)[source]

Function to generate the x coordinate for plotting based on the quantum numbers specified.

pyspectools.figurefactory.init_bokeh_figure(yml_path=None, **kwargs)[source]

Initialize a Bokeh Figure object. This code is fairly low level, and is used simply as a matter of convenience for supplying a default theme even without the user explicitly providing one.

Kwargs are passed into the creation of the figure, and so further customization like title, axis limits, etc. should be supplied this way.

Parameters
  • yml_path (str or None, optional) – If None, uses the PySpecTools default bokeh styling. If a str is provided then it should correspond to the filepath to a YAML file.

  • kwargs – Kwargs are passed into the creation of the Figure object

Returns

Return type

Bokeh Figure object

pyspectools.figurefactory.init_plotly_subplot(nrows, ncols, **kwargs)[source]

Initialize a Plotly subplot. :param nrows: number of rows for the subplot :param ncols: number of columns for the subplot :return: plotly FigureWidget object

pyspectools.figurefactory.make_elevel_plot(cat_dict, axis, color, maxE, alpha=1.0)[source]

make_elevel_plot is used to create energy level diagrams with Matplotlib axis objects. This is considered slightly lower level: you should call the higher level wrapper functions like vib_energy_diagram instead!

The function will loop over every transition that has been categorized/binned into an x-axis index, and sub- sequently plot each x-bin individually.

The input arguments are:

cat_dict: dict-like with keys as the x-axis values, and the items are dictionaries containing the energy and quantum number configuration.

pyspectools.figurefactory.make_pes(x, energies, width=5)[source]

Function to create a smooth PES, where stationary points are connected.

Basically makes a linearly spaced x array which pads x-axis density to create the horizontal line for the stationary points

Optional arguments are how many x-points to pad with on either side.

pyspectools.figurefactory.no_scientific(axis)[source]
pyspectools.figurefactory.overlay_dr_spectrum(dataframe, progressions, freq_col='Frequency', int_col='Intensity', **kwargs)[source]
pyspectools.figurefactory.pandas_bokeh_table(dataframe, html=False, **kwargs)[source]

Convert a Pandas DataFrame to a Bokeh DataTable object. Columns will be automatically generated based on the DataFrame keys. The html flag can be used to specify whether or not an HTML representation is returned.

Additional kwargs are passed into the file_html function, and is only used when html is True.

Parameters
  • dataframe (pandas dataframe) – Pandas DataFrame to convert into a DataTable object

  • html (bool, optional) – If True, function will return a string of the HTML code for embedding

  • kwargs – Additional kwargs are passed into the HTML conversion

Returns

Return type

DataTable object if html is False, otherwise str

pyspectools.figurefactory.plot_assignment(spec_df, assignments_df, col='Intensity')[source]

Function for plotting spectra with assignments. The assumption is that the assignments routines are ran prior too this, and so the function simply takes a dataframe of chosen molecules and plots them alongside the experimental spectrum, color coded by the molecule

Input argument: spec_df - dataframe holding the experimental data assignments_df - dataframe produced from running assignments

pyspectools.figurefactory.plot_bar_assignments(species_df, color='#fc8d62')[source]

Function to generate a bar plot trace for a chemical species. These plots will be placed in the second y axis!

Input arguments: species_df - a slice of an assignments dataframe, containing only one unique species Optional argument color is a hex code color; if nothing is given it just defaults to whatever

pyspectools.figurefactory.plot_catchirp(chirpdf, catfiles=None)[source]

Function to perform interactive analysis with a chirp spectrum, as well as any reference .cat files you may want to provide. This is not designed to replace SPECData analysis, but simply to perform some interactive viewing of the data.

The argument catfiles is supplied as a dictionary; where the keys are the names of the species, and the items are the paths to the .cat files

pyspectools.figurefactory.plot_column(dataframe, col, name=None, color=None, layout=None)[source]

A low level function for plotting a specific column of data in a pandas dataframe. This will assume that there is a column named “Frequency” in the dataframe.

If a layout is not supplied, then the function will return a Plotly scatter object to be combined with other data. If a layout is given, then the data will be plot up directly.

Input arguments: dataframe - pandas dataframe object col - str specifying the column used to plot layout - optional argument; if specified a plotly plot will be produced.

pyspectools.figurefactory.plot_df(dataframe, cols=None, **kwargs)[source]

Function that wraps around the lower level function plot_column. Will plot every column in a dataframe against the Frequency, unless specific column names are provided.

Input arguments: dataframe - pandas dataframe object, with every column as intensity except “Frequency” cols - NoneType or tuple-like: if None, every column is plotted. Alternatively, an iterable is provided to specify which columns are plotted. Optional arguments are passed into define_layout, which will define the axis labels, or into the color map generation

pyspectools.figurefactory.save_plot(fig, filename, js=True)[source]

Method for exporting a plotly figure with interactivity. This method does inject the plotly.js code by default, and so will result in relatively large files. Use save_html instead.

pyspectools.figurefactory.stacked_plot(dataframe, frequencies, freq_range=0.002, freq_col='Frequency', int_col='Intensity')[source]

Create a Loomis-Wood style plot via a list of frequencies, and a broadband spectrum. The keyword freq_range will use a percentage of the center frequency to extend the frequency range that gets plotted. :param dataframe: pandas DataFrame :param frequencies: iterable with float frequencies to use as centers :param freq_range: decimal percentage to specify the range to plot :param freq_col: str name for the column to use as the frequency axis :param int_col: str name for the column to use as the intensity axis :return fig: Plotly FigureWidget with the subplots

pyspectools.figurefactory.strip_spines(spines, axis)[source]
pyspectools.figurefactory.vib_energy_diagram(quant_nums, vibrations, maxV=2, maxE=3000.0, useFull=True, image=None, imagesize=0.1)[source]

Function that will generate a vibrational energy diagram.

This function wraps the make_elevel_plot function!

Input arguments are

quant_nums: A 2D numpy array of quantum numbers, where each row is a single configuration. vibrations: A list of vibrational frequencies. maxV: The maximum quanta for considering predicted frequencies. maxE: Maximum energy for plotting. useFull: Boolean for flagging whether predict frequencies are plotted. image: String-like for specifying path to an image.

Fitting routines

Wrapper functions for lmfit.

Each module of PySpectools should use these functions when fitting is required, rather than rewrite for each purpose.

class pyspectools.fitting.BJModel(**kwargs)[source]

Bases: pyspectools.fitting.PySpecModel

Model for fitting prolate/linear molecules.

class pyspectools.fitting.FirstDerivLorentzian_Model(**kwargs)[source]

Bases: pyspectools.fitting.PySpecModel

Child class of the PySpecModel, which in itself inherits from the lmfit Models class. Gives the first derivative Lorentzian line shape profile for fitting.

class pyspectools.fitting.PairGaussianModel(**kwargs)[source]

Bases: pyspectools.fitting.PySpecModel

fit_pair(x, y, verbose=False)[source]
class pyspectools.fitting.PySpecModel(function, **kwargs)[source]

Bases: lmfit.model.Model

class pyspectools.fitting.SecDerivLorentzian_Model(**kwargs)[source]

Bases: pyspectools.fitting.PySpecModel

Child class of the PySpecModel, which in itself inherits from the lmfit Models class. Gives the second derivative Lorentzian line shape profile for fitting.

pyspectools.fitting.baseline_als(y, lam=10000.0, p=0.01, niter=10)[source]

Function for performing an iterative baseline fitting using the asymmetric least squares algorithm.

This refers to the paper: “Baseline Correction with Asymmetric Least Squares Smoothing” by Eilers and Boelens (2005).

The code is taken from a Stack Overflow question: https://stackoverflow.com/a/29185844

According to the paper, the tested values are: 0.001 <= p <= 0.1 for positive peaks 1e2 <= lam <= 1e9

ynumpy 1D array

Data used to fit the baseline

lamfloat

Tuning factor for penalty function that offsets the difference cost function

pfloat

Weighting factor for the cost function

znumpy 1D array

Array containing the baseline values

pyspectools.fitting.calc_harmonic_transition(J, B, D=0.0)[source]

Calculate the transition frequency for a given upper state J, B, and D.

J - quantum number B - rotational constant in MHz D - centrifugal distortion constant in MHz

transition frequency in MHz

pyspectools.fitting.harmonic_fitter(progressions, J_thres=0.01)[source]

Function that will sequentially fit every progression with a simple harmonic model defined by B and D. The “B” value here actually corresponds to B+C for a near-prolate, or 2B for a prolate top.

There are a number of filters applied in order to minimize calculations that won’t be meaningful - these parameters may have to be tuned for different test cases.

Because the model is not actually quantized, J is represented as a float. To our advantage, this will actually separate real (molecular) progressions from fake news; at least half of the J values must be close to being an integer for us to consider fitting.

progressions - iterable containing arrays of progressions J_thres - optional argument corresponding to how close a

value must be to an integer

pandas dataframe containing the fit results; columns are B, D, fit RMS, and pairs of columns corresponding to the fitted frequency and approximate J value.

pyspectools.fitting.quant_check(value, threshold=0.001)[source]

Function that will check if a value is close to an integer to the absolute value of the threshold.

value - float for number to check threshold - float determining whether value is

close enough to being integer

True if the value is close enough to being an integer, False otherwise.

pyspectools.fitting.rotor_energy(J, B, D=0.0)[source]

Expression for a linear/prolate top with centrifugal distortion.

J - integer quantum number B - rotational constant in MHz D - CD term in MHz

state energy in MHz

Cavity FTMW module

class pyspectools.ftmw_analysis.AssayBatch(data, exp_id, freq_col='Frequency', int_col='Intensity')[source]

Bases: object

calc_scan_SNR(peak_int, noise_array)[source]

Calculate the signal-to-noise ratio of a peak for a given reference noise intensity array and peak intensity.

dipole_analysis(batch_path, thres=0.5, dipoles=[1.0, 0.01, 0.1, 1.0, 3.0, 5.0], snr_thres=5.0)[source]

Method for determining the optimal dipole moment to use for each frequency in a given exported batch of dipole tests.

In addition to returning a pandas dataframe, it is also stored as the object attribute dipole_df.

batch_path - filepath to the exported XY file from a QtFTM batch thres - threshold in absolute intensity for peak detection (in Volts) dipoles - list of dipole moments used in the screening snr_thres - threshold in signal-to-noise for line detection

optimal_df - pandas dataframe containing the optimal dipole moments

find_progressions(**kwargs)[source]

Uses the dipole assay data to look for harmonic progression.

Kwargs are passed into the affinity propagation clustering; usually this means “preference” should be set to tune the number of clusters.

cluster_dict - dictionary containing all of the clustered

progressions

classmethod from_csv(filepath, exp_id)[source]

Create an AssayBatch session by providing a filepath to a file containing the frequency and intensity information, as well as the experiment ID from which it was based.

filepath - path to a CSV file with Frequency/Intensity

columns

exp_id - experiment ID; typically the chirp experiment number

generate_bruteforce_dr(nshots=10, dr_channel=3)[source]

Brute force double resonance test on every single frequency observed in the initial dipole test.

This method will perform DR measurements on sequentially weaker lines, if the dipole_df is sorted by SNR.

Optionally, the

generate_magnet_test(dataframe=None, cal=False, nshots=50, **kwargs)[source]

Generate an FT batch file for performing magnetic tests.

dataframe - dataframe used for the frequency information.

By default the dipole dataframe will be used.

cal - bool denoting whether a calibration line is used.

A user can provide it in kwargs, or use the default which is the first line in the dataframe (strongest if sorted by intensity)

nshots - optional int specifying number of shots for each

line, or if SNR is in the dataframe, the number of shots for the strongest line.

kwargs - passed into the calibration settings, which are

cal_freq, cal_rate, and cal_shots

generate_progression_test(nshots=50, dr_channel=3)[source]

Take the dipole moment dataframe and generate a DR batch. If possible, we will instead use the progressions predicted by the cluster model.

classmethod load_session(filepath)[source]

Loads a previously saved AssayBatch session.

plot_scan(scan_number=None)[source]

Quick method for plotting up a strip to highlight a particular scan in a batch.

scan_number - float corresponding to the scan

save_session(filepath=None)[source]

Method to save the current assay analysis session to disk.

The data can be reloaded using the AssayBatch.load_session class method.

filepath - path to save the data to. By default, the path will

be the experiment ID.

static_plot(scan_number, dataframe=None)[source]

Produce a static plot with matplotlib of a particular scan from a batch.

Saves the plot to ./assays/plots/

By default, the full dataframe will be used for the plotting. Other dataframes (such as from other assays) can also be used.

scan_number - float corresponding to the scan of interest dataframe - optional arg; pandas dataframe with Scan/Intensity

class pyspectools.ftmw_analysis.Batch(assay: str, id: int, machine: str, date: datetime.datetime, scans: List = <factory>, filter: List = <factory>, exp: float = 0.0, zeropad: bool = False, window: str = '')[source]

Bases: object

assay: str
create_dr_network(scans)[source]

Take a list of scans, and generate a NetworkX Graph object for analysis and plotting. :param scans: list of scan IDs to connect :return fig: Plotly FigureWidget object

date: datetime.datetime
exp: float = 0.0
filter: List
find_optimum_scans(thres=0.8)[source]
Parameters

thres

Returns

find_scan(id)[source]
classmethod from_pickle(filepath)[source]

Method to create a Scan object from a previously pickled Scan. :param filepath: path to the Scan pickle :return: instance of the Scan object

classmethod from_qtftm(filepath, assay, machine)[source]

Create a Batch object from a QtFTM scan file. :param filepath: :param assay: :param machine: :return:

classmethod from_remote(root_path, batch_id, assay, machine, ssh_obj=None)[source]

Create a Batch object by retrieving a QtFTM batch file from a remote location. The user must provide a path to the root directory of the batch type, e.g. /home/data/QtFTM/batch/, and the corresponding batch type ID. Additionally, the type of batch must be specified to determine the type of analysis required.

Optionally, the user can provide a reference to a RemoteClient object from pyspectools.routines. If none is provided, a RemoteClient object will be created with public key authentication (if available), otherwise the user will be queried for a hostname, username, and password.

Keep in mind this method can be slow as every scan is downloaded. I recommend creating this once, then saving a local copy for subsequent analysis. :param root_path: str path to the batch type root directory :param batch_id: int or str value for the batch number :param assay: str the batch type :param machine: str reference the machine used for the batch :param ssh_obj: RemoteClient object :return:

get_scans(root_path, ids)[source]

Function to create Scan objects for all of the scans in a QtFTM batch. :param root_path: str scans root path :param ids: list scan ids :param src: str optional specifying whether a remote or local path is used

id: int
interactive_dr_batch()[source]

Create an interactive widget slider with a Plotly figure. The batch will be split up into “subbatches” by the cavity frequency and whether or not the scan IDs are consecutive. :return vbox: VBox object with the Plotly figure and slider objects

machine: str
plot_scans()[source]

Create a plotly figure of all of the Scans within a Batch. :return:

process_dr(significance=16.0)[source]

Function to batch process all of the DR measurements. :param global_depletion: float between 0. and 1. specifying the expected depletion for any line

without a specific expected value.

Parameters

depletion_dict – dict with keys corresponding to cavity frequencies, and values the expected depletion value between 0. and 1.

Return dr_dict

dict with keys corresponding to cavity frequency, with each value a dict of the DR frequencies, scan IDs and Scan objects.

reprocess_fft(**kwargs)[source]

Reprocess all of the FIDs with specified settings. The default values are taken from the Batch attributes, and kwargs provided will override the defaults. :param kwargs:

scans: List
search_frequency(frequency, tol=0.001)[source]

Search the Batch scans for a particular frequency, and return any scans that lie within the tolerance window :param frequency: float specifying frequency to search :param tol: float decimal percentage to use for the search tolerance :return new_batch: a new Batch object with selected scans

split_progression_batch()[source]

Split up a DR batch into individual progressions based on the cavity frequency and whether or not the scan IDs are consecutive. :return progressions: dict with keys corresponding to progression index and values are lists of Scans

to_pickle(filepath=None, **kwargs)[source]

Pickles the Batch object with the joblib wrapper implemented in routines. :param filepath: optional argument to pickle to. Defaults to the {assay}-{id}.pkl :param kwargs: additional settings for the pickle operation

window: str = ''
zeropad: bool = False
class pyspectools.ftmw_analysis.BlackChirpFid(xy_data: <built-in function array>, header: Dict = <factory>)[source]

Bases: object

determine_frequencies()[source]

Calculate the frequency bins for the FFT.

Returns

Array containing the frequency bins (x values)

Return type

frequency - numpy 1D array

classmethod from_binary(filepath)[source]

Create a BlackChirp FID object from a binary BlackChirp FID file.

Parameters

- str (filepath) – Filepath to the BlackChirp .fid file

Returns

Return type

BlackChirpFid object

header: Dict
perform_fft(start=0, stop=- 1, window='boxcar', f_min=0.0, f_max=30000.0)[source]

Perform an FFT on the current FID to get the frequency domain spectrum. All of the arguments are optional, and provide control over how the FFT is performed, as well as post-processing parameters like window functions and zero-padding.

This is based on the FFT code by Kyle Crabtree, with modifications to fit this dataclass.

Parameters
  • - int, optional (zpf) – Starting index for the FID array to perform the FFT

  • - int, optional – End index for the FID array to perform the FFT

  • - int, optional – Pad the FID with zeros to nth nearest power of 2

  • - str (window) – Specify the window function used to process the FID. Defaults to boxcar, which is effectively no filtering. The names of the window functions available can be found at: https://docs.scipy.org/doc/scipy/reference/signal.windows.html

  • - float (f_max) – Specify the minimum frequency in the spectrum; everything below this value is set to zero

  • - float – Specify the maximum frequency in the spectrum; everything above this value is set to zero

to_pickle(filepath, **kwargs)[source]

Save the Blackchirp FID to a pickle file.

Parameters
  • - str (filepath) – Filepath to save the FID to

  • - dict-like (kwargs) – Additional keyword arguments that are passed to the pickle function.

xy_data: np.array
class pyspectools.ftmw_analysis.BlackchirpExperiment(exp_id: int, fid_start: int = 0, fid_end: int = -1, ft_min: float = 0.0, ft_max: float = 40000.0, ft_filter: str = 'boxcar', freq_offset: float = 0.0, fids: List = <factory>, header: Dict = <factory>)[source]

Bases: object

exp_id: int
fid_end: int = -1
fid_start: int = 0
fids: List
freq_offset: float = 0.0
classmethod from_dir(filepath)[source]
ft_filter: str = 'boxcar'
ft_max: float = 40000.0
ft_min: float = 0.0
header: Dict
process_ffts(weighting=None)[source]

Batch perform FFTs on all of the FIDs. The end result is a Pandas DataFrame with the Frequency and Intensity data, where the intensity is just the weighted co-average of all the FFTs. By default, every FID is equally weighted. :param weighting:

class pyspectools.ftmw_analysis.Scan(id: int, machine: str, fid: numpy.array, date: datetime.datetime, shots: int = 0, cavity_voltage: int = 0, cavity_atten: int = 0, cavity_frequency: float = 0.0, dr_frequency: float = 0.0, dr_power: int = 0, fid_points: int = 0, fid_spacing: float = 0.0, discharge: bool = False, magnet: bool = False, gases: Dict = <factory>, filter: List = <factory>, exp: float = 0.0, zeropad: bool = False, window: str = '')[source]

Bases: object

DataClass for a Scan. Holds all of the relevant information that describes a FT scan, such as the ID, what machine it was collected on, and the experimental settings.

Has a few class methods that will make look ups easily such as the date the scan was collected and the gases used.

add_frequency(other)[source]

Method to add another Scan from the current in the frequency domain. :param other: Scan object to add with :return: A new Scan object with the co-added spectrum

average(others)[source]

Dunder method to co-average two or more Scans in the time domain. :param other: Scan object, or tuple/list :return: A new Scan object with the co-added FID

calc_snr(noise=None, thres=0.6)[source]
cavity_atten: int = 0
cavity_frequency: float = 0.0
cavity_voltage: int = 0
date: datetime.datetime
discharge: bool = False
dr_frequency: float = 0.0
dr_power: int = 0
exp: float = 0.0
fid: np.array
fid_points: int = 0
fid_spacing: float = 0.0
filter: List
fit_cavity(plot=True, verbose=False)[source]

Perform a fit to the cavity spectrum. Uses a paired Gaussian model that minimizes the number of fitting parameters. :param plot: bool specify whether a Plotly figure is made :return: Model Fit result

classmethod from_dict(data_dict)[source]

Function to initialize a Scan object from a dictionary of FT scan data collected from parse_scan. :param data_dict: dict containing parsed data from FT :return: Scan object

classmethod from_pickle(filepath)[source]

Method to create a Scan object from a previously pickled Scan. :param filepath: path to the Scan pickle :return: instance of the Scan object

classmethod from_qtftm(filepath)[source]

Method to initialize a Scan object from a FT scan file. Will load the lines into memory and parse the data into a dictionary, which then gets passed into a Scan object. :param filepath: str path to FID file :return: Scan object

classmethod from_remote(remote_path, ssh_obj=None)[source]

Method to initialize a Scan object from a remote server. Has the option to pass an instance of a paramiko SSHClient, which would be useful in a Batch. If none is supplied, an instance will be created.

Parameters
  • remote_path – str remote path to the file

  • ssh_obj – optional argument to supply a paramiko SSHClient object

Returns

Scan object from remote QtFTM file

gases: Dict
get_line_roi()[source]
id: int
is_depleted(ref, roi=None, depletion=None)[source]

Function for determining if the signal in this Scan is less than that of another scan. This is done by a simple comparison of the average of 10 largest intensities in the two spectra. If the current scan is less intense than the reference by the expected depletion percentage, then it is “depleted”.

This function can be used to determine if a scan if depleted in DR/magnet/discharge assays.

TODO - implement a chi squared test of sorts to determine if a

depletion is statistically significant

Parameters
  • ref – second Scan object for comparison

  • depletion – percentage of depletion expected of the reference

Returns

bool - True if signal in this Scan is less intense than the reference

machine: str
magnet: bool = False
process_fid(**kwargs)[source]

Perform an FFT on the FID to yield the frequency domain spectrum. Kwargs are passed into the FID processing, which will override the Scan attributes. :param kwargs: Optional keyword arguments for processing the FID

scatter_trace()[source]

Create a Plotly Scattergl trace. Called by the Batch function, although performance-wise it takes forever to plot up ~3000 scans. :return trace: Scattergl object

shots: int = 0
subtract_frequency(other)[source]

Method to subtract another Scan from the current in the frequency domain. :param other: Scan object to subtract with :return: A new Scan object with the subtracted spectrum

to_file(filepath, format='yaml')[source]

Method to dump data to YAML format. Extensions are automatically decided, but can also be supplied.

:param filepath - str path to yaml file :param format - str denoting the syntax used for dumping. Defaults to YAML.

to_pickle(filepath=None, **kwargs)[source]

Pickles the Scan object with the joblib wrapper implemented in routines. :param filepath: optional argument to pickle to. Defaults to the id.pkl :param kwargs: additional settings for the pickle operation

window: str = ''
within_time(date_range)[source]

Function for determining of the scan was taken between a specified date range in month/day/year, in the format 04/09/08 for April 9th, 2008. :param date_range: list containing the beginning and end date strings :return: bool - True if within range, False otherwise

zeropad: bool = False
pyspectools.ftmw_analysis.apply_butter_filter(data, low, high, rate, order=1)[source]

A modified Butterworth bandpass filter, adapted from the Scipy cookbook.

The argument data supplies the FID, which then uses the scipy signal processing function to apply the digital filter, and returns the filtered FID.

See the butter_bandpass function for additional arguments.

pyspectools.ftmw_analysis.butter_bandpass(low, high, rate, order=1)[source]

A modified version of the Butterworth bandpass filter described here, adapted for use with the FID signal. http://scipy-cookbook.readthedocs.io/items/ButterworthBandpass.html The arguments are:

:param low The low frequency cut-off, given in kHz. :param high The high frequency cut-off, given in kHz. :param rate The sampling rate, given in Hz. From the FIDs, this means that

the inverse of the FID spacing is used.

:return bandpass window

pyspectools.ftmw_analysis.calculate_integration_times(intensity, nshots=50)[source]

Method for calculating the expected integration time in shot counts based on the intensity; either theoretical line strengths or SNR.

intensity - array of intensity metric; e.g. SNR nshots - optional int number of shots used for the strongest line

shot_counts - array of shot counts for each frequency

pyspectools.ftmw_analysis.categorize_frequencies(frequencies, nshots=50, intensities=None, power=None, attn_list=None, dipole=None, attn=None, magnet=False, dr=False, discharge=False)[source]

Function that will format an FT batch file to perform categorization tests, with some flexibility on how certain tests are performed.

pyspectools.ftmw_analysis.center_cavity(dataframe, thres=0.3, verbose=True)[source]

Finds the center frequency of a Doppler pair in cavity FTM measurements and provides a column of offset frequencies.

Sometimes the peak finding threshold has to be tweaked to get the center frequency correctly.

pyspectools.ftmw_analysis.fid2fft(fid, rate, frequencies, **kwargs)[source]

Process an FID by performing an FFT to yield the frequency domain information. Kwargs are passed as additional processing options, and are implemented as some case statements to ensure the settings are valid (e.g. conforms to sampling rate, etc.)

Parameters
  • fid – np.array corresponding to the FID intensity

  • rate – sampling rate in Hz

  • frequencies – np.array corresponding to the frequency bins

  • kwargs

    signal processing options: delay - delays the FID processing by setting the start

    of the FID to zero

    zeropad - Toggles whether or not the number of sampled

    points is doubled to get artificially higher resolution in the FFT

    window - Various window functions provided by scipy.signal exp - Specifies an exponential filter filter - 2-tuple specifying the frequency cutoffs for a

    band pass filter

Returns

freq_df - pandas dataframe with the FFT spectrum

pyspectools.ftmw_analysis.generate_ftb_line(frequency, shots, **kwargs)[source]

Function that generates an FTB file for a list of frequencies, plus categorization tests.

kwargs are passed as additional options for the ftb batch. Keywords are:

magnet: bool dipole: float atten: int skiptune: bool drfreq: float drpower: int cal

Parameters
  • frequency – float for frequency in MHz

  • shots – int number of shots to integrate for

Return ftbline

str

pyspectools.ftmw_analysis.neu_categorize_frequencies(frequencies, intensities=None, nshots=50, **kwargs)[source]

Routine to generate an FTB batch file for performing a series of tests on frequencies.

pyspectools.ftmw_analysis.parse_batch(filecontents)[source]
pyspectools.ftmw_analysis.parse_scan(filecontents)[source]

Function for extracting the FID data from an FT scan. The data is returned as a dictionary, which can be used to initialize a Scan object. :param filecontents: list of lines from an FID file :return: dict containing parsed data from FID

pyspectools.ftmw_analysis.parse_specdata(filename)[source]
pyspectools.ftmw_analysis.parse_spectrum(filename, threshold=20.0)[source]

Function to read in a blackchirp or QtFTM spectrum from file

pyspectools.ftmw_analysis.perform_fft(fid, spacing, start=0, stop=- 1, window='boxcar')[source]

Perform an FFT on an FID to get the frequency domain spectrum. All of the arguments are optional, and provide control over how the FFT is performed, as well as post-processing parameters like window functions and zero-padding.

This is based on the FFT code by Kyle Crabtree, with modifications to fit this dataclass.

Parameters
  • - Numpy 1D array (fid) – Array holding the values of the FID

  • - float (spacing) – Time spacing between FID points in microseconds

  • - int, optional (zpf) – Starting index for the FID array to perform the FFT

  • - int, optional – End index for the FID array to perform the FFT

  • - int, optional – Pad the FID with zeros to nth nearest power of 2

  • - str (window) – Specify the window function used to process the FID. Defaults to boxcar, which is effectively no filtering. The names of the window functions available can be found at: https://docs.scipy.org/doc/scipy/reference/signal.windows.html

pyspectools.ftmw_analysis.predict_prolate_series(progressions, J_thres=0.1)[source]

Spectroscopic lineshapes module

pyspectools.lineshapes.fast_multi_gaussian(x: numpy.ndarray, A: numpy.ndarray, x0: numpy.ndarray, w: numpy.ndarray)[source]

Fast, parallel implementation of a mixture of Gaussian lineshapes. Uses the gaussian function defined in this module, which itself is also JIT’d, and uses parallel loops to evaluate multiple Gaussians.

The result is a NumPy 2D array of shape N x D, where N is the length of the frequency array, and D is the number of Gaussians.

The inputs are expected to all be NumPy arrays, where A, x0, and w all equal in length and contain parameters for each respective Gaussian.

With a 200,000 length frequency array and about 70 Gaussians, this code takes ~70 ms to compute; about four times faster than the unJIT’d version.

Parameters
  • x (np.ndarray) – [description]

  • A (np.ndarray) – [description]

  • x0 (np.ndarray) – [description]

  • w (np.ndarray) – [description]

Returns

[description]

Return type

[type]

pyspectools.lineshapes.first_deriv_lorentzian(x, x0, gamma, I)[source]

Function to evaluate the first derivative of a Lorentzian lineshape function.

Parameters
  • x (Numpy 1D array) – Array of floats corresponding to the x values to evaluate on

  • x0 (float) – Center for the distribution

  • gamma (float) – Width of the distribution

  • I (float) – Height of the distribution

Returns

Values of the Lorentzian distribution

Return type

Numpy 1D array

pyspectools.lineshapes.gaussian(x: numpy.ndarray, A=1.0, x0=0.0, w=1.0)[source]

Vectorized implementation of a single Gaussian lineshape. For a given array of x values, we compute the corresponding amplitude of a Gaussian for a set of amplitude, center, and widths.

Uses JIT compilation with Numba, and should be reasonably fast.

Parameters
  • x (np.ndarray) – NumPy 1D array containing x values to evaluate over.

  • A (float) – Scaling of the Gaussian; actually corresponds to the area.

  • x0 (float) – Center of the Gaussian

  • w (float) – Width of the Gaussian.

Returns

Array of amplitude values of the specified Gaussian

Return type

NumPy 1D array

pyspectools.lineshapes.lorentzian(x, x0, gamma, I)[source]

Function to evaluate a Lorentzian lineshape function.

Parameters
  • x (Numpy 1D array) – Array of floats corresponding to the x values to evaluate on

  • x0 (float) – Center for the distribution

  • gamma (float) – Width of the distribution

  • I (float) – Height of the distribution

Returns

Values of the Lorentzian distribution

Return type

Numpy 1D array

pyspectools.lineshapes.pair_gaussian(x: numpy.ndarray, A1: float, A2: float, x0: float, w: float, xsep: float)[source]

Paired Gaussian lineshape. The function allows for the amplitudes to be floated, however the two Gaussians are locked in width and center frequency.

Parameters
  • x (np.ndarray) – [description]

  • A2 (A1,) – Amplitude of the two Gaussians

  • x0 (float) – Centroid of the two Gaussians

  • w (float) – Width of the two Gaussians

  • xsep (float) – Distance from the centroid and a Gaussian center

Returns

Array of amplitude values of the pair of Gaussians

Return type

NumPy 1D array

pyspectools.lineshapes.sec_deriv_lorentzian(x, x0, gamma, I)[source]

Function to evaluate the second derivative of a Lorentzian lineshape function. This was evaluated analytically with SymPy by differentiation of the Lorentzian expression used for the lorentzian function in this module.

Parameters
  • x (Numpy 1D array) – Array of floats corresponding to the x values to evaluate on

  • x0 (float) – Center for the distribution

  • gamma (float) – Width of the distribution

  • I (float) – Height of the distribution

Returns

Values of the Lorentzian distribution

Return type

Numpy 1D array

Standard parsers module

pyspectools.parsers.parse_ascii(filename, delimiter='\t', names=None, header=None, skiprows=0)[source]

Generic ASCII parser wrapping the pandas read_csv function. :param filename: :param delimiter: :param names: :param header: :param skiprows:

pyspectools.parsers.parse_blackchirp(dir_path)[source]

Function for reading in a Blackchirp experiment. The required input should point to the directory containing the Blackchirp files with the correct extensions: .hdr, .tdt, and .fid

Parameters

- str (dir_path) – Filepath pointing to the directory containing the Blackchirp experiment files.

pyspectools.parsers.parse_cat(simulation_path, low_freq=0.0, high_freq=inf, threshold=- inf)[source]

Parses a simulation output, and filters the frequency and intensity to give a specific set of lines.

The only argument that is required is the path to the simulation output. Others are optional, and will default to effectively not filter.

The quantum numbers are read in assuming hyperfine structure, and thus might not be accurate descriptions of what they actually are.

pyspectools.parsers.parse_fit(filepath)[source]

Function to parse the output of an SPFIT .fit file. This version of the code is barebones compared to the previous iteration, which provides more feedback. This version simply returns a dictionary containing the obs - calc for each line, the fitted parameters, and the microwave RMS.

Parameters

filepath (str) – Filepath to the .fit file to parse.

Returns

fit_dict – Dictionary containing the parsed data.

Return type

dict

pyspectools.parsers.parse_lin(filename)[source]

Function to read in a line file, formatted in the SPFIT convention.

pyspectools.parsers.parse_spectrum(filename, threshold=20.0)[source]

Function to read in a blackchirp or QtFTM spectrum from file

pyspectools.parsers.read_binary_fid(filepath)[source]

Read in a binary Blackchirp FID file. This is based on the original code by Kyle Crabtree, with some minor perfomance improvements by Kelvin Lee. The only difference is most of the for loops for reading the points have been replaced by numpy broadcasts.

Parameters

- str (filepath) – Filepath to the Blackchirp .fid file

Returns

  • param_dict - dict – Contains header information about the FID, such as the number of shots, point spacing, etc.

  • xy_data - 2-tuple of numpy 1D array – Contains two columns; xy_data[0] is the time data in microseconds, and xy_data[1] is the signal.

  • raw_data - numpy 1D array – Contains the raw, uncorrected ADC sums. The signal data is converted from this by scaling it with the multiplication factor v_mult.

PyPickett module

class pyspectools.pypickett.AutoFitSession(filename: str, n_numbers: int, frequencies: List = <factory>, uncertainties: List = <factory>, centers: List = <factory>, widths: List = <factory>, deltas: List = <factory>, j: List = <factory>, method: str = 'mc', rms_target: float = 1.0, rms: float = 1000000000.0, nfit: int = 0, niter: int = 10000, nprocesses: int = 1, verbose: int = 0, debug: bool = False, clean: bool = True)[source]

Bases: object

centers: List
clean: bool = True
debug: bool = False
deltas: List
filename: str
filter(nlines=1)[source]

Reads in all of the YAML parsed fits, and reduces the number of possible fits a person has to look through.

Parameters

nlines (int) – Integer value for the minimum number of lines seen in the observed - calc. parse

Returns

viable – Dictionary with indexes corresponding to the fit number, and values are the parsed fit dictionaries

Return type

dict

frequencies: List
classmethod from_pkl(filepath)[source]

Function to load a previously saved Pickle instance of AutoFitSession.

TODO: write a check to make sure we’re reading in an AutoFitSession pickle! :param filepath: Filepath to the pickle file to load. :type filepath: str

Returns

Return type

Loaded

classmethod from_yml(filepath)[source]

Class method to read the settings for an AutoFitSession via YAML file. :param filepath: Filepath to the YAML settings file :type filepath: str

Returns

Return type

AutoFitSession object

j: List
method: str = 'mc'
n_numbers: int
nfit: int = 0
niter: int = 10000
nprocesses: int = 1
rms: float = 1000000000.0
rms_target: float = 1.0
run(niter=None, nprocesses=None, headless=True, method='mc')[source]

Run the search for assignments. The function wraps a private method, and is parallelized with a joblib Pool. :param niter: Number of iterations. If None, uses the class attribute, otherwise the user specified value. :type niter: int or None, optional :param nprocesses: Number of parallel jobs to break the task into. If None, uses the class attribute. :type nprocesses: int or None, optional

Returns

results – List of the final RMS values from individual SPFIT runs.

Return type

list

save(filepath=None)[source]

Dump the current session to disk as a Pickle file.

Parameters

filepath (str, optional) – Filepath to save the file to. If None, uses the filename attribute plus .pkl extension

uncertainties: List
verbose: int = 0
widths: List
class pyspectools.pypickett.GenerateCatalog(niter: int = 10, temp_path: str = '', out_path: str = '', temp_dict: Dict = <factory>, constants_dict: Dict = <factory>, constants: List = <factory>, cwd: str = '')[source]

Bases: object

constants: List
constants_dict: Dict
cwd: str = ''
generate_constants(lower=1000.0, upper=10000.0, distortion=True)[source]

Function to generate a random set of constants for an Asymmetric top based on a uniform random distribution. This also includes centrifugal distortion terms.

Parameters
  • upper (lower,) – Lower and upper bounds for constants to be generated, in MHz.

  • distortion (bool, optional) – If True, quartic centrifugal distortion terms are also included in the simulation. This option is on by default.

Returns

constants_dict – Dictionary with generated rotational constants

Return type

dict

niter: int = 10
out_path: str = ''
run_batch(niter=None, progressbar=True, **kwargs)[source]

Run a batch of simulations. This is the main function to be called by a user, and will automatically carry out all of the book keeping and

Parameters
  • niter (int or None, optional) – Number of simulations to perform. This option overrides the class attribute, and if the user provided argument is None, will just use that instead.

  • progressbar (bool, optional) – If True, wraps the iterator with a tqdm progress bar.

  • kwargs – Additional kwargs are passed into the generate_constants function, which allows for control on bounds, etc.

run_spcat()[source]

Function to run SPCAT from within Python. The function does so with temporary folders within a context manager, such that there are no scratch files left behind when the process is finished.

Returns

catalog – PySpecTools LineList object based on the digested catalog

Return type

LineList object

temp_dict: Dict
temp_path: str = ''
class pyspectools.pypickett.MoleculeFit(options=None)[source]

Bases: object

Class for handling the top level of a Pickett simulation. Inspired by PGopher, the molecule class stores information about whether we’re dealing with a diatomic or polyatomic, number of lines to fit, temperature, etc.

All of the information is bundled into a dictionary called properties.

There are two methods right now that will generate a molecule object; from_json and from_yaml, which will interpret JSON and YAML input files respectively.

backup(comment=None)[source]

Method for backing up files for a specific reason. The most common use I have for this is to backup .cat and .lin files for whatever reason (adding/removing lines to/from fit)

calbak()[source]

Run calbak to generate a .lin file from .cat

check_input()[source]

Method for going through the input settings and flagging common mistakes.

copy_settings(iteration=0)[source]

Copy settings used in a previous iteration If none specified, we’ll take the settings from before the first fit

class exp_line(frequency, uncertainty, lower_num, upper_num, comment=None)[source]

Bases: object

Class for an experimental line. Converts to and from .lin files.

format_line()[source]
format_quantum_numbers()[source]
update_line(line_dict)[source]
finalize(iteration=None)[source]

Been hard to keep track which iteration was the final one sometimes, and so this function will “finalize” the fits by creating a separate folder for the final fits.

fit_lines(verbose=True)[source]
classmethod from_json(json_filepath)[source]
classmethod from_pickle(picklepath)[source]
classmethod from_yaml(yaml_filepath)[source]
generate_parameter_objects(verbose=True)[source]
initialize(options=None)[source]

Method that will rewrite the .par and .int files, after updating the properties dictionary.

Any warnings regarding common mistakes in input files should also be flagged here.

nuclear(delete=False)[source]

Function that cleans up Pickett files in a folder

class parameter(name, parameter_dict, reduction='A', linear=True, verbose=True)[source]

Bases: object

Class for handling parameters in Pickett. Each instance has a human name (i.e. A, B, C constants) which is to be translated to Pickett identifiers.

A fit flag is used to denote whether or not the parameter is going to be fit, which automatically sets the uncertainty to a large number.

Nuclear spin terms will have the nuclei identifier

fit_check()[source]

A function to flip the uncertainty if we will fit a parameter

format_line()[source]

Formats a string output to match the Pickett format for a parameter

parameter_scan(parameter, values, relaxed=False)[source]

A method for automatically scanning parameter space to see what values give a minimum RMS.

We will repeatedly call SPFIT to estimate the fitting error based on what the parameters are. There are two modes depending on the relaxed variable: whether or not all other values are allowed to relax (like a relaxed potential energy scan) or if all parameters are held frozen.

Args: parameter - a string input name of the parameter to change values - a list or array of values to be scanned relaxed - boolean determining whether the parameters are fixed

predict_lines(verbose=True)[source]

Run SPCAT to predict lines based on a .var and .int file. This will operate in the current directory - since it does not need to overwrite any files, we don’t actually back up anything!

The predicted lines are also parsed into a .csv file, and plot up into: (A) a notebook inline plot, and (B) a PDF output.

SPCAT is run twice - first to get the partition function, and second to get the correct intensities.

report_parameters()[source]

Method to return a dictionary of only the parameter values

restore_backup(number)[source]

Restores backed up files from the backup method

save_progress()[source]
set_fit(fit=True, params=None, verbose=False)[source]

Function to flip all parameters to fit or not to fit. The default behaviour, if nothing is provided, is to fit all the parameters.

A list of parameters can be supplied to the params argument, which will specifically fit or not fit those parameters.

setup_int()[source]

Setup the int file. Order of things written: 1. units 2. molecular tag identifier 3. partition function 4. quantum number lower limit 5. quantum number upper limit 6. intensity threshold lower limit 7. intensity threshold upper limit 8. frequency limit in GHz 9. vibrational quantum number limit 10. dipole moments

setup_par()[source]

Function that provides the correct formatting for a .par file

toggle_interactive(connected=False)[source]

Method to toggle interactive plots on and off

update_parameters(parameters, verbose=True)[source]

Update the simulation parameters This is written with a loop in order to make sure the keys that aren’t specified remain the same as before without change.

class pyspectools.pypickett.QuantumNumber(value: int, upper: bool = False, frozen: bool = False, j: bool = True, center: int = 1, width: int = 1, delta: None = None)[source]

Bases: object

Class for a Quantum Number.

center: int = 1
delta: None = None
frozen: bool = False
j: bool = True
roll()[source]

Generate a random value for the current quantum number.

spawn_upper(center=0, width=1)[source]

Create a new QuantumNumber instance for the corresponding upper state. Will also shift the quantum number to a new value, +/-2,1,0.

Returns

QuantumNumber – A deep copy of the current QuantumNumber instance, but also shifts the quantum number by a random integer.

Return type

object

upper: bool = False
value: int
width: int = 1
class pyspectools.pypickett.Transition(frequency: float, n_numbers: int, quantum_numbers: List = <factory>, j: List = <factory>, lower_state: List = <factory>, upper_state: List = <factory>, centers: List = <factory>, widths: List = <factory>, deltas: List = <factory>, uncertainty: float = 0.005)[source]

Bases: object

centers: List
deltas: List
frequency: float
classmethod from_list(frequency, qnos, uncertainty=None)[source]

Class method to spawn a Transition from a list of quantum numbers. This takes a flat iterable (qnos), and splits it into two; the first half is used for the lower state quantum numbers, and the second half the upper state.

Parameters
  • frequency (float) – Frequency of the transition in MHz

  • qnos (list) – Flat list of quantum numbers, includes both lower and upper states

  • uncertainty (float or None, optional) – Optional frequency uncertainty of the transition in MHz. Defaults to None, which uses the default value of 0.005 MHz.

Returns

Transition – Transition object initialized with the specifications

Return type

object

j: List
lower_state: List
n_numbers: int
quantum_numbers: List
random_quantum_numbers()[source]

Create a random set of quantum numbers for a transition. First, the lower state is generated based on lower and upper bounds specified by the user. A deepcopy is made for each lower state quantum number, and the associated upper state number is created by shifting the lower value by a random integer between -2 and 2.

uncertainty: float = 0.005
upper_state: List
widths: List

Generic routines module

Routines to: Parse cat files Run SPFIT and/or SPCAT

class pyspectools.routines.RemoteClient(hostname=None, username=None, **kwargs)[source]

Bases: paramiko.client.SSHClient

classmethod from_file(filepath: str)[source]

Reload a remote session from a pickle file created by the save_session. :param filepath: str path to RemoteClient pickle file :return: RemoteClient object

get_file(remote_path: str, local_path='/home/kelvin/Python/PySpecTools/docs')[source]

Download a file from remote server to disk. If no local path is provided, defaults to the current working directory. :param remote_path: str remote file path target :param local_path: str optional path to save the file to

ls(remote_path='')[source]

Function to get the list of files present in a specified directory. Defaults to the current ssh directory. :param remote_path: str remote path to inspect :return: list of files and folders

open_remote(remote_path: str)[source]

Function to stream the file contents of a remote file. Can be used to directly provide data into memory without downloading it to disk. :param remote_path: str remote path to target file :return: list of contents of the target file

run_command(command: str)[source]
save_session(filepath='ssh.pkl', **kwargs)[source]

Function to dump the ssh settings object to a pickle file. Keep in mind that while this is a matter of convenience, the file is unencrypted and so storing passwords in here is not exactly the safest thing to do! :param filepath: str optional path to save the session to.

pyspectools.routines.backup_files(molecule_name, save_location)[source]
pyspectools.routines.copy_template()[source]
pyspectools.routines.decimal_length(value: float)[source]
pyspectools.routines.dump_json(json_filepath: str, json_dict: Dict[Any, Any])[source]

Function to serialize a Python dictionary into a JSON file. The pretty printing is enabled by default.

Parameters
  • json_filepath (str) – Path to the JSON file to save to

  • json_dict (Dict[Any, Any]) – Dictionary to be serialized

pyspectools.routines.dump_packages()[source]

Function that will return a list of packages that have been loaded and their version numbers.

This function will ignore system packages: sys, __builtins__, types, os

as well as modules with no version.

This is not working the way I want it to…

mod_dict - dict with keys corresponding to module name,

and values the version number.

pyspectools.routines.dump_yaml(yaml_filepath: str, yaml_dict: Dict[Any, Any])[source]

Function to serialize a Python dictionary into a YAML file.

Parameters
  • yaml_filepath (str) – Path to the YAML file

  • yaml_dict (Dict[Any, Any]) – Dictionary to be serialized

pyspectools.routines.find_nearest(array: numpy.ndarray, value: Union[float, int]) → Tuple[numpy.ndarray, int][source]

Function that will find the nearest value in a NumPy array to a specified value.

Parameters
  • array (np.ndarray) – NumPy 1D array

  • value (float) – Value to search the array for

Returns

Returns the closest value, as well as the index

Return type

Tuple[np.ndarray, int]

pyspectools.routines.flatten_list(input_list: List[List[Any]])[source]

Takes a nested list of values and flattens it. The code is written as a try/except that makes the assumption that the data is a list/tuple/array, and in the case that it isn’t will simply append the item to the output instead.

Parameters

input_list (list) – List of values, where some of the elements are lists

Returns

output_list – Flattened version of input_list

Return type

list

pyspectools.routines.format_uncertainty(value: float, uncertainty: float)[source]

Function to determine the number of decimal places to format the uncertainty. Probably not the most elegant way of doing this.

pyspectools.routines.generate_folder()[source]

Generates the folder for the next calculation and returns the next calculation number

pyspectools.routines.group_consecutives(vals: List[float], step=1)[source]

Function to group all consecutive values in a list together. The primary purpose of this is to split concatenated spectra that are given in a single list of frequencies into individual windows.

Parameters
  • vals (list) – List of floats to be split

  • step (int, optional) – [description], by default 1

Returns

[description]

Return type

[type]

pyspectools.routines.human2pickett(name: str, reduction='A', linear=True, nuclei=0)[source]

Function for translating a Hamiltonian parameter to a Pickett identifier.

An alternative way of doing this is to programmatically generate the Pickett identifiers, and just use format string to output the identifier.

pyspectools.routines.isnotebook()[source]
pyspectools.routines.list_chunks(target: List[Any], n: int)[source]

Split a list into a number of chunks with length n. If there are not enough elements, the last chunk will finish the remaining elements.

Parameters
  • target (list) – List to split into chunks

  • n (int) – Number of elements per chunk

Returns

split_list – Nested list of chunks

Return type

list

pyspectools.routines.list_directories()[source]
pyspectools.routines.read_json(json_filepath: str) → Dict[Any, Any][source]

Load a JSON file into memory as a Python dictionary.

Parameters

json_filepath (str) – Path to the JSON file

Returns

Dictionary from JSON file

Return type

Dict[Any, Any]

pyspectools.routines.read_obj(filepath: str)[source]

Wrapper for joblib.load to load an object from disk

filepath - path to object

pyspectools.routines.read_yaml(yaml_filepath: str) → Dict[Any, Any][source]

Function to load in a YAML file into a Python dictionary.

Parameters

yaml_filepath (str) – Path to the YAML file

Returns

Dictionary based on the YAML contents

Return type

Dict[Any, Any]

pyspectools.routines.run_calbak(filename: str)[source]

Runs the calbak routine, which generates a .lin file from the .cat

pyspectools.routines.run_spcat(filename: str, temperature=None)[source]
pyspectools.routines.run_spfit(filename: str)[source]
Parameters

filename

pyspectools.routines.save_obj(obj: Any, filepath: str, **kwargs)[source]

Function to serialize an object using dump from joblib.

Additional kwargs are passed into the dump, which can be compression parameters, etc.

obj - instance of object to be serialized filepath - filepath to save to

Unit conversions

units.py

Routines for performing unit conversions and quantities that are often used in spectroscopy.

pyspectools.units.I2S(I: float, Q: float, frequency: float, E_lower, T=300.0)[source]

Function for converting intensity (in nm^2 MHz) to the more standard intrinsic linestrength, S_ij mu^2.

Parameters
  • - float (T) – The log of the transition intensity, typically given in catalog files

  • - float – Partition function at specified temperature T

  • - float – Frequency of the transition in MHz

  • - float – ENergy of the lower state in wavenumbers

  • - float – Temperature in Kelvin

Returns

Value of the intrinsic linestrength

Return type

siju - float

pyspectools.units.MHz2cm(frequency: float)[source]

Convert MHz to wavenumbers :param frequency: float :return: corresponding value in 1/cm

pyspectools.units.S2I(S: float, Q: float, frequency: float, E_lower: float, T=300.0)[source]

Function for converting intensity (in nm^2 MHz) to the more standard intrinsic linestrength, S_ij mu^2.

Parameters
  • - float (T) – Intrinsic linestrength; Sij mu^2

  • - float – Partition function at specified temperature T

  • - float – Frequency of the transition in MHz

  • - float – ENergy of the lower state in wavenumbers

  • - float – Temperature in Kelvin

Returns

log10 of the intensity at the specified temperature

Return type

I - float

pyspectools.units.T2wavenumber(T: float)[source]

Convert temperature in Kelvin to wavenumbers. :param T: float :return: corresponding value in 1/cm

pyspectools.units.approx_Q_linear(B: float, T: float)[source]

Approximate rotational partition function for a linear molecule.

Parameters
  • - float (T) – Rotational constant in MHz.

  • - float – Temperature in Kelvin.

Returns

Rotational partition function at temperature T.

Return type

Q - float

pyspectools.units.approx_Q_top(A: float, B: float, T: float, sigma=1, C=None)[source]

Approximate expression for the (a)symmetric top partition function. The expression is adapted from Gordy and Cook, p.g. 57 equation 3.68. By default, the prolate top is used if the C constant is not specified, where B = C. Oblate case can also be specified if A = C.

Parameters
  • - float (T) – Rotational constant for the A principal axis, in MHz.

  • - float – Rotational constant for the B principal axis, in MHz.

  • - float – Temperature in Kelvin

  • - int (sigma) – Rotational level degeneracy; i.e. spin statistics

  • - float, optional (C) – Rotational constant for the C principal axis, in MHz. Defaults to None, which will reduce to the prolate top case.

Returns

Partition function for the molecule at temperature T

Return type

Q - float

pyspectools.units.boltzmann_factor(E: float, T: float)[source]

Calculate the Boltzmann weighting for a given state and temperature.

Parameters
  • - float (T) – State energy in wavenumbers

  • - float – Temperature in Kelvin

Returns

Unitless Boltzmann factor for the state

Return type

boltzmann_factor - float

pyspectools.units.calc_E_lower(frequency: float, E_upper: float)[source]

Calculate the lower state energy, for a given lower state energy and the frequency of the transition.

Parameters
  • - float (E_upper) – Frequency of the transition in MHz

  • - float – Upper state energy in wavenumbers

Returns

Lower state energy in wavenumbers

Return type

E_lower - float

pyspectools.units.calc_E_upper(frequency: float, E_lower: float)[source]

Calculate the upper state energy, for a given lower state energy and the frequency of the transition.

Parameters
  • - float (E_lower) – Frequency of the transition in MHz

  • - float – Lower state energy in wavenumbers

Returns

Upper state energy in wavenumbers

Return type

E_upper - float

pyspectools.units.cm2MHz(wavenumber: float)[source]

Convert wavenumbers to MHz :param wavenumber: float :return: corresponding value in MHz

pyspectools.units.dop2freq(velocity: float, frequency: float)[source]

Calculates the expected frequency in MHz based on a Doppler shift in km/s and a center frequency.

Parameters
  • velocity (float) – Radial velocity in km/s

  • frequency (float) – Center frequency in MHz

Returns

offset – The change in frequency associated with the velocity and

Return type

float

pyspectools.units.einsteinA(S: float, frequency: float)[source]

Calculate the Einstein A coefficient for a transition with specified transition frequency and intrinsic linestrength.

Parameters
  • S (float) – Intrinsic linestrength; unitless

  • frequency (float) – Transition frequency in MHz

Returns

Einstein A coefficient in units of per second

Return type

float

pyspectools.units.freq2vel(frequency: float, offset: float)[source]

Calculates the Doppler shift in km/s based on a center frequency in MHz and n offset frequency in MHz (delta nu).

Parameters
  • frequency (float) – Center frequency in MHz

  • offset (float) – Frequency offset from the center in MHz

Returns

doppler – Doppler offset in km/s

Return type

float

pyspectools.units.gaussian_fwhm(sigma: float)[source]

Calculate the full-width half maximum value assuming a Gaussian function.

sigma - float for width

fwhm - float value for full-width at half-max

pyspectools.units.gaussian_height(amplitude: float, sigma: float)[source]

Calculate the height of a Gaussian distribution, based on the amplitude and sigma. This value corresponds to the peak height at the centroid.

amplitude - float sigma - float

h - float

pyspectools.units.gaussian_integral(amplitude: float, sigma: float)[source]

Calculate the integral of a Gaussian analytically using the amplitude and sigma. :param amplitude: amplitude of the Gaussian :param sigma: width of the Gaussian :return: integrated area of the Gaussian

pyspectools.units.hartree2K(hartree: float)[source]

Convert Hartrees to temperature in Kelvin.

Parameters

hartree (float) – Electronic energy in Hartrees

Returns

kelvin – Corresponding value in Kelvin

Return type

float

pyspectools.units.hartree2eV(hartree: float)[source]

Convert Hartrees to eV. :param hartree: Electronic energy in Hartrees :type hartree: float

Returns

eV – Corresponding value in eV

Return type

float

pyspectools.units.hartree2kjmol(hartree: float)[source]

Convert Hartrees to kJ/mol. :param hartree: float :return: converted value in kJ/mol

pyspectools.units.hartree2wavenumber(hartree: float)[source]

Convert Hartrees to wavenumbers. :param hartree: float :return: corresponding value in 1/cm

pyspectools.units.inertial_defect(A: float, B: float, C: float)[source]

Calculate the inertial defect of a molecule with a set of A, B, and C rotational constants.

Parameters

B, C - float (A,) – Rotational constant along the respective principal axis in units of MHz.

Returns

The inertial defect in units of amu Ang**2

Return type

delta - float

pyspectools.units.kappa(A: float, B: float, C: float)[source]

Calculate Ray’s asymmetry parameter for a given set of A, B, and C rotational constants. This parameter determines how asymmetric a molecule is by setting a range between two limits: the prolate (+1) and the oblate (-1) limits.

Parameters

B, C (A,) – Rotational constant in MHz for each respective axis

Returns

kappa – Ray’s asymmetry parameter

Return type

float

pyspectools.units.kjmol2wavenumber(kj: float)[source]

Convert kJ/mol to wavenumbers :param kj: float :return: corresponding value in 1/cm

pyspectools.units.rotcon2pmi(rotational_constant: float)[source]

Convert rotational constants in units of MHz to Inertia, in units of amu A^2.

The conversion factor is adapted from: Oka & Morino, JMS (1962) 8, 9-21 This factor comprises h / pi^2 c.

Parameters

rotational_constant – Corresponding rotational constant in MHz

Returns

Return type

Rotational constant converted to units of amu A^2

pyspectools.units.thermal_corrections(frequencies: List[float], T: float, linear=True, hartree=True)[source]

Calculates the thermal contributions from nuclear motion, in the same way as Gaussian does. :param frequencies: Iterable of vibrational frequencies in wavenumbers. Can be Harmonic or Anharmonic fundamentals. :type frequencies: list of floats or Numpy 1-D array :param T: Value of the temperature to calculate thermal corrections at :type T: float :param linear: Specifies whether molecule is linear or not. Affects the rotational contribution. :type linear: bool, optional :param hartree: If True, converts the contribution into Hartrees. Otherwise, in units of Kelvin :type hartree: bool, optional

Returns

thermal – Total thermal contribution at a given temperature

Return type

float

pyspectools.units.wavenumber2T(wavenumber: float)[source]

Convert wavenumbers to Kelvin :param wavenumber: float :return: corresponding value in K

pyspectools.units.wavenumber2kjmol(wavenumber: float)[source]

Convert wavenumbers to kJ/mol. :param wavenumber: float :return: converted value in kJ/mol

Module contents