Summarises the GIFT calls of a single genome into quantitative traits within declared reference frames. Nothing here is curated and nothing here changes a call: this reads the calls [evaluate_gifts()] already made, the facets that classify them, and the derived [gift_profile()] and [gift_graph()] views.
Usage
genome_traits(
result,
frames = NULL,
genome_id = "genome",
quality = NULL,
policy = "none",
threshold = NULL,
min_confidence = NULL,
db = NULL
)Arguments
- result
A result returned by [evaluate_gifts()].
- frames
Optional list of [reference_frame()] objects. A default set partitioning the catalogue by type, mode and resource strategy, plus the bounded biomass-essential anabolic frame, is used if omitted.
- genome_id
Identifier reported in the `target_id` column.
- 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 details.
- 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, one of `"ambiguous"`, `"putative"`, `"high-confidence"` or `"curated"`. A supported GIFT whose `evidence_confidence` falls below it becomes indeterminate rather than negative, because weak evidence is not evidence of absence. `NULL`, the default, counts every positive call whatever it rests on. Set it to `"high-confidence"` to exclude capabilities called from polyspecific sequence families, which is the usual reason a carbohydrate GIFT is ambiguous.
- db
Optional open gifter database connection.
Value
A `gifter_traits` list with `metrics` (one row per trait), `trace` (the GIFTs behind each trait), `frames`, and `database_version`.
Details
Metrics reported per frame:
- `gift_richness`
supported GIFTs in the frame
- `supported_fraction`
richness over assessable members, reported for bounded frames only. Over the biomass-essential anabolic frame this is biosynthetic capability coverage
- `breadth_*`
distinct values of one curated facet, one [gift_profile()] classification or one anchor facet represented by a supported GIFT
- `supported_gifts_*`
per facet value, named `supported_gifts_<facet>:<value>`, the supported GIFTs carrying it over the assessable GIFTs carrying it. Breadth counts the values a genome reaches; this counts the GIFTs it reaches them by. Reported for a value the genome reaches; a value it reaches nothing of is counted in the `breadth_*` denominator instead
- `handoff_out_degree`, `handoff_in_degree`
distinct anchors through which the genome's supported GIFTs could hand off to, or receive from, a curated GIFT. Reported only where the frame reaches the metabolic model, since anchors belong to it
- `multi_implementation_gifts`
supported GIFTs completed by more than one curated implementation
- `assessable_fraction`
members of the frame whose absence the assessability policy treats as informative
- `closed_cycles`
elementary cycles of the composition graph whose every member is supported, from [evaluate_gift_cycles()]
Where a resource comes from
`resource_origin` is curated on anchors rather than on GIFTs, and reaches the metrics split by the role the anchor plays: `input_resource_origin` for what a GIFT is declared to act on, `output_resource_origin` for what it is declared to release. Read together with `breadth_*` and `supported_gifts` they place a genome on the axis a community's resource structure runs along — a genome whose supported catabolic GIFTs enter on `plant_derived` or `host_derived` anchors opens resources that arrive from outside the community, while one entering on `microbially_derived` anchors lives on what other organisms release.
The two roles stay separate facets because consuming a microbially derived compound and releasing one are opposite positions, and one `resource_origin` count would add them together.
This is a reading of declared boundaries, not a trophic level. It says what a genome encodes the capability to act on, never what it eats, whether the resource is present, whether the genome meets it, or whether anything is expressed when it does. A trophic level is a statement about flux through a realised food web, and no arrangement of these counts is evidence of one.
Assessability
A negative call means the observed markers did not support any curated implementation. On a fragmented genome that is not the same as absence, so `policy` decides which negative calls may enter a denominator.
`"none"`, the default, declares nothing indeterminate and reproduces Boolean behaviour. `"completeness"` requires a genome completeness estimate in `quality` and an explicit `threshold`, and treats every negative call on a genome below that threshold as indeterminate, removing it from every denominator. It is deliberately blunt: gifter has no validated model of how gene content is lost from a fragmented assembly, and a finer rule would imply a precision it cannot support. There is no default threshold, because how complete a genome must be before its silence is informative is the analyst's declared choice.
No policy can make an unsupported GIFT supported. Quality informs the reading of absence and nothing else.
Interpretation
These traits count encoded capabilities in the current gifter ontology within a stated frame. They are not measures of biological complexity, metabolic versatility in an environment, growth independence, activity, flux or phenotype. `supported_fraction = 0.8` over the biomass-essential anabolic frame means four fifths of the curated biomass-essential anabolic capabilities that were assessable are genomically supported; it does not mean the organism grows without supplementation. The database is not the frame of microbial function, which is why an unbounded frame reports no fraction at all.
Under the default policy `assessable` equals the size of the frame: every member is treated as assessed, and a fragmented genome will report absences that a complete one would not. `assessable_fraction` states this in the output rather than leaving it implied.
Examples
markers <- data.frame(
gene_id = paste0("gene_", 1:9),
namespace = "KO",
accession = c(
"K00764", "K01945", "K00601", "K01952", "K01933",
"K01587", "K01756", "K00602", "K01939"
)
)
traits <- genome_traits(evaluate_gifts(markers), genome_id = "MAG_001")
subset(traits$metrics, metric_id == "gift_richness",
c("reference_frame", "value", "assessable"))
#> # A tibble: 14 × 3
#> reference_frame value assessable
#> <chr> <dbl> <int>
#> 1 all curated GIFTs 2 163
#> 2 defense GIFTs 0 7
#> 3 metabolic GIFTs 2 143
#> 4 regulatory GIFTs 0 4
#> 5 structural GIFTs 0 9
#> 6 anabolic GIFTs 2 67
#> 7 catabolic GIFTs 0 69
#> 8 interconversion GIFTs 0 4
#> 9 transport GIFTs 0 3
#> 10 GIFTs with resource strategy private 2 130
#> 11 GIFTs with resource strategy public_good 0 3
#> 12 GIFTs with resource strategy unresolved 0 7
#> 13 GIFTs with resource strategy uptake 0 3
#> 14 biomass-essential anabolic GIFTs 1 44