ReadImmuneMap {celltrackR}

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
)

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.

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.

Note

This functionality requires the rjson package to be installed.

See Also

get.immap.metadata.

Examples

## Not run: 
## 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 )

## End(Not run)

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