zoe 0.0.31

A nightly library for viral genomics
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
146
147
148

//! Structs and algorithms for profile Hidden Markov Models (pHMMs).
//!
//! ## Log Space Parameters
//!
//! Internally, *Zoe* stores pHMM parameters in log space with $-\ln(\cdot)$.
//! This allows for algorithms to be performed in a numerically stable manner,
//! while also avoiding repeated logarithm computations.
//!
//! When the input model is probabilistic (so that all parameters are in
//! `0..=1`), this will result in stored parameters in `0..=INFINITY`. *Zoe*
//! does not currently provide functionality for parameters outside of this
//! range ([`SamHmmParser`] will return an error). If this is required
//! functionality, please raise an issue (supporting it will require more
//! careful handling of NaNs and negative infinity values).
//!
//! [`SamHmmParser`]: sam_parser::SamHmmParser

use crate::math::{CastAs, CastAsNumeric, CastFrom, CastFromNumeric, Float};
use std::{
    fmt::Display,
    ops::{Add, AddAssign, Mul},
};

mod errors;
mod models;
pub mod modules;
pub mod sam_parser;
pub(crate) mod state;
mod traits;
mod viterbi;

#[cfg(feature = "alignment-diagnostics")]
pub mod editing;

#[cfg(not(feature = "alignment-diagnostics"))]
#[doc(auto_cfg(hide(feature, values("alignment-diagnostics"))))]
pub(crate) mod indexing;
#[cfg(feature = "alignment-diagnostics")]
pub mod indexing;

#[cfg(feature = "alignment-diagnostics")]
pub mod score_from_path;

#[cfg(not(feature = "alignment-diagnostics"))]
#[doc(auto_cfg(hide(feature, values("alignment-diagnostics"))))]
pub(crate) mod views;
#[cfg(feature = "alignment-diagnostics")]
pub mod views;

#[cfg(feature = "alignment-diagnostics")]
pub mod visit_params;

pub use errors::*;
pub use models::*;

#[cfg(feature = "alignment-diagnostics")]
pub use state::*;

/// A trait for numeric types compatible with pHMMs.
///
/// These numeric types are used for performing pHMM calculations in negative
/// log space.
pub trait PhmmNumber:
    Copy
    + Add<Output = Self>
    + Mul<Output = Self>
    + AddAssign
    + PartialOrd
    + CastAs
    + CastAsNumeric
    + CastFrom
    + CastFromNumeric
    + Default
    + Display {
    /// Infinity, the negative log space score corresponding to probability zero
    const INFINITY: Self;
    /// Zero, the negative log space score corresponding to probability one
    const ZERO: Self;

    /// Converts a probability (a floating point value) into negative log space
    fn from_prob<T: Float>(prob: T) -> Self;

    /// Converts a negative log space score back to a probability
    fn to_prob<T: Float>(self) -> T;

    /// Returns the negative log space score as a float
    fn to_float<T: Float>(self) -> T;

    /// Computes the minimum of two negative log space scores
    #[must_use]
    fn min(self, other: Self) -> Self;
}

impl PhmmNumber for f32 {
    const INFINITY: Self = f32::INFINITY;
    const ZERO: Self = 0.0;

    #[inline]
    fn from_prob<T: Float>(prob: T) -> Self {
        // Increase precision by converting to f32 last
        let param = (-prob.ln()).cast_as::<f32>();
        if param.is_nan() { Self::INFINITY } else { param }
    }

    #[inline]
    fn to_prob<T: Float>(self) -> T {
        // Increase precision by converting from f32 first
        (-T::cast_from(self)).exp()
    }

    #[inline]
    fn to_float<T: Float>(self) -> T {
        T::cast_from(self)
    }

    #[inline]
    fn min(self, other: Self) -> Self {
        self.min(other)
    }
}

impl PhmmNumber for f64 {
    const INFINITY: Self = f64::INFINITY;
    const ZERO: Self = 0.0;

    #[inline]
    fn from_prob<T: Float>(prob: T) -> Self {
        // Increase precision by converting to f64 first
        let param = -prob.cast_as::<f64>().ln();
        if param.is_nan() { Self::INFINITY } else { param }
    }

    #[inline]
    fn to_prob<T: Float>(self) -> T {
        // Increase precision by converting from f64 last
        T::cast_from((-self).exp())
    }

    #[inline]
    fn to_float<T: Float>(self) -> T {
        T::cast_from(self)
    }

    #[inline]
    fn min(self, other: Self) -> Self {
        self.min(other)
    }
}