htslib 0.3.2 → 0.4.0

data/lib/hts/bam/header.rb

@@ -6,6 +6,39 @@ module HTS
   class Bam < Hts
     # A class for working with alignment header.
     class Header
+      HD_TAG_MAP = {
+        version: "VN",
+        sort_order: "SO",
+        group_order: "GO",
+        subsorting: "SS"
+      }.freeze
+
+      SQ_TAG_MAP = {
+        name: "SN",
+        length: "LN",
+        assembly: "AS",
+        md5: "M5",
+        species: "SP",
+        uri: "UR",
+        alt_names: "AN"
+      }.freeze
+
+      RG_TAG_MAP = {
+        id: "ID",
+        sample: "SM",
+        library: "LB",
+        platform: "PL",
+        platform_unit: "PU",
+        center: "CN",
+        description: "DS",
+        date: "DT",
+        flow_order: "FO",
+        key_sequence: "KS",
+        program: "PG",
+        insert_size: "PI",
+        molecule_topology: "PM"
+      }.freeze
+
       def self.parse(text)
         new(LibHTS.sam_hdr_parse(text.size, text))
       end
@@ -66,6 +99,11 @@ module HTS
         add_lines(...)
       end
 
+      def append(line)
+        add_lines(ensure_newline(line.to_s))
+        self
+      end
+
       # experimental
       def <<(obj)
         case obj
@@ -81,15 +119,33 @@ module HTS
       # experimental
       def find_line(type, key, value)
         ks = LibHTS::KString.new
-        r = LibHTS.sam_hdr_find_line_id(@sam_hdr, type, key, value, ks)
-        r == 0 ? ks[:s] : nil
+        begin
+          r = LibHTS.sam_hdr_find_line_id(@sam_hdr, type, key, value, ks)
+          r == 0 ? ks.read_string_copy : nil
+        ensure
+          ks.free_buffer
+        end
+      end
+
+      def find_tag(type, id_key, id_value, key)
+        ks = LibHTS::KString.new
+        begin
+          r = LibHTS.sam_hdr_find_tag_id(@sam_hdr, type, id_key, id_value, key, ks)
+          r == 0 ? ks.read_string_copy : nil
+        ensure
+          ks.free_buffer
+        end
       end
 
       # experimental
       def find_line_at(type, pos)
         ks = LibHTS::KString.new
-        r = LibHTS.sam_hdr_find_line_pos(@sam_hdr, type, pos, ks)
-        r == 0 ? ks[:s] : nil
+        begin
+          r = LibHTS.sam_hdr_find_line_pos(@sam_hdr, type, pos, ks)
+          r == 0 ? ks.read_string_copy : nil
+        ensure
+          ks.free_buffer
+        end
       end
 
       # experimental
@@ -102,6 +158,26 @@ module HTS
         LibHTS.sam_hdr_remove_line_pos(@sam_hdr, type, pos)
       end
 
+      def delete_line(type, key = nil, value = nil)
+        LibHTS.sam_hdr_remove_line_id(@sam_hdr, type, key, value).zero?
+      end
+
+      def delete_tag(type, id_key, id_value, key)
+        LibHTS.sam_hdr_remove_tag_id(@sam_hdr, type, id_key, id_value, key) == 1
+      end
+
+      def count_lines(type)
+        LibHTS.sam_hdr_count_lines(@sam_hdr, type)
+      end
+
+      def line_index(type, key)
+        LibHTS.sam_hdr_line_index(@sam_hdr, type, key)
+      end
+
+      def line_name(type, pos)
+        LibHTS.sam_hdr_line_name(@sam_hdr, type, pos)
+      end
+
       def to_s
         LibHTS.sam_hdr_str(@sam_hdr)
       end
@@ -111,6 +187,46 @@ module HTS
         name2tid(name)
       end
 
+      def update_hd(**tags)
+        pairs = merge_sam_pairs(find_line_pairs("HD", nil, nil), normalize_hd_tags(tags))
+        replace_sam_line("HD", nil, nil, pairs, %w[VN SO GO SS])
+        self
+      end
+
+      def add_sq(name, length:, **tags)
+        pairs = [["SN", name.to_s], ["LN", length.to_s]]
+        pairs.concat normalize_sq_tags(tags)
+        add_structured_sam_line("SQ", pairs, %w[SN LN AS M5 SP UR AN])
+        self
+      end
+
+      def update_sq(name, **tags)
+        pairs = merge_identified_sam_line("SQ", "SN", name.to_s, normalize_sq_tags(tags), protected_keys: ["SN"])
+        replace_sam_line("SQ", "SN", name.to_s, pairs, %w[SN LN AS M5 SP UR AN])
+        self
+      end
+
+      def remove_sq(name)
+        delete_line("SQ", "SN", name.to_s)
+      end
+
+      def add_rg(id, **tags)
+        pairs = [["ID", id.to_s]]
+        pairs.concat normalize_rg_tags(tags)
+        add_structured_sam_line("RG", pairs, %w[ID SM LB PL PU CN DS DT FO KS PG PI PM])
+        self
+      end
+
+      def update_rg(id, **tags)
+        pairs = merge_identified_sam_line("RG", "ID", id.to_s, normalize_rg_tags(tags), protected_keys: ["ID"])
+        replace_sam_line("RG", "ID", id.to_s, pairs, %w[ID SM LB PL PU CN DS DT FO KS PG PI PM])
+        self
+      end
+
+      def remove_rg(id)
+        delete_line("RG", "ID", id.to_s)
+      end
+
       # Add a @PG (program) line to the header
       # @param program_name [String] Name of the program
       # @param options [Hash] Key-value pairs for @PG tags (ID, PN, VN, CL, PP, etc.)
@@ -124,12 +240,183 @@ module HTS
       #   header.add_pg("bwa", VN: "0.7.17", CL: "bwa mem ref.fa read.fq")
       #   header.add_pg("samtools", VN: "1.15", PP: "bwa")
       def add_pg(program_name, **options)
-        args = options.flat_map { |k, v| [:string, k.to_s, :string, v.to_s] }
-        LibHTS.sam_hdr_add_pg(@sam_hdr, program_name, *args, :pointer, FFI::Pointer::NULL)
+        line = build_pg_line(program_name.to_s, options)
+        result = LibHTS.sam_hdr_add_lines(@sam_hdr, line, line.bytesize)
+        raise "Failed to add @PG line" if result < 0
+
+        self
       end
 
       private
 
+      def normalize_hd_tags(tags)
+        normalize_sam_tags(tags, HD_TAG_MAP)
+      end
+
+      def normalize_sq_tags(tags)
+        normalize_sam_tags(tags, SQ_TAG_MAP)
+      end
+
+      def normalize_rg_tags(tags)
+        normalize_sam_tags(tags, RG_TAG_MAP)
+      end
+
+      def normalize_sam_tags(tags, tag_map)
+        tags.each_with_object([]) do |(key, value), pairs|
+          sam_key = tag_map.fetch(key.to_sym, key.to_s.upcase)
+          sam_value = value.is_a?(Array) ? value.join(",") : value.to_s
+          raise ArgumentError, "Header tag keys must not be empty" if sam_key.empty?
+          if sam_value.include?("\t") || sam_value.include?("\n") || sam_value.include?("\r")
+            raise ArgumentError, "Header tag values must not contain tabs or newlines"
+          end
+
+          pairs << [sam_key, sam_value]
+        end
+      end
+
+      def parse_sam_pairs(line)
+        line.to_s.chomp.split("\t")[1..].to_a.map do |field|
+          key, value = field.split(":", 2)
+          [key, value.to_s]
+        end
+      end
+
+      def find_line_pairs(type, id_key, id_value)
+        line = find_line(type, id_key, id_value)
+        line ? parse_sam_pairs(line) : []
+      end
+
+      def merge_identified_sam_line(type, id_key, id_value, updates, protected_keys: [])
+        line = find_line(type, id_key, id_value)
+        raise ArgumentError, "Header line not found: @#{type} #{id_key}:#{id_value}" unless line
+
+        merge_sam_pairs(parse_sam_pairs(line), updates, protected_keys:)
+      end
+
+      def merge_sam_pairs(existing_pairs, updates, protected_keys: [])
+        pairs = existing_pairs.map(&:dup)
+        updates.each do |key, value|
+          if protected_keys.include?(key)
+            raise ArgumentError, "Header tag #{key} cannot be updated" unless existing_pairs.none? do |pair|
+              pair[0] == key && pair[1] == value
+            end
+
+            next
+          end
+
+          index = pairs.index { |pair| pair[0] == key }
+          if index
+            pairs[index] = [key, value]
+          else
+            pairs << [key, value]
+          end
+        end
+        pairs
+      end
+
+      def add_structured_sam_line(type, pairs, preferred_order)
+        append(build_sam_line(type, pairs, preferred_order))
+      end
+
+      def replace_sam_line(type, id_key, id_value, pairs, preferred_order)
+        delete_line(type, id_key, id_value)
+        append(build_sam_line(type, pairs, preferred_order))
+      end
+
+      def build_sam_line(type, pairs, preferred_order)
+        ordered_pairs = preferred_order.filter_map do |key|
+          pairs.find { |pair| pair[0] == key }
+        end
+        pairs.each do |pair|
+          ordered_pairs << pair unless preferred_order.include?(pair[0])
+        end
+
+        "@#{type}\t#{ordered_pairs.map { |key, value| "#{key}:#{value}" }.join("\t")}\n"
+      end
+
+      def ensure_newline(text)
+        text.end_with?("\n") ? text : "#{text}\n"
+      end
+
+      def build_pg_line(program_name, options)
+        ordered_tags = normalize_pg_tags(program_name, options)
+        "@PG\t#{ordered_tags.map { |key, value| "#{key}:#{value}" }.join("\t")}\n"
+      end
+
+      def normalize_pg_tags(program_name, options)
+        existing_ids = pg_ids
+        tag_map = options.each_with_object({}) do |(key, value), tags|
+          string_key = key.to_s
+          string_value = value.to_s
+          validate_pg_tag(string_key, string_value)
+          tags[string_key] = string_value
+        end
+
+        pg_id = resolve_pg_id(program_name, tag_map, existing_ids)
+        validate_pg_parent(tag_map["PP"], existing_ids)
+
+        ordered_tags = []
+        ordered_tags << ["ID", pg_id]
+        ordered_tags << ["PN", tag_map.fetch("PN", program_name)]
+        tag_map.each do |key, value|
+          next if %w[ID PN].include?(key)
+
+          ordered_tags << [key, value]
+        end
+        ordered_tags
+      end
+
+      def validate_pg_tag(key, value)
+        raise ArgumentError, "PG tag keys must not be empty" if key.empty?
+        return unless value.include?("\t") || value.include?("\n") || value.include?("\r")
+
+        raise ArgumentError, "PG tag values must not contain tabs or newlines"
+      end
+
+      def resolve_pg_id(program_name, tag_map, existing_ids)
+        explicit_id = tag_map["ID"]
+        if explicit_id
+          raise ArgumentError, "PG ID already exists: #{explicit_id}" if existing_ids.include?(explicit_id)
+
+          explicit_id
+        else
+          next_pg_id(program_name, existing_ids)
+        end
+      end
+
+      def validate_pg_parent(parent_id, existing_ids)
+        return unless parent_id
+        return if existing_ids.include?(parent_id)
+
+        raise ArgumentError, "Unknown PG parent: #{parent_id}"
+      end
+
+      def next_pg_id(program_name, existing_ids)
+        candidate = program_name
+        suffix = 0
+        while existing_ids.include?(candidate)
+          suffix += 1
+          candidate = "#{program_name}.#{suffix}"
+        end
+        candidate
+      end
+
+      def pg_ids
+        ids = []
+        to_s.each_line do |line|
+          next unless line.start_with?("@PG\t")
+
+          line.chomp.split("\t")[1..].each do |field|
+            key, value = field.split(":", 2)
+            next unless key == "ID" && value
+
+            ids << value
+            break
+          end
+        end
+        ids
+      end
+
       def name2tid(name)
         LibHTS.sam_hdr_name2tid(@sam_hdr, name)
       end

data/lib/hts/bam/mpileup.rb

@@ -44,6 +44,7 @@ module HTS
         n = @bams.length
         @iters       = []
         @data_blocks = [] # per-input packed pointers kept alive
+        @data_entries = {}
 
         # Prepare optional region iterators for each input
         @bams.each_with_index do |bam, i|
@@ -66,7 +67,8 @@ module HTS
         end
 
         # Build per-input packed pointer blocks so C passes them back to the callback.
-        # Layout per input: [0] hts_fp (htsFile*), [1] hdr_struct (bam_hdr_t*), [2] itr (hts_itr_t* or NULL)
+        # Keep the Ruby FFI structs in @data_entries to avoid rebuilding wrappers
+        # in the per-record callback.
         ptr_size = FFI.type_size(:pointer)
         data_array = FFI::MemoryPointer.new(:pointer, n)
         @bams.each_with_index do |bam, i|
@@ -78,18 +80,16 @@ module HTS
           block.put_pointer(1 * ptr_size, hdr_struct)
           block.put_pointer(2 * ptr_size, itr && !itr.null? ? itr : FFI::Pointer::NULL)
           @data_blocks << block
+          @data_entries[block.address] = [hts_fp, hdr_struct, itr && !itr.null? ? itr : nil]
           data_array.put_pointer(i * ptr_size, block)
         end
         # Keep the array of per-input blocks alive while the C side holds on to them
         @data_array = data_array
 
         @cb = FFI::Function.new(:int, %i[pointer pointer]) do |data, b|
-          # Unpack pointers from the per-input block
-          hts_fp     = data.get_pointer(0 * ptr_size)
-          hdr_struct = data.get_pointer(1 * ptr_size)
-          itr        = data.get_pointer(2 * ptr_size)
+          hts_fp, hdr_struct, itr = @data_entries.fetch(data.address)
           # HTSlib contract: return same as sam_itr_next/sam_read1 (>= 0 on success, -1 on EOF, < -1 on error)
-          if itr && !itr.null?
+          if itr
             HTS::LibHTS.sam_itr_next(hts_fp, itr, b)
           else
             HTS::LibHTS.sam_read1(hts_fp, hdr_struct, b)
@@ -162,7 +162,7 @@ module HTS
         end
         @iters.clear
         # Keep references to callback and data blocks to prevent GC
-        @_keepalive = [@cb, @data_array, *@data_blocks]
+        @_keepalive = [@cb, @data_array, @data_entries, *@data_blocks]
         # Close owned bams opened by this object
         @owned_bams.each do |b|
           b.close

data/lib/hts/bam/record.rb

@@ -37,12 +37,14 @@ module HTS
         return if params.all? { |x| x.nil? }
 
         if params.all?
-          c = FFI::MemoryPointer.new(:pointer)
-          m = FFI::MemoryPointer.new(:size_t)
-          LibHTS.sam_parse_cigar(cigar, FFI::Pointer::NULL, c, m)
-          cigar_array = c.read_pointer.read_array_of_uint32(m.read(:size_t))
-          cigar_pointer = FFI::MemoryPointer.new(:uint32, cigar_array.length)
-          cigar_pointer.write_array_of_uint32(cigar_array)
+          cigar_array = Cigar.parse(cigar).array
+          cigar_pointer = if cigar_array.empty?
+                            FFI::Pointer::NULL
+                          else
+                            FFI::MemoryPointer.new(:uint32, cigar_array.length).tap do |pointer|
+                              pointer.write_array_of_uint32(cigar_array)
+                            end
+                          end
           if qual.is_a?(Array)
             qual = qual.pack("C*")
           elsif qual.is_a?(String)
@@ -214,11 +216,10 @@ module HTS
       end
 
       def cigar=(str)
-        if cigar.is_a? Cigar
-          raise "Not implemented yet."
-        elsif cigar.is_a? String
-          r = LibHTS.bam_parse_cigar(str, FFI::Pointer::NULL, @bam1)
-          raise "bam_parse_cigar failed: #{r}" if r != 0
+        case str
+        when Cigar, String
+          r = LibHTS.bam_parse_cigar(str.to_s, FFI::Pointer::NULL, @bam1)
+          raise "bam_parse_cigar failed: #{r}" if r.negative?
         else
           raise ArgumentError, "cigar must be a String or Bam::Cigar"
         end
@@ -272,8 +273,11 @@ module HTS
         SEQ_NT16_STR[LibHTS.bam_seqi(r, n)]
       end
 
-      # Get the base qualities.
-      # @return [Array] base qualities
+      # Get the base qualities as raw PHRED bytes.
+      # Ruby has no UInt8 type, so this returns an Array<Integer> with values in 0..255,
+      # corresponding to Crystal's Array(UInt8).
+      # Use qual_string for the SAM-style ASCII representation.
+      # @return [Array<Integer>] base qualities as unsigned bytes
       def qual
         q_ptr = LibHTS.bam_get_qual(@bam1)
         q_ptr.read_array_of_uint8(len)
@@ -351,9 +355,13 @@ module HTS
       # @return [String] a string representation of the alignment.
       def to_s
         kstr = LibHTS::KString.new
-        raise "Failed to format bam record" if LibHTS.sam_format1(@header.struct, @bam1, kstr) == -1
+        begin
+          raise "Failed to format bam record" if LibHTS.sam_format1(@header.struct, @bam1, kstr) == -1
 
-        kstr[:s]
+          kstr.read_string_copy
+        ensure
+          kstr.free_buffer
+        end
       end
 
       private

data/lib/hts/bam.rb

@@ -31,6 +31,25 @@ module HTS
       file
     end
 
+    def self.build_index(file_name, index_name = nil, min_shift = 0, threads = 0, verbose = true)
+      if verbose
+        if index_name
+          warn "Create index for #{file_name} to #{index_name}"
+        else
+          warn "Create index for #{file_name}"
+        end
+      end
+
+      case LibHTS.sam_index_build3(file_name, index_name, min_shift, threads)
+      when 0 # successful
+      when -1 then raise "indexing failed"
+      when -2 then raise "opening #{file_name} failed"
+      when -3 then raise "format not indexable"
+      when -4 then raise "failed to create and/or save the index"
+      else raise "unknown error"
+      end
+    end
+
     def initialize(file_name, mode = "r", index: nil, fai: nil, threads: nil,
                    build_index: false)
       if block_given?
@@ -74,22 +93,10 @@ module HTS
       @start_position = tell
     end
 
-    def build_index(index_name = nil, min_shift: 0, threads: 2)
+    def build_index(index_name = nil, min_shift: 0, verbose: true)
       check_closed
 
-      if index_name
-        warn "Create index for #{@file_name} to #{index_name}"
-      else
-        warn "Create index for #{@file_name}"
-      end
-      case LibHTS.sam_index_build3(@file_name, index_name, min_shift, @nthreads || threads)
-      when 0 # successful
-      when -1 then raise "indexing failed"
-      when -2 then raise "opening #{@file_name} failed"
-      when -3 then raise "format not indexable"
-      when -4 then raise "failed to create and/or save the index"
-      else raise "unknown error"
-      end
+      self.class.build_index(@file_name, index_name, min_shift, @nthreads || 0, verbose)
       self # for method chaining
     end
 
@@ -317,15 +324,14 @@ module HTS
       check_closed
       return to_enum(__method__) unless block_given?
 
-      while LibHTS.sam_read1(@hts_file, header, bam1 = LibHTS.bam_init1) != -1
-        record = Record.new(header, bam1)
-        yield record
-      end
+      bam1 = LibHTS.bam_init1
+      record = Record.new(header, bam1)
+      yield record.dup while LibHTS.sam_read1(@hts_file, header, bam1) != -1
       self
     end
 
     def queryi_reuse(tid, beg, end_, &block)
-      return to_enum(__method__, region, beg, end_) unless block_given?
+      return to_enum(__method__, tid, beg, end_) unless block_given?
 
       qiter = LibHTS.sam_itr_queryi(@idx, tid, beg, end_)
       raise "Failed to query region: #{tid} #{beg} #{end_}" if qiter.null?
@@ -369,20 +375,24 @@ module HTS
       bam1 = LibHTS.bam_init1
       record = Record.new(header, bam1)
       begin
-        yield record while LibHTS.sam_itr_next(@hts_file, qiter, bam1) > 0
+        while (slen = LibHTS.sam_itr_next(@hts_file, qiter, bam1)) >= 0
+          yield record
+        end
+        raise if slen < -1
       ensure
         LibHTS.hts_itr_destroy(qiter)
       end
     end
 
     def query_copy(qiter)
+      bam1 = LibHTS.bam_init1
+      record = Record.new(header, bam1)
       loop do
-        bam1 = LibHTS.bam_init1
         slen = LibHTS.sam_itr_next(@hts_file, qiter, bam1)
         break if slen == -1
         raise if slen < -1
 
-        yield Record.new(header, bam1)
+        yield record.dup
       end
     ensure
       LibHTS.hts_itr_destroy(qiter)

data/lib/hts/bcf/errors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module HTS
+  class Bcf < Hts
+    class Error < HTS::Error; end
+
+    class OpenError < Error; end
+    class IndexError < Error; end
+    class MissingIndexError < IndexError; end
+    class QueryError < Error; end
+    class HeaderError < Error; end
+    class SubsetError < HeaderError; end
+    class UnknownSampleError < SubsetError; end
+    class FieldError < Error; end
+    class InfoError < FieldError; end
+    class InfoTypeError < InfoError; end
+    class InfoReadError < InfoError; end
+    class InfoUpdateError < InfoError; end
+    class UnsupportedInfoOperationError < InfoError; end
+    class FormatError < FieldError; end
+    class FormatDefinitionError < FormatError; end
+    class FormatTypeError < FormatError; end
+    class FormatReadError < FormatError; end
+    class FormatUpdateError < FormatError; end
+    class UnsupportedFormatOperationError < FormatError; end
+  end
+end