Experiments

Defining new experiments

Experiment([name, protocol, plate_setup, ...])

A QuantStudio experiment / EDS file

Protocols

A basic Protocol is generally made up of Stage s, which are made up of Step s. These are often compatible with AB’s software.

Protocol([stages, name, volume, runmode, ...])	A run protocol for the QuantStudio.
Stage(steps[, repeat, index, label, ...])	A Stage in a protocol, composed of Step s with a possible repeat.
Step(time, temperature[, collect, ...])	A normal protocol step, of a hold and possible collection.

There are also some convenience commands to construct often-used stages:

Stage.stepped_ramp(from_temperature, ...[, ...])	Hold at a series of temperatures, from one to another.
Stage.hold_at(temperature, total_time[, ...])	Hold at a temperature for a set amount of time, with steps of a configurable fixed time.

While the parameters for these classes default to seconds and degrees Celsius, when using numbers as input, they also use the pint library to accept strings (or pint Quantity objects). Thus, you can use "1 hr" or "1 hour" instead of 3600, or "59 °C" or "59 degC" for a temperature. Note that for temperature increments, pint distinguishes between a temperature change and absolute temperature unit, so you would need to use, for example "-1 delta_degC".

QSLib also supports custom steps, which can contain arbitrary SCPI commands. For common commands, it also includes classes that allow more convenient use:

CustomStep(body[, identifier, repeat])	A protocol step composed of SCPI/protocol commands.
protocol.Exposure(settings[, state])	Modifies exposure settings.
protocol.Hold(time[, increment, ...])	A protocol hold (for a time) command.
protocol.Ramp(temperature[, increment, ...])	Ramps temperature to a new setting.
protocol.HACFILT(filters[, default_filters])	Sets filters for HoldAndCollect .
protocol.HoldAndCollect(time[, increment, ...])	A protocol hold (for a time) and collect (set by HACFILT) command.
scpi_commands.SCPICommand(command, *args[, ...])	A representation of an SCPI Command.

Once created, there are several useful methods:

Protocol.info()	Generate a (markdown) text protocol description.
Protocol.plot_protocol([ax])	A plot of the temperature and data collection points.
Protocol.dataframe	A DataFrame of the temperature protocol.
Protocol.all_times	An array of all start and end times of each step, interleaved.
Protocol.all_filters	A list of all filters used at some point in the protocol.
Protocol.check_compatible(new, status)	Checks compatibility for changing a running protocol to a new one.
Protocol.copy()	Returns a new copy (recursively) of the protocol.

Plates

PlateSetup([sample_wells, samples, plate_type])

Loading and saving existing experiments

Loading

Experiment.from_file(file)	Load an experiment from an EDS file.
Experiment.from_machine(machine, name)	Create an experiment from data on a machine, checking the running experiment if any, the machine's public_run_complete storage, and the machine's uncollected storage.
Experiment.from_running(machine)	Create an experiment from the one currently running on a machine.

Saving

Experiment.save_file([path_or_stream, ...])

Save an EDS file of the experiment.

Information, data access and plotting

Information

Experiment.name	Experiment name, also used as file name on the machine.
Experiment.get_status([machine])	Return the status of the experiment, if currently running.
Experiment.createdtime	The run creation time.
Experiment.activestarttime	The actual beginning of the first stage of the run, defined as the first "Run Stage" message in the log after "Stage PRERUN".
Experiment.runstarttime	The run start time as a datetime.
Experiment.activeendtime	The actual end of the main part of the run, indicated by "Stage POSTRun" or an abort.
Experiment.runendtime	The run end time as a datetime, taken from the log.
Experiment.all_filters	All filters used at some point in the experiment.
Experiment.sample_wells	A dictionary of sample names to sample wells (convenience read/write access to the PlateSetup .
Experiment.info([format, plate])	Generate a summary of the experiment, with some formatting configuation.
Experiment.info_html()	Create a self-contained HTML summary (returned as a string, but very large) of the experiment.

Data

Experiment.welldata	A DataFrame with fluorescence reading information.
Experiment.temperatures	A DataFrame of temperature readings, at one second resolution, during the experiment (and potentially slightly before and after, if included in the message log).

Plotting

Experiment.plot_anneal_melt([samples, ...])	Plots anneal/melt curves.
Experiment.plot_over_time([samples, ...])	Plots fluorescence over time, optionally with temperatures over time.
Experiment.plot_protocol([ax])	A plot of the temperature and data collection points in the experiment's protocol.
Experiment.plot_temperatures(*[, sel, ...])	Plot sample temperature readings.

Normalization

NormToMeanPerWell([stage, step, cycle, ...])	A Processor that divides the fluorescence reading for each (filterset, well) pair by the mean value of that pair within a particular selection of data.
NormToMaxPerWell([stage, step, cycle, selection])	A Processor that divides the fluorescence reading for each (filterset, well) pair by the max value of that pair within a particular selection of data.
NormRaw()	A Processor that takes no arguments, and simply passes through raw fluorescence values.

Running and controlling experiments

Experiment.run([machine, overwrite, ...])	Load the run onto a machine, and start it.
Experiment.change_protocol(new_protocol[, ...])	For a running experiment and an updated protocol, check compatibility with the current run, and if possible, update the protocol in the experiment file and on the machine, changing the current run.
Experiment.pause_now([machine])	If this experiment is running, pause it (immediately).
Experiment.resume([machine])	If this experiment is running, resume it.
Experiment.stop([machine])	If this experiment is running, stop it after the end of the current cycle.
Experiment.abort([machine])	If this experiment is running, abort it, stopping it immediately.