1.1 Input data format

Tracking data is usually stored as a table, with columns indicating the cellid, time, and coordinates of each measured point. Here we have an example in the file “t-cells.txt”, which we can read in as a normal dataframe:

d <- read.table( system.file("extdata", "t-cells.txt", package="celltrackR" ) )
str(d)

## 'data.frame':    5157 obs. of  6 variables:
##  $ V1: int  2 3 4 5 6 7 8 9 10 11 ...
##  $ V2: int  1 1 1 1 1 1 1 1 1 1 ...
##  $ V3: int  48 72 96 120 144 168 192 216 240 264 ...
##  $ V4: num  90.9 89.6 88.7 87.3 86.3 ...
##  $ V5: num  65.4 64.9 67.1 68.2 67.9 ...
##  $ V6: num  -6417 -6420 -6422 -6424 -6425 ...

head(d)

##   V1 V2  V3      V4      V5       V6
## 1  2  1  48 90.8534 65.3943 -6416.80
## 2  3  1  72 89.5923 64.9042 -6419.93
## 3  4  1  96 88.6958 67.1125 -6421.80
## 4  5  1 120 87.3437 68.2392 -6424.08
## 5  6  1 144 86.2740 67.9236 -6425.14
## 6  7  1 168 84.0549 68.2502 -6426.68

The result is a normal dataframe, where here we have an index for the time point in the first column, cell id in the second column, the actual time (in seconds) in the third column, and (x, y, z) coordinates in columns 4:6.

2.1 The tracks object data structure

The tracks object is a special datastructure that allows efficient handling of track datasets. As an example, we will use the tracks loaded in the previous section.

A tracks object has the form of a list, where each element of the list is a track of a single cell:

# Structure of the TCells object
str( t, list.len = 3 )

## List of 258
##  $ 1   : num [1:39, 1:4] 48 72 96 120 144 168 192 216 240 264 ...
##   ..- attr(*, "dimnames")=List of 2
##   .. ..$ : NULL
##   .. ..$ : chr [1:4] "t" "x" "y" "z"
##  $ 2   : num [1:7, 1:4] 48 72 96 120 144 ...
##   ..- attr(*, "dimnames")=List of 2
##   .. ..$ : NULL
##   .. ..$ : chr [1:4] "t" "x" "y" "z"
##  $ 3   : num [1:19, 1:4] 24 48 72 96 120 144 168 192 216 240 ...
##   ..- attr(*, "dimnames")=List of 2
##   .. ..$ : NULL
##   .. ..$ : chr [1:4] "t" "x" "y" "z"
##   [list output truncated]
##  - attr(*, "class")= chr "tracks"

# This object is both a list and a "tracks" object
is.list( t )

## [1] TRUE

is.tracks( t )

## [1] TRUE

# The first element is the track of the first cell in the data:
head( t[[1]] )

##        t       x       y        z
## [1,]  48 90.8534 65.3943 -6416.80
## [2,]  72 89.5923 64.9042 -6419.93
## [3,]  96 88.6958 67.1125 -6421.80
## [4,] 120 87.3437 68.2392 -6424.08
## [5,] 144 86.2740 67.9236 -6425.14
## [6,] 168 84.0549 68.2502 -6426.68

Each track in the tracks object is a matrix with coordinates at different timepoints for each cell. The cell id is no longer a column in this matrix, as tracks belonging to different cells are stored in different elements of the tracks object list.

2.2 Subsetting data

Note that we can subset the track matrix of an individual track using the double square brackets:

# Get the first track
t1 <- t[[1]]
str(t1)

##  num [1:39, 1:4] 48 72 96 120 144 168 192 216 240 264 ...
##  - attr(*, "dimnames")=List of 2
##   ..$ : NULL
##   ..$ : chr [1:4] "t" "x" "y" "z"

# This is no longer a tracks object, but a matrix
is.tracks( t1 )

## [1] FALSE

is.matrix( t1 )

## [1] TRUE

If we now want to plot this track, the plotting method for tracks will not work because this is not recognized as a tracks object. We can use the frunction wrapTrack() to “pack” this matrix back into a tracks object:

par( mfrow=c(1,2) )
plot( t1, main = "Plotting matrix directly" )
plot( wrapTrack( t1 ), main = "After using wrapTrack()" )

Note that we can also achieve this by subsetting with single instead of double brackets:

# Get the first track
t1b <- t[1]
str(t1b)

## List of 1
##  $ 1: num [1:39, 1:4] 48 72 96 120 144 168 192 216 240 264 ...
##   ..- attr(*, "dimnames")=List of 2
##   .. ..$ : NULL
##   .. ..$ : chr [1:4] "t" "x" "y" "z"
##  - attr(*, "class")= chr "tracks"

# This remains a track object
is.tracks( t1b )

## [1] TRUE

In the same way, we can also subset multiple tracks at once

# Get the first and the third track
t13 <- t[c(1,3)]
str(t13)

## List of 2
##  $ 1: num [1:39, 1:4] 48 72 96 120 144 168 192 216 240 264 ...
##   ..- attr(*, "dimnames")=List of 2
##   .. ..$ : NULL
##   .. ..$ : chr [1:4] "t" "x" "y" "z"
##  $ 3: num [1:19, 1:4] 24 48 72 96 120 144 168 192 216 240 ...
##   ..- attr(*, "dimnames")=List of 2
##   .. ..$ : NULL
##   .. ..$ : chr [1:4] "t" "x" "y" "z"
##  - attr(*, "class")= chr "tracks"

Note that the track ids are strings that do not always correspond to the index of the track in the dataset. If we want the ones with ids 1 and 3, we can subset using the track name as a character string:

# Get tracks with ids 1 and 3
t13b <- t[c("1","3")]
str(t13b)

## List of 2
##  $ 1: num [1:39, 1:4] 48 72 96 120 144 168 192 216 240 264 ...
##   ..- attr(*, "dimnames")=List of 2
##   .. ..$ : NULL
##   .. ..$ : chr [1:4] "t" "x" "y" "z"
##  $ 3: num [1:19, 1:4] 24 48 72 96 120 144 168 192 216 240 ...
##   ..- attr(*, "dimnames")=List of 2
##   .. ..$ : NULL
##   .. ..$ : chr [1:4] "t" "x" "y" "z"
##  - attr(*, "class")= chr "tracks"

2.3 Using tracks objects in combination with R’s lapply and sapply

Because tracks objects are lists, we can make use of R’s lapply() and sapply() functions to compute metrics or manipulate tracks efficiently.

For example, if we want to compute the speed of each track, we simply use:

speeds <- sapply( t, speed )
head(speeds)

##          1          2          3          4          5          6 
## 0.18035686 0.05231612 0.09511618 0.14386174 0.20168555 0.11651339

Note that sapply() applies the speed() function to each matrix in the track list (analogous to subsetting with double brackets). Thus, the speed() function sees an individual track matrix, not a tracks object.

Or we can use lapply() to manipulate each track in the dataset with some custom function, keeping separate tracks as separate list elements. For example, suppose we wish to remove all data after a given timepoint:

# Function to remove all data after given timepoint
# x must be a single track matrix, which is what this function will
# receive from lapply
removeAfterT <- function( x, time.cutoff ){
  
  # Filter out later timepoints
  x2 <- x[ x[,"t"] <= time.cutoff, ]
  
  # Return the new matrix, or NULL if there are no timepoints before the cutoff
  if( nrow(x2) == 0 ){
    return(NULL)
  } else {
    return(x2)
  }
}

# Call function on each track using lapply
filtered.t <- lapply( t, function(x) removeAfterT( x, 200 ) )

# Remove any tracks where NULL was returned
filtered.t <- filtered.t[ !sapply( filtered.t, is.null )]

Note that lapply() returns list but not a tracks object:

str(filtered.t, list.len = 3 )

## List of 144
##  $ 1   : num [1:7, 1:4] 48 72 96 120 144 ...
##   ..- attr(*, "dimnames")=List of 2
##   .. ..$ : NULL
##   .. ..$ : chr [1:4] "t" "x" "y" "z"
##  $ 2   : num [1:7, 1:4] 48 72 96 120 144 ...
##   ..- attr(*, "dimnames")=List of 2
##   .. ..$ : NULL
##   .. ..$ : chr [1:4] "t" "x" "y" "z"
##  $ 3   : num [1:8, 1:4] 24 48 72 96 120 ...
##   ..- attr(*, "dimnames")=List of 2
##   .. ..$ : NULL
##   .. ..$ : chr [1:4] "t" "x" "y" "z"
##   [list output truncated]

is.list( filtered.t )

## [1] TRUE

is.tracks( filtered.t )

## [1] FALSE

We can fix this by calling as.tracks().

filtered.t <- as.tracks( filtered.t )
is.tracks( filtered.t )

## [1] TRUE

str(filtered.t, list.len = 1)

## List of 144
##  $ 1   : num [1:7, 1:4] 48 72 96 120 144 ...
##   ..- attr(*, "dimnames")=List of 2
##   .. ..$ : NULL
##   .. .. [list output truncated]
##   [list output truncated]
##  - attr(*, "class")= chr "tracks"

We now have a new tracks object, which contains only tracks that had coordinates at t < 200.

2.4 Built-in filtering/subsetting functions

The package contains several built-in functions to filter and subset tracks.

The function filterTracks() can be used to select tracks with a certain property. For example, to select all tracks with at least 15 steps (16 datapoints):

# The filtering function must return TRUE or FALSE for each track given to it
my.filter <- function(x){
  return( nrow(x) > 15 )
}

# Filter with this function using filterTracks
long.tracks <- filterTracks( my.filter, t )

# check the minimum track length; # steps = number of coordinates minus 1
min( sapply( long.tracks, nrow ) - 1 )

## [1] 15

The function selectTracks() selects tracks based on upper and lower bounds of a certain measure. For example, we can get the fastest half of the T cells:

# Filter with this function using filterTracks
median.speed <- median( sapply( t, speed ) )
fast.tracks <- selectTracks( t, speed, median.speed, Inf )

# these should have a higher mean speed
c( "all tracks" = mean( sapply( t, speed ) ),
   "fastest half" = mean( sapply( fast.tracks, speed ) ) )

##   all tracks fastest half 
##    0.1650678    0.2255908

Another option is to filter not tracks, but timepoints within those tracks. Using the function subsample(), we can adjust the time resolution of the data by keeping e.g. only every k^th timepoint:

# Lower resolution
lower.res <- subsample( t, k = 2 )

# Plot the result; plot just one track to see the result more clearly
par(mfrow=c(1,2))
plot( t[1], main = "Original data")
plot( lower.res[1], main = "Lower resolution" )

2.5 Extracting subtracks

The package also contains functions to extract parts of tracks. For example, use subtracks() to extract subtracks of a given length:

subtrack.nsteps <- 2
t.2steps <- subtracks( t, subtrack.nsteps )
str( t.2steps, list.len = 3 )

## List of 4641
##  $ 1.1    : num [1:3, 1:4] 48 72 96 90.9 89.6 ...
##   ..- attr(*, "dimnames")=List of 2
##   .. ..$ : NULL
##   .. ..$ : chr [1:4] "t" "x" "y" "z"
##  $ 1.2    : num [1:3, 1:4] 72 96 120 89.6 88.7 ...
##   ..- attr(*, "dimnames")=List of 2
##   .. ..$ : NULL
##   .. ..$ : chr [1:4] "t" "x" "y" "z"
##  $ 1.3    : num [1:3, 1:4] 96 120 144 88.7 87.3 ...
##   ..- attr(*, "dimnames")=List of 2
##   .. ..$ : NULL
##   .. ..$ : chr [1:4] "t" "x" "y" "z"
##   [list output truncated]
##  - attr(*, "class")= chr "tracks"

Note that these subtracks overlap:

# Last step of the first subtrack and first step of the second are equal
t.2steps[c(1,2)]

## $`1.1`
##       t       x       y        z
## [1,] 48 90.8534 65.3943 -6416.80
## [2,] 72 89.5923 64.9042 -6419.93
## [3,] 96 88.6958 67.1125 -6421.80
## 
## $`1.2`
##        t       x       y        z
## [1,]  72 89.5923 64.9042 -6419.93
## [2,]  96 88.6958 67.1125 -6421.80
## [3,] 120 87.3437 68.2392 -6424.08
## 
## attr(,"class")
## [1] "tracks"

We can prevent this by adjusting the overlap argument to 0, or even to negative values so that space is left between the subtracks:

t.2steps.b <- subtracks( t, subtrack.nsteps, overlap = 0 )

# No longer any overlap
t.2steps.b[c(1,2)]

## $`1.1`
##       t       x       y        z
## [1,] 48 90.8534 65.3943 -6416.80
## [2,] 72 89.5923 64.9042 -6419.93
## [3,] 96 88.6958 67.1125 -6421.80
## 
## $`1.3`
##        t       x       y        z
## [1,]  96 88.6958 67.1125 -6421.80
## [2,] 120 87.3437 68.2392 -6424.08
## [3,] 144 86.2740 67.9236 -6425.14
## 
## attr(,"class")
## [1] "tracks"

An alternative to subtracks() is prefixes(), which returns only the first subtrack of a given length from each track:

t.prefixes <- prefixes( t, subtrack.nsteps )

# these subtracks come from different cells
t.prefixes[c(1,2)]

## $`1`
##       t       x       y        z
## [1,] 48 90.8534 65.3943 -6416.80
## [2,] 72 89.5923 64.9042 -6419.93
## [3,] 96 88.6958 67.1125 -6421.80
## 
## $`2`
##       t       x       y        z
## [1,] 48 200.672 38.0959 -6441.29
## [2,] 72 200.464 38.0264 -6441.29
## [3,] 96 200.928 37.7967 -6441.29

If we want to extract subtracks starting at a specific timepoint, use subtracksByTime():

# Check which timepoints occur in the dataset
tp <- timePoints(t)
tp

##  [1]  24  48  72  96 120 144 168 192 216 240 264 288 312 336 360 384 408 432 456 480 504 528 552 576 600 624 648 672 696
## [30] 720 744 768 792 816 840 864 888 912 936 960

# Extract all subtracks starting from the third timepoint
t.sbytime <- subtracksByTime( t, tp[3], subtrack.nsteps )

t.sbytime[c(1,2)]

## $`1`
##        t       x       y        z
## [1,]  72 89.5923 64.9042 -6419.93
## [2,]  96 88.6958 67.1125 -6421.80
## [3,] 120 87.3437 68.2392 -6424.08
## 
## $`2`
##        t       x       y        z
## [1,]  72 200.464 38.0264 -6441.29
## [2,]  96 200.928 37.7967 -6441.29
## [3,] 120 198.919 38.5586 -6441.29
## 
## attr(,"class")
## [1] "tracks"