bio-cr / hts.cr

HTSlib bindings for Crystal

HTS.cr

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.

• ruby-htslib

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

hts.cr's Issues

images

Release memory using `finalize`

• https://forum.crystal-lang.org/t/c-binding-how-to-call-the-memory-release-function-when-being-finalized-by-gc/4187
• https://crystal-lang.org/reference/1.2/syntax_and_semantics/finalize.html

Index handling when opening Bam and Bcf files

Need to design keyword variables better

• Whether the index should be loaded or not.
• Whether the index should be created or not
  • Whether or not to create new index, even if it exists.
• If the index is in a separate directory from the data Files

Calling write_sam1 causes a segmentation fault

Invalid memory access (signal 11) at address 0x8
[0x558b21a3c730] ?? [phone] in ./bam-filter
[0x558b21a3c5e5] ?? [phone] in ./bam-filter
[0x7fdfbd4ac420] ?? [phone] in /lib/x86_64-linux-gnu/libpthread.so.0
[0x558b21a52be9] ?? [phone] in ./bam-filter
[0x558b219d0ddd] __crystal_main +8973 in ./bam-filter
[0x558b21a55a8b] ?? [phone] in ./bam-filter
[0x558b21a5572c] ?? [phone] in ./bam-filter
[0x558b219e205b] main +27 in ./bam-filter
[0x7fdfbd251083] __libc_start_main +243 in /lib/x86_64-linux-gnu/libc.so.6
[0x558b219cea0e] _start +46 in ./bam-filter
[0x0] ???

This error can be avoided by cloning the header.

[Documentation] Small typo: "htslib.cr is the Crystal bindings to HTSlib, a C library for for high-throughput sequencing data formats" has one "for" too many

Hey there kojix2, just a small typo:

"htslib.cr is the Crystal bindings to HTSlib, a C library for for high-throughput sequencing data formats"

I think you can replace "for for" with just one "for". Hope that typo report is not too annoying for you. :)