@@ -11,3 +11,4 @@

 ^doc$

 ^Design$

 ^sample_reports$

+^man-roxygen$

@@ -44,8 +44,9 @@ Imports:

     readxl,

     tools,

     Rcapture,

-    grDevices, 

-    zip

+    grDevices,

+    forcats,

+    glue

 Encoding: UTF-8

 LazyData: false

 Roxygen: list(markdown = TRUE)

@@ -71,7 +72,8 @@ Suggests:

     circlize,

     plotly,

     gtools,

-    eulerr

+    eulerr,

+    openxlsx

 VignetteBuilder: knitr

 RdMacros: 

     lifecycle

@@ -20,12 +20,15 @@ export(compute_abundance)

 export(compute_near_integrations)

 export(cumulative_count_union)

 export(cumulative_is)

-export(date_columns_coll)

 export(date_formats)

+export(default_af_transform)

 export(default_iss_file_prefixes)

 export(default_meta_agg)

+export(default_rec_agg_lambdas)

 export(default_report_path)

 export(default_stats)

+export(fisher_scatterplot)

+export(gene_frequency_fisher)

 export(generate_Vispa2_launch_AF)

 export(generate_blank_association_file)

 export(generate_default_folder_structure)

@@ -55,6 +58,7 @@ export(refGene_table_cols)

 export(remove_collisions)

 export(reset_af_columns_def)

 export(reset_annotation_IS_vars)

+export(reset_dyn_vars_config)

 export(reset_iss_stats_specs)

 export(reset_mandatory_IS_vars)

 export(reset_matrix_file_suffixes)

@@ -70,6 +74,7 @@ export(sharing_venn)

 export(threshold_filter)

 export(top_abund_tableGrob)

 export(top_integrations)

+export(top_targeted_genes)

 export(transform_columns)

 export(unzip_file_system)

 import(ggplot2)

@@ -87,39 +92,28 @@ importFrom(data.table,.N)

 importFrom(data.table,.SD)

 importFrom(data.table,`%chin%`)

 importFrom(data.table,fread)

-importFrom(data.table,melt.data.table)

-importFrom(data.table,rbindlist)

 importFrom(data.table,setDT)

 importFrom(data.table,setnames)

 importFrom(dplyr,across)

 importFrom(dplyr,all_of)

-importFrom(dplyr,anti_join)

 importFrom(dplyr,arrange)

 importFrom(dplyr,bind_cols)

 importFrom(dplyr,bind_rows)

-importFrom(dplyr,contains)

-importFrom(dplyr,cur_column)

 importFrom(dplyr,desc)

 importFrom(dplyr,distinct)

 importFrom(dplyr,everything)

 importFrom(dplyr,filter)

-importFrom(dplyr,first)

-importFrom(dplyr,full_join)

 importFrom(dplyr,group_by)

 importFrom(dplyr,group_keys)

 importFrom(dplyr,group_modify)

 importFrom(dplyr,group_split)

-importFrom(dplyr,if_else)

-importFrom(dplyr,intersect)

 importFrom(dplyr,left_join)

 importFrom(dplyr,mutate)

 importFrom(dplyr,n)

-importFrom(dplyr,n_distinct)

 importFrom(dplyr,pull)

 importFrom(dplyr,rename)

 importFrom(dplyr,rename_with)

 importFrom(dplyr,select)

-importFrom(dplyr,semi_join)

 importFrom(dplyr,slice)

 importFrom(dplyr,slice_head)

 importFrom(dplyr,starts_with)

@@ -129,10 +123,8 @@ importFrom(fs,as_fs_path)

 importFrom(fs,dir_create)

 importFrom(fs,dir_exists)

 importFrom(fs,dir_ls)

-importFrom(fs,file_exists)

 importFrom(fs,is_dir)

 importFrom(fs,path)

-importFrom(fs,path_dir)

 importFrom(fs,path_ext)

 importFrom(fs,path_ext_set)

 importFrom(fs,path_home)

@@ -141,8 +133,6 @@ importFrom(ggplot2,aes)

 importFrom(ggplot2,aes_)

 importFrom(ggplot2,element_blank)

 importFrom(ggplot2,element_text)

-importFrom(ggplot2,geom_hline)

-importFrom(ggplot2,geom_point)

 importFrom(ggplot2,geom_raster)

 importFrom(ggplot2,geom_text)

 importFrom(ggplot2,ggplot)

@@ -152,12 +142,8 @@ importFrom(ggplot2,rel)

 importFrom(ggplot2,scale_alpha_continuous)

 importFrom(ggplot2,scale_fill_gradientn)

 importFrom(ggplot2,scale_fill_viridis_d)

-importFrom(ggplot2,scale_x_continuous)

-importFrom(ggplot2,scale_y_continuous)

 importFrom(ggplot2,sym)

 importFrom(ggplot2,theme)

-importFrom(ggplot2,unit)

-importFrom(ggrepel,geom_label_repel)

 importFrom(lifecycle,deprecate_warn)

 importFrom(lubridate,today)

 importFrom(magrittr,`%>%`)

@@ -166,8 +152,6 @@ importFrom(purrr,detect_index)

 importFrom(purrr,flatten)

 importFrom(purrr,flatten_chr)

 importFrom(purrr,is_empty)

-importFrom(purrr,is_formula)

-importFrom(purrr,is_function)

 importFrom(purrr,map)

 importFrom(purrr,map2)

 importFrom(purrr,map2_dfr)

@@ -206,27 +190,19 @@ importFrom(rlang,list2)

 importFrom(rlang,parse_expr)

 importFrom(rlang,sym)

 importFrom(stats,dt)

-importFrom(stats,na.omit)

 importFrom(stats,setNames)

 importFrom(stats,shapiro.test)

 importFrom(stringr,str_detect)

-importFrom(stringr,str_pad)

-importFrom(stringr,str_replace)

 importFrom(stringr,str_replace_all)

 importFrom(stringr,str_split)

-importFrom(stringr,str_to_lower)

 importFrom(stringr,str_to_upper)

 importFrom(tibble,add_column)

 importFrom(tibble,as_tibble)

 importFrom(tibble,tibble)

 importFrom(tibble,tribble)

 importFrom(tidyr,nest)

-importFrom(tidyr,pivot_longer)

 importFrom(tidyr,pivot_wider)

-importFrom(tidyr,separate)

 importFrom(tidyr,unite)

 importFrom(tidyr,unnest)

 importFrom(tools,file_path_sans_ext)

-importFrom(utils,read.csv)

 importFrom(utils,read.delim)

-importFrom(zip,unzip)

@@ -11,5 +11,9 @@

 #'  \code{\link{import_parallel_Vispa2Matrices}}

 #'  * import_parallel_Vispa2Matrices_interactive:

 #'  \code{\link{import_parallel_Vispa2Matrices}}

+#'  * unzip_file_system:

+#'  \code{\link{generate_default_folder_structure}}

+#'  * cumulative_count_union:

+#'  \code{\link{cumulative_is}}

 #' @keywords internal

 NULL

@@ -3,7 +3,8 @@

 #------------------------------------------------------------------------------#

 #' Performs aggregation on metadata contained in the association file.

 #'

-#' \lifecycle{stable}

+#' @description

+#' `r lifecycle::badge("stable")`

 #' Groups metadata by the specified grouping keys and returns a

 #' summary of info for each group. For more details on how to use this function:

 #' \code{vignette("aggregate_function_usage", package = "ISAnalytics")}

@@ -20,10 +21,8 @@

 #' @param import_stats `r lifecycle::badge("deprecated")` The import

 #' of VISPA2 stats has been moved to its dedicated function,

 #' see \link{import_Vispa2_stats}.

-#' @family Aggregate functions

-#' @importFrom rlang abort inform

-#' @importFrom purrr is_empty

-#' @import lifecycle

+#'

+#' @family Data cleaning and pre-processing

 #'

 #' @return An aggregated data frame

 #' @export

@@ -101,9 +100,8 @@ aggregate_metadata <- function(association_file,

 #' * `Output_colname`: a `glue` specification that will be used to determine

 #' a unique output column name. See \link[glue]{glue} for more details.

 #'

-#' @importFrom tibble tribble

 #' @return A data frame

-#' @family Aggregate functions

+#' @family Data cleaning and pre-processing

 #' @export

 #'

 #' @examples

@@ -146,7 +144,8 @@ default_meta_agg <- function() {

 #' Aggregates matrices values based on specified key.

 #'

-#' \lifecycle{stable}

+#' @description

+#' `r lifecycle::badge("stable")`

 #' Performs aggregation on values contained in the integration matrices based

 #' on the key and the specified lambda. For more details on how to use this

 #' function:

@@ -206,12 +205,13 @@ default_meta_agg <- function() {

 #' @param join_af_by A character vector representing the joining key

 #' between the matrix and the metadata. Useful to re-aggregate already

 #' aggregated matrices.

-#' @family Aggregate functions

+#'

+#' @family Data cleaning and pre-processing

 #'

 #' @importFrom purrr walk set_names map_lgl

 #' @importFrom rlang expr eval_tidy abort

 #'

-#' @return A list of tibbles or a single tibble aggregated according to

+#' @return A list of data frames or a single data frame aggregated according to

 #' the specified arguments

 #' @export

 #'

@@ -248,43 +248,46 @@ aggregate_values_by_key <- function(x,

     data.table::setDT(association_file)

     stopifnot(is.list(lambda) && !is.null(names(lambda)))

     join_key_err <- c("Join key not present in in both data frames",

-                      x = paste("Fields specified in the argument",

-                                "`join_af_by` must appear in both",

-                                "the association file and the matrix(es)"))

+        x = paste(

+            "Fields specified in the argument",

+            "`join_af_by` must appear in both",

+            "the association file and the matrix(es)"

+        )

+    )

     check_single_matrix <- function(df) {

-      stopifnot(is.data.frame(df))

-      is_numeric_col <- purrr::map_lgl(

-        value_cols,

-        ~ is.numeric(df[[.x]]) ||

-          is.double(df[[.x]]) ||

-          is.integer(df[[.x]])

-      ) %>% purrr::set_names(value_cols)

-      if (any(!is_numeric_col)) {

-        rlang::abort(.non_num_user_cols_error(

-          names(is_numeric_col)[!is_numeric_col]

-        ))

-      }

-      if (!all(join_af_by %in% colnames(df))) {

-        rlang::abort(join_key_err, class = "join_key_err_agg")

-      }

+        stopifnot(is.data.frame(df))

+        is_numeric_col <- purrr::map_lgl(

+            value_cols,

+            ~ is.numeric(df[[.x]]) ||

+                is.double(df[[.x]]) ||

+                is.integer(df[[.x]])

+        ) %>% purrr::set_names(value_cols)

+        if (any(!is_numeric_col)) {

+            rlang::abort(.non_num_user_cols_error(

+                names(is_numeric_col)[!is_numeric_col]

+            ))

+        }

+        if (!all(join_af_by %in% colnames(df))) {

+            rlang::abort(join_key_err, class = "join_key_err_agg")

+        }

     }

     if (!is.data.frame(x)) {

-      purrr::walk(x, check_single_matrix)

+        purrr::walk(x, check_single_matrix)

     } else {

-      check_single_matrix(x)

+        check_single_matrix(x)

     }

-    join_key_in_af  <- all(join_af_by %in% colnames(association_file))

+    join_key_in_af <- all(join_af_by %in% colnames(association_file))

     if (!join_key_in_af) {

-      rlang::abort(join_key_err, class = "join_key_err_agg")

+        rlang::abort(join_key_err, class = "join_key_err_agg")

     }

     agg_matrix <- if (is.data.frame(x)) {

         .aggregate_lambda(

             x, association_file, key, value_cols, lambda, group, join_af_by

         )

     } else {

-      agg_matrix <- purrr::map(x, ~ .aggregate_lambda(

-        .x, association_file, key, value_cols, lambda, group, join_af_by

-      ))

+        agg_matrix <- purrr::map(x, ~ .aggregate_lambda(

+            .x, association_file, key, value_cols, lambda, group, join_af_by

+        ))

     }

     return(agg_matrix)

 }

@@ -4,7 +4,8 @@

 #' Computes the abundance for every integration event in the input data frame.

 #'

-#' \lifecycle{stable}

+#' @description

+#' `r lifecycle::badge("stable")`

 #' Abundance is obtained for every integration event by calculating the ratio

 #' between the single value and the total value for the given group.

 #'

@@ -13,6 +14,11 @@

 #' relative abundance column (and optionally a percentage abundance

 #' column) will be produced.

 #'

+#' @section Required tags:

+#' The function will explicitly check for the presence of these tags:

+#'

+#' * All columns declared in `mandatory_IS_vars()`

+#'

 #' @param x An integration matrix - aka a data frame that includes

 #' the `mandatory_IS_vars()` as columns. The matrix can either be aggregated

 #' (via `aggregate_values_by_key()`) or not.

@@ -29,12 +35,6 @@

 #'

 #' @family Analysis functions

 #'

-#' @importFrom magrittr `%>%`

-#' @importFrom dplyr group_by across all_of summarise left_join mutate

-#' @importFrom dplyr cur_column distinct select contains rename_with

-#' @importFrom rlang .data eval_tidy parse_expr abort

-#' @importFrom purrr map_lgl

-#' @importFrom stringr str_replace

 #' @return Either a single data frame with computed abundance values or

 #' a list of 2 data frames (abundance_df, quant_totals)

 #' @export

@@ -130,7 +130,7 @@ compute_abundance <- function(x,

 #' Filter data frames with custom predicates

 #'

 #' @description

-#' \lifecycle{experimental}

+#' `r lifecycle::badge("stable")`

 #' Filter a single data frame or a list of data frames with custom

 #' predicates assembled from the function parameters.

 #'

@@ -242,7 +242,7 @@ compute_abundance <- function(x,

 #' character vectors. Must be one of the allowed values between

 #' `c("<", ">", "==", "!=", ">=", "<=")`

 #'

-#' @family Analysis functions

+#' @family Data cleaning and pre-processing

 #'

 #' @return A data frame or a list of data frames

 #' @export

@@ -291,7 +291,8 @@ threshold_filter <- function(x,

 #' Sorts and keeps the top n integration sites based on the values

 #' in a given column.

 #'

-#' \lifecycle{experimental}

+#' @description

+#' `r lifecycle::badge("stable")`

 #' The input data frame will be sorted by the highest values in

 #' the columns specified and the top n rows will be returned as output.

 #' The user can choose to keep additional columns in the output

@@ -300,6 +301,11 @@ threshold_filter <- function(x,

 #' * `keep = "nothing"` only keeps the mandatory columns

 #' (`mandatory_IS_vars()`) plus the columns in the `columns` parameter.

 #'

+#' @section Required tags:

+#' The function will explicitly check for the presence of these tags:

+#'

+#' * All columns declared in `mandatory_IS_vars()`

+#'

 #' @param x An integration matrix (data frame containing

 #' `mandatory_IS_vars()`)

 #' @param n How many integrations should be sliced (in total or

@@ -316,8 +322,6 @@ threshold_filter <- function(x,

 #'

 #' @family Analysis functions

 #'

-#' @importFrom magrittr `%>%`

-#' @importFrom rlang abort

 #'

 #' @return Either a data frame with at most n rows or

 #' a data frames with at most n*(number of groups) rows.

@@ -344,7 +348,7 @@ threshold_filter <- function(x,

 #'     keep = "Value2",

 #'     key = "CompleteAmplificationID"

 #' )

-#top_abundant_is

+# top_abundant_is

 top_integrations <- function(x,

     n = 20,

     columns = "fragmentEstimate_sum_RelAbundance",

@@ -408,6 +412,75 @@ top_integrations <- function(x,

 }

+#' Top n targeted genes based on number of IS.

+#'

+#' @description

+#' `r lifecycle::badge("experimental")`

+#' Produces a summary of the number of integration events per gene, orders

+#' the table in decreasing order and slices the first n rows - either on

+#' all the data frame or by group.

+#'

+#' @details

+#' ## Gene grouping

+#' When producing a summary of IS by gene, there are different options that

+#' can be chosen.

+#' The argument `consider_chr` accounts for the fact that some genes (same

+#' gene symbol) may span more than one chromosome: if set to `TRUE`

+#' counts of IS will be separated for those genes that span 2 or more

+#' chromosomes - in other words they will be in 2 different rows of the

+#' output table. On the contrary, if the argument is set to `FALSE`,

+#' counts will be produced in a single row.

+#'

+#' NOTE: the function counts **DISTINCT** integration events, which logically

+#' corresponds to a union of sets. Be aware of the fact that counts per group

+#' and counts with different arguments might be different: if for example

+#' counts are performed by considering chromosome and there is one gene symbol

+#' with 2 different counts, the sum of those 2 will likely not be equal to

+#' the count obtained by performing the calculations without

+#' considering the chromosome.

+#'

+#' The same reasoning can be applied for the argument `consider_gene_strand`,

+#' that takes into account the strand of the gene.

+#'

+#' @section Required tags:

+#' The function will explicitly check for the presence of these tags:

+#'

+#' ```{r echo=FALSE, results="asis"}

+#' all_tags <- available_tags()

+#' needed <- unique(all_tags[purrr::map_lgl(eval(rlang::sym("needed_in")),

+#'  ~ "top_targeted_genes" %in% .x)][["tag"]])

+#'  cat(paste0("* ", needed, collapse="\n"))

+#' ```

+#'

+#' Note that the tags "gene_strand" and "chromosome" are explicitly required

+#' only if `consider_chr = TRUE` and/or `consider_gene_strand = TRUE`.

+#'

+#' @param x An integration matrix - must be annotated

+#' @param n Number of rows to slice

+#' @param key If slice has to be performed for each group, the character

+#' vector of column names that identify the groups. If `NULL` considers the

+#' whole input data frame.

+#' @param consider_chr Logical, should the chromosome be taken into account?

+#' See details.

+#' @param consider_gene_strand Logical, should the gene strand be taken into

+#' account? See details.

+#' @param as_df If computation is performed by group, `TRUE` returns all

+#' groups merged in a single data frame with a column containing the group id.

+#' If `FALSE` returns a named list.

+#'

+#' @importFrom rlang sym

+#'

+#' @return A data frame or a list of data frames

+#' @export

+#' @family Analysis functions

+#'

+#' @examples

+#' data("integration_matrices", package = "ISAnalytics")

+#' top_targ <- top_targeted_genes(

+#'     integration_matrices,

+#'     key = NULL

+#' )

+#' top_targ

 top_targeted_genes <- function(x,

     n = 20,

     key = c(

@@ -417,70 +490,134 @@ top_targeted_genes <- function(x,

     consider_chr = TRUE,

     consider_gene_strand = TRUE,

     as_df = TRUE) {

-  stopifnot(is.data.frame(x))

-  data.table::setDT(x)

-  stopifnot(is.numeric(n) || is.integer(n))

-  stopifnot(is.null(key) || is.character(key))

-  stopifnot(is.logical(consider_chr))

-  stopifnot(is.logical(consider_gene_strand))

+    stopifnot(is.data.frame(x))

+    data.table::setDT(x)

+    stopifnot(is.numeric(n) || is.integer(n))

+    stopifnot(is.null(key) || is.character(key))

+    stopifnot(is.logical(consider_chr))

+    stopifnot(is.logical(consider_gene_strand))

-  required_annot_tags <- c("gene_symbol")

-  if (consider_gene_strand) {

-    required_annot_tags <- c(required_annot_tags, "gene_strand")

-  }

-  annot_tag_cols <- .check_required_cols(required_annot_tags,

-                                         annotation_IS_vars(TRUE),

-                                         "error")

-  if (consider_chr) {

-    chr_tag_col <- .check_required_cols(c("chromosome", "locus"),

-                                        mandatory_IS_vars(TRUE),

-                                        "error")

-    annot_tag_cols <- annot_tag_cols %>%

-      dplyr::bind_rows(chr_tag_col)

-  }

-  data.table::setDT(annot_tag_cols)

-  cols_to_check <- c(annot_tag_cols$names, key)

-  if (!all(cols_to_check %in% colnames(x))) {

-    rlang::abort(.missing_needed_cols(

-      cols_to_check[!cols_to_check %in% colnames(x)]))

-  }

+    required_annot_tags <- c("gene_symbol")

+    if (consider_gene_strand) {

+        required_annot_tags <- c(required_annot_tags, "gene_strand")

+    }

+    annot_tag_cols <- .check_required_cols(

+        required_annot_tags,

+        annotation_IS_vars(TRUE),

+        "error"

+    )

+    if (consider_chr) {

+        chr_tag_col <- .check_required_cols(

+            c("chromosome", "locus"),

+            mandatory_IS_vars(TRUE),

+            "error"

+        )

+        annot_tag_cols <- annot_tag_cols %>%

+            dplyr::bind_rows(chr_tag_col)

+    }

+    data.table::setDT(annot_tag_cols)

+    cols_to_check <- c(annot_tag_cols$names, key)

+    if (!all(cols_to_check %in% colnames(x))) {

+        rlang::abort(.missing_needed_cols(

+            cols_to_check[!cols_to_check %in% colnames(x)]

+        ))

+    }

-  df_with_is_counts <- if (is.null(key)) {

-    .count_distinct_is_per_gene(

-      x = x, include_chr = consider_chr,

-      include_gene_strand = consider_gene_strand,

-      gene_sym_col = annot_tag_cols[

-        eval(sym("tag")) == "gene_symbol"][["names"]],

-      gene_strand_col = annot_tag_cols[

-        eval(sym("tag")) == "gene_strand"][["names"]],

-      chr_col = annot_tag_cols[eval(sym("tag")) == "chromosome"][["names"]],

-      mand_vars_to_check = mandatory_IS_vars(TRUE)

-    ) %>%

-      dplyr::arrange(dplyr::desc(.data$n_IS)) %>%

-      dplyr::slice_head(n = n)

-  } else {

-    tmp <- x[, .count_distinct_is_per_gene(

-      x = .SD, include_chr = consider_chr,

-      include_gene_strand = consider_gene_strand,

-      gene_sym_col = annot_tag_cols[

-        eval(sym("tag")) == "gene_symbol"][["names"]],

-      gene_strand_col = annot_tag_cols[

-        eval(sym("tag")) == "gene_strand"][["names"]],

-      chr_col = annot_tag_cols[eval(sym("tag")) == "chromosome"][["names"]],

-      mand_vars_to_check = mandatory_IS_vars(TRUE)

-    ), by = eval(key)]

-    tmp[,

-        .SD %>% dplyr::arrange(dplyr::desc(.data$n_IS)) %>%

-          dplyr::slice_head(n = n),

-        by = eval(key)]

-  }

-  if (as_df) {

-    return(df_with_is_counts)

-  }

-  return(split(df_with_is_counts, by = key))

+    df_with_is_counts <- if (is.null(key)) {

+        .count_distinct_is_per_gene(

+            x = x, include_chr = consider_chr,

+            include_gene_strand = consider_gene_strand,

+            gene_sym_col = annot_tag_cols[

+                eval(sym("tag")) == "gene_symbol"

+            ][["names"]],

+            gene_strand_col = annot_tag_cols[

+                eval(sym("tag")) == "gene_strand"

+            ][["names"]],

+            chr_col = annot_tag_cols[eval(sym("tag")) ==

+                "chromosome"][["names"]],

+            mand_vars_to_check = mandatory_IS_vars(TRUE)

+        ) %>%

+            dplyr::arrange(dplyr::desc(.data$n_IS)) %>%

+            dplyr::slice_head(n = n)

+    } else {

+        tmp <- x[, .count_distinct_is_per_gene(

+            x = .SD, include_chr = consider_chr,

+            include_gene_strand = consider_gene_strand,

+            gene_sym_col = annot_tag_cols[

+                eval(sym("tag")) == "gene_symbol"

+            ][["names"]],

+            gene_strand_col = annot_tag_cols[

+                eval(sym("tag")) == "gene_strand"

+            ][["names"]],

+            chr_col = annot_tag_cols[eval(sym("tag")) ==

+                "chromosome"][["names"]],

+            mand_vars_to_check = mandatory_IS_vars(TRUE)

+        ), by = eval(key)]

+        tmp[,

+            .SD %>% dplyr::arrange(dplyr::desc(.data$n_IS)) %>%

+                dplyr::slice_head(n = n),

+            by = eval(key)

+        ]

+    }

+    if (as_df) {

+        return(df_with_is_counts)

+    }

+    return(split(df_with_is_counts, by = key))

 }

+#' Compute Fisher's exact test on gene frequencies.

+#'

+#' @description

+#' `r lifecycle::badge("experimental")`

+#' Provided 2 data frames with calculations for CIS, via `CIS_grubbs()`,

+#' computes Fisher's exact test.

+#' Results can be plotted via `fisher_scatterplot()`.

+#'

+#' @param cis_x A data frame obtained via `CIS_grubbs()`

+#' @param cis_y A data frame obtained via `CIS_grubbs()`

+#' @param min_is_per_gene Used for pre-filtering purposes. Genes with a

+#' number of distinct integration less than this number will be filtered out

+#' prior calculations. Single numeric or integer.

+#' @param gene_set_method One between "intersection" and "union". When merging

+#' the 2 data frames, `intersection` will perform an inner join operation,

+#' while `union` will perform a full join operation.

+#' @param significance_threshold Significance threshold for the Fisher's

+#' test p-value

+#' @param remove_unbalanced_0 Remove from the final output those pairs in

+#' which there are no IS for one group or the other and the number of

+#' IS of the non-missing group are less than the mean number of IS for that

+#' group

+#'

+#' @template genes_db

+#'

+#' @section Required tags:

+#' The function will explicitly check for the presence of these tags:

+#'

+#' ```{r echo=FALSE, results="asis"}

+#' all_tags <- available_tags()

+#' needed <- unique(all_tags[purrr::map_lgl(eval(rlang::sym("needed_in")),

+#'  ~ "gene_frequency_fisher" %in% .x)][["tag"]])

+#'  cat(paste0("* ", needed, collapse="\n"))

+#' ```

+#'

+#' @return A data frame

+#' @export

+#' @family Analysis functions

+#'

+#' @examples

+#' data("integration_matrices", package = "ISAnalytics")

+#' data("association_file", package = "ISAnalytics")

+#' aggreg <- aggregate_values_by_key(

+#'     x = integration_matrices,

+#'     association_file = association_file,

+#'     value_cols = c("seqCount", "fragmentEstimate")

+#' )

+#' cis <- CIS_grubbs(aggreg, by = "SubjectID")

+#' fisher <- gene_frequency_fisher(cis$cis$PT001, cis$cis$PT002,

+#'     min_is_per_gene = 2

+#' )

+#' fisher

 gene_frequency_fisher <- function(cis_x,

     cis_y,

     min_is_per_gene = 3,

@@ -506,142 +643,169 @@ gene_frequency_fisher <- function(cis_x,

     stopifnot(is.logical(remove_unbalanced_0))

     ## -- Fetch gene symbol column

     gene_sym_col <- .check_required_cols(

-      "gene_symbol", annotation_IS_vars(TRUE), duplicate_politic = "error"

+        "gene_symbol", annotation_IS_vars(TRUE),

+        duplicate_politic = "error"

     )[["names"]]

-    req_cis_cols <- c(gene_sym_col, "n_IS_perGene", "average_TxLen",

-                      "raw_gene_integration_frequency")

+    req_cis_cols <- c(

+        gene_sym_col, "n_IS_perGene", "average_TxLen",

+        "raw_gene_integration_frequency"

+    )

     quiet_expand <- purrr::quietly(.expand_cis_df)

-    cols_for_join <- c(gene_sym_col,

-                     "Onco1_TS2", "ClinicalRelevance", "DOIReference",

-                     "KnownGeneClass", "KnownClonalExpansion",

-                     "CriticalForInsMut")

+    cols_for_join <- c(

+        gene_sym_col,

+        "Onco1_TS2", "ClinicalRelevance", "DOIReference",

+        "KnownGeneClass", "KnownClonalExpansion",

+        "CriticalForInsMut"

+    )

     ## --- Calculations to perform on each df

     append_calc <- function(df, group_n) {

-      if (!all(req_cis_cols %in% colnames(df))) {

-        rlang::abort(

-          .missing_needed_cols(req_cis_cols[!req_cis_cols %in% colnames(df)]))

-      }

-      modified <- quiet_expand(df, gene_sym_col,

-                                 onco_db_file, tumor_suppressors_db_file,

-                                 species, known_onco, suspicious_genes)$result

-      modified <- modified %>%

-        dplyr::mutate(

-          IS_per_kbGeneLen = .data$raw_gene_integration_frequency * 1000,

-          Sum_IS_per_kbGeneLen = sum(.data$IS_per_kbGeneLen, na.rm = TRUE),

-          IS_per_kbGeneLen_perMDepth_TPM = (.data$IS_per_kbGeneLen /

-                                              .data$Sum_IS_per_kbGeneLen) * 1e6

-        ) %>%

-        dplyr::filter(.data$n_IS_perGene >= min_is_per_gene) %>%

-        dplyr::select(dplyr::all_of(c(req_cis_cols, cols_for_join,

-                                      "IS_per_kbGeneLen",

-                                      "Sum_IS_per_kbGeneLen",

-                                      "IS_per_kbGeneLen_perMDepth_TPM")))

-      colnames(modified)[!colnames(modified) %in% cols_for_join] <- paste(

-        colnames(modified)[!colnames(modified) %in% cols_for_join], group_n,

-        sep = "_"

-      )

-      return(modified)

+        if (!all(req_cis_cols %in% colnames(df))) {

+            rlang::abort(

+                .missing_needed_cols(req_cis_cols[!req_cis_cols %in%

+                    colnames(df)])

+            )

+        }

+        modified <- quiet_expand(

+            df, gene_sym_col,

+            onco_db_file, tumor_suppressors_db_file,

+            species, known_onco, suspicious_genes

+        )$result

+        modified <- modified %>%

+            dplyr::mutate(

+                IS_per_kbGeneLen = .data$raw_gene_integration_frequency * 1000,

+                Sum_IS_per_kbGeneLen = sum(.data$IS_per_kbGeneLen,

+                    na.rm = TRUE

+                ),

+                IS_per_kbGeneLen_perMDepth_TPM = (.data$IS_per_kbGeneLen /

+                    .data$Sum_IS_per_kbGeneLen) * 1e6

+            ) %>%

+            dplyr::filter(.data$n_IS_perGene >= min_is_per_gene) %>%

+            dplyr::select(dplyr::all_of(c(

+                req_cis_cols, cols_for_join,

+                "IS_per_kbGeneLen",

+                "Sum_IS_per_kbGeneLen",

+                "IS_per_kbGeneLen_perMDepth_TPM"

+            )))

+        colnames(modified)[!colnames(modified) %in% cols_for_join] <- paste(

+            colnames(modified)[!colnames(modified) %in% cols_for_join], group_n,

+            sep = "_"

+        )

+        return(modified)

     }

-    cis_mod <- purrr::map2(list(cis_x, cis_y), c(1,2), append_calc)

+    cis_mod <- purrr::map2(list(cis_x, cis_y), c(1, 2), append_calc)

     ## --- Merge the two in 1 df

     merged <- if (gene_set_method == "union") {

-      purrr::reduce(cis_mod, ~ dplyr::full_join(.x, .y, by = cols_for_join))

+        purrr::reduce(cis_mod, ~ dplyr::full_join(.x, .y, by = cols_for_join))

     } else {

-      purrr::reduce(cis_mod, ~ dplyr::inner_join(.x, .y, by = cols_for_join))

+        purrr::reduce(cis_mod, ~ dplyr::inner_join(.x, .y, by = cols_for_join))

     }

     if (nrow(merged) == 0) {

-      if (getOption("ISAnalytics.verbose") == TRUE) {

-        msg <- c("Data frame empty after filtering",

-                 i = paste("Data frame is empty after applying filter on IS,",

-                           "is your filter too stringent?"),

-                 x = "Nothing to return")

-        rlang::inform(msg, class = "empty_df_gene_freq")

-      }

-      return(NULL)

+        if (getOption("ISAnalytics.verbose") == TRUE) {

+            msg <- c("Data frame empty after filtering",

+                i = paste(

+                    "Data frame is empty after applying filter on IS,",

+                    "is your filter too stringent?"

+                ),

+                x = "Nothing to return"

+            )

+            rlang::inform(msg, class = "empty_df_gene_freq")

+        }

+        return(NULL)

     }

     ## --- Actual computation of fisher test: test is applied on each row

     ## (each gene)

     merged <- merged %>%

-      dplyr::mutate(

-        tot_n_IS_perGene_1 = sum(cis_x$n_IS_perGene, na.rm = TRUE),

-        tot_n_IS_perGene_2 = sum(cis_y$n_IS_perGene, na.rm = TRUE)

-      )

+        dplyr::mutate(

+            tot_n_IS_perGene_1 = sum(cis_x$n_IS_perGene, na.rm = TRUE),

+            tot_n_IS_perGene_2 = sum(cis_y$n_IS_perGene, na.rm = TRUE)

+        )

     compute_fisher <- function(...) {

-      row <- list(...)

-      n_IS_perGene_1 <- row$n_IS_perGene_1

-      n_IS_perGene_2 <- row$n_IS_perGene_2

-      n_IS_perGene_1[which(is.na(n_IS_perGene_1))] <- 0

-      n_IS_perGene_2[which(is.na(n_IS_perGene_2))] <- 0

-      matrix <- matrix(

-        data = c(n_IS_perGene_1,

-                 row$tot_n_IS_perGene_1 - n_IS_perGene_1,

-                 n_IS_perGene_2,

-                 row$tot_n_IS_perGene_2 - n_IS_perGene_2),

-        nrow = 2,

-        dimnames = list(G1 = c("IS_of_gene", "TotalIS"),

-                        G2 = c("IS_of_gene", "TotalIS"))

-      )

-      ft <- stats::fisher.test(matrix)

-      return(ft$p.value)

+        row <- list(...)

+        n_IS_perGene_1 <- row$n_IS_perGene_1

+        n_IS_perGene_2 <- row$n_IS_perGene_2

+        n_IS_perGene_1[which(is.na(n_IS_perGene_1))] <- 0

+        n_IS_perGene_2[which(is.na(n_IS_perGene_2))] <- 0

+        matrix <- matrix(

+            data = c(

+                n_IS_perGene_1,

+                row$tot_n_IS_perGene_1 - n_IS_perGene_1,

+                n_IS_perGene_2,

+                row$tot_n_IS_perGene_2 - n_IS_perGene_2

+            ),

+            nrow = 2,

+            dimnames = list(

+                G1 = c("IS_of_gene", "TotalIS"),

+                G2 = c("IS_of_gene", "TotalIS")

+            )

+        )

+        ft <- stats::fisher.test(matrix)

+        return(ft$p.value)

     }

     merged <- merged %>%