Quantitative traits of one genome catalogue across many samples

Reports, per sample, how curated capabilities are distributed across the genomes detected in it, within declared reference frames. Nothing is re-evaluated and nothing changes a call: the catalogue is read once, and a sample is a restriction of that reading to its detected genomes and a reweighting by their abundance.

Usage

dataset_traits(
  dataset,
  frames = NULL,
  quality = NULL,
  policy = "none",
  threshold = NULL,
  min_confidence = NULL,
  detection = 0,
  pairwise = TRUE,
  db = NULL,
  progress = NULL
)

Arguments

dataset: A dataset from [gifter_dataset()].
frames: Optional list of [reference_frame()] objects. The default set is used if omitted.
quality, policy, threshold, min_confidence: Assessability, on exactly the terms of [community_traits()]. These are properties of a genome, so they are applied once to the catalogue before any sample is read.
detection: Abundance a genome must exceed to be a member of a sample's community. `0` by default, meaning observed at all. A sample in which no genome exceeds it is refused, naming it.
pairwise: Whether to report `repertoire_overlap` and its per-sample summary. `TRUE` by default. It is the one quadratic metric, and unlike in [community_traits()] it is paid once rather than once per sample.
db: Optional open gifter database connection.
progress: Whether to display a progress bar over the reference frames. Reference frames remain the unit, because the sample loop is vectorized away.

Value

A `gifter_dataset_traits` list with `metrics`, `catalogue_metrics`, `trace`, and the metadata, detection and assessability the reading used.

Details

Metrics reported per sample per frame, in `metrics`:

`community_richness`: GIFTs supported by at least one detected genome
`community_coverage`: richness over assessable members, for bounded frames only
`mean_genome_richness`: reported beside community richness rather than divided into it, so both components stay visible
`detected_genomes`: catalogue genomes detected in this sample, over all catalogue genomes
`assessable_fraction`: members of the frame at least one detected genome could assess
`singleton_fraction`: represented GIFTs with exactly one provider
`provider_count`, `provider_fraction`: per GIFT, the detected genomes supporting it, and that count over the detected genomes that could assess it
`abundance_coverage`: per GIFT, the share of the sample's detected abundance those genomes carry
`unique_contribution`: per genome, the GIFTs it alone provides in this sample
`mean_repertoire_overlap`: the one composite; see below

Metrics reported once, in `catalogue_metrics`:

`gift_richness`: per genome, its supported GIFTs in the frame
`repertoire_overlap`: per genome pair, the Jaccard index of their supported GIFTs

Two tables, not one nullable column

A genome supports the same GIFTs in every sample it is detected in, and two genomes share the same repertoire wherever both are detected. Those rows cannot vary between samples, so they are not given a `sample_id` column that would always be empty: the absence of the column is the claim. Read either for one sample by restricting it to that sample's detected genomes, which `as.data.frame()` and [trace_sample()] both do for you.

The `assessable` column of a `catalogue_metrics` row counts what the whole catalogue could assess, since that row belongs to no sample. The metric itself — `value`, `numerator`, `denominator` — is what [community_traits()] reports for the same genome or pair in any sample.

Detection

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 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, corrects for one, or rarefies. Every sample-level richness is reported beside `detected_genomes` instead, so a richness of 40 over 31 detected genomes is not read as the same result as a richness of 40 over 207.

Abundance closure

Abundance is closed within each sample's **detected** set, after detection has been applied, so `abundance_coverage` is a share of the community actually being described. At `detection = 0` this is the same as closing over the whole catalogue; above it, it is not, and deliberately so. Once a reader has declared that a genome below the threshold is not part of the community, leaving its abundance in the denominator would report a share of a community that same reader just said does not include it.

What these numbers may not say

`abundance_coverage` is the share of observed genome abundance carrying a capability. It is not a share of activity, transcript production, flux or effect, which is why it never merges with `provider_count`. A GIFT whose carriers are more abundant in one group of samples has not been shown to be more active, more expressed or more important there.

gifter runs no hypothesis test, differential-abundance analysis, ordination or effect size between groups of samples, and interprets no metadata column. The design, the contrasts and the multiple-testing correction are the analyst's. What gifter contributes instead is an assessability-aware matrix with a declared reference frame — see [gift_matrix()] and [dataset_matrix()] — in which a genome's silence about a capability it was never well enough observed to assess is `NA` rather than a fabricated zero.

The one composite

`mean_repertoire_overlap` is a mean of ratios, so it has no count for a numerator and reports `NA` there; its denominator is the comparable pairs both of whose genomes the sample detected. It is reported because its terms stay exactly recoverable from `catalogue_metrics` and the detection set, which is a stronger guarantee than a trace table gives. It is taken over a larger pair set in a sample that detected more genomes, so two samples' means are not comparisons over the same number of pairs. `pairwise = FALSE` drops it and the pair rows together.

The trace

`trace` records the catalogue's providers: which genomes support each GIFT, per frame. Every per-sample trace is a recount over those rows restricted to the sample's detected genomes, which is what [trace_sample()] does, so per-sample rows are derivable rather than stored. This is the same reasoning as the `pair_trace = FALSE` default of [community_traits()]: the rows are identical either way, and what is at stake is only whether a multiple of them is carried around by default.