Dealing with documentation (#1)

.Rbuildignore

@@ -0,0 +1,7 @@
+^.*\.Rproj$
+^\.Rproj\.user$
+^doc$
+^Meta$
+.gitignore
+readme.md
+readme.Rmd

DESCRIPTION

@@ -1,10 +1,10 @@
 Package: cytoqc
 Type: Package
-Title: Quality control for cytometry
-Version: 0.99.1
-Author: Mike Jiang, Jake Wagner
+Title: Quality control and standardization of cytometry data
+Version: 0.99.2
+Author: Mike Jiang, Jake Wagner, Greg Finak
 Maintainer: Mike Jiang <[email protected]>
-Description: Provides quality control and quality assessment tools for cytometry data. 
+Description: Provides quality control, quality assessment, and data standardization tools for cytometry. 
 Depends: R (>= 3.5.0)
 Imports: 
     methods,
@@ -20,9 +20,11 @@ Imports:
     purrr,
     shiny,
     tibble,
-    tidyr
+    tidyr,
+    stats,
+    graphics
 License: Artistic-2.0
-biocViews: ImmunoOncology, Infrastructure, FlowCytometry, CellBasedAssays
+biocViews: Infrastructure, FlowCytometry, CellBasedAssays
 Suggests: 
     rmarkdown
 VignetteBuilder: knitr

NAMESPACE

@@ -84,6 +84,7 @@ importFrom(dplyr,select)
 importFrom(dplyr,summarise)
 importFrom(dplyr,ungroup)
 importFrom(flowCore,parameters)
+importFrom(flowCore,write.FCS)
 importFrom(flowWorkspace,colnames)
 importFrom(ggcyto,autoplot)
 importFrom(ggplot2,aes)
@@ -93,13 +94,15 @@ importFrom(ggplot2,geom_jitter)
 importFrom(ggplot2,geom_point)
 importFrom(ggplot2,ggplot)
 importFrom(ggplot2,scale_color_identity)
+importFrom(graphics,abline)
 importFrom(kableExtra,cell_spec)
 importFrom(kableExtra,collapse_rows)
 importFrom(kableExtra,column_spec)
 importFrom(kableExtra,kable_styling)
 importFrom(kableExtra,row_spec)
 importFrom(knitr,kable)
 importFrom(knitr,knit_print)
+importFrom(methods,is)
 importFrom(purrr,map)
 importFrom(purrr,map_dfr)
 importFrom(purrr,reduce)
@@ -114,6 +117,14 @@ importFrom(shiny,renderPlot)
 importFrom(shiny,selectInput)
 importFrom(shiny,shinyApp)
 importFrom(shiny,wellPanel)
+importFrom(stats,dbeta)
+importFrom(stats,dt)
+importFrom(stats,mad)
+importFrom(stats,median)
+importFrom(stats,optim)
+importFrom(stats,pbeta)
+importFrom(stats,pnorm)
+importFrom(stats,pt)
 importFrom(tibble,add_row)
 importFrom(tibble,as.tibble)
 importFrom(tibble,tibble)
@@ -122,3 +133,4 @@ importFrom(tidyr,pivot_wider)
 importFrom(tidyr,separate)
 importFrom(tidyr,separate_rows)
 importFrom(tidyr,unite)
+importFrom(utils,adist)

R/cqc_find_reference.R

@@ -48,7 +48,7 @@ cqc_find_params_reference <- function(cqc_cf_list, type = c("channel", "marker")
 cqc_remove_not_in_reference <- function(x, ...)UseMethod("cqc_remove_not_in_reference")
 #' @importFrom flowWorkspace colnames
 #' @export
-cqc_remove_not_in_reference.cqc_report_channel <- function(x, cqc_cf_list){
+cqc_remove_not_in_reference.cqc_report_channel <- function(x, cqc_cf_list,...){
   for(sn in names(x))
   {
     check_result <- x[[sn]]
@@ -65,7 +65,7 @@ cqc_remove_not_in_reference.cqc_report_channel <- function(x, cqc_cf_list){
   }
 }
 #' @export
-cqc_remove_not_in_reference.cqc_report_marker <- function(x, cqc_cf_list){
+cqc_remove_not_in_reference.cqc_report_marker <- function(x, cqc_cf_list,...){
   for(sn in names(x))
   {
     check_result <- x[[sn]]

R/cqc_find_solution.R

@@ -31,16 +31,19 @@ cqc_find_solution.cqc_match_result_keyword <- function(x, ...){
 #' Find solution to resolve the discrepancy discovered by match_reference
 #'
 #' It tries to find the aproximate match(based on 'agrep') between the target and reference as well as the extra redundunt items that can be removed.
-#'
+#' @name cqc_find_solution
 #' @return a table (with 'from' and 'to' columns) represents the itemized fix recommendation. When 'to' is 'NA', it means the entry is redundunt and can be removed
 #' @examples
 #' \dontrun{
 #' solution <-  cqc_find_solution(groups, select = c(1, 4))
 #' }
+#' @param x A CQC object of some kind. See vignettes.
 #' @param max.distance Maximum distance allowed for a match. See ?agrep
+#' @param ... additional arguments not for the user. 
 #' @importFrom tibble tibble add_row
+#' @importFrom utils adist
 #' @export
-cqc_find_solution.cqc_match_result <- function(x, max.distance = 0.1){
+cqc_find_solution.cqc_match_result <- function(x, max.distance = 0.1,...){
   res <- map_dfr(x, function(check_result)
   {
     unknown <- check_result[["unknown"]]

R/cqc_fix.R

@@ -6,10 +6,10 @@ cqc_fix <- function(x, ...)UseMethod("cqc_fix")
 #'
 #' Peform the actual fixing action (i.e update or delete)
 #' @param x the cqc_solution returned by 'find_solution' calls
-#'
+#' @param ... addiitional arguments not for the user.
 #' @importFrom dplyr rowwise do
 #' @export
-cqc_fix.cqc_solution <- function(x, func){
+cqc_fix.cqc_solution <- function(x,...){
   group <- attr(x, "group")
   cqc_data <- attr(group, "data")
   type <- sub("cqc_solution_", "", class(x)[[1]])
@@ -29,7 +29,7 @@ cqc_fix.cqc_solution <- function(x, func){
 #' @export
 cqc_delete <- function(x, ...)UseMethod("cqc_delete")
 #' @export
-cqc_delete.cytoframe <- function(x, value, type){
+cqc_delete.cytoframe <- function(x, value, type, ...){
   if(type == "channel")
   {
     cols <- flowWorkspace::colnames(x)
@@ -55,7 +55,7 @@ cqc_delete.GatingSet <- function(x, ...){
 #' @export
 cqc_update <- function(x, ...)UseMethod("cqc_update")
 #' @export
-cqc_update.cytoframe <- function(x, from, to, type){
+cqc_update.cytoframe <- function(x, from, to, type,...){
   if(type == "channel")
   {
     flowWorkspace:::setChannel(x@pointer, from, to)
@@ -71,7 +71,7 @@ cqc_update.cytoframe <- function(x, from, to, type){
 
 }
 #' @export
-cqc_update.GatingSet <- function(x, from, to, type){
+cqc_update.GatingSet <- function(x, from, to, type,...){
   if(type == "channel")
     gs_update_channels(x, map = data.frame(old = from
                                            , new = to

R/cqc_group.R

@@ -29,7 +29,7 @@ cqc_group.cqc_gs_list <- function(x, ...){
   attr(res, "data") <- x
   res
 }
-#' QC check
+#' Perform a QC check on flow data.
 #'
 #' This is the first step of the entire qc workflow.
 #' It extracts meta information(specified by 'type' argument) from the raw data
@@ -40,14 +40,15 @@ cqc_group.cqc_gs_list <- function(x, ...){
 #' @param x cqc_cf_list
 #' @param type specify the qc type, can be "channel", "marker" or "panel"
 #' @param delimiter a special character used to separate channel and marker
+#' @param ... additional arguments.
 #' @examples
 #' \dontrun{
 #' groups <- cqc_group(cqc_cf_list, "channel")
 #' }
 #' @export
 #' @importFrom dplyr filter arrange pull mutate group_indices distinct count add_count
 #' @importFrom tidyr separate separate_rows
-cqc_group.cqc_cf_list <- function(x, type = c("channel", "marker", "panel", "keyword"), delimiter = "|"){
+cqc_group.cqc_cf_list <- function(x, type = c("channel", "marker", "panel", "keyword"), delimiter = "|",...){
   sep <- paste0(delimiter, delimiter)#double delimiter for sep params and single delimiter for sep channel and marker
   keys <- sapply(x, function(cf){
     if(type == "keyword")
@@ -89,18 +90,19 @@ cqc_group.cqc_cf_list <- function(x, type = c("channel", "marker", "panel", "key
   res
 }
 
-#' Provide the summary view of the qc report
+#' Provide the summary view of the cqc_group report.
 #'
 #' It summarise the sample-wise qc report into group overview report for reference selection and further QC action.
 #'
 #' @param object qc table returned by 'cqc_group'
+#' @param ... Additional arguments not for the user. Ignore.
 #' @examples
 #' \dontrun{
 #' su <- summary(groups)
 #'
 #' }
 #' @export
-summary.cqc_group <- function(object){
+summary.cqc_group <- function(object,...){
   res <-  object %>%
     select(-c(object)) %>%
     distinct()
@@ -109,31 +111,33 @@ summary.cqc_group <- function(object){
 }
 
 #' @export
-diff.cqc_group_keyword <- function(x){
+diff.cqc_group_keyword <- function(x,...){
 
   diff.cqc_group(x, c("keyword"))
 }
 
 #' @export
-diff.cqc_group_channel <- function(x){
+diff.cqc_group_channel <- function(x,...){
 
   diff.cqc_group(x, c("channel"))
 }
 
 #' @export
-diff.cqc_group_marker <- function(x){
+diff.cqc_group_marker <- function(x,...){
 
   diff.cqc_group(x, c("marker"))
 }
 #' @export
-diff.cqc_group_panel <- function(x){
+diff.cqc_group_panel <- function(x,...){
 
   diff.cqc_group(x, c("channel", "marker"))
 }
 
-#' Helper function to only show the difference among qc group
+#' Display the differences among QC groups
 #'
 #' @param x the grouped summary report generated by 'summary' call on the 'cqc_group' results
+#' @param vars variable to split by. Determined automatically.
+#' @param ... Additional arguments not for the user. Ignore.
 #' @examples
 #' \dontrun{
 #' su <- summary(groups)
@@ -143,7 +147,7 @@ diff.cqc_group_panel <- function(x){
 #' @importFrom dplyr group_split inner_join anti_join
 #' @importFrom purrr reduce map map_dfr
 #' @export
-diff.cqc_group <- function(x, vars){
+diff.cqc_group <- function(x, vars, ...){
   grps <- x %>%
     group_split(group_id)
   commons <- grps %>% reduce(inner_join, by = vars)
@@ -152,13 +156,13 @@ diff.cqc_group <- function(x, vars){
     `class<-`(value = class(x))
 }
 
-#' Split the samples into groups
+#' Split the result of 'cqc_group' into groups
 #'
 #' It is used to split samples into separate groups when they can't be reconciled into the sampe group.
 #'
 #' @importFrom purrr walk
 #' @export
-split.cqc_group <- function(x){
+split.cqc_group <- function(x, f,drop=FALSE,...){
   cqc_data <- attr(x, "data")
   data_type <- class(cqc_data)
   vec <- x %>% select(c(object, group_id)) %>% distinct() %>% pull(group_id)
@@ -168,7 +172,7 @@ split.cqc_group <- function(x){
   })
 }
 
-#' Helper function to remove the outlier groups that can't be fixed
+#' Remove outlier groups from the result of 'cqc_group'.
 #'
 #' @param groups the object returned by 'cqc_groups'
 #' @param id the group id to be dropped from the dataset
@@ -184,7 +188,7 @@ cqc_drop_groups <- function(groups, id){
   groups
 }
 
-#' Helper function to extract the data from 'cqc_groups' object
+#' Extract the data from the result of a 'cqc_groups' call.
 #'
 #' @param groups the object returned by 'cqc_groups'
 #' @param id the group id to be selected from the dataset, default is NULL, meaning all data
@@ -198,9 +202,9 @@ cqc_get_data <- function(groups, id = NULL){
   }
   cqc_data
 }
-#' set reference
+#' Set a reference sample for further QC.
 #'
-#' It is the step prior to the further qc solution finding step.
+#' This is the first step prior to finding a QC solution for a data set.
 #'
 #' @param x cqc report generated by 'cqc_group'
 #' @param ref specifies the reference, which can be either an integer group id or a characte vector giving the actual values of the reference

R/cqc_io.R

@@ -1,6 +1,9 @@
 #' Load FCS files
-#' load fcs into 'cqc_cf_list' object which is a list of cytoframes
+#' load fcs into 'cqc_cf_list' object which is a list of cytoframes.
+#' This is the method to construct the core data object for cytoQC.
+#' @param is_h5 \code{logical} should the cytoframe be constructed as an h5 disk-backed structure. Default \code{TRUE}.
 #' @import flowWorkspace
+#' @importFrom methods is
 #' @export
 cqc_load_fcs <- function(files, is_h5 = TRUE, ...){
   res <- sapply(files, function(file)load_cytoframe_from_fcs(file, is_h5 = is_h5, ...))
@@ -10,7 +13,7 @@ cqc_load_fcs <- function(files, is_h5 = TRUE, ...){
 
 #' Construct a 'cqc_cf_list' object from a list of 'cytoframe' objects
 #'
-#' For the methods dispatching purpose
+#' This is the core data object for CytoQC.
 #'
 #' @param x a list of 'cytoframe' objects
 #' @export
@@ -32,11 +35,13 @@ cqc_cf_list <- function(x){
 #' @export
 write_fcs <- function(x, ...)UseMethod("write_fcs")
 
-#' The helper function to write the cleaned cqc_cf_list back to fcs
+#' Write out tidied flow data (cqc_cf_list) back to fcs
 #' @param x cqc_cf_list
+#' @param ... additional arguments.
 #' @param out the output directory that the FCS will be written
+#' @importFrom flowCore write.FCS
 #' @export
-write_fcs.cqc_cf_list <- function(x, out, verbose = TRUE){
+write_fcs.cqc_cf_list <- function(x, out, verbose = TRUE,...){
   if(!dir.exists(out))
     dir.create(out)
   for(sn in names(x))

R/outlier.R

@@ -21,11 +21,13 @@
 #'@author Mike Jiang,Greg Finak
 #'
 #'Maintainer: Mike Jiang <wjiang2@@fhcrc.org>
-#'@seealso \code{\link{qaCheck}},\code{\link[QUALIFIER:qaReport]{qaReport}}
+#'@seealso \code{\link[QUALIFIER:qaCheck]{qaCheck}},\code{\link[QUALIFIER:qaReport]{qaReport}}
 #'@keywords functions
-#' @rdname outlierFunctions
-#' @export
-#' @aliases rlm outlierFunctions
+#'@importFrom graphics abline
+#'@importFrom stats dbeta dt mad median optim pbeta pnorm pt
+#'@rdname outlierFunctions
+#'@export
+#'@aliases rlm outlierFunctions
 proportion.outliers.robust<-function (x, alpha = 0.01,isUpper=TRUE,isLower=TRUE)
 {
 	outliers<-rep(FALSE,length(x))

R/print.R

@@ -1,5 +1,5 @@
 #' @export
-print.cqc_cf_list <- function(x){
+print.cqc_cf_list <- function(x,...){
   cat("cytoqc data: \n")
   cat(length(x), " samples \n")
 }