Basic Tutorial

Cell Sampler

---

• Cell Sampler
  • Basic Tutorial
    • Prerequisites
    • Example Dataset
    • Display Modes
    • Starting the Plugin and Opening a TIFF Movie
    • Button Help
    • Exiting the Plugin
    • Zooming, Frame Navigation and the Default View
    • Placing a Region-of-Interest (ROI) for Sampling
    • Saving the ROI Coordinates to File
    • Opening the ROI Coordinates File
    • ROI Navigation
    • ROI Deletion
    • Plotting the Time Series
    • Specifying a ROI for Export
    • Setting ROI Type
    • Feature Overlay File
    • Exporting Time Series
    • Copying Projects between Computers

---

Basic Tutorial

Prerequisites

• Install the Cell Sampler/ImageJ bundle (see [Installation]).
• Download Example Dataset.
• Download Example Overlay File.

Example Dataset

Download Example Dataset

The example data-set consists of a TIFF movie.
This movie has 172 noisy frames (110x162 px), each frame contains 6 bright Regions-Of-Interest (ROI) whose intensity varies sinusoidally overtime. Each bright region represents a cell-like feature. Each frame is placed in a unique file ordered numerically by file name. An example of a frame from this example data-set is shown below. This example data-set was created with ImageJ.

A single frame from the example data set showing 6 bright Regions-Of-Interest.

Display Modes

The plugin can be started in 3 modes called Cell Sampler, Cell Sampler Lazy and Cell Sampler Mono. These modes relate to how the software opens and displays the imaging data. If the plugin is started with Cell Sampler or Cell Sampler Lazy, the imaging data is displayed in 2 windows. These windows are labeled Raw and Processed. Imaging data is always sampled from the Raw window. The Processed window allows filters to be applied to a movie to segment a cellular feature against the background. Navigation and user interaction between the 2 windows is linked. Applying a filter to the processed window is demonstrated in this screen shot of the plugin. The greyscale TIFF movie is display in the left Raw Image window. The right Processed window was smoothed and a colour table applied to the imaging data to find areas of high pixel intensity (i.e. cellular features). Cell Sampler Mono opens a TIFF movie a single window titled Raw.

If you require two linked Image Windows and the TIFF movie is large, it is recommended to start the plugin using Cell Sampler Lazy. This option opens a movie as a virtual stack, thereby reducing the memory needed to display an image for a small drop in performance.

Starting the Plugin and Opening a TIFF Movie

N/B Only one instance of the Cell Sampler plugin can run within ImageJ.

1. Download and unzip the example data set for this tutorial.
2. Create an directory to store output files created by the plugin.
3. Start ImageJ. If using a Mac click on ImageJ.app or if on a PC, click on ImageJ.exe. These files are found in the root directory of the software.
4. From the Main menu of ImageJ, select Plugins->Cell Sampler.
5. A Start Window appears containing 2 buttons. Without clicking, hover your mice over the left button. A message will appear saying Open TIFF Directory.
6. Click on the left button to open a File Dialog window.
7. Choose the directory where your TIFF images are located. For this tutorial, select the directory test_data1, which contains the example images.
8. Press the Choose button to select that directory.
9. If you press Cancel or the selected directory contains no TIFF images, you will get a warning message.
10. The plugin will load TIFF movie, opening 3 windows. Two of the windows will be standard ImageJ image windows. The third window is the Cell Sampler Window.
11. By default, all of the windows will be centrally positioned onscreen. Arrange the window so that you can see all the windows. When zooming an image, ImageJ will enlarge the display window. Position the imaging windows so your view is not obscured while zooming. This principle is shown by the 2 images below.

Image: Cell Sampler plugin with 2-opened imaging windows, centrally positioned to permit zooming.

Image: Cell Sampler plugin with 2-opened imaging windows, images magnified by 200%.

N/B Sometimes ImageJ will hang when trying to load images. If this occurs you may have too many applications open and ImageJ has not enough memory to open a movie. When using ImageJ, close as many superfluous applications as possible so that ImageJ will run with the optimum performance.

Button Help

The Cell Sampler Window has a lot of buttons. The icon of the button is indicative of the function that the button performs.
To get a text description of a button's function, without clicking place your mouse over the button icon. A short context-sensitive message will appear below the button, describing its general function.

Exiting the Plugin

• The plugin opens several windows within ImageJ.
• The management of these windows is controlled by the plugin, rather than ImageJ.
• To close these windows, select the File->Exit option in the Cell Sampler Window.
• If you have positioned ROI on a movie, the plugin will ask to Save the Sampled ROI before exiting.
• If you try to close an opened window without Exiting from the Cell Sampler Window, the plugin will display a warning message.
• If filters were applied to the TIFF movie to enhance the imaging data, when closing the plugin will never attempt to save the modified file.

Zooming, Frame Navigation and the Default View

N/B Slice = Movie Frame

If the plugin is closed, open the plugin as described in Starting the Plugin and Opening a TIFF Movie.

1. When the plugin starts initially, zooming is switched on and linked to mouse click on a image. Click on the 'Raw' image window twice in the top left corner of that window. This will perform a 200% zoom in both imaging windows.
2. Zooming can be toggled off or on by clicking on the Zoom On or Zoom Off buttons.
3. Click on the Cell Sampler Window and use the horizontal scrollbar to move through the movie. For more accurate navigation, use the arrows on the scrollbar. You will see both image windows scroll through the movie frames.
4. Move the scrollbar to navigate to the middle on the movie.
5. To return to Frame 1 you can use the scrollbar or the Default View button.
6. Initially clicking on Default View button does nothing. The navigation option of this button need to be enabled.
7. To enable the Default View button, click on the Settings Button to display the Settings Window.
8. Check the options Go to Slice 1 on Default View and Unzoom on ROI navigation and click on the Ok button.
9. Click on "Default View Button", the Image windows will return to Frame 1 and the default aspect ratio (unzoom) when the movie was initially opened.

Placing a Region-of-Interest (ROI) for Sampling

Placing a ROI means that you have found a cellular feature that you wish to track and sample.
Sampling collects 2 sets of information about a ROI, the average pixel intensity in the ROI and the ROI position per frame in the movie.
ROI used by this plugin are all circular in shape.

N/B ROI position and size can be modified after initial placement.

1. Before placing ROI on a image, inspect the Image data and assess how big the default ROI needs to be when placed over a cell. The default diameter of a cell is assumed to be 6 pixels.
2. To change the default ROI size, click on the Settings Button to display the Settings Window.
3. Select an appropriate value from the Default ROI Size (px) option and click Ok. Default size can range from 3-12 pixels. For the best placement of a ROI, an even-numbered size is recommended as ROI are placed relative to the pixel grid of a image.
4. Click on the Zoom On button to activate the zoom function.
5. Click on the processed window twice to do a 200% magnification of the Image.
6. Click on the Add ROI On button (green circle) to switch on the Add ROI option. You will notice that the zooming option is now inactive.
7. Place focus on the Processed image window by clicking once on the window title.
8. Slowly move the mouse cursor onto the image surface and in the middle of topmost bright most bright region.
9. Click once with your mouse, a ROI is placed on the plotting surface. This region is labelled as _ 1 _. Each ROI added to an image is given a unique, sequential, integer identifier.
10. When a ROI is placed on one image window, it is immediately echoed in the second. There is a 1 second delay between ROI placement.
11. Place a ROI each of the bright regions of the image. The display of the Raw Window should look similar to this image.

Saving the ROI Coordinates to File

This software does not provide an Undo option.
It is recommended that you have your work periodically.
If you close and exit the plugin, you will be prompted if you wish to save your work.

To save the ROI coordinates to file, do the following.

1. This software will only save ROI coordinates if ROI are placed on a movie.
2. Place ROI on the TIFF movie and create (if necessary) an output directory for files generated by this plugin.
3. In the Cell Sampler Window, select the File->Save ROI option from the menu.
4. A File dialogue appears asking to you to Select XML File for ROI.
5. Use the file dialogue to navigate to your output directory.
6. The output file name is preset, using the directory name where the imaging data is stored as the default file stem. You can specify your own file name.
7. If you have used example dataset, the XML file is called test_data1.xml.
8. Click on the Save button to save your work to file. If you press Cancel, the plugin displays a warning message.
9. ROI coordinates/types/export status, colour selections, default ROI size and paths to the source images are written to file. The XML is a text file format and so saved file can be opened with any standard text editor.
10. If normally takes just a couple of second to save the file. A dialogue will appear when the save has completed.

Opening the ROI Coordinates File

To open an existing XML file created by the Cell Sampler plugin, specifying the position of ROI in a TIFF movie, do the following.

1. If the Cell Sampler plugin is open, close the plugin as described in Exiting the Plugin.
2. Start ImageJ and from the main menu, select File->Plugins->Cell Sampler option.
3. The Start Window appears containing 2 buttons. Without clicking, hover your mice over the right button. A message will appear saying Open Saved ROI XML File.
4. Use the File Dialogue to select a XML file created by the Cell Sampler plugin.
5. Click Open to load the TIFF images and the ROI coordinates data.
6. If Cancel is pressed, the plugin will display a warning message.

ROI Navigation

For each ROI placed on a image, a number of operations can be performed on a ROI such as plotting the time series or re-positioning the ROI in a frame of the movie.
These operations are performed on the active ROI id.
The currently active ROI id and its coordinates in frame 1 of a movie are displayed in the Cell Sampler Window. This plugin provides a number of options to navigate around the ROI placed on a movie.

1. Click on the Hide ROI button. This option leaves only the active ROI in the Image Window.
2. Click on the Show ROI button to redisplay all of the ROI in the Image Windows.
3. To move through the ROI list, use the black navigation arrows on the Cell Sampler Window. ROI navigation is circular.
4. Click on the navigation arrows to move through the ROI list.
5. If the appropriate settings are specified, the Image Windows Try this with ROI Hidden and ROI Shown. If the option is specified in the Settings Window, ROI navigation will unzoom the image window(s) and reset the movie back to Frame 1.
6. Click on the Go to ROI button and enter a ROI id. Click Ok to the active ROI. This option is useful if you do not wish to scroll through a lengthy list.

ROI Deletion

1. To delete a ROI placed on a movie, use the navigation controls to set the ROI as the active ROI.
2. Click on the Delete ROI button.
3. The ROI is deleted. Be warned that there is no Undo option in this software.
4. When a ROI is deleted, the active ROI becomes the previous ROI in the list.

Plotting the Time Series

1. To plot the time series associated with a ROI, use the navigation controls to set the ROI as the active ROI.
2. Click on the Show Plot button to display a graph. The graph window is resizable.
3. Moving the mouse cursor over the graph surface will display the time index and intensity value.
4. Clicking on the graph surface at a specific time index will cause to Image window(s) to display that frame from the source movie.
5. When a plot is showing, click on the Hide Plot button to close the graph.
6. If ROI position is modified, the graph is not automatically updated. To re-plot a graph click the Hide Plot and Show Plot buttons.
7. The active ROI can be reset via the navigation controls. If a graph is displayed whilst changing the active ROI, the plot updates automatically.

Specifying a ROI for Export

1. To specify that a ROI is for export, set the appropriate Keep? flag on the Cell Sampler Window.
2. By default, all ROI placed on a movie are flagged for export.
3. Setting Keep? to No means that the ROI in the Image Window(s) is coloured black.
4. Setting Keep? to Maybe means that the ROI in the Image Window(s) is coloured blue.
5. Setting Keep? to No means that the ROI time series is never exported into final dataset created by the plugin.
6. When changing the Keep? state of a ROI, the running total of ROI to be included in the exported dataset is echoed in the Cell Sampler Window.

Setting ROI Type

1. Each ROI placed on a movie can be assigned a type, i.e. a broad classification of the cellular feature based on position or time series topology.
2. The default value for type is Unspecified.
3. The list of available types is found in the file ~/plugins/Cell_Types.csv located in the ImageJ installation root directory.
4. This file must be present and have at least one category defined otherwise the plugin will not work.
5. To specify your own type categories, update the the category list contained in this file.
6. The default type (e.g. Unspecified) is always the first in the list located in ~/plugins/Cell_Types.csv.

Feature Overlay File

The plugin can load and display coordinates from an overlay file. An overlay file consists of a text CSV file containing 2 columns of numbers. The numbers are the cartesian coordinates (x,y) of a features found in the first frame of a TIFF movie.

To use a overlay file with this tutorial's example data-set, do the following:-

1. Download the Example Overlay File and place this file in your output directory.
2. Start ImageJ and either load the example data-set or load the saved ROI XML file.
3. Click on the Show Overlay, a file dialogue window will appear.
4. Select the overlay file and click Open. If you press Cancel the plugin will report an error.
5. Circles will appear, showing the position of flagged features.
6. Unlike manually placed ROI, overlay features are not numbered.
7. The display of the overlay can be toggled off or on by using the Show Overlay / No Overlay buttons.
8. Image: Overlay file displayed by the plugin is shown. Red circles use coordinates from the overlay file, numbered yellow circles are manually placed ROI.
9. The colour and size of the overlay can be modified by using the Overlay Colour and Default ROI Size options in the Settings Window.
10. Click on the the Settings Button to show the Settings Window.

Exporting Time Series

To export the time series obtained from a movie to file, do the following:-

1. In the Cell Sampler Window, select the File->Export Time Series option from the menu. If the movie has no ROI, the plugin will flag an error.
2. A file dialogue appears stating to Choose a Directory for Time Series. The plugin creates several files when exporting time series, hence it asks for a directory.
3. Click Choose to start the export. If Cancel is pressed, the plugin will display an error.
4. For a large movie with many sampled ROI, it can take up to 30 seconds to generate the output files. The progress bar on the bottom of the Cell Sampler Window can be used to follow the status of the export.
5. An dialogue window will appear when the export is complete.
6. The shared file stem of the generated files is set by the file name used to save the ROI XML file (see Saving The ROI Coordinates to File).

The exported time series files for this tutorial are found here.

A list of the output files containing the time series and positional information derived from the example data-set (test_data1) is listed below.

Output File	Contents
test_data1.xml	The XML file containing the sampling ROI manually set by a user using the Cell Sampler plugin.
test_data1_intensities.csv	Column-major spreadsheet containing time series derived from the imaging data. First row of spread is Cell Identifiers. Second row of spreadsheet is the specified cell type. Third row of spreadsheet is the cell position at frame 1 of a movie. The remaining rows is the time series data.
test_data1_intensities2.csv	Row-major spreadsheet containing only time series derived from the imaging data. Time series related to positional information by index number.
test_data1_dim.csv	The dimension of the exported time series (No. Exported cells x No. Frames).
test_data1_mask.csv	A binary masking file to differentiate cells flagged as 'Yes' or 'Maybe'.
test_data1_id.csv	A list of ROI numerical identifiers exported. Identifiers related to time series/positional data by index number
test_data1_xy.csv	The positional information of each tracked ROI in a movie. Used to record cell movement.
test_data1_averages.csv	Average background image intensities of each frame in a movie

Copying Projects between Computers

The Cell Sampler plugin is cross-platform as the plugin/ImageJ software bundle will run on both Mac and Windows computers.
A XML file of ROI coordinates (i.e. a project) created by the plugin is transferable between different computers.

To copy a project between different computers, do the following:-

1. Copy the imaging data between the 2 computers and take note of the path of the destination directory. If the plugin cannot load the TIFF images of a movie when it opens a project XML file, it will report an error.
2. Update the path to the source images in the ROI XML, do this by editing the XML file created by the plugin.
3. Open the XML file in a text editor (e.g. Notepad/TextEdit).
4. Update the image path within the directory tags with the new directory path on the destination computer. An example of the directory tag is shown below. When updating the directory path, its safest to forward slash "/" when specifying the delimiting the path components. Always specify the absolute path a the image directory.
5. To find the directory tag in the XML document, use the text editor search function (e.g. Ctrl+f) or scroll down to the bottom of the XML document.

<directory>/Users/auser/Images/SCN Slice-1</directory>

---