bixverse-rs 0.7.0

A Rust library with various utilities for computational biology and single cell.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

//! Implementation of the tied diffusion method from Paull, et al.,
//! Bioinformatics, 2013

#![allow(dead_code)]

use rayon::prelude::*;
use std::sync::Arc;

use crate::graph::graph_structures::graph_from_strings;
use crate::graph::page_rank::*;
use crate::prelude::BixverseFloat;

///////////
// Enums //
///////////

/// Enum for the TiedSumType types
#[derive(Clone, Debug, Default)]
pub enum TiedSumType {
    /// Minimum between the two diffusion vectors
    #[default]
    Min,
    /// Maximum between the two diffusion vectors
    Max,
    /// Average between the two diffusion vectors
    Avg,
}

/// Parsing the tied summarisation types
///
/// ### Params
///
/// * `s` - The string that defines the tied summarisation type
///
/// ### Results
///
/// The `TiedSumType` defining the tied summarisation type
pub fn parse_tied_sum(s: &str) -> Option<TiedSumType> {
    match s.to_lowercase().as_str() {
        "max" => Some(TiedSumType::Max),
        "min" => Some(TiedSumType::Min),
        "mean" => Some(TiedSumType::Avg),
        _ => None,
    }
}

////////////////////
// Main functions //
////////////////////

/// Calculates the tied diffusion between two graphs
///
/// Function is designed to handle permutations of the personalisation vectors
/// and leverages parallel processing for efficiency.
///
/// ### Params
///
/// * `node_names` - The names of the nodes in the graph
/// * `from` - The source nodes of the edges in the graph
/// * `to` - The destination nodes of the edges in the graph
/// * `weights` - The weights of the edges in the graph
/// * `summarisation_fun` - The function used to summarise the personalisation
///   vectors (i.e., the tied diffusion)
/// * `personalise_vecs_1` - The personalisation vectors for the first graph
/// * `personalise_vecs_2` - The personalisation vectors for the second graph
/// * `undirected` - Whether the graph is undirected
/// * `damping_factor` - PageRank damping factor, i.e. the probability of
///   continuing the walk
/// * `max_iter` - Maximum number of power iterations
/// * `tol` - Convergence threshold on the L1 change between iterations
///
/// ### Returns
///
/// * `Vec<Vec<T>>` - The tied diffusion between the two graphs for all of the
///   supplied personalisation vectors
#[allow(clippy::too_many_arguments)]
pub fn tied_diffusion_parallel<T>(
    node_names: Vec<String>,
    from: Vec<String>,
    to: Vec<String>,
    weights: Option<&[T]>,
    summarisation_fun: String,
    personalise_vecs_1: &[Vec<T>],
    personalise_vecs_2: &[Vec<T>],
    undirected: bool,
    damping_factor: T,
    max_iter: usize,
    tol: T,
) -> Vec<Vec<T>>
where
    T: BixverseFloat + std::iter::Sum,
{
    let summarisation_type: TiedSumType = parse_tied_sum(&summarisation_fun).unwrap();
    let graph_1 = graph_from_strings(&node_names, &from, &to, weights, undirected);

    // For tied diffusion in the directed case, the directionality is reversed
    let graph_2 = if !undirected {
        graph_from_strings(&node_names, &to, &from, weights, undirected)
    } else {
        graph_from_strings(&node_names, &from, &to, weights, undirected)
    };

    let half = T::from_f64(0.5).unwrap();

    // Pre-process graph once
    let pagerank_graph_1 = Arc::new(PageRankGraph::from_petgraph(graph_1));
    let pagerank_graph_2 = Arc::new(PageRankGraph::from_petgraph(graph_2));

    let tied_res: Vec<Vec<T>> = personalise_vecs_1
        .into_par_iter()
        .zip(personalise_vecs_2.into_par_iter())
        .map_init(
            || (PageRankWorkingMemory::new(), PageRankWorkingMemory::new()),
            |(working_mem1, working_mem2), (diff1, diff2)| {
                let pr1 = personalised_page_rank_optimised(
                    &pagerank_graph_1,
                    damping_factor,
                    diff1,
                    max_iter,
                    tol,
                    working_mem1,
                );
                let pr2 = personalised_page_rank_optimised(
                    &pagerank_graph_2,
                    damping_factor,
                    diff2,
                    max_iter,
                    tol,
                    working_mem2,
                );

                pr1.iter()
                    .zip(pr2.iter())
                    .map(|(&v1, &v2)| match summarisation_type {
                        TiedSumType::Max => v1.max(v2),
                        TiedSumType::Min => v1.min(v2),
                        TiedSumType::Avg => (v1 + v2) * half, // multiplication is faster
                    })
                    .collect()
            },
        )
        .collect();

    tied_res
}