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
#![warn(clippy::pedantic, clippy::perf)]
#![allow(
clippy::module_inception,
clippy::module_name_repetitions,
clippy::missing_errors_doc
)]
//! [](./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);
//! ```
//!
//! ## 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
pub mod traits;
/// Types used within the library
pub mod types;
/// Prelude for the library
pub mod prelude;
pub use traits::{
Coordinates, Distance, Intersect, Overlap, Segment, StrandedOverlap, Subtract,
UnstrandedOverlap,
};
pub use types::{
BaseInterval, Bed12, Bed3, Bed4, Bed6, BedGraph, Frame, Gtf, IntersectIter, IntervalContainer,
IntervalIterOwned, IntervalIterRef, MergeIter, MetaInterval, Score, Strand, StrandedBed3,
};