R/import_oufti.R

In vicstefanou/ViSCA: Cell-Movie Analysis and Visualization

#' Import \emph{Oufti} data
#'
#' Imports a \code{.csv} file generated by \emph{Oufti} and converts it into
#' a cell list containing all the cell instants of the movie.
#'
#' \emph{Oufti} treats the whole frame as a single colony.
#' \cr\cr
#' \emph{Oufti} does not export any information about either the pixels of each cell or the pixels each colony.
#' \cr\cr
#' \emph{Oufti} users importing the data with this function are \bold{excluded} from using
#' \code{\link{plot_col_tree}},
#' \code{\link{split_cell}}, \code{\link{get_cand_merge_cells}}, \code{\link{merge_cells}},
#' \code{\link{get_cand_mother_cells}}, \code{\link{add_branch}},
#' \code{\link{create_movie}}, \code{\link{create_cell_life}} and \code{\link{view_cell}}.
#'
#' @param file A character string naming the \code{.csv} file generated by \emph{Oufti}
#' (including the suffix \code{".csv"}) from which the data is to be imported.
#' If it does not contain an absolute path, the file name is relative to the current working directory, \code{getwd()}.
#' \cr\cr
#' NOTE: The components should be separated by \code{"/"} on Windows.
#' \cr\cr
#' Before using this function, the user has to open the \code{.csv} file in a text editor and
#' manually delete or comment (by adding the character \code{"\%"} at the beginning)
#' all lines of the file until the line with the \code{"\% parameter values"} string.
#'
#' @param pixelR The pixel ratio in units of length, a non-zero positive numeric value.
#'
#' @return A named list with the following components:
#' \item{col_list}{\code{NULL}}
#' \item{cell_list}{A list containing all the cell instants of the movie.
#' Each element of the list is a named list with the following components:
#' \itemize{
#' \item \code{cellName} is the name of the cell, a character string in the format \code{"c<cellId>_f<frame>"}
#' \item \code{frame} is the ID of the frame of the cell, a non-zero positive integer number
#' \item \code{colony} is the ID of the colony of the cell in the \code{frame}, equal to \code{1}
#' \item \code{daughterIds} is a vector of character strings containing the \code{cellName}
#' of the linked cell(s) in the next frame,
#' or \code{NULL} in case no such cells exist
#' \item \code{length} is the length of the cell in units of length, a non-zero positive numeric value
#' \item \code{area} is the area of the cell in squared units of length, a non-zero positive numeric value
#' \item \code{polarity} is a numeric value defining the polarity of the cell
#' }
#' }
#' \item{Nframes}{Number of frames in the movie, a non-zero positive integer value.
#' IDs of frames are in the range \code{[1, Nframes]}.}
#' \item{Ncols}{Number of colonies in the movie, equal to \code{1}.
#' IDs of colonies are in the range \code{[1, Ncols]}.}
#' \item{frameH}{\code{NULL}}
#' \item{frameW}{\code{NULL}}
#'
#' @references \url{http://oufti.org/}
#' @export
#' @importFrom utils read.table setTxtProgressBar txtProgressBar


import_oufti <- function(file, pixelR) {

  cat("Loading file...\n")
  meshes <- read.table(file, header = TRUE, sep = ",", dec = ".", quote = "", comment.char = "%", na.strings = "NA", stringsAsFactors = FALSE)

  # "frame" -> frameNumber without first "#"
  meshes$frame <- as.numeric(unlist(unname(sapply(meshes$frameNumber, function(x) strsplit(x, split = "#")[[1]][2]))))
  Nframes <- length(unique(meshes$frame))

  # "length"
  meshes$length <- meshes$length * pixelR
  # "area"
  meshes$area <- meshes$area * pixelR * pixelR

  # "colony" -> 1
  Ncols <- 1
  meshes$colony <- 1

  # "cellName" -> c<cellId>_f<frameNumber without first "#">
  meshes$cellName <- paste("c", meshes$cellId. , "_f", meshes$frame, sep = "")

  # "daughterIds"
  meshes$daughterIds <- ""

  for (cell in unique(meshes$cellId.)) {

    meshes[meshes$cellId. == cell, ]$daughterIds <- paste("c", cell, "_f", meshes[meshes$cellId. == cell, ]$frame + 1, sep = "")

    frame_division <- max(meshes[meshes$cellId. == cell, ]$frame)

    daughters <- meshes[meshes$cellId. == cell, ]$descendants
    daughters <- daughters[daughters != " "]

    meshes[meshes$cellId. == cell & meshes$frame == frame_division, ]$daughterIds <- ifelse(length(daughters) != 0,
                                                                                            toString( paste("c", unlist(strsplit(daughters, split = ";")), "_f", frame_division + 1, sep = "") ),
                                                                                            "")

  }


  cell_list <- list()

  cat("Creating cell list...\n")
  pb <- txtProgressBar(min = 0, max = nrow(meshes), style = 3) ### set progress bar
  ipb <- 0

  for (i_cell in 1:nrow(meshes))  {

    ipb <- ipb + 1
    setTxtProgressBar(pb, ipb) ### update progress bar

    if (meshes[i_cell, ]$daughterIds == "") {
      d <- NULL
    } else {
      d <- unlist(strsplit(meshes[i_cell, ]$daughterIds, split = ", "))
    }


    cell_list[[i_cell]] <- list(cellName = meshes[i_cell, ]$cellName,
                                frame = meshes[i_cell, ]$frame,
                                colony = meshes[i_cell, ]$colony,
                                daughterIds = d,
                                length = meshes[i_cell, ]$length,
                                area = meshes[i_cell, ]$area,
                                polarity = meshes[i_cell, ]$polarity)

  }

  close(pb) ### close progress bar
  cat("\n")

  cat("Checking cell list...\n")
  cell_list <- checkCellList(cell_list = cell_list, col_list = NULL)

  return(list(col_list = NULL, cell_list = cell_list,
              Nframes = Nframes, Ncols = Ncols,
              frameH = NULL, frameW = NULL))

}