extended_htslib/
lib.rs

1// Copyright 2014-2021 Johannes Köster.
2// Copyright 2025 Guilhem Zeitoun
3// Licensed under the MIT license (http://opensource.org/licenses/MIT)
4// This file may not be copied, modified, or distributed
5// except according to those terms.
6//! This crate is an extension of Rust-Htslib. It allows the parsing of MD and CS tag as well as parsing of match and mismatch in CIGAR format.
7//! The rest of the crate remains unchanged.
8//! 
9//! Rust-Htslib provides a high level API to working with the common HTS file formats.
10//!
11//! Htslib itself is the *de facto* standard implementation for reading and writing files for
12//! HTS alignments (SAM and BAM) as well as variant calls in VCF and BCF format.
13//!
14//! For example, let's say that we use samtools to view the header of a test file:
15//!
16//! ```bash
17//! samtools view -H test/test.bam
18//! @SQ    SN:CHROMOSOME_I    LN:15072423
19//! @SQ    SN:CHROMOSOME_II    LN:15279345
20//! @SQ    SN:CHROMOSOME_III    LN:13783700
21//! @SQ    SN:CHROMOSOME_IV    LN:17493793
22//! @SQ    SN:CHROMOSOME_V    LN:20924149
23//! ```
24//!
25//! We can reproduce that with Rust-Htslib. Reading BAM files and printing the header
26//! to the the screen is as easy as
27//!
28//! ```
29//! use extended_htslib::{bam, bam::Read};
30//!
31//!
32//! let bam = bam::Reader::from_path(&"test/test.bam").unwrap();
33//! let header = bam::Header::from_template(bam.header());
34//!
35//! // print header records to the terminal, akin to samtool
36//! for (key, records) in header.to_hashmap() {
37//!     for record in records {
38//!          println!("@{}\tSN:{}\tLN:{}", key, record["SN"], record["LN"]);
39//!     }
40//! }
41//! ```
42//!
43//! which results in the following output, equivalent to samtools.
44//!
45//! ```bash
46//! @SQ    SN:CHROMOSOME_I    LN:15072423
47//! @SQ    SN:CHROMOSOME_II    LN:15279345
48//! @SQ    SN:CHROMOSOME_III    LN:13783700
49//! @SQ    SN:CHROMOSOME_IV    LN:17493793
50//! @SQ    SN:CHROMOSOME_V    LN:20924149
51//! ```
52//!
53//! We can also read directly from the BAM file and write to an output file
54//!
55//! ```
56//! use extended_htslib::{bam, bam::Read};
57//!
58//! let mut bam = bam::Reader::from_path(&"test/test.bam").unwrap();
59//! let header = bam::Header::from_template(bam.header());
60//! let mut out = bam::Writer::from_path(&"test/out.bam", &header, bam::Format::Bam).unwrap();
61//!
62//! // copy reverse reads to new BAM file
63//! for r in bam.records() {
64//!     let record = r.unwrap();
65//!     if record.is_reverse() {
66//!         out.write(&record).unwrap();
67//!     }
68//! }
69//! ```
70//!
71//! Pileups can be performed with
72//!
73//! ```
74//! use extended_htslib::{bam, bam::Read};
75//!
76//! let mut bam = bam::Reader::from_path(&"test/test.bam").unwrap();
77//!
78//! // pileup over all covered sites
79//! for p in bam.pileup() {
80//!     let pileup = p.unwrap();
81//!     println!("{}:{} depth {}", pileup.tid(), pileup.pos(), pileup.depth());
82//!
83//!     for alignment in pileup.alignments() {
84//!         if !alignment.is_del() && !alignment.is_refskip() {
85//!             println!("Base {}", alignment.record().seq()[alignment.qpos().unwrap()]);
86//!         }
87//!         // mark indel start
88//!         match alignment.indel() {
89//!             bam::pileup::Indel::Ins(len) => println!("Insertion of length {} between this and next position.", len),
90//!             bam::pileup::Indel::Del(len) => println!("Deletion of length {} between this and next position.", len),
91//!             bam::pileup::Indel::None => ()
92//!         }
93//!     }
94//! }
95//! ```
96//!
97//! In both cases, indexed BAM files can be seeked for specific regions using [`fetch`](bam/struct.IndexedReader.html#method.fetch), constraining either the record iterator or the pileups:
98//!
99//! ```
100//! use extended_htslib::{bam, bam::Read};
101//!
102//! let mut bam = bam::IndexedReader::from_path(&"test/test.bam").unwrap();
103//!
104//! bam.fetch(("CHROMOSOME_I", 0, 20)).unwrap();
105//! // afterwards, read or pileup in this region
106//! ```
107//!
108//! See
109//! * [`fetch`](bam/struct.IndexedReader.html#method.fetch)
110//! * [`records`](bam/struct.IndexedReader.html#method.records)
111//! * [`read`](bam/struct.IndexedReader.html#method.read)
112//! * [`pileup`](bam/struct.IndexedReader.html#method.pileup)
113
114#[macro_use]
115extern crate custom_derive;
116
117#[macro_use]
118extern crate newtype_derive;
119
120#[cfg(feature = "serde_feature")]
121extern crate serde;
122
123#[cfg(test)] // <-- not needed in examples + integration tests
124#[macro_use]
125extern crate pretty_assertions;
126#[cfg(all(test, feature = "serde_feature"))]
127extern crate serde_json;
128
129pub mod bam;
130pub mod bcf;
131pub mod bgzf;
132pub mod errors;
133pub mod faidx;
134pub mod htslib;
135pub mod tbx;
136pub mod tpool;
137pub mod utils;
extended_htslib/lib.rs

extended_htslib/
lib.rs
