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
//! [](./LICENSE.md)
//! 
//! [](https://codecov.io/gh/noamteyssier/bedrs)
//! [](https://crates.io/crates/bedrs)
//! [](https://docs.rs/bedrs/latest/bedrs/)
//!
//! # bedrs
//!
//! `bedtools`-like functionality for interval sets in rust
//!
//! ## Summary
//!
//! This is an interval library written in rust that takes advantage of the trait
//! system, generics, monomorphization, and procedural macros, for high efficiency
//! interval operations with nice quality of life features for developers.
//!
//! It focuses around the [`Coordinates`] trait, which once implemented on
//! and arbitrary interval type allows for a wide range of genomic interval arithmetic.
//!
//! It also introduces a new collection type, [`IntervalContainer`], which acts as a collection
//! of [`Coordinates`] and has many set operations implemented.
//!
//! Interval arithmetic can be thought of as set theoretic operations (like intersection,
//! union, difference, complement, etc.) on intervals with associated chromosomes, strands,
//! and other genomic markers.
//!
//! This library facilitates the development of these types of operations on arbitrary types
//! and lets the user tailor their structures to minimize computational overhead, but also
//! remains a flexible library for general interval operations.
//!
//! ## Usage
//!
//! The main benefit of this library is that it is trait-based.
//! So you can define your own types - but if they implement the
//! [`Coordinates`] trait they can use the other functions within the
//! library.
//!
//! For detailed usage and examples please review the [documentation](https://docs.rs/bedrs/latest/bedrs/).
//!
//! ### [`Coordinates`] Trait
//!
//! The library centers around the [`Coordinates`] trait.
//!
//! This trait defines some minimal functions that are required for all set operations.
//! This includes things like getting the chromosome ID of an interval, or the start and
//! endpoints of that interval, or the strand.
//!
//! This can be implemented by hand, or if you follow common naming conventions used in the
//! library (`chr`, `start`, `end`, `strand`) then you can `[derive(Coordinates)]` on your
//! custom interval type.
//!
//! ```rust
//! use bedrs::prelude::*;
//!
//! // define a custom interval struct for testing
//! #[derive(Default, Coordinates)]
//! struct MyInterval {
//! chr: usize,
//! start: usize,
//! end: usize,
//! }
//! ```
//!
//! ### Interval Types
//!
//! While you can create your own interval types, there are plenty of 'batteries-included'
//! types you can use in your own libraries already.
//!
//! These include:
//! - [`Bed3`]
//! - [`Bed4`]
//! - [`Bed6`]
//! - [`Bed12`]
//! - [`BedGraph`]
//! - [`Gtf`]
//! - [`MetaInterval`]
//! - [`StrandedBed3`]
//!
//! These are pre-built interval types and can be used in many usecases:
//!
//! ``` rust
//! use bedrs::prelude::*;
//!
//! // An interval on chromosome 1 and spanning base 20 <-> 40
//! let a = Bed3::new(1, 20, 40);
//!
//! // An interval on chromosome 1 and spanning base 30 <-> 50
//! let b = Bed3::new(1, 30, 50);
//!
//! // Find the intersecting interval of the two
//! // This returns an Option<Bed3> because they may not intersect.
//! let c = a.intersect(&b).unwrap();
//!
//! assert_eq!(c.chr(), &1);
//! assert_eq!(c.start(), 30);
//! assert_eq!(c.end(), 40);
//! ```
//!
//! When compiled with the htslib feature, BAM records from the `rust_htslib`
//! library can be converted to a `StrandedBed3` interval.
//! ```
//! #[cfg(htslib)]
//! {
//! // Load a BAM file and convert records to StrandedBed3.
//! use bedrs::prelude::*;
//! use rust_htslib::{bam, bam::Read};
//!
//! let mut bam = bam::Reader::from_path(&"examples/sample.sorted.bam").unwrap();
//! for r in bam.records() {
//! let record = r.unwrap();
//! let a = StrandedBed3::try_from(record).unwrap();
//! }
//! }
//! ```
//!
//! ## Interval Operations
//!
//! - [`Overlap`]
//! - [`Distance`]
//! - [`Intersect`]
//! - [`Segment`]
//! - [`Subtract`]
//!
//! ## Interval Set Operations
//!
//! Set operations are performed using the methods of the [`IntervalContainer`].
//!
//! We can build an [`IntervalContainer`] easily on any collection of intervals:
//!
//! ``` rust
//! use bedrs::prelude::*;
//!
//! let set = IntervalContainer::new(vec![
//! Bed3::new(1, 20, 30),
//! Bed3::new(1, 30, 40),
//! Bed3::new(1, 40, 50),
//! ]);
//!
//! assert_eq!(set.len(), 3);
//! ```
//!
//! For more details on each of these and more please explore the [`IntervalContainer`] for all
//! associated methods.
//!
//! - Bound
//! - Closest
//! - Complement
//! - Find
//! - Internal
//! - Merge
//! - Sample
//! - Intersect
//! - Segment
//! - Subtract
//!
//! ## Other Work
//!
//! This library is heavily inspired by other interval libraries in rust
//! which are listed below:
//!
//! - [rampart](https://crates.io/crates/rampart)
//! - [rust_lapper](https://crates.io/crates/rust-lapper)
//! - [COITrees](https://crates.io/crates/coitrees)
//!
//! It also was motivated by the following interval toolkits in C++ and C respectively:
//! - [bedtools](https://github.com/arq5x/bedtools2)
//! - [bedops](https://github.com/bedops/bedops)
/// Traits used within the library
/// Types used within the library
/// Prelude for the library
pub use ;
pub use ;