extended_htslib/
lib.rs

1// Copyright 2014-2021 Johannes Köster.
2// Copyright 2024-2026 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
7//! Rust-Htslib provides a high level API to working with the common HTS file formats.
8//!
9//! Htslib itself is the *de facto* standard implementation for reading and writing files for
10//! HTS alignments (SAM and BAM) as well as variant calls in VCF and BCF format.
11//!
12//! For example, let's say that we use samtools to view the header of a test file:
13//!
14//! ```bash
15//! samtools view -H test/test.bam
16//! @SQ    SN:CHROMOSOME_I    LN:15072423
17//! @SQ    SN:CHROMOSOME_II    LN:15279345
18//! @SQ    SN:CHROMOSOME_III    LN:13783700
19//! @SQ    SN:CHROMOSOME_IV    LN:17493793
20//! @SQ    SN:CHROMOSOME_V    LN:20924149
21//! ```
22//!
23//! We can reproduce that with Rust-Htslib. Reading BAM files and printing the header
24//! to the screen is as easy as
25//!
26//! ```
27//! use extended_htslib::{bam, bam::Read};
28//!
29//!
30//! let bam = bam::Reader::from_path(&"test/test.bam").unwrap();
31//! let header = bam::Header::from_template(bam.header());
32//!
33//! // print header records to the terminal, akin to samtool
34//! for (key, records) in header.to_hashmap() {
35//!     for record in records {
36//!          println!("@{}\tSN:{}\tLN:{}", key, record["SN"], record["LN"]);
37//!     }
38//! }
39//! ```
40//!
41//! which results in the following output, equivalent to samtools.
42//!
43//! ```bash
44//! @SQ    SN:CHROMOSOME_I    LN:15072423
45//! @SQ    SN:CHROMOSOME_II    LN:15279345
46//! @SQ    SN:CHROMOSOME_III    LN:13783700
47//! @SQ    SN:CHROMOSOME_IV    LN:17493793
48//! @SQ    SN:CHROMOSOME_V    LN:20924149
49//! ```
50//!
51//! We can also read directly from the BAM file and write to an output file
52//!
53//! ```
54//! use extended_htslib::{bam, bam::Read};
55//!
56//! let mut bam = bam::Reader::from_path(&"test/test.bam").unwrap();
57//! let header = bam::Header::from_template(bam.header());
58//! let mut out = bam::Writer::from_path(&"test/out.bam", &header, bam::Format::Bam).unwrap();
59//!
60//! // copy reverse reads to new BAM file
61//! for r in bam.records() {
62//!     let record = r.unwrap();
63//!     if record.is_reverse() {
64//!         out.write(&record).unwrap();
65//!     }
66//! }
67//! ```
68//!
69//! Pileups can be performed with (requires a RegionString region):
70//!
71//! ```
72//! use extended_htslib::{bam::{self,pileup}, bam::Read};
73//!
74//! let mut path = "test/test.bam";
75//!
76//! let config = pileup::RustPileupConfig::default();
77//! let pos = bam::FetchDefinition::RegionString("CHROMOSOME_I".as_bytes(), 1, 100);
78//! let config = pileup::RustPileupConfig::default();
79//! let mut po = pileup::RustPileups::new(path, None, None, None, pos, config).unwrap();
80//! for pileup in po {
81//!     println!("Pileup is {}", pileup.to_string());
82//!     println!("Base is {}",pileup.getbase());
83//! }
84//! ```
85//!
86//! 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:
87//!
88//! ```
89//! use extended_htslib::{bam, bam::Read};
90//!
91//! let mut bam = bam::IndexedReader::from_path(&"test/test.bam").unwrap();
92//!
93//! bam.fetch(("CHROMOSOME_I", 0, 20)).unwrap();
94//! // afterwards, read or pileup in this region
95//! ```
96//!
97//! See
98//! * [`fetch`](bam/struct.IndexedReader.html#method.fetch)
99//! * [`records`](bam/struct.IndexedReader.html#method.records)
100//! * [`read`](bam/struct.IndexedReader.html#method.read)
101//! * [`pileup`](bam/struct.IndexedReader.html#method.pileup)
102
103#[macro_use]
104extern crate custom_derive;
105
106#[macro_use]
107extern crate newtype_derive;
108
109#[cfg(feature = "serde_feature")]
110extern crate serde;
111
112#[cfg(test)] // <-- not needed in examples + integration tests
113#[macro_use]
114extern crate pretty_assertions;
115#[cfg(all(test, feature = "serde_feature"))]
116extern crate serde_json;
117
118pub mod bam;
119pub mod bcf;
120pub mod bgzf;
121pub mod errors;
122pub mod faidx;
123pub mod htslib;
124pub mod tbx;
125pub mod tpool;
126pub mod utils;
extended_htslib/lib.rs

extended_htslib/
lib.rs
