README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# CPTrackR

<!-- badges: start -->
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4725472.svg)](https://doi.org/10.5281/zenodo.4725472)
[![R-CMD-check](https://github.com/burgerga/CPTrackR/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/burgerga/CPTrackR/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

The goal of CPTrackR is to add unique track ids to CellProfiler tracking output.

**NB:** No support for LAP tracking with temporal gaps (yet)

## Installation

You can install the development version of CPTrackR with:

``` r
remotes::install_github("burgerga/CPTrackR")
```

## Usage

### Creating a lookup table (LUT)

```{r, echo=F, message = FALSE, warning=FALSE}
library(tidyverse)

library(future)
plan(multisession)

# Example data is generated from a dataset from Britt (shared by Muriel)
# all_data <- read_tsv(file.path("~/../../Downloads","20190925_BrittData_singleCell_1hrDelay_withoutT01.txt"))
# data = all_data |>
#   filter(groupNumber <= 2) |>
#   select(groupNumber,
#          groupInd,
#          Nuclei_TrackObjects_ParentObjectNumber_30,
#          Nuclei_Number_Object_Number,
#          Nuclei_Intensity_MeanIntensity_image_green,
#          starts_with("Nuclei_Location_Center_"))

theme_set(theme_classic(base_size = 13))
```

Show some example uncorrected data extracted from a CellProfiler tsv:

```{r}
library(CPTrackR)
library(tidyverse)

data <- read_tsv(system.file("extdata", "cptrackr_example_data.tsv.xz", package="CPTrackR"), show_col_types = F)
data %>%
  select(groupNumber, 
         groupInd, 
         Nuclei_TrackObjects_ParentObjectNumber_30, 
         Nuclei_Number_Object_Number,
         Nuclei_Intensity_MeanIntensity_image_green)
```

We can create a lookup table (LUT) for a single group using `createLUTGroup`:

```{r}
library(CPTrackR)
lut <- createLUTGroup(data %>% filter(groupNumber == 1),
                      frame_var = groupInd, 
                      obj_var = Nuclei_Number_Object_Number,
                      par_obj_var = Nuclei_TrackObjects_ParentObjectNumber_30) 
lut %>% 
  arrange(Nuclei_Number_Object_Number, groupInd)
```

Three new columns are added:

* `cid`: id of the original cell (daughter cells share `cid` with parent)
* `uid`: unique id (daughter cells don't share `uid` with parent)
* `alt_uid`: character id of cells that show lineage with suffixes

For illustration here the second frame, where we can see `alt_uid`s for daughter cells:

```{r}
lut %>% 
  filter(groupInd == 2) %>%
  arrange(Nuclei_Number_Object_Number, groupInd)
```
We can also enable a progress bar (will be visible if you run this code in R):

```{r}
library(progressr)
with_progress({
  lut <- createLUTGroup(data %>% filter(groupNumber == 1),
                        frame_var = groupInd, 
                        obj_var = Nuclei_Number_Object_Number,
                        par_obj_var = Nuclei_TrackObjects_ParentObjectNumber_30) 
})
lut %>% 
  arrange(Nuclei_Number_Object_Number, groupInd)
```


We can create a LUT for multiple groups (=movies) using `createLut`, the `group_vars` are used to denote the different groups (can be multiple columns):

```{r}
with_progress({
  lut_all <- createLUT(data, 
                       group_vars = groupNumber, 
                       frame_var = groupInd, 
                       obj_var = Nuclei_Number_Object_Number, 
                       par_obj_var = Nuclei_TrackObjects_ParentObjectNumber_30) 
})
lut_all 
```

Now we can join the LUT to the original data

```{r}
fixed <- data %>% 
  left_join(lut_all) 
fixed %>%
  select(groupNumber, groupInd, uid, alt_uid, Nuclei_Intensity_MeanIntensity_image_green)
```

#### Parallelisation

We can also enable parallelisation using the `future` package and specifying a `plan`, this will give a considerable speed improvement if you have many movies:

```{r, eval = F}
library(future)
plan(multisession)
with_progress({
  lut_all <- createLUT(data, 
                       group_vars = groupNumber, 
                       frame_var = groupInd, 
                       obj_var = Nuclei_Number_Object_Number, 
                       par_obj_var = Nuclei_TrackObjects_ParentObjectNumber_30) 
})
lut_all
```

```{r, echo = F}
lut_all
```

### Plotting

With our `uid` per cell we can now plot the tracks:

```{r}
ggplot(fixed %>% filter(groupNumber == 1), 
       aes(Nuclei_Location_Center_X, Nuclei_Location_Center_Y, 
           group = uid, color = as.factor(uid))) + 
  geom_path() + 
  guides(color = F) +
  coord_fixed()
```