chore: version bump, migration stuff

Author: vadimnazarov

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: immunarch
 Type: Package
 Title: Multi-Modal Immune Repertoire Analytics for Immunotherapy and Vaccine Design in R
-Version: 0.9.1.9001
+Version: 0.10.0
 Authors@R: c(
     person("Vadim I.", "Nazarov", , "support@immunomind.com", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0003-3659-2709")),
@@ -19,12 +19,12 @@ Description: A comprehensive analytics framework for building reproducible pipel
     Think Scanpy or Seurat, but for AIRR data, a.k.a. Adaptive Immune Receptor Repertoire, VDJ-seq, RepSeq, or 
     VDJ sequencing data. A successor to our previously published "tcR" R package (Nazarov 2015).
 License: Apache License (== 2.0)
-URL: https://immunarch.com/, https://github.com/immunomind/immunarch
+URL: https://immunomind.github.io/docs/, https://github.com/immunomind/immunarch
 BugReports: https://github.com/immunomind/immunarch/issues
 Depends:
     R (>= 4.1.0),
     ggplot2 (>= 3.1.0),
-    immundata (>= 0.0.3),
+    immundata (>= 0.0.5),
     patchwork
 Imports:
     dplyr,

NAMESPACE

@@ -49,6 +49,7 @@ S3method(vis,step_failure_ignored)
 export(airr_clonality_line)
 export(airr_clonality_prop)
 export(airr_clonality_rank)
+export(airr_diversity_chao1)
 export(airr_diversity_dxx)
 export(airr_diversity_hill)
 export(airr_diversity_index)
@@ -59,6 +60,8 @@ 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)
 export(apply_symm)
 export(bunch_translate)
@@ -203,6 +206,7 @@ importFrom(dplyr,slice_head)
 importFrom(dplyr,summarise)
 importFrom(dplyr,tally)
 importFrom(dplyr,top_n)
+importFrom(dplyr,transmute)
 importFrom(dplyr,ungroup)
 importFrom(dplyr,union)
 importFrom(dplyr,union_all)
@@ -291,12 +295,14 @@ importFrom(stringr,str_sub)
 importFrom(stringr,str_trim)
 importFrom(tibble,rownames_to_column)
 importFrom(tibble,tibble)
+importFrom(tidyr,as_tibble)
 importFrom(tidyr,drop_na)
 importFrom(tidyr,unite)
 importFrom(tidyr,unnest)
 importFrom(tidyselect,all_of)
 importFrom(tidyselect,any_of)
 importFrom(tidyselect,starts_with)
+importFrom(utils,adist)
 importFrom(utils,capture.output)
 importFrom(utils,globalVariables)
 importFrom(utils,packageVersion)

R/aaa-registry.R

@@ -3,28 +3,22 @@ IMMUNARCH_METHOD_REGISTRY <- new.env(parent = emptyenv())
 
 #' Common arguments for immundata helpers
 #' @keywords internal
-#' @param autojoin If TRUE, join repertoire metadata by the schema repertoire id.
-#'   For `format="analysis"`, metadata is joined to the long table; for
-#'   `format="ml"`, it’s joined after pivoting to wide. Defaults to
-#'   `getOption("immundata.autojoin", FALSE)`.
-#' @param format One of `"analysis"` (long tibble with `repertoire_id`, facet
-#'   columns, and `value`) or `"ml"` (wide/unmelted table of features).
-#' @param features Character vector of **feature keys** to keep when
-#'   `format="ml"`. If `NULL`, features are derived from the data. A feature key
-#'   looks like `family.method|facet1=...;facet2=...` (e.g.,
-#'   `airr_stats.genes|v_call=TRBV7-2`).
+#' @param autojoin Logical. If TRUE, join repertoire metadata by the schema repertoire id.
+#'  Change the default behaviour by calling `options(immunarch.autojoin = FALSE)`.
+#' @param format String. One of `"long"` ("long" tibble with `imd_repertoire_id`, facet
+#'   columns, and `value`; useful for visualizations) or `"wide"` (wide/unmelted table of features,
+#'   with each row corresponding to a specific repertoire / pair of repertoires; useful for Machine Learning).
 im_common_args <- function(
-    autojoin = getOption("immundata.autojoin", FALSE),
-    format   = c("analysis", "ml"),
-    features = NULL) {} # nocov
+    autojoin = getOption("immundata.autojoin", TRUE),
+    format   = c("long", "wide")) {} # nocov
 
 
-im_method <- function(core, family, name) {
+im_method <- function(core, family, name, required_cols = NULL, need_repertoires = TRUE) {
   checkmate::assert_function(core, args = c("idata"))
   checkmate::assert_string(family)
   checkmate::assert_string(name)
+  checkmate::assert_logical(need_repertoires)
 
-  # Merge core formals with wrapper defaults to enable autocompletion
   core_fmls <- formals(core)
   if (!"idata" %in% names(core_fmls)) {
     cli::cli_abort("Core method must declare an {.code idata} argument.")
@@ -33,6 +27,11 @@ im_method <- function(core, family, name) {
     cli::cli_abort("Core method must not declare {.code autojoin}, {.code format}, or {.code features}.")
   }
 
+  # required_cols = columns expected in idata$annotations
+  if (!is.null(required_cols)) {
+    checkmate::assert_character(required_cols, any.missing = FALSE)
+  }
+
   wrapper <- function() { }
   formals(wrapper) <- c(
     core_fmls,
@@ -43,25 +42,131 @@ im_method <- function(core, family, name) {
   body(wrapper) <- substitute(
     {
       format <- match.arg(format)
-
-      # Pre: validate idata + schema
       checkmate::assert_r6(idata, "ImmunData")
 
-      # Build argument list for core from our own formals (now visible to the user)
+      if (need_repertoires) {
+        if (is.null(idata$schema_repertoire)) {
+          cli::cli_abort("Repertoire aggregation is needed for this function. Run {.code ?agg_repertoires} for more info.")
+        }
+      }
+
+      # For each argument name in `required_cols`, fetch its runtime value
+      # and ensure the referenced columns exist in idata$annotations.
+      if (length(required_cols)) {
+        ann_cols <- colnames(idata$annotations)
+        for (.arg in required_cols) {
+          .val <- get(.arg, inherits = TRUE)
+
+          # Just in case
+          if (is.null(.val) || (length(.val) == 1 && is.na(.val))) next
+
+          # Allow symbols or character vectors
+          if (rlang::is_symbol(.val)) {
+            .val <- rlang::as_string(.val)
+          }
+
+          if (!is.character(.val)) {
+            cli::cli_abort("Argument {.code {.arg}} must be a character (column name) or character vector; got a {.code {class(.val)[1]}}.")
+          }
+
+          missing <- setdiff(.val, ann_cols)
+          if (length(missing)) {
+            suggest <- function(x, pool, n = 3) {
+              if (!length(pool)) {
+                return(character())
+              }
+              d <- utils::adist(x, pool)
+              pool[order(d)][seq_len(min(n, length(pool)))]
+            }
+            hints <- unique(unlist(lapply(missing, suggest, pool = ann_cols, n = 3)))
+            cli::cli_abort("Passed column name(s) [{.code {missing}}] is not in the input ImmunData. Did you mean [{.code {hints}}]?")
+          }
+        }
+      }
+
+      # Call core with its own formals
       .core_args <- mget(names(core_fmls), inherits = TRUE)
       out <- do.call(core, .core_args)
 
+      # Autojoin: join repertoire metadata if requested and applicable (!)
+      if (isTRUE(autojoin) && !is.null(idata$repertoires)) {
+        rep_col <- immundata::imd_schema("repertoire")
+        if (!is.null(rep_col) && rep_col %in% names(out)) {
+          out <- dplyr::left_join(out, idata$repertoires |> select(all_of(c(rep_col, idata$schema_repertoire))), by = rep_col)
+        }
+      }
+
       out
     },
-    list(core = core, core_fmls = core_fmls)
+    list(core = core, core_fmls = core_fmls, required_cols = required_cols)
   )
 
   wrapper
 }
 
 
-register_immunarch_method <- function(core, family, name, register_family = TRUE) {
-  fn <- im_method(core, family, name)
+#' Register an Immunarch method (developer)
+#'
+#' `r lifecycle::badge("experimental")`
+#'
+#' Wrap a core implementation into a user-facing function and (optionally)
+#' register it in the in-memory method registry. The wrapper **adds common
+#' arguments** and **runs safety checks** so your core stays minimal.
+#'
+#' ## What your core must look like
+#' * Signature: `function(idata, ...)`
+#' * **Must not** declare `autojoin`, `format`, or `features` — these are added by the wrapper.
+#'
+#' ## What the wrapper adds
+#' * Common args from `im_common_args()`: `autojoin`, `format`, `features`
+#'   (with `autojoin` default controlled by `getOption("immunarch.autojoin", FALSE)`).
+#' * Validates `idata` is an [immundata::ImmunData] object.
+#' * Ensures all columns in `required_cols` exist in `idata$annotations`.
+#' * If `autojoin = TRUE` and the result is a data frame containing the repertoire id
+#'   column (`immundata::imd_schema("repertoire")`), joins repertoire metadata from
+#'   `idata$repertoires`.
+#'
+#' @param core A function with signature `function(idata, ...)`. This is your core
+#'   implementation; it must accept an `ImmunData` as the first argument and **must not**
+#'   declare `autojoin`, `format`, or `features`.
+#' @param family String. Method family name used for dispatch (e.g., `"airr_stats"`).
+#' @param name String. Method name within the family (e.g., `"lengths"`).
+#' @param register_family Logical (default `TRUE`). If `TRUE`, attempts to create/ensure
+#'   the family environment by calling `register_airr_family()` when available.
+#' @param required_cols Character vector of column names that **must** be present in
+#'   `idata$annotations`. Use this to declare the minimal input schema your core needs.
+#' @param need_repertoires Logical. Use this to declare the necessity of having aggregated
+#'  repertoires.
+#'
+#' @return A **function** — the user-facing wrapper around `core`. Typical usage is to
+#' assign it to the exported symbol of the method, e.g.:
+#' `airr_stats_lengths <- register_immunarch_method(...)`.
+#'
+#' @examples
+#' \dontrun{
+#' # Minimal core implementation (must accept `idata`)
+#' airr_stats_lengths_impl <- function(idata, seq_col = "cdr3_aa") {
+#'   dplyr::as_tibble(idata$annotations) |>
+#'     dplyr::distinct(.data[[immundata::imd_schema("repertoire")]], .data[[seq_col]]) |>
+#'     dplyr::mutate(seq_len = nchar(.data[[seq_col]])) |>
+#'     dplyr::count(.data[[immundata::imd_schema("repertoire")]], seq_len, name = "n")
+#' }
+#'
+#' # Register and expose a user-facing function
+#' airr_stats_lengths <- register_immunarch_method(
+#'   core = airr_stats_lengths_impl,
+#'   family = "airr_stats",
+#'   name = "lengths",
+#'   required_cols = c("cdr3_aa", immundata::imd_schema("repertoire"))
+#' )
+#'
+#' # Optional: call via dispatcher
+#' # make_airr_dispatcher("airr_stats")(idata = immdata, method = "lengths")
+#' }
+#'
+#' @keywords internal
+register_immunarch_method <- function(core, family, name, register_family = TRUE, required_cols = NULL, need_repertoires = TRUE) {
+  fn <- im_method(core, family, name, required_cols = required_cols, need_repertoires = need_repertoires)
 
   if (isTRUE(register_family) && exists("register_airr_family", mode = "function", inherits = TRUE)) {
     try(register_airr_family(family), silent = TRUE)

R/globals.R

@@ -2,7 +2,13 @@ utils::globalVariables(c(
   "index",
   "richness",
   "shannon",
-  "dd"
+  "dd",
+  "counts",
+  "annotate_immundata",
+  "ch",
+  "clonal_prop_bin",
+  "clonal_rank_bin",
+  "prop"
 ))
 
 #' @keywords internal

R/immunarch-package.R

@@ -32,6 +32,7 @@
 #' @importFrom dplyr select
 #' @importFrom dplyr slice_head
 #' @importFrom dplyr summarise
+#' @importFrom dplyr transmute
 #' @importFrom dplyr union
 #' @importFrom dplyr union_all
 #' @importFrom duckplyr as_duckdb_tibble
@@ -53,6 +54,8 @@
 #' @importFrom rlang set_names
 #' @importFrom rlang sym
 #' @importFrom stats runif
+#' @importFrom tidyr as_tibble
+#' @importFrom utils adist
 #' @importFrom utils globalVariables
 #' @useDynLib immunarch, .registration = TRUE
 ## usethis namespace: end

R/v1_migration_updates.R

@@ -1,39 +1,46 @@
 #' @keywords internal
-immunarch_v1_update_sep_2025 <- function() {
-  cli::cli_h1("{cli::col_green('immunarch')} {cli::col_yellow('0.9.x')} -- Critical Pre-release Notice")
+immunarch_v1_update_oct_2025 <- function() {
+  cli::cli_h1("{cli::col_green('immunarch')} {cli::col_yellow('0.10.0')} -- Critical Pre-release Notice")
 
-  cli::cli_alert_warning("Update #1 [Sep 2025] -- Major changes are coming in {cli::col_green('immunarch')} {cli::col_yellow('1.0.0')}!")
+  cli::cli_alert_warning("Update #1 [Oct 2025] -- Major changes are coming in {cli::col_green('immunarch')} {cli::col_yellow('1.0.0')}!")
   cli::cli_text(cli::col_yellow(cli::spark_line(runif(110, 0, 1))))
 
   cli::cli_par()
   cli::cli_text()
   cli::cli_text(
-    "Hi, this is Vadim Nazarov speaking -- author of {cli::col_green('immunarch')}. ",
-    "{cli::col_green('immunarch')} is finally graduating from out of the {cli::col_yellow('0.x.y')} development cycle. ",
-    "I'm preparing our {cli::col_yellow('1.0.0')} release, which will remain stable and free of sudden changes until we approach {cli::col_yellow('2.0.0')}, along with ",
-    "a scientific publication for proper citations. ",
+    "Hi, this is Vadim Nazarov speaking - author of {cli::col_green('immunarch')}. ",
+    "{cli::col_green('immunarch')} is finally graduating out of the {cli::col_yellow('0.x.y')} development cycle. ",
+    "I'm preparing our {cli::col_yellow('1.0.0')} release, which will remain stable and free of sudden changes until we approach {cli::col_yellow('2.0.0')}. ",
+    "A scientific publication will accompany it for proper citation. ",
     "Significant changes are coming, and I want to ensure you have everything you need to migrate to the new version."
   )
 
   cli::cli_par()
   cli::cli_text()
   cli::cli_text("Here's a preview of what's coming in {cli::col_green('immunarch')} {cli::col_yellow('1.0.0')}:")
   cli::cli_bullets(c(
-    "i" = "Some computationally intensive or advanced features (e.g., distance computations, graph-based analyses, dimensionality reduction techniques) will move to separate packages, making {cli::col_green('immunarch')} much more lightweight to install and manage;",
-    "i" = "New functions will be introduced instead of the left old ones to make code more readable and maintainable. Legacy functions will remain temporarily, but they won't be updated and will be removed by {cli::col_yellow('~2027')};",
-    "i" = "We will discontinue support for most custom file formats because the AIRR ecosystem is now mature enough that the majority of tools adhere to the AIRR standard;",
-    "i" = "The package will transition from data frames to the new {cli::col_blue('ImmunData')} structure -- better suited for handling modern larger, more complex, and multi-modal datasets (e.g., single-cell, spatial);",
-    "i" = "{cli::col_blue('ImmunData')} is available in the separate {cli::col_blue('immundata')} package, which you can already install via {cli::col_cyan('pak::pkg_install(\"immundata\")')};",
-    "i" = "The {cli::col_blue('ImmunData')}-based computations will be significantly faster, support datasets larger than RAM, and fully adhere to AIRR Community standards.",
-    "i" = "There currently only a handful functions which implement {cli::col_blue('ImmunData')}-based computations. However, if you want to start learning it, or you have a large-scale data, now it is the best time: the tutorials are available on {cli::col_cyan('https://github.com/immunomind/immundata') and {cli::col_cyan('https://immunomind.github.io/docs/')}"
+    "i" = "Some computationally intensive or advanced features (e.g., distance computations, graph-based analyses, dimensionality reduction techniques) will move to separate packages, making {cli::col_green('immunarch')} much lighter to install and manage.",
+    "i" = "New functions will replace older ones to make code more readable and maintainable. Legacy functions will remain temporarily, but they won't be updated and will be removed {cli::col_yellow('around 2027')}.",
+    "i" = "We will discontinue support for most custom file formats because the AIRR ecosystem is now mature enough; most tools adhere to the AIRR standard.",
+    "i" = "The package will transition from data frames to the new {cli::col_blue('ImmunData')} structure, better suited for handling larger, more complex, and multimodal datasets (e.g., single-cell, spatial).",
+    "i" = "{cli::col_blue('ImmunData')} is available in the separate {cli::col_blue('immundata')} package, which you can already install via {cli::col_cyan('pak::pkg_install(\"immundata\")')}.",
+    "i" = "The {cli::col_blue('ImmunData')}-based computations will be significantly faster, will support datasets larger than RAM, and will fully adhere to AIRR Community standards.",
+    "i" = "There are currently only a handful of functions that implement {cli::col_blue('ImmunData')}-based computations. However, if you want to start learning it, or you have large-scale data, now is the best time: tutorials are available at {.url https://github.com/immunomind/immundata} and {.url https://immunomind.github.io/docs/}."
   ))
 
   cli::cli_par()
   cli::cli_text()
   cli::cli_text(
-    "See the dedicated migration guide for migration on what you can do now and how to prepare for the future:"
+    "See the dedicated migration guide for what you can do now and how to prepare for the future:"
   )
-  cli::cli_text(">> visit {cli::col_cyan('https://immunomind.github.io/docs/tutorials/migration')}")
+  cli::cli_text(">> visit {.url https://immunomind.github.io/docs/tutorials/migration}")
+
+  cli::cli_par()
+  cli::cli_text()
+  cli::cli_text(
+    "See the comprehensive tutorial on how to analyse single-cell AIRR data:"
+  )
+  cli::cli_text(">> visit {.url https://immunomind.github.io/docs/tutorials/single_cell}")
 
   cli::cli_par()
   cli::cli_text()
@@ -42,9 +49,9 @@ immunarch_v1_update_sep_2025 <- function() {
   cli::cli_par()
   cli::cli_text()
   cli::cli_alert_info("Questions, comments, ideas? I'm available via:")
-  cli::cli_text(">> Support email: {cli::col_cyan('support@immunomind.com')}")
-  cli::cli_text(">> GitHub tickets: {cli::col_cyan('https://github.com/immunomind/immunarch')}")
-  cli::cli_text(">> LinkedIn: {cli::col_cyan('https://www.linkedin.com/in/vdnaz/')}")
+  cli::cli_text(">> Support email: {.url mailto:support@immunomind.com}")
+  cli::cli_text(">> GitHub tickets: {.url https://github.com/immunomind/immunarch}")
+  cli::cli_text(">> LinkedIn: {.url https://www.linkedin.com/in/vdnaz/}")
 
   cli::cli_par()
   cli::cli_text()

R/v1_migration_utils.R

@@ -38,5 +38,7 @@ get_immunarch_news <- function(datepoint = "latest") {
 #'
 #' @export
 list_immunarch_news <- function() {
-  names(immunarch_v1_updates)
+  for (i in seq_along(names(immunarch_v1_updates))) {
+    cat(names(immunarch_v1_updates), " -> ", "run immunarch::get_immunarch_news(", '"', names(immunarch_v1_updates), '"', ")", sep = "")
+  }
 }