implemented concatenate_fcs_files + minor fixes

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: premessa
 Type: Package
 Title: R package for pre-processing of flow and mass cytometry data
-Version: 0.1.9
+Version: 0.2.0
 Author: "Pier Federico Gherardini <pfgherardini@parkerici.org> [aut, cre]"
 Description: This package includes panel editing/renaming for FCS files, bead-based normalization and debarcoding.
 Imports: shiny (>= 0.14), flowCore, reshape, ggplot2, hexbin, gridExtra, rhandsontable, jsonlite

NAMESPACE

@@ -1,6 +1,7 @@
 # Generated by roxygen2: do not edit by hand
 
 export(as_flowFrame)
+export(concatenate_fcs_files)
 export(debarcode_data)
 export(debarcode_fcs)
 export(debarcoder_GUI)

R/fcs_io.R

@@ -113,6 +113,37 @@ as_flowFrame <- function(exprs.m, source.frame = NULL) {
 
 }
 
+#' Concatente multiple FCS files into a single one
+#'
+#' This function concatenates multilpe FCS files into a single one. It assumes that the files are all identical
+#' panel-wise (i.e. parameters names and descriptions, $PxN and $PxS FCS keywords)
+#'
+#' @param files.list Character vector of FCS file paths to concatenate
+#' @param output.file The path the concatenated file will be written to. If this is \code{NULL} the data
+#'   is returned as a \code{flowFrame} instead, which you can write with \code{\link{write_flowFrame}}
+#'
+#' @return If an \code{output.file} is provided, this function returns \code{NULL}, otherwise the data is returned
+#'   as a \code{flowFrame}
+#'
+#' @export
+concatenate_fcs_files <- function(files.list, output.file = NULL) {
+    m <- lapply(files.list, flowCore::read.FCS)
+
+    # Use the first flowFrame as reference
+    flow.frame <- m[[1]]
+
+    m <- lapply(m, function(x) {flowCore::exprs(x)})
+    m <- do.call(rbind, m)
+
+    ret <- as_flowFrame(m, flow.frame)
+
+    if(!is.null(output.file))
+        write_flowFrame(ret, output.file)
+    else
+        return(ret)
+
+}
+
 #' Write a flowFrame as FCS file
 #'
 #' This function writes a flowFrame as an FCS file, taking care of updating the \code{$FILENAME} keyword
@@ -124,6 +155,7 @@ write_flowFrame <- function(flowFrame, path) {
     f.name <- basename(path)
     flowCore::keyword(flowFrame)[["$FIL"]] <- f.name
     flowCore::write.FCS(flowFrame, path)
+    return(invisible(NULL))
 }
 
 read_fcs <- function(f.name) {

README.md

@@ -49,8 +49,9 @@ This will install the premessa R package together with all the required dependen
 
 # Usage
 
-The software allows you to perform two operations:
+The software allows you to perform four operations:
 - [Panel editing and renaming](#panel-editing-and-renaming)
+- [FCS file concatenation](#fcs-file-concatenation)
 - [Bead-based normalization](#bead-based-normalization)
 - [De-barcoding](#de-barcoding)
 
@@ -68,7 +69,7 @@ The consequence of this choice is that **the ordering of the channels is not pre
 
 ## Starting the GUI and selecting the working directory
 
-You can start the normalizer GUI by typing the following commands in your R session
+You can start the panel editor GUI by typing the following commands in your R session
 
 ```
 library(premessa)
@@ -82,6 +83,8 @@ To stop the software simply hit the "ESC" key in your R session.
 
 Once you have selected the working directory, the software will extract the panel information from all the FCS files contained in the directory. This information is then displayed in a table, where each row corresponds to a different parameter name ($PnN keyword), indicated by the row names (leftmost column), and each column corresponds to a different file, indicated in the column header. Each cell represents the description string ($PnS keyword) of a specific parameter in a given file. If a parameter is missing from a file, the word *absent* is displayed in the corresponding cell, which will be colored orange (note that this means that *absent* cannot be a valid parameter name)
 
+Whatever is written in the table when the *Process files* button is pressed, represents what the parameters will be renamed to. In other words the table represents the current state of the files, and you have to edit the individual cells as necessary to reflect the desired final state of the files. You can use the same shortcuts you use in Excel to facilitate the editing process (e.g. shift-click to select multiple rows or columns, ctrl-C and ctrl-V for copy and paste respectively, etc.). However be careful that pressing ctrl-Z (the conventional undo shortcut) will undo *all* you changes
+
 The table begins with three special columns:
 - *Remove*: if the box is checked the corresponding parameter is removed from all the files, and the row is grayed out
 - *Parameter*: this column represent the parameter name ($PnN keyword). Initially it will be identical to the first column of row names, but this column is editable. You can edit this column if you want to change the parameter names in the output files.
@@ -96,8 +99,9 @@ Two controls are located at the top of the table
 
 
 
+## FCS file concatenation
 
-
+The `premessa` package contains a simple function for concatenating multiple FCS files together. This is useful in case the acquisition of a single samples has been split across multiple files. The function is called `concatenate_fcs_files` and its documentation can be acessed directly from R. Note that this function assumes that the files are all identical panel-wise, i.e. they have the same parameter names and descriptions. Please use the [panel editor](#panel-editing-and-renaming) before concatenation if that is not the case.
 
 ## Bead-based normalization
 
@@ -167,7 +171,7 @@ This panel contains the following controls:
 - *Select beads type*: select the type of normalization beads that have been used for the experiment. Most users will select the default *Fluidigm Beads (140, 151, 153, 165, 175)*. These are the beads [sold](https://www.fluidigm.com/reagents/proteomics/201078-eq-four-element-calibration-beads--100ml) by Fluidigm. The numbers indicate the beads channels used for normalization.
 - *Select FCS file*: the FCS  that is currently being visualized for gating. This dropdown will contain all the FCS files located in the working directory. The gating plots will appear under the row of buttons.
 - *Select baseline for normalization*: the baseline beads intensities to be used for normalization. You can either use the median beads intensities of the FCS files that you are currently using for normalization (*Current files* option), or the median intensities of an existing set of beads files (*Existing folder of beads files*). If you select the latter a file dialog window will pop-up when you select the option. Use the window to navigate to a directory containing FCS files containing beads events only (for instance the *A_beads.fcs* file in the above example) and select one of the files. The software will then load *all* the files contained in the same directory as the file you selected. The currently selected folder will be displayed in a text box on the right. 
-- *Identify beads*: clicking this button will color in red the events that are recognized as beads events in the gating plots.
+- *Visualize beads*: clicking this button will color in red the events that are recognized as beads events in the gating plots. Note that this is for visualization only, whether you press this button or not has no effect on the normalization process
 - *Apply current gates to all files*: applies the current gates to all the files.
 - *Normalize*: starts the normalization routine. When the process is completed a confirmation dialog will appear
 

inst/normalizer_shinyGUI/server.R

@@ -49,7 +49,7 @@ render_normalizer_ui <- function(working.directory, ...){renderUI({
                 ),
                 p("You have gated beads for the following files (Only these files will be normalized):"),
                 verbatimTextOutput("normalizerui_dialog2"),
-                actionButton("normalizerui_identify_beads", "Identify beads"),
+                actionButton("normalizerui_visualize_beads", "Visualize beads"),
                 actionButton("normalizerui_apply_gates_all_files", "Apply current gates to all files"),
                 actionButton("normalizerui_normalize_files", "Normalize")
             )
@@ -286,7 +286,7 @@ shinyServer(function(input, output, session) {
 
     })
 
-    observeEvent(input$normalizerui_identify_beads, {
+    observeEvent(input$normalizerui_visualize_beads, {
         isolate({
             fcs <- get_fcs()
             m <- get_exprs()

inst/paneleditor_shinyGUI/server.R

@@ -21,9 +21,9 @@ render_paneleditor_ui <- function(working.directory, ...) {renderUI({
 
 
 get_panel_table <- function(files.list) {
-    print("Reading FCS parameters...")
+    message("Reading FCS parameters...")
     panel.table <- premessa:::read_parameters(files.list)
-    print("Done")
+    message("Done")
     common.names <- premessa:::get_common_names(panel.table)
     problem.idx <- premessa:::get_problem_idx(panel.table, common.names)
     panel.table <- panel.table[, order(colSums(problem.idx), decreasing = T), drop = F]