README.Rmd

---
output: github_document
---

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

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

# TrackMateR <a href='https://quantixed.github.io/TrackMateR/'><img src='man/figures/logo.png' align="right" height="131.5" /></a>

<!-- badges: start -->
[![R-CMD-check](https://github.com/quantixed/TrackMateR/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/quantixed/TrackMateR/actions/workflows/R-CMD-check.yaml)
[![DOI](https://zenodo.org/badge/453722113.svg)](https://zenodo.org/badge/latestdoi/453722113)
<!-- badges: end -->

Analysis of TrackMate XML outputs in R.

[TrackMate](https://imagej.net/plugins/trackmate/) is a single-particle tracking plugin for ImageJ/Fiji.
The standard output from a tracking session is in TrackMate XML format.

The goal of this R package is to import all of the data associated with the final filtered tracks in TrackMate for further analysis and visualization in R.

## Installation

Once you have installed [R](https://cran.rstudio.com) and [RStudio Desktop](https://www.rstudio.com/products/rstudio/download/), you can install TrackMateR using devtools

```{r gh-installation, eval = FALSE}
# install.packages("devtools")
devtools::install_github("quantixed/TrackMateR")
```

## An Example

A basic example is to load one TrackMate XML file, calibrate it (if needed) and analyse it.

```{r example, fig.height = 8, fig.width = 8}
library(ggplot2)
library(TrackMateR)
# an example file is provided, otherwise use file.choose()
xmlPath <- system.file("extdata", "ExampleTrackMateData.xml", package="TrackMateR")
# read the TrackMate XML file into R using
tmObj <- readTrackMateXML(XMLpath = xmlPath)
# Pixel size is actually 0.04 um and original data was 1 pixel, xyscalar = 0.04
tmObj <- correctTrackMateData(dataList = tmObj, xyscalar = 0.04, xyunit = "um")
# generate a report
reportDataset(tmObj)
```

TrackMateR can generate several different types of plot individually using commands or it can make them all automatically and create a report for you.

- For details of how to make individual plots and/or tweak the default parameters, see `vignette("TrackMateR")`
- To see how to compare different datasets, see `vignette("comparison")`
- In order to rescale or recalibrate TrackMate data, see `vignette("recalibration")`

## Credits

- TrackMateR builds on initial work by Julien Godet on [trackR](https://github.com/jgodet/trackR).
- Méghane Sittewelle provided example TrackMate data and helped with testing TrackMateR.
- The Fiji plug-in [TrackMate](https://github.com/trackmate-sc/TrackMate) is developed by Jean-Yves Tinevez.

## Limitations, future development

- TrackMateR is currently written for 2D data. 3D data is read but analysis is currently on the first two dimensions.
- Addition of a dry run option to quickly report what data would be analysed by `compareDatasets()`.
- Addition of number of tracks per frame and more advanced calculation of the density of tracks.