README.Rmd

---
title: mdftracks
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 = "README-"
)
```

<!-- badges: start -->
[![R-CMD-check](https://github.com/burgerga/mdftracks/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/burgerga/mdftracks/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/burgerga/mdftracks/branch/master/graph/badge.svg)](https://app.codecov.io/gh/burgerga/mdftracks?branch=master)
[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/mdftracks)](https://cran.r-project.org/package=mdftracks)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4692671.svg)](https://doi.org/10.5281/zenodo.4692671)
<!-- badges: end -->

## Overview

mdftracks reads and writes **[MTrackJ](https://imagescience.org/meijering/software/mtrackj/) Data Files** ([`.mdf`](https://imagescience.org/meijering/software/mtrackj/format/)).
Supports clusters, 2D data, and channel information. If desired, generates
unique track identifiers based on cluster and id data from the `.mdf` file.

## Installation

```{r, eval=F}
install.packages('mdftracks')
```

### Development version

To get a bug fix or to use a feature from the development version, you can install the development version from GitHub.

```{r, eval=F}
# install.packages("remotes")
remotes::install_github("burgerga/mdftracks")

```


## Usage

First load the package with 
```{r}
library(mdftracks)
```

### Reading 3D data

```{r}
mdf.file <- system.file("extdata", "example.mdf", package = 'mdftracks')
data <- read.mdf(mdf.file)
head(data, 10)
```

### Dropping the z-coordinate for 2D data

```{r}
data <- read.mdf(mdf.file, drop.Z = T)
head(data, 10)
```

### Writing data in `(id, t, x, y, z)` format (e.g., from [celltrackR](https://github.com/ingewortel/celltrackR))

```{r}
library('celltrackR')
tracks.df <- as.data.frame(TCells)
```

```{r, collapse=FALSE}
head(tracks.df, 10)
write.mdf(head(tracks.df, 10), pos.columns = c(3,4))
```

### Writing data with cluster, channel, and point information

```{r, collapse=FALSE}
print(mdftracks.example.data)
write.mdf(mdftracks.example.data, cluster.column = 'cl', id.column = 'id',  
          pos.columns = letters[24:26], channel.column = 'ch', 
          point.column = "p")
```

For more information, please consult the package documentation.