NEWS.md

scRepertoire VERSION 2.7.3

BUG FIXES

• Fixed combineBCR() assigning the same group.by value to all cells instead of per-barcode values.
• Fixed clonalCluster() failing when group.by produces a single group by correcting the condition for adding the group column to the edge list.
• Fixed test for CTstrict clustering pattern to match the new default chain = "IGH" behavior in combineBCR().

scRepertoire VERSION 2.7.2

NEW FEATURES

• New clonalBin() function to bin clones by frequency or proportion without requiring a single-cell object. Adds clonalFrequency, clonalProportion, and cloneSize columns to the output of combineTCR(), combineBCR(), or combineExpression(). Supports custom bin thresholds, optional grouping by metadata variable, and chain filtering.
• New vizCirclize() function for quick chord diagram visualization without manual circlize code. Supports directional arrows, custom colors, and sector annotations.
• getCirclize() major enhancements:
  • Multi-level hierarchical grouping via group.by accepting a vector of columns
  • New method parameter: "unique", "abundance", "jaccard", "overlap"
  • New symmetric parameter for directional flow analysis
  • New include.metadata parameter returning sector statistics
  • New filtering options: min.shared, top.links, filter.sectors
  • Built-in color palette generation with palette parameter
• alluvialClones() major enhancements:
  • New top.clones, min.freq, highlight.clones, and highlight.color parameters
  • Visual customization: stratum.width, flow.alpha, show.labels, label.size
  • New order.strata parameter for controlling level ordering within each stratum
  • Enhanced export.table output now includes freq, prop, and rank columns
• combineBCR() defaults the clustering call to "IGH" instead of "both"

API CHANGES

• Soft-deprecated camelCase arguments across all exported functions in favor of dot.notation (e.g., cloneCall to clone.call, exportTable to export.table, cloneSize to clone.size, filterNA to filter.na, addLabel to add.label, clonalSplit to clonal.split). All deprecated arguments will continue to work with a deprecation warning until version 3.0.0.

BUG FIXES

• Fixed combineExpression() failing with "undefined columns selected" when input data already contained clonalFrequency/clonalProportion columns from a prior clonalBin() call.

scRepertoire VERSION 2.6.2

UNDERLYING CHANGES

• Expanded functionality in combineBCR() and clonalCluster():
  • New metrics beyond normalized Levenshtein edit distances
  • Support for raw and normalized-based calculations
  • Support for distance matrices to allow for alignment
• Added support for declaring chains = "IGL", "IGK", or "Light" to get all light chains in downstream quantification.

BUG FIXES

• Fixed handling of multiple chains in combineBCR(), specifically in formatting CTstrict.

scRepertoire VERSION 2.6.1

Update to match Bioconductor Release 3.22 on 2025/10/30.

BUG FIXES

• Fixed order.by issue in positionalProperty().
• Fixed individual chain call for combineExpression().
• Fixed issue with removing kmer with ";" in percentKmer().

scRepertoire VERSION 2.5.7

BUG FIXES

• Fixed chain handling for BCR genes in percentGeneUsage() and propagated to wrappers: percentGenes(), percentVJ(), and vizGenes().

scRepertoire VERSION 2.5.6

BUG FIXES

• Fixed passing group.by for combineBCR().

scRepertoire VERSION 2.5.5

UNDERLYING CHANGES

• Updated unit tests for ggplot2 v4.

scRepertoire VERSION 2.5.3

BUG FIXES

• Fixed clonalProportion calculation to use grouping properly during combineExpression().
• Fixed immunarch support for exportClones() TRA/Light chain column handling.

scRepertoire VERSION 2.5.2

UNDERLYING CHANGES

• Added support for mouse genes in quietBCRgenes() and quietTCRgenes().

scRepertoire VERSION 2.5.1

UNDERLYING CHANGES

• Introduced pairwise calculations to StartracDiversity().
• Internal function conversion for clonalSizeDistribution() - removed cubature, truncdist, and VGAM from dependencies.
• Increased speed of clonalSizeDistribution().

scRepertoire VERSION 2.5.0

UNDERLYING CHANGES

• Updated and improved code for loadContigs().
• Consolidated support for discrete AIRR formats under the umbrella of AIRR.
• Added "tcrpheno" and "immunarch" to exportClones().
• Converted exportClones() to base R to reduce dependencies.
• Added dandelionR and tcrpheno vignettes to pkgdown site.
• percentAA() refactored to minimize dependencies and use immApex calculateFrequency().
• positionalEntropy() refactored to minimize dependencies and use immApex calculateEntropy().
• clonalDiversity() refactored for performance - now calculates a single diversity metric at a time and includes new estimators like "gini", "d50", and supports hill numbers.
• percentKmer() refactored to use immApex calculateMotif() for both aa and nt sequences. No longer calculates all possible motifs, but only motifs present.
• clonalCluster() now allows for dual-chain clustering, V/J filtering, normalized or straight edit distance calculations, and return of clusters, igraph objects, or adjacency matrix.
• combineBCR() offers single/dual chain clustering, aa or nt sequences, adaptive filtering of V and J genes, and normalized or straight edit distance calculations.
• percentGeneUsage() is now the underlying function for percentGenes(), percentVJ(), and vizGenes() and allows for percent, proportion, and raw count quantification.
• Added common theme (internal .themeRepertoire()) to all plots and allow users to pass arguments to it.

BUG FIXES

• clonalCompare() issue with plotting a 0 row data frame now errors with message.
• clonalScatter() group.by/axes call now works for non-single-cell objects.
• Fixed issue with NULL and "none" group.by in combineExpression().
• Allowing multi groupings via x.axis and group.by in clonalDiversity().

scRepertoire VERSION 2.3.4

UNDERLYING CHANGES

• Updated internal .parseContigs() to function with more complex groupings.
• Added annotateInvariant() functionality for mouse and human TCRs.
• Added quietTCRgenes(), quietBCRgenes(), quietVDJgenes().
• Fixed issue with clonalCompare() assertthat statements.
• Started integration with immApex API package.

scRepertoire VERSION 2.3.2

BUG FIXES

• Fixed issue with denominator in getCirclize().
• Fixed chain issue with clonalCompare() - expanded assertthat statement.

scRepertoire VERSION 2.2.1

Update for Bioconductor version 3.20.

NEW FEATURES

• Added support for BCRs for loading ParseBio sequences.
• Added quietBCRgenes(), quietTCRgenes(), and quietVDJgenes() for filtering out known TCR and/or BCR gene signatures.

UNDERLYING CHANGES

• Added Seurat to the Suggests field in the DESCRIPTION file.

scRepertoire VERSION 2.0.8

NEW FEATURES

• Added getContigDoublets() experimental function to identify TCR and BCR doublets as a preprocessing step to combineExpression().
• Added proportion argument to clonalCompare() so that when set to FALSE, the comparison will be based on frequency normalized by per-sample repertoire diversity.

UNDERLYING CHANGES

• Fixed issue with single chain output for clonalLength().
• Removed unnecessary code remnant in clonalLength().
• Allow one sample to be plotted by percentVJ().
• Fixed issue with positionalProperty() and exportTable.
• Fixed issue with loadContigs() edge case when TRUST4 data only has 1 row.
• Converted documentation to use markdown (roxygen2md).
• Imported lifecycle, purrr, withr.
• Fixed issue with clonalCluster() and exportGraph = TRUE.
• Improved performance of combineBCR() by a constant factor with C++.
• Restructured functions to exportTable before plotting.

scRepertoire VERSION 2.0.7

BUG FIXES

• Fixed issue with group.by in clonalOverlap().
• Fixed issue with group.by in clonalCompare().

scRepertoire VERSION 2.0.6

BUG FIXES

• Fixed issue with custom column headers for clones.

scRepertoire VERSION 2.0.5

UNDERLYING CHANGES

• Added type checks using assertthat.
• Updated conditional statements in constructConDFAndparseTCR.cpp.
• Fixed issue in clonalQuant() and factor-based group.by variable.

scRepertoire VERSION 2.0.4

UNDERLYING CHANGES

• getCirclize() refactored to prevent assumptions and added include.self argument.
• Added .count.clones() internal function for getCirclize() and clonalNetwork().
• Added order.by parameter to visualizations to specifically call order of plotting using a vector or "alphanumeric".
• Fixed issue with clonalLength() and NA handling.
• clonalCompare() now retains the original clonal info if using relabel.clones.
• Added Dandelion support to loadContigs() and testthat.
• Fixed issue with positionalProperty() assumption that clones will all have 20 amino acids.
• Fixed issue with positionalProperty() and removing non-amino acids.
• Fixed IGH/K/L mistaking gene issue in vizGenes().
• Added error message for NULL results in clonalCluster() with export.graph = TRUE.
• Fixed issue with "full.clones" missing in combineExpression() when using 1 chain.

scRepertoire VERSION 2.0.3

UNDERLYING CHANGES

• Modified support for Omniscope format to allow for dual chains.
• Added ParseBio support to loadContigs() and testthat.
• Added support for productive variable to loadContigs() for BD, Omniscope, and Immcantation formats.
• Replaced numerical indexing with name indexing for loadContigs().
• combineBCR() and combineTCR() now allow for unproductive contig inclusions with new filterNonproductive parameter.
• combineBCR() will now prompt user if samples is not included instead of erroring.
• Added base threshold by length for internal .lvCompare().
• Ensured internal .lvCompare() only looks at first set of sequences in multi-sequence chain.
• Fixed bug in exporting graph for clonalCluster().
• Fixed conflict in functions between igraph and dplyr packages.

scRepertoire VERSION 2.0.2

BUG FIXES

• clonalOccupy() rewrite counting and NA handling.

scRepertoire VERSION 2.0.1

UNDERLYING CHANGES

• clonalOverlay() arguments now cutpoint and use cut.category to select either clonalProportion or clonalFrequency.

scRepertoire VERSION 2.0.0 (2024-01-10)

NEW FEATURES

• Added percentAA(), percentGenes(), percentVJ(), percentKmer(), exportClones(), positionalEntropy(), positionalProperty().
• Renamed functions: compareClonotypes to clonalCompare(), clonotypeSizeDistribution to clonalSizeDistribution(), scatterClonotypes to clonalScatter(), quantContig to clonalQuant(), highlightClonotypes to highlightClones(), lengthContigs to clonalLength(), occupiedscRepertoire to clonalOccupy(), abundanceContig to clonalAbundance(), alluvialClonotypes to alluvialClones().
• Added features to clonalCompare() to allow for highlighting sequences and relabeling clonotypes.

UNDERLYING CHANGES

• Removed internal .quiet() function.
• .theCall() now allows for a custom header/variable and checks the colnames.
• Replaced data arguments to be more descriptive: df to input.data, dir to input, sc to sc.data.
• Deep clean on documentation for increased consistency and explainability.
• StartracDiversity() metric re-implemented to remove startrac-class object intermediary.
• Implemented powerTCR locally to reduce dependencies and continue support.
• Universalized underlying function language and intermediate variables.
• License change to MIT.
• group.by and split.by consolidated into single group.by parameter.
• Added support for Immcantation pipeline, .json, Omniscope, and MiXCR formats for loadContigs().
• Made GitHub.io website for support/vignettes/FAQ.
• Added testthat for all exported and internal functions.
• Fixed issue with clonalQuant() for instance of scale = FALSE and group.by being set.
• clonalDiversity() no longer automatically orders samples.
• Removed order parameter from clonalQuant(), clonalLength(), and clonalAbundance().
• x.axis parameter in clonalDiversity() separated from group.by parameter.
• Filtering chains will not eliminate non-matching chains.

DEPRECATED AND DEFUNCT

• Deprecated stripBarcodes().
• Deprecated expression2List() (now only an internal function).
• Deprecated checkContigs().

scRepertoire VERSION 1.11.0

• Rebasing for Bioconductor version.

scRepertoire VERSION 1.7.5

• Fixed combineBCR() to allow for non-related sequences.

scRepertoire VERSION 1.7.4

NEW FEATURES

• checkContigs() function to quantify the percentages of NA values by genes or sequences.
• exportClones to clonalNetwork() to isolate clones shared across identities.

UNDERLYING CHANGES

• Fixed issue with clonalDiversity() and skipping boots.
• Fixed underlying assumptions with clonalBias().
• Added reads variable to parseAIRR.
• Fixed handling of samples parameter in combine functions.
• Removed need to relevel the cloneType factor after combineExpression().
• Set up lapply() for combineBCR() and clusterTCR() - no more pairwise distance matrix calculation.
• loadContigs() support for data.frames or lists of contigs.
• Added examples for loadContigs().
• Removed requirement for T cell type designation - will combine A/B and G/D simultaneously.
• Updated combineBCR() to chunk nucleotide edit distance calculations by V gene and give option to skip edit distance calculation with call.related.clones = FALSE.
• Updated clusterTCR() to use lvCompare() and base edit distances on V gene usage.

scRepertoire VERSION 1.7.3

UNDERLYING CHANGES

• Fixed misspellings for parse functions.
• Optimized WAT3R and 10x loadContigs().
• Removed combineTRUST4 - superseded by loadContigs().
• Added support of TRUST4 for combineBCR().
• Added support for BD in loadContigs().
• loadContigs() TRUST4 parsing allows for all NA values in a chain.
• combineExpression() group.by = NULL will now collapse the whole list.

scRepertoire VERSION 1.7.2

UNDERLYING CHANGES

• clonalDiversity() now has skip.boots to stop bootstrapping and downsampling.

scRepertoire VERSION 1.7.0

UNDERLYING CHANGES

• Rebumping the version change with new release of Bioconductor.
• Added mean call to the heatmap of vizGenes().
• filteringMulti in combineTCR now checks to remove list elements with 0 cells.
• Removed top_n() call (deprecated), using slice_max() without ties.
• Added arrange() call during parseTCR() to organize the chains.
• Corrected the gd flip in combine functions.
• Removed viridis call in clonalNetwork() that was leading to errors.
• Matched syntax for strict clonotype in combineBCR().
• Added group.by variable to all applicable visualizations.
• Added return.boots to clonalDiversity() to allow export of all bootstrapped values.

scRepertoire VERSION 1.5.4

BUG FIXES

• Modified grabMeta() internal function to no longer assume the active identity is clusters.
• checkBlanks() now checks if a blank was detected before trying to remove it.
• clonalNetwork() automatically resulted in default error message - bug now removed.
• clonalBias() now adds z-score of bias when matrix is exported. exportTable parameter is now fixed.

scRepertoire VERSION 1.5.3

UNDERLYING CHANGES

• Added loadContigs() for non-10X formatted single-cell data.
• Removed combineTRUST4, superseded by loadContigs().
• combineTCR() now allows for > 3 recovered TCRs per barcode.
• Re-added filtering steps to combineTCR(), will detect if data is from 10X and automatically remove nonproductive or multi chains.
• Updated parseTCR() to include evaluation for gamma/delta chains.

scRepertoire VERSION 1.5.2

UNDERLYING CHANGES

• highlightClones() now returns the specific clones instead of clonotype 1, etc.
• clonalCompare() numbers parameter now for group-wide numbers and not overall top X numbers.
• Fixed issue with clonalDiversity() that caused errors when group.by parameter was used.
• Modified parseBCR() to reduce complexity and assume lambda >> kappa.
• Fixed clonalCluster() function broken with Seurat Objects.
• checkContigs now ensures data frames and that "" are converted into NAs.
• Modified makeGenes() internal function changing na.omit to str_replace_na() and separating the BCR calls by chain to prevent combination errors.

scRepertoire VERSION 1.3.5

UNDERLYING CHANGES

• Modified parseBCR() to check for contents of the chains. Resolved issue with placing light chain into heavy chain slots when 2 contigs are present.
• Updated checkBlanks() to include NA evaluation and placed the check in all viz functions.
• Added clonalNetwork() function.
• Modified diversity visualization to remove outliers and place graphs on a single line.
• Modified clonalOverlay() to use new internal getCoord() function like clonalNetwork().
• Added threshold parameter to clonalSizeDistribution().
• Added support for single-cell objects to clonalCluster().

scRepertoire VERSION 1.3.4

UNDERLYING CHANGES

• Modified clonalCluster() and combineBCR() to speed up comparison and use less memory.
• filteringMulti now isolates the top contig by chain, then for barcodes with chains > 2, isolates the top expressing chains.
• Modified makeGenes() internal function to use str_c().
• Added threshold parameter to combineTRUST4 for B cell manipulation.
• Changed combineTCR function to prevent cell type mix up.
• vizGenes() can now look at other component genes of the receptor and separate parameter replaced by y.axis.
• Added clonalBias() function for inter-cluster comparison.
• Fixed clonalCluster() and combineBCR() assumption that you will have unrelated clones.

scRepertoire VERSION 1.3.3

UNDERLYING CHANGES

• combineBCR() auto naming function updated to actually name the list elements.
• Added createHTOContigList() function to create contig list of multiplexed experiments. Fixed issue with groupBy variable.
• Added Inverse Pielou metric to diversity call.
• Added include.na and split.by to clonalOccupy() and changed labeling depending on frequency vs proportion.
• Added support for single-cell objects for most visualizations, list organizing by single-cell object can be called using split.by variable.
• All group and groupBy parameters are now group.by.

scRepertoire VERSION 1.3.2

UNDERLYING CHANGES

• Added dot.size parameter to clonalScatter().
• filteringMulti now subsets clonotypes with contigs >= 2, to prevent 2 of the same chains.
• Changed how coldata is added to SCE objects using merge instead of union.
• Can now add BCR and TCR simultaneously by making large list.
• Scatter plotting code allows for user to select dot.size as a variable on the x or y axis.
• Removed regressClonotype function - too many dependencies required.
• Added chain option to visualizations and combineExpression() to allow users to facilitate single chains - removed chain option from combineTCR/combineBCR/combineTRUST4.
• Added NA filter to combineTCR/combineBCR/combineTRUST4 for cell barcodes with only NA values.
• Added NA filter to expression2List() for cells with NA clonotypes.
• Updated vizGenes() to order genes automatically by highest to lowest variance.
• Updated vizGenes() to pull the correct genes based on selection.
• Updated parse method for V/J/D placement in TRB/Heavy chains.
• Simplified clonalDiversity() to allow for more options in organizing plot and box plots.
• combineExpression() adds the groupBy variable to Frequency, allowing for multiple calculations to be saved in the meta data.

scRepertoire VERSION 1.2.3

UNDERLYING CHANGES

• Changed the access of the sample data to github.io repo.

scRepertoire VERSION 1.2.2

DEPRECATED AND DEFUNCT

• Removed Startrac-based functions to pass build on Bioconductor.
• Deprecated StartracDiversity().

scRepertoire VERSION 1.2.0

UNDERLYING CHANGES

• Added support for SingleCellExperiment format.

DEPRECATED AND DEFUNCT

• Deprecated combineSeurat in favor of combineExpression().
• Deprecated seurat2List in favor of expression2List().

scRepertoire VERSION 1.1.4

NEW FEATURES

• Added proportion to combineExpression() function.
• Added clonalCluster() and clonalOverlay() functions.

UNDERLYING CHANGES

• Replaced hammingCompare with lvCompare to enable superior clonotype calling in combineBCR().
• Added downsampling to diversity calculations.
• Fixed Clonal Overlap Coefficient issue - was comparing unique barcodes and not clonotypes.
• Added checkBlanks() function to remove list elements without clonotypes.
• Re-added Startrac metrics by stripping down the package.
• Heavily modified dependencies to reduce total number.

scRepertoire VERSION 1.0.0

UNDERLYING CHANGES

• Removed dependencies ggfittext and ggdendrogram.
• clonalSizeDistribution() now returns a plot() function.

scRepertoire VERSION 0.99.0

• Initial Bioconductor submission.
• Added getCirclize(), exportTable to visualization functions.
• Added screp_example data to package.
• Added vizGenes() function and support for monocle in combineExpression().