sojourner 1.6.0
A basic task in 2D single molecule tracking is to determine diffusion coefficient from molecule trajectories identified after initial image data acquisition. The trajectory (term used interchangeably with “tracks”) of a molecule is presented as a table of \(x\),\(y\)-coordinates in the unit of pixel, which then can be converted to other measurement, such as \(\mu\)m, according to the resolution of the camera. The sojourner package provides methods to import/export, process, and analyze such data. Analysis techniques include the diffusion coefficient using the mean square displacement (MSD), displacement cumulative distribution function (CDF), as well as hidden Markov model (HMM) methods (in next release) from such input data. This vignette covers basic usage of the package.
Using BiocManager:
if(!requireNamespace("BiocManager", quietly = TRUE))
install.packages("BiocManager")
BiocManager::install("sojourner")
Or, using the release version from GitHub:
devtools::install_github("sheng-liu/sojourner", build_vignettes = TRUE)
To load the package:
library(sojourner)
The input file for sojourner is the Diatrack (.txt or .mat), ImageJ Particle
Tracker (.csv), SLIMfast (.txt), or u-track (.mat) output file. Tracks are
extracted from the output files and then stored in a trackll
, a list of track
lists. A track denotes a single trajectory stored in a data.frame
recording
\(x\), \(y\), \(z\) and (video) frame number. A trackl
track list is a collection of
track data from one video file output. Lastly, a “trackll” is a collection of
“trackl” in one folder.
In this example, the folder “SWR1_2” contains one track list with 207 tracks and one track list with 139 tracks:
folder=system.file("extdata","SWR1_2",package="sojourner")
trackll = createTrackll(folder=folder, input=3)
str(trackll,max.level=2, list.len=2)
## List of 2
## $ SWR1_WT_140mW_image6.csv:List of 207
## ..$ mage6.1.4.1.1 :'data.frame': 4 obs. of 4 variables:
## ..$ mage6.2.2.2.2 :'data.frame': 2 obs. of 4 variables:
## .. [list output truncated]
## $ SWR1_WT_140mW_image7.csv:List of 139
## ..$ mage7.1.2.1.1 :'data.frame': 2 obs. of 4 variables:
## ..$ mage7.1.9.2.2 :'data.frame': 9 obs. of 4 variables:
## .. [list output truncated]
Multiple folders can also be stored in a single trackll. Here, trackll
denotes
a list of folders, and each trackl
contains all tracks from every file in the
folder. This structure can be constructed as such:
trackll=list(FOLDER=list(track=track))
# Construct trackll from data.frame
trackl=list(track_1=dataframe_1,
track_2=dataframe_2,
track_3=dataframe_3,
...
track_n=dataframe_n)
trackll=list(FOLDER_1=trackl_1,
FOLDER_2=trackl_2,
FOLDER_3=trackl_3,
...
FOLDER_n=trackl_n,)
Merging all tracks from every file in the folder into a single trackl
in a
trackll
can also be done through mergeTracks()
. In this example, both track
lists from “SWR1_2” were merged together to form a list of 346 tracks.
folder=system.file("extdata","SWR1_2",package="sojourner")
trackll = createTrackll(folder=folder, input=3)
trackll <- mergeTracks(folder=folder, trackll=trackll)
str(trackll,max.level=2, list.len=2)
## List of 1
## $ SWR1_2:List of 346
## ..$ mage6.1.4.1.1 :'data.frame': 4 obs. of 4 variables:
## ..$ mage6.2.2.2.2 :'data.frame': 2 obs. of 4 variables:
## .. [list output truncated]
To see the coordinates of an individual track:
# Specify the folder name and the track name
trackll[["SWR1_2"]]["mage6.1.4.1.1"]
# Alternatively, specify the index of the folder and the track
# trackll[[1]][1]
## $mage6.1.4.1.1
## x y z Frame
## 1 40.32 49.36 1 1
## 2 41.03 47.33 1 2
## 3 41.05 48.43 1 3
## 4 40.90 49.09 1 4
sojourner provides tools to manage and manipulate track data. Below are a few examples of the commonly used functions to import, process, and export single molecule track data.
First, read in track data taken from Diatrack, ImageJ Particle Tracker, SLIMfast, or u-track. In this example, we read data from ImageJ .csv-formatted files from “SWR1_2”.
# Designate a folder and then create trackll from ImageJ .csv data
folder=system.file("extdata","SWR1_2",package="sojourner")
trackll = createTrackll(folder=folder, input=3)
# Alternatively, use interact to open file browser and select input data type
# trackll = createTrackll(interact = TRUE)
##
## Reading ParticleTracker file: SWR1_WT_140mW_image6.csv ...
##
## mage6 read and processed.
##
## Reading ParticleTracker file: SWR1_WT_140mW_image7.csv ...
##
## mage7 read and processed.
##
## Process complete.
Different tracking softwares (Diatrack, ImageJ Particle Tracker, SLIMfast,
u-track) often use varying algorithms to stitch together single
molecule localizations into trajectories. Sometimes, a molecule can disappear
for several frames and can classify single trajectories as two.
linkSkippedFrames()
allows users to link trajectories that skip (or do not
appear for) a number of frames. In this example, all tracks that skip a
maximum of 10 frames and reappear within 5 pixels are linked:
# Basic function call of linkSkippedFrames
trackll.linked <- linkSkippedFrames(trackll, tolerance = 5, maxSkip = 10)
##
## Linking mage6 ...
##
## 156 links found in mage6
##
## Linking mage7 ...
##
## 112 links found in mage7
##
## Process complete.
filterTrack()
can be used to filter out track that have lengths (defined by
number of frames) that fall within a specified range. In this example, only
tracks that appear for at least 7 frames are kept:
trackll.filter=filterTrack(trackll ,filter=c(7,Inf))
## applying filter, min 7 max Inf
# See the min and max length of the trackll
# trackLength() is a helper function output track length of trackll
lapply(trackLength(trackll),min)
## $SWR1_WT_140mW_image6.csv
## [1] 2
##
## $SWR1_WT_140mW_image7.csv
## [1] 2
lapply(trackLength(trackll.filter),min)
## $SWR1_WT_140mW_image6.csv
## [1] 7
##
## $SWR1_WT_140mW_image7.csv
## [1] 7
trimTrack()
is used to to trim/cutoff tracks. Given a specified range of
track lengths (defined by number of frames), only tracks that fall within the
range are kept, otherwise trimmed to the upper limit. In this example, all
tracks with lengths greater than 20 have their lengths trimmed to 20:
trackll.trim=trimTrack(trackll,trimmer=c(1,20))
## applying trimmer, min 1 max 20
# See the min and max length of the trackll
# trackLength() is a helper function output track length of trackll
lapply(trackLength(trackll),max)
## $SWR1_WT_140mW_image6.csv
## [1] 30
##
## $SWR1_WT_140mW_image7.csv
## [1] 15
lapply(trackLength(trackll.trim),max)
## $SWR1_WT_140mW_image6.csv
## [1] 20
##
## $SWR1_WT_140mW_image7.csv
## [1] 15
In order to apply a binary image mask to track data, one can use
maskTracks()
. In this example, we use image masks for each track file
generated by thresholding the initial fluorescent glow of the nucleus. See man
pages for indexCell()
, filterOnCell()
, and sampleTracks()
for more
advanced functionality (e.g. separating tracks, filtering, and sampling by
masked cells).
# Basic masking with folder path with image masks
folder = system.file("extdata","ImageJ",package="sojourner")
trackll = createTrackll(folder, input = 3)
trackll.filter=filterTrack(trackll ,filter=c(7,Inf))
trackll.masked <- maskTracks(folder = folder, trackll = trackll.filter)
To plot the masks:
# Plot mask
plotMask(folder)
To plot the nuclear overlay of the un-masked data:
# If nuclear image is available
plotNucTrackOverlay(folder=folder,trackll=trackll)
To plot the nuclear overlay of the masked data:
# If nuclear image is available
plotNucTrackOverlay(folder=folder,trackll=trackll.masked)
To export a trackll
, use exportTrackll()
to save track data into a .csv file
in the working directory. This function saves the data into the same format used
by ImageJ Particle Tracker, fully preserving all track information, and
maintaining short read/write computation time and readability in Excel/etc.
# Basic function call to exportTrackll into working directory
exportTrackll(trackll)
# Read exported trackll saved in working directory
trackll.2 <- createTrackll(folder = getwd(), input = 3)
The first thing one may want to do is to see how the tracks look like in 2-D space. The track name is useful in this case if one wants to see specific trajectories and its associated movies.
All one needs to do is to create a .csv file contains trajectory names in its first column. sojourner package contains such an example .csv file.
# specify the path of the file containing trajectory index names, index file
index.file2=system.file("extdata","INDEX","indexFile2.csv",
package="sojourner")
# specify the folders containing the output files
folder1=system.file("extdata","SWR1",package="sojourner")
folder2=system.file("extdata","HTZ1",package="sojourner")
# plot trajectories specified in the trajectory index file
plotTrackFromIndex(index.file=index.file2,
movie.folder=c(folder1,folder2),input=3)
The output plots the tracks based on its name, with the information contained
in its name (i.e. start frame and length/duration), one can also pull out its
movie. See ? plotTrack
for more plotting options.
One may be interested to see the distribution of the (time) length of the tracks. This can be done by calculating and plotting the dwell times:
dwellTime(trackll,plot=TRUE) # default t.interval=10, x.scale=c(0,250)