Class Documentation

class blackchirp.BCExperiment(path: str = '.', num: int = None)

Container for Blackchirp experimental data

The BCExperiment class reads in experimental data files from a Blackchirp Experiment, providing access to all of the data and settings associated with the experiment. The CP-FTMW and/or LIF data associated with the experiment are loaded into BCFTMW and BCLIF objects which are used to access and process the experimental data.

Essentially, the BCExperiment class directly stores the data shown on the Header, Aux Data, and Log tabs, and its ftmw and lif properties contain the data shown on the CP-FTMW and LIF tabs in the Blackchirp program.

Parameters:

path – Path to data storage folder or experiment folder
num – Experiment number (only required if path is a data storage folder)

Raises:

FileNotFoundError – If no version.csv file is found

Example

To load data, pass the experiment number and/or the path to the folder containing the data. The path should point either to the base Blackchirp data storage folder or to the specific folder of the desired experiment.

For example, if the data storage location is /home/user/blackchirp, then to load experiment 347 (/home/user/blackchirp/experiments/0/0/347):

$ e347 = BCExperiment('/home/user/blackchirp',347)

The experiment number is only required if pointing to a data storage folder. The same data could be accessed with:

$ e347 = BCExperiment('/home/user/blackchirp/experiments/0/0/347')

If, instead, folder 347 has been copied into the same directory as your python script, the experiment can be accessed with:

$ e347 = BCExperiment('./347')

Each csv file in the Experiment folder is loaded as a pandas DataFrame. These DataFrames are each stored as a variable with the same name as the csv file. For example, to see the contents of hardware.csv:

$ e437.hardware

                key   subKey
           AWG.0  virtual
         Clock.0    fixed
         Clock.1    fixed
 FtmwDigitizer.0  virtual
PulseGenerator.0  virtual

num

Experiment number

Type:: int

path

Experiment path

Type:: str

version

Contents of version.csv. Information about the Blackchirp version used to acquire the data

Type:: pd.DataFrame

header

Contents of header.csv. General experimental parameters.

Type:: pd.DataFrame

objectives

Contents of objectives.csv. Information about the goals of the experiment (FTMW type, LIF, etc)

Type:: pd.DataFrame

log

Contents of log.csv. All messages printed to Blackchirp’s log during the experiment.

Type:: pd.DataFrame

hardware

Contents of hardware.csv. All hardware items and their implementation keys.

Type:: pd.DataFrame

clocks

Contents of clocks.csv Configurations of all clocks at each experimental step.

Type:: pd.DataFrame

auxdata

Contents of auxdata.csv (if present). Data shown on Aux Data plots during the experiment.

Type:: pd.DataFrame, optional

chirps

Contents of chirps.csv (if present). Details of all chirps associated with a CP-FTMW acquisition.

Type:: pd.DataFrame, optional

ftmw

Contents of fid directory. This object provides an interface for accessing CP-FTMW data.

Type:: BCFTMW, optional

lif

Contents of lif directory. This object provides an interface for accessing LIF data.

Type:: BCLIF, optional

header_rows(objKey: str = None, valKey: str = None, arrKey: str = None) → pandas.DataFrame

Fetch rows from the header file matching conditions

Filters rows in the header according to ObjKey, ValueKey, and ArrayKey. Any combination of these (or none) may be specified to filter.

Parameters:

objKey – Object key in header
valKey – Value key in header
arrKey – Array key in header

Returns:

DataFrame with matching wors

header_unique_keys() → set[str]

Fetch all unique ObjKeys in experiment header

Returns:: List of unique header keys

header_unit(objKey: str, valKey: str, idx: int = 0, arrKey: str = None) → str

Fetch one unit value from header

The objKey and valKey (and arrKey, if specified) are used to filter the header. Then the idx value is used to determine which row to return. If a match is not found, an empty string is returned

Parameters:

objKey – Object key in header
valKey – Value key in header
idx – Row number to return (optional)
arrKey – Array key in header (optional)

Returns:

Matching value or empty string

header_value(objKey: str, valKey: str, idx: int = 0, arrKey: str = None) → str

Fetch one value from header

The objKey and valKey (and arrKey, if specified) are used to filter the header. Then the idx value is used to determine which row to return. If a match is not found, an empty string is returned

Parameters:

objKey – Object key in header
valKey – Value key in header
idx – Row number to return (optional)
arrKey – Array key in header (optional)

Returns:

Matching value or empty string

class blackchirp.BCFTMW(path: str, sep: str)

Storage object for CP-FTMW data

The BCFTMW class loads FID and processing data for CP-FTMW experiments. It provides functions for accessing FIDs and for performing processing tasks that involve analyzing multiple FIDs in a single operation (e.g., sideband deconvolution in an LO Scan experiment).

This class is not meant to be initialized directly by the user; it is created automatically by BCExperiment.

Parameters:

path – Path to fid directory
sep – CSV delimiter

Examples

Loading an experiment and reading a FID (0.csv):

from blackchirp import *

exp = BCExperiment('path/to/experiment')

# The BCFTMW object is exp.ftmw if the experiment contains CP-FTMW data.

fid = exp.ftmw.get_fid()

Performing upper sideband deconvolution, harmonic mean, FT range 0.1-1.0 GHz per segment:

x, y = exp.ftmw.process_sideband(which='upper',
                                 avg='harmonic',
                                 min_ft_offset=100.0,
                                 max_ft_offset=1000.0)

fidparams

Contents of fidparams.csv file

Type:: DataFrame

processing

Contents of proessing.csv file

Type:: DataFrame

numfids

Number of FIDs specified in fidparams.csv

Type:: int

get_fid(num: int = 0) → BCFid

Loads a (potentially multi-frame) FID from disk.

For standard acquisition modes (Target Shots, Target Time, and Forever), the complete FID is stored as 0.csv and would correspond to num=0, the default. Any other CSV files are backups and are accessed by providing the desired backup number for num.

For other acquisition modes that consist of several segments (LO Scan, DR Scan), num corresponds to the desired segment.

Parameters:: num – Number of FID file to load.
Returns:: A BCFid object containing the requested FID

Raises ValueError:: If num is out of range.

process_sideband(which: str = 'both', avg: str = 'harmonic', min_ft_offset: float = None, max_ft_offset: float = None, frame: int = 0, verbose: bool = False, **proc_kwargs) → tuple[numpy.ndarray, numpy.ndarray]

Performs sideband deconvolution on an LO Scan experiment

See Sideband Deconvolution for an explanation of the purpose of the algorithm. The arguments correspond to the options available in the Sideband Processing and FID processing menus in Blackchirp.

Parameters:

which – {‘both’, ‘upper’, ‘lower’} Sideband to use in deconvolution.
avg – {‘harmonic’, ‘geometric’} Whether to use a harmonic or geometric mean for overlapped segments.
min_ft_offset – Minimum offset frequency for sideband, in MHz. Value is relative to the Downconversion LO frequency. Defaults to 0.0 MHz.
max_ft_offset – Maximum offset frequency for sideband, in MHz. Value is relative to the Downconversion LO frequency. Defaults to the FT bandwidth.
frame – Frame number (indexed from 0). If negative, all frames will be averaged
verbose – If true, print a progress message during the deconvolution.
**proc_kwargs – FID processing settings passed as **kwargs to BCFid.ft.

Returns:

Frequency and intensity arrays for processed spectrum.

Raises:

ValueError – If a provided argument is invalid.

class blackchirp.BCFid(num: int, path: str, fidparams: pandas.DataFrame, sep: str, proc: dict)

Container for FID data

The BCFid class reads in raw Blackchirp data from disk and converts it from base-36 integers to voltage using the conversion values located in fidparams.csv. In addition, it provides convenience functions for coaveraging FIDs, subtracting FIDs, and computing Fourier transforms using Blackchirp’s FID processing settings.

A single FID may consist of multiple frames. The FID data is represented as a 2D numpy array, where the first axis corresponds to the time points and the second axis to the frame number. This is true even if the FID contains only a single frame.

A BCFid object should not be created by the end user; it is designed to work with the BCFTMW class.

Parameters:

num – Number of the FID csv file
path – Base path of experiment
sep – CSV delimiter
proc – Default processing settings from processing.csv

fidparams: pandas Series containing corresponding row from fidparams.csv

proc: Dictionary of processing settings from processing.csv

shots: Number of shots

frames: Number of frames

data: Array of shape (len(fid),frames) containing FID voltage data

apply_lo(freqMHz: numpy.ndarray) → numpy.ndarray

Compute molecular frequency from scope frequency.

If the downconversion mixer is the lower sideband, then the molecular frequency is the Downconversion LO frequency - scope frequency. Otherwise, it is Downconverion LO frequency + scope frequency.

Parameters:: freqMHz – Scope frequency array, in MHz
Returns:: 1D numpy array of molecular frequencies, in MHz

average_frames() → None

Coaverages all frames in the time domain

For FIDs with multiple frames, this function performs a coaverage, reducing the FID y data second axis to length 1. If there is only 1 frame, the function has no effect.

ft(*, start_us: float = None, end_us: float = None, winf: str = None, zpf: int = None, rdc: bool = None, expf_us: float = None, autoscale_MHz: float = None, units_power: int = None, frame: int = None) → tuple[numpy.ndarray, numpy.ndarray]

Compute the Fourier transform of the FID

By default, this computes the FT for each frame in the FID using the settings stored in the proc dictionary. This behavior can be overridden by specifying any combination of the keyword arguments.

Parameters:

start_us – Starting time, in μs. Points at earlier times are set to 0.
end_us – Ending time, in μs. Points at later times are set to 0.
winf – Window function applied to points between start and end. This is passed directly to scipy.signal.get_window.
zpf – Zero-padding factor (positive integer). If nonzero, the FID is padded with zeroes until its length reaches the next power of 2, Then, its length is further extended by 2**zpf.
rdc – If true, the average of the FID is subtracted before the FT is computed.
expf_us – Time constant for an exponential decay filter, in μs.
autoscale_MHz – Range of FT points to set to 0, relative to the Downconversion LO frequency. Useful for suppressing noise near DC.
units_power – FT is scaled by 10**units_power. For μV units, set units_power=6.
frame – Apply FT to only the specified frame.

Returns:

Frequency array (MHz), Intensity array

Raises:

ValueError – If supplied arguments are invalid

Examples

Assuming a BCFid object named fid:

#default FT calculation
x,y = fid.ft()

#override some processing settings
x,y = fid.ft(start_us=3.0,rdc=False,units_power=3)

#compute ft for only frame 3 (assuming the number of frames is >=4)
x,y = fid.ft(frame=3)

#average all frames, then apply a custom window function
fid.average_frames()
p = 1.5
sigma = len(fid)//5
x,y = fid.ft(winf=('general_gaussian',p,sigma))

x() → numpy.ndarray

Compute time array for FID (units: s)

Returns:: Numpy array containing time points

xy() → tuple[numpy.ndarray, numpy.ndarray]

Get time and voltage arrays for FID

The FID data is a 2D numpy array whose second axis corresponds to the frame index. The time array is 1D.

Returns:: Time array, FID array