Returns one minus the Jaccard index of every pair of genomes' supported GIFTs, as a [stats::dist] object, so that a repertoire can be handed to `hclust()`, `cmdscale()`, `vegan::adonis2()` or any other routine that takes a distance.
Arguments
- x
A `gifter_community` or a `gifter_dataset`. A dataset delegates to its catalogue: a pair of genomes shares what it shares in every sample both are detected in, so the distance carries no `sample_id`.
- frame
Optional [reference_frame()] restricting which GIFTs the repertoires are compared over. Omitted, every GIFT the evaluation produced is compared. Stratifying matters here: the catalogue is overwhelmingly metabolic, so an unstratified distance is a metabolic distance under a general name.
- min_confidence
Optional weakest marker confidence a positive call may rest on and still enter a repertoire, as in [community_traits()]. `NULL`, the default, compares every positive call whatever it rests on.
Value
A [stats::dist] over the genomes, carrying `reference_frame`, `database_version` and `min_confidence` attributes.
Details
The values are the `repertoire_overlap` of [community_traits()], subtracted from one. Computing them here does not require the traits to have been computed, and the two agree exactly.
What gifter does not do with it
gifter returns the distance and stops. It fits no clustering, chooses no linkage, cuts no tree and names no groups, because the linkage, the cut and the number of groups are the analyst's choices and gifter cannot defend any of them from the calls.
Nor are the groups that a clustering finds guilds. A guild is a set of organisms exploiting a resource in the same way, which is a claim about resource use where the organisms live. Two genomes near each other here encode similar capabilities; they have not been shown to use the same resource, to use it in the same way, or to co-occur.
Why there is no assessability policy here
A Jaccard index reads supported sets. A GIFT a genome does not support is outside its set whether the call was a confident negative or an indeterminate one, so `policy`, `quality` and `threshold` cannot move this distance and are not accepted: an argument that does nothing is worse than one that is absent, because a reader assumes it worked.
`min_confidence` is accepted, because it does move the distance. It removes a positive call from the supported set when the evidence behind it is too weak, and the set is what is being compared.
Pairs with no distance
Two genomes that support nothing in the frame have no overlap to measure rather than an overlap of zero, so their distance is `NA`. Reporting `1` would say they were compared and found to share nothing.
See also
[gift_matrix()] for the calls the distance is computed from, and [community_traits()], which reports the same overlaps per pair beside the GIFTs behind them.
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"
))
community <- gifter_community(donor = donor, recipient = recipient)
repertoire_distance(community)
#> donor
#> recipient NA