omics-coordinate 0.4.0

Foundational representations of coordinates in the Rust omics ecosystem
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
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209

//! Base intervals.

use crate::base::Coordinate;
use crate::interval::r#trait;
use crate::position::Number;
use crate::system::Base;
use crate::system::Interbase;

////////////////////////////////////////////////////////////////////////////////////////
// Intervals
////////////////////////////////////////////////////////////////////////////////////////

/// A base interval.
///
/// Base intervals consist of two in-base positions. The range is represented by
/// the interval `[start, end]`.
pub type Interval = crate::Interval<Base>;

impl Interval {
    /// Consumes `self` and returns the equivalent interbase interval.
    ///
    /// # Examples
    ///
    /// ```
    /// use omics_coordinate::Interval;
    /// use omics_coordinate::system::Base;
    /// use omics_coordinate::system::Interbase;
    ///
    /// let interval = "seq0:+:1-1000".parse::<Interval<Base>>()?;
    /// let equivalent = interval.into_equivalent_interbase();
    ///
    /// assert_eq!("seq0:+:0-1000".parse::<Interval<Interbase>>()?, equivalent);
    ///
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn into_equivalent_interbase(self) -> crate::interval::Interval<Interbase> {
        let (start, end) = self.into_coordinates();

        // SAFETY: given the rules of how interbase and base coordinate systems
        // work, this should always unwrap.
        let start = start.nudge_backward().unwrap();
        let end = end.nudge_forward().unwrap();

        // SAFETY: since this was previously a valid interbase interval, as long
        // as the two nudges above succeed, this should always unwrap.
        crate::interval::Interval::<Interbase>::try_new(start, end).unwrap()
    }
}

////////////////////////////////////////////////////////////////////////////////////////
// Trait implementations
////////////////////////////////////////////////////////////////////////////////////////

impl r#trait::Interval<Base> for Interval {
    fn contains_entity(&self, coordinate: &Coordinate) -> bool {
        // NOTE: for in-base positions whether or not the entity is contained in
        // the interval matches the implementation of whether or not the
        // coordinate is contained within the interval, as entities and
        // coordinates are essentially the same thing in this system.
        self.contains_coordinate(coordinate)
    }

    /// Gets the number of entities within the interval.
    fn count_entities(&self) -> Number {
        self.start()
            .position()
            .distance_unchecked(self.end().position())
            + 1
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::Coordinate;
    use crate::system::Base;

    fn create_coordinate(contig: &str, strand: &str, position: Number) -> crate::Coordinate<Base> {
        Coordinate::try_new(contig, strand, position).unwrap()
    }

    fn create_interval(contig: &str, strand: &str, start: Number, end: Number) -> Interval {
        Interval::try_new(
            create_coordinate(contig, strand, start),
            create_coordinate(contig, strand, end),
        )
        .unwrap()
    }

    #[test]
    fn contains() {
        let interval = create_interval("seq0", "+", 10, 20);

        // An interval contains the coordinate representing its start position.
        assert!(interval.contains_coordinate(interval.start()));

        // An interval contains the coordinate representing its end position.
        assert!(interval.contains_coordinate(interval.end()));

        // An interval contains a coordinate in the middle of its range.
        assert!(interval.contains_coordinate(&create_coordinate("seq0", "+", 15)));

        // An interval does not contain the position _before_ its start
        // position.
        assert!(!interval.contains_coordinate(&create_coordinate("seq0", "+", 9)));

        // An interval does not contain the position _after_ its end position.
        assert!(!interval.contains_coordinate(&create_coordinate("seq0", "+", 21)));

        // An interval does not contain a random other position.
        assert!(!interval.contains_coordinate(&create_coordinate("seq0", "+", 1000)));

        // An interval does not contain a coordinate on another contig.
        assert!(!interval.contains_coordinate(&create_coordinate("seq1", "+", 15)));

        // An interval does not contain a coordinate on another strand.
        assert!(!interval.contains_coordinate(&create_coordinate("seq0", "-", 15)));

        let interval = create_interval("seq0", "-", 20, 10);

        // An interval contains the coordinate representing its start position.
        assert!(interval.contains_coordinate(interval.start()));

        // An interval contains the coordinate representing its end position.
        assert!(interval.contains_coordinate(interval.end()));

        // An interval contains a coordinate in the middle of its range.
        assert!(interval.contains_coordinate(&create_coordinate("seq0", "-", 15)));

        // An interval does not contain the position _before_ its start
        // position.
        assert!(!interval.contains_coordinate(&create_coordinate("seq0", "-", 21)));

        // An interval does not contain the position _after_ its end position.
        assert!(!interval.contains_coordinate(&create_coordinate("seq0", "-", 9)));

        // An interval does not contain a random other position.
        assert!(!interval.contains_coordinate(&create_coordinate("seq0", "-", 1)));

        // An interval does not contain a coordinate on another contig.
        assert!(!interval.contains_coordinate(&create_coordinate("seq1", "-", 15)));

        // An interval does not contain a coordinate on another strand.
        assert!(!interval.contains_coordinate(&create_coordinate("seq0", "+", 15)));
    }

    #[test]
    fn contains_entity() {
        let interval = create_interval("seq0", "+", 10, 20);

        // A base interval does not contain the entity at the full-step _before_
        // its start position when on the positive strand.
        assert!(!interval.contains_entity(&create_coordinate("seq0", "+", 9)));

        // A base interval does contain the entity at it start position when on
        // the positive strand.
        assert!(interval.contains_entity(&create_coordinate("seq0", "+", 10)));

        // A base interval does contain the entity at the its end position when
        // on the positive strand.
        assert!(interval.contains_entity(&create_coordinate("seq0", "+", 20)));

        // A base interval does not contain the entity at the full-step _after_
        // its end position when on the positive strand.
        assert!(!interval.contains_entity(&create_coordinate("seq0", "+", 21)));

        // A base interval does contain an entity midway through its range on
        // the positive strand.
        assert!(interval.contains_entity(&create_coordinate("seq0", "+", 15)));

        // A base interval does not contain an entity on a different contig on
        // the positive strand.
        assert!(!interval.contains_entity(&create_coordinate("seq1", "+", 15)));

        // A base interval does not contain an entity on a different strand on
        // the positive strand.
        assert!(!interval.contains_entity(&create_coordinate("seq0", "-", 15)));

        let interval = create_interval("seq0", "-", 20, 10);

        // A base interval does not contain the entity at the full-step _before_
        // its start position when on the negative strand.
        assert!(!interval.contains_entity(&create_coordinate("seq0", "-", 21)));

        // A base interval does contain the entity at its start position when on
        // the negative strand.
        assert!(interval.contains_entity(&create_coordinate("seq0", "-", 20)));

        // A base interval does contain the entity at its end position when on
        // the negative strand.
        assert!(interval.contains_entity(&create_coordinate("seq0", "-", 10)));

        // A base interval does not contain the entity at the full-step _after_
        // its end position when on the negative strand.
        assert!(!interval.contains_entity(&create_coordinate("seq0", "-", 9)));

        // A base interval does contain an entity midway through its range on
        // the negative strand.
        assert!(interval.contains_entity(&create_coordinate("seq0", "-", 15)));

        // A base interval does not contain an entity on a different contig on
        // the negative strand.
        assert!(!interval.contains_entity(&create_coordinate("seq1", "-", 15)));

        // A base interval does not contain an entity on a different strand on
        // the negative strand.
        assert!(!interval.contains_entity(&create_coordinate("seq0", "+", 15)));
    }
}