API Reference¶

Trap steering¶

Control over trap steering is provided through the Trap class. Instances of this class are available by default as:

from bluelake import trap1, trap2, trap3, trap4

trap1.move_to(x=1, y=2)

# Note: this line will fail on dual-trap systems:
trap3.move_to(x=0, y=0)

# Additional trap steering devices that are defined in bluelake:
# (depending on actual availability of the hardware on your C-Trap)
from bluelake import trap12xy, trap12z, trap34xy, trap34z, nanostage

class Trap(name, axes)¶

Control interface for an optical trap

clear(self, delay_ms=500)¶

Clear any trapped particles from the trap, by briefly closing the shutter.

This works best if there is some amount of liquid flow in the flowcell.

Parameters:	delay_ms : int For how long to close the shutter, in milliseconds.

is_busy(self)¶

Is the trap currenty executing a move?

Returns:	bool

move_by(self, dx=None, dy=None, dz=None, speed=1)¶

Move the trap relative to the current position.

The function returns when the trap has finished the move.

Parameters:

dx, dy, dz : Optional[float]: How much to move the trap, in micrometers. Any of the axes can be omitted, in which case the trap does not move in that direction.
speed : float: Total speed of the move, in um/s (i.e, magnitude of the velocity vector). Note: The actual speed of the trap depends on the accuracy of the trap steering device. Only for the high-resolution Trap 1 can an accurate motion in X/Y be guaranteed.

move_to(self, waypoint=None, x=None, y=None, z=None, speed=1)¶

Move the trap to an absolute position in space.

The function returns when the trap has finished the move.

This function is only available for traps that have absolute position control, such as the high-resolution Trap 1 on C-Trap systems.

Parameters:

waypoint : Optional[str]: Name of a previously stored waypoint. Should exactly match the name of the waypoint as entered in the Bluelake user interface.
x, y, z : Optional[float]: Instead of giving a waypoint, this function can also be called with a set of destination coordinates, in micrometers. Any of the axes can be omitted, in which case the trap does not move in that direction.
speed : float: Total speed of the move, in um/s (i.e, magnitude of the velocity vector). Note: The actual speed of the trap depends on the accuracy of the trap steering device. Only for the high-resolution Trap 1 can an accurate motion in X/Y be guaranteed.

Examples

trap1.move_to('start position')
trap1.move_to(x=1, y=2, speed=10)

start_oscillation(self, axis, amplitude, frequency, reset_position=True)¶

Start sinusoidal oscillation of the trap

This function starts sinusoidal motion of the trap along the given axis. Note that availability of oscillation depends on the trap: not all trap hardware supports this feature.

To stop the oscillation, simply call stop.

NOTE: For freqencies above 0.075 Hz, this motion is precisely timed (in hardware). Lower frequencies are typically software-timed, and therefore subject to jitter.

Parameters:	axis : str Which axis to oscillate: ‘X’ or ‘Y’. amplitude : float Oscillation amplitude, in micrometers. frequency : float Oscillation frequency, in hertz. reset_position : bool Go back to the starting position when the oscillation is stopped (True by default)

stop(self)¶: Stop all movement of the trap immediately.

wait(self)¶: Wait until the movement that is currently in progress has finished

current_force¶: Total magnitude of the force measured on the particle in this trap, in piconewton

position¶

Current absolute position of the trap.

This function is only available for traps that have absolute position control, such as the high-resolution Trap 1 on C-Trap systems.

Returns:	x, y, z : float Coordinates in micrometer.

Stage control¶

Navigation within the flowcell is done through bluelake.stage, an instance of the Stage class:

from bluelake import stage

stage.move_to('My favorite point')

class Stage¶

Microstage control

static move_to(waypoint_name, speed=100)¶

Move to a pre-defined waypoint.

Parameters:	waypoint_name : str Name of the waypoint. Should exactly match the name of the waypoint as entered in the Bluelake user interface. speed : float Approximate stage motion speed, in percent of maximum speed.

Fluidics control¶

To contol the microfluidics, use bluelake.fluidics, an instance of the Fluidics class:

from bluelake import fluidics

fluidics.open_valves(1, 2, 3, 6)

class Fluidics¶

Microfluidics control

static close(*valves)¶

Close the valves with the given numbers.

Parameters:	*valves : int The numbers of the valves to open. These match the numbers as seen in the Bluelake user interface. The first valve has number 1.

Examples

To close valves 1, 2, 3, and 6:

fluidics.close(1, 2, 3, 6)

static decrease_pressure()¶

Decrease the pressure by one step.

Acts just like the “-” button in the user interface.

static increase_pressure()¶

Increase the pressure by one step.

Acts just like the “+” button in the user interface.

static open(*valves)¶

Open the valves with the given numbers.

Parameters:	*valves : int The numbers of the valves to open. These match the numbers as seen in the Bluelake user interface. The first valve has number 1.

Examples

To open valves 1, 2, 3, and 6:

fluidics.open(1, 2, 3, 6)

static start_venting()¶

Start venting the pressure.

This function returns immediately, but it may take several seconds for the pressure box to completely vent.

static stop_flow()¶: Close all valves and vent the pressure.

pressure¶: The current pressure, in bar.

Power control¶

Power settings can be changed through the following objects that are defined in the bluelake module:

from bluelake import power

# Trapping laser
print(power.trapping_laser)  # power in %
power.trapping_laser = 50    # set to 50% power

# Power modulation (availability varies per system)
print(power.overall_trapping_power)
print(power.qtrap_split)
print(power.trap1_split)

# Bright-field LED
print(power.bright_field_led)

# Excitation lasers (only for confocal systems)
from bluelake import excitation_lasers
print(excitation_lasers.red)
print(excitation_lasers.green)
print(excitation_lasers.blue)

Timeline¶

Access to data from the timeline is provided through the bluelake.timeline object, an instance of the Timeline class described below.

Index timeline to gain access to individual channels:

from bluelake import timeline

force_channel = timeline["Force HF"]["Force 1x"]

The first index is the name of a channel group; the second index is the name of a channel within the group. Group and channel names match the ones displayed in the Bluelake user interface.

The above code snippet sets the force_channel variable to an instance of the Channel class described below. We can now, for instance, check the latest force value that has been measured using:

print(force_channel.latest_value)

class Timeline¶

Access to data from the timeline.

__getitem__()¶

export()¶

Export channel data to HDF5.

By default, only the channels which are selected in the Bluelake user interface will be exported.

Parameters:

filepath : str: Path to an HDF5 file where the data should be exported. The file is created, or overwritten if it already exists.
start, stop : int: The time range to export (64-bit integer timestamps, in nanoseconds; see also start_time and current_time).
everything : Optional[bool]: Off by default. If enabled, all of the available timeline channels will be exported, regardless of the selection in Bluelake’s user interface.

keys()¶: List of available groups in the timeline.

mark_begin()¶

Start a marked section on the timeline.

Be sure to pair each call to mark_begin with a call to mark_end.

Parameters:	name : Optional[str] Name of the marked section

mark_end()¶

End a marked section on the timeline.

Confocal¶

For C-Trap systems that feature a confocal scanner, a bluelake.confocal object is available. Through this instance of the Scanner class described below, simple automation of confocal scans can be done.

class Scanner¶

abort_scan()¶: Abort any confocal scan that is currently in progress.

start_scan()¶

Overloaded function.

start_scan(self: object) -> None

Start a confocal scan, using the current scan settings.

Start a new confocal scan, using the settings from Bluelake’s user interface.
start_scan(self: object, arg0: str) -> None

Start a confocal scan, based on a scan preset.

Parameters:	preset_name : str Name of a confocal scan preset, as previously created in the Bluelake user interface.

Miscellaneous¶

pause(secs, delta_secs=0.1)¶

Delay execution for a given number of seconds

The argument may be a floating point number for subsecond precision.

reset_force()¶: Set forces to zero. Calibrate force offsets for all channels to zero force.

get_force_calibration()¶

Return the current force calibration for each force channel

The available parameters match the ones available in the force calibration UI.

Examples

cal = bluelake.get_force_calibration()
response = cal["Force 1x"]["Response (pN/V)"]
offset = cal["Force 1x"]["Offset (pN)"]
stiffness = cal["Force 1x"]["kappa (pN/nm)"]

print(cal)  # see available force channels and parameters for each channel
print(cal["Force 1x"])  # see all parameters just for this channel

class PiezoTracker¶

Piezo tracking control

enabled¶

Indicates the state of the piezo tracking

Raises:	RuntimeError If piezo tracking is already enabled

Examples

piezo_tracker.enabled = True
...
piezo_tracker.enabled = False

Parameters:	export : bool If `True`, the marker will also be exported immediately. filepath : str The exact path where the exported file should be created. If empty, the path will be auto-generated just like exporting in the UI.
Returns:	Tuple[int, int] The (start, stop) timestamps of the created marker.