A quantitative trait is only interpretable relative to the set of GIFTs that could have been called, so every metric [genome_traits()] reports names the frame it was computed in. This function builds one from curated metadata.
Usage
reference_frame(
type = NULL,
mode = NULL,
facet = NULL,
value = NULL,
resource_strategy = NULL,
auxotrophy_indicator = NULL,
status = NULL,
bounded = FALSE,
label = NULL,
db = NULL,
preset = NULL
)Arguments
- type
Optional GIFT type: `"metabolic"`, `"structural"`, `"regulatory"` or `"defense"`.
- mode
Optional metabolic mode: `"anabolic"`, `"catabolic"`, `"transport"` or `"interconversion"`.
- facet
Optional registered facet name, such as `"substrate_class"`.
- value
Optional facet values. Requires `facet`.
- resource_strategy
Optional [gift_profile()] resource strategy.
- auxotrophy_indicator
Optional logical. `TRUE` selects the anabolic GIFTs whose declared output is a biomass-essential anchor.
- status
Optional curation status filter.
- bounded
Whether the denominator is biologically meaningful. See details.
- label
Optional human-readable name. Derived from the filters if omitted.
- db
Optional open gifter database connection.
- preset
Optional identifier from [list_reference_frames()]. A preset supplies its versioned filters, label, interpretation and boundedness. Direct filters cannot be combined with a preset. `label` may override its display label, but an unbounded preset cannot be promoted with `bounded`.
Value
A `gifter_frame`: the member `gift_id`s, the `label`, the filters that produced it, whether it is `bounded`, and the `database_version` it was resolved against. Preset frames also carry their identifier, description, interpretation limits and recommended metrics.
Details
Filters combine with AND. `facet` and `value` read the registered facet vocabulary; `resource_strategy` and `auxotrophy_indicator` read the derived [gift_profile()] view, which covers metabolic GIFTs only, so either of them bounds the frame to that type by construction.
Bounded frames
`bounded` declares that the frame enumerates a biologically closed set that curation intends to cover completely, so the fraction of it a genome supports is a meaningful quantity. The curated biomass-essential anabolic capabilities are such a set. "All metabolic GIFTs" is not: the catalogue is open and growing, and a genome supporting 12 of 122 has not been shown to lack 110 capabilities. [genome_traits()] reports `supported_fraction` for bounded frames and withholds it otherwise, which is why the flag is a biological claim rather than a formatting option. It defaults to `FALSE`.
Examples
frame <- reference_frame(mode = "anabolic", auxotrophy_indicator = TRUE,
bounded = TRUE, label = "biomass-essential anabolic")
length(frame$gift_id)
#> [1] 44
carbohydrate <- reference_frame(preset = "carbohydrate_degradation")
carbohydrate$gift_id
#> [1] "arabinose_degradation" "arabinoxylan_debranching"
#> [3] "chitin_degradation" "fucose_degradation_isomerase"
#> [5] "galactose_degradation_leloir" "galacturonate_degradation"
#> [7] "glcnac_degradation" "glucuronate_degradation"
#> [9] "mucin_fucose_release" "mucin_galnac_release"
#> [11] "mucin_sialic_acid_release" "neuac_degradation"
#> [13] "pectate_lyase_degradation" "pectin_degradation"
#> [15] "rhamnose_degradation" "starch_degradation"
#> [17] "xylan_degradation" "xylose_degradation_isomerase"