Import plain tracking output from a table.

Given the path of a table file (e.g., .txt or .csv, see read.table) or an already imported tibble, dataframe or list of vectors containing x and y coordinates (named X and Y respectively), the identity of the particle(s) and time, this function returns an object of class "tracklets", a list of tracklets (data frame) containing 7 elements classically used for further computations using MoveR package:

'x.pos': x position of the particle's centroid.
'y.pos': y position of the particle's centroid.
'identity': the particle's identity given by the tracking software.
'frame': the video frame number at which the measurements has been made.

Also, the function can flip y coordinates (see flipY argument).

Usage

readPlain(
  plainTab,
  sep = ";",
  dec = ".",
  id = "identity",
  timeCol = "frame",
  flipY = FALSE,
  imgHeight = NULL
)

Arguments

plainTab: The full path of a plain tracking output (e.g., .txt or .csv, see read.table) or an already imported tibble, dataframe or list of vectors.
sep: The field separator character. Values on each line of the file are separated by this character (default = ";" - only useful if plainTab is a path).
dec: The character used in the file for decimal points (default = "." - only useful if plainTab is a path).
id: A character string corresponding to the name of the column containing particle's identity (default = "identity").
timeCol: A character string corresponding to the name of the column containing Time information (default = "frame").
flipY: A logical value (i.e., TRUE or FALSE) indicating whether the origin of y coordinates should be flipped. If TRUE, y coordinates are flipped to start on the top-left (default = FALSE).
imgHeight: A numeric value expressed in pixels, the length of Y axis corresponding to the height of the image or video resolution (optional, only used when flipY = TRUE).

Value

An object of class "tracklets" containing a list of tracklets and their characteristics classically used for further computations. In case the input data (plainTab) contains other columns, those columns are also appended to the returned tracklets object

Author

Quentin PETITJEAN

Examples


set.seed(2023)
# generate some dummy tracklets
## start to specify some parameters to generate tracklets
TrackN <- 40 # the number of tracklet to simulate
TrackL <-
  1:1000 # the length of the tracklets or a sequence to randomly sample tracklet length
TrackList <- stats::setNames(lapply(lapply(seq(TrackN), function(i)
  trajr::TrajGenerate(sample(TrackL, 1), random = TRUE, fps = 1)), function(j) {
    data.frame(
      X = j$x - min(j$x),
      Y = j$y - min(j$y),
      frame = j$time
    )
  }), seq(TrackN))
## convert it to a simple list of vector
plainTab <- MoveR::convert2List(TrackList)
#> Error in MoveR::convert2List(TrackList): Invalid 'tracklets' object, please import your data with the 'read' functions included in the MoveR package or use `trackletsClass()` function to turn your data into 'tracklets' object

# Import the data as an object of class "tracklets" (the function can also retrieve the plainTab from a table file by giving the full path to the file)
# also do not flip Y coordinates (start on the bottom-left)
Data <-
  MoveR::readPlain(plainTab,
                   id = "trackletId")
#> Error in is.data.frame(plainTab): object 'plainTab' not found
str(Data)
#> Error in str(Data): object 'Data' not found