htslib 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4fe8c4a8f710ee3b35793e997f394ba8f80e0fe5b507768de2af2c5ab1297a0
-  data.tar.gz: 1bb06ced745342f4de8665f046304364c9d419ae05eee355c3cd852d6b2b454a
+  metadata.gz: 30f42b474bc317136d665b00781fbfcb11caaf588b091e76bc86bf9cdf8d5e3f
+  data.tar.gz: d48e5f74fb0efed4de5af2955b0093d1eb7ef5ee7767bc7ee50bf3e296e7ce28
 SHA512:
-  metadata.gz: 8c7fb677d2462a1ddf4cd146d9f9962b570f39762e98d893d77f89bbbf61c92329ed8391030f772bf4f98fb3dc874edc3c365dd2d85266e1e966b24effc1715c
-  data.tar.gz: fee9ec647e3ef51e83a1aec1c62ac02c796dcfefe4d5fd6c901e4b04e4253619e7337cee651df1ece9ca58c74a7a50620befd5cd8ab823696d0f893a437bd562
+  metadata.gz: 6c1bf27a8fdc04a4a9ba678923df5bb579439c286802a5d1f2a4e6f11d7102217eafa0e4e42c2fa853e9ee82c706756315a0a1d6f97c5b5fab58ee909add4eb0
+  data.tar.gz: 59219371057e45cf31951eda2dae250acaedd12c593c09fb08f19720818be514797c57e9b45be8e1f6ea60f2fbc79fe6038a1aced6ba66d8f39a544eb6516a0a

data/README.md

@@ -1,4 +1,4 @@
-# HTSlib
+# ruby-htslib
 
 [![Gem Version](https://badge.fury.io/rb/htslib.svg)](https://badge.fury.io/rb/htslib)
 ![CI](https://github.com/kojix2/ruby-htslib/workflows/CI/badge.svg)
@@ -10,7 +10,7 @@
 
 :apple: Feel free to fork it out if you can develop it! 
 
-:bowtie: Just a prototype. Pre-alpha stage.
+:bowtie: alpha stage.
 
 ## Requirements
 
@@ -24,7 +24,7 @@
 gem install htslib
 ```
 
-If you installed htslib with Ubuntu/apt or Mac/homebrew, pkg-config will automatically detect the location of the shared library.
+If you installed htslib with Ubuntu/apt or Mac/homebrew, [pkg-config](https://github.com/ruby-gnome/pkg-config) will automatically detect the location of the shared library.
 
 Or you can set the environment variable `HTSLIBDIR`.
 
@@ -34,33 +34,39 @@ export HTSLIBDIR="/your/path/to/htslib" # libhts.so
 
 ## Usage
 
-HTS::FFI - Low-level API 
+### Low level API
+
+HTS::LibHTS
 
 ```ruby
 require 'htslib'
 
-a = HTS::FFI.hts_open("a.bam", "r")
-b = HTS::FFI.hts_get_format(a)
+a = HTS::LibHTS.hts_open("a.bam", "r")
+b = HTS::LibHTS.hts_get_format(a)
 p b[:category]
 p b[:format]
 ```
 
-A high-level API based on [hts-python](https://github.com/quinlan-lab/hts-python) is under development.
+Note: Managed struct is not used in ruby-htslib. You may need to free the memory by yourself.
+
+### High level API
+
+A high-level API based on [hts-python](https://github.com/quinlan-lab/hts-python) or [hts-nim](https://github.com/brentp/hts-nim) is under development. We will change and improve the API to make it better.
 
 ```ruby
 require 'htslib'
 
 bam = HTS::Bam.new("a.bam")
 
-bam.each do |aln|
-  p name:  aln.qname,
-    flag:  aln.flag,
-    start: aln.start + 1,
-    mpos:  aln.mate_pos + 1,
-    mqual: aln.mapping_quality,
-    seq:   aln.sequence,
-    cigar: aln.cigar.to_s,
-    qual:  aln.base_qualities.map { |i| (i + 33).chr }.join
+bam.each do |r|
+  p name:  r.qname,
+    flag:  r.flag,
+    start: r.start + 1,
+    mpos:  r.mate_pos + 1,
+    mqual: r.mapping_quality,
+    seq:   r.sequence,
+    cigar: r.cigar.to_s,
+    qual:  r.base_qualities.map { |i| (i + 33).chr }.join
 end
 ```
 
@@ -80,6 +86,9 @@ bundle exec rake htslib:build
 bundle exec rake test
 ```
 
+[c2ffi](https://github.com/rpav/c2ffi) : 
+I am trying to find a way to automatically generate a low-level API using c2ffi.
+
 ## Contributing
 
 Ruby-htslib is a library under development, so even small improvements like typofix are welcome! Please feel free to send us your pull requests.

data/lib/hts/bam.rb

@@ -3,76 +3,82 @@
 # Based on hts-python
 # https://github.com/quinlan-lab/hts-python
 
-require_relative 'bam/header'
-require_relative 'bam/cigar'
-require_relative 'bam/alignment'
+require_relative "bam/header"
+require_relative "bam/cigar"
+require_relative "bam/flag"
+require_relative "bam/record"
 
 module HTS
   class Bam
     include Enumerable
-    attr_reader :file_path, :mode, :header, :htf
+    attr_reader :file_path, :mode, :htf, :header
 
-    def initialize(file_path, mode = 'r', create_index: nil, header: nil, fasta: nil)
-      @file_path = File.expand_path(file_path)
-      File.exist?(@file_path) || raise("No such SAM/BAM file - #{@file_path}")
+    def initialize(file_path, mode = "r", create_index: nil)
+      file_path = File.expand_path(file_path)
 
-      @mode = mode
-      @htf = FFI.hts_open(@file_path, mode)
+      raise("No such SAM/BAM file - #{file_path}") unless File.exist?(file_path)
 
-      if mode[0] == 'r'
-        @idx = FFI.sam_index_load(@htf, @file_path)
-        if (@idx.null? && create_index.nil?) || create_index
-          FFI.sam_index_build(file_path, -1)
-          @idx = FFI.sam_index_load(@htf, @file_path)
-          warn 'NO querying'
-        end
-        @header = Bam::Header.new(FFI.sam_hdr_read(@htf))
-        @b = FFI.bam_init1
+      @file_path = file_path
+      @mode      = mode
+      @htf       = LibHTS.hts_open(@file_path, mode)
+      @header    = Bam::Header.new(LibHTS.sam_hdr_read(htf))
+      # FIXME: should be defined here?
+      @b         = LibHTS.bam_init1
 
+      # read
+      if mode[0] == "r"
+        # load index
+        @idx = LibHTS.sam_index_load(htf, file_path)
+        # create index
+        if create_index || (@idx.null? && create_index.nil?)
+          warn "Create index for #{file_path}"
+          LibHTS.sam_index_build(file_path, -1)
+          @idx = LibHTS.sam_index_load(@htf, @file_path)
+        end
       else
-        # FIXME
-        raise 'not implemented yet.'
-
+        # FIXME: implement
+        raise "not implemented yet."
       end
     end
 
-    def self.header_from_fasta; end
-
     def write(alns)
       alns.each do
-        FFI.sam_write1(@htf, @header, alns.b) > 0 || raise
+        LibHTS.sam_write1(htf, header, alns.b) > 0 || raise
       end
     end
 
     # Close the current file.
     def close
-      FFI.hts_close(@htf)
+      LibHTS.hts_close(htf)
     end
 
     # Flush the current file.
     def flush
       raise
-      # FFI.bgzf_flush(@htf.fp.bgzf)
+      # LibHTS.bgzf_flush(@htf.fp.bgzf)
     end
 
     def each(&block)
       # Each does not always start at the beginning of the file.
       # This is the common behavior of IO objects in Ruby.
       # This may change in the future.
-      block.call(Alignment.new(@b, @header.h)) while FFI.sam_read1(@htf, @header.h, @b) > 0
+      while LibHTS.sam_read1(htf, header.h, @b) > 0
+        record = Record.new(@b, header.h)
+        block.call(record)
+      end
     end
 
     # query [WIP]
     def query(region)
-      qiter = FFI.sam_itr_querys(@idx, @header.h, region)
+      qiter = LibHTS.sam_itr_querys(@idx, header.h, region)
       begin
-        slen = FFI.sam_itr_next(@htf, qiter, @b)
+        slen = LibHTS.sam_itr_next(htf, qiter, @b)
         while slen > 0
-          yield Alignment.new(@b, @header.h)
-          slen = FFI.sam_itr_next(@htf, qiter, @b)
+          yield Record.new(@b, header.h)
+          slen = LibHTS.sam_itr_next(htf, qiter, @b)
         end
       ensure
-        FFI.hts_itr_destroy(qiter)
+        LibHTS.hts_itr_destroy(qiter)
       end
     end
   end

data/lib/hts/bam/cigar.rb

@@ -7,7 +7,7 @@ module HTS
   class Bam
     class Cigar
       include Enumerable
-      OPS = 'MIDNSHP=XB'
+      OPS = "MIDNSHP=XB"
 
       def initialize(cigar, n_cigar)
         @c = cigar
@@ -21,8 +21,8 @@ module HTS
       def each
         @n_cigar.times do |i|
           c = @c[i].read_uint32
-          yield [FFI.bam_cigar_oplen(c),
-                 FFI.bam_cigar_opchr(c)]
+          yield [LibHTS.bam_cigar_oplen(c),
+                 LibHTS.bam_cigar_opchr(c)]
         end
       end
     end

data/lib/hts/bam/flag.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# Based on hts-nim
+# https://github.com/brentp/hts-nim/blob/master/src/hts/bam/flag.nim
+
+module HTS
+  class Bam
+    class Flag
+      def initialize(flag_value)
+        @value = flag_value # tytpe check?
+      end
+
+      attr_accessor :value
+
+      # BAM_FPAIRED        =    1
+      # BAM_FPROPER_PAIR   =    2
+      # BAM_FUNMAP         =    4
+      # BAM_FMUNMAP        =    8
+      # BAM_FREVERSE       =   16
+      # BAM_FMREVERSE      =   32
+      # BAM_FREAD1         =   64
+      # BAM_FREAD2         =  128
+      # BAM_FSECONDARY     =  256
+      # BAM_FQCFAIL        =  512
+      # BAM_FDUP           = 1024
+      # BAM_FSUPPLEMENTARY = 2048
+
+      # TODO: Enabling bitwise operations
+      # hts-nim
+      # proc `and`*(f: Flag, o: uint16): uint16 {. borrow, inline .}
+      # proc `and`*(f: Flag, o: Flag): uint16 {. borrow, inline .}
+      # proc `or`*(f: Flag, o: uint16): uint16 {. borrow .}
+      # proc `or`*(o: uint16, f: Flag): uint16 {. borrow .}
+      # proc `==`*(f: Flag, o: Flag): bool {. borrow, inline .}
+      # proc `==`*(f: Flag, o: uint16): bool {. borrow, inline .}
+      # proc `==`*(o: uint16, f: Flag): bool {. borrow, inline .}
+
+      def paired?
+        has_flag? LibHTS::BAM_FPAIRED
+      end
+
+      def proper_pair?
+        has_flag? LibHTS::BAM_FPROPER_PAIR
+      end
+
+      def unmapped?
+        has_flag? LibHTS::BAM_FUNMAP
+      end
+
+      def mate_unmapped?
+        has_flag? LibHTS::BAM_FMUNMAP
+      end
+
+      def reverse?
+        has_flag? LibHTS::BAM_FREVERSE
+      end
+
+      def mate_reverse?
+        has_flag? LibHTS::BAM_FMREVERSE
+      end
+
+      def read1?
+        has_flag? LibHTS::BAM_FREAD1
+      end
+
+      def read2?
+        has_flag? LibHTS::BAM_FREAD2
+      end
+
+      def secondary?
+        has_flag? LibHTS::BAM_FSECONDARY
+      end
+
+      def qcfail?
+        has_flag? LibHTS::BAM_FQCFAIL
+      end
+
+      def dup?
+        has_flag? LibHTS::BAM_FDUP
+      end
+
+      def supplementary?
+        has_flag? LibHTS::BAM_FSUPPLEMENTARY
+      end
+
+      def has_flag?(o)
+        (@value & o) != 0
+      end
+    end
+  end
+end

data/lib/hts/bam/header.rb

@@ -15,12 +15,12 @@ module HTS
       # FIXME: better name?
       def seqs
         Array.new(@h[:n_targets]) do |i|
-          FFI.sam_hdr_tid2name(@h, i)
+          LibHTS.sam_hdr_tid2name(@h, i)
         end
       end
 
       def text
-        FFI.sam_hdr_str(@h)
+        LibHTS.sam_hdr_str(@h)
       end
     end
   end

data/lib/hts/bam/{alignment.rb → record.rb}

@@ -5,7 +5,9 @@
 
 module HTS
   class Bam
-    class Alignment
+    class Record
+      SEQ_NT16_STR = "=ACMGRSVTWYHKDBN"
+
       def initialize(bam1_t, bam_hdr_t)
         @b = bam1_t
         @h = bam_hdr_t
@@ -19,9 +21,9 @@ module HTS
 
       def tags; end
 
-      # Read (query) name.
+      # returns the query name.
       def qname
-        FFI.bam_get_qname(@b).read_string
+        LibHTS.bam_get_qname(@b).read_string
       end
 
       # Set (query) name.
@@ -29,12 +31,9 @@ module HTS
       #   raise 'Not Implemented'
       # end
 
-      # returns the chromosome of the mate or '' if not mapped.
-      def mate_chrom
-        tid = @b[:core][:mtid]
-        return '' if tid == -1
-
-        FFI.sam_hdr_tid2name(@h, tid)
+      # returns the tid of the record or -1 if not mapped.
+      def tid
+        @b[:core][:tid]
       end
 
       # returns the tid of the mate or -1 if not mapped.
@@ -42,16 +41,6 @@ module HTS
         @b[:core][:mtid]
       end
 
-      # returns the tid of the alignment or -1 if not mapped.
-      def tid
-        @b[:core][:tid]
-      end
-
-      # mate position
-      def mate_pos
-        @b[:core][:mpos]
-      end
-
       # returns 0-based start position.
       def start
         @b[:core][:pos]
@@ -59,19 +48,33 @@ module HTS
 
       # returns end position of the read.
       def stop
-        FFI.bam_endpos @b
+        LibHTS.bam_endpos @b
+      end
+
+      # returns 0-based mate position
+      def mate_start
+        @b[:core][:mpos]
       end
+      alias mate_pos mate_start
 
       # returns the chromosome or '' if not mapped.
       def chrom
         tid = @b[:core][:tid]
-        return '' if tid == -1
+        return "" if tid == -1
+
+        LibHTS.sam_hdr_tid2name(@h, tid)
+      end
+
+      # returns the chromosome of the mate or '' if not mapped.
+      def mate_chrom
+        tid = @b[:core][:mtid]
+        return "" if tid == -1
 
-        FFI.sam_hdr_tid2name(@h, tid)
+        LibHTS.sam_hdr_tid2name(@h, tid)
       end
 
       def strand
-        FFI.bam_is_rev(@b) ? '-' : '+'
+        LibHTS.bam_is_rev(@b) ? "-" : "+"
       end
 
       # def start=(v)
@@ -90,61 +93,64 @@ module HTS
 
       # returns a `Cigar` object.
       def cigar
-        Cigar.new(FFI.bam_get_cigar(@b), @b[:core][:n_cigar])
+        Cigar.new(LibHTS.bam_get_cigar(@b), @b[:core][:n_cigar])
       end
 
       def qlen
-        FFI.bam_cigar2qlen(
+        LibHTS.bam_cigar2qlen(
           @b[:core][:n_cigar],
-          FFI.bam_get_cigar(@b)
+          LibHTS.bam_get_cigar(@b)
         )
       end
 
       def rlen
-        FFI.bam_cigar2rlen(
+        LibHTS.bam_cigar2rlen(
           @b[:core][:n_cigar],
-          FFI.bam_get_cigar(@b)
+          LibHTS.bam_get_cigar(@b)
         )
       end
 
       # return the read sequence
       def sequence
-        seq_nt16_str = '=ACMGRSVTWYHKDBN'
-        r = FFI.bam_get_seq(@b)
-        Array.new(@b[:core][:l_qseq]) do |i|
-          seq_nt16_str[FFI.bam_seqi(r, i)]
-        end.join
+        r = LibHTS.bam_get_seq(@b)
+        seq = String.new
+        (@b[:core][:l_qseq]).times do |i|
+          seq << SEQ_NT16_STR[LibHTS.bam_seqi(r, i)]
+        end
+        seq
       end
 
+      # return only the base of the requested index "i" of the query sequence.
       def base_at(n)
         n += @b[:core][:l_qseq] if n < 0
-        seq_nt16_str = '=ACMGRSVTWYHKDBN'
-        return '.' if (n >= @b[:core][:l_qseq]) || (n < 0) # eg. base_at(-1000)
+        return "." if (n >= @b[:core][:l_qseq]) || (n < 0) # eg. base_at(-1000)
 
-        r = FFI.bam_get_seq(@b)
-        seq_nt16_str[FFI.bam_seqi(r, n)]
+        r = LibHTS.bam_get_seq(@b)
+        SEQ_NT16_STR[LibHTS.bam_seqi(r, n)]
       end
 
+      # return the base qualities
       def base_qualities
-        q_ptr = FFI.bam_get_qual(@b)
+        q_ptr = LibHTS.bam_get_qual(@b)
         q_ptr.read_array_of_uint8(@b[:core][:l_qseq])
       end
 
+      # return only the base quality of the requested index "i" of the query sequence.
       def base_quality_at(n)
-        n += @b[:core][:l_qseq] if n < 0 # eg. base_quality_at(-1000)
-        return 0 if (n >= @b[:core][:l_qseq]) || (n < 0)
+        n += @b[:core][:l_qseq] if n < 0
+        return 0 if (n >= @b[:core][:l_qseq]) || (n < 0) # eg. base_quality_at(-1000)
 
-        q_ptr = FFI.bam_get_qual(@b)
+        q_ptr = LibHTS.bam_get_qual(@b)
         q_ptr.get_uint8(n)
       end
 
       def flag_str
-        FFI.bam_flag2str(flag)
+        LibHTS.bam_flag2str(@b[:core][:flag])
       end
 
       # returns a `Flag` object.
       def flag
-        @b[:core][:flag]
+        Flag.new(@b[:core][:flag])
       end
 
       # TODO: