stride-align 0.6.0

data/lib/stride_align/batch.rb

@@ -0,0 +1,705 @@
+# frozen_string_literal: true
+
+module StrideAlign
+  module Scorer
+    LEVENSHTEIN = 0
+    LEVENSHTEIN_NORMALIZED = 1
+    DAMERAU_LEVENSHTEIN = 2
+    DAMERAU_LEVENSHTEIN_NORMALIZED = 3
+    HAMMING = 4
+    HAMMING_NORMALIZED = 5
+    JARO = 6
+    JARO_WINKLER = 7
+    INDEL = 8
+    INDEL_NORMALIZED = 9
+    TRUE_DAMERAU_LEVENSHTEIN = 10
+    TRUE_DAMERAU_LEVENSHTEIN_NORMALIZED = 11
+    SMITH_WATERMAN = 12
+    SMITH_WATERMAN_NORMALIZED = 13
+    NEEDLEMAN_WUNSCH = 14
+    NEEDLEMAN_WUNSCH_NORMALIZED = 15
+  end
+
+  ScorerEntry = Struct.new(
+    :names, :id, :batch_method, :higher, :normalized, keyword_init: true
+  )
+
+  class LevenshteinScorer
+    attr_reader :query
+
+    def initialize(query)
+      @query = StrideAlign.__send__(:scalar_query, query)
+    end
+
+    def distance(target, score_cutoff: nil)
+      StrideAlign.levenshtein_score(@query, target, score_cutoff: score_cutoff)
+    end
+
+    def normalized_distance(target, score_cutoff: nil)
+      StrideAlign.levenshtein_normalized_score(
+        @query, target, score_cutoff: score_cutoff
+      )
+    end
+
+    def distances(targets, score_cutoff: nil)
+      StrideAlign.levenshtein_scores(@query, targets, score_cutoff: score_cutoff)
+    end
+
+    def normalized_distances(targets, score_cutoff: nil)
+      StrideAlign.levenshtein_normalized_scores(
+        @query, targets, score_cutoff: score_cutoff
+      )
+    end
+  end
+
+  class << self
+    def levenshtein_score(query, target, score_cutoff: nil)
+      cutoff = score_cutoff.nil? ? nil : non_negative_integer(score_cutoff, "score_cutoff")
+      pairwise(query, target) do |left, right|
+        value = __native_backend.levenshtein(left, right)
+        value.nil? || cutoff.nil? ? value : [value, cutoff + 1].min
+      end
+    end
+
+    def levenshtein_normalized_score(query, target, score_cutoff: nil)
+      cutoff = score_cutoff.nil? ? nil : non_negative_integer(score_cutoff, "score_cutoff")
+      pairwise(query, target) do |left, right|
+        if left.nil? || right.nil?
+          nil
+        else
+          distance = __native_backend.levenshtein(left, right)
+          distance = [distance, cutoff + 1].min unless cutoff.nil?
+          longest = [left.each_char.count, right.each_char.count].max
+          longest.zero? ? 1.0 : [0.0, 1.0 - distance.to_f / longest].max
+        end
+      end
+    end
+
+    def damerau_levenshtein_score(query, target)
+      stride_osa(query, target)
+    end
+
+    def damerau_levenshtein_normalized_score(query, target)
+      stride_osa_similarity(query, target)
+    end
+
+    def true_damerau_levenshtein_score(query, target)
+      stride_true_damerau_levenshtein(query, target)
+    end
+
+    def true_damerau_levenshtein_normalized_score(query, target)
+      stride_true_damerau_levenshtein_similarity(query, target)
+    end
+
+    def indel_score(query, target, score_cutoff: nil)
+      cutoff = score_cutoff.nil? ? nil : non_negative_integer(score_cutoff, "score_cutoff")
+      pairwise(query, target) do |left, right|
+        value = __native_backend.indel(left, right)
+        value.nil? || cutoff.nil? ? value : [value, cutoff + 1].min
+      end
+    end
+
+    def indel_normalized_score(query, target, score_cutoff: nil)
+      unless score_cutoff.nil? ||
+             (score_cutoff.is_a?(Numeric) && score_cutoff.finite? &&
+              score_cutoff.between?(0, 1))
+        raise ArgumentError, "score_cutoff must be between 0 and 1"
+      end
+      pairwise(query, target) do |left, right|
+        value = __native_backend.indel_similarity(left, right)
+        if value.nil? || score_cutoff.nil?
+          value
+        else
+          value < score_cutoff ? 0.0 : value
+        end
+      end
+    end
+
+    def hamming_score(query, target)
+      stride_hamming(query, target)
+    end
+
+    def hamming_normalized_score(query, target)
+      stride_hamming_similarity(query, target)
+    end
+
+    def jaro_similarity(query, target)
+      stride_jaro(query, target)
+    end
+
+    def jaro_winkler_similarity(query, target, prefix_weight: 0.1,
+                                prefix_threshold: 0.7, prefix_cap: 4)
+      stride_jaro_winkler(
+        query, target, prefix_weight: prefix_weight,
+        prefix_threshold: prefix_threshold, prefix_cap: prefix_cap
+      )
+    end
+
+    def smith_waterman_score(query, target, match_score: 2,
+                             mismatch_score: -1, gap_score: -1,
+                             gap_open_score: nil, gap_extend_score: nil,
+                             width: nil, matrix: nil)
+      if matrix
+        matrix_kwargs_clean(match_score, mismatch_score, width)
+        return matrix_pairwise(
+          query, target, matrix, true, gap_score: gap_score,
+          gap_open_score: gap_open_score, gap_extend_score: gap_extend_score
+        )
+      end
+      validate_width(width)
+      alignment_score(
+        query, target, true, match_score, mismatch_score, gap_score,
+        gap_open_score, gap_extend_score
+      )
+    end
+
+    def needleman_wunsch_score(query, target, match_score: 2,
+                               mismatch_score: -1, gap_score: -1,
+                               gap_open_score: nil, gap_extend_score: nil,
+                               width: nil, matrix: nil)
+      if matrix
+        matrix_kwargs_clean(match_score, mismatch_score, width)
+        return matrix_pairwise(
+          query, target, matrix, false, gap_score: gap_score,
+          gap_open_score: gap_open_score, gap_extend_score: gap_extend_score
+        )
+      end
+      validate_width(width)
+      alignment_score(
+        query, target, false, match_score, mismatch_score, gap_score,
+        gap_open_score, gap_extend_score
+      )
+    end
+
+    def smith_waterman_normalized_score(query, target, **kwargs)
+      match_score = kwargs.fetch(:match_score, 2)
+      raw = smith_waterman_score(query, target, **kwargs)
+      normalize_alignment_result(raw, query, target, true, match_score)
+    end
+
+    def needleman_wunsch_normalized_score(query, target, **kwargs)
+      match_score = kwargs.fetch(:match_score, 2)
+      raw = needleman_wunsch_score(query, target, **kwargs)
+      normalize_alignment_result(raw, query, target, false, match_score)
+    end
+
+    alias smith_waterman_farrar_score smith_waterman_score
+    alias smith_waterman_farrar_normalized_score smith_waterman_normalized_score
+
+    def levenshtein_scores(query, targets, score_cutoff: nil)
+      one_to_many(query, targets) do |left, right|
+        levenshtein_score(left, right, score_cutoff: score_cutoff)
+      end
+    end
+
+    def levenshtein_normalized_scores(query, targets, score_cutoff: nil)
+      one_to_many(query, targets) do |left, right|
+        levenshtein_normalized_score(left, right, score_cutoff: score_cutoff)
+      end
+    end
+
+    def damerau_levenshtein_scores(query, targets)
+      one_to_many(query, targets) { |left, right| damerau_levenshtein_score(left, right) }
+    end
+
+    def damerau_levenshtein_normalized_scores(query, targets)
+      one_to_many(query, targets) do |left, right|
+        damerau_levenshtein_normalized_score(left, right)
+      end
+    end
+
+    def true_damerau_levenshtein_scores(query, targets)
+      one_to_many(query, targets) do |left, right|
+        true_damerau_levenshtein_score(left, right)
+      end
+    end
+
+    def true_damerau_levenshtein_normalized_scores(query, targets)
+      one_to_many(query, targets) do |left, right|
+        true_damerau_levenshtein_normalized_score(left, right)
+      end
+    end
+
+    def indel_scores(query, targets, score_cutoff: nil)
+      one_to_many(query, targets) do |left, right|
+        indel_score(left, right, score_cutoff: score_cutoff)
+      end
+    end
+
+    def indel_normalized_scores(query, targets, score_cutoff: nil)
+      one_to_many(query, targets) do |left, right|
+        indel_normalized_score(left, right, score_cutoff: score_cutoff)
+      end
+    end
+
+    def hamming_scores(query, targets)
+      one_to_many(query, targets) { |left, right| hamming_score(left, right) }
+    end
+
+    def hamming_normalized_scores(query, targets)
+      one_to_many(query, targets) { |left, right| hamming_normalized_score(left, right) }
+    end
+
+    def jaro_similarities(query, targets)
+      one_to_many(query, targets) { |left, right| jaro_similarity(left, right) }
+    end
+
+    def jaro_winkler_similarities(query, targets, **kwargs)
+      one_to_many(query, targets) do |left, right|
+        jaro_winkler_similarity(left, right, **kwargs)
+      end
+    end
+
+    def smith_waterman_scores(query, targets, **kwargs)
+      one_to_many(query, targets) do |left, right|
+        smith_waterman_score(left, right, **kwargs)
+      end
+    end
+
+    def smith_waterman_normalized_scores(query, targets, **kwargs)
+      one_to_many(query, targets) do |left, right|
+        smith_waterman_normalized_score(left, right, **kwargs)
+      end
+    end
+
+    alias smith_waterman_farrar_scores smith_waterman_scores
+    alias smith_waterman_farrar_normalized_scores smith_waterman_normalized_scores
+
+    def needleman_wunsch_scores(query, targets, **kwargs)
+      one_to_many(query, targets) do |left, right|
+        needleman_wunsch_score(left, right, **kwargs)
+      end
+    end
+
+    def needleman_wunsch_normalized_scores(query, targets, **kwargs)
+      one_to_many(query, targets) do |left, right|
+        needleman_wunsch_normalized_score(left, right, **kwargs)
+      end
+    end
+
+    def levenshtein_top_k(query, targets, k: 5)
+      top_k(query, targets, Scorer::LEVENSHTEIN, k: k)
+    end
+
+    def levenshtein_normalized_top_k(query, targets, k: 5)
+      top_k(query, targets, Scorer::LEVENSHTEIN_NORMALIZED, k: k)
+    end
+
+    def damerau_levenshtein_top_k(query, targets, k: 5)
+      top_k(query, targets, Scorer::DAMERAU_LEVENSHTEIN, k: k)
+    end
+
+    def damerau_levenshtein_normalized_top_k(query, targets, k: 5)
+      top_k(query, targets, Scorer::DAMERAU_LEVENSHTEIN_NORMALIZED, k: k)
+    end
+
+    def true_damerau_levenshtein_top_k(query, targets, k: 5)
+      top_k(query, targets, Scorer::TRUE_DAMERAU_LEVENSHTEIN, k: k)
+    end
+
+    def true_damerau_levenshtein_normalized_top_k(query, targets, k: 5)
+      top_k(query, targets, Scorer::TRUE_DAMERAU_LEVENSHTEIN_NORMALIZED, k: k)
+    end
+
+    def indel_top_k(query, targets, k: 5)
+      top_k(query, targets, Scorer::INDEL, k: k)
+    end
+
+    def indel_normalized_top_k(query, targets, k: 5)
+      top_k(query, targets, Scorer::INDEL_NORMALIZED, k: k)
+    end
+
+    def hamming_top_k(query, targets, k: 5)
+      top_k(query, targets, Scorer::HAMMING, k: k)
+    end
+
+    def hamming_normalized_top_k(query, targets, k: 5)
+      top_k(query, targets, Scorer::HAMMING_NORMALIZED, k: k)
+    end
+
+    def jaro_top_k(query, targets, k: 5)
+      top_k(query, targets, Scorer::JARO, k: k)
+    end
+
+    def jaro_winkler_top_k(query, targets, k: 5, **kwargs)
+      top_k(query, targets, Scorer::JARO_WINKLER, k: k, **kwargs)
+    end
+
+    def smith_waterman_top_k(query, targets, k: 5, **kwargs)
+      top_k(query, targets, Scorer::SMITH_WATERMAN, k: k, **kwargs)
+    end
+
+    def levenshtein_best(query, targets)
+      best(query, targets, Scorer::LEVENSHTEIN)
+    end
+
+    def levenshtein_normalized_best(query, targets)
+      best(query, targets, Scorer::LEVENSHTEIN_NORMALIZED)
+    end
+
+    def damerau_levenshtein_best(query, targets)
+      best(query, targets, Scorer::DAMERAU_LEVENSHTEIN)
+    end
+
+    def damerau_levenshtein_normalized_best(query, targets)
+      best(query, targets, Scorer::DAMERAU_LEVENSHTEIN_NORMALIZED)
+    end
+
+    def true_damerau_levenshtein_best(query, targets)
+      best(query, targets, Scorer::TRUE_DAMERAU_LEVENSHTEIN)
+    end
+
+    def true_damerau_levenshtein_normalized_best(query, targets)
+      best(query, targets, Scorer::TRUE_DAMERAU_LEVENSHTEIN_NORMALIZED)
+    end
+
+    def indel_best(query, targets)
+      best(query, targets, Scorer::INDEL)
+    end
+
+    def indel_normalized_best(query, targets)
+      best(query, targets, Scorer::INDEL_NORMALIZED)
+    end
+
+    def hamming_best(query, targets)
+      best(query, targets, Scorer::HAMMING)
+    end
+
+    def hamming_normalized_best(query, targets)
+      best(query, targets, Scorer::HAMMING_NORMALIZED)
+    end
+
+    def jaro_best(query, targets)
+      best(query, targets, Scorer::JARO)
+    end
+
+    def jaro_winkler_best(query, targets, **kwargs)
+      best(query, targets, Scorer::JARO_WINKLER, **kwargs)
+    end
+
+    def smith_waterman_best(query, targets, **kwargs)
+      best(query, targets, Scorer::SMITH_WATERMAN, **kwargs)
+    end
+
+    def extract(query, targets, scorer, k: 5, **kwargs)
+      top_k(query, targets, scorer, k: k, **kwargs)
+    end
+
+    def extract_best(query, targets, scorer, **kwargs)
+      best(query, targets, scorer, **kwargs)
+    end
+
+    def cdist(queries, targets, scorer: nil, matrix: nil,
+              match_score: 2, mismatch_score: -1, gap_score: -1,
+              gap_open_score: nil, gap_extend_score: nil, width: nil,
+              tqdm: nil, cpu_count: 0, prefix_weight: 0.1,
+              prefix_threshold: 0.7, prefix_cap: 4)
+      _ = cpu_count
+      queries = target_array(queries)
+      targets = target_array(targets)
+      if scorer.nil?
+        raise ArgumentError, "cdist requires either scorer or matrix" if matrix.nil?
+        scorer = Scorer::SMITH_WATERMAN
+      end
+      entry = resolve_scorer(scorer)
+      if matrix && ![Scorer::SMITH_WATERMAN, Scorer::NEEDLEMAN_WUNSCH].include?(entry.id)
+        raise ArgumentError,
+              "matrix cdist requires a Smith-Waterman or Needleman-Wunsch scorer"
+      end
+
+      progress = nil
+      if tqdm
+        raise ArgumentError, "tqdm must respond to call" unless tqdm.respond_to?(:call)
+        progress = tqdm.call(queries.length)
+        unless progress.respond_to?(:update) && progress.respond_to?(:close)
+          raise ArgumentError, "tqdm progress object must provide update and close"
+        end
+      end
+
+      begin
+        queries.map do |query|
+          options = {}
+          if (12..15).cover?(entry.id)
+            options.merge!(
+              match_score: match_score, mismatch_score: mismatch_score,
+              gap_score: gap_score, gap_open_score: gap_open_score,
+              gap_extend_score: gap_extend_score, width: width
+            )
+            options[:matrix] = matrix if matrix
+          elsif entry.id == Scorer::JARO_WINKLER
+            options.merge!(
+              prefix_weight: prefix_weight,
+              prefix_threshold: prefix_threshold,
+              prefix_cap: prefix_cap
+            )
+          end
+          row = if options.empty?
+                  public_send(entry.batch_method, query, targets)
+                else
+                  public_send(entry.batch_method, query, targets, **options)
+                end
+          progress.update(1) if progress
+          row
+        end
+      ensure
+        progress.close if progress
+      end
+    end
+
+    def cdist_above_threshold(queries, targets, scorer: nil, threshold:,
+                              matrix: nil, **kwargs)
+      if scorer.nil? && matrix.nil?
+        raise ArgumentError, "cdist_above_threshold requires either scorer or matrix"
+      end
+      resolved = scorer.nil? ? Scorer::SMITH_WATERMAN : scorer
+      entry = resolve_scorer(resolved)
+      if matrix.nil? && !entry.normalized
+        raise ArgumentError,
+              "cdist_above_threshold requires a normalized or similarity scorer"
+      end
+      finite_number(threshold, "threshold")
+      if matrix.nil? && !threshold.between?(0, 1)
+        raise ArgumentError, "threshold must be between 0 and 1"
+      end
+      clean_queries = target_array(queries)
+      clean_targets = target_array(targets)
+      scores = cdist(
+        clean_queries, clean_targets, scorer: resolved, matrix: matrix, **kwargs
+      )
+      output = []
+      scores.each_with_index do |row, query_index|
+        row.each_with_index do |score, target_index|
+          next if score.nil? || score < threshold
+          output << {
+            score: score, query: clean_queries[query_index],
+            target: clean_targets[target_index], query_index: query_index,
+            target_index: target_index
+          }
+        end
+      end
+      output
+    end
+
+    def cdist_top_k(queries, targets, scorer: nil, k:, matrix: nil,
+                    reject_duplicates: false, **kwargs)
+      if scorer.nil? && matrix.nil?
+        raise ArgumentError, "cdist_top_k requires either scorer or matrix"
+      end
+      resolved = scorer.nil? ? Scorer::SMITH_WATERMAN : scorer
+      entry = resolve_scorer(resolved)
+      if matrix.nil? && !entry.normalized
+        raise ArgumentError, "cdist_top_k requires a normalized or similarity scorer"
+      end
+      if matrix && reject_duplicates
+        raise ArgumentError, "reject_duplicates is not supported with matrix"
+      end
+      k = non_negative_integer(k, "k")
+      clean_queries = target_array(queries)
+      clean_targets = target_array(targets)
+      scores = cdist(
+        clean_queries, clean_targets, scorer: resolved, matrix: matrix, **kwargs
+      )
+      values = []
+      scores.each_with_index do |row, query_index|
+        row.each_with_index do |score, target_index|
+          next if score.nil?
+          next if reject_duplicates && clean_queries[query_index] == clean_targets[target_index]
+          values << {
+            score: score, query: clean_queries[query_index],
+            target: clean_targets[target_index], query_index: query_index,
+            target_index: target_index
+          }
+        end
+      end
+      values.sort_by { |item| [-item[:score], item[:query_index], item[:target_index]] }
+            .first(k)
+    end
+
+    def cdist_top_k_per_query(queries, targets, scorer:, k: 5,
+                              pruning: false, cpu_count: 0,
+                              prefix_weight: 0.1,
+                              prefix_threshold: 0.7, prefix_cap: 4)
+      _ = [pruning, cpu_count]
+      clean_queries = target_array(queries)
+      clean_targets = target_array(targets)
+      entry = resolve_scorer(scorer)
+      unless entry.normalized
+        raise ArgumentError,
+              "cdist_top_k_per_query requires a normalized or similarity scorer"
+      end
+      options = entry.id == Scorer::JARO_WINKLER ? {
+        prefix_weight: prefix_weight,
+        prefix_threshold: prefix_threshold,
+        prefix_cap: prefix_cap
+      } : {}
+      clean_queries.each_with_object({}) do |query, output|
+        if entry.id == Scorer::HAMMING_NORMALIZED
+          valid = clean_targets.each_index.select do |index|
+            !query.nil? && !clean_targets[index].nil? &&
+              clean_targets[index].each_char.count == query.each_char.count
+          end
+          subset = valid.map { |index| clean_targets[index] }
+          ranked = ranked(
+            subset, hamming_normalized_scores(query, subset), k, true
+          )
+          ranked.each { |item| item[:index] = valid[item[:index]] }
+          output[query] = ranked
+        else
+          output[query] = top_k(query, clean_targets, scorer, k: k, **options)
+        end
+      end
+    end
+
+    private
+
+    def matrix_kwargs_clean(match_score, mismatch_score, width)
+      return if match_score == 2 && mismatch_score == -1 && width.nil?
+
+      raise ArgumentError,
+            "match_score, mismatch_score, and width cannot be used with matrix"
+    end
+
+    def alignment_score(query, target, local, match_score, mismatch_score,
+                        gap_score, gap_open_score, gap_extend_score)
+      open_score, extend_score = resolve_gaps(
+        gap_score, gap_open_score, gap_extend_score
+      )
+      if open_score == extend_score
+        return local ?
+          stride_smith_waterman(
+            query, target, match_score: match_score,
+            mismatch_score: mismatch_score, gap_score: open_score
+          ) :
+          stride_needleman_wunsch(
+            query, target, match_score: match_score,
+            mismatch_score: mismatch_score, gap_score: open_score
+          )
+      end
+      local ?
+        stride_smith_waterman_affine(
+          query, target, match_score: match_score,
+          mismatch_score: mismatch_score, gap_open_score: open_score,
+          gap_extend_score: extend_score
+        ) :
+        stride_needleman_wunsch_affine(
+          query, target, match_score: match_score,
+          mismatch_score: mismatch_score, gap_open_score: open_score,
+          gap_extend_score: extend_score
+        )
+    end
+
+    def normalize_alignment_result(raw, query, target, local, match_score)
+      unless match_score.is_a?(Numeric) && match_score.finite? && match_score.positive?
+        raise ArgumentError, "match_score must be positive for normalized scores"
+      end
+      unless raw.is_a?(Array)
+        return normalize_one_alignment(raw, query, target, local, match_score)
+      end
+
+      left_values = query.is_a?(Array) ? query : [query]
+      right_values = target.is_a?(Array) ? target : [target]
+      raw.each_with_index.map do |score, index|
+        left = left_values[left_values.length == 1 ? 0 : index]
+        right = right_values[right_values.length == 1 ? 0 : index]
+        normalize_one_alignment(score, left, right, local, match_score)
+      end
+    end
+
+    def normalize_one_alignment(raw, query, target, local, match_score)
+      return nil if raw.nil? || query.nil? || target.nil?
+      query_length = query.each_char.count
+      target_length = target.each_char.count
+      denominator = (local ? [query_length, target_length].min :
+                             [query_length, target_length].max) * match_score
+      return 1.0 if query_length.zero? && target_length.zero?
+      return 0.0 if denominator <= 0
+      [[raw.to_f / denominator, 0.0].max, 1.0].min
+    end
+
+    def one_to_many(query, targets)
+      query = scalar_query(query)
+      targets = target_array(targets)
+      targets.map { |target| yield(query, target) }
+    end
+
+    def scorer_table
+      @scorer_table ||= [
+        ScorerEntry.new(names: %w[levenshtein levenshtein_score], id: 0,
+                        batch_method: :levenshtein_scores, higher: false, normalized: false),
+        ScorerEntry.new(names: %w[levenshtein_normalized levenshtein_normalized_score], id: 1,
+                        batch_method: :levenshtein_normalized_scores, higher: true, normalized: true),
+        ScorerEntry.new(names: %w[damerau_levenshtein osa damerau_levenshtein_score], id: 2,
+                        batch_method: :damerau_levenshtein_scores, higher: false, normalized: false),
+        ScorerEntry.new(names: %w[damerau_levenshtein_normalized osa_normalized], id: 3,
+                        batch_method: :damerau_levenshtein_normalized_scores, higher: true, normalized: true),
+        ScorerEntry.new(names: %w[hamming hamming_score], id: 4,
+                        batch_method: :hamming_scores, higher: false, normalized: false),
+        ScorerEntry.new(names: %w[hamming_normalized hamming_normalized_score], id: 5,
+                        batch_method: :hamming_normalized_scores, higher: true, normalized: true),
+        ScorerEntry.new(names: %w[jaro jaro_similarity], id: 6,
+                        batch_method: :jaro_similarities, higher: true, normalized: true),
+        ScorerEntry.new(names: %w[jaro_winkler jaro_winkler_similarity], id: 7,
+                        batch_method: :jaro_winkler_similarities, higher: true, normalized: true),
+        ScorerEntry.new(names: %w[indel indel_score], id: 8,
+                        batch_method: :indel_scores, higher: false, normalized: false),
+        ScorerEntry.new(names: %w[indel_normalized indel_normalized_score], id: 9,
+                        batch_method: :indel_normalized_scores, higher: true, normalized: true),
+        ScorerEntry.new(names: %w[true_damerau_levenshtein true_damerau_levenshtein_score], id: 10,
+                        batch_method: :true_damerau_levenshtein_scores, higher: false, normalized: false),
+        ScorerEntry.new(names: %w[true_damerau_levenshtein_normalized], id: 11,
+                        batch_method: :true_damerau_levenshtein_normalized_scores, higher: true, normalized: true),
+        ScorerEntry.new(names: %w[sw smith_waterman smith-waterman local smith_waterman_score], id: 12,
+                        batch_method: :smith_waterman_scores, higher: true, normalized: false),
+        ScorerEntry.new(names: %w[smith_waterman_normalized], id: 13,
+                        batch_method: :smith_waterman_normalized_scores, higher: true, normalized: true),
+        ScorerEntry.new(names: %w[nw needleman_wunsch needleman-wunsch global needleman_wunsch_score], id: 14,
+                        batch_method: :needleman_wunsch_scores, higher: true, normalized: false),
+        ScorerEntry.new(names: %w[needleman_wunsch_normalized], id: 15,
+                        batch_method: :needleman_wunsch_normalized_scores, higher: true, normalized: true)
+      ].freeze
+    end
+
+    def resolve_scorer(scorer)
+      if scorer.respond_to?(:call)
+        name = scorer.respond_to?(:name) ? scorer.name.to_s : ""
+        entry = scorer_table.find { |candidate| candidate.batch_method.to_s == name }
+        return entry if entry
+        raise ArgumentError, "unknown stride-align scorer function"
+      end
+      entry = if scorer.is_a?(Numeric)
+                scorer_table.find { |candidate| candidate.id == scorer.to_i }
+              else
+                name = scorer.to_s.downcase
+                scorer_table.find { |candidate| candidate.names.include?(name) }
+              end
+      entry || raise(ArgumentError, "unknown stride-align scorer")
+    end
+
+    def ranked(targets, scores, k, higher)
+      k = non_negative_integer(k, "k")
+      values = targets.each_index.each_with_object([]) do |index, output|
+        next if scores[index].nil?
+        output << { target: targets[index], score: scores[index], index: index }
+      end
+      values.sort_by do |item|
+        [higher ? -item[:score] : item[:score], item[:index]]
+      end.first(k)
+    end
+
+    def top_k(query, targets, scorer, k: 5, **kwargs)
+      query = scalar_query(query)
+      targets = target_array(targets)
+      entry = resolve_scorer(scorer)
+      scores = if kwargs.empty?
+                 public_send(entry.batch_method, query, targets)
+               else
+                 public_send(entry.batch_method, query, targets, **kwargs)
+               end
+      ranked(targets, scores, k, entry.higher)
+    end
+
+    def best(query, targets, scorer, **kwargs)
+      top_k(query, targets, scorer, k: 1, **kwargs).first
+    end
+  end
+end