stride-align 0.6.0

data/lib/stride_align/matrices.rb

@@ -0,0 +1,403 @@
+# frozen_string_literal: true
+
+module StrideAlign
+  class SubstitutionMatrix
+    attr_reader :name, :alphabet, :matrix, :gap_score, :wildcard,
+                :gap_open, :gap_extend, :stride, :max_abs, :matrix_bytes
+
+    def initialize(name:, alphabet:, matrix:, gap_score: -4, wildcard: "X",
+                   gap_open: nil, gap_extend: nil)
+      raise ArgumentError, "name must be one String" unless name.is_a?(String)
+      raise ArgumentError, "alphabet must be one String" unless alphabet.is_a?(String)
+
+      symbols = alphabet.each_char.to_a
+      raise ArgumentError, "alphabet has duplicate symbols" unless symbols.uniq.length == symbols.length
+      unless matrix.is_a?(Array) && matrix.length == symbols.length &&
+             matrix.all? { |row| row.is_a?(Array) && row.length == symbols.length }
+        raise ArgumentError, "matrix dimensions must match the alphabet"
+      end
+
+      values = matrix.map do |row|
+        row.map do |score|
+          unless score.is_a?(Numeric) && score.finite? && score == score.to_i
+            raise ArgumentError, "matrix must contain finite integer scores"
+          end
+          score = score.to_i
+          raise ArgumentError, "matrix scores must fit in signed 8-bit integers" unless (-128..127).cover?(score)
+          score
+        end.freeze
+      end.freeze
+      unless wildcard.is_a?(String) && wildcard.each_char.count == 1 && symbols.include?(wildcard)
+        raise ArgumentError, "wildcard must be one symbol in alphabet"
+      end
+
+      @name = name.dup.freeze
+      @alphabet = alphabet.dup.freeze
+      @matrix = values
+      @gap_score = gap_score
+      @wildcard = wildcard.dup.freeze
+      @gap_open = gap_open
+      @gap_extend = gap_extend
+      @stride = symbols.length
+      @max_abs = values.flatten.map(&:abs).max || 0
+      @matrix_bytes = values.flatten.pack("c*").freeze
+      @symbol_indices = symbols.each_with_index.to_h.freeze
+      @wildcard_index = @symbol_indices.fetch(@wildcard)
+    end
+
+    def encode(sequence)
+      StrideAlign.substitution_matrix_encode(self, sequence)
+    end
+
+    def score(query, target)
+      StrideAlign.substitution_matrix_score(self, query, target)
+    end
+
+    def score_step_limit(gap_score: nil, gap_open: nil, gap_extend: nil)
+      StrideAlign.substitution_matrix_score_step_limit(
+        self, gap_score: gap_score, gap_open: gap_open, gap_extend: gap_extend
+      )
+    end
+
+    def transpose(name: "#{@name}.T")
+      StrideAlign.substitution_matrix_transpose(self, name: name)
+    end
+
+    def encode_one(sequence)
+      raise ArgumentError, "sequence must be a String" unless sequence.is_a?(String)
+
+      sequence.encode(Encoding::UTF_8).each_char.map do |symbol|
+        @symbol_indices.fetch(symbol, @wildcard_index)
+      end
+    end
+  end
+
+  class << self
+    def SubstitutionMatrix(name:, alphabet:, matrix:, gap_score: -4,
+                           wildcard: "X", gap_open: nil, gap_extend: nil)
+      SubstitutionMatrix.new(
+        name: name, alphabet: alphabet, matrix: matrix,
+        gap_score: gap_score, wildcard: wildcard,
+        gap_open: gap_open, gap_extend: gap_extend
+      )
+    end
+
+    def substitution_matrix_encode(substitution_matrix, sequence)
+      validate_substitution_matrix(substitution_matrix)
+      if sequence.is_a?(Array)
+        sequence.map { |value| value.nil? ? nil : substitution_matrix.encode_one(value) }
+      elsif sequence.nil?
+        nil
+      else
+        substitution_matrix.encode_one(sequence)
+      end
+    end
+
+    def substitution_matrix_score(substitution_matrix, query, target)
+      validate_substitution_matrix(substitution_matrix)
+      smith_waterman_score(
+        query, target, matrix: substitution_matrix,
+        gap_score: substitution_matrix.gap_score
+      )
+    end
+
+    def substitution_matrix_score_step_limit(substitution_matrix,
+                                              gap_score: nil,
+                                              gap_open: nil,
+                                              gap_extend: nil)
+      validate_substitution_matrix(substitution_matrix)
+      if gap_score.nil? && gap_open.nil? && gap_extend.nil?
+        gap_score = substitution_matrix.gap_score
+        gap_open = substitution_matrix.gap_open
+        gap_extend = substitution_matrix.gap_extend
+      end
+      [substitution_matrix.max_abs, gap_score, gap_open, gap_extend]
+        .compact.map(&:abs).max
+    end
+
+    def substitution_matrix_transpose(substitution_matrix,
+                                      name: "#{substitution_matrix.name}.T")
+      validate_substitution_matrix(substitution_matrix)
+      SubstitutionMatrix.new(
+        name: name,
+        alphabet: substitution_matrix.alphabet,
+        matrix: substitution_matrix.matrix.transpose,
+        gap_score: substitution_matrix.gap_score,
+        wildcard: substitution_matrix.wildcard,
+        gap_open: substitution_matrix.gap_open,
+        gap_extend: substitution_matrix.gap_extend
+      )
+    end
+
+    def substitution_matrix_from_ncbi_text(text, name: "<unnamed>",
+                                           gap_score: -4, wildcard: "X",
+                                           gap_open: nil, gap_extend: nil)
+      raise ArgumentError, "text must be one String" unless text.is_a?(String)
+
+      lines = text.lines.map(&:strip).reject { |line| line.empty? || line.start_with?("#") }
+      raise ArgumentError, "NCBI matrix text has no header or data rows" if lines.length < 2
+
+      header = lines.shift.split
+      rows = lines.map(&:split)
+      labels = rows.map(&:first)
+      raise ArgumentError, "NCBI matrix row labels do not match column header" unless labels == header
+
+      values = rows.map do |row|
+        raise ArgumentError, "NCBI matrix row has the wrong number of values" unless row.length == header.length + 1
+        row.drop(1).map do |token|
+          Integer(token, 10)
+        rescue ArgumentError
+          raise ArgumentError, "non-integer score in NCBI matrix row"
+        end
+      end
+      SubstitutionMatrix.new(
+        name: name, alphabet: header.join, matrix: values,
+        gap_score: gap_score, wildcard: wildcard,
+        gap_open: gap_open, gap_extend: gap_extend
+      )
+    end
+
+    def identity_matrix(alphabet, match: 1, mismatch: 0, wildcard: "*",
+                        name: "IDENTITY", gap_score: -1,
+                        gap_open: nil, gap_extend: nil)
+      raise ArgumentError, "alphabet must be a String" unless alphabet.is_a?(String)
+
+      symbols = alphabet.each_char.to_a
+      symbols << wildcard unless symbols.include?(wildcard)
+      values = Array.new(symbols.length) { Array.new(symbols.length, mismatch) }
+      symbols.length.times { |index| values[index][index] = match }
+      wildcard_index = symbols.index(wildcard)
+      symbols.length.times do |index|
+        values[wildcard_index][index] = mismatch
+        values[index][wildcard_index] = mismatch
+      end
+      SubstitutionMatrix.new(
+        name: name, alphabet: symbols.join, matrix: values,
+        gap_score: gap_score, wildcard: wildcard,
+        gap_open: gap_open, gap_extend: gap_extend
+      )
+    end
+
+    def ascii_matrix(match: 1, mismatch: -1, name: "ASCII", gap_score: -1,
+                     gap_open: nil, gap_extend: nil)
+      symbols = (0..127).map(&:chr)
+      values = Array.new(128) { Array.new(128, mismatch) }
+      128.times { |index| values[index][index] = match }
+      128.times do |index|
+        values[127][index] = mismatch
+        values[index][127] = mismatch
+      end
+      SubstitutionMatrix.new(
+        name: name, alphabet: symbols.join, matrix: values,
+        gap_score: gap_score, wildcard: symbols[127],
+        gap_open: gap_open, gap_extend: gap_extend
+      )
+    end
+
+    private
+
+    def validate_substitution_matrix(matrix)
+      raise ArgumentError, "matrix must be a SubstitutionMatrix" unless matrix.is_a?(SubstitutionMatrix)
+    end
+
+    def matrix_defaults(name)
+      if name.start_with?("BLOSUM")
+        level = name.delete_prefix("BLOSUM").to_i
+        return [-5, -10, -1] if level >= 80
+        return [-5, -11, -1] if level >= 62
+        return [-6, -13, -2] if level >= 50
+        return [-6, -14, -2]
+      end
+      if name.start_with?("PAM")
+        level = name.delete_prefix("PAM").to_i
+        return [-5, -9, -1] if level <= 30
+        return [-6, -10, -1] if level <= 120
+        return [-7, -12, -1] if level <= 200
+        return [-8, -14, -2]
+      end
+      [-5, -10, -2]
+    end
+
+    def read_ncbi_matrix(filename, name = filename, wildcard = "X")
+      defaults = matrix_defaults(name)
+      path = File.join(__data_directory("matrix_data"), filename)
+      substitution_matrix_from_ncbi_text(
+        File.read(path, mode: "r:BOM|UTF-8"), name: name,
+        gap_score: defaults[0], wildcard: wildcard,
+        gap_open: defaults[1], gap_extend: defaults[2]
+      )
+    end
+
+    def matrix_catalog_load(name)
+      @matrix_catalog ||= {}
+      return @matrix_catalog[name] if @matrix_catalog.key?(name)
+
+      value = case name
+              when "nuc44"
+                read_ncbi_matrix("NUC.4.4", "NUC.4.4", "N")
+              when "dna_match"
+                identity_matrix("ACGT", match: 5, mismatch: -4,
+                                wildcard: "N", name: "DNA_MATCH", gap_score: -5)
+              when "ascii_text"
+                ascii_matrix(name: "ASCII")
+              when /\Ablosum\d+\z/
+                label = name.upcase
+                read_ncbi_matrix(label, label)
+              when /\Apam\d+\z/
+                label = name.upcase
+                read_ncbi_matrix(label, label)
+              else
+                raise ArgumentError, "unknown substitution matrix: #{name}"
+              end
+      @matrix_catalog[name] = value
+    end
+
+    def matrix_pairwise(query, target, substitution_matrix, local,
+                        gap_score: nil, gap_open_score: nil,
+                        gap_extend_score: nil)
+      validate_substitution_matrix(substitution_matrix)
+      pairwise(query, target) do |left, right|
+        if left.nil? || right.nil?
+          nil
+        else
+          matrix_alignment(
+            left, right, substitution_matrix, local,
+            gap_score: gap_score, gap_open_score: gap_open_score,
+            gap_extend_score: gap_extend_score
+          )
+        end
+      end
+    end
+
+    def matrix_alignment(query, target, substitution_matrix, local,
+                         gap_score: nil, gap_open_score: nil,
+                         gap_extend_score: nil, traceback: false)
+      validate_substitution_matrix(substitution_matrix)
+      query = scalar_query(query)
+      target = scalar_query(target)
+      q = substitution_matrix.encode_one(query)
+      t = substitution_matrix.encode_one(target)
+      linear_gap = gap_score.nil? ? substitution_matrix.gap_score : gap_score
+      open_score = gap_open_score.nil? ? linear_gap : gap_open_score
+      extend_score = gap_extend_score.nil? ? open_score : gap_extend_score
+      rows = q.length + 1
+      columns = t.length + 1
+      negative_infinity = -Float::INFINITY
+      h = Array.new(rows) { Array.new(columns, local ? 0 : negative_infinity) }
+      vertical = Array.new(rows) { Array.new(columns, negative_infinity) }
+      horizontal = Array.new(rows) { Array.new(columns, negative_infinity) }
+      h[0][0] = 0
+      gap_cost = lambda { |length| length.zero? ? 0 : open_score + (length - 1) * extend_score }
+      unless local
+        1.upto(rows - 1) do |row|
+          h[row][0] = gap_cost.call(row)
+          vertical[row][0] = h[row][0]
+        end
+        1.upto(columns - 1) do |column|
+          h[0][column] = gap_cost.call(column)
+          horizontal[0][column] = h[0][column]
+        end
+      end
+
+      best_score = 0
+      best_row = 0
+      best_column = 0
+      1.upto(rows - 1) do |row|
+        1.upto(columns - 1) do |column|
+          vertical[row][column] = [
+            h[row - 1][column] + open_score,
+            vertical[row - 1][column] + extend_score
+          ].max
+          horizontal[row][column] = [
+            h[row][column - 1] + open_score,
+            horizontal[row][column - 1] + extend_score
+          ].max
+          diagonal = h[row - 1][column - 1] +
+                     substitution_matrix.matrix[q[row - 1]][t[column - 1]]
+          cell = [diagonal, vertical[row][column], horizontal[row][column]].max
+          cell = [0, cell].max if local
+          h[row][column] = cell
+          if local && cell > best_score
+            best_score = cell
+            best_row = row
+            best_column = column
+          end
+        end
+      end
+      unless local
+        best_score = h[rows - 1][columns - 1]
+        best_row = rows - 1
+        best_column = columns - 1
+      end
+      return best_score unless traceback
+
+      row = best_row
+      column = best_column
+      query_end = row
+      target_end = column
+      operations = []
+      state = :h
+      while row.positive? || column.positive?
+        break if local && state == :h && h[row][column] <= 0
+
+        if state == :h
+          if row.positive? && column.positive?
+            diagonal = h[row - 1][column - 1] +
+                       substitution_matrix.matrix[q[row - 1]][t[column - 1]]
+            if h[row][column] == diagonal
+              operations.unshift(q[row - 1] == t[column - 1] ? "=" : "X")
+              row -= 1
+              column -= 1
+              next
+            end
+          end
+          if row.positive? && h[row][column] == vertical[row][column]
+            state = :vertical
+            next
+          end
+          if column.positive? && h[row][column] == horizontal[row][column]
+            state = :horizontal
+            next
+          end
+          break
+        elsif state == :vertical
+          operations.unshift("D")
+          continuing = row > 1 &&
+                       vertical[row][column] == vertical[row - 1][column] + extend_score
+          row -= 1
+          state = continuing ? :vertical : :h
+        else
+          operations.unshift("I")
+          continuing = column > 1 &&
+                       horizontal[row][column] == horizontal[row][column - 1] + extend_score
+          column -= 1
+          state = continuing ? :horizontal : :h
+        end
+      end
+      operation_string = operations.join
+      cigar = operations.chunk_while { |left, right| left == right }
+                        .map { |run| "#{run.length}#{run[0]}" }.join
+      AlignmentPath.new(
+        score: best_score, query_start: row, query_end: query_end,
+        target_start: column, target_end: target_end,
+        operations: operation_string, cigar: cigar,
+        matches: operations.count("="), mismatches: operations.count("X"),
+        insertions: operations.count("I"), deletions: operations.count("D"),
+        aligned_length: operations.length
+      )
+    end
+  end
+
+  MATRIX_NAMES = (
+    [30, 35, 40, 45, 50, 55, 60, 62, 65, 70, 75, 80, 85, 90, 100]
+      .map { |level| "blosum#{level}" } +
+    (10..500).step(10).map { |level| "pam#{level}" } +
+    %w[nuc44 dna_match ascii_text]
+  ).freeze
+
+  class << self
+    MATRIX_NAMES.each do |matrix_name|
+      define_method(matrix_name) { matrix_catalog_load(matrix_name) }
+    end
+  end
+end

data/lib/stride_align/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module StrideAlign
+  VERSION = "0.6.0"
+end

data/lib/stride_align.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "stride_align/version"
+require "stride_align/_generic"
+
+module StrideAlign
+  NATIVE_MODULES = {
+    "generic" => "Generic",
+    "sse41" => "Sse41",
+    "avx2" => "Avx2",
+    "avx512bwvl" => "Avx512bwvl",
+    "neon" => "Neon",
+    "sve" => "Sve",
+    "sve2" => "Sve2",
+    "lsx" => "Lsx",
+    "lasx" => "Lasx",
+    "vsx" => "Vsx",
+    "rvv" => "Rvv"
+  }.freeze
+
+  @primary_backend = Native::Generic
+  @available_backend_names = @primary_backend.backend_candidates
+                                             .map { |name| name.freeze }
+                                             .freeze
+  requested_backend = ENV.fetch("STRIDE_ALIGN_RUBY_BACKEND", "").strip
+
+  if !requested_backend.empty? && !@available_backend_names.include?(requested_backend)
+    raise LoadError,
+          "requested stride-align backend is unavailable or CPU-incompatible: " \
+          "#{requested_backend}; compatible packaged backends: " \
+          "#{@available_backend_names.join(', ')}"
+  end
+
+  dispatch_order = requested_backend.empty? ? @available_backend_names : [requested_backend]
+  @backend_name = "generic"
+  @native_backend = @primary_backend
+
+  dispatch_order.each do |candidate|
+    break if candidate == "generic"
+
+    begin
+      require "stride_align/_#{candidate}"
+      @backend_name = candidate
+      @native_backend = Native.const_get(NATIVE_MODULES.fetch(candidate), false)
+      break
+    rescue LoadError
+      raise if !requested_backend.empty?
+    end
+  end
+
+  class << self
+    def __native_backend
+      @native_backend
+    end
+
+    def __primary_backend
+      @primary_backend
+    end
+
+    def __available_backend_names
+      @available_backend_names
+    end
+
+    def __data_directory(kind)
+      installed = File.expand_path("../data/#{kind}", __dir__)
+      return installed if File.directory?(installed)
+
+      repository_relative = case kind
+                            when "keyboard_data"
+                              "../../../src/stride_align/matrices/keyboard_data"
+                            else
+                              "../../../src/stride_align/#{kind}"
+                            end
+      File.expand_path(repository_relative, __dir__)
+    end
+  end
+end
+
+require_relative "stride_align/backend"
+require_relative "stride_align/core"
+require_relative "stride_align/matrices"
+require_relative "stride_align/alignment_path"
+require_relative "stride_align/batch"
+require_relative "stride_align/algorithms"
+require_relative "stride_align/keyboard"
+
+StrideAlign.__send__(:load_bundled_keyboards)