# barbieQ: An R package for analysing barcode count data from clonal tracking experiments

# Introduction

The barbieQ package provides a series of robust statistical tools for analysing barcode count data generated from cell clonal tracking (lineage tracing) experiments.

In these experiments, an initial cell and its offspring collectively form a clone (or lineage). A unique DNA barcode, incorporated into the genome of an initial cell, is inherited by all its progeny within the clone. This one-to-one mapping of barcodes to clones enables tracking of clonal behaviours. By quantifying barcode counts, researchers can measure the abundance of individual clones under various experimental conditions or perturbations.

While existing tools for barcode count data analysis primarily rely on qualitative interpretation through visualizations, they often lack robust methods to model the sources of barcode variability.1^

To address this gap, this R software package, barbieQ, provides advanced statistical methods to model barcode variability. The package supports preprocessing, visualization, and statistical testing to identify barcodes with significant differences in proportions or occurrences across experimental conditions. Key functionalities include initializing data structures, filtering barcodes, and applying regression models to test for significant clonal changes.

The main functions include:

- `createBarbieQ()`

- `tagTopBarcodes()`

- `plotBarcodePairCorrelation()`

- `clusterCorrelatingBarcodes()`

- `plotSamplePairCorrelation()`

- `plotBarcodeProportion()`

- `testBarcodeSignif()`

- `plotSignifBarcodeProportion()`

- `plotBarcodeMA()`

# Intallation

    ## You can install the released version of barbieQ like so:
    # if (!require("BiocManager", quietly = TRUE))
    #     install.packages("BiocManager")
    #
    # BiocManager::install("barbieQ")

    ## Alternatively, you can install the development version of barbieQ from GitHub
    devtools::install_github("Oshlack/barbieQ")

# Load Dependecy

    suppressPackageStartupMessages({
      library(barbieQ)
      library(magrittr)
      library(tidyr)
      library(dplyr)
      library(ggplot2)
      library(circlize)
      library(logistf)
      library(igraph)
      library(data.table)
      library(ComplexHeatmap)
      library(limma)
      library(SummarizedExperiment)
      library(S4Vectors)
    })
    set.seed(2025)

# Load Package Data

- Monkey HSPC Cell Barcoding Data (`monkeyHSPC`)

A subset of data from a study on monkey HSPC cell expansion using barcoding technique.2^ Barcode counts within different samples of various cell types were used to interpret the patterns of HSPC differentiation.

It is a `SummarizedExperiment` object created using function `barbieQ::createBarbie`, containing a barcode count matrix with 16,603 rows and 62 columns, and a data frame of sample metadata.

    data(monkeyHSPC, package = "barbieQ")

# Example

## Create `barbieQ` Object

Please start with creating a `barbieQ` structure by passing the barcode count matrix as input to `createBarbieQ()` function .

By creating a `barbieQ` object, a series of data transformations will be automatically applied, and the transformed data will be saved within the `barbieQ` object, for easy use in subsequent analyses.

    ## Passing `object`, `sampleMetadata` and `factorColors` for optional
    exampleBBQ <- createBarbieQ(
      object = SummarizedExperiment::assay(monkeyHSPC),
      sampleMetadata = SummarizedExperiment::colData(monkeyHSPC)$sampleMetadata
    )
    #> continuing with missing `factorColors`.

## Subset Dataset

Here we subset the object by selecting samples from specific stages of collection time.

In `sampleMetadata`, Define “early”, “mid”, and “late” stages based on “Months”, and clean up “Celltype”.

    updateSampleMetadata <- exampleBBQ$sampleMetadata %>%
      as.data.frame() %>%
      select(Celltype, Months) %>%
      mutate(Phase = ifelse(Months < 6, "early", ifelse(Months >=55, "late", "mid"))) %>%
      mutate(Celltype = gsub("(Gr).*", "\\1", Celltype))

    SummarizedExperiment::colData(exampleBBQ)$sampleMetadata <- S4Vectors::DataFrame(updateSampleMetadata)

    exampleBBQ$sampleMetadata
    #> DataFrame with 62 rows and 3 columns
    #>                                                  Celltype    Months       Phase
    #>                                               <character> <numeric> <character>
    #> ZG66_6.5m_T                                             T       6.5         mid
    #> ZG66_12m_T                                              T      12.0         mid
    #> ZG66_17m_T                                              T      17.0         mid
    #> ZG66_27m_T                                              T      27.0         mid
    #> ZG66_36m_T                                              T      36.0         mid
    #> ...                                                   ...       ...         ...
    #> ZG66_58m_NK_NKG2Ap_CD16p_KIR3DL01n NK_NKG2Ap_CD16p_KIR3..        58        late
    #> ZG66_58m_NK_NKG2Ap_CD16p_KIR3DL01p NK_NKG2Ap_CD16p_KIR3..        58        late
    #> ZG66_68m_NK_NKG2Ap_CD16p                  NK_NKG2Ap_CD16p        68        late
    #> ZG66_68m_NK_NKG2Ap_CD16p_KIR3DL01n NK_NKG2Ap_CD16p_KIR3..        68        late
    #> ZG66_68m_NK_NKG2Ap_CD16p_KIR3DL01p NK_NKG2Ap_CD16p_KIR3..        68        late

Subset the object to retain only the samples from the “mid” stage.

    flag_sample <- exampleBBQ$sampleMetadata$Phase == "mid"
    exampleBBQ <- exampleBBQ[, flag_sample]
    exampleBBQ$sampleMetadata
    #> DataFrame with 42 rows and 3 columns
    #>                                 Celltype    Months       Phase
    #>                              <character> <numeric> <character>
    #> ZG66_6.5m_T                            T       6.5         mid
    #> ZG66_12m_T                             T      12.0         mid
    #> ZG66_17m_T                             T      17.0         mid
    #> ZG66_27m_T                             T      27.0         mid
    #> ZG66_36m_T                             T      36.0         mid
    #> ...                                  ...       ...         ...
    #> ZG66_22m_Gr                           Gr      22.0         mid
    #> ZG66_24m_Gr                           Gr      24.0         mid
    #> ZG66_36m_Gr_2                         Gr      36.0         mid
    #> ZG66_14.5m_NK_CD56n_CD16p NK_CD56n_CD16p      14.5         mid
    #> ZG66_14.5m_NK_CD56p_CD16n NK_CD56p_CD16n      14.5         mid

## Tag Top Contributing Barcodes

A filtering step is recommended to remove barcodes that consistently show low counts across the dataset. The retained barcodes, which are considered to make an essential contribution, are referred to as “top barcodes”.

- By applying the `tagTopBarcodes()` function to the `barbieQ` object, you identify and tag the “top barcodes” within the object.

- In this example dataset, we are interested in the differences in barcode outcomes between cell types, so we will group samples by cell types. We set up the `nSampleThreshold` to `6` as the minimum group size.

    ## Check out minimum group size.
    table(exampleBBQ$sampleMetadata$Celltype)
    #>
    #>              B             Gr NK_CD56n_CD16p NK_CD56p_CD16n              T
    #>              6             12              7              7             10
    ## Tag top Barcodes.
    exampleBBQ <- tagTopBarcodes(barbieQ = exampleBBQ, nSampleThreshold = 6)

- Once “top barcodes” are determined and tagged, it’s useful to assess their contributions before actually removing the “bottom barcodes”, which are considered as non-essential contributors.

  - By applying the `plotBarcodePareto()` function to the `barbieQ` object, you can visualize the contribution of each barcode, colour-coded as “top” or “bottom”. (Here, “contribution” refers to the average proportion of individual barcodes across samples in the dataset.)

  - By applying the `plotBarcodeSankey()` function to the `barbieQ` object, you can visualize the collective contribution of the “top” and “bottom” barcode groups.

    ## visualize contribution of top vs. bottom barcodes
    plotBarcodePareto(barbieQ = exampleBBQ) |> plot()
    #> Warning: Removed 10 rows containing missing values or values outside the scale range
    #> (`geom_bar()`).

    ## visualize collective contribution of top vs. bottom barcodes
    plotBarcodeSankey(barbieQ = exampleBBQ) |> plot()

- Once you are happy with the classification of “top” and “bottom” barcodes, you can filter out the “bottom” barcodes by subsetting the `barbieQ` object based on the tagged array.

    flag_barcode <- SummarizedExperiment::rowData(exampleBBQ)$isTopBarcode$isTop
    exampleBBQ <- exampleBBQ[flag_barcode,]

## Visualize Sample Correlation

To gain a general understanding of sample similarity, you can visualize sample pairwise correlations in a checkboard style by applying the `plotSamplePairCorrelation()` function to the `barbieQ` object.

    ## visualize sample pair wise correlation
    plotSamplePairCorrelation(barbieQ = exampleBBQ) |> plot()
    #> setting Celltype as the primary factor in `sampleMetadata`.
    #> displaying pearson correlation coefficient between samples on Barcode log2 CPM+1.

## Interaction with other tools

The `barbieQ` object is interoperable with other packages, such as `bartools`. Below is an example of how to import a `barbieQ` object into the bartools pipeline for visualization. This code chunk is not executed in the vignette, but you can run it in your local environment.

    # devtools::install_github("DaneVass/bartools", dependencies = TRUE, force = TRUE)
    #
    # dge <- DGEList(
    #   counts = assay(exampleBBQ),
    #   group = exampleBBQ$sampleMetadata$Celltype)
    #
    # bartools::plotBarcodeHistogram(dge)

Below is an example of inspecting barcode data variance using `speckle` package. This code chunk is not executed in the vignette, but you can run it in your local environment.

    ## to inspect variance
    # speckle::plotCellTypeMeanVar(assay(exampleBBQ))
    # speckle::plotCellTypePropsMeanVar(assay(exampleBBQ))

## Test Barcodes and Identify Significant Changes

Based on the understanding of sample conditions that likely to be the source of variability in barcode outcomes, you can robustly test the significance of the barcode changes between the sample conditions, by applying the function `testBarcodeSignif()` to the `barbieQ` object. The testing results will be saved in the object, and can be further visualized using functions: `plotBarcodeMA()`, `plotSignifBarcodeHeatmap()`, `plotSignifBarcodeProportion()`, and etc.

- By setting the `method` parameter to “diffProp” (default), you test each barcode’s differential proportion between conditions.

- By setting the `method` parameter by “diffOcc”, you test each barcode’s differential occurrence between conditions.

### Differential Proportion

We recommend setting the `transformation` parameter to “asin-sqrt” (default), although alternatives such as “logit” and “none” are also available. Statistical tests are performed on the data following the specified proportion transformation.

    ## test Barcode differential proportion between sample groups
    ## Defult transformation: asin-sqrt
    asinTrans <- testBarcodeSignif(
      barbieQ = exampleBBQ,
      contrastFormula = "(CelltypeNK_CD56n_CD16p) - (CelltypeB+CelltypeGr+CelltypeT+CelltypeNK_CD56p_CD16n)/4",
      method = "diffProp", transformation = "asin-sqrt"
    )
    #> setting Celltype as the primary factor in `sampleMetadata`.
    #> removing factors with only one level from sampleMetadata: NA
    #> no block specified, so there are no duplicate measurements.

    ## Alternatively: using logit transformation
    logitTrans <- testBarcodeSignif(
      barbieQ = exampleBBQ,
      contrastFormula = "(CelltypeNK_CD56n_CD16p) - (CelltypeB+CelltypeGr+CelltypeT+CelltypeNK_CD56p_CD16n)/4",
      method = "diffProp", transformation = "logit"
    )
    #> setting Celltype as the primary factor in `sampleMetadata`.
    #> removing factors with only one level from sampleMetadata: NA
    #> Warning in FUN(X[[i]], ...): NaNs produced
    #> no block specified, so there are no duplicate measurements.

    ## Alternatively: no transformation
    noTrans <- testBarcodeSignif(
      barbieQ = exampleBBQ,
      contrastFormula = "(CelltypeNK_CD56n_CD16p) - (CelltypeB+CelltypeGr+CelltypeT+CelltypeNK_CD56p_CD16n)/4",
      method = "diffProp", transformation = "none"
    )
    #> setting Celltype as the primary factor in `sampleMetadata`.
    #> removing factors with only one level from sampleMetadata: NA
    #> no block specified, so there are no duplicate measurements.

Draw MA plot for differential proportion tests following different transformations.

    (plotBarcodeMA(asinTrans) + coord_trans(x = "log10"))|> plot()
    #> Warning: `coord_trans()` was deprecated in ggplot2 4.0.0.
    #> ℹ Please use `coord_transform()` instead.
    #> This warning is displayed once per session.
    #> Call `lifecycle::last_lifecycle_warnings()` to see where this warning was
    #> generated.

    plotBarcodeMA(logitTrans)|> plot()

    (plotBarcodeMA(noTrans) + coord_trans(x = "log10"))|> plot()

Annotate barcodes in the heatmap based on significance derived from differential proportion tests following different transformations.

    plotSignifBarcodeHeatmap(asinTrans) |> plot()
    plotSignifBarcodeHeatmap(logitTrans) |> plot()

Visualize the aggregated barcode proportion in each sample, grouped by significance.

    plotSignifBarcodeProportion(asinTrans) |> plot()

    plotSignifBarcodeProportion(logitTrans) |> plot()

### Differential Occurrence

In differential occurrence test, the `regularization` parameter is set to “firth” by default, and is strongly recommended, especially with small sample sizes.

    ## test Barcode differential occurrence between sample groups
    ## set up the targets (sample conditions)
    targets <- exampleBBQ$sampleMetadata %>%
      as.data.frame() %>%
      mutate(Group = ifelse(
        Celltype == "NK_CD56n_CD16p",
        "NK_CD56n_CD16p",
        "B.Gr.T.NK_CD56p_CD16n"))

    exampleBBQ <- testBarcodeSignif(
      barbieQ = exampleBBQ,
      sampleMetadata = targets[,"Group", drop=FALSE],
      method = "diffOcc"
    )
    #> setting Group as the primary factor in `sampleMetadata`.
    #> setting up contrastFormula: GroupNK_CD56n_CD16p - GroupB.Gr.T.NK_CD56p_CD16n

Draw an “MA plot” for the differential occurrence test by plotting the Log Odds Ratio (LOR) against the Mean Occurrence Frequency (number of total occurrences across samples / number of total samples) for each barcode.

    plotBarcodeMA(exampleBBQ) |> plot()

    plotSignifBarcodeHeatmap(exampleBBQ) |> plot()

    plotSignifBarcodeProportion(exampleBBQ) |> plot()

# References

We are currently writing a paper to introduce the methods and approaches implemented in this `barbieQ` package and will update with a citation once available.

# SessionInfo

    sessionInfo()
    #> R version 4.6.0 (2026-04-24)
    #> Platform: x86_64-pc-linux-gnu
    #> Running under: Ubuntu 24.04.4 LTS
    #>
    #> Matrix products: default
    #> BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
    #> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so;  LAPACK version 3.12.0
    #>
    #> locale:
    #>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C
    #>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8
    #>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8
    #>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C
    #>  [9] LC_ADDRESS=C               LC_TELEPHONE=C
    #> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
    #>
    #> time zone: Etc/UTC
    #> tzcode source: system (glibc)
    #>
    #> attached base packages:
    #> [1] stats4    grid      stats     graphics  grDevices utils     datasets
    #> [8] methods   base
    #>
    #> other attached packages:
    #>  [1] SummarizedExperiment_1.42.0 Biobase_2.72.0
    #>  [3] GenomicRanges_1.64.0        Seqinfo_1.2.0
    #>  [5] IRanges_2.46.0              S4Vectors_0.50.0
    #>  [7] BiocGenerics_0.58.0         generics_0.1.4
    #>  [9] MatrixGenerics_1.24.0       matrixStats_1.5.0
    #> [11] limma_3.68.0                ComplexHeatmap_2.28.0
    #> [13] data.table_1.18.2.1         igraph_2.3.0
    #> [15] logistf_1.26.1              circlize_0.4.18
    #> [17] ggplot2_4.0.3               dplyr_1.2.1
    #> [19] tidyr_1.3.2                 magrittr_2.0.5
    #> [21] barbieQ_1.4.0               BiocStyle_2.40.0
    #>
    #> loaded via a namespace (and not attached):
    #>  [1] Rdpack_2.6.6           rlang_1.2.0            clue_0.3-68
    #>  [4] GetoptLong_1.1.1       compiler_4.6.0         mgcv_1.9-4
    #>  [7] png_0.1-9              vctrs_0.7.3            pkgconfig_2.0.3
    #> [10] shape_1.4.6.1          crayon_1.5.3           fastmap_1.2.0
    #> [13] backports_1.5.1        XVector_0.52.0         labeling_0.4.3
    #> [16] rmarkdown_2.31         nloptr_2.2.1           purrr_1.2.2
    #> [19] xfun_0.57              glmnet_4.1-10          jomo_2.7-6
    #> [22] cachem_1.1.0           jsonlite_2.0.0         DelayedArray_0.38.0
    #> [25] pan_1.9                broom_1.0.12           parallel_4.6.0
    #> [28] cluster_2.1.8.2        R6_2.6.1               bslib_0.10.0
    #> [31] RColorBrewer_1.1-3     boot_1.3-32            rpart_4.1.27
    #> [34] jquerylib_0.1.4        Rcpp_1.1.1-1.1         iterators_1.0.14
    #> [37] knitr_1.51             Matrix_1.7-5           splines_4.6.0
    #> [40] nnet_7.3-20            tidyselect_1.2.1       abind_1.4-8
    #> [43] yaml_2.3.12            doParallel_1.0.17      codetools_0.2-20
    #> [46] lattice_0.22-9         tibble_3.3.1           withr_3.0.2
    #> [49] S7_0.2.2               evaluate_1.0.5         survival_3.8-6
    #> [52] pillar_1.11.1          BiocManager_1.30.27    mice_3.19.0
    #> [55] foreach_1.5.2          reformulas_0.4.4       scales_1.4.0
    #> [58] minqa_1.2.8            glue_1.8.1             maketools_1.3.2
    #> [61] tools_4.6.0            sys_3.4.3              lme4_2.0-1
    #> [64] buildtools_1.0.0       rbibutils_2.4.1        colorspace_2.1-2
    #> [67] nlme_3.1-169           formula.tools_1.7.1    cli_3.6.6
    #> [70] S4Arrays_1.12.0        gtable_0.3.6           sass_0.4.10
    #> [73] digest_0.6.39          operator.tools_1.6.3.1 SparseArray_1.12.0
    #> [76] rjson_0.2.23           farver_2.1.2           htmltools_0.5.9
    #> [79] lifecycle_1.0.5        GlobalOptions_0.1.4    mitml_0.4-5
    #> [82] statmod_1.5.1          MASS_7.3-65

1. barcodetrackR, CellDestiny, genBaRcode↩︎

2. NK clonal expansion), barcodetrackRData↩︎