ReadImmuneMap: Read tracks from ImmuneMap

Description

Reads tracks from https://immunemap.org for import into celltrackR. This produces both tracks object(s) and a dataframe with metadata.

Usage

read.immap.json(
  url,
  tracks.url = NULL,
  keep.id = TRUE,
  scale.auto = TRUE,
  scale.t = NULL,
  scale.pos = NULL,
  warn.scaling = TRUE,
  simplify.2D = TRUE,
  warn.celltypes = TRUE,
  split.celltypes = FALSE,
  ...
)
parse.immap.json(url)
get.immap.tracks(
  input,
  keep.id = TRUE,
  scale.t = NULL,
  scale.pos = NULL,
  warn.scaling = TRUE,
  simplify.2D = TRUE
)

Value

read.immap.json returns a list with:

tracks: either a single tracks object or a named list of tracks objects per cell type (if split.celltypes = TRUE
metadata: a dataframe with metadata for all the track.ids; this is read from the immunemap json file.

parse.immap.json simply returns the R list generated from the input json file.

get.immap.tracks returns a single tracks object.

Arguments

url: of the json file to download from immunemap; this should be the url to the video metadata without the "/tracks" suffix. With this method, the metadata will be used to automatically scale time to seconds and coordinates to microns if scale.auto=TRUE.
tracks.url: optional: alternatively, provide directly the url of the tracks (ending with "/tracks"), or an url of a local json file with tracks. With this method, scales must be set manually. If not specified, it is assumed that adding the suffix "/tracks" to the supplied url will provide the track data.
keep.id: logical: keep track ids from immunemap? If false, new unique ids are generated. Defaults to TRUE. If there are no ids in the input json, a warning will be returned; this can be suppressed by setting keep.id = FALSE.
scale.auto: logical: if TRUE (the default), scales will be set automatically using the metadata found in url. This works only if the url is given, not if only tracks.url is supplied.
scale.t: optional: multiply timepoints with constant factor to rescale time. By default, immunemap returns time in # frames.
scale.pos: optional: multiply coordinates with constant factor to rescale lengths. By default, immunemap measures coordinates in pixels.
warn.scaling: logical: if scale.t and scale.pos are not set, warn the user that units are pixels and #frames instead of microns and min/sec. Defaults to TRUE.
simplify.2D: logical: if TRUE (default), automatically project to 2D when the z-coordinate has only one value.
warn.celltypes: logical: if TRUE (default), warn when the user is either trying to return a single tracks object while the metadata indicates there are multiple celltypes in the data, or when the user is trying to set split.celltypes = TRUE when there is only one celltype present.
split.celltypes: logical: if TRUE (default = FALSE), return not one tracks object but a list of tracks objects for each celltype in the data (as determined from the metadata in the immunemap json).
...: additional parameters to be passed to get.immap.metadata.
input: the output of parse.immap.json serves as input for get.immap.tracks

Details

read.immap.json internally uses parse.immap.json to parse the json file, get.immap.tracks to extract the tracks, and get.immap.metadata to read the metadata.

Examples

Run this code

if (FALSE) {
## Read tracks from immunemap online, using the video info for automatic scaling
tr <- read.immap.json( url = "https://api.immunemap.org/video/14" )

## Read tracks and rescale time (.5min/frame) and coordinates (2microns/pixel)
tracksUrl <- "https://api.immunemap.org/video/14/tracks"
tr <- read.immap.json( tracks.url = tracksUrl, scale.auto = FALSE, scale.t = .5, scale.pos = 2 )
}

## Read tracks from a file 
# tr <- read.immap.json( tracks.url = "my-file.json", warn.scaling = FALSE )