stride-align 0.6.0

data/lib/stride_align/core.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module StrideAlign
+  class << self
+    private
+
+    def utf8_string(value, name)
+      return nil if value.nil?
+      raise ArgumentError, "#{name} must be a String or nil" unless value.is_a?(String)
+
+      value.encode(Encoding::UTF_8)
+    end
+
+    def pairwise(query, target)
+      query_is_array = query.is_a?(Array)
+      target_is_array = target.is_a?(Array)
+      queries = query_is_array ? query : [query]
+      targets = target_is_array ? target : [target]
+
+      output_size = if queries.length == targets.length
+                      queries.length
+                    elsif queries.length == 1
+                      targets.length
+                    elsif targets.length == 1
+                      queries.length
+                    else
+                      raise ArgumentError,
+                            "query and target must have equal lengths, or one must have length one"
+                    end
+
+      output = Array.new(output_size) do |index|
+        left = queries.length == 1 ? queries[0] : queries[index]
+        right = targets.length == 1 ? targets[0] : targets[index]
+        yield(utf8_string(left, "query"), utf8_string(right, "target"))
+      end
+      query_is_array || target_is_array ? output : output[0]
+    end
+
+    def unary(input)
+      is_array = input.is_a?(Array)
+      values = is_array ? input : [input]
+      output = values.map { |value| yield(utf8_string(value, "input")) }
+      is_array ? output : output[0]
+    end
+
+    def scalar_query(query)
+      return nil if query.nil?
+      raise ArgumentError, "query must be one String or nil" unless query.is_a?(String)
+
+      query.encode(Encoding::UTF_8)
+    end
+
+    def target_array(targets)
+      raise ArgumentError, "targets must be an Array" unless targets.is_a?(Array)
+
+      targets.map { |target| utf8_string(target, "target") }
+    end
+
+    def non_negative_integer(value, name)
+      unless value.is_a?(Numeric) && value.finite? && value >= 0 && value == value.to_i
+        raise ArgumentError, "#{name} must be one non-negative integer"
+      end
+      value.to_i
+    end
+
+    def finite_number(value, name)
+      unless value.is_a?(Numeric) && value.finite?
+        raise ArgumentError, "#{name} must be one finite number"
+      end
+      value
+    end
+
+    public
+
+    def stride_levenshtein(query, target)
+      pairwise(query, target) { |left, right| __native_backend.levenshtein(left, right) }
+    end
+
+    def stride_levenshtein_similarity(query, target)
+      pairwise(query, target) do |left, right|
+        __native_backend.levenshtein_similarity(left, right)
+      end
+    end
+
+    def stride_osa(query, target)
+      pairwise(query, target) { |left, right| __native_backend.osa(left, right) }
+    end
+
+    def stride_osa_similarity(query, target)
+      pairwise(query, target) { |left, right| __native_backend.osa_similarity(left, right) }
+    end
+
+    def stride_true_damerau_levenshtein(query, target)
+      pairwise(query, target) do |left, right|
+        __native_backend.true_damerau_levenshtein(left, right)
+      end
+    end
+
+    def stride_true_damerau_levenshtein_similarity(query, target)
+      pairwise(query, target) do |left, right|
+        __native_backend.true_damerau_levenshtein_similarity(left, right)
+      end
+    end
+
+    def stride_indel(query, target)
+      pairwise(query, target) { |left, right| __native_backend.indel(left, right) }
+    end
+
+    def stride_indel_similarity(query, target)
+      pairwise(query, target) do |left, right|
+        __native_backend.indel_similarity(left, right)
+      end
+    end
+
+    def stride_hamming(query, target)
+      pairwise(query, target) { |left, right| __native_backend.hamming(left, right) }
+    end
+
+    def stride_hamming_similarity(query, target)
+      pairwise(query, target) do |left, right|
+        __native_backend.hamming_similarity(left, right)
+      end
+    end
+
+    def stride_jaro(query, target)
+      pairwise(query, target) { |left, right| __native_backend.jaro(left, right) }
+    end
+
+    def stride_jaro_winkler(query, target, prefix_weight: 0.1,
+                            prefix_threshold: 0.7, prefix_cap: 4)
+      pairwise(query, target) do |left, right|
+        __native_backend.jaro_winkler(
+          left, right, prefix_weight, prefix_threshold, prefix_cap
+        )
+      end
+    end
+
+    def stride_smith_waterman(query, target, match_score: 2,
+                              mismatch_score: -1, gap_score: -1)
+      pairwise(query, target) do |left, right|
+        __native_backend.smith_waterman(
+          left, right, match_score, mismatch_score, gap_score
+        )
+      end
+    end
+
+    def stride_needleman_wunsch(query, target, match_score: 2,
+                                mismatch_score: -1, gap_score: -1)
+      pairwise(query, target) do |left, right|
+        __native_backend.needleman_wunsch(
+          left, right, match_score, mismatch_score, gap_score
+        )
+      end
+    end
+
+    def stride_smith_waterman_affine(query, target, match_score: 2,
+                                     mismatch_score: -1,
+                                     gap_open_score: -2,
+                                     gap_extend_score: -1)
+      pairwise(query, target) do |left, right|
+        __native_backend.smith_waterman_affine(
+          left, right, match_score, mismatch_score,
+          gap_open_score, gap_extend_score
+        )
+      end
+    end
+
+    def stride_needleman_wunsch_affine(query, target, match_score: 2,
+                                       mismatch_score: -1,
+                                       gap_open_score: -2,
+                                       gap_extend_score: -1)
+      pairwise(query, target) do |left, right|
+        __native_backend.needleman_wunsch_affine(
+          left, right, match_score, mismatch_score,
+          gap_open_score, gap_extend_score
+        )
+      end
+    end
+  end
+end

data/lib/stride_align/keyboard.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module StrideAlign
+  module Keyboard
+    ASCII_CODEPOINTS = (0..127).to_a.freeze
+    ASCII_ALPHABET = ASCII_CODEPOINTS.map(&:chr).join.freeze
+    ASCII_WILDCARD = 127.chr.freeze
+
+    class << self
+      def from_npy(*args, **kwargs)
+        StrideAlign.keyboard_from_npy(*args, **kwargs)
+      end
+
+      def from_confusion_counts(*args, **kwargs)
+        StrideAlign.keyboard_from_confusion_counts(*args, **kwargs)
+      end
+
+      def available
+        StrideAlign.keyboard_available
+      end
+    end
+  end
+
+  class << self
+    def keyboard
+      Keyboard
+    end
+
+    def keyboard_from_npy(path, name: File.basename(path, File.extname(path)),
+                          alphabet: Keyboard::ASCII_ALPHABET,
+                          wildcard: Keyboard::ASCII_WILDCARD,
+                          transpose: false, gap_score: -1,
+                          gap_open: nil, gap_extend: nil)
+      raise ArgumentError, "path must be one filename" unless path.is_a?(String)
+      grid = keyboard_grid_for_alphabet(read_npy(path), alphabet)
+      grid = grid.transpose if transpose
+      SubstitutionMatrix.new(
+        name: name, alphabet: alphabet, matrix: grid,
+        gap_score: gap_score, wildcard: wildcard,
+        gap_open: gap_open, gap_extend: gap_extend
+      )
+    end
+
+    def keyboard_from_confusion_counts(counts,
+                                       alphabet: Keyboard::ASCII_ALPHABET,
+                                       name: "KEYBOARD", scale: 2,
+                                       match_margin: 4, floor: nil,
+                                       wildcard: alphabet.each_char.to_a.last,
+                                       gap_score: -1, gap_open: nil,
+                                       gap_extend: nil)
+      grid_counts = keyboard_counts_grid(counts, alphabet)
+      size = grid_counts.length
+      total = grid_counts.sum { |row| row.sum }
+      grid = if total.zero?
+               Array.new(size) do |row|
+                 Array.new(size) { |column| row == column ? 1 : -1 }
+               end
+             else
+               row_totals = grid_counts.map(&:sum)
+               column_totals = grid_counts.transpose.map(&:sum)
+               scores = Array.new(size) { Array.new(size) }
+               finite_scores = []
+               size.times do |row|
+                 size.times do |column|
+                   denominator = row_totals[row] * column_totals[column]
+                   value = if grid_counts[row][column].zero? || denominator.zero?
+                             -Float::INFINITY
+                           else
+                             scale * Math.log2(grid_counts[row][column] * total / denominator.to_f)
+                           end
+                   scores[row][column] = value
+                   finite_scores << value if value.finite?
+                 end
+               end
+               resolved_floor = floor.nil? ? (finite_scores.min&.floor || -1) : floor
+               scores.map! do |row|
+                 row.map do |value|
+                   value = resolved_floor unless value.finite?
+                   [[value.round, -128].max, 127].min
+                 end
+               end
+               size.times { |index| scores[index][index] = -128 }
+               best_substitution = scores.flatten.max
+               diagonal = [[best_substitution, 0].max + match_margin, 127].min
+               size.times { |index| scores[index][index] = diagonal }
+               scores
+             end
+      SubstitutionMatrix.new(
+        name: name, alphabet: alphabet, matrix: grid,
+        gap_score: gap_score, wildcard: wildcard,
+        gap_open: gap_open, gap_extend: gap_extend
+      )
+    end
+
+    def keyboard_available
+      directory = __data_directory("keyboard_data")
+      return [] unless File.directory?(directory)
+      Dir[File.join(directory, "*.npy")].map do |path|
+        File.basename(path, ".npy")
+      end.sort
+    end
+
+    private
+
+    def read_npy(path)
+      data = File.binread(path)
+      raise ArgumentError, "not a NumPy .npy file" unless data.byteslice(0, 6) == "\x93NUMPY".b
+      major = data.getbyte(6)
+      header_size, offset = case major
+                            when 1 then [data.byteslice(8, 2).unpack1("v"), 10]
+                            when 2, 3 then [data.byteslice(8, 4).unpack1("V"), 12]
+                            else
+                              raise ArgumentError, "unsupported NumPy .npy version"
+                            end
+      header = data.byteslice(offset, header_size)
+      unless header.match?(/["']descr["']\s*:\s*["']\|i1["']/)
+        raise ArgumentError, "keyboard .npy matrix must use signed int8 values"
+      end
+      if header.match?(/["']fortran_order["']\s*:\s*True/)
+        raise ArgumentError, "Fortran-order .npy matrices are not supported"
+      end
+      shape_text = header[/["']shape["']\s*:\s*\(([^)]*)\)/, 1]
+      raise ArgumentError, "could not read shape from keyboard .npy file" unless shape_text
+      dimensions = shape_text.split(",").map(&:strip).reject(&:empty?).map do |value|
+        Integer(value, 10)
+      end
+      unless dimensions.length == 2
+        raise ArgumentError, "keyboard .npy value must be a two-dimensional matrix"
+      end
+      payload = data.byteslice(offset + header_size, dimensions.reduce(:*))
+      unless payload && payload.bytesize == dimensions.reduce(:*)
+        raise ArgumentError, "truncated keyboard .npy payload"
+      end
+      values = payload.unpack("c*")
+      Array.new(dimensions[0]) do |row|
+        values.slice(row * dimensions[1], dimensions[1])
+      end
+    end
+
+    def keyboard_grid_for_alphabet(grid, alphabet)
+      size = alphabet.each_char.count
+      if grid.length == 128 && grid.all? { |row| row.length == 128 } && size == 127
+        grid = grid.drop(1).map { |row| row.drop(1) }
+      end
+      unless grid.length == size && grid.all? { |row| row.length == size }
+        raise ArgumentError, "keyboard matrix shape does not match the alphabet size"
+      end
+      grid
+    end
+
+    def keyboard_counts_grid(counts, alphabet)
+      symbols = alphabet.each_char.to_a
+      size = symbols.length
+      if counts.is_a?(Array) && counts.length == size &&
+         counts.all? { |row| row.is_a?(Array) && row.length == size }
+        return counts.map do |row|
+          row.map do |value|
+            unless value.is_a?(Numeric) && value.finite? && value >= 0
+              raise ArgumentError, "counts must be finite non-negative numbers"
+            end
+            value.to_f
+          end
+        end
+      end
+      unless counts.is_a?(Array) && counts.all? { |row| row.is_a?(Hash) }
+        raise ArgumentError,
+              "counts must be a numeric matrix or an Array of typed/intended/count Hashes"
+      end
+      indices = symbols.each_with_index.to_h
+      grid = Array.new(size) { Array.new(size, 0.0) }
+      counts.each do |row|
+        typed = row[:typed] || row["typed"]
+        intended = row[:intended] || row["intended"]
+        count = row.key?(:count) ? row[:count] : row["count"]
+        unless typed.is_a?(String) && intended.is_a?(String) &&
+               count.is_a?(Numeric) && count.finite? && count >= 0
+          raise ArgumentError, "confusion-count rows are invalid"
+        end
+        next unless indices.key?(typed) && indices.key?(intended)
+        grid[indices[typed]][indices[intended]] = count.to_f
+      end
+      grid
+    end
+
+    def load_bundled_keyboards
+      directory = __data_directory("keyboard_data")
+      keyboard_available.each do |name|
+        matrix = keyboard_from_npy(
+          File.join(directory, "#{name}.npy"), name: "keyboard:#{name}"
+        )
+        install_keyboard(name, matrix)
+      end
+      nil
+    end
+
+    def install_keyboard(name, matrix)
+      Keyboard.define_singleton_method(name) { matrix }
+    end
+  end
+end