Struct hpo::stats::Linkage

pub struct Linkage<'a> { /* private fields */ }

Linkage matrices from HpoSets

Crate a linkage matrix from a list of HpoSets to use in dendograms or other hierarchical cluster analyses

Provided algorithms for clustering

• Linkage::union: Create a new HpoSet for each cluster based on the union of both combined clusters. This method becomes slow with growing input data
• Linkage::single: The minimum distance of each cluster’s nodes to the other nodes is used as distance for newly formed clusters. This is also known as the Nearest Point Algorithm.
• Linkage::complete: The maximum distance of each cluster’s nodes to the other nodes is used as distance for newly formed clusters. This is also known by the Farthest Point Algorithm or Voor Hees Algorithm.
• Linkage::average: The mean distance of each cluster’s nodes to the other nodes is used as distance for newly formed clusters. This is also called the UPGMA algorithm.

Examples

use hpo::Ontology;
use hpo::HpoSet;
use hpo::similarity::GroupSimilarity;
use hpo::utils::Combinations;
use hpo::stats::Linkage;

// This method can and should utilize parallel processing, e.g.
// using rayon iterators
fn distance(combs: Combinations<HpoSet<'_>>) -> Vec<f32> {
    let sim = GroupSimilarity::default();
    combs.map(|comp| {
        1.0 - sim.calculate(comp.0, comp.1)
    }).collect()
}

let ontology = Ontology::from_binary("tests/example.hpo").unwrap();
let sets = vec![
    ontology.gene_by_name("GBA1").unwrap().to_hpo_set(&ontology),
    ontology.gene_by_name("BRCA2").unwrap().to_hpo_set(&ontology),
    ontology.gene_by_name("EZH2").unwrap().to_hpo_set(&ontology),
    ontology.gene_by_name("DMD").unwrap().to_hpo_set(&ontology),
];


let mut cluster = Linkage::union(sets, distance).into_cluster();
let first = cluster.next().unwrap();
println!("{:?}", first);
// Cluster { idx1: 0, idx2: 3, distance: 0.008127391, size: 2 }
assert_eq!(cluster.next().unwrap().len(), 3);
assert_eq!(cluster.next().unwrap().len(), 4);
assert!(cluster.next().is_none());

Implementations

impl<'a> Linkage<'a>

pub fn union<T, F>(sets: T, distance: F) -> Self

where T: IntoIterator<Item = HpoSet<'a>>, F: Fn(Combinations<'_, HpoSet<'_>>) -> Vec<f32>,

Performs union-based hierarchical clustering of HpoSets

In each iteration, HpoSets are compared to each other based on the provided distance function. Clusters are formed by combining the 2 closest HpoSets into a single set (forming the union).

This method becomes exponentially slower with larger lists of sets, because it merges sets and calculates pairwise similarities for each term in each set.

Examples

use hpo::Ontology;
use hpo::HpoSet;
use hpo::similarity::GroupSimilarity;
use hpo::utils::Combinations;
use hpo::stats::Linkage;

// This method can and should utilize parallel processing, e.g.
// using rayon iterators
fn distance(combs: Combinations<HpoSet<'_>>) -> Vec<f32> {
    let sim = GroupSimilarity::default();
    combs.map(|comp| {
        1.0 - sim.calculate(comp.0, comp.1)
    }).collect()
}

let ontology = Ontology::from_binary("tests/example.hpo").unwrap();
let sets = vec![
    ontology.gene_by_name("GBA1").unwrap().to_hpo_set(&ontology),
    ontology.gene_by_name("BRCA2").unwrap().to_hpo_set(&ontology),
    ontology.gene_by_name("EZH2").unwrap().to_hpo_set(&ontology),
    ontology.gene_by_name("DMD").unwrap().to_hpo_set(&ontology),
];


let mut cluster = Linkage::union(sets, distance).into_cluster();
let first = cluster.next().unwrap();
println!("{:?}", first);
// Cluster { idx1: 0, idx2: 3, distance: 0.008127391, size: 2 }
assert_eq!(cluster.next().unwrap().len(), 3);
assert_eq!(cluster.next().unwrap().len(), 4);
assert!(cluster.next().is_none());

pub fn single<T, F>(sets: T, distance: F) -> Self

where T: IntoIterator<Item = HpoSet<'a>>, F: Fn(Combinations<'_, HpoSet<'_>>) -> Vec<f32>,

Performs single-hierarchical clustering of HpoSets

HpoSets are compared to each other based on the provided distance function. Clusters are formed by using the minimum distance of each encompassing set to the comparison set. This is also known as the Nearest Point Algorithm.

Examples

use hpo::Ontology;
use hpo::HpoSet;
use hpo::similarity::GroupSimilarity;
use hpo::utils::Combinations;
use hpo::stats::Linkage;

// This method can and should utilize parallel processing, e.g.
// using rayon iterators
fn distance(combs: Combinations<HpoSet<'_>>) -> Vec<f32> {
    let sim = GroupSimilarity::default();
    combs.map(|comp| {
        1.0 - sim.calculate(comp.0, comp.1)
    }).collect()
}

let ontology = Ontology::from_binary("tests/example.hpo").unwrap();
let sets = vec![
    ontology.gene_by_name("GBA1").unwrap().to_hpo_set(&ontology),
    ontology.gene_by_name("BRCA2").unwrap().to_hpo_set(&ontology),
    ontology.gene_by_name("EZH2").unwrap().to_hpo_set(&ontology),
    ontology.gene_by_name("DMD").unwrap().to_hpo_set(&ontology),
];


let mut cluster = Linkage::single(sets, distance).into_cluster();
let first = cluster.next().unwrap();
println!("{:?}", first);
// Cluster { idx1: 0, idx2: 3, distance: 0.008127391, size: 2 }
assert_eq!(cluster.next().unwrap().len(), 3);
assert_eq!(cluster.next().unwrap().len(), 4);
assert!(cluster.next().is_none());

pub fn complete<T, F>(sets: T, distance: F) -> Self

where T: IntoIterator<Item = HpoSet<'a>>, F: Fn(Combinations<'_, HpoSet<'_>>) -> Vec<f32>,

Performs complete-hierarchical clustering of HpoSets

HpoSets are compared to each other based on the provided distance function. Clusters are formed by using the maximum distance of each encompassing set to the comparison set. This is also known by the Farthest Point Algorithm or Voor Hees Algorithm.

pub fn average<T, F>(sets: T, distance: F) -> Self

where T: IntoIterator<Item = HpoSet<'a>>, F: Fn(Combinations<'_, HpoSet<'_>>) -> Vec<f32>,

Performs average-hierarchical clustering of HpoSets

HpoSets are compared to each other based on the provided distance function. Clusters are formed by using the average distance of both encompassing sets to the comparison set. This is also called the UPGMA algorithm.

Note

This method is not implemented completely correct. Instead of calculating the average of all distances, it only uses the mean distance of all direct cluster nodes.

pub fn cluster(&self) -> Iter<'_>

Returns an Iterator of Cluster references

pub fn into_cluster(self) -> IntoIter

Returns an Iterator of owned Cluster

pub fn indicies(&self) -> Vec<usize>

Returns the order of the input set items in the final cluster

Examples

use hpo::Ontology;
use hpo::HpoSet;
use hpo::similarity::GroupSimilarity;
use hpo::utils::Combinations;
use hpo::stats::Linkage;

// This method can and should utilize parallel processing, e.g.
// using rayon iterators
fn distance(combs: Combinations<HpoSet<'_>>) -> Vec<f32> {
    let sim = GroupSimilarity::default();
    combs.map(|comp| {
        1.0 - sim.calculate(comp.0, comp.1)
    }).collect()
}

let ontology = Ontology::from_binary("tests/example.hpo").unwrap();

let genes = vec!["GBA1", "BRCA2", "EZH2", "DMD"];
let sets = genes.iter().map(|gene| ontology.gene_by_name(gene).unwrap().to_hpo_set(&ontology));

let linkage = Linkage::union(sets, distance);
let indicies = linkage.indicies();
assert_eq!(indicies, vec![0usize, 3usize, 2usize, 1usize]);
for idx in indicies {
   print!("{} ", genes[idx]);
}
// "GBA1 DMD EZH2 BRCA2"

pub fn iter(&self) -> Iter<'_>

Returns an Iterator of Cluster references

Trait Implementations

impl<'a> IntoIterator for &'a Linkage<'a>

type Item = &'a Cluster

The type of the elements being iterated over.

type IntoIter = Iter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl IntoIterator for Linkage<'_>

type Item = Cluster

The type of the elements being iterated over.

type IntoIter = IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.