repository·master·Indexed 20 days ago
https://github.com/zaeleus/noodlesA collection of specification-compliant Rust libraries for handling bioinformatics file formats, including BAM, BCF, CRAM, FASTA, and VCF. Version 0.115.0 provides modular support for these formats with optional features for asynchronous I/O via Tokio and accelerated DEFLATE encoding/decoding via libdeflate.
To use noodles in your Rust project, add the noodles crate to your dependencies. The library is modular; you must enable specific features for the file formats you intend to work with. For example, to work with the BAM format, add the noodles crate and enable the bam feature.
cargo add noodles --features bamOnce a feature is enabled in your Cargo.toml, you can access the corresponding format module through the noodles meta-crate re-exports. For example, if the bam feature is enabled, you can import it using noodles::bam.
use noodles::bam;The noodles-fasta crate provides tools for reading and writing the FASTA format. FASTA files consist of records where the first line (starting with >) contains the sequence name and optional description, followed by lines containing the sequence data (typically a byte array of characters).
Key modules include:
io: For reading and writing FASTA files.record: For handling individual FASTA records.sequence: For managing sequence data.fai: For handling FASTA index files.async: Provides asynchronous support (when the async feature is enabled).The noodles-util crate provides unified interfaces for reading and writing bioinformatics data formats. It is organized into two main modules based on the type of data being processed:
alignment module (requires the alignment feature flag).variant module (requires the variant feature flag).To use these interfaces, ensure you enable the corresponding feature in your Cargo.toml.
# Example Cargo.toml configuration
[dependencies]
noodles-util = {
version = "...",
features = ["alignment", "variant"]
}The noodles crate acts as a central entrypoint for a collection of specialized bioinformatics file format libraries. Instead of importing individual crates, you can use noodles and enable specific features to access the desired format modules.
Supported formats available via features include:
bam: BAM 1.6bcf: BCF 2.2bed: BEDbgzf: BGZFcore: Core functionalitycram: CRAM 3.0/3.1csi: CSIfasta: FASTAfastq: FASTQgff: GFF3gtf: GTF 2.2htsget: htsget 1.3refget: refget 2.0sam: SAM 1.6tabix: tabixvcf: VCF 4.3/4.4BGZF (Blocked GNU Zip Format) is a multistream gzip format. Unlike a standard gzip file which is a single stream, a BGZF file is a concatenation of many independent gzip streams called 'blocks'.
Key characteristics:
VirtualPosition.noodles-bgzf hides the complexity of these blocks by providing std::io::Read and std::io::Write implementations.Noodles provides optional features to extend functionality. The following global features are available for specific formats:
async: Enables asynchronous I/O using [Tokio]. Supported for: BAM, BCF, BGZF, CRAM, CSI, FASTA, FASTQ, GFF, SAM, tabix, and VCF.libdeflate: Uses [libdeflate] for faster encoding and decoding of DEFLATE streams. Supported for: BGZF and CRAM.A BAM file header consists of three distinct parts that must be read in a specific order to maintain correct stream positioning:
BAM\x01) at the very beginning.u32) immediately following the magic number. The raw_sam_header_reader uses this length to know how much text to parse.If the SAM header text contains padding, you must call discard_to_end() on the SAM header reader before attempting to read the reference sequences to ensure the stream is positioned correctly at the start of the binary dictionary.
To read BAM files, use noodles_bam::io::Reader. You can initialize it from a file or any type that implements Read. If you provide a raw stream, Reader::new will automatically wrap it in a BGZF decoder.
If you need to use a custom decoder (like flate2::read::MultiGzDecoder or noodles_bgzf::io::MultithreadedReader), use Reader::from instead.
use std::fs::File;
use noodles_bam as bam;
// From a file
let mut reader = File::open("sample.bam").map(bam::io::Reader::new)?;
// From a custom decoder
// let reader = bam::io::Reader::from(custom_decoder);To use a specific format module through the noodles meta-crate, you must enable the corresponding feature in your Cargo.toml. For example, to use BAM support, add noodles = { version = "...", features = ["bam"] }.
[dependencies]
noodles = {
version = "0.x.x",
features = ["bam", "fasta", "vcf"]
}The noodles_bcf::io::Writer is used to write BCF (Binary Call Format) files. You can initialize it with a standard writer (like a file or std::io::sink) or wrap it in a BGZF encoder for compressed output.
To write a valid BCF file, you must first write a VCF header using write_header, which also initializes the internal string maps required for record encoding. Subsequently, you can write individual records using write_record.
use std::io;
use noodles_bcf as bcf;
use noodles_vcf as vcf;
use noodles_core::Position;
// 1. Initialize the writer (using sink for this example)
let mut writer = bcf::io::Writer::new(io::sink());
// 2. Prepare and write the header
let mut header = vcf::Header::builder()
.add_contig("sq0", vcf::header::record::value::map::Contig::new())
.build();
// Note: StringMaps must be synchronized with the header
*header.string_maps_mut() = vcf::header::StringMaps::try_from(&header)?;
writer.write_header(&header)?;
// 3. Write a record
let record = bcf::Record::default();
writer.write_record(&header, &record)?;To use noodles_bam asynchronously, wrap an asynchronous reader (like tokio::fs::File) in noodles_bam::r#async::io::Reader. If you are providing a raw BGZF stream, the Reader::new method will automatically wrap it in a BGZF decoder.
Note: The reader expects the stream to be at the start of the BAM file (e.g., at the magic number).
use noodles_bam as bam;
use tokio::fs::File;
let mut reader = File::open("sample.bam").await.map(bam::r#async::io::Reader::new)?;