Usage

To use acqpack in a project:

import acqpack

Classes

class acqpack.Motor(config_file, home=True)

Low-level wrapper for the Lin Engineering (LE) CO-4118S-09. Config file must be defined.

The LE CO-4118S-09 has an integrated controller with a documented serial command-set. It lacks an encoder, and so relies on dead-reckoning for position. It does have an optical sensor that allows it to get a positional fix (home).

cmd(cmd_string, block=True)

Wraps core cmd_string with prefix and terminator specified in config, writes to serial, and returns response. Optionally blocks programmatic flow (default=True).

Parameters:

• cmd_string – (str) core command (w/o prefix nor terminator)
• block – (bool) whether the command blocks program flow until action is complete

Returns:

(str) device response

is_busy()

Sends query command, then parses response to determine if motor is busy.

Returns:(bool) true if motor is executing a command

set_velocity(velocity)

Checks requested velocity against the velocity limit, then sets motor velocity in usteps/sec.

Parameters:velocity – (int) velocity Returns:(str) device response

halt()

Sends halt command to motor, which stops it from executing its current command. Note that many commands are sent in ‘blocking’ mode, so this function will likely not be called until the motor finishes executing its current command.

In the future, it may be nice to implement a ‘waiting’ scheme.

home()

Homes the motor until the optical sensor is triggered. Zero position is reset (motor gets positional fix).

Returns:(str) device response

goto(mm, block=True)

Moves motor absolutely to the specified position.

Parameters:

• mm – (float) desired absolute position [mm]
• block – (bool) whether the command blocks program flow until action is complete

Returns:

(str) device response

move_relative(mm)

Moves motor relatively by the specified number of mm.

Parameters:mm – (float) desired relative movement [mm] Returns:(str) device response

where()

Retrieves motor’s current position relative to zero-position (by dead reckoning).

Returns:(tup) current position of the motor [mm]

exit()

Closes the device’s serial connection.

class acqpack.AsiController(config_file, init_xy=True)

Low-level wrapper for the Applied Scientific Instrumentation (ASI) Controller. Config file must be defined.

This class can control both an XY-axis (MS-2000 stage) and a Z-axis (LS-50 linear stage). Since this hardware was taken from an Illumina GaIIx, it assumes the controller’s serial command-set requires an OEM prefix of 1h (Z-axis) or 2h (XY-axes). Both stages have a linear-encoder.

Functions for Z-axis control are defined, but it is not initialized. If it is desired to be used, then a homing procedure needs to be defined in initialize().

cmd(cmd_string)

Wraps core cmd_string with terminator specified in config, writes to serial, and returns response.

Parameters:cmd_string – (str) core command (w/o prefix nor terminator) Returns:(str) device response

halt()

Sends halt command to both axes, interrupting execution of their current commands. Note that many commands are sent in ‘blocking’ mode, so this function will likely not be called until the axes finish executing their current command.

In the future, it may be nice to implement a ‘waiting’ scheme.

exit()

Closes the device’s serial connection.

cmd_xy(cmd_string, block=True)

Wraps core cmd_string with axes prefix (2h), passes to the cmd() function, and returns response. Optionally blocks programmatic flow (default=True).

Parameters:

• cmd_string – (str) core command (w/o prefix nor terminator)
• block – (bool) whether the command blocks program flow until action is complete

Returns:

(str) device response

is_busy_xy()

Sends status command, then parses response to determine if XY-axes are busy.

Returns:(bool) true if axes are executing a command

halt_xy()

Sends halt command to the XY-axes (stage), interrupting execution of its current command. Note that many commands are sent in ‘blocking’ mode, so this function will likely not be called until the axes finish executing their current command.

In the future, it may be nice to implement a ‘waiting’ scheme.

zero_xy(x_dir=1, y_dir=1)

Sets the origin (zeros) at current location. If ‘x_dir’ and ‘y_dir’ are specified, will seek hardware limit (hall-effect stops) before zeroing. ‘x_dir’ and ‘y_dir’ represent whether to max (+1) or min (-1) each axis.

Parameters:

• x_dir – (int) -1 to min, +1 to max
• y_dir – (int) -1 to min, +1 to max

Returns:

(str) device response

home_xy()

Moves XY-axes to origin (0,0)

where_xy()

Retrieves XY-axes’ current position relative to zero point (w/ linear encoder).

Returns:(tup) current X and Y position [mm]

goto_xy(x_mm, y_mm)

Moves XY-axes absolutely to the specified position.

Parameters:

• x_mm – (float) desired absolute X position [mm]
• y_mm – (float) desired absolute Y position [mm]

Returns:

(str) device response

move_relative_xy(x_mm, y_mm)

Moves XY-axes relatively by the specified number of mm.

Parameters:

• x_mm – (float) desired relative movement [mm]
• y_mm – (float) desired relative movement [mm]

Returns:

(str) device response

cmd_z(cmd_string, block=True)

Wraps core cmd_string with axis prefix (1h), passes to the cmd() function, and returns response. Optionally blocks programmatic flow (default=True).

Parameters:

• cmd_string – (str) core command (w/o prefix nor terminator)
• block – (bool) whether the command blocks program flow until action is complete

Returns:

(str) device response

is_busy_z()

Sends status command, then parses response to determine if Z-axis is busy.

Returns:(bool) true if axis is executing a command

halt_z()

Sends halt command to the Z-axis (linear motor), interrupting execution of its current command. Note that many commands are sent in ‘blocking’ mode, so this function will likely not be called until the axes finish executing their current command.

In the future, it may be nice to implement a ‘waiting’ scheme.

home_z()

Moves Z-axis to 0.

where_z()

Retrieves Z-axis’ current position relative to zero point (w/ linear encoder).

Returns:(tup) current Z position [mm]

goto_z(z_mm)

Moves Z-axis absolutely to the specified position.

Parameters:z_mm – (float) desired absolute Z position [mm] Returns:(str) device response

move_relative_z(z_mm)

Moves Z-axis relatively by the specified number of mm.

Parameters:z_mm – (float) desired relative movement [mm] Returns:(str) device response

class acqpack.Autosampler(z, xy)

A high-level wrapper that coordinates XY and Z axes to create an autosampler. Incorporates a deck.

add_frame(name, trans=array([[1., 0., 0., 0.], [0., 1., 0., 0.], [0., 0., 1., 0.], [0., 0., 0., 1.]]), position_table=None)

Adds coordinate frame. Frame requires affine transform to hardware coordinates; position_table optional.

Parameters:

• name – (str) the name to be given to the frame (e.g. hardware)
• trans – (np.ndarray <- str) xyzw affine transform matrix; if string, tries to load delimited file
• position_table – (None | pd.DataFrame <- str) position_table; if string, tries to load delimited file

add_plate(name, filepath, ref_frame='deck')

TODO: UNDER DEVELOPMENT

where(frame=None)

Retrieves current hardware (x,y,z). If frame is specified, transforms hardware coordinates into frame’s coordinates.

Parameters:frame – (str) name of frame to specify transform (optional) Returns:(tup) current position

home()

Homes Z axis, then XY axes.

goto(frame, lookup_columns, lookup_values, zh_travel=0)

Finds lookup_values in lookup_columns of frame’s position_list; retrieves corresponding X,Y,Z. Transforms X,Y,Z to hardware X,Y,Z by frame’s transform. Moves to hardware X,Y,Z, taking into account zh_travel.

Parameters:

• frame – (str) frame that specifies position_list and transform
• lookup_columns – (str | list) column(s) to search in position_table
• lookup_values – (val | list) values(s) to find in lookup_columns
• zh_travel – (float) hardware height at which to travel

exit()

Send exit command to XY and Z

class acqpack.FractionCollector(xy)

A high-level wrapper around an XY stage.

add_frame(name, trans=array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]]), position_table=None)

Adds coordinate frame. Frame requires affine transform to hardware coordinates; position_table optional.

Parameters:

• name – (str) the name to be given to the frame (e.g. hardware)
• trans – (np.ndarray <- str) xyw affine transform matrix; if string, tries to load delimited file
• position_table – (None | pd.DataFrame <- str) position_table; if string, tries to load delimited file

where(frame=None)

Retrieves current hardware (x,y). If frame is specified, transforms hardware coordinates into frame’s coordinates.

Parameters:frame – (str) name of frame to specify transform (optional) Returns:(tup) current position

home()

Homes XY axes.

goto(frame, lookup_columns, lookup_values)

Finds lookup_values in lookup_columns of frame’s position_list; retrieves corresponding X,Y Transforms X,Y to hardware X,Y by frame’s transform. Moves to hardware X,Y.

Parameters:

• frame – (str) frame that specifies position_list and transform
• lookup_columns – (str | list) column(s) to search in position_table
• lookup_values – (val | list) values(s) to find in lookup_columns

exit()

Send exit command to XY.

class acqpack.Manifold(ip_address, valvemap_path, read_offset=512)

Provides a wrapper for the manifold, which is controlled by the Wago nModbus

load_valvemap(valvemap_path)

Stores valvemap. To work with open/close, valvemap should have one column named ‘valve’.

Parameters:valvemap_path – (str) path to valvemap

read_valve(valve_num)

Reads the state of the register associated with the specified valve.

Parameters:valve_num – (int) register number to read Returns:() state of the register (True: depressurized, False: pressurized)

pressurize(valve_num)

Pressurizes valve at the specified register.

Parameters:valve_num – (int) valve to pressurize

depressurize(valve_num)

Depressurizes valve at the specified register.

Parameters:valve_num – (int) valve to depressurize

close(lookup_cols, lookup_vals)

Finds lookup_vals in lookup_cols of valvemap; retrieves corresponding valve_num. Closes valve_num.

Parameters:

• lookup_cols – (str | list) column(s) to search in valvemap
• lookup_vals – (val | list) value(s) to find in lookup_cols

open(lookup_cols, lookup_vals)

Finds lookup_vals in lookup_cols of valvemap; retrieves corresponding valve_num. Opens valve_num.

Parameters:

• lookup_cols – (str | list) column(s) to search in valvemap
• lookup_vals – (val | list) value(s) to find in lookup_cols

exit()

Closes the device’s serial connection.

class acqpack.Mfcs(config_file, chanmap_path)

Class to control the MFCS-EZ.

detect()

Detects up to 8 connected MFCS devices; returns serial numbers of connected devices.

Returns:(list) detected MFCS serial numbers as ints

connect()

Initializes the MFCS. Makes connection, checks status, and sets the PID alpha parameter of all channels to 2.

status()

Gets and returns status of the MFCS. 0: ‘MFCS is reset - press “Play”’ 1: ‘normal’ 2: ‘overpressure’ 3: ‘need to rearm’

Returns:(tup) status int [0-3], status string

pid(chan, a)

Sets alpha parameter of the PID controller for the given channel. Lower values of alpha (1-2) are typically more stable at lower pressures, but take slightly longer to equilibrate.

For some reason, the python kernel would crash when ‘channel’ and ‘alpha’ were used as keywords. C-types…

Parameters:

• chan – (int) channel [1-4] to set; 0 sets for all channels
• a – (int) desired alpha value for PID

load_chanmap(chanmap_path)

Stores channel map.

Parameters:chanmap_path – (str) path to chanmap

exit()

Safely closes the MFCS. First closes device connection, then releases the DLL.

set(lookup_cols, lookup_vals, pressure=0.0)

Sets pressure of specified channel.

Parameters:

• lookup_cols – (str | list) column(s) to search in chanmap
• lookup_vals – (val | list) value(s) to find in lookup_cols
• pressure – (float) desired pressure; units specified in config file

read(lookup_cols, lookup_vals)

Reads current pressure of the channel.

Parameters:

• lookup_cols – (str | list) column(s) to search in chanmap
• lookup_vals – (val | list) value(s) to find in lookup_cols

Returns:

(float) current pressure; units specified in config file

Modules

acqpack.gui.imshow(img, name='Image', mode='cv2')

acqpack.gui.snap(core, mode='mpl')

acqpack.gui.video(core, loop_pause=0.15)

acqpack.gui.grid(core, loop_pause=0.15)

acqpack.gui.manifold_control(manifold, button_col='name', trim_to_valvemap=True)

acqpack.gui.stage_control(stage)

acqpack.utils.read_delim(filepath)

Reads delimited file (auto-detects delimiter + header). Returns list.

Parameters:filepath – (str) location of delimited file Returns:(list) list of records w/o header

acqpack.utils.read_delim_pd(filepath)

Reads delimited file (auto-detects delimiter + header). Returns pandas DataFrame.

Parameters:filepath – (str) location of delimited file Returns:(DataFrame)

acqpack.utils.lookup(table, lookup_cols, lookup_vals, output_cols=None, output_recs=None)

Looks up records where lookup_cols == lookup_vals. Optionally returns only specified output_cols and/or specified output_recs.

Parameters:

• table – (DataFrame) the pandas DataFrame to use as a lookup table
• lookup_cols – (str | list)
• lookup_vals – (val | list)
• output_cols –
• output_recs –

Returns:

acqpack.utils.generate_position_table(num_rc, space_rc, offset=(0.0, 0.0, 0.0), to_clipboard=False)

Generates a position table for a plate. Assumes that ‘x’ and ‘c’ are aligned and that ‘y’ and ‘r’ are aligned. These axes can be reflected by negating the corresponding ‘space_rc’; translations can be applied via ‘offset’. All entries are indexed by ‘n’ (newspaper order) and ‘s’ (serpentine order). Other columns may be added as needed, but Autosampler.goto() requires ‘x’, ‘y’, and ‘z’ to function properly.

Parameters:

• num_rc – (tup) number of rows and columns (num_rows, num_cols)
• space_rc – (tup) spacing for rows and columns [mm] (spacing_rows, spacing_cols)
• offset – (tup) 3-tuple of floats to be added to x,y,z [mm]
• to_clipboard – (bool) whether to copy the position_table to the OS clipboard

Returns:

(DataFrame)

acqpack.utils.spacing(num_rc, p1, p2)

acqpack.utils.load_mm_positionlist(filepath)

Takes a MicroManager position list and converts it to a pandas DataFrame. Will load z-coordinates if available.

Parameters:filepath – (str) Returns:(DataFrame) position list with headers = “r, c, name, x, y, [z]”

acqpack.utils.generate_grid(c0, c1, l_img, p)

Based on two points, creates a 2D-acquisition grid similar to what MicroManager would produce.

Parameters:

• c0 – (arr) first point; numpy 1d array of len 2
• c1 – (arr) second point; numpy 1d array of len 2
• l_img – (float)
• p – (float) desired percent overlap

Returns:

(DataFrame) position_list in the same format as load_mm_positionlist