Search:
Group by:

# Introduction

hts-nim is a library to enable writing fast, efficient tools and libraries using the Nim programming language. It is available at https://github.com/brentp/hts-nim/

Nim has a simple syntax and compiles to C code. In our experience it is as fast as code written in C. We have previously published mosdepth, a tool for fast depth calculation that uses hts-nim.

The hts-nim-tools repository also contains several tools written with hts-nim that can serve as documentation for how to use the library.

Below we show short snippets of example usage of the library. Full API documentation of each module is linked from the bottom of the page.

# BAM / CRAM / SAM

    import hts

    # open a bam and look for the index.
    var b:Bam
    open(b, "test/HG02002.bam", index=true)

    for record in b:
      if record.qual > 10:
        echo record.chrom, record.start, record.stop

    # regional queries:
    for record in b.query('6', 30816675, 32816675):
      if record.flag.proper_pair and record.flag.reverse:
        # cigar is an iterable of operations:
        for op in record.cigar:
          # $op gives the string repr of the operation, e.g. '151M'
          echo $op, op.consumes.reference, op.consumes.query

      # tags are pulled with `aux`
      var mismatches = record.aux("NM")
      if mismatches != nil and mismatches.integer() < 3:
        var rg = rec.aux("RG")
        echo rg.tostring()

    # cram requires an fasta to decode:
    var cram:Bam
    open(cram, "/tmp/t.cram", fai="/data/human/g1k_v37_decoy.fa")
    for record in cram:
      # now record is same as from bam above
      echo record.qname, record.isize

# VCF / BCF

    import hts

    var tsamples = @["101976-101976", "100920-100920", "100231-100231", "100232-100232", "100919-100919"]

    # VCF and BCF supported
    var v:VCF
    doAssert open(v, "tests/test.bcf", samples=tsamples)

    var afs = new_seq[float32](5) # size doesn't matter. this will be re-sized as needed
    var acs = new_seq[int32](5) # size doesn't matter. this will be re-sized as needed
    var csq = new_string_of_cap(20)
    for rec in v:
      echo rec, " qual:", rec.QUAL, " filter:", rec.FILTER
      var info = rec.info
      # accessing stuff from the INFO fields is meant to be as fast as possible, allowing
      # the user to re-use memory as needed.
      info.get("CSQ", csq) # string
      info.get("AC", acs) # ints
      info.get("AF", afs) # floats
      echo acs, afs, csq, info.has_flag("IN_EXAC")

      # accessing format fields is similar
      var format = ref.format
      var dps = new_seq[int32](len(v.samples))
      doAssert format.get("DP", dps)
      echo dps

      echo v.samples

      # regional queries look for index. works for VCF and BCF
      for rec in v.query("1:15600-18250"):
        echo rec.CHROM, ":", $rec.POS

# Imports

- ./hts/utils
- ./hts/private/hts_concat
- ./hts/bam
- ./hts/vcf
- ./hts/fai
- ./hts/bgzf
- ./hts/bgzf/bgzi
- ./hts/csi