Arbitrary Line Scanning

../_images/lscan.png

ScanImage® 2016 introduces a new way to utilize a linear scanning (galvo-galvo) microscope for fast imaging. Building upon the robust ScanImage® multi ROI core, Arbitrary line scanning enables high speed sampling of desired ROIs by reducing time spent scanning areas of little interest in the sample. If the locations of desired ROIs are already known and you are only interested in how the fluorescence at specified points is changing over time, an arbitrary path can be configured to sample the desired points at high speed, as opposed to raster scanning the entire field which is much slower. Depending on the duration of the scan path (dictated by the number and spread of ROIs to be scanned) arbitrary line scanning can sample the entire scan path at rates upwards of 200 Hz, allowing you to capture fluorescence transients. The scan path can be designed in 2D or 3D, enabling use of a fast Z actuator for arbitrary volume scanning. In addition to recording fluorescence signals, the line scanning feature includes the ability to record and show in real-time the actual positions of the scan mirrors to ensure that they are accurately hitting the desired ROIs.

Hardware Requirements

The arbitrary line scanning scanning feature supports the same hardware used for regular linear scanning. In order to utilize the scan mirror position recording, an auxiliary DAQ must be present and the galvo position signals must be on a different DAQ than the photo-detector signals.

Using Arbitrary Line Scanning in ScanImage

To utilize arbitrary line scanning, select a linear scanning system as the active imaging system on the CONFIGURATION interface, then select Line Scan as the scan type. The Channel Display Window will change to suit arbitrary line scanning.

../_images/als1.png

Before starting a scan, a scan path must be configured. You can do so by selecting Edit ROIs

The scan path is designed as a stimulus group, the same way photostimulation patterns are designed. Stimulus groups are a special kind of ROI group that define a parametric path instead of a 3D volume. A stimulus group is comprised of multiple ROIs that define a continuous sequential laser path.

Scan Path Design

Stimulus groups allow complete freedom in designing the path for the laser to take. Best practices should be followed to ensure desired results. A stimulus pattern is comprised of a sequence of stimulus functions, each of which can be parameterized with position, size, rotation, laser power, number of repeats, parametric function, and custom parameters for the parametric function. The stimulus function can be chosen from a set of built in or custom stimulus functions.

A typical stimulus pattern should consist of pause functions interleaved with stimulus functions at desired positions, IE:

  • Pause function

  • Sinesquare function

  • Pause function

  • Logspiral function

  • Pause function

  • Point function

The pauses between stimulations are important because the galvo’s require time to travel between ROIs. Without the pauses (or if the pauses are too short), the pockels cell will be open while the galvo is still traveling to the desired ROI, causing light exposure to the wrong part of the sample. If too large of a change in position is commanded without adequate transit time, or if the stimulus pattern is too demanding of performance from the galvo’s, the galvo controller may reset, causing a momentary loss of galvo position control. It is therefore important to carefully design the stimulus pattern to avoid this and test the pattern to make sure the results are desirable.

Note

Utilizing the Monitor Scanner Feedback on the CONFIGURATION interface is a good way to verify the galvos are able to follow the designed path.

This is shown below.

Waypoints are a special stimulus function that can be very useful for designing a scan path. If there is a point you are interested in sampling data at, you could place a point stimulus function there. This would cause the scan mirrors to move to that point and stop there for the specified duration. It is much faster, however, to pass through the point without stopping, just exposing the beam over the point. This can be achieved using a waypoint function. Waypoints constrain the path to pass through the desired position with the beam exposed for the desired duration as the scan mirrors pass through the point.

If it is desired to create a custom stimulus function of a user-defined shape, please see the page on writing custom stimulus functions.

Using the Stimulus Editor

In the stimulus editor, an image can be copied in to serve as a context for designing the stimulus pattern. You can show a context image from the legend by turning on the live image, taking a snap shot, or loading an image from a tiff file.

To add a stimulus function, click the Add ROI… button under the table display. You select parameters for the stimulus function from the panel in the bottom right then draw the desired function in the main view. The Quick Add panel in the bottom right can also be used to easily add pause and park functions. The sequence of stimulus functions is displayed in the table view. The controls below can be used to reorder or remove functions. Select a stimulus function in the table or in the main view to view its parameters in the bottom right. A complete reference for the stimulus editor interface can be found in the window reference guide.

../_images/als2.png

  1. Overlay a reference image (not shown)

  2. Add ROI

  3. Select function and its parameters

  4. Draw on the reference image

  5. Add pause before repeating steps 2-4

  6. Sequence of stim functions is viewable here, and parameters of each can be altered from box 3 after checking its box

The screen shot below shows an example of designing a scan path using way points and a sine square to sample a larger area of interest.

../_images/waypoins.png

One scan of the complete path is referred to as a cycle or frame. The Cycle Rate on the CONFIGURATION interface indicates how fast cycles can be scanned (dictated by the total time duration of the path you have designed).

../_images/als4.png

Executing a Line Scan

At this point you can start a FOCUS, GRAB, or LOOP from the MAIN CONTROLS interface. These operations function the same way they do for normal raster scanning. A FOCUS will run the scan path continuously to display data only. A GRAB will run the scan for the specified number of cycles and log data to disk if logging is enabled. You can specify the number of cycles to run by setting the number of frames to collect on the MAIN CONTROLS interface. A LOOP will execute multiple GRAB sessions. 3D scanning is enabled during GRAB and LOOP if the designed path is 3D and the fast Z feature is enabled from the FAST Z CONTROLS interface.

Verifying the Scan Path

Position feedback can be enabled to log to disk and show in real time the actual path scanned by the mirrors. This can be useful to ensure the scan mirrors are achieving the desired path. Before using position feedback for the first time, the sensors must be calibrated by clicking Calibrate Feedback Sensors on the CONFIGURATION interface. Then select “Monitor Scanner Feedback”

../_images/als3.png

Reading Line Scanning Data Files

The data is written to disk in multiple files to facilitate efficient processing. This helps enable higher sample rates due to low processing overhead. Each line scanning GRAB session will create 3 files:

  • [File name stem][File counter].meta.txt (Ex: filename_00001.meta.txt): Plain text file containing metadata describing the ScanImage® parameters and stimulus pattern used for the scan

  • [File name stem][File counter].pmt.dat (Ex: filename_00001.pmt.dat): Binary data file containing the collected fluorescence data

  • [File name stem][File counter].scnnr.dat (Ex: filename_00001.scnnr.dat): Binary data file containing the collected scanner position feedback data (only created if position monitoring is enabled)

ScanImage® includes a utility function to read these files and load the data into a convenient structure.

Using the ScanImage® Utility

The ScanImage® utility to load a data file can be called with the following signature:

1>> [header, pmtData, scannerPosData, roiGroup] = scanimage.util.readLineScanDataFiles(fileName)

The meta data and data files should exist in the same directory and fileName should be entered without the extension (ex: “filename_00001”). The return values are the following:

  • header: A hierarchical data structure containing the ScanImage parameters used when the data was collected as well as useful statistics about the total number of samples and frames collected and sample rate information. Reference the ScanImage API for more information about the contents of data log headers.

  • pmtData: A matrix of the collected fluorescence data organized by channel and frame. The size of the matrix is NxCxF where N is the number of samples per scan cycle, C is the number of channels, and F is the number of frames (cycles) collected. Index this array appropriately to extract the data you are interested in. To plot data collected during the 100th frame on channel 2, for instance, you could do the following:

1% squeeze is needed to remove the first dimension since it becomes singleton
2plot(squeeze(pmtData(:,2,100)));

To plot data at point 600 from channel 1 over every frame (ie a plot of how fluorescence at a single point is changing over time) you could do the following:

1% squeeze is needed to remove the third dimension since it becomes singleton
2plot(squeeze(pmtData(600,1,:)));

  • scannerPosData: If scanner position monitoring was on, a structure with a fields “G” and “Z” containing matrices for recorded scanner position data for scan mirrors and the Z actuator respectively. The size of the G matrix is Nx2xF where N is the number of data points per cycle and F is the number of frames collected. The columns correspond to the X and Y mirrors. The size of the Z matrix is Nx1xF where N is the number of data points per cycle and F is the number of frames collected. To plot the path of the X scan mirror collected during the 100th frame, for instance, you could do the following:

1% squeeze is needed to remove the first dimension since it becomes singleton
2plot(squeeze(scannerPosData.G(:,1,100)));

To plot the position of the Y scan mirror at point 600 from over every frame (ie a plot of the repeat-ability of scan mirror position at that point in the path) you could do the following:

1% squeeze is needed to remove the third dimension since it becomes singleton
2plot(squeeze(scannerPosData.G(600,2,:)));

Note

Recording scanner feedback data for the Z actuator is not yet supported

  • roiGroup: A copy of the stimulation pattern that was used to collect the data. Reference the ScanImage API for more information about how to work with ROI Group objects.

Manually Decoding Data Files

If it is desired to write your own code to load the files (for instance if you need to perform analysis outside of MATLAB) the following provides information about how to read the files.

  • Metadata File: (Ex: filename_00001.meta.txt): This is a plain text file. If the option is enabled to store metadata in JSON format, there will be two JSON structures. The first will be a hierarchical data structure containing the ScanImage® parameters used when the data was collected. The second structure will be a data structure representing the stimulus pattern that defines the scan path used to collect the data. If the JSON option is not enabled, the ScanImage parameters will be written with “dot” syntax to represent the data sctructure, ie:

SI.hScan2D.sampleRate = 1.2e+08

In this case, the stimulation pattern info following the ScanImage parameter data will still be JSON. You can detect if the ScanImage data is stored as JSON by checking if the first character of the file it “{“.

  • Fluorescence Data File: (Ex: filename_00001.pmt.dat): This file contains raw binary data of samples written as signed 16-bit integers. The order that samples are written is:

[Channel 1 Sample 1, Channel 2 Sample 1, ..., Channel N Sample 1,
Channel 1 Sample 2, Channel 2 Sample 2, ..., Channel N Sample 2, ...,
Channel 1 Sample M, Channel 2 Sample M, ... Channel N Sample M]

where N is the number of channels and M is the number of samples per channel. The number of channels can be found in the header by counting the number of elements in SI.hChannels.channelSave. The number of samples per frame can be found at SI.hScan2D.lineScanSamplesPerFrame. The acquisition sample rate can be found at SI.hScan2D.sampleRate.

  • Scanner Position Feedback Data File: (Ex: filename_00001.scnnr.dat): This file contains raw binary data of samples written in single precision. The order that samples are written is:

[Channel 1 Sample 1, Channel 2 Sample 1, ..., Channel N Sample 1,
Channel 1 Sample 2, Channel 2 Sample 2, ..., Channel N Sample 2, ...,
Channel 1 Sample M, Channel 2 Sample M, ... Channel N Sample M]

where N is the number of channels and M is the number of samples per channel. The number of channels can be found in the header at SI.hScan2D.lineScanNumFdbkChannels. For a 2D scan there will be two channels: X and Y. For a 3D scan there will be three channels: X, Y, and Z. The number of samples per frame can be found at SI.hScan2D.lineScanFdbkSamplesPerFrame. The feedback sample rate can be found at SI.hScan2D.sampleRateFdbk.

Analysis

Starting in SI Premium 2018a and SI 5.4 , the Offline Data Viewer is an option for analyzing data acquired from a previous acquisition. The tool allows you to easily create plots to show the change in fluorescence over time for a given pixel or area.

It is accessed via command window by execucting the command:

1>> sidataview

Learn more about SIDataView

../_images/lsdv.PNG