ShuttleTracker: Difference between revisions

From Laboratory of Modeling in Biology and Medicine
Jump to: navigation, search
mNo edit summary
mNo edit summary
 
(90 intermediate revisions by the same user not shown)
Line 1: Line 1:
<div align="center">'''A software for semi-automated cell tracking'''</div><br />
<div align="center">'''An interactive tool for analyzing nucleocytoplasmic shuttling<br/> of fluorescent reporters<!-- in living cells-->'''</div><br />
<div align="center">
<div align="center">
<div align="left" style="width:520px">
ShuttleTracker can detect stained cell nuclei, generate corresponding
annular perinuclear extensions, measure geometric and photometric properties of detected
objects, and perform frame-to-frame nuclei tracking.&nbsp; Parameters of
the underlying image processing algorithms can be changed manually
and the effects of these changes can be seen nearly immediately
overlaid on currently displayed microscopic images.&nbsp; A key capability
of ShuttleTracker is that nuclear contours and tracks can be generated
automatically and then corrected manually.
</div></div><br/>


[[Image:ShuttleTracker_montage.png|link={{SERVER}}/images/7/7e/ShuttleTracker_montage.png|500px]]


<accordion parent="accordion" heading="Complete manual">
<div align="left" style="width:520px">
 
S<span style="font-variant:small-caps">huttle</span>T<span style="font-variant:small-caps">racker</span> can detect stained cell nuclei, generate corresponding annular perinuclear extensions, quantify geometric and photometric properties of detected objects, and perform frame-to-frame nuclei tracking.&nbsp; Parameters of the image processing algorithms can be changed manually and the effects of these changes can be seen nearly immediately overlaid on currently displayed microscopic images.&nbsp; A key capability of ShuttleTracker is that nuclear contours and tracks can be generated automatically and then corrected manually. The tool is scriptable. <br/><br/>
<h1>ShuttleTracker &ndash; User's manual</h1>
The latest S<span style="font-variant:small-caps">huttle</span>T<span style="font-variant:small-caps">racker</span> version is '''1.5.3''' (February 2023).
 
</div></div>
 
<br/><br/>
<h1 id="h1_overview">Overview</h1>
 
<!-- Thank you for giving ShuttleTracker a chance! -->
 
<h2 id="h2_capabilities">Overview: Capabilities</h2>
<p>
ShuttleTracker (permalink to homepage:
<!-- a href="http://pmbm.ippt.pan.pl/software/shuttletracker"-->
<span class="tt">http://pmbm.ippt.pan.pl/software/shuttletracker</span><!-- /a -->)
can detect stained cell nuclei, generate corresponding annular perinuclear
extensions, measure properties of detected objects, and perform frame-to-frame
nuclei tracking.
Parameters of the underlying image processing algorithms can be changed manually
and the effects of these changes can be seen nearly immediately overlaid on
currently displayed microscopic images.
A key capability of ShuttleTracker is that nuclear contours and tracks can be
generated automatically and then corrected manually.
</p>
<p>
Detailed quantitative analysis of properties of tracked nuclei and tracks is
out of the scope of the program.
Quantified geometric and photometric properties of nuclei and tracks are
exported to plain-text files that can be easily analyzed using external tools.
A package of Python scripts and example IPython Notebooks are distributed
together with this software to demonstrate exemplary approaches to the analysis
of features quantified in and exported from ShuttleTracker.
</p>
 
 
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 
 
<h1 id="h1_launching">Launching</h1>
 
<h2 id="h2_launching_gui">Launching with GUI</h2>
<p>
Initially, ShuttleTracker displays an "empty" window.
A directory with images to be analyzed can be selected after clicking menu
<i>File</i> &rarr; <i>Open directory...</i> (or by pressing Ctrl + Shift + O).
Image files in the selected directory are expected to be properly named,
see <a href="#h2_input_images_names">naming guidelines</a>.
</p>
 
<h2 id="h2_launching_terminal">Launching from terminal</h2>
<p>
When ShuttleTracker is executed from the command line without additional
arguments, it displays an "empty" GUI window. Optionally, as the argument
one may give a path to a directory with images; ShuttleTracker will then
open GUI and load images.
If one would like to execute a ShuttleTracker script immediately after loading
images, path to the ShuttleTracker script file (<span class="tt">*.stscript</span>)
should be given just after the path to the directory.
After successful script execution, ShuttleTracker will quit.
</p>
<p>
This software has been created with the intent to enable user to interactively
control behavior of image processing algorithms, but it is also possible to
run ShuttleTracker without displaying GUI (in a "headless" mode) and in this
way perform batch processing (e.g., on a cluster). To this end, one should use
ShuttleTracker scripts and invoke the program through a virtual frame buffer
such as Xvfb:
</p>
<pre>  xvfb-run ShuttleTracker PATH_TO_DIRECTORY PATH_TO_SCRIPT</pre>
<!--(of note, Xvfb is installed in the ShuttleTracker Singularity container).-->
 
 
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 
 
<h1 id="h1_input_images">Input images</h1>
 
<h2 id="h2_input_images_names">Input images: File names</h2>
<p>
The following regular expressions are used to fish for images in the selected
directory:</p>
<ul>
  <li>
For a single time-frame:&nbsp;
<span class="tt">^(.+)(?:_ch([0-9]+))\\.(jpe?g|tiff?|png)$</span>
  </li>
  <li>
For multiple time-frames (i.e., a time-lapse serries):&nbsp;
<span class="tt">^(.+)(?:_t([0-9]+))(?:_ch([0-9]+))\\.(jpe?g|tiff?|png)$</span>
  </li>
</ul><p>
In other words, as an example, the following list of files will be understood
correctly:</p><pre>
  MyExperiment_t000_ch0.tif
  MyExperiment_t000_ch1.tif
  MyExperiment_t000_ch2.tif
  MyExperiment_t001_ch0.tif
  MyExperiment_t001_ch1.tif
  MyExperiment_t001_ch2.tif</pre><p>
(and so on). Please note that the index of the time point should be padded with
zeros (in the example it is assumed that more than one hundred but not more
than one thousand of time points is available). Both the index of a time point
and the channel number are 0-based.
</p><p>
If names of your files do not conform the neither of these patterns, please
rename your files. Often, proper naming of files can be assured during conversion:
for example, assume that you have a two-channel movie saved as two multi-layer
TIFF files. In the command line under Linux or Mac, having bash shell and
imagemagick installed, you can use the following method to generate a series of
properly named input images:</p><pre>
  export NFRAMES=100
  for i in $(seq -w 0 $NFRAMES); do
    convert MyMovieChannel1.tif[${i}] -depth 8 MyMMovie_t${i}_ch0.tif
    convert MyMovieChannel2.tif[${i}] -depth 8 MyMMovie_t${i}_ch1.tif
  done
</pre><p>
To split multi-frame TIFFs and simultaneously perform controlled bit depth
conversions you may use a python script <span class="tt">tiff_expander.py</span>
that comes with ShuttleTracker.
Its advantages are described in a subsection on bit depth
<a href="#h2_input_images_bit_depth">below</a>.
</p>
 
<h2 id="h2_input_images_formats">Input images: Image formats</h2>
<p>
ShuttleTracker can read only gray-scale images in the following graphics formats:
TIF (<span class="tt">*.tif</span>, <span class="tt">*.tiff</span>),
PNG (<span class="tt">*.png</span>), and
JPEG (<span class="tt">*.jpg</span>, <span class="tt">*.jpeg</span>; use of
JPEGs in microscopic image analysis is strongly discouraged because they are
compressed using a lossy algorithm that distorts originally recorded pixel
intensities).
</p>
 
<h2 id="h2_input_images_bit_depth">Input images: Bit depth</h2>
<p>
Bit depth of images (i.e., maximum-intensity gray-scale value) depends, i.a., on
the scanner or camera used to record the images.
ShuttleTracker reads bit depth from the metadata associated with the given image
set (see below).
If an image has <i>more than 8-bit</i> gray-scale resolution, its depth is
<i>scaled linearly to 8-bit</i> resolution.
Please note that all image processing and analyses (especially, quantifications)
are performed using 8-bit images<!-- (this is due to the fact that the key routines
in OpenCV work for only single-channel 8-bit images)-->.
</p><!--<p>
If the image does not use intensities from the full range allowed by its
bit depth (especially, if it's "dim"), then nuclei detection algorithms
may have hard time finding nuclear contours.
</p>--><p>
You can perform bit depth conversions with the above-mentioned
<span class="tt">tiff_expander.py</span>.
This python script allows for converting images of any over-8-bit depth to 8-bit
depth with or without "clipping" of the over-the-range values
(clipping can be advantageous, for example, when a 14-bit image, that has
very few pixels of intensity higher than 2^12, is converted to an 8-bit image
by treating it as a 12-bit image, because then more "resolution" in lower-value
pixels will be preserved than in the case of 14-to-8 conversion).
Invoke the script with argument -h or look at the docstring in file header
to learn how to use it.
The script is usually placed in
<span class="tt"><i>INSTALL_PREFIX</i>/shared/shuttletracker/support</span> and
requires python3-pil and python3-numpy.
</p>
 
 
<h2 id="h2_input_images_metadata">Input images: Metadata</h2>
<p>
Metadata are used to:
</p>
<ul>
  <li>establish the mapping between channel number and pseudocolor/LUT,</li>
  <li>declare the bit depth (i.e., greyscale resolution) of the scanner or
      camera used to record the images,</li>
  <li>get the number of time frames and their relative times (in seconds).</li>
</ul>
<p>
Metadata can be read from the MetaData directory which is exported by Leica LAS
software. Information expected to be found in metadata can be also provided
manually &ndash; by creating a file <span class="tt">hints_for_shuttletracker.txt</span>
in the directory that contains images. In an example hints file of the following
contents:
</p><pre>
  channel 0 Protein1-GFP    green 8
  channel 1 Protein2-mCherry red  8
  channel 2 H2B              blue  8
  time_interval 120.3
</pre><p>
first three lines define the mapping from channel number (and mini-description)
to channel LUT (color), and specify bit depth of images.
Color assignments are used only to display images in specific colors in GUI
and may be relevant for generating legible channel overlays (still, within
ShuttleTracker all images can be viewed in greyscale).
In the last line, time interval between frames is provided (in seconds).
This is a free-format text file: the exact number of white-spaces does not
matter; lines can appear in any order.
</p>
 
 
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 
 
<h1 id="h1_viewing">Viewing</h1>
 
<h2 id="h2_viewing_navigation">Navigation</h2>
<p>
After images are loaded, each channel is displayed in a separate pane.
Channels are referred to using their assigned pseudocolors.
One may zoom into/out of a region of an image using mouse scroll and move
around when the left mouse button is pressed.
Fields of view in all channel panes are synchronized to assure that the
corresponding image region is displayed in all panes.
</p><p>
Using menu <i>View</i> one can hide each pane or black out contained image.
Blacking-out is useful when one would like to show only image annotations
(called markings).
When multiple markings occlude microscopic image in the background, one may
also, conversely, hide all markings to display only the microscopic image
(it's convenient to use the spacebar key instead of selecting hide/unhide in
the menu).
</p>
 
<h2 id="h2_viewing_enhanced_view">Enhanced view</h2>
<p>
Microscopic images can be displayed (<i>i</i>) as originally provided,
(<i>ii</i>) with pixel intensities normalized, or weakly (<i>iii</i>) or
(<i>iv</i>) strongly auto-leveled.
Weak (strong) auto-leveling discards 2% (8%) of brightest pixels and performs
normalization of the remaining pixels.
Enhancements (<i>i</i>)&ndash;(<i>iv</i>) are available in the saturated
(pseudocolor) as well as desaturated (grayscale) mode.
</p><p>
Switching to the normalized view enables assessment whether input images have
a reasonable dynamic range.
Auto-leveled mode helps to visually discern darker portions of the image
(after some time you may find yourself falling into the habit pressing of
F7 or F8 just after loading input images).
Desaturated images appear brighter on the screen than their saturated
counterparts and thus may be more convenient to work on.
The enhancements affect only how the images are displayed, and in particular
do not impact image segmentation nor quantification.
</p>
 
 
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 
 
<h1 id="h1_toolboxen">Toolboxen</h1>
<p>
All available toolboxen are available from the Toolbox Menu and, additionally,
from a dockable tool-bar that can be displayed when selected in a pop-up menu
that appears after right-clicking on the main menu bar (under Linux and Windows).
You may find it handy to use keyboard shortcuts Ctrl+1, Ctrl+2, and so on,
to switch between the toolboxen, especially in the full-screen mode (press F11
or use <i>Window</i> menu to enter/exit).
</p><p>
Visibility or "selectability" of objects overlaid over microscopic image depends
crucially on the currently active toolbox.
</p>
 
 
<h2 id="h2_image_masking">Toolbox: Image masking</h2>
<p>
Selected areas of an analyzed image can be masked to get rid of the regions
in the image that should not be analyzed nor quantified (because, for example,
they contain contaminations that would skew analysis).
Masked areas are excluded from segmentation (within Nuclei Detection toolbox)
and whole-image quantification (within Quantification toolbox).
</p><p>
If one wants to mask some portion of the image, one should activate the
Image Masking toolbox, click with right mouse button over the microscopic
image to enter the marking mode and while pressing left mouse button mark
the area to be masked.
Several (non-overlapping) areas can be marked in this way.
To clear all markings, one can use button <i>Reset</i> in the toolbox.
If all desired markings are ready, one can click toolbox button <i>Mask</i> to create
the mask.
Masked areas are blackened out.
Masking contours for a current image can be stored and restored using suitable
buttons at the bottom of the toolbox pane, next to <i>Mask &harr; file</i>.
To create masks for a series of images, each image has to be treated separately.
</p>
 
 
 
<h2 id="h2_nuclei_detection">Toolbox: Nuclei detection</h2>
 
<h3>Image preprocessing</h3>
<p>
Before nuclear contours are detected, the input image has to be preprocessed.
Image preprocessing pipeline consists of the series of filters:
</p><ol>
  <li><b>Normalization</b> linearly stretches the range of intensities of
    all 8-bit image pixels so that they fill the full available intensity range
    (0...255).</li>
  <li><b>Denoising</b> removes salt-and-pepper noise using non-local means
    denoising. Associated parameter, <i>strength</i>, influences jointly
    several filter properties:
    <!--<ul>
      <li>--> size of the scanning window<!-- = 21 pixels + 5&times;log(<i>strength</i>)-->, <!--</li>
      <li>-->range of a local scan<!-- = 7 pixels + 2.5&times;log(<i>strength</i>)-->, <!--</li>
      <li>-->and the strength of filter application.<!--</li>
    </ul>-->
    This filter is CPU-intensive for larger values of <i>strength</i>
    that imply more non-local scan.
  </li>
  <li><b>Smoothing</b> performs bilateral noise filtering. Neighborhood
    of each pixel is defined based on the filter only parameter, <i>radius</i>,
    and the weights of the photometric and geometric distances are set as linearly
    proportional to <i>radius</i>.
    This filter may be used as a faster replacement, or as a complement, of
    the previous denoising step.
  </li>
  <li><b>Thresholding</b> binarizes input image using local adaptive
    thresholding: for each pixel, a mean intensity of pixels in its
    neighborhood (of radius controlled by parameter <i>block size</i>)
    is set as the binarization threshold.
    The threshold can be futher adjusted using parameter <i>base-line</i>.
    Local adaptive thresholding handles well images with uneven illumination.
    If a single, global intensity threshold is desired, one should just
    increase <i>block size</i> to be twice the larger dimension of the image.
    Optimal values of both the parameters can be found automatically via
    a na&iuml;ve grid search (radio button <i>Manual</i> &rarr; <i>Auto</i>),
    with resultant nuclear contours solidity being the optimization objective.
    For some parameter values the algorithm for nuclei detection and splitting
    may have long completion times, hence it's possible to impose a time-out
    for testing a single set of parameters.
  </li>
  <li><b>Opening</b> regularizes silhouettes of nuclei after thresholding and
    removes small debris by performing morphological erosion followed by dilation.
    A number of consecutive opening rounds can be performed; the sizes of
    structuring elements for erosion and dilation are controlled jointly
    to prevent having nuclear contours that would be overtly round or too
    tight/loose.
</ol><p>
All these stages (filters) in the pipeline can be individually turned on
and off.
If the <i>preview stages</i> checkbox has been checked, previews of the
effects of the filters will be displayed in separate windows.
The filters and their parameters are also described briefly in tooltips
that pop up when hovering the mouse cursor over filter names or their
parameter labels.
</p><p>
Image preprocessing does not impact image quantification nor the way in
which the image is displayed.
</p>
 
<h3>Nuclei detection and assessment</h3>
<p>
The binarized image resulting from the preprocessing pipeline is used
to find contours.
Median nuclear contour area serves as the reference contour area and two
user-defined parameters, <i>min&nbsp;area</i> and <i>max&nbsp;area</i>,
expressed as fractions of the median area, are used to classify all contours as:
(<i>i</i>) too small to be a nucleus,
(<i>ii</i>) too large to be a single nucleus, or
(<i>iii</i>) having area close enough to the reference nucleus and thus being
single-nucleus contours.
Too small contours are called debris.
Contours that are too large can be split depending on their solidity &ndash;
defined as the surface area of the contour divided by the surface area
of its convex hull.
If a too large contour has solidity higher that user-defined
<i>min&nbsp;solidity</i>, it is deemed non-splittable.
However, when solidity of a too large contour is lower, then it will be
subjected to splitting based on convexity defects called <i>indents</i>.
Indents that can be used for splitting should be sufficiently large,
which is decided based on the user-defined <i>min&nbsp;indent</i> parameter.
A split can be attempted only when a contour has two or more indents.
Splitting works recursively as long as there are indents that can be
used to obtain contours of nuclei of areas close to the reference area.
Contours that result from splitting but according to the <i>min&nbsp;area</i>
parameter are too small are called split orphans.
Descriptions of parameters involved in nuclei assessment are shown in tooltips
that pop up when hovering the mouse pointer over parameter labels.
</p><p>
Nuclear contours are drawn over microscopic images in colors associated
with their origin in the above-described segmentation algorithm:
(1) typically sized contours that do not result from splitting ("solo" contours)
    are white,
(2) typically sized contours resulting from splitting &ndash; green,
(3) large non-splittable &ndash; red,
(4) split orphans (relatively rare) &ndash; yellow,
(5) debris &ndash; violet.
The obtained set of contours is scored according to the variance of their
solidities: the lower is variability, the higher is the score.
Scoring is used currently for automated optimization of thresholding
parameters at the image preprocessing stage.
</p><p>
If the checkbox <i>auto-click</i> has been checked, then one can adjust
image preprocessing and nuclei assessment parameters and nearly instantaneously
observe their impact on nuclei detection (without clicking <i>Detect</i>
button after each parameter adjustment).
</p><p>
Both the image preprocessing parameters and nuclei assessment parameters
may be saved to/loaded from a text file using buttons labeled
<i>Protocol &harr; file</i>.
</p>
 
 
<h2 id="h2_nuclei_editing">Toolbox: Nuclei editing</h2>
<p>
It is possible to correct automatically detected nuclei one-by-one by deleting
existing nuclear contours and adding new ones manually:
</p><ul>
  <li><b>To remove a nucleus</b>: select the unwanted nucleus by a left-click
    and then right-click on it.</li>
  <li><b>To add a nucleus</b>: after right-clicking in a free space, press left
    mouse button and use mouse pointer to draw the contour of a new nucleus;</li>
</ul><p>
All nuclei are numbered sequentially starting from 1.
Use checkbox <i>numbers</i> in box <i>Annotations</i> to show/hide the numbers.
After a nucleus of a given number is removed, all higher nuclei numbers are
decreased by one.
After a new nuclear contour has been drawn, it is assigned the smallest available
number (equal to the current number of all nuclear contours).
A contour can be redrawn, that is, replaced without changing its number,
only in the tracks editing toolbox.
</p><p>
Double-left-click on a contour can be used to manually toggle a binary state
of a nucleus called <i>completeness</i>.
This state can be used at a later stage of analysis.
One can toggle completeness status of nuclei that lie on the image border
using a suitable button in the box <i>Editing by location</i>.
Using other buttons in this box one can remove such border touching contours
as well as contours classified as debris or split orphans.
</p><p>
Coordinates of nuclear contours can be save to/loaded from a text file using
button labeled <i>Nuclei &harr; file</i>.
The order of contours in the file corresponds to the numbering displayed on
the screen.
</p><p>
When all nuclei in a frame are removed (which takes place also upon nuclei
contours file loading), all tracks are removed as well.
</p>
 
 
 
<h2 id="h2_perinuclei_derivation">Toolbox: Perinuclei derivation</h2>
<p>
(to be written) <!-- TOOD -->
</p>
 
 
 
<h2 id="h2_regions_editing">Toolbox: Regions editing</h2>
<p>
(to be written) <!-- TOOD -->
</p>
 
 
 
<h2 id="h2_quantifiction">Toolbox: Quantification</h2>
<p>
Areas enclosed in nuclear and region contours can be quantified w.r. to:
surface area, intensity sum, median, mean, min, and max, in each channel
separately. The same values can be calculated for the whole image.
Quantification results for the current frame can be exported to a text file
and analyzed with external tools.
</p>
<!-- TODO describe python scripts -->
 
 
<h2 id="h2_tracking">Toolbox: Tracking</h2>
<p>
Tracking is local in time and space, i.e., corresponding nuclei are matched
between adjacent time frames using a "greedy" matching algorithm.
</p>
<p>
Tracks are created only for the nuclei which have a contour.
The "completeness" status of nuclei (displayed by using either solid or dashed
contour line) is not taken into account.
</p>
 
<p>
Nuclei matching is performed in three phases:
</p><ol>
  <li>
<b>Nuclei similarity scoring</b>.
Similarity in all nuclei pairs, in which one nucleus comes from to the
previous time frame and the other nucleus belongs to the current time frame,
is estimated.
Similarity scores form a matrix, where the number of rows and the number of
columns are equal to the number of nuclei in the previous and the current
time frame.
(At this phase, the distance between nuclei in each pair is not directly
considered.)
  </li>
  <li>
<b>Internuclear distance-dependent similarity scaling</b>.
Each estimated similarity score is scaled depending on the internuclear
distance.
  </li>
  <li>
<b>Tracks elongation based on max similarity</b>.
A distances-scaled similarity score of maximum value is sought in the
similarity matrix.
When found, two corresponding nuclei are considered as matched.
The procedure of finding maximum similarity is repeated for the still unmatched
nuclei.
When two nuclei are matched but their distance is larger than an allowed
inter-nuclear spacing, the nuclei matching stops.
  </li>
</ol>
 
Parameters:
<ol>
  <li>
<p>
Nuclei similarity score (phase 1) is computed as the linear combination of six
features, which are all order statistics.
Weights used for calculating a linear combination of these features are
following:
</p>
<ul>
  <li><b>proximity</b> &ndash; order statistics is calculated based
    on the distances of nuclear positions,</li>
  <li><b>surface area</b>,</li>
  <li><b>eccentricity</b> &ndash; order statistics is calculated based on how
    far is the nucleus shape from the circle,</li>
  <li><b>orientation</b> &ndash; order statistics is calculated using the angle
    of the first principal axis</li>
  <li><b>sum of pixel intensities</b>,</li>
  <li><b>distribution of pixel intensities</b> &ndash; order statistics is
    based on the Kolmogorov-Smirnov distance between two distributions of
    nuclear intensities.</li>
</ul>
  </li>
  <li>
<p>
Distance-dependent similarity scaling (phase 2) is parametrized by
<i>&Delta;<sub>xy</sub> scaling</i>.
The value of this parameter is used as the exponent for scaling inter-nuclear
distances (in feature space).
</p>
  </li>
  <li>
<p>
Tracks are elongated (phase 3) if the currently matched nuclei are not more than
than <i>&Delta;<sub>xy</sub> cutoff</i> median inter-nuclear distances apart.
</p>
  </li>
</ol>
 
 
<p>
Currently, tracking must be gapless, i.e., the outline of the nucleus must be
marked in every track frame (although in some frames it's status can be set to
"incomplete" so that, by convention, it is possible to omit them in
quantifications).
</p>
 
<!-- TODO: comment that nuclei numbers are not consistent along the track! -->
 
<h2 id="h2_tracks_editing">Toolbox: Tracks editing</h2>
<p>
When the correspondence between nucleus' appearances in different time frames
has been found, its centers of the mass are connected with straight lines
(called <i>segments</i>).
Unmatched nuclei are marked with small squares (called <i>stubs</i>).
</p>
<p>
Tracks are listed in a tabular form, sorted by their lengths.
Tracks of the same length are ordered by a descending confidence score.
It is possible to remove a track by right-clicking on the corresponding row
of the tabular tracks view.
</p>
<p>
It is possible to correct erroneous tracks manually: segments can be added and
removed with mouse:
</p>
<ul>
  <li>
To add a segment, select one segment (or a stub) using mouse left-click, press
Ctrl key, and select another segment (or a stub) with the left-click.
As tracks are assumed to be gapless, only the tracks which end/begin at
consecutive time frames can be joined.
  </li>
  <li>
To remove a segment, select it with the mouse left-click and then right-click
on the selection.
  </li>
</ul>
<p>
To redraw a nucleus within a track, first: select it with the left-click,
second: while pressing right mouse button make the left-click, third: draw
the new contour (by pressing the left mouse button) or left-click in any empty
space to abandon the replacing mode.
</p>
<p>
To add a new nucleus (while tracks are already present), switch to the Nuclei
Editing toolbox, draw a new contour, then switch back to the Tracks Editing
toolbox and click with mouse middle button on the new contour to create a new
stub. Stubs can be merged into segments, as described previously.
</p>
<p>
Tracks are saved to files in a simple textual format.
First column is the frame number (0-based), and the second column is the number
of nucleus (consistent with the nuclei numbering in the frame nuclei contours
file and in the nuclei quantification file; nuclei numbering begins with 1).
</p>
<p>
Note: When all nuclei in a frame are removed (which takes place also upon nuclei
contours file loading), tracks are removed as well to prevent the program from
being internally inconsistent.
</p> <!-- this is repeated intentionally -->
 
 
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 
 
<h1 id="h1_scripting">Scripting</h1>
<p>
ShuttleTracker ships an embedded JavaScript interpreter to enable automation of
repeatable, daunting mouse clicks.
The interpreter has been fitted with syntactic extensions which facilitate, i.a.,
looping over all the frames.
To see the available functions please open the editor window (Menu Script)
and click on the Show API button.
A simple debugging capabilities are provided: error message and erratic script
line number are to be displayed upon script failure.
</p>
<p>
Scripts are an integral part of ShuttleTracker functionalities, for example are
used to play the sequence of images as a movie.
As such, the scripts can be launched directly from the Scripts menu (also via
keyboard shortcuts; shortcuts are assigned after ordering script file names
in the lexicographic order).
Newly added scripts become immediately available in the menu.
</p>
<p>
On Linux, scripts are installed in
<span class="tt"><i>INSTALL_PREFIX</i>/share/shuttletracker/scripts</span>.
On Windows, scripts are usually stored as plain text files in user's
<span class="tt">Document/STScripts directory</span>.
On macOS, scripts are stored in
<span class="tt">ShuttleTracker.app/Contents/Resources/shuttletracker/scripts</span>.
(On all systems, the exact location can be checked at the bottom of the
Help &rarr; About window.)
</p>
 
 
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 
 
<h1 id="h1_preferences">Preferences</h1>
<p>The following preferences can be set or unset in the Preferences menu:</p>
<ul>
  <li>
<i>Display buffers: Cache images in memory for fast display.</i>
This preference affects the way images are prepared just after they are loaded.
Cached images occupy consume memory but are displayed faster.
  </li>
  <li>
<i>Over-8-bit images: normalize to camera bit depth (if available)</i>.
This preference affects the way images are loaded, and has effect virtually only
on 16-bit images.
  </li>
  <li>
<i>Bright-field images: Skip when loading</i>.
This preference affects the way images are loaded. If BF images are not to be
used, skipping them will save memory.
  </li>
  <li>
<i>Bright-field images: Hide even when available</i>.
Auto-hide BF panel even when BF images were loaded.
  </li>
  <li>
<i>Bright-field images: Exclude from overlays</i>.
BF images overlaid on fluorescence images attenuate (pseudo)colors, thus it
may be preferred to not use BF images for overlays. It may be actively overridden
by manually selecting overlay components in menu View.
  </li>
</ul>
<p>
When exiting, ShuttleTracker stores these preferences and some other settings
to restore them when launched again.
Stored settings include: widths of contours, ranges of parameters for performing
nuclei detection parameters scan, nuclei detection scoring criterion, window
geometry, the location of the last opened directory, exported quantifications,
etc. On Linux, preferences and settings are saved to an INI-file (which is
placed in <span class="tt"><i>INSTALL_PREFIX</i>/shared/shuttletracker/config</span>).
On macOS, <span class="tt">settings.ini</span> is located in
<span class="tt">ShuttleTracker.app/Contents/Resources/shuttletracker/config</span>.
Under Windows, preferences are saved to the system registry (don't worry: upon
deinstallation, the registry is purged of all entries created by ShuttleTracker).
</p>
<p>
 
The number of threads used by several image processing algorithms is controlled
by the environmental variable <span class="tt">SHUTTLETRACKER_OPENCV_NUM_THREADS</span>.
Since the images are usually not that large, it is advised to set this number low.
In Linux terminal, the variable can be set in the bash shell with:
</p><pre>  export SHUTTLETRACKER_OPENCV_NUM_THREADS=2</pre>




===Documentation===
* User's manual: &nbsp;[{{SERVER}}/software/shuttletracker/release/shuttletracker-1.5.3-manual.pdf shuttletracker-1.5.3-manual.pdf]<br  style="line-height: 100%; margin-bottom:14px">
* Tutorial and overview: &nbsp;[{{SERVER}}/software/shuttletracker/release/previous/shuttletracker-1.3.0-tutorial.pdf shuttletracker-1.3.0-tutorial.pdf]<!--<span style="background:yellow">&nbsp;''' TODO '''&nbsp;</span>--><br  style="line-height: 100%; margin-bottom:6px">+&nbsp;example input images: &nbsp;[{{SERVER}}/software/shuttletracker/tutorial/March26_WellB_Pos09.zip March26_WellB_Pos09.zip] (~1.3 GB)<br  style="line-height: 100%; margin-bottom:6px">+&nbsp;example output from tracking analysis: &nbsp;[{{SERVER}}/software/shuttletracker/tutorial/March26_WellB_Pos09.html March26_WellB_Pos09.html]
<br/>


<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
===Stand-alone binary executables for Windows and Mac===
* Windows 64-bit installer: &nbsp; [{{SERVER}}/software/shuttletracker/release/shuttletracker-1.5.3-x86_win64-setup.exe shuttletracker-1.5.3-x86_win64-setup.exe]<div class="accordion" id="accordion-win"><accordion parent="accordion-win" heading="How to verify and run">COMPATIBILITY:&nbsp; This software was built with MSVC 14.2 on Windows&nbsp;10, and tested on Windows&nbsp;10 and Windows&nbsp;8. An installer of Microsoft Visual C++ 2019 Redistributable (required runtime libraries) is contained in the ShuttleTracker installer.<br/><br/>SECURITY:&nbsp; The downloadable installer is not signed with a certificate (so in Windows parlance it comes from an "unknown publisher"); however, its integrity can be checked manually in command line using a Windows pre-installed utility:<br/><div align="center"><span style="font-family: Lucida Sans Typewriter,Lucida Console,monaco,Bitstream Vera Sans Mono,Consolas,Inconsolata,monospace;">certUtil -hashfile <i>path_to_installer</i> MD5</span></div>MD5 sum of untainted shuttletracker-1.5.3-x86_win64-setup.exe is '''d6a87dec0b6167ae12833821d6d8a208'''.<br/></accordion></div>


* macOS application bundle (zipped "app", outdated): &nbsp;[{{SERVER}}/software/shuttletracker/release/shuttletracker-1.4.5-x86_64-darwin17.zip shuttletracker-1.4.5-x86_64-darwin17.zip]<div class="accordion" id="accordion-mac"><accordion parent="accordion-mac" heading="How to verify and run">COMPATIBILITY:&nbsp; This software was built with XCode 8 and tested under macOS 10.13 (High Sierra). It is likely incompatible with previous Mac operating system releases.<br/><br/>SECURITY:&nbsp; MD5 sum of the downloadable ZIP archive can be checked in Terminal:<div align="center"> <span style="font-family: Lucida Sans Typewriter,Lucida Console,monaco,Bitstream Vera Sans Mono,Consolas,Inconsolata,monospace;">md5 <i>path_to_zip</i></span></div>MD5 sum of untainted shuttletracker-1.4.5-x86_64-darwin17.zip is '''68ed03597b5e43e02ceace2e3530ce38'''.</accordion></div>
<br/>


<h1 id="h1_further_analysis">Further analysis</h1>
===Containers for Linux===
* Docker container: &nbsp;[{{SERVER}}/software/shuttletracker/release/shuttletracker-1.5.3.Dockerfile shuttletracker-1.5.3.Dockerfile]<div class="accordion" id="accordion-docker"><accordion parent="accordion-docker" heading="How to set up and run">BUILDING a container (in terminal):<div align="left"> <span style="font-family: Lucida Sans Typewriter,Lucida Console,monaco,Bitstream Vera Sans Mono,Consolas,Inconsolata,monospace;">
  docker build .  -f shuttletracker-1.5.3.Dockerfile  --tag st-container
</span></div><br/>LAUNCHING the GUI app within a container (in terminal):<div align="left"> <span style="font-family: Lucida Sans Typewriter,Lucida Console,monaco,Bitstream Vera Sans Mono,Consolas,Inconsolata,monospace;">
  docker run  -e DISPLAY  --net=host  st-container
</span></div><br/>You will likely want to specify a filesystem location with images using docker run's flag&nbsp;<span style="font-family: Lucida Sans Typewriter,Lucida Console,monaco,Bitstream Vera Sans Mono,Consolas,Inconsolata,monospace;">-v</span>. If the app fails to connect to the windows server, you may need to grant permission as follows:  <div align="left"><span style="font-family: Lucida Sans Typewriter,Lucida Console,monaco,Bitstream Vera Sans Mono,Consolas,Inconsolata,monospace;">
  xhost +local:docker
</span></div></accordion></div>
* Singularity container: &nbsp;[{{SERVER}}/software/shuttletracker/release/shuttletracker-1.5.3.recipe shuttletracker-1.5.3.recipe]<div class="accordion" id="accordion-singularity"><accordion parent="accordion-singularity" heading="How to set up and run">BUILDING a container (in terminal):<div align="left"> <span style="font-family: Lucida Sans Typewriter,Lucida Console,monaco,Bitstream Vera Sans Mono,Consolas,Inconsolata,monospace;">
  sudo singularity build --sandbox st shuttletracker-1.5.3.recipe
</span></div><br/>LAUNCHING the GUI app within a container (in terminal):<div align="left"> <span style="font-family: Lucida Sans Typewriter,Lucida Console,monaco,Bitstream Vera Sans Mono,Consolas,Inconsolata,monospace;">
  singularity exec --writable st /opt/local/bin/ShuttleTracker
</span></div></accordion><div><br/>


Quantification results and tracks generated with ShuttleTracker as saved to
===Source code===
plain-text files that should be readily parseable by external data analysis
S<span style="font-variant:small-caps">huttle</span>T<span style="font-variant:small-caps">racker</span> source code is distributed under [http://www.gnu.org/licenses/gpl-3.0.html GNU GPL v3.0].<br/>
scripts and tools. Python module "shuttletracker" located in
* C++ source code: &nbsp; [{{SERVER}}/software/shuttletracker/release/shuttletracker-1.5.3-source.tar.gz shuttletracker-1.5.3-source.tar.gz]
<span class="tt"><i>INSTALL_PREFIX</i>/shared/analysis</span> shows how to
<div class="accordion" id="accordion-sourcecode"><accordion parent="accordion-sourcecode" heading="How to compile">Compilation on Linux, macOS, and Windows is managed by [http://www.cmake.org/ CMake], which is expected to be used in the standard way:
"zip" tracks and respective quantifications.
<div align="left"> <span style="font-family: Lucida Sans Typewriter,Lucida Console,monaco,Bitstream Vera Sans Mono,Consolas,Inconsolata,monospace;">
  tar xfz shuttletracker-1.5.3-source.tar.gz
  cd shuttletracker-1.5.3-source
  mkdir build && cd build
  cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/opt/local/
  make -j4 && make install
</span></div>
More detailed instructions are provided in file COMPILING.md in the source code package. You may also have a look at how the build process is automated in a Singularity container recipe distributed in the source code distribution subdirectory distrib/singularity.<br/></accordion></div>
<br/>


<!--
===References===
====Primary citation====
* <span class="pmbm">Kochańczyk M</span>. '''ShuttleTracker: an interactive tool for analysing nucleocytoplasmic shuttling of fluorescent reporters''' (''submitted'')<br style="margin-bottom:12px">-->
===Applications===
* <span class="pmbm">Korwek&nbsp;Z</span>, <i>et&nbsp;al</i>. '''Nonself RNA rewires IFNβ signaling: A mathematical model of the innate immune response''', ''Science Signaling'' (accepted) [https://doi.org/10.1101/2022.01.30.478391 bioRxiv]<br style="line-height: 100%; margin-bottom:12px">
* <span class="pmbm">Grabowski&nbsp;F</span>, <i>et&nbsp;al</i>. '''Antagonism between viral infection and innate immunity at the single-cell level''', ''PLOS Pathogens'' <u>19</u>:e1011597 (2023) [https://pubmed.ncbi.nlm.nih.gov/37669278 PubMed] [https://doi.org/10.1371/journal.ppat.1011597 CrossRef]<br style="line-height: 100%; margin-bottom:12px">
* <span class="author">Czerkies&nbsp;M</span>, <i>et&nbsp;al</i>.  '''Respiratory syncytial virus protects bystander cells against influenza A virus infection by triggering secretion of type I and type III interferons''', ''Journal of Virology'' <u>96</u>:22 e01341-22 (2022) [https://doi.org/10.1128/jvi.01341-22 CrossRef] [https://doi.org/10.1101/2021.10.11.463877 bioRxiv]<br style="line-height: 100%; margin-bottom:12px">
* <span class="pmbm">Czerkies M</span>, <i>et&nbsp;al</i>. '''Cell fate in antiviral response arises in the crosstalk of IRF, NF-κB and JAK/STAT pathways''', ''Nature Communications'' <u>9</u>:493 (2018) [http://www.ncbi.nlm.nih.gov/pubmed/29402958 PubMed] [http://dx.doi.org/10.1038/s41467-017-02640-8 CrossRef]<br style="line-height: 100%; margin-bottom:12px">
* <span class="pmbm">Tudelska K</span>, <i>et&nbsp;al</i>. '''Information processing in the NF-κB pathway''', ''Scientific&nbsp;Reports'' <u>7</u>:15926 (2017) [http://www.ncbi.nlm.nih.gov/pubmed/29162874 PubMed] [http://doi.org/10.1038/s41598-017-16166-y CrossRef]
<br/>


<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
===Contact===
The lead software developer is Marek Kochańczyk. For both user's and developer's queries please use the following e-mail address: &#115;huttletrac&#107;er.software@gmail.com.


<br />
<br/><br/>
<br />


<!--
<accordion parent="accordion" heading="">
</accordion>
</accordion>
-->

Latest revision as of 19:24, 7 November 2023

An interactive tool for analyzing nucleocytoplasmic shuttling
of fluorescent reporters


ShuttleTracker montage.png

ShuttleTracker can detect stained cell nuclei, generate corresponding annular perinuclear extensions, quantify geometric and photometric properties of detected objects, and perform frame-to-frame nuclei tracking.  Parameters of the image processing algorithms can be changed manually and the effects of these changes can be seen nearly immediately overlaid on currently displayed microscopic images.  A key capability of ShuttleTracker is that nuclear contours and tracks can be generated automatically and then corrected manually. The tool is scriptable.

The latest ShuttleTracker version is 1.5.3 (February 2023).




Documentation


Stand-alone binary executables for Windows and Mac

COMPATIBILITY:  This software was built with MSVC 14.2 on Windows 10, and tested on Windows 10 and Windows 8. An installer of Microsoft Visual C++ 2019 Redistributable (required runtime libraries) is contained in the ShuttleTracker installer.

SECURITY:  The downloadable installer is not signed with a certificate (so in Windows parlance it comes from an "unknown publisher"); however, its integrity can be checked manually in command line using a Windows pre-installed utility:
certUtil -hashfile path_to_installer MD5
MD5 sum of untainted shuttletracker-1.5.3-x86_win64-setup.exe is d6a87dec0b6167ae12833821d6d8a208.

COMPATIBILITY:  This software was built with XCode 8 and tested under macOS 10.13 (High Sierra). It is likely incompatible with previous Mac operating system releases.

SECURITY:  MD5 sum of the downloadable ZIP archive can be checked in Terminal:
md5 path_to_zip
MD5 sum of untainted shuttletracker-1.4.5-x86_64-darwin17.zip is 68ed03597b5e43e02ceace2e3530ce38.


Containers for Linux

BUILDING a container (in terminal):
 docker build .  -f shuttletracker-1.5.3.Dockerfile  --tag st-container

LAUNCHING the GUI app within a container (in terminal):
 docker run  -e DISPLAY  --net=host  st-container

You will likely want to specify a filesystem location with images using docker run's flag -v. If the app fails to connect to the windows server, you may need to grant permission as follows: 
 xhost +local:docker

BUILDING a container (in terminal):
 sudo singularity build --sandbox st shuttletracker-1.5.3.recipe

LAUNCHING the GUI app within a container (in terminal):
 singularity exec --writable st /opt/local/bin/ShuttleTracker

Source code

ShuttleTracker source code is distributed under GNU GPL v3.0.

Compilation on Linux, macOS, and Windows is managed by CMake, which is expected to be used in the standard way: 
 tar xfz shuttletracker-1.5.3-source.tar.gz
 cd shuttletracker-1.5.3-source
 mkdir build && cd build
 cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/opt/local/
 make -j4 && make install
More detailed instructions are provided in file COMPILING.md in the source code package. You may also have a look at how the build process is automated in a Singularity container recipe distributed in the source code distribution subdirectory distrib/singularity.


Applications

  • Korwek Z, et al. Nonself RNA rewires IFNβ signaling: A mathematical model of the innate immune response, Science Signaling (accepted) bioRxiv
  • Grabowski F, et al. Antagonism between viral infection and innate immunity at the single-cell level, PLOS Pathogens 19:e1011597 (2023) PubMed CrossRef
  • Czerkies M, et al. Respiratory syncytial virus protects bystander cells against influenza A virus infection by triggering secretion of type I and type III interferons, Journal of Virology 96:22 e01341-22 (2022) CrossRef bioRxiv
  • Czerkies M, et al. Cell fate in antiviral response arises in the crosstalk of IRF, NF-κB and JAK/STAT pathways, Nature Communications 9:493 (2018) PubMed CrossRef
  • Tudelska K, et al. Information processing in the NF-κB pathway, Scientific Reports 7:15926 (2017) PubMed CrossRef


Contact

The lead software developer is Marek Kochańczyk. For both user's and developer's queries please use the following e-mail address: shuttletracker.software@gmail.com.




Retrieved from "https://pmbm.ippt.pan.pl/index.php?title=ShuttleTracker&oldid=1948"