diff --git a/.github/ISSUE_TEMPLATE/1-bug-report.yml b/.github/ISSUE_TEMPLATE/1-bug-report.yml new file mode 100644 index 00000000..7e59c01d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/1-bug-report.yml @@ -0,0 +1,26 @@ +name: "πŸͺ² Bug report" +description: "Something works incorrectly or throws an error? Let us know." +labels: +- bug +body: +- type: textarea + id: description + attributes: + label: What happened? + description: Describe what you tried to do, and what happened instead. + validations: + required: true +- type: textarea + id: code + attributes: + label: Minimal code sample + description: Paste your code. Attach minimal data as a file to this ticket if necessary. Provide plots. + validations: + required: true +- type: textarea + id: info + attributes: + label: Additional information + description: "Any additional information you want to share with us: your R version and OS, how you want the result look like, etc." + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/2-enhancement.yml b/.github/ISSUE_TEMPLATE/2-enhancement.yml new file mode 100644 index 00000000..7b7e3803 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/2-enhancement.yml @@ -0,0 +1,11 @@ +name: "πŸ’‘ Enhancement request" +description: "Propose a new feature or an improvement." +labels: +- enhancement +body: +- type: textarea + id: description + attributes: + label: Please describe your idea or what you want to achieve + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/3-documentation.yml b/.github/ISSUE_TEMPLATE/3-documentation.yml new file mode 100644 index 00000000..45f2450c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/3-documentation.yml @@ -0,0 +1,12 @@ +name: "πŸ“š Tutorial or documentation request" +description: "Propose a tutorial for a specific use case or new documentation." +labels: +- documentation +body: +- type: textarea + id: description + attributes: + label: What type of documentation would you like to see on the website? + description: Interested in a tutorial? More details on how a specific method works? More examples? Something else entirely? + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/4-question.yml b/.github/ISSUE_TEMPLATE/4-question.yml new file mode 100644 index 00000000..34a41f33 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/4-question.yml @@ -0,0 +1,12 @@ +name: "❓ Question" +description: Ask us anything about immundata - how to use it, how to do something, how it works +labels: +- question +body: +- type: textarea + id: description + attributes: + label: Your question + description: Describe what you want to know. E.g., how to analyse a specific data, how to do X, when a method will be available, etc. + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md deleted file mode 100644 index d843d80a..00000000 --- a/.github/ISSUE_TEMPLATE/bug-report.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -name: "\U0001F41B Bug Report" -about: Submit a bug report to help us improve Immunarch - ---- - -## πŸ› Bug - - -## To Reproduce -Steps to reproduce the behavior: - -1. -2. -3. - - - -## Expected behavior - - -## Additional context - - diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..3ba13e0c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: false diff --git a/.github/ISSUE_TEMPLATE/documentation.md b/.github/ISSUE_TEMPLATE/documentation.md deleted file mode 100644 index 20a4534b..00000000 --- a/.github/ISSUE_TEMPLATE/documentation.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -name: "\U0001F4DA Documentation" -about: Report an issue related to our Documentation - ---- - -## πŸ“š Documentation - - diff --git a/.github/ISSUE_TEMPLATE/email-template.md b/.github/ISSUE_TEMPLATE/email-template.md deleted file mode 100644 index 47cb866b..00000000 --- a/.github/ISSUE_TEMPLATE/email-template.md +++ /dev/null @@ -1,46 +0,0 @@ - - -### Description - -1. - -### Steps to reproduce - -1. -2. -3. - -### Feature request - - -### Expected result - -1. [Screenshots, logs or description] - -### Actual result - -1. [Screenshots, logs or description] - -## Additional context - - diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md deleted file mode 100644 index 4d9fbb04..00000000 --- a/.github/ISSUE_TEMPLATE/feature-request.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -name: "\U0001F680Feature Request" -about: Submit a proposal/request for a new Immunarch feature - ---- - -## πŸš€ Feature - - -## Motivation - - -## Pitch - - -## Alternatives - - -## Additional context - - diff --git a/.github/ISSUE_TEMPLATE/questions-help-support.md b/.github/ISSUE_TEMPLATE/questions-help-support.md deleted file mode 100644 index 37b6f115..00000000 --- a/.github/ISSUE_TEMPLATE/questions-help-support.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -name: "❓Questions/Help/Support" -about: Do you need support? We have resources. - ---- - -## ❓ Questions and Help -We have a set of [listed tutorials available on the website](https://immunarch.com/articles/). - diff --git a/DESCRIPTION b/DESCRIPTION index b727373f..c774bc78 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: immunarch Type: Package Title: Multi-Modal Immune Repertoire Analytics for Immunotherapy and Vaccine Design in R -Version: 0.10.3 +Version: 0.10.3.9002 Authors@R: c( person("Vadim I.", "Nazarov", , "support@immunomind.com", role = c("aut", "cre"), comment = c(ORCID = "0000-0003-3659-2709")), diff --git a/NAMESPACE b/NAMESPACE index faa2be93..4daae1df 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -49,17 +49,15 @@ S3method(vis,step_failure_ignored) export(airr_clonality_line) export(airr_clonality_prop) export(airr_clonality_rank) +export(airr_desc_chains) +export(airr_desc_genes) +export(airr_desc_lengths) export(airr_diversity_chao1) export(airr_diversity_dxx) export(airr_diversity_hill) export(airr_diversity_index) export(airr_diversity_pielou) export(airr_diversity_shannon) -export(airr_public_intersection) -export(airr_public_jaccard) -export(airr_stats_chains) -export(airr_stats_genes) -export(airr_stats_lengths) export(annotate_clonality_prop) export(annotate_clonality_rank) export(apply_asymm) @@ -117,6 +115,8 @@ export(repOverlapAnalysis) export(repSample) export(repSave) export(repSomaticHypermutation) +export(repsim_intersection) +export(repsim_jaccard) export(select_barcodes) export(select_clusters) export(seqCluster) diff --git a/R/v0_align_lineage.R b/R/v0_align_lineage.R index 27bd1293..4c9947d3 100644 --- a/R/v0_align_lineage.R +++ b/R/v0_align_lineage.R @@ -75,6 +75,8 @@ repAlignLineage <- function(.data, .prepare_threads = 2, .align_threads = 4, .nofail = FALSE) { + lifecycle::deprecate_warn("0.10.3", "repAlignLineage()") + if (!require_system_package(c("clustalw", "clustalw2"), error_message = paste0( "repAlignLineage requires Clustal W app to be installed!\n", "Please download it from here: http://www.clustal.org/download/current/\n", diff --git a/R/v0_annotation.R b/R/v0_annotation.R index 1c90d389..eca78c2f 100644 --- a/R/v0_annotation.R +++ b/R/v0_annotation.R @@ -54,6 +54,8 @@ if (getRversion() >= "2.15.1") { #' db #' @export dbLoad <- function(.path, .db, .species = NA, .chain = NA, .pathology = NA) { + lifecycle::deprecate_warn("0.10.3", "dbLoad()") + .db <- tolower(.db) if (!(.db %in% c("vdjdb", "vdjdb-search", "mcpas", "mcpas-tcr", "pird"))) { stop('Unknown .db argument. Please provide one of the following: "vdjdb", "vdjdb-search", "mcpas"') @@ -158,6 +160,8 @@ dbLoad <- function(.path, .db, .species = NA, .chain = NA, .pathology = NA) { #' res #' @export dbAnnotate dbAnnotate <- function(.data, .db, .data.col, .db.col) { + lifecycle::deprecate_warn("0.10.3", "dbAnnotate()") + # Check if the number of columns is equal if (length(.data.col) != length(.db.col)) { stop("Number of columns in .data.col and .db.col doesn't match! Please provide equal number of columns.") diff --git a/R/v0_clonality.R b/R/v0_clonality.R index edd91bbb..24beb783 100644 --- a/R/v0_clonality.R +++ b/R/v0_clonality.R @@ -89,6 +89,8 @@ repClonality <- function(.data, .method = c("clonal.prop", "homeo", "top", "rare ), .head = c(10, 100, 1000, 3000, 10000, 30000, 100000), .bound = c(1, 3, 10, 30, 100)) { + lifecycle::deprecate_warn("0.10.3", "repClonality()", details = "See `?airr_clonality()` on details for replacement functions.") + .method <- .method[1] if (.method == "tail") { .method <- "rare" diff --git a/R/v0_diversity.R b/R/v0_diversity.R index 00b57c18..38abe988 100644 --- a/R/v0_diversity.R +++ b/R/v0_diversity.R @@ -158,6 +158,8 @@ if (getRversion() >= "2.15.1") { repDiversity <- function(.data, .method = "chao1", .col = "aa", .max.q = 6, .min.q = 1, .q = 5, .step = NA, .quantile = c(.025, .975), .extrapolation = NA, .perc = 50, .norm = TRUE, .verbose = TRUE, .do.norm = NA, .laplace = 0) { + lifecycle::deprecate_warn("0.10.3", "repDiversity()", details = "See `?airr_diversity()` for details on new functions.") + .method <- .method[1] if (.method == "rarefaction") { diff --git a/R/v0_explore.R b/R/v0_explore.R index aa63abf8..01583a1c 100644 --- a/R/v0_explore.R +++ b/R/v0_explore.R @@ -65,6 +65,8 @@ #' repExplore(immdata$data, .method = "len") %>% vis() #' @export repExplore repExplore <- function(.data, .method = c("volume", "count", "len", "clones"), .col = c("nt", "aa"), .coding = TRUE) { + lifecycle::deprecate_warn("0.10.3", "repExplore()", details = "Run `?airr_desc()` for information on new functions.") + if (!has_class(.data, "list")) { .data <- list(Sample = .data) } diff --git a/R/v0_filters.R b/R/v0_filters.R index 10541e21..a5f247bb 100644 --- a/R/v0_filters.R +++ b/R/v0_filters.R @@ -49,6 +49,8 @@ repFilter <- function(.data, .method = "by.clonotype", .query = list(CDR3.aa = exclude("partial", "out_of_frame")), .match = "exact") { + lifecycle::deprecate_warn("0.10.3", "repFilter()", details = "See `?immundata::filter.ImmunData()` for details on replacement functions.") + .validate_immdata(.data) if (length(names(.query)) == 0) { diff --git a/R/v0_gene_usage.R b/R/v0_gene_usage.R index 68857b16..e94e88e5 100644 --- a/R/v0_gene_usage.R +++ b/R/v0_gene_usage.R @@ -64,6 +64,8 @@ geneUsage <- function(.data, # df, list, MonetDB .ambig = c("inc", "exc", "maj"), .type = c("segment", "allele", "family"), .norm = FALSE) { + lifecycle::deprecate_warn("0.10.3", "geneUsage()", details = "See `?airr_desc()` for details on replacement functions.") + .type <- .type[1] .ambig <- .ambig[1] .quant <- .quant[1] diff --git a/R/v0_io.R b/R/v0_io.R index 4e6db265..5a639e8e 100644 --- a/R/v0_io.R +++ b/R/v0_io.R @@ -8,7 +8,6 @@ if (getRversion() >= "2.15.1") { } - ##### Main IO functions ##### @@ -141,6 +140,8 @@ if (getRversion() >= "2.15.1") { #' # [1] "data" "meta" #' @export repLoad repLoad <- function(.path, .mode = "paired", .coding = TRUE, ...) { + lifecycle::deprecate_warn("0.10.3", "repLoad()", details = "See `?immundata::read_repertoires()` for details on replacement functions.") + exclude_extensions <- c( "so", "exe", "bam", "fasta", "fai", "fastq", "bed", "rds", "report", "vdjca" ) @@ -471,6 +472,8 @@ repLoad <- function(.path, .mode = "paired", .coding = TRUE, ...) { #' @export repSave repSave <- function(.data, .path, .format = c("immunarch", "vdjtools"), .compress = TRUE) { + lifecycle::deprecate_warn("0.10.3", "repSave()", details = "Run `?immundata::write_immundata()` for information on new functions.") + .format <- .format[1] if (!.format %in% c("immunarch", "vdjtools")) { stop("Unknown format. Please provide either 'immunarch' or 'vdjtools'") diff --git a/R/v0_overlap.R b/R/v0_overlap.R index 9f19a3ec..9d12c588 100644 --- a/R/v0_overlap.R +++ b/R/v0_overlap.R @@ -113,6 +113,8 @@ repOverlap <- function(.data, .bootstrap = NA, .verbose.inc = NA, .force.matrix = FALSE) { + lifecycle::deprecate_warn("0.10.3", "repOverlap()", details = "See `?repsim()` for details on replacement functions.") + .validate_repertoires_data(.data) .method <- .method[1] diff --git a/R/v1_stats_airr.R b/R/v1_desc_airr.R similarity index 80% rename from R/v1_stats_airr.R rename to R/v1_desc_airr.R index 99cdaa19..cfb53e00 100644 --- a/R/v1_stats_airr.R +++ b/R/v1_desc_airr.R @@ -1,4 +1,4 @@ -#' @title Compute key immune repertoire statistics +#' @title Descriptive immune repertoire statistics #' #' @description #' `r lifecycle::badge("experimental")` @@ -10,9 +10,9 @@ #' Supported methods are the following. #' #' @param idata An `ImmunData` object. -#' @inheritParams airr_stats_chains -#' @inheritParams airr_stats_lengths -#' @inheritParams airr_stats_genes +#' @inheritParams airr_desc_chains +#' @inheritParams airr_desc_lengths +#' @inheritParams airr_desc_genes #' @inheritParams im_common_args #' #' @seealso [immundata::ImmunData] @@ -27,13 +27,13 @@ #' immdata <- get_test_idata() |> agg_repertoires("Therapy") #' } #' -#' @name airr_stats +#' @name airr_desc #' @concept Key AIRR statistics NULL #' @keywords internal -airr_stats_chains_impl <- function(idata, locus_col = NA) { +airr_desc_chains_impl <- function(idata, locus_col = NA) { checkmate::assert_character(locus_col, null.ok = TRUE) if (is.null(idata$repertoires)) { @@ -76,7 +76,7 @@ airr_stats_chains_impl <- function(idata, locus_col = NA) { } -#' @description `airr_stats_chains` --- count V(D)J *chains* per repertoire +#' @description `airr_desc_chains` --- count V(D)J *chains* per repertoire #' (optionally split by locus). Quickly gauges capture depth per repertoire #' and, when split by locus, reveals TRA/TRB/IGH balance. Use it for QC, #' library-size checks, and to spot locus-specific dropouts or @@ -87,32 +87,32 @@ airr_stats_chains_impl <- function(idata, locus_col = NA) { #' #' @return #' -#' ## `airr_stats_chains` Returns a tibble with columns: +#' ## `airr_desc_chains` Returns a tibble with columns: #' * `repertoire_id` -- repertoire identifier #' * `locus` -- TRA, TRB, IGH, ... (present only if `locus_col` is supplied) #' * `n_chains` -- number of chains #' #' @examples #' # -#' # airr_stats_chains +#' # airr_desc_chains #' # #' #' \dontrun{ -#' airr_stats_chains(immdata) +#' airr_desc_chains(immdata) #' } #' -#' @rdname airr_stats +#' @rdname airr_desc #' @concept Key AIRR statistics #' @export -airr_stats_chains <- register_immunarch_method( - core = airr_stats_chains_impl, - family = "airr_stats", +airr_desc_chains <- register_immunarch_method( + core = airr_desc_chains_impl, + family = "airr_desc", name = "chains" ) #' @keywords internal -airr_stats_lengths_impl <- function(idata, seq_col = "cdr3_aa") { +airr_desc_lengths_impl <- function(idata, seq_col = "cdr3_aa") { idata$annotations |> dplyr::select(dplyr::all_of(c(immundata::imd_schema("repertoire"), seq_col))) |> dplyr::mutate(seq_len = dd$length(!!rlang::sym(seq_col))) |> @@ -129,7 +129,7 @@ airr_stats_lengths_impl <- function(idata, seq_col = "cdr3_aa") { } -#' @description `airr_stats_lengths` --- count the number of sequence lengths +#' @description `airr_desc_lengths` --- count the number of sequence lengths #' per repertoire. Summarizes the CDR3 length distribution, a sensitive QC #' fingerprint of repertoire prep and selection. Helpful for detecting #' primer/UMI biases, comparing cohorts, and deriving length-based features for @@ -140,33 +140,33 @@ airr_stats_lengths_impl <- function(idata, seq_col = "cdr3_aa") { #' #' @return #' -#' ## `airr_stats_lengths` Returns a tibble with columns: +#' ## `airr_desc_lengths` Returns a tibble with columns: #' * `repertoire_id` -- repertoire identifier #' * `seq_len` -- lengths of sequences #' * `n` -- number of receptors #' #' @examples #' # -#' # airr_stats_lengths +#' # airr_desc_lengths #' # #' #' \dontrun{ -#' airr_stats_lengths(immdata) +#' airr_desc_lengths(immdata) #' } #' -#' @rdname airr_stats +#' @rdname airr_desc #' @concept Key AIRR statistics #' @export -airr_stats_lengths <- register_immunarch_method( - core = airr_stats_lengths_impl, - family = "airr_stats", +airr_desc_lengths <- register_immunarch_method( + core = airr_desc_lengths_impl, + family = "airr_desc", name = "lengths", required = "seq_col" ) #' @keywords internal -airr_stats_genes_impl <- function(idata, gene_col = "v_call", level = c("receptor", "barcode"), by = c(NA, "locus")) { +airr_desc_genes_impl <- function(idata, gene_col = "v_call", level = c("receptor", "barcode"), by = c(NA, "locus")) { checkmate::assert_logical(gene_col %in% colnames(idata$annotations)) level <- match.arg(level) by <- match.arg(by) @@ -190,7 +190,7 @@ airr_stats_genes_impl <- function(idata, gene_col = "v_call", level = c("recepto collect() } -#' @description `airr_stats_genes` - count V(D)J gene segments per repertoire, +#' @description `airr_desc_genes` - count V(D)J gene segments per repertoire, #' optionally split by locus and using either receptor counts or barcode/UMI #' counts as the measure. Profiles V/D/J gene usage to characterize repertoire #' composition and germline biases, with optional locus split. Useful for @@ -212,7 +212,7 @@ airr_stats_genes_impl <- function(idata, gene_col = "v_call", level = c("recepto #' #' @return #' -#' ## `airr_stats_genes` A tibble with columns: +#' ## `airr_desc_genes` A tibble with columns: #' * `repertoire_id` - repertoire identifier #' * *(optional)* `locus` - TRA, TRB, IGH, ... (present only when `by = "locus"` #' and the locus column exists) @@ -223,26 +223,26 @@ airr_stats_genes_impl <- function(idata, gene_col = "v_call", level = c("recepto #' #' @examples #' # -#' # airr_stats_genes +#' # airr_desc_genes #' # #' #' \dontrun{ #' # V gene usage by receptor count -#' airr_stats_genes(immdata, gene_col = "v_call", level = "receptor") +#' airr_desc_genes(immdata, gene_col = "v_call", level = "receptor") #' #' # V gene usage by summed cell/UMI counts (if a count column is present) -#' airr_stats_genes(immdata, gene_col = "v_call", level = "barcode") +#' airr_desc_genes(immdata, gene_col = "v_call", level = "barcode") #' #' # Split by locus (TRA/TRB/... if locus column exists) -#' airr_stats_genes(immdata, gene_col = "v_call", level = "receptor", by = "locus") +#' airr_desc_genes(immdata, gene_col = "v_call", level = "receptor", by = "locus") #' } #' -#' @rdname airr_stats +#' @rdname airr_desc #' @concept Key AIRR statistics #' @export -airr_stats_genes <- register_immunarch_method( - core = airr_stats_genes_impl, - family = "airr_stats", +airr_desc_genes <- register_immunarch_method( + core = airr_desc_genes_impl, + family = "airr_desc", name = "genes", required = "gene_col" ) diff --git a/R/v1_stats_vis.R b/R/v1_desc_vis.R similarity index 50% rename from R/v1_stats_vis.R rename to R/v1_desc_vis.R index ed87e1f4..0dbdea8d 100644 --- a/R/v1_stats_vis.R +++ b/R/v1_desc_vis.R @@ -1,28 +1,28 @@ #' @keywords internal -vis_airr_stats_chains_impl <- make_dynam_col_plot( +vis_airr_desc_chains_impl <- make_dynam_col_plot( y_default = "n_receptors", title_default = "No. receptors per sample", position = "dodge" ) -register_immunarch_visualisation(vis_airr_stats_chains_impl, "airr_stats", "chains") +register_immunarch_visualisation(vis_airr_desc_chains_impl, "airr_desc", "chains") #' @keywords internal -vis_airr_stats_lengths_impl <- make_fixed_col_plot( +vis_airr_desc_lengths_impl <- make_fixed_col_plot( x_col = "seq_len", y_col = "prop", title = "CDR3 length distribution", xlab = "CDR3 length", ylab = "Proportion" ) -register_immunarch_visualisation(vis_airr_stats_lengths_impl, "airr_stats", "lengths") +register_immunarch_visualisation(vis_airr_desc_lengths_impl, "airr_desc", "lengths") #' @keywords internal -vis_airr_stats_genes_impl <- make_dotplot( +vis_airr_desc_genes_impl <- make_dotplot( title_default = "Gene usage", size_default = "Proportion (all data)", fill_default = "No. Receptors" ) -register_immunarch_visualisation(vis_airr_stats_genes_impl, "airr_stats", "genes") +register_immunarch_visualisation(vis_airr_desc_genes_impl, "airr_desc", "genes") diff --git a/R/v1_public_vis.R b/R/v1_public_vis.R deleted file mode 100644 index 567873ac..00000000 --- a/R/v1_public_vis.R +++ /dev/null @@ -1,18 +0,0 @@ -#' @keywords internal -vis_airr_public_intersection_impl <- make_dotplot( - title_default = "No. of public receptors", - size_default = "No. receptors", - fill_default = "No. receptors" -) - -register_immunarch_visualisation(vis_airr_public_intersection_impl, "airr_public", "intersection") - - -#' @keywords internal -vis_airr_public_jaccard_impl <- make_dotplot( - title_default = "Jaccard similarity index", - size_default = "Value", - fill_default = "Value" -) - -register_immunarch_visualisation(vis_airr_public_jaccard_impl, "airr_public", "jaccard") diff --git a/R/v1_public_airr.R b/R/v1_repsim.R similarity index 84% rename from R/v1_public_airr.R rename to R/v1_repsim.R index 727b080e..6c4a57d9 100644 --- a/R/v1_public_airr.R +++ b/R/v1_repsim.R @@ -1,4 +1,4 @@ -#' @title Public indices - pairwise repertoire overlap +#' @title Immune repertoire similarity #' #' @description #' `r lifecycle::badge("experimental")` @@ -10,8 +10,8 @@ #' Supported methods are the following. #' #' @param idata An `ImmunData` object. -#' @inheritParams airr_public_intersection -#' @inheritParams airr_public_jaccard +#' @inheritParams repsim_intersection +#' @inheritParams repsim_jaccard #' @inheritParams im_common_args #' #' @seealso [immundata::ImmunData] @@ -25,13 +25,13 @@ #' immdata <- get_test_idata() |> agg_repertoires("Therapy") #' } #' -#' @name airr_public -#' @concept Public indices +#' @name repsim +#' @concept Repertoire similarity NULL #' @keywords internal -airr_public_intersection_impl <- function(idata) { +repsim_intersection_impl <- function(idata) { receptor_id_col <- immundata::imd_schema("receptor") repertoire_id_col <- immundata::imd_schema("repertoire") repertoire_ids <- idata$repertoires |> @@ -73,33 +73,33 @@ airr_public_intersection_impl <- function(idata) { result_matrix } -#' @description `airr_public_intersection` - number of **shared receptors** between +#' @description `repsim_intersection` - number of **shared receptors** between #' each pair of repertoires (intersection size). Handy for quick overlap heatmaps, #' QC of replicate similarity, or spotting donor-shared "public" clonotypes. #' #' @return #' -#' ## `airr_public_intersection` +#' ## `repsim_intersection` #' A **symmetric numeric matrix** where rows/columns are `repertoire_id` and each #' cell is the count of shared unique receptors. The diagonal contains per-repertoire #' richness (total unique receptors). Row/column names are repertoire IDs. #' #' @examples #' # -#' # airr_public_intersection +#' # repsim_intersection #' # #' \dontrun{ -#' m_pub <- airr_public_intersection(immdata) +#' m_pub <- repsim_intersection(immdata) #' } #' -#' @rdname airr_public -#' @concept Public indices +#' @rdname repsim +#' @concept Repertoire similarity #' @export -airr_public_intersection <- register_immunarch_method(airr_public_intersection_impl, "airr_public", "intersection", ) +repsim_intersection <- register_immunarch_method(repsim_intersection_impl, "repsim", "intersection", ) #' @keywords internal -airr_public_jaccard_impl <- function(idata) { +repsim_jaccard_impl <- function(idata) { receptor_id_col <- immundata::imd_schema("receptor") repertoire_id_col <- immundata::imd_schema("repertoire") repertoire_ids <- idata$repertoires |> @@ -152,7 +152,7 @@ airr_public_jaccard_impl <- function(idata) { } -#' @description `airr_public_jaccard` - **Jaccard similarity** of receptor +#' @description `repsim_jaccard` - **Jaccard similarity** of receptor #' sets between repertoires (\eqn{A \cap B}{A cap B} / \eqn{A \cup B}{A cup B}). Best when comparing cohorts with #' different sizes to get a scale-invariant overlap score. #' @@ -160,20 +160,20 @@ airr_public_jaccard_impl <- function(idata) { #' #' @return #' -#' ## `airr_public_jaccard` +#' ## `repsim_jaccard` #' A **symmetric numeric matrix** where rows/columns are `repertoire_id` and each #' cell is the Jaccard similarity in `[0, 1]`. The diagonal is `1`. Row/column #' names are repertoire IDs. #' #' @examples #' # -#' # airr_public_jaccard +#' # repsim_jaccard #' # #' \dontrun{ -#' m_jac <- airr_public_jaccard(immdata) +#' m_jac <- repsim_jaccard(immdata) #' } #' -#' @rdname airr_public -#' @concept Public indices +#' @rdname repsim +#' @concept Repertoire similarity #' @export -airr_public_jaccard <- register_immunarch_method(airr_public_jaccard_impl, "airr_public", "jaccard") +repsim_jaccard <- register_immunarch_method(repsim_jaccard_impl, "repsim", "jaccard") diff --git a/R/v1_repsim_vis.R b/R/v1_repsim_vis.R new file mode 100644 index 00000000..5bb3d1fb --- /dev/null +++ b/R/v1_repsim_vis.R @@ -0,0 +1,18 @@ +#' @keywords internal +vis_repsim_intersection_impl <- make_dotplot( + title_default = "No. of public receptors", + size_default = "No. receptors", + fill_default = "No. receptors" +) + +register_immunarch_visualisation(vis_repsim_intersection_impl, "repsim", "intersection") + + +#' @keywords internal +vis_repsim_jaccard_impl <- make_dotplot( + title_default = "Jaccard similarity index", + size_default = "Value", + fill_default = "Value" +) + +register_immunarch_visualisation(vis_repsim_jaccard_impl, "repsim", "jaccard") diff --git a/man/airr_stats.Rd b/man/airr_desc.Rd similarity index 83% rename from man/airr_stats.Rd rename to man/airr_desc.Rd index 3c687f17..c1360b42 100644 --- a/man/airr_stats.Rd +++ b/man/airr_desc.Rd @@ -1,27 +1,27 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/v1_stats_airr.R -\name{airr_stats} -\alias{airr_stats} -\alias{airr_stats_chains} -\alias{airr_stats_lengths} -\alias{airr_stats_genes} +% Please edit documentation in R/v1_desc_airr.R +\name{airr_desc} +\alias{airr_desc} +\alias{airr_desc_chains} +\alias{airr_desc_lengths} +\alias{airr_desc_genes} \title{Compute key immune repertoire statistics} \usage{ -airr_stats_chains( +airr_desc_chains( idata, locus_col = NA, autojoin = getOption("immundata.autojoin", TRUE), format = c("long", "wide") ) -airr_stats_lengths( +airr_desc_lengths( idata, seq_col = "cdr3_aa", autojoin = getOption("immundata.autojoin", TRUE), format = c("long", "wide") ) -airr_stats_genes( +airr_desc_genes( idata, gene_col = "v_call", level = c("receptor", "barcode"), @@ -62,7 +62,7 @@ is further split by the locus column if present (as given by split is ignored.} } \value{ -\subsection{\code{airr_stats_chains} Returns a tibble with columns:}{ +\subsection{\code{airr_desc_chains} Returns a tibble with columns:}{ \itemize{ \item \code{repertoire_id} -- repertoire identifier \item \code{locus} -- TRA, TRB, IGH, ... (present only if \code{locus_col} is supplied) @@ -70,7 +70,7 @@ split is ignored.} } } -\subsection{\code{airr_stats_lengths} Returns a tibble with columns:}{ +\subsection{\code{airr_desc_lengths} Returns a tibble with columns:}{ \itemize{ \item \code{repertoire_id} -- repertoire identifier \item \code{seq_len} -- lengths of sequences @@ -78,7 +78,7 @@ split is ignored.} } } -\subsection{\code{airr_stats_genes} A tibble with columns:}{ +\subsection{\code{airr_desc_genes} A tibble with columns:}{ \itemize{ \item \code{repertoire_id} - repertoire identifier \item \emph{(optional)} \code{locus} - TRA, TRB, IGH, ... (present only when \code{by = "locus"} @@ -101,19 +101,19 @@ A family of functions that extract \strong{core descriptive statistics} from an Supported methods are the following. } -\code{airr_stats_chains} --- count V(D)J \emph{chains} per repertoire +\code{airr_desc_chains} --- count V(D)J \emph{chains} per repertoire (optionally split by locus). Quickly gauges capture depth per repertoire and, when split by locus, reveals TRA/TRB/IGH balance. Use it for QC, library-size checks, and to spot locus-specific dropouts or over-representation. -\code{airr_stats_lengths} --- count the number of sequence lengths +\code{airr_desc_lengths} --- count the number of sequence lengths per repertoire. Summarizes the CDR3 length distribution, a sensitive QC fingerprint of repertoire prep and selection. Helpful for detecting primer/UMI biases, comparing cohorts, and deriving length-based features for models. -\code{airr_stats_genes} - count V(D)J gene segments per repertoire, +\code{airr_desc_genes} - count V(D)J gene segments per repertoire, optionally split by locus and using either receptor counts or barcode/UMI counts as the measure. Profiles V/D/J gene usage to characterize repertoire composition and germline biases, with optional locus split. Useful for @@ -131,34 +131,34 @@ immdata <- get_test_idata() |> agg_repertoires("Therapy") } # -# airr_stats_chains +# airr_desc_chains # \dontrun{ -airr_stats_chains(immdata) +airr_desc_chains(immdata) } # -# airr_stats_lengths +# airr_desc_lengths # \dontrun{ -airr_stats_lengths(immdata) +airr_desc_lengths(immdata) } # -# airr_stats_genes +# airr_desc_genes # \dontrun{ # V gene usage by receptor count -airr_stats_genes(immdata, gene_col = "v_call", level = "receptor") +airr_desc_genes(immdata, gene_col = "v_call", level = "receptor") # V gene usage by summed cell/UMI counts (if a count column is present) -airr_stats_genes(immdata, gene_col = "v_call", level = "barcode") +airr_desc_genes(immdata, gene_col = "v_call", level = "barcode") # Split by locus (TRA/TRB/... if locus column exists) -airr_stats_genes(immdata, gene_col = "v_call", level = "receptor", by = "locus") +airr_desc_genes(immdata, gene_col = "v_call", level = "receptor", by = "locus") } } diff --git a/man/airr_public.Rd b/man/repsim.Rd similarity index 80% rename from man/airr_public.Rd rename to man/repsim.Rd index ee7d03d4..1de27b75 100644 --- a/man/airr_public.Rd +++ b/man/repsim.Rd @@ -1,18 +1,18 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/v1_public_airr.R -\name{airr_public} -\alias{airr_public} -\alias{airr_public_intersection} -\alias{airr_public_jaccard} +% Please edit documentation in R/v1_repsim.R +\name{repsim} +\alias{repsim} +\alias{repsim_intersection} +\alias{repsim_jaccard} \title{Public indices - pairwise repertoire overlap} \usage{ -airr_public_intersection( +repsim_intersection( idata, autojoin = getOption("immundata.autojoin", TRUE), format = c("long", "wide") ) -airr_public_jaccard( +repsim_jaccard( idata, autojoin = getOption("immundata.autojoin", TRUE), format = c("long", "wide") @@ -29,14 +29,14 @@ columns, and \code{value}; useful for visualizations) or \code{"wide"} (wide/unm with each row corresponding to a specific repertoire / pair of repertoires; useful for Machine Learning).} } \value{ -\subsection{\code{airr_public_intersection}}{ +\subsection{\code{repsim_intersection}}{ A \strong{symmetric numeric matrix} where rows/columns are \code{repertoire_id} and each cell is the count of shared unique receptors. The diagonal contains per-repertoire richness (total unique receptors). Row/column names are repertoire IDs. } -\subsection{\code{airr_public_jaccard}}{ +\subsection{\code{repsim_jaccard}}{ A \strong{symmetric numeric matrix} where rows/columns are \code{repertoire_id} and each cell is the Jaccard similarity in \verb{[0, 1]}. The diagonal is \code{1}. Row/column @@ -52,11 +52,11 @@ A family of functions to quantify \strong{public or shared receptors} between re Supported methods are the following. } -\code{airr_public_intersection} - number of \strong{shared receptors} between +\code{repsim_intersection} - number of \strong{shared receptors} between each pair of repertoires (intersection size). Handy for quick overlap heatmaps, QC of replicate similarity, or spotting donor-shared "public" clonotypes. -\code{airr_public_jaccard} - \strong{Jaccard similarity} of receptor +\code{repsim_jaccard} - \strong{Jaccard similarity} of receptor sets between repertoires (\eqn{A \cap B}{A cap B} / \eqn{A \cup B}{A cup B}). Best when comparing cohorts with different sizes to get a scale-invariant overlap score. } @@ -70,21 +70,21 @@ immdata <- get_test_idata() |> agg_repertoires("Therapy") } # -# airr_public_intersection +# repsim_intersection # \dontrun{ -m_pub <- airr_public_intersection(immdata) +m_pub <- repsim_intersection(immdata) } # -# airr_public_jaccard +# repsim_jaccard # \dontrun{ -m_jac <- airr_public_jaccard(immdata) +m_jac <- repsim_jaccard(immdata) } } \seealso{ \link[immundata:ImmunData]{immundata::ImmunData} } -\concept{Public indices} +\concept{Repertoire similarity} diff --git a/man/vis.Rd b/man/vis.Rd index 51b6dddd..8f1c92f0 100644 --- a/man/vis.Rd +++ b/man/vis.Rd @@ -37,7 +37,6 @@ airr_stats_genes(immdata, gene_col = "v_call") |> vis() airr_public_jaccard(immdata) |> vis() airr_diversity_pielou(immdata) |> vis() airr_diversity_chao1(immdata) |> vis() -airr_clonality_prop(immdata) } } \seealso{ diff --git a/tests/testthat/test-vis_airr_stats_length.R b/tests/testthat/test-vis_airr_desc_length.R similarity index 92% rename from tests/testthat/test-vis_airr_stats_length.R rename to tests/testthat/test-vis_airr_desc_length.R index 2d85f4c9..74e314a5 100644 --- a/tests/testthat/test-vis_airr_stats_length.R +++ b/tests/testthat/test-vis_airr_desc_length.R @@ -1,9 +1,9 @@ -test_that("vis() for airr_stats_lengths builds plots", { +test_that("vis() for airr_desc_lengths builds plots", { skip_on_cran() skip_if_not_installed("ggplot2") idata <- get_test_immundata() |> agg_repertoires("Therapy") - res_lengths <- idata |> airr_stats_lengths() + res_lengths <- idata |> airr_desc_lengths() p1 <- vis(res_lengths, fill = "Therapy") expect_s3_class(p1, "ggplot") expect_error(suppressWarnings(ggplot2::ggplot_build(p1)), NA)