Interactive Control¶

Initializing¶

The HiSeq instruments and cameras must first be initialized by using initializeInstruments() and initializeCams() respectively. DCAM-API from Hamamatsu needs to be installed to use the cameras. Initializing the cameras may take up to 2 mins. Initializing the instruments including the stages, FPGA, pumps, valves and lasers may take up to 10 minutes.

import pyseq
hs = pyseq.HiSeq()
hs.initializeCams()
hs.initializeInstruments()

Pumping Reagents¶

Flowcell specific pumps and valves are accessed by keys ‘A’ or ‘B’. Reagents are selected using the 24 port valve, hs.v24. Reagents are assigned to a port on the valve with it’s port_dict. Use move() to select a reagent in the port_dict. If the port_dict is not specified, the port index may be used instead.

hs.v24['A'].move(1)                             # Move to port 1
hs.v24['A'].port_dict = {'water':1, 'PBS':2}    # Assign reagents to ports
hs.v24['A'].move('PBS')                         # Move to PBS at port 2

Use pump() to pull reagents through the flowcell with negative pressure on a flowcell lane basis. For example, with an 8 lane flowcell, pump(250, 100), will pump 250 uL at 100 uL/min through each flowcell lane for a total volume of 2000 uL pumped at a total rate of 800 uL/min. The default number of syringe barrels dedicated to a flowcell lane is 1 and can be changed with update_limits(). Use larger volumes at slower flowrates for optimal pumping.

n_barrels_per_lane = 8
hs.v24['A'].update_limits(n_barrels_per_lane)       # Tied 8 outlets together
volume = 1000                                       # uL
flowrate = 100                                      # uL/min
hs.p['A'].pump(volume, flowrate)

Reagents can be pulled through either the 2 inlet row or 8 inlet row by switching the port on the 10 port valve, hs.v10. Alternatively, move_inlet() can be used to change between the inlet rows.

# Pump through 2 inlet port row
hs.v10['A'].move(2)
hs.v10['B'].move(4)
# Pump through 8 inlet port row
hs.v10['A'].move(3)
hs.v10['B'].move(5)
# Or change between inlet rows with move_inlet
# Change to 2 inlet row
hs.move_inlet(2)
# Change to 8 inlet row
hs.move_inlet(8)

Positioning¶

Use position() to return all the stage information needed to image a section in dictionary.

pos_dict = hs.position('A', [15, 45, 10, 35])

Move the ystage to ‘y_initial’, the xstage to ‘x_initial’ and the zstage to [21500, 21500, 21500] before imaging a section. In general, move the ystage before moving the xstage.

hs.y.move(pos_dict['y_initial'])
hs.x.move(pos_dict['x_initial'])
hs.z.move([21500, 21500, 21500])

The in focus position of the objective can be found with and moved to with autofocus(). The default Autofocus routine set in HiSeq.AF is partial once. Other Autofocus routines include full, partial, and full once.

hs.AF = 'full once'
hs.autofocus(pos_dict)

Setup Optics¶

The excitaton filters need to be moved in place before taking an image or autofocusing. In general the emission filter should always be set in the path of the light when focusing and out of the light path when imaging in the lowest 558 nm channel.

hs.optics.move_ex('green','open')
hs.optics.move_ex('red','open')
hs.optics.move_em_in(True)

Take Images¶

All the following imaging commands take and save images from all 4 emission channels. The images are saved as 16 bit TIFFs (the actual pixel depth of the camera is only 12 bit) and stored in hs.image_path. The default common name of the images is a time stamp, but can be changed by specifying a name. The exact name of the images depend on the imaging command but are always prefixed with the emission channel wavelength, for example c610. The size of the images are 2048 columns of pixels and 128 (the default sensor mode line bundle height) x n_frames rows of pixels. The area imaged is 0.769 mm wide. The length of the area is .048 x n_frames mm, from close to the initial position of the ystage to the back end of the ystage. The stage, objective, and filters should be positioned before the imaging command. A text file with the imaging settings is also saved with the same name as the image prefixed with metadata.

Use take_picture() to image a small area. The exact image names will be the common name if specified or a time stamp if not, prefixed with ‘c’ and the emission channel, for example ‘c610_FirstHiSeqPicture.tiff’.

n_frames = 16
im_name = 'FirstHiSeqPicture'
hs.take_picture(n_frames,im_name) # 2048x2048 px images

Use zstack() to image a tile, or an area at a series of objective positions starting from the current object position, and increasing further in distance from the stage. The spacing of objective positions is controlled by the hs.nyquist_obj attribute. The exact image names will be the emission channel, followed by the common name, and finally the objective step position the images were taken at, for example ‘c610_FirstHiSeqZStack_o30000.tiff’.

hs.nyquist_obj = 235                      # 235 obj step spacing = 0.9 um
n_obj_planes = 10
n_frames = 16
im_name = 'FirstHiSeqZStack'
hs.zstack(n_obj_planes, n_frames, im_name) # 10 obj planes

Use scan() to image across an entire section, or image a volume of a sample. After a tile has been imaged, the stage moves in the x direction, the distance of which is controlled by hs.overlap. The default overlap is 0 pixels. The minimum significant overlap is 4 pixels. The exact image names will in the following order: emission channel, common name, xstage step position, and finally objective step position, for example ‘c610_FirstHiSeqScan_x10000_o30000.tiff’.

hs.y.move(pos_dict['y_initial'])
hs.autofocus(pos_dict)
hs.overlap = 0                                      # non-overlapping images
n_obj_planes = 1
n_frames = pos_dict['n_frames']
n_tiles = pos_dict['n_tiles']
im_name = 'FirstHiSeqScan'
hs.zstack(n_tiles, n_obj_planes, n_frames, im_name) # Scan area defined in pos_dict

HiSeq¶

Illumina HiSeq 2500 System

Examples:

#Create HiSeq object
import pyseq
hs = pyseq.HiSeq()
#Initialize cameras
hs.initializeCams()
#Initialize Instruments, will take a few minutes
hs.initializeInstruments()
#Specify directory to save images in
hs.image_path = 'C:\Users\Public\HiSeqImages\'
#Load stage
hs.move_stage_out()
#Get stage positioning and imaging details for section on flowcell A
pos = hs.position('A', [15.5, 45, 10.5, 35])
#Move stage to imaging position.
hs.z.move([21500, 21500, 21500])
# Set laser intensity to 100 mW
hs.lasers['green'].set_power(100)
hs.lasers['red'].set_power(100)
#Move green excitation filter to optical density 1.4
hs.move_ex('green', 1.4)
#Move red excitation filter to optical density 1.0
hs.move_ex('red', 1.0)
#Find focus
hs.AF = 'partial once'
hs.autofocus(pos)
True
#Move to center of section
hs.x.move(pos['x_center'])
12000
hs.y.move(pos['y_center'])
True
# Take a 32 frame picture, creates image for each channel 2048 x 4096 px
hs.take_picture(32, image_name='FirstHiSeqImage')
#Move stage to the initial image scan position and scan image at 1 obj plane
hs.x.move(pos['x_initial'])
10000
hs.y.move(pos['y_initial'])
True
hs.scan(pos['n_scans'], 1, pos['n_frames'], image_name='FirstHiSeqScan')

TODO:

Double check gains and velocity are set in take_picture

Classes

class pyseq.__init__.HiSeq(name='HiSeq2500', Logger=None, com_ports=None)¶

Illumina HiSeq 2500 System

Attributes:

x (xstage): Illumina HiSeq 2500 :: Xstage.
y (ystage): Illumina HiSeq 2500 :: Ystage.
z (zstage): Illumina HiSeq 2500 :: Zstage.
obj (objstage): Illumina HiSeq 2500 :: Objective stage.
p[‘A’] (pump): Illumina HiSeq 2500 :: Pump for flowcell A.
p[‘B’] (pump): Illumina HiSeq 2500 :: Pump for flowcell B.
v10[‘A’] (valve): Illumina HiSeq 2500 :: Valve with 10 ports for flowcell A.
v10[‘B’] (valve): Illumina HiSeq 2500 :: Valve with 10 ports for flowcell B.
v24[‘A’] (valve): Illumina HiSeq 2500 :: Valve with 24 ports for flowcell A.
v24[‘B’] (valve): Illumina HiSeq 2500 :: Valve with 24 ports for flowcell B.
lasers[‘green’] (laser): Illumina HiSeq 2500 :: Laser for 532 nm line.
lasers[‘red’] (laser): Illumina HiSeq 2500 :: Laser for 660 nm line.
f (fpga): Illumina HiSeq 2500 :: FPGA.
optics (optics): Illumina HiSeq 2500 :: Optics.
cam1 (camera): Camera for 558 nm and 687 nm emissions.
cam2 (camera): Camera for 610 nm and 740 nm emissions.
T (temperature): ARM9 CHEM for stage and temperature control.
logger (logger): Logger object to log communication with HiSeq.
image_path (path): Directory to store images in.
log_path (path): Directory to write log files in.
tile_width (float): Width of field of view in mm.
resolution (float): Scale of pixels in microns per pixel.
bundle_height: Line bundle height for TDI imaging.
nyquist_obj: Nyquist sampling distance of z plane in objective steps.
channels: List of imaging channel names.
AF: Autofocus routine, options are full, partial, full once, partial once, or None, the default is partial once.
focus_tol: Focus tolerance, distance in microns.
stack_split: = Portion of image stack below optimal focus object step, default is 2/3
overlap: Pixel overlap, the default is 0.
overlap_dir: Pixel overlap direction (left/right), the default is left.
virtual: Flag for using virtual HiSeq
fc_origin: Upper right X and Y stage step position for flowcell slots.
scan_flag: True if HiSeq is currently scanning
current_view: Block run to show latest images, otherwise is None

autofocus(pos_dict)¶: Find optimal objective position for imaging, True if found.

autolevel(focal_points, obj_focus)¶

Tilt the stage motors so the focal points are on a level plane.

# TODO: Improve autolevel, only makes miniscule improvement

Parameters: - focal_points [int, int, int]: List of focus points. - obj_focus: Objective step of the level plane.

Returns: - [int, int, int]: Z stage positions for a level plane.

check_COM()¶: Check to see COM Ports setup sucessfully.

initializeCams(Logger=None)¶: Initialize all cameras.

initializeInstruments()¶: Initialize x,y,z, & obj stages, pumps, valves, optics, and FPGA.

message(*args)¶

Print output text to logger or console.

If there is no logger, text is printed to the console. If a logger is assigned, and the first argument is False, text is printed only the log, otherwise text is printed to the log & console.

move_inlet(n_ports)¶: Move 10 port valves to 2 inlet row or 8 inlet row ports.

move_stage_out()¶: Move stage out for loading/unloading flowcells.

obj_stack(n_frames=None, velocity=None)¶

Take an objective stack of images.

The start and stop position of the objective is set by hs.obj.focus_start and hs.obj.focus_stop.

Parameters:

n_frames (int): Number of images in the stack.
velocity (float): Speed in mm/s to move objective.

Returns:

array: N x 2 array where the column 1 is the objective step the frame was taken and column 2 is the file size of the frame summed over all channels

optimize_filter(pos_dict, init_filter, n_filters)¶

Image a section with different filters.

Images a section with all possible excitation filter set combinations. The highest OD filters (lowest light intensity) are imaged first. Lower OD filters are sequentially used to image the section. The laser is blocked with the last filter. Upon completion of imaging, users can inspect the images to ascertain which filter set is optimal.

Parameters:

pos_dict (dict): Dictionary of stage position information
init_filter (int): Descending order position of highest OD filter
n_filters (int): Number of filters to use for imaging

position(AorB, box)¶

Returns stage position information.

The center of the image is used to bring the section into focus and optimize laser intensities. Image scans of sections start on the upper right corner of the section. The section is imaged in strips 0.760 mm wide by length of the section long until the entire section has been imaged. The box region of interest surrounding the section is converted into stage and imaging details to scan the entire section.

key	description
x_center	The xstage center position of the section.
y_center	The ystage center position of the section.
x_initial	Initial xstage position to scan the section.
y_initial	Initial ystage position to scan the section.
x_final	Last xstage position of the section scan
y_final	Last ystage position of the section scan
n_tiles	Number of tiles to scan the entire section.
n_frames	Number of frames to scan the entire section.

Parameters:

AorB (str): Flowcell A or B.
box ([float, float, float, float]) = The region of interest as x&y position of the corners of a box surrounding the section to be imaged defined as [LLx, LLy, URx, URy] where LL=Lower Left and UR=Upper Right corner using the slide ruler.

Returns:

dict: Dictionary of stage positioning and imaging details to scan the entire section. See table above for details.

px_to_step(row, col, pos_dict, scale)¶

Convert pixel coordinates in image to stage step position.

Parameters:

row_col ([int,int]): Row and column pixel position in image.
pos_dict (dict): Dictionary of position data
scale (int): Scale factor of imaged

Returns:

[int, int]: X-stage and Y-stage step position respectively.

reset_stage()¶: Home ystage and sync with TDI through the FPGA.

scan(n_tiles, n_Zplanes, n_frames, image_name=None)¶

Image a volume.

Images a zstack at incremental x positions. The length of the image (y dimension) remains constant. Need a minimum overlap of 4 pixels for a significant x increment.

Parameters:

n_tiles (int): Number of x positions to image.
n_Zplanes (int): Number of Z planes to image.
n_frames (int): Number of frames to image.
image_name (str): Common name for images, the default is a time stamp.

Returns:

int: Time it took to do scan in seconds.

take_picture(n_frames, image_name=None)¶

Take a picture using all the cameras and save as a tiff.

The section to be imaged should already be in position and optical settings should already be set.

The final size of the image is 2048 px wide and n_frames * self.bundle_height px long. The images and metadata are stored in the self.image_path directory.

Parameters:

n_frames (int): Number of frames in the images.
image_name (str, optional): Common name of the images, the default is a time stamp.

Returns:

bool: True if all of the frames of the image were taken, False if there were incomplete frames.

twoscan(n)¶

Takes n (int) images at 2 different positions.

For validation of positioning.

write_metadata(n_frames, image_name)¶

Write image metadata to file.

Parameters:

n_frames (int): Number of frames in the images.
bundle (int): Line bundle height of the images.
image_name (int): Common name of the images.

Returns:

file: Metadata file to write info about images to.

zstack(n_Zplanes, n_frames, image_name=None)¶

Take a zstack/tile of images.

Takes images from all channels at incremental z planes at the same x&y position.

Parameters:

n_Zplanes (int): Number of Z planes to image.
n_frames (int): Number of frames to image.
image_name (str): Common name for images, the default is a time stamp.

Returns:

int: Time it took to do zstack in seconds.