recipe() accepts a phyloseq or
TreeSummarizedExperiment object. These containers connect
an abundance matrix to sample metadata and, when available, taxonomy.
Import files with the tools supplied by phyloseq or
mia, then inspect the resulting object before configuring
an analysis.
Importing data does not establish that their units, experimental design or taxonomic annotations are appropriate for a particular differential-abundance method.
The package includes metaHIV_phy, with its recorded
sample metadata and taxonomy. No statistical model is needed to inspect
the data or define preprocessing steps.
library(dar)
data("metaHIV_phy", package = "dar")
rec <- recipe(metaHIV_phy)
rec
#> ── DAR Recipe ──────────────────────────────────────────────────────────────────
#> Inputs:
#>
#> ℹ phyloseq object with 451 taxa and 156 samples
#> ✖ undefined analysis target. Use add_model() to define the analysis!
#> ✖ undefined taxonomic level. Use add_model() to define the analysis!recipe() also accepts a phyloseq object
whose stored abundance matrix has samples in rows: the accessors below
return one consistent orientation. When constructing your own
phyloseq object, set taxa_are_rows to match
the actual matrix, rather than changing this flag without transposing
the data.
Use the dar accessors explicitly when other attached packages export functions with the same names.
samples <- dar::sample_data(rec)
taxonomy <- dar::tax_table(rec)
abundances <- dar::otu_table(rec)
head(samples[c("sample_id", "RiskGroup2")])
#> # A tibble: 6 × 2
#> sample_id RiskGroup2
#> <chr> <chr>
#> 1 Sample_186 msm
#> 2 Sample_185 msm
#> 3 Sample_184 hts
#> 4 Sample_182 pwid
#> 5 Sample_181 msm
#> 6 Sample_170 msm
head(taxonomy)
#> # A tibble: 6 × 8
#> taxa_id Kingdom Phylum Class Order Family Genus Species
#> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 Otu_1 Archaea Euryarchaeota Methanobacteria Methanob… Metha… Meth… Methan…
#> 2 Otu_2 Archaea Euryarchaeota Methanobacteria Methanob… Metha… Meth… Methan…
#> 3 Otu_3 Bacteria Actinobacteria Actinobacteria Actinomy… Actin… Acti… Actino…
#> 4 Otu_4 Bacteria Actinobacteria Actinobacteria Actinomy… Actin… Acti… Actino…
#> 5 Otu_5 Bacteria Actinobacteria Actinobacteria Actinomy… Actin… Acti… Actino…
#> 6 Otu_6 Bacteria Actinobacteria Actinobacteria Actinomy… Actin… Acti… Actino…
abundances[seq_len(6), seq_len(5)]
#> # A tibble: 6 × 5
#> taxa_id Sample_186 Sample_185 Sample_184 Sample_182
#> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 Otu_1 2538 0 9026 12049
#> 2 Otu_2 0 0 0 609
#> 3 Otu_3 0 0 0 0
#> 4 Otu_4 0 0 0 0
#> 5 Otu_5 0 0 0 0
#> 6 Otu_6 0 0 0 0The accessors expose the complete stored components, independently of
the target or taxonomic rank later selected with
add_model():
sample_data() returns sample_id followed
by all sample metadata columns, in phyloseq::sample_names()
order.tax_table() returns taxa_id followed by
all taxonomic ranks, in phyloseq::taxa_names() order.otu_table() returns one row per taxon, with
taxa_id first and one column per sample. Taxon and sample
order match the other two accessors.stopifnot(
identical(colnames(abundances)[-1], samples$sample_id),
identical(abundances$taxa_id, taxonomy$taxa_id)
)Keep sample and taxon identifiers unique and consistent across input
files. Taxonomic labels are annotations, not replacements for feature
identifiers: several features can share a species name. Inspect missing
annotations and use standard rank names such as Kingdom,
Genus and Species.
If metadata or taxonomy is absent, the corresponding accessor returns
an ID-only tibble. That is sufficient for inspection, but it does not
supply the real covariates or taxonomic rank needed by a model. Add
genuine study metadata before calling add_model(); do not
manufacture groups just to make an example run.
This example uses a file distributed with phyloseq,
without downloading data. The importer reads the sample metadata already
present in that file.
biom_file <- system.file(
"extdata", "rich_dense_otu_table.biom", package = "phyloseq"
)
phy <- phyloseq::import_biom(
biom_file,
parseFunction = phyloseq::parse_taxonomy_greengenes
)
biom_rec <- recipe(phy)
head(dar::sample_data(biom_rec))
#> # A tibble: 6 × 5
#> sample_id BarcodeSequence LinkerPrimerSequence BODY_SITE Description
#> <chr> <chr> <chr> <chr> <chr>
#> 1 Sample1 CGCTTATCGAGA CATGCTGCCTCCCGTAGGAGT gut human gut
#> 2 Sample2 CATACCAGTAGC CATGCTGCCTCCCGTAGGAGT gut human gut
#> 3 Sample3 CTCTCTACCTGT CATGCTGCCTCCCGTAGGAGT gut human gut
#> 4 Sample4 CTCTCGGCCTGT CATGCTGCCTCCCGTAGGAGT skin human skin
#> 5 Sample5 CTCTCTACCAAT CATGCTGCCTCCCGTAGGAGT skin human skin
#> 6 Sample6 CTAACTACCAAT CATGCTGCCTCCCGTAGGAGT skin human skin
head(dar::tax_table(biom_rec))
#> # A tibble: 5 × 8
#> taxa_id Kingdom Phylum Class Order Family Genus Species
#> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 GG_OTU_1 Bacteria Proteobacteria Gammaproteobacter… Ente… Enter… Esch… <NA>
#> 2 GG_OTU_2 Bacteria Cyanobacteria Nostocophycideae Nost… Nosto… Doli… <NA>
#> 3 GG_OTU_3 Archaea Euryarchaeota Methanomicrobia Meth… Metha… Meth… <NA>
#> 4 GG_OTU_4 Bacteria Firmicutes Clostridia Hala… Halan… Hala… Halana…
#> 5 GG_OTU_5 Bacteria Proteobacteria Gammaproteobacter… Ente… Enter… Esch… <NA>The same file can be imported as a
TreeSummarizedExperiment. Rows of a TSE represent features,
columns represent samples, rowData() holds feature
annotations and colData() holds sample metadata.
tse <- mia::importBIOM(biom_file)
# This bundled example contains these seven ranks, in this order.
colnames(SummarizedExperiment::rowData(tse)) <- c(
"Kingdom", "Phylum", "Class", "Order", "Family", "Genus", "Species"
)
tse_rec <- recipe(tse)
head(dar::tax_table(tse_rec))
#> # A tibble: 5 × 8
#> taxa_id Kingdom Phylum Class Order Family Genus Species
#> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 GG_OTU_1 k__Bacteria p__Proteobacteria c__Gammapro… o__E… f__En… g__E… s__
#> 2 GG_OTU_2 k__Bacteria p__Cyanobacteria c__Nostocop… o__N… f__No… g__D… s__
#> 3 GG_OTU_3 k__Archaea p__Euryarchaeota c__Methanom… o__M… f__Me… g__M… s__
#> 4 GG_OTU_4 k__Bacteria p__Firmicutes c__Clostrid… o__H… f__Ha… g__H… s__Hal…
#> 5 GG_OTU_5 k__Bacteria p__Proteobacteria c__Gammapro… o__E… f__En… g__E… s__The rank relabeling above is specific to this file. Inspect the
annotations in your own data instead of assigning rank names by position
without checking their meaning. A TSE input is converted internally to
phyloseq; if the intended abundance table is not the
default assay, select it explicitly with
mia::convertToPhyloseq(..., assay.type = "your_assay")
before creating the recipe.
For other formats, consult the importers’ documentation rather than treating all formats as equivalent:
phyloseq::import_qiime() reads legacy QIIME tables;
mia::importQIIME2() reads QIIME 2 artifacts.phyloseq::import_mothur() and
mia::importMothur() read the supported mothur files.mia::importMetaPhlAn() reads MetaPhlAn abundance
profiles.For example, open the installed help with
help("importQIIME2", package = "mia") or
help("import_biom", package = "phyloseq").
An abundance matrix can contain raw read counts, proportions, percentages or other transformed values. These are not interchangeable inputs. In particular, MetaPhlAn relative-abundance profiles are not raw read counts. Neither importing them nor converting their container makes them suitable for a count-based model; rounding percentages does not recover read counts.
Check the provenance and assay units, not just whether values happen to be integers. Retain raw counts when they are available and choose a method whose input requirements match the measurements. Missing values are also distinct from observed zeros.
For QC and filtering, continue with Quality control and preprocessing. For formulas, target variables and engine compatibility, see Statistical models and contrasts.
sessionInfo()
#> R version 4.6.1 (2026-06-24)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 24.04.5 LTS
#>
#> Matrix products: default
#> BLAS: /home/biocbuild/bbs-3.24-bioc/R/lib/libRblas.so
#> LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.12.0 LAPACK version 3.12.0
#>
#> locale:
#> [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
#> [3] LC_TIME=en_GB LC_COLLATE=C
#> [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: America/New_York
#> tzcode source: system (glibc)
#>
#> attached base packages:
#> [1] stats graphics grDevices utils datasets methods base
#>
#> other attached packages:
#> [1] dar_1.99.0
#>
#> loaded via a namespace (and not attached):
#> [1] RColorBrewer_1.1-3 jsonlite_2.0.0
#> [3] MultiAssayExperiment_1.39.1 magrittr_2.0.5
#> [5] TH.data_1.1-5 ggbeeswarm_0.7.3
#> [7] farver_2.1.2 rmarkdown_2.32
#> [9] fs_2.1.0 vctrs_0.7.3
#> [11] multtest_2.69.0 DelayedMatrixStats_1.35.0
#> [13] SQUAREM_2026.1 mixsqp_0.3-54
#> [15] htmltools_0.5.9 S4Arrays_1.13.2
#> [17] BiocNeighbors_2.7.3 truncnorm_1.0-9
#> [19] SparseArray_1.13.4 sass_0.4.10
#> [21] bslib_0.12.0 sandwich_3.1-3
#> [23] plyr_1.8.9 DECIPHER_3.9.5
#> [25] zoo_1.9-1 cachem_1.1.0
#> [27] igraph_2.3.4 lifecycle_1.0.5
#> [29] iterators_1.0.14 pkgconfig_2.0.3
#> [31] rsvd_2.0.0 Matrix_1.7-6
#> [33] R6_2.6.1 fastmap_1.2.0
#> [35] collapse_2.1.9 rbibutils_2.4.1
#> [37] MatrixGenerics_1.25.0 digest_0.6.39
#> [39] S4Vectors_0.51.10 DESeq2_1.53.7
#> [41] scater_1.41.3 irlba_2.4.1
#> [43] GenomicRanges_1.65.4 vegan_2.7-6
#> [45] beachmat_2.29.3 labeling_0.4.3
#> [47] invgamma_1.2 TreeSummarizedExperiment_2.21.0
#> [49] abind_1.4-8 mgcv_1.9-5
#> [51] compiler_4.6.1 withr_3.0.3
#> [53] S7_0.2.2 backports_1.5.1
#> [55] BiocParallel_1.47.0 viridis_0.6.5
#> [57] DBI_1.3.0 MASS_7.3-66
#> [59] rappdirs_0.3.4 DelayedArray_0.39.8
#> [61] biomformat_1.41.0 bluster_1.23.1
#> [63] permute_0.10-0 optparse_1.8.2
#> [65] tools_4.6.1 vipor_0.4.7
#> [67] otel_0.3.0 beeswarm_0.4.0
#> [69] ape_5.8-1 glue_1.8.1
#> [71] nlme_3.1-172 grid_4.6.1
#> [73] Rtsne_0.17 checkmate_2.3.4
#> [75] mia_1.21.30 cluster_2.1.8.3
#> [77] reshape2_1.4.5 ade4_1.7-24
#> [79] generics_0.1.4 microbiome_1.35.2
#> [81] gtable_0.3.6 tidyr_1.3.2
#> [83] data.table_1.18.6.1 utf8_1.2.6
#> [85] BiocSingular_1.29.2 ScaledMatrix_1.21.0
#> [87] XVector_0.53.0 BiocGenerics_0.59.13
#> [89] ggrepel_0.9.8 foreach_1.5.2
#> [91] pillar_1.11.1 stringr_1.6.0
#> [93] yulab.utils_0.2.5 splines_4.6.1
#> [95] dplyr_1.2.1 maaslin3_1.5.7
#> [97] treeio_1.37.1 lattice_0.23-1
#> [99] survival_3.8-12 tidyselect_1.2.1
#> [101] DirichletMultinomial_1.55.1 SingleCellExperiment_1.35.2
#> [103] locfit_1.5-9.12 Biostrings_2.81.9
#> [105] scuttle_1.23.2 knitr_1.52
#> [107] reformulas_0.4.4 gridExtra_2.3.1
#> [109] phyloseq_1.57.0 IRanges_2.47.5
#> [111] Seqinfo_1.3.2 SummarizedExperiment_1.43.0
#> [113] stats4_4.6.1 xfun_0.62
#> [115] Biobase_2.73.2 matrixStats_1.5.0
#> [117] stringi_1.8.9 lazyeval_0.2.3
#> [119] yaml_2.3.12 evaluate_1.0.5
#> [121] codetools_0.2-20 tibble_3.3.1
#> [123] cli_3.6.6 Rdpack_2.6.6
#> [125] jquerylib_0.1.4 mirai_2.7.4
#> [127] dichromat_2.0-1 Rcpp_1.1.2
#> [129] nanonext_1.10.4 parallel_4.6.1
#> [131] ggplot2_4.0.3 sparseMatrixStats_1.25.0
#> [133] mvtnorm_1.4-2 decontam_1.33.0
#> [135] viridisLite_0.4.3 tidytree_0.4.8
#> [137] scales_1.4.0 purrr_1.2.2
#> [139] crayon_1.5.3 rlang_1.3.0
#> [141] multcomp_1.4-32 ashr_2.2-63