R/flowjo2df.R

In chris-hsiung/bears01: What the Package Does (One Line, Title Case)

#' Function to read csv file exported from flowjo. The original .fcs files from which the .csv file was generated must contain keywords. Parses sampleID from $FIL keyword and platename from $PLATENAME keyword and date from $DATE keyword.
#' Returns data frame
#' Intended for use within the function processFlowjoExportDir() for processing an entire directory of .csv files.
#' Updated 2022-08-02 to remove additional header lines inserted by Arc Attune that do not start with '$'
#' Updated 2023-04-04 added additional regex matches for identifying datacsv in case some variables are not exported from flowjo
#' Updated 2023-06-12 to allow IDvar as input

#' Warning: roxygen documentation generated by chatgpt

#'
#' #' Convert a flow cytometry file to a dataframe
#'
#' This function takes a flow cytometry file and transforms it into a dataframe.
#' It also extracts meta information such as plate name, file name and date from the file.
#' The function also allows you to add an ID variable.
#'
#' @param file A character string specifying the path of the flow cytometry file to be converted.
#' @param IDvar A character string specifying the name of the ID variable to be added to the dataframe.
#'
#' @return
#' A dataframe with the flow cytometry data. In the case where the file contains no data, the function returns NULL.
#'
#' @examples
#' \dontrun{
#' flowjo2df(file = "path_to_file.fcs", IDvar = "sample_ID")
#' }
#' @export

flowjo2df <- function( file, IDvar ){

      #print(file)
      lines <- readLines(file)
      lines2 <- lines[2:length(lines)] ## remove the first line which does not follow patterns

      metainfo <- lines2[ grepl("^\\$|^\\#", lines2) ]

      headercsv <- lines2[ grepl('FSC-A', lines2) & !grepl("^\\$|^\\#|FJ_FCS_VERSION|^HOSTID,XE3-IoT-", lines2) ]

      datacsv <- lines2[ !grepl("^\\$|^\\#|FJ_FCS_VERSION|^HOSTID,XE3-IoT-", lines2) & !grepl('FSC-A|SSC-A|BL1-A|VL1-A|RL1-A|YL1-A', lines2) ]

      if ( length(datacsv) == 0 ){
            message( paste0( file, ' contains no data, skipping.'))
            return( NULL )
      } else{
            header <- str_remove_all( unlist( strsplit( headercsv, "," ) ), '\"')

            df <- as.data.frame( matrix( unlist( strsplit( datacsv, ",")), nrow = length(datacsv), byrow=T))

            names(df) <- header

            platename <- str_remove( metainfo[ grepl( '^\\$PLATENAME', metainfo ) ], '\\$PLATENAME,' )

            # assertthat::assert_that( is.character(platename),
            #                          msg = 'platename must be character')

            filename <- str_remove( metainfo[ grepl( '^\\$FIL', metainfo ) ], '\\$FIL,' )

            filename <- str_remove( filename, '.fcs$' )

            date <- str_remove( metainfo[ grepl('^\\$DATE', metainfo)], '\\$DATE,' )

            # assertthat::assert_that( is.character(filename),
            #                          msg = 'filename must be character')

            df <- dplyr::mutate( df,
                                 !!sym(IDvar) := filename,
                                 platename = platename,
                                 date = date)

            return(df)

      }


}