Skip to content

bio-cr/hts.cr

Repository files navigation

HTS.cr

CI Slack Get invite to BioCrystal DOI Docs Latest

HTS.cr provides Crystal bindings for HTSlib that allows you to read and write file formats commonly used in genomics, such as SAM, BAM, VCF, and BCF.

ℹ️ Method names will be changed to rust-htslib style in the next version.

Requirements

  • Crystal
  • HTSlib
    • Ubuntu : apt install libhts-dev
    • macOS : brew install htslib
    • Any OS : Build from source code
    • Make sure that pkg-config can detect htslib: pkg-config --libs htslib

Installation

Add htslib to your shard.yml:

dependencies:
  htslib:
    github: bio-cr/hts.cr
    branch: develop

Run shards install

Usage

Read SAM / BAM / CRAM

require "hts/bam"

bam = HTS::Bam.open(bam_path)

bam.each do |r|
  p name: r.qname,
    flag: r.flag.value,
    chrm: r.chrom,
    strt: r.pos + 1,
    mapq: r.mapq,
    cigr: r.cigar.to_s,
    mchr: r.mate_chrom,
    mpos: r.mpos + 1,
    isiz: r.isize,
    seqs: r.seq,
    qual: r.qual_string,
    axMC: r.aux("MC")
end

bam.close

Read VCF / BCF

require "hts/bcf"

bcf = HTS::Bcf.open(bcf_path)

bcf.each do |r|
  p chrom:  r.chrom,
    pos:    r.pos,
    id:     r.id,
    qual:   r.qual,
    filter: r.filter,
    ref:    r.ref,
    alt:    r.alt,
  # alleles r.alleles
  # info:   r.info,
  # format  r.format
end

bcf.close

API Overview

  • High level API - Classes include Bam, Bcf, Tabix, Faidx, etc.
  • LibHTS - Native C bindings to HTSLib generated by crystal_lib.
  • For more information, please see API documentation.
 ┌──────────────────── HTS ────────────────────┐
 │                                             │
 │ ┌─ Bam ────────┬─ Bcf ───────┬─ Tabix ────┐ │
 │ │ SAM BAM CRAM │ VCF BCF     │ TABIX      │ │
 │ └──────────────┴─────────────┴────────────┘ │
 │                     ┌─LibHTS2───────────┐   │
 │ ┌─LibHTS────────────┤ Macro functions   ├─┐ │
 │ │ Native C bindings └───────────────────┘ │ │
 │ └─────────────────────────────────────────┘ │
 └─────────────────────────────────────────────┘

LibHTS2: Since methods cannot be added to Lib in the Crystal language, macro functions are implemented in the LibHTS2 module. This is different from Ruby-htslib.

Looking for flexibility?

The Crystal language is suited for creating efficient command-line tools. The Ruby language, on the other hand, is suited for exploratory analysis.

Contributing

🚀 Feel free to fork it out!

git clone https://github.com/bio-cr/hts.cr
cd hts.cr
crystal run test/run_all.cr

HTS.cr is an immature, work-in-progress library, and pull requests such as small typo fixes are welcome.

Do you need commit rights to hts?
Do you want to get admin rights and take over the project?
Please feel free to contact us @kojix2.

Benchmark

https://github.com/brentp/vcf-bench

code: https://github.com/kojix2/vcf-bench/blob/kojix2/crystal-htslib/read.cr