load_clinical_data.R

#' @title Loads a table containing clinical data.
#'
#' @description This function loads the clinical data associated with a dataset. It returns an annotated
#' data-frame that contains the clinical data.
#'
#' Note: the function assumes that a TSV file containing the clinical data exists. In
#' particular, it does not check for the existence of folders or files.
#'
#' @param data_dir A string representing the folder that contains the clinical data.
#' @param clinical_file_name A string containing the file name. By default, this is 'ClinicalData.tsv'
#' @param use_factors A boolean stating whether the columns should be read as factors (default FALSE).
#' @param verbose A boolean representing whether the function should display log information. This
#'  is FALSE by default.
#' @return An annotated data-frame that contains the clinical data.
load_clinical_data <- function(data_dir,
                               clinical_file_name = "ClinicalData.tsv",
                               use_factors        = TRUE,
                               verbose            = FALSE) {

  # We define the I/Os.
  clinical_data_file <- paste0(data_dir, clinical_file_name)
  if (verbose == TRUE) {
    message(paste0("[", Sys.time(), "] File set to ", clinical_data_file))
  }

  # We load the clinical data.
  pheno_data <- NULL
  if (use_factors) {
    pheno_data <- Biobase::AnnotatedDataFrame(utils::read.delim(file       = clinical_data_file,
                                                                row.names  = 1,
                                                                colClasses = "factor"))
  } else {
    # We do not use factors.
    pheno_data <- Biobase::AnnotatedDataFrame(utils::read.delim(file       = clinical_data_file,
                                                                row.names  = 1))
  }

  # We clean up and log information.
  rm(clinical_data_file)
  if (verbose == TRUE) {
    data_dimensions <- paste0(dim(pheno_data), collapse = " * ")
    message(paste0("[", Sys.time(), "] Clinical data read (", data_dimensions, ")."))
    rm(data_dimensions)
  }

  # We return the clinical data.
  return(pheno_data)
}