Binds an evaluated genome catalogue to a genome by sample abundance matrix, so that quantitative traits can be reported per sample without evaluating any genome more than once. Nothing is re-evaluated and nothing changes a call: a call is a property of a genome, and across a dataset only which genomes are members of a sample and how much of it they represent can vary.
Arguments
- catalogue
A `gifter_community` from [gifter_community()] or [evaluate_gifts_community()], holding every genome the samples were mapped against.
- abundance
A genome by sample numeric matrix carrying genome identifiers in its row names and sample identifiers in its column names, or a long data frame with `sample_id`, `genome_id` and `abundance` columns. The long form must carry a row for every genome in every sample: an absent row and an abundance of zero are indistinguishable after the pivot, so gifter refuses to read one as the other. Values must be finite and non-negative, the genomes must be exactly the catalogue's, and no sample may be entirely zero.
- metadata
Optional data frame with a `sample_id` column covering exactly the samples `abundance` names. Every other column is carried through untouched and interpreted by nothing in gifter.
Value
A `gifter_dataset` list holding the catalogue, the genome and sample identifiers, the abundance matrix as supplied, the metadata and the `database_version`.
Detection is to samples what assessability is to genomes
Both may only move denominators. Assessability decides whether a genome's silence about a GIFT is informative; detection decides whether a genome is part of a sample's community at all. Neither may promote an unsupported GIFT to supported, neither may change a call, and both are resolved per genome.
A detection threshold is therefore a way of reading an abundance rather than a property of one, and is supplied to the readers — [dataset_traits()], [sample_community()] — rather than here, on exactly the terms that put `threshold` on [community_traits()] rather than on [gifter_community()]. One dataset can then be read at two thresholds without being rebuilt.
What a dataset does not hold
A dataset holds membership evidence and weights. It holds no detection threshold, no assessability policy, no completeness table, no confidence floor, and no group label, design or hypothesis. The first four are readings and belong to [dataset_traits()]. The last three are the analyst's: gifter carries metadata columns through untouched and interprets none of them, and runs no test, ordination or effect size between groups of samples.
Absence below detection
A genome absent from a sample may be below detection rather than genuinely absent, and gifter models no sequencing depth, library size or detection limit. Nothing here imputes one. [dataset_traits()] reports `detected_genomes` beside every sample-level richness instead, so that a richness of 40 over 31 detected genomes is not read as the same result as a richness of 40 over 207.
Examples
donor <- evaluate_gifts(data.frame(
gene_id = "g1", namespace = "KO", accession = "K01198"
))
recipient <- evaluate_gifts(data.frame(
gene_id = "g1", namespace = "KO", accession = "K01805"
))
catalogue <- gifter_community(donor = donor, recipient = recipient)
abundance <- matrix(
c(0.7, 0.3, 0.2, 0.8), nrow = 2,
dimnames = list(c("donor", "recipient"), c("gut", "soil"))
)
dataset <- gifter_dataset(catalogue, abundance)
sample_id(dataset)
#> [1] "gut" "soil"