BCFid

BCFid is the single-FID container served by BCFTMW.get_fid and BCFTMW.get_differential_fid. On construction it reads one fid/N.csv file, decodes the base-36-packed accumulated samples into per-shot voltages using the matching fidparams.csv row (vmult / shots), and stores the result as a 2-D numpy array. The first axis is time; the second axis is the frame index. A single-frame acquisition still has shape (size, 1) so downstream code can index uniformly.

The ft method computes the Fourier transform of every frame using the default settings drawn from fid/processing.csv (start / end window in microseconds, window function, exponential filter, zero-padding factor, FT units). Any of those settings may be overridden per call via keyword argument; frame=N restricts the FT to a single frame, and freq_units= rescales the returned frequency axis to Hz, kHz, MHz (default), GHz, or THz. apply_lo and is_lower_sideband expose the sideband-aware mapping from detected frequency to molecular frequency that ft and the BCFTMW deconvolution path both use internally.

The default-vs-override pattern is the same one used by Blackchirp’s GUI FID-processing menu: each named ft argument left as None falls back to the value in processing.csv. Window-function and FtUnits settings are accepted as either canonical name strings (BlackmanHarris, FtuV, …) or the historical integer enum values, so the loader works against acquisitions captured before and after the v2 enum-string migration.

For combining FIDs across multiple Blackchirp experiments, see the two module-level helpers documented in Coaverage.

API Reference

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

  • fidparams – DataFrame loaded from fidparams.csv (indexed by FID number)

  • 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 digitizer 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

Raises:

ValueError – If fidparams['sideband'] is unrecognised.

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, freq_units: str = 'MHz') → 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 name. One of None, Bartlett, Blackman, BlackmanHarris, Hamming, Hanning, KaiserBessel. May also be passed in any form accepted by scipy.signal.get_window — tuples and arbitrary names are forwarded directly.

  • 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. May also be specified in processing.csv as an enum name (FtV / FtmV / FtuV / FtnV) or as the corresponding integer.

  • frame – Apply FT to only the specified frame.

  • freq_units – Units for the returned frequency array. One of "Hz", "kHz", "MHz" (default), "GHz", "THz". start_us, end_us, expf_us, and autoscale_MHz are interpreted in their declared units regardless of this choice.

Returns:

Frequency array (in freq_units), Intensity array.

Raises:

ValueError – If winf is a string that does not match a known window-function name, if the FidWindowFunction value stored in processing.csv is unrecognised, if the FtUnits value is unrecognised, or if freq_units is not a recognised frequency-unit string.

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))
is_lower_sideband() → bool

Indicate whether downconversion uses the lower sideband.

Returns:

True if the sideband field in fidparams denotes the lower sideband (canonical name LowerSideband or integer 1).

Raises:

ValueError – If the sideband value is neither a recognised name nor a recognised integer.

x(units: str = 's') → numpy.ndarray

Compute time array for FID.

Parameters:

units – One of "s", "ms", "us" (or "μs"), "ns". "s" is the default; other choices rescale the array for plotting convenience and have no effect on the stored sample spacing.

Returns:

1D numpy array of sample times in the requested units.

Raises:

ValueError – If units is not a recognised time-unit string.

xy(units: str = 's') → 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.

Parameters:

units – Time-axis units (see x()).

Returns:

Time array, FID array.