Summarises how curated capabilities are distributed across the genomes of a community, within declared reference frames. Nothing here is curated and nothing changes a call.
Usage
community_traits(
community,
frames = NULL,
abundance = NULL,
quality = NULL,
policy = "none",
threshold = NULL,
min_confidence = NULL,
pairwise = TRUE,
pair_trace = FALSE,
db = NULL,
progress = NULL
)Arguments
- community
A community from [gifter_community()].
- frames
Optional list of [reference_frame()] objects. The default set is used if omitted: the whole catalogue, each `gift_type`, each `mode`, each resource strategy, and the bounded biomass-essential anabolic set that `community_coverage` is reported for.
- abundance
Optional named numeric vector of relative abundances over the community's genomes, named with their identifiers. Must be non-negative and not all zero.
- quality
Optional genome completeness, as a named numeric vector or a data frame with `genome_id` and `completeness` columns. Read as proportions, or as percentages when any value exceeds 1.
- policy
Assessability policy: `"none"` or `"completeness"`. See [genome_traits()].
- threshold
Completeness below which a negative call is treated as indeterminate, on the same scale as `quality`. Required by the `"completeness"` policy and has no default.
- min_confidence
Optional weakest marker confidence a positive call may rest on and still count, as in [genome_traits()]. Applied per genome, so a capability stays in the community count while any one genome evidences it above the floor. `NULL`, the default, counts every positive call.
- pairwise
Whether to report `repertoire_overlap`. `TRUE`, the default. It is the one metric that is quadratic in the community, and the only one a community of thousands of genomes cannot afford in every frame: `FALSE` drops it and leaves every other metric untouched.
- pair_trace
Whether to record, for every genome pair, the GIFTs behind its `repertoire_overlap`. `FALSE`, the default: the trace carries one row per pair per shared GIFT, which is quadratic in the community and reaches gigabytes at a few hundred genomes, and the overlap values are unchanged either way. The community, GIFT and genome traces are always recorded.
- db
Optional open gifter database connection.
- progress
Whether to display a progress bar over the reference frames. Defaults to `TRUE` at an interactive console reading more than one frame, and to `FALSE` otherwise. The display never changes a metric.
Value
A `gifter_traits` list with `metrics` and `trace`, whose `target_type` distinguishes community, GIFT, genome and genome-pair rows.
Details
Metrics reported per frame:
- `community_richness`
GIFTs supported by at least one 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
- `provider_count`, `provider_fraction`
per GIFT, the genomes supporting it, and that count over the genomes that could assess it
- `abundance_coverage`
per GIFT, the share of supplied abundance those genomes carry. Only when `abundance` was supplied
- `singleton_fraction`
represented GIFTs with exactly one provider
- `unique_contribution`
per genome, the GIFTs it alone provides
- `repertoire_overlap`
per genome pair, the Jaccard index of their supported GIFTs
Interpretation
These traits describe how genomic capability is distributed among the genomes supplied. They are not measures of ecological interaction, division of labour, cooperation or stability. Two genomes with disjoint repertoires have different repertoires; they have not been shown to be complementary. `unique_contribution` counts GIFTs no other sampled genome provides; it does not make a genome ecologically indispensable, and it moves when the sampling does.
`abundance_coverage` is the fraction of observed genome abundance carrying a capability. It is not a fraction of activity, flux, transcript production or ecological effect, which is why it never merges with `provider_count`.
Abundance
`abundance` is optional and, when supplied, is normalised to sum to one. It weights how much of the observed community a capability's carriers represent. It is not a weight on the capability: a GIFT encoded by an abundant genome is not thereby more active, more expressed or more important, which is why presence-based and abundance-weighted quantities are reported in separate rows and never combined.
Assessability
`quality`, `policy` and `threshold` decide which negative calls may enter a denominator, on the same terms as [genome_traits()], and are supplied here rather than to [gifter_community()] because they are a way of reading calls and not a property of them. Indeterminacy is resolved per genome: a fragmented member's silence is withheld from a provider count while a complete member's is not. No policy can make an unsupported GIFT supported.
Cost
Everything reported per GIFT and per genome is cheap: reading four hundred genomes within all fourteen default frames is thirteen thousand rows and a few seconds. The pair metric is the expensive one, because the pair count is quadratic in the community – four hundred genomes are eighty-seven thousand pairs, two thousand are two million – and every frame pays it again. Measured on four hundred and eighteen genomes over the default frames: 13 s and 100 MB, of which 99 thousand genomes the same reading is 93 s and 2.2 GB.
The two are separate arguments because they are separate costs. `pairwise = FALSE` drops `repertoire_overlap` and keeps every richness, provider and unique-contribution row, which is what makes a community of thousands of genomes readable within every frame. `pair_trace = TRUE` adds the GIFTs behind each overlap, one row per pair per shared GIFT: tens of millions of rows and gigabytes at a few hundred genomes, which is why it is off unless it is asked for. The overlap values themselves are the same with it or without it.
Progress
A run over several frames reports itself at an interactive console, in reference frames summarised out of frames to summarise, with an estimate of the time remaining. A frame is not a fixed quantity of work – one spanning the whole catalogue takes longer than a narrow one – so the estimate is coarser than the genome count of [evaluate_gifts_community()]. Nothing is reported when there is nobody watching, which is why a script, a knitted document and a package check stay silent unless they ask for the display with `progress = TRUE`.