Reference¶

polarstar¶

Scientific Tools for Automation and Replication - STAR.

STAR is a Python library focused on simplifying the automation of scientific experiments, including data collection and hardware control. While STAR is designed to integrate with POLAR, it can also be used independently for various scientific applications.

Modules: - cnc: Manages CNC hardware communication and G-code operations. - plate: Defines the Plate class for data management and optical measurement automation.

Exports: - Plate: Represents a microplate for organizing and managing well-based data. - load_plate: Loads a saved plate configuration from a file. - CNCController: Handles CNC hardware control and communication.

class polarstar.CNCController(port='COM6', baudrate=115200, timeout=1)¶

A controller for managing CNC machines via serial communication.

This class provides functionality to send G-code commands to CNC machines, monitor their status, and register callbacks for specific G-code commands.

port¶

The serial port to which the CNC machine is connected.

Type:

str

baudrate¶

The communication speed in bits per second.

Type:

int

timeout¶

The timeout for serial read operations, in seconds.

Type:

int

callbacks¶

A dictionary of registered callbacks for G-code commands.

Type:

dict

register_callback(command, callback, *args, **kwargs)¶

Register a callback for a specific G-code command.

Parameters:

  • command (str) – The G-code command to monitor (e.g., ‘G1’).

  • callback (callable) – The function to call when the command is detected.

  • args (Any) – Additional positional arguments to pass to the callback.

  • kwargs (Any) – Additional keyword arguments to pass to the callback.

Return type:

None

send_gcode(input_data=None)¶

Send G-code commands to the CNC machine.

Parameters:

input_data (Plate, str, or file path) – Can be: - A Plate object (generates G-code automatically). - A string containing G-code. - A file path to a G-code file.

Raises:

  • ValueError – If input_data is None or invalid.

  • Exception – If there is an error in serial communication.

Return type:

None

simulate(plate, figsize=(15, 10))¶

Create a 3D simulation of the G-code path.

Parameters:

  • plate (Plate) – The plate object to visualize.

  • figsize (tuple of int, optional) – Figure size (width, height), by default (15, 10).

Returns:

HTML animation of the 3D simulation.

Return type:

IPython.display.HTML

wait_for_idle(cnc_serial)¶

Wait until the CNC machine enters the ‘Idle’ state.

Parameters:

cnc_serial (serial.Serial) – The active serial connection to the CNC machine.

Return type:

None

class polarstar.Plate(rows, cols, x_spacing=9, y_spacing=9, z_read=-5, offset_y=-90, offset_z=-5, diameter=6.94, z_safe=0)¶

Class representing a plate for storing substances, concentrations or custom information.

Parameters:

  • rows (int) – Number of rows in the plate.

  • cols (int) – Number of columns in the plate.

  • x_spacing (float, optional) – Distance between wells along the X-axis in mm. Default is 9.

  • y_spacing (float, optional) – Distance between wells along the Y-axis in mm. Default is 9.

  • z_read (float, optional) – Z-axis height for interaction in mm. Default is -5.

  • z_safe (float, optional) – Safe height in Z-axis for non-reading positions in mm. Default is 0.

  • offset_y (float, optional) – Y-axis calibration offset in mm. Default is -90.

  • offset_z (float, optional) – Z-axis calibration offset in mm. Default is -5.

  • diameter (float, optional) – Well diameter in mm. Default is 6.94.

convert_concentration(concentration)¶

Convert concentration to a more readable format (mM, µM, nM, pM).

Parameters:

concentration (float) – Concentration value in M.

Returns:

Display concentration and unit.

Return type:

tuple

generate_gcode(filename=None)¶

Generate G-code for CNC movement across wells.

Parameters:

filename (str, optional) – File path to save the G-code.

Returns:

Generated G-code as a string.

Return type:

str

index_to_pos(index)¶

Convert a linear index to row and column positions.

Parameters:

index (int) – Linear index.

Returns:

Row and column positions.

Return type:

tuple of int

index_to_row_label(index)¶

Convert row index to a label (e.g., ‘A’, ‘B’).

Parameters:

index (int) – Row index.

Returns:

Row label.

Return type:

str

plot_plate(figsize=(14, 8), show_concentration=True, well_font_size=10, legend_font_size=10, tick_font_size=6)¶

Plot the plate with well contents and concentrations.

Parameters:

  • figsize (tuple) – Figure size.

  • show_concentration (bool) – Display concentration if True.

  • well_font_size (int) – Font size for the text inside wells. Default is 10.

  • legend_font_size (int) – Font size for the legend text. Default is 10.

  • tick_font_size (int) – Font size for axis tick labels (row letters and column numbers). Default is 6.

Return type:

None

pos_to_index(row, col)¶

Convert a row and column position to a linear index.

Parameters:

  • row (int) – Row index.

  • col (int) – Column index.

Returns:

Linear index for the position.

Return type:

int

save(filename)¶

Save plate data to a file with a .star extension.

Parameters:

filename (str) – The base path to save the data. If the filename does not already end with .star, the function will automatically append it.

Returns:

The full path of the saved file, including the .star extension.

Return type:

str

Notes

The saved file will have a .star extension if not already present, and the data will be stored in binary format using NumPy’s np.save.

set_custom(pos, value, substance, color)¶

Set a specific well with a custom value.

Parameters:

  • pos (str) – Well position (e.g., ‘A1’).

  • value (float) – Custom value for the well.

  • substance (str) – Substance name.

  • color (str) – Color for the substance.

Return type:

None

set_serial_dilutions(start_pos, initial_concentration, dilution_factor, num_dilutions, substance, color)¶

Set serial dilutions of a substance in wells starting from a given position.

This function assigns serial dilutions of a specified substance to consecutive wells, following a given dilution factor.

Parameters:

  • start_pos (str) – Start position (e.g., ‘A1’).

  • initial_concentration (float) – Initial concentration in millimolar (mM).

  • dilution_factor (float) – Factor for serial dilutions.

  • num_dilutions (int) – Number of dilutions.

  • substance (str) – Name of the substance.

  • color (str) – Color for the substance representation.

Return type:

None

polarstar.load_plate(filename)¶

Load plate data from a file.

Parameters:

filename (str) – File path from which to load the data.

Returns:

Plate object with loaded data.

Return type:

Plate