BCExperiment

BCExperiment is the entry point for loading a Blackchirp experiment from disk into Python. Pass it the path to a single experiment folder (the directory containing version.csv) or a path to the data-storage root together with a numeric experiment num; it resolves the on-disk location, reads every per-experiment CSV present, and exposes each as a pandas DataFrame attribute named after the file.

The constructor always reads version.csv, header.csv, objectives.csv, log.csv, and hardware.csv. Optional files (clocks.csv, auxdata.csv, chirps.csv, markers.csv) are loaded when present; the corresponding attribute is omitted (or set to None for clocks) when the file is absent. A clocks.csv is required for any experiment that contains an fid/ subdirectory and its absence raises FileNotFoundError at construction time.

If the experiment folder contains an fid/ subdirectory, a BCFTMW is constructed and exposed as ftmw. If it contains a lif/ subdirectory, a BCLIF is constructed and exposed as lif. Both attributes are present on a combined CP-FTMW + LIF experiment; either may be present alone.

The header table — by far the largest and most useful of the loaded DataFrames — is queried through the header_unique_keys, header_rows, header_value, and header_unit helpers. The on-disk schema is described in detail on the Data Storage user-guide page; the helpers there are direct counterparts to the column meanings documented on that page.

API Reference

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 at the resolved experiment path.
KeyError – If header.csv does not contain the Experiment / Number row required to identify the experiment.

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:

$ e347.hardware

                              key                       driver
                        AWG.Ka                   VirtualAwg
                  Clock.virtual                   FixedClock
        FtmwDigitizer.virtual       VirtualFtmwDigitizer
     FlowController.Default       PythonFlowController
 PulseGenerator.Default       VirtualPulseGenerator

The hardware.csv file from older experiments may use the legacy column header subKey instead of driver. Both forms are normalised to driver on read so downstream code can use a single column name.

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 driver identities. The second column is exposed as driver regardless of whether the on-disk header was driver or subKey.

Type:: pd.DataFrame

clocks

Contents of clocks.csv. Configurations of all clocks at each experimental step. Required for CP-FTMW experiments and None for LIF-only acquisitions, which do not produce a clocks.csv.

Type:: pd.DataFrame, optional

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

markers

Contents of markers.csv (if present). Marker channel configuration for the experiment’s pulse pattern. Columns: Channel, Name, Role, TimingMode, StartUs, EndUs, Enabled.

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 rows. May be empty (use .empty / len() to test) — an empty result is not an error here.

header_unique_keys() → set[str]

Fetch all unique ObjKeys in experiment header

Returns:: Set 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. The idx value then selects which matching row to return.

Parameters:

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

Returns:

Unit string for the matching row. An empty string is returned when the row exists but its Units cell is empty (a value with no associated unit is a legitimate state).

Raises:

KeyError – If no row matches the supplied filter, or if idx is past the end of the matching rows.

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. The idx value then selects which matching row to return.

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 as a string.

Raises:

KeyError – If no row matches the supplied filter, or if idx is past the end of the matching rows.