Compositional Data Analysis for Stereological, Histomorphometric and Blood-Cell Data
A Shiny application implementing the Aitchison geometry for the full data analysis cycle: data upload, zero/NA handling, compositional visualisation, balances, and permutational MANOVA with post-hoc tests. Interface in English, Portuguese and Spanish.
Developed alongside: Provete, D.B., Severgnini, M.R., Fernandes, C.E. & Franco-Belussi, L. A Practical Guide to using Compositional Data Analysis in Tissue Stereology and Blood Cell Profile. Physiological Reports (in review).
Use it online, no installation needed: https://sxzbf8.short.gy/CoDaStereo
(the interface opens in English; add ?lang=pt or ?lang=es to the link for
Portuguese or Spanish).
See NEWS.md for the changes in each version and the package website for the getting-started guide.
| Module | Capabilities |
|---|---|
| Data Upload | CSV and Excel (.xlsx/.xls) with sheet selector; the four case-study datasets of the companion paper as examples; aggregation of fields of view into specimens (nested designs); smart parts selector; pre-flight check |
| Data Inspection | Zero/NA heatmap (observed vs. structural zero vs. missing); naniar::vis_miss plot; counts per part |
| Zero Handling | Three methods via zCompositions: CZM (count zeros), multRepl (rounded zeros), lrEM (rounded zeros); NA handling via listwise deletion or geometric-mean imputation |
| Compositional Analysis | Ternary plot in pure ggplot2 with amalgamation, convex hulls or 95% confidence/predictive regions and group centres; clr-biplot on unscaled clr coordinates (axis choice, shapes, labels, optional log-total as in a T-space biplot) with a "how to read" note, scree plot and ray lengths; variation-matrix heatmap; compositional centre and total variance per group; colour palettes (Okabe-Ito, Dark2, viridis); interactive hover (ggiraph) |
| Balances (SBP) | Automatic sequential binary partition (Ward clustering on clr distances), editable cell by cell with on-the-fly validation; CoDa dendrogram; boxplots and permutational tests (Z, P) of each balance by group |
| Statistical Modeling | Permutational MANOVA via RRPP::lm.rrpp with factors, covariates (ANCOVA), a block term, SS type I/II/III and 199-9999 permutations (fixed seed); the log-total as a joint response or a covariate (Pawlowsky-Glahn, Egozcue & Lovell 2015), with a warning when totals are fixed by design; pairwise tests of means and dispersions; residual diagnostics. Fits run in background workers (mirai) |
| Reproducibility | R script that reproduces the analysis; self-contained HTML report; save and reload the session (JSON) |
| Downloads | Every figure as PDF, PNG, SVG or TIFF at a chosen size, resolution and font size; imputed data, SBP, variation matrix, ANOVA, balance and pairwise tables as CSV |
Install the binary package from r-universe (no build tools needed):
install.packages("CoDaStereo",
repos = c("https://diogoprov.r-universe.dev", "https://cloud.r-project.org"))
# Launch
CoDaStereo::run_app()
Or install the development version from GitHub:
# install.packages("devtools")
devtools::install_github("diogoprov/CoDaStereo")
# Clone the repo, then:
setwd("CoDaStereo/")
pkgload::load_all()
run_app()
CoDaStereo depends on: shiny, shinydashboard, rintrojs, dplyr,
ggplot2, ggiraph, ggrepel, scales, svglite, readxl, naniar,
compositions, zCompositions, RRPP, FactoMineR, htmltools,
jsonlite and golem. If mirai is installed, model fits run in background
workers so the interface stays responsive.
All are available on CRAN.
Connect Cloud is Posit's next-generation hosting platform. It deploys directly from a public GitHub repository with automatic push-to-publish.
Fork or push this repository to your GitHub account.
Generate manifest.json — this file tells Connect Cloud which R
version and packages to use. Run this once in your local R session
(from the repository root):
# install.packages("rsconnect")
# list only the files the deployed app needs
f <- system("git ls-files", intern = TRUE)
f <- f[grepl("^(app[.]R|DESCRIPTION|NAMESPACE|LICENSE|R/|www/|inst/)", f)]
rsconnect::writeManifest(appDir = ".", appFiles = f, appPrimaryDoc = "app.R")
# (the same code is in dev/write_manifest.R)
Commit and push the generated manifest.json.
Sign in to Connect Cloud with your GitHub account.
Click "Publish" (+ icon at the top), select your repository and
branch (main). Connect Cloud will detect app.R and deploy
automatically.
Get a shareable URL — share it in your manuscript or supplementary materials.
After the initial setup, every git push to main triggers an
automatic re-deploy. No manual steps needed.
# One-time authentication (opens browser)
rsconnect::connectCloudUser()
# Deploy
rsconnect::deployApp(appDir = ".", appName = "CoDaStereo")
CoDaStereo/
├── app.R # Entry point for Posit Connect Cloud
├── DESCRIPTION, NAMESPACE, LICENSE, NEWS.md, _pkgdown.yml
├── manifest.json # Generated by rsconnect::writeManifest()
├── R/
│ ├── run_app.R # golem entry point: run_app()
│ ├── app_ui.R # Dashboard layout (assembles modules)
│ ├── app_server.R # Wires modules, session state and restore
│ ├── fct_helpers.R # Zeros, ternary plot, palettes, SBP, total, clr-PCA, examples
│ ├── fct_plots.R # Biplot, scree, variation matrix, regions, balances, export
│ ├── fct_models.R # RRPP model fitting and background workers (mirai)
│ ├── fct_reproducibility.R # R script, HTML report, session JSON
│ ├── fct_i18n.R # English / Portuguese interface
│ ├── mod_data.R # Upload, examples, specimen aggregation, inspection
│ ├── mod_imputation.R # Zero/NA imputation
│ ├── mod_analysis.R # Ternary, biplot, variation matrix, descriptives
│ ├── mod_balances.R # SBP editor, CoDa dendrogram, balance tests
│ ├── mod_stats.R # MANOVA, pairwise tests, diagnostics
│ ├── mod_export.R # Reproducibility tab
│ └── mod_tutorial.R # Guided tour (rintrojs)
├── inst/extdata/ # Case-study example datasets
├── inst/i18n/ # Portuguese translations (UTF-8)
├── inst/logo/ # Hex sticker (SVG, PNG)
├── tests/testthat/ # Unit, module and reproducibility tests
├── vignettes/ # Getting started
├── data-raw/ # Scripts that build the examples and translations
├── dev/ # Development scripts (run_dev.R, write_manifest.R)
└── .github/workflows/ # R CMD check (3 OSes) and pkgdown site
The name joins the two fields that the package brings together: CoDa, the usual abbreviation of compositional data analysis, and stereology, the quantification of tissue structure whose volume fractions and point counts are compositions by construction. It is also a double musical homage. Coda (1982) is the ninth and final studio album by Led Zeppelin, released almost two years after the band broke up following the death of drummer John Bonham, and its title refers to the closing section of a piece of music. Soda Stereo is the band formed in Buenos Aires in 1982 by Gustavo Cerati, Zeta Bosio and Charly Alberti, regarded as a pioneer of Latin American rock. Changing a single letter turns Soda Stereo into CoDa Stereo.
The logo carries both references in its typography. "CODA" is set in
Ryga, a free display typeface with
neon-like outlined strokes, chosen as a homage to Led Zeppelin's Coda.
"STEREO" is set in Inter Bold, widely spaced, as a solid 1980s nod to Soda
Stereo. Above the name, an isometric block of tissue with cells and blood
vessels stands for the object of stereology, and its stacked bars stand both
for the parts of a composition and for the level meters of a stereo
equalizer. The package has no connection with either band, and the logo uses
none of their artwork or lyrics. The fonts are documented in
inst/logo/FONTS.md.
If you use CoDaStereo in your research, please cite both the paper and the software:
@article{provete2026codastreo,
author = {Provete, Diogo B. and Severgnini, Marcos R. and Fernandes, Carlos E. and Franco-Belussi, Lilian},
title = {A Practical Guide to using Compositional Data Analysis in Tissue Stereology and Blood Cell Profile},
journal = {Physiological Reports},
year = {2026},
note = {In review}
}
@software{provete2026codastreo_app,
author = {Provete, Diogo B.},
title = {{CoDa Stereo}: Compositional Data Analysis for Stereological Data},
year = {2026},
url = {https://github.com/diogoprov/CoDaStereo},
doi = {10.5281/zenodo.19925778},
version = {3.1.1}
}
Bug reports and feature requests are welcome via GitHub Issues. Pull requests are welcome.
MIT © Diogo B. Provete