PosteriorHCA applies Bayesian inference to model the comprehensive
Human Cell Atlas (HCA), allowing researchers to probabilistically
analyze both cellular composition and gene expression patterns
across human samples.
This package provides two main analytical capabilities:
- Cellular Composition Analysis: Uses the
sccomppackage to model variations in cell type proportions across:- Cell Types
- Sex
- Age
- Ethnicity
- Disease conditions
- Tissue Groups
- Gene Expression Prediction: Uses
brmsmodels to predict gene expression levels for specific cell types and genes based on sample metadata including:- Cell Types
- Sex
- Age Decade
- Disease Groups
- Ethnicity Groups
- Assay Groups
- Tissue Groups
The probabilistic landscapes are pre-trained, meaning they represent
posterior distributions estimated from millions of cells.
PosteriorHCA makes these queryable, allowing researchers to:
- Test hypotheses against precomputed reference baselines.
- Compare new samples to expected cellular composition distributions.
- Predict gene expression levels for specific cell types and genes.
- Assess how cell proportions and gene expression vary across human conditions.
To install the latest development version of PosteriorHCA from GitHub,
run:
# Install devtools if not already installed
install.packages("devtools")
# Install PosteriorHCA from GitHub
devtools::install_github("MangiolaLaboratory/posteriorHCA")Once installed, load the package:
library(posteriorHCA)To rebuild this vignette and sync README.md, run
source("scripts/render_introduction.R"); render_introduction() (or
Rscript scripts/render_introduction_cli.R from the package root).
Plain rmarkdown::render("vignettes/Introduction.Rmd") only builds the
vignette HTML.
The package includes a small example dataset for demonstration:
data(example_proportions)
print(example_proportions)
#> # A tibble: 26 × 3
#> sample_id cell_type proportion
#> <chr> <chr> <dbl>
#> 1 0000c153da22cf963b807c0563aca6a6 b memory 0
#> 2 0000c153da22cf963b807c0563aca6a6 b naive 0
#> 3 0000c153da22cf963b807c0563aca6a6 cd14 mono 0
#> 4 0000c153da22cf963b807c0563aca6a6 cd16 mono 0.00502
#> 5 0000c153da22cf963b807c0563aca6a6 cd4 fh em 0
#> 6 0000c153da22cf963b807c0563aca6a6 cd4 naive 0
#> 7 0000c153da22cf963b807c0563aca6a6 cd4 tcm 0.000359
#> 8 0000c153da22cf963b807c0563aca6a6 cd4 th1 em 0
#> 9 0000c153da22cf963b807c0563aca6a6 cd4 th1/th17 em 0.000359
#> 10 0000c153da22cf963b807c0563aca6a6 cd4 th17 em 0
#> # ℹ 16 more rowsThe default composition model is a healthy-only CellNexus sccomp fit.
Unknown covariates can be left as NA; sccomp marginalises over them
automatically.
sccomp_fit <- load_sccomp_fit()
#> ℹ Using cached file: /home/a1237163/.cache/R/posteriorHCA/sccomp_est/cellNexus_1_0_12/estimates_age_decade___L3___disease_FALSE___immune_only_TRUE.rdscomp_draws <- composition_draws(
sccomp_fit,
sex = "male",
age_decade = "4",
ethnicity_groups = "European",
assay_groups = "10x Genomics 3",
tissue_groups = "blood"
)
#> Loading model from cache...
#> Running standalone generated quantities after 1 MCMC chain, with 1 thread(s) per chain...
#>
#> Chain 1 Elapsed Time: 3.472 seconds (Generated Quantities)
#> Chain 1 finished in 0.0 seconds.
head(comp_draws$draws)
#> sample_id age_decade sex ethnicity_groups_imputed assay_groups___altered
#> 1 query_sample 4 male European 10x Genomics 3
#> 2 query_sample 4 male European 10x Genomics 3
#> 3 query_sample 4 male European 10x Genomics 3
#> 4 query_sample 4 male European 10x Genomics 3
#> 5 query_sample 4 male European 10x Genomics 3
#> 6 query_sample 4 male European 10x Genomics 3
#> dataset_id___altered tissue_groups L3 proportion .draw cell_type
#> 1 NA blood b memory 0.04567696 1 b memory
#> 2 NA blood b memory 0.04531969 2 b memory
#> 3 NA blood b memory 0.04686371 3 b memory
#> 4 NA blood b memory 0.05109034 4 b memory
#> 5 NA blood b memory 0.04660289 5 b memory
#> 6 NA blood b memory 0.04953086 6 b memorycomposition_posterior_test() keeps the legacy table + plot interface,
but now uses [load_sccomp_fit()] and [composition_draws()]
internally.
result <- composition_posterior_test(
proportions = example_proportions,
sex = "male",
age_decade = "4",
ethnicity_groups = "European",
assay_groups = "10x Genomics 3",
tissue_groups = "blood",
fit = sccomp_fit
)
#> Loading model from cache...
#> Running standalone generated quantities after 1 MCMC chain, with 1 thread(s) per chain...
#>
#> Chain 1 Elapsed Time: 3.523 seconds (Generated Quantities)
#> Chain 1 finished in 0.0 seconds.
#> # A tibble: 26 × 7
#> sample_id_observed cell_type proportion_observed Empirical_Confidence mean
#> <chr> <chr> <dbl> <dbl> <dbl>
#> 1 0000c153da22cf963… b memory 0 0 4.62e-2
#> 2 0000c153da22cf963… b naive 0 0 5.11e-2
#> 3 0000c153da22cf963… cd14 mono 0 0 3.72e-2
#> 4 0000c153da22cf963… cd16 mono 0.00502 0 1.23e-2
#> 5 0000c153da22cf963… cd4 fh em 0 0 6.81e-4
#> 6 0000c153da22cf963… cd4 naive 0 0 2.11e-1
#> 7 0000c153da22cf963… cd4 tcm 0.000359 0 1.85e-1
#> 8 0000c153da22cf963… cd4 th1 … 0 0 3.74e-3
#> 9 0000c153da22cf963… cd4 th1/… 0.000359 0 6.92e-3
#> 10 0000c153da22cf963… cd4 th17… 0 0 1.72e-3
#> # ℹ 16 more rows
#> # ℹ 2 more variables: lower <dbl>, upper <dbl>
Posterior Distribution Table:
print(result$result_table)
#> # A tibble: 26 × 7
#> sample_id_observed cell_type proportion_observed Empirical_Confidence mean
#> <chr> <chr> <dbl> <dbl> <dbl>
#> 1 0000c153da22cf963… b memory 0 0 4.62e-2
#> 2 0000c153da22cf963… b naive 0 0 5.11e-2
#> 3 0000c153da22cf963… cd14 mono 0 0 3.72e-2
#> 4 0000c153da22cf963… cd16 mono 0.00502 0 1.23e-2
#> 5 0000c153da22cf963… cd4 fh em 0 0 6.81e-4
#> 6 0000c153da22cf963… cd4 naive 0 0 2.11e-1
#> 7 0000c153da22cf963… cd4 tcm 0.000359 0 1.85e-1
#> 8 0000c153da22cf963… cd4 th1 … 0 0 3.74e-3
#> 9 0000c153da22cf963… cd4 th1/… 0.000359 0 6.92e-3
#> 10 0000c153da22cf963… cd4 th17… 0 0 1.72e-3
#> # ℹ 16 more rows
#> # ℹ 2 more variables: lower <dbl>, upper <dbl>Density Plot of Posterior Predictions:
print(result$plot)
Load a stored expression model and draw healthy posteriors with
load_expression_fit(), build_newdata_grid(), and expression_draws():
expression_fit <- load_expression_fit(
cell_type = "cd4 naive",
gene_ensg = "ENSG00000000419"
)
newdata <- build_newdata_grid(
expression_fit,
age_decade = "7",
sex = "female",
disease_groups = "Normal",
ethnicity_groups = "European",
assay_groups = "10x Genomics 3",
tissue_groups = "blood"
)
posterior_draws <- expression_draws(
expression_fit,
newdata = newdata,
quantity = "linpred",
marginalise = "mean"
)Summary Statistics:
summarize_posterior_draws(posterior_draws)Density Plot of Predicted Expression:
print(plot_hca_draws(posterior_draws))
Both composition_posterior_test() / [composition_draws()] and
[expression_draws()] accept metadata inputs corresponding to observed
sample characteristics. For composition, the default healthy sccomp
model uses sex, age decade, ethnicity, assay, and tissue. Unknown
covariates can be set to NA and are marginalised automatically by
sccomp. For expression queries, metadata can also be left empty to
marginalise over the pre-trained model.
If users choose to specify metadata, it must be consistent with the Human Cell Atlas (HCA) annotations to ensure accurate comparisons. Below is a comprehensive list of valid arguments:
-
Cell Types: “b memory”, “b naive”, “cd14 mono”, “cd16 mono”, “cd4 fh em”, “cd4 naive”, “cd4 tcm”, “cd4 th1 em”, “cd4 th1/th17 em”, “cd4 th17 em”, “cd4 th2 em”, “cd8 naive”, “cd8 tcm”, “cd8 tem”, “cdc”, “granulocyte”, “ilc”, “macrophage”, “mait”, “mast”, “nk”, “nkt”, “pdc”, “plasma”, “tgd”, “treg”
-
Sex: “female”, “male”, “unknown”
-
Age Decades: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
-
Ethnicity Groups: “African”, “Other/Unknown”, “European”, “East Asian”, “Hispanic/Latin American”, “South Asian”, “Native American & Pacific Islander”
-
Tissue Groups: “respiratory system”, “blood”, “renal system”, “small intestine”, “nasal, oral, and pharyngeal regions”, “cerebral lobes and cortical areas”, “bone marrow”, “breast”, “cardiovascular system”, “trachea”, “endocrine system”, “liver”, “large intestine”, “lymphatic system”, “prostate”, “sensory-related structures”, “oesophagus”, “spleen”, “brainstem and cerebellar structures”, “stomach”, “female reproductive system”, “thymus”, “adipose tissue”, “integumentary system (skin)”, “digestive system (general)”, “gallbladder”, “pancreas”
sessionInfo()
#> R version 4.5.3 (2026-03-11)
#> Platform: x86_64-conda-linux-gnu
#> Running under: Red Hat Enterprise Linux 8.4 (Ootpa)
#>
#> Matrix products: default
#> BLAS/LAPACK: /home/a1237163/miniconda3/envs/R_env/lib/libopenblasp-r0.3.29.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: Australia/Adelaide
#> tzcode source: system (glibc)
#>
#> attached base packages:
#> [1] stats graphics grDevices utils datasets methods base
#>
#> other attached packages:
#> [1] posteriorHCA_0.2.0 testthat_3.3.2
#>
#> loaded via a namespace (and not attached):
#> [1] RColorBrewer_1.1-3 tensorA_0.36.2.1
#> [3] rstudioapi_0.18.0 jsonlite_2.0.0
#> [5] magrittr_2.0.5 TH.data_1.1-5
#> [7] estimability_1.5.1 farver_2.1.2
#> [9] rmarkdown_2.31 fs_2.1.0
#> [11] vctrs_0.7.3 memoise_2.0.1
#> [13] htmltools_0.5.9 S4Arrays_1.10.1
#> [15] forcats_1.0.1 usethis_3.2.1
#> [17] curl_7.1.0 distributional_0.8.1
#> [19] SparseArray_1.10.10 StanHeaders_2.39.0.9000
#> [21] sass_0.4.10 bslib_0.12.0
#> [23] desc_1.4.3 sandwich_3.1-1
#> [25] emmeans_2.0.3 zoo_1.8-15
#> [27] cachem_1.1.0 lifecycle_1.0.5
#> [29] pkgconfig_2.0.3 Matrix_1.7-5
#> [31] R6_2.6.1 fastmap_1.2.0
#> [33] MatrixGenerics_1.22.0 digest_0.6.39
#> [35] colorspace_2.1-2 patchwork_1.3.2
#> [37] S4Vectors_0.48.1 ps_1.9.3
#> [39] rprojroot_2.1.1 brms_2.23.1
#> [41] pkgload_1.5.2 GenomicRanges_1.62.1
#> [43] labeling_0.4.3 httr_1.4.8
#> [45] abind_1.4-8 compiler_4.5.3
#> [47] bit64_4.8.2 withr_3.0.3
#> [49] inline_0.3.21 S7_0.2.2
#> [51] backports_1.5.1 QuickJSR_1.10.0
#> [53] pkgbuild_1.4.8 MASS_7.3-65
#> [55] DelayedArray_0.36.1 sessioninfo_1.2.3
#> [57] loo_2.10.0.9000 tools_4.5.3
#> [59] otel_0.2.0 glue_1.8.1
#> [61] callr_3.8.0 nlme_3.1-169
#> [63] grid_4.5.3 cmdstanr_0.9.0
#> [65] instantiate_0.2.3 checkmate_2.3.4
#> [67] generics_0.1.4 gtable_0.3.6
#> [69] tzdb_0.5.0 tidyr_1.3.2
#> [71] data.table_1.18.4 hms_1.1.4
#> [73] stringfish_0.19.0 utf8_1.2.6
#> [75] XVector_0.50.0 BiocGenerics_0.56.0
#> [77] ggrepel_0.9.8 pillar_1.11.1
#> [79] stringr_1.6.0 vroom_1.7.1
#> [81] limma_3.66.0 posterior_1.7.1
#> [83] splines_4.5.3 dplyr_1.2.1
#> [85] lattice_0.22-9 bit_4.6.0
#> [87] survival_3.8-6 tidyselect_1.2.1
#> [89] SingleCellExperiment_1.32.0 locfit_1.5-9.12
#> [91] knitr_1.51 gridExtra_2.3.1
#> [93] IRanges_2.44.0 Seqinfo_1.0.0
#> [95] edgeR_4.8.2 SummarizedExperiment_1.40.0
#> [97] stats4_4.5.3 xfun_0.57
#> [99] dittoSeq_1.22.0 bridgesampling_1.2-1
#> [101] Biobase_2.70.0 statmod_1.5.2
#> [103] devtools_2.5.2 brio_1.1.5
#> [105] matrixStats_1.5.0 rstan_2.39.0.9000
#> [107] pheatmap_1.0.13 stringi_1.8.9
#> [109] sccomp_2.2.0 yaml_2.3.12
#> [111] evaluate_1.0.5 codetools_0.2-20
#> [113] tibble_3.3.1 cli_3.6.6
#> [115] RcppParallel_5.1.11-2 xtable_1.8-8
#> [117] processx_3.9.0 jquerylib_0.1.4
#> [119] dichromat_2.0-0.1 Rcpp_1.1.2
#> [121] coda_0.19-4.1 parallel_4.5.3
#> [123] rstantools_2.6.0.9000 ellipsis_0.3.3
#> [125] ggplot2_4.0.3 readr_2.2.0
#> [127] bayesplot_1.15.0.9000 Brobdingnag_1.2-9
#> [129] mvtnorm_1.4-2 scales_1.4.0
#> [131] ggridges_0.5.7 purrr_1.2.2
#> [133] crayon_1.5.3 rlang_1.3.0
#> [135] cowplot_1.2.0 qs2_0.2.1
#> [137] multcomp_1.4-30