Migrate mutation data to SQLite (gambl_mutations.db), fix SLMS-3/Publication dedup bug, auto-download via GitHub Releases

.Rbuildignore

@@ -2,3 +2,4 @@
 ^\.Rproj\.user$
 ^LICENSE\.md$
 ^data-raw$
+^gambl_mutations\.db$

.gitignore

@@ -1 +1,2 @@
 .Rproj.user
+gambl_mutations.db

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: GAMBLR.data
 Title: Collection of Curated Data for Genomic Analysis of Mature B-cell Lymphomas in R
-Version: 1.3
+Version: 1.5
 Authors@R:
     c(
         person(given = "Ryan",
@@ -25,15 +25,20 @@ Description: The package contains manually curated data for the genomic Analysis
 License: MIT + file LICENSE
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.2
+RoxygenNote: 7.3.3
 Depends:
     R (>= 3.5)
 LazyData: true
 Imports:
+    DBI,
+    dbplyr,
     dplyr,
     ggplot2,
+    rlang,
+    RSQLite,
     tidyr
 LazyDataCompression: xz
 Suggests:
+    piggyback,
     testthat (>= 3.0.0)
 Config/testthat/edition: 3

NAMESPACE

@@ -1,5 +1,12 @@
 # Generated by roxygen2: do not edit by hand
 
+export(download_gambl_mutations_db)
+export(gambl_mutations_db)
+export(gambl_reference_db)
+export(get_cn_segments_from_db)
+export(get_genes)
+export(get_ssm_from_db)
+export(get_sv_from_db)
 import(dplyr)
 import(ggplot2)
 import(tidyr)

R/data-vars.R

@@ -19,12 +19,13 @@ if (getRversion() >= "2.15.1") {
     "SCORE", "START_A", "START_B", "Start_Position", "Start_Position.x", 
     "Tumor_Sample_Barcode", "VAF_tumour", "Variant_Classification", 
     "bin", "category", "chrom", "cohort", "colour", "curated", "end", 
-    "ensembl_gene_id", "gambl_metadata", "gene", "genome_build", 
+    "ensembl_gene_id", "gene", "genome_build",
     "grch37_ashm_regions", "group", "head", "hg38_ashm_regions", 
-    "hot_spot", "hotspot_regions_grch37", "hotspot_regions_hg38", 
-    "is_alias", "log.ratio", "mutated", "mutation_count", "n_mut", 
-    "name", "pair_status", "pathology", "patient_id", "region", 
-    "row_id", "sample_id", "seq_type", "start", "t_alt_count", 
-    "tumour_sample_id", "window_end", "window_start"
+    "hot_spot", "hotspot_regions_grch37", "hotspot_regions_hg38",
+    "is_alias", "log.ratio", "maf_seq_type", "mutated", "mutation_count", "n_mut",
+    "name", "pair_status", "pathology", "patient_id", "region",
+    "row_id", "sample_id", "seq_type", "start", "t_alt_count",
+    "tumour_sample_id", "window_end", "window_start",
+    "study", "Pipeline", "elem"
   ))
 }

R/data.R

@@ -933,45 +933,6 @@
 "somatic_hypermutation_locations_GRCh38_v_latest"
 
 
-#' GAMBL Metadata
-#'
-#' A data frame with metadata for a collection of GAMBL samples.
-#'
-#' @format ## `gambl_metadata`
-#' A data frame with 4785 rows and 27 columns
-#' \describe{
-#'   \item{sample_id}{Sample identifier.}
-#'   \item{patient_id}{Patient identifier.}
-#'   \item{pathology}{Pathology.}
-#'   \item{seq_type}{Sample sequencing type.}
-#'   \item{genome_build}{Genome build the sample coordinates are in reference to.}
-#'   \item{pairing_status}{Matched or unmatched.}
-#'   \item{Tumor_Sample_Barcode}{Sample ID in another column, needed for certain functions.}
-#'   \item{age_group}{Sample age group.}
-#'   \item{compression}{The compression available for a particular sample.}
-#'   \item{bam_available}{Boolean.}
-#'   \item{pathology_rank}{Pathology rank.}
-#'   \item{cohort}{Sample cohort}
-#'   \item{COO_consensus}{COO consensus.}
-#'   \item{DHITsig_consensus}{DHIT signature consensus.}
-#'   \item{EBV_status_inf}{EBV status.}
-#'   \item{ffpe_or_frozen}{FFPE or frozen.}
-#'   \item{fl_grade}{FL grade.}
-#'   \item{hiv_status}{Sample HIV status.}
-#'   \item{lymphgen}{Lymphgen.}
-#'   \item{lymphgen_cnv_noA53}{Lymphgen with CNV no A53.}
-#'   \item{lymphgen_no_cnv}{Lymphgen no CNV.}
-#'   \item{lymphgen_with_cnv}{Lymphgen with CNV}
-#'   \item{lymphgen_wright}{Lymphgen Wright.}
-#'   \item{molecular_BL}{Molecualr BL.}
-#'   \item{normal_sample_id}{Normal sample ID}
-#'   \item{sex}{Female or Male}
-#'   \item{time_point}{Smaple timepoint.}
-#' }
-#' @keywords internal
-"gambl_metadata"
-
-
 #' Mirage Metrics
 #'
 #' A data frame with Quality Control metrics for a collection of GAMBL samples.

R/data_comp.R

@@ -3,197 +3,124 @@
 #'
 #' @description Retrieve gene names from bundled lymphoma gene lists.
 #'
-#' @details Complete lists of genes described as significantly mutated in large
-#' lymphoma studies have been curated and provided with this package.
+#' @details Gene lists are read from the bundled normalized reference database
+#' (`inst/extdata/gambl_reference.db`), which is built from the LLMPP curated
+#' lists. Confidence tier and data version are columns in that database, so the
+#' previous per-entity, per-version `.rda` objects are no longer required.
 #'
 #' @param entities Optional vector specifying one or more lymphoma entities
 #'      e.g. MCL, DLBCL, BL.
-#' @param curated_only Specify FALSE to retrieve all genes or leave default
-#'      for the curated subset.
+#' @param curated_only When TRUE (default) return the curated set (Tier 1 and
+#'      Tier 2) and drop retired Tier 3 genes. Set FALSE to include all tiers.
+#'      Ignored when `tier` is supplied.
+#' @param tier Optional integer vector of confidence tiers to keep, e.g.
+#'      `tier = 1` for high-confidence genes only, or `tier = c(1, 2)`. When
+#'      supplied it takes precedence over `curated_only`.
 #' @param gene_format Specify what to return as output. Can be one of:
 #'      * "symbol" (the default): list of gene symbols
-#'      * "ensembl": list of ENSEMBLE IDs
-#'      * "data.frame": data frame with column Gene and per-entity gene status
-#' @param version Specify which version to return. Currently supported versions
-#'      are 0.0 (legacy version from original GAMBLR), 0.1, and _latest. The
-#'      latter will always point to the highest numeric version of the genes.
+#'      * "ensembl": list of Ensembl IDs
+#'      * "data.frame": one row per gene with a `<ENTITY>_Tier` column per
+#'        requested entity (the gene's tier there, or NA if absent). Filter
+#'        these columns to focus on tiers, e.g.
+#'        `dplyr::filter(df, DLBCL_Tier == 1, FL_Tier == 1) |> dplyr::pull(Gene)`.
+#' @param version Data version to return. Defaults to "_latest", the current
+#'      LLMPP-sourced version in the reference database. Legacy numeric versions
+#'      (0.0, 0.1) are no longer bundled.
 #'
-#' @return A character vector of gene symbol or Ensembl IDs or a data frame.
+#' @return A character vector of gene symbols or Ensembl IDs, or a data frame.
 #'
 #' @import dplyr tidyr
 #'
+#' @export
+#'
 #' @examples
-#' all_dlbcl_genes <- get_genes(entities = "DLBCL", curated_only = FALSE)
+#' # high-confidence (Tier 1) DLBCL genes
+#' dlbcl_tier1 <- get_genes(entities = "DLBCL", tier = 1)
+#'
+#' # genes that are Tier 1 in DLBCL, FL and BL simultaneously
+#' gene_df <- get_genes(entities = c("DLBCL", "FL", "BL"), gene_format = "data.frame")
+#' shared_tier1 <- dplyr::filter(gene_df, DLBCL_Tier == 1, FL_Tier == 1, BL_Tier == 1)
+#'
 #' all_curated_genes <- get_genes()
 
 get_genes <- function(
         entities = c("DLBCL", "MCL", "BL"),
         curated_only = TRUE,
+        tier = NULL,
         gene_format = "symbol",
         version = "_latest"
     ) {
 
-    # We need to handle the legacy version (0.0) separately
-    # because it was not pathology-specific
-    if (version == "0.0") {
+    # Gene lists are sourced from the normalized reference database (built from
+    # the LLMPP curated lists) rather than per-entity, per-version .rda objects.
+    # "version" and "tier" are columns, so lymphoma_genes_*_v0.1/v0.2/v_latest
+    # are no longer needed.
+    if (!version %in% c("_latest", "latest")) {
         message(
             paste(
-            "You have requested the legacy version of the lymphoma genes.",
-            "It is only provided here for backwards compatibility.",
-            "We recommend you use the most recent version by keeping the",
-            "default value of the argument version. Use at your own risk."
+                "Legacy per-version gene lists (e.g. 0.0, 0.1) are no longer",
+                "bundled. Data is now sourced from the LLMPP curated lists;",
+                "returning the current version."
             )
         )
-
-        legacy_lymphoma_genes <- eval(
-                parse(
-                    text = paste0(
-                        "GAMBLR.data::",
-                        "lymphoma_genes_lymphoma_genes_v0.0")
-                    )
-            )
-
-        legacy_lymphoma_genes <- legacy_lymphoma_genes %>%
-            dplyr::select(
-                Gene, ensembl_gene_id,
-                intersect(
-                    colnames(.),
-                    entities
-                )
-            )
-        if (curated_only) {
-            # drop any row where all pathologies have FALSE
-            legacy_lymphoma_genes <- legacy_lymphoma_genes %>%
-                dplyr::filter(
-                    ! if_all(3:ncol(.), ~ . == "FALSE")
-                )
-        }
-
-        if (gene_format == "symbol") {
-            return(legacy_lymphoma_genes$Gene)
-        } else if (gene_format == "ensembl") {
-            return(legacy_lymphoma_genes$ensembl_gene_id)
-        } else if (gene_format == "data.frame") {
-            return(legacy_lymphoma_genes)
-        } else {
-            stop(
-                "You requested output format that is not supported."
-            )
-        }
     }
 
-    #construct file name using entity
-    entities <- tolower(entities)
-
-    r_objects <- entities %>%
-        paste0(
-            "lymphoma_genes_",
-            .,
-            "_v",
-            version
-        )
-
-    # check for unsupported gene sets
-    all_files <- system.file(
-        "extdata",
-        package = "GAMBLR.data"
-    ) %>%
-    list.files(
-        recursive = TRUE,
-        full.names = TRUE
-    )
-
-    all_files <- gsub(
-        ".*extdata/",
-        "",
-        all_files
-    )
-
-    all_files <- all_files[grepl("lymphoma_genes", all_files)]
-
-    all_files <- all_files[grepl(version, all_files)]
-
-    available_entities <- gsub("(.*/\\s*(.*$))", "\\2", all_files)
+    # `tier`, when supplied, selects exactly those confidence tiers (e.g.
+    # tier = 1 for high-confidence genes only) and takes precedence over
+    # `curated_only`. Otherwise curated_only == TRUE keeps the curated set
+    # (Tier 1 + Tier 2) and drops retired Tier 3 genes; FALSE returns all tiers.
+    keep_tiers <- if (!is.null(tier)) {
+        as.integer(tier)
+    } else if (curated_only) {
+        c(1L, 2L)
+    } else {
+        c(1L, 2L, 3L)
+    }
 
-    available_entities <- gsub(".tsv", "", available_entities)
+    con <- gambl_reference_db()
+    entities_u <- toupper(entities)
 
-    missing_sets <- setdiff(
-        entities,
-        available_entities
-    )
+    available <- dplyr::tbl(con, "gene_entity") %>%
+        dplyr::distinct(entity) %>%
+        dplyr::pull(entity)
 
+    missing_sets <- setdiff(entities_u, available)
     if (length(missing_sets) > 0) {
         warning(
             paste(
                 "The gene set for the entity",
-                missing_sets,
+                paste(missing_sets, collapse = ", "),
                 "is not available and will not be returned."
             )
         )
-        r_objects <- r_objects[
-                grepl(
-                    paste(
-                        available_entities,
-                        collapse="|"
-                    ),
-                    r_objects
-                )
-            ]
-        entities <- entities[entities %in% available_entities]
+        entities_u <- intersect(entities_u, available)
     }
 
-    # Combine all lists into one df
-    # Do it in a way that when GAMBLR.data is ot imported, the data objects
-    # are still available
-    all_entities_data <- list()
-
-    for (i in seq_along(r_objects)) {
-        all_entities_data[[i]] <- eval(
-            parse(
-                text = paste0(
-                    "GAMBLR.data::",
-                    r_objects[i]
-                )
-            )
-        )
-    }
-
-    all_entities_data <- all_entities_data %>%
-        # only select necessary columns
-        lapply(
-            .,
-            `[`,
-            ,
-            c("ensembl_gene_id", "Gene", "curated")
-        )
-
-    names(all_entities_data) <- toupper(entities)
-
-    all_entities_data <- all_entities_data %>%
-        bind_rows(.id = "entity")
-
-    if (curated_only) {
-        # drop any row where curated is FALSE
-        all_entities_data <- all_entities_data %>%
-            dplyr::filter(
-                curated == "TRUE"
-            )
-    }
+    dat <- dplyr::tbl(con, "gene_entity") %>%
+        dplyr::filter(entity %in% entities_u, tier %in% keep_tiers) %>%
+        dplyr::select(entity, ensembl_gene_id, Gene = gene, tier) %>%
+        dplyr::collect()
 
     if (gene_format == "symbol") {
-        return(all_entities_data$Gene %>% unique %>% sort)
+        return(dat$Gene %>% unique %>% sort)
     } else if (gene_format == "ensembl") {
-        return(all_entities_data$ensembl_gene_id %>% unique %>% sort)
+        return(dat$ensembl_gene_id %>% unique %>% sort)
     } else if (gene_format == "data.frame") {
+        # one row per gene; one <ENTITY>_Tier column per requested entity
+        # holding the gene's tier there (NA if absent), so callers can do
+        # filter(df, DLBCL_Tier == 1, FL_Tier == 1, ...) %>% pull(Gene)
         return(
-            all_entities_data %>%
-            select(-curated) %>%
-            mutate(is_gene = "TRUE") %>%
-            tidyr::pivot_wider(
-                names_from = "entity",
-                values_from = "is_gene"
-            ) %>%
-            replace(is.na(.), "FALSE")
+            dat %>%
+                dplyr::distinct(Gene, ensembl_gene_id, entity, tier) %>%
+                tidyr::pivot_wider(
+                    id_cols = c(Gene, ensembl_gene_id),
+                    names_from = "entity",
+                    values_from = "tier",
+                    names_glue = "{entity}_Tier"
+                ) %>%
+                dplyr::select(Gene, ensembl_gene_id,
+                              dplyr::any_of(paste0(entities_u, "_Tier"))) %>%
+                dplyr::arrange(Gene)
         )
     } else {
         stop(