minibwa 0.0.0

data/ext/minibwa/minibwa/seed.c

@@ -0,0 +1,354 @@
+#include <string.h>
+#include <assert.h>
+#include <stdio.h>
+#include "mbpriv.h"
+#include "kalloc.h"
+#include "ksort.h"
+
+#define key_sai0(a) ((a).x[0])
+KRADIX_SORT_INIT(mb_sai0, mb_sai_t, key_sai0, 8)
+
+#define key_sais(a) ((a).size)
+KRADIX_SORT_INIT(mb_sais, mb_sai_t, key_sais, 8)
+
+#define key_saii(a) ((a).info)
+KRADIX_SORT_INIT(mb_saii, mb_sai_t, key_saii, 8)
+
+#define key_anchor(a) ((a).tpos)
+KRADIX_SORT_INIT(mb_anchor, mb_anchor_t, key_anchor, 8)
+
+/***********
+ * Seeding *
+ ***********/
+
+void mb_seed_intv(void *km, const mb_bwt_t *bwt, int32_t len, const uint8_t *seq, int32_t min_len, int32_t max_sub_occ, mb_sai_v *v)
+{
+	int64_t x = 0, i, n_a0;
+	mb_sai_t p;
+
+	v->n = 0;
+	do { // pass 1: standard SMEMs
+		x = mb_bwt_smem(bwt, len, seq, x, min_len, 1, &p);
+		if (p.size > 0) {
+			Kgrow(km, mb_sai_t, v->a, v->n, v->m);
+			v->a[v->n++] = p;
+		}
+	} while (x < len);
+
+	n_a0 = v->n;
+	for (i = 0; i < n_a0; ++i) { // pass 2: sub-SMEMs
+		int32_t sub_min_len;
+		uint32_t st = v->a[i].info>>32, en = (uint32_t)v->a[i].info;
+		if (en - st < min_len * 2 || v->a[i].size > max_sub_occ)
+			continue;
+		x = st;
+		sub_min_len = (en - st) / 2 > min_len? (en - st) / 2 : min_len;
+		do { // if two SMEMs have large overlaps, we may find the same sub intervals in both. A rare case not worth optimizing
+			x = mb_bwt_smem(bwt, en, seq, x, sub_min_len, v->a[i].size + 1, &p);
+			if (p.size > v->a[i].size) {
+				Kgrow(km, mb_sai_t, v->a, v->n, v->m);
+				v->a[v->n++] = p;
+			}
+		} while (x < en);
+	}
+}
+
+void mb_seed_intv_batch(void *km, const mb_bwt_t *bwt, int32_t n_seq, const int32_t *len, uint8_t *const* seq, int32_t min_len, int32_t max_sub_occ, mb_sai_v *v)
+{ // identical to mb_seed_intv() though the order of intervals is often different
+	const int max_batch_size = 50;
+	mb_smem_entry_t *s;
+	int32_t i, j, n_s, *nv;
+
+	// first pass: standard SMEMs
+	s = Kcalloc(km, mb_smem_entry_t, max_batch_size);
+	nv = Kcalloc(km, int32_t, n_seq);
+	for (i = 0; i < n_seq; ++i) v[i].n = 0;
+	for (i = 0; i < n_seq; i += max_batch_size) {
+		int32_t en = i + max_batch_size < n_seq? i + max_batch_size : n_seq;
+		for (j = i; j < en; ++j) {
+			mb_smem_entry_t *t = &s[j - i];
+			t->min_len = min_len;
+			t->min_occ = 1;
+			t->st = 0, t->en = len[j];
+			t->q = seq[j];
+			t->v = &v[j];
+		}
+		mb_bwt_smem_batch(km, bwt, en - i, s);
+	}
+
+	// second pass; sub-SMEMs
+	for (i = 0; i < n_seq; ++i) nv[i] = v[i].n;
+	for (i = n_s = 0; i < n_seq; ++i) {
+		for (j = 0; j < nv[i]; ++j) {
+			mb_smem_entry_t *t;
+			uint32_t st = v[i].a[j].info>>32, en = (uint32_t)v[i].a[j].info;
+			if (en - st < min_len * 2 || v[i].a[j].size > max_sub_occ)
+				continue;
+			t = &s[n_s++];
+			t->min_len = (en - st) / 2 > min_len? (en - st) / 2 : min_len;
+			t->min_occ = v[i].a[j].size + 1;
+			t->st = st, t->en = en;
+			t->q = seq[i];
+			t->v = &v[i];
+			if (n_s == max_batch_size) {
+				mb_bwt_smem_batch(km, bwt, n_s, s);
+				n_s = 0;
+			}
+		}
+	}
+	if (n_s > 0)
+		mb_bwt_smem_batch(km, bwt, n_s, s);
+	kfree(km, nv);
+	kfree(km, s);
+}
+
+/*****************************
+ * Seed/anchor deduplication *
+ *****************************/
+
+static void mb_seed_sort_dedup(mb_sai_v *u)
+{
+	int64_t i, i0, j;
+	if (u->n <= 1) return;
+	// sort by ::{x[0],size,info}
+	radix_sort_mb_sai0(u->a, u->a + u->n); // sort by ::x[0]
+	for (i = 1, i0 = 0; i <= u->n; ++i) {
+		if (i == u->n || u->a[i].x[0] != u->a[i0].x[0]) {
+			if (i - i0 > 1) {
+				int64_t k, k0, n1 = i - i0;
+				mb_sai_t *a1 = &u->a[i0];
+				radix_sort_mb_sais(&u->a[i0], &u->a[i]); // sort by ::size
+				kom_reverse(mb_sai_t, n1, a1);
+				for (k = i0 + 1, k0 = i0; k <= i; ++k) {
+					if (k == i || u->a[k0].size != u->a[k].size) {
+						if (k - k0 > 1)
+							radix_sort_mb_saii(&u->a[k0], &u->a[k]); // sort by ::info
+						k0 = k;
+					}
+				}
+			}
+			i0 = i;
+		}
+	}
+	// dedup
+	for (i = 1, j = 0; i < u->n; ++i)
+		if (!(u->a[i].x[0] == u->a[j].x[0] && u->a[i].size == u->a[j].size && u->a[i].info == u->a[j].info))
+			u->a[++j] = u->a[i];
+	u->n = j + 1;
+}
+
+/* Remove duplicated anchors. The two-round seeding algorithm may lead an
+ * anchor precisely contained in a longer anchor. This routine filters out the
+ * shorter anchor. This wouldn't happen to minimap2. */
+static void mb_anchor_dedup(mb_anchor_v *v) // NB: assuming sorted by tpos
+{
+	const int max_back = 100; // to avoid quadratic behavior in the worst case
+	int64_t i, j, k;
+	for (i = 1; i < v->n; ++i) {
+		mb_anchor_t *ai = &v->a[i];
+		int64_t tsj, tsi = ai->tpos + 1 - ai->len;
+		int32_t qsj, qsi = ai->qpos + 1 - ai->len;
+		for (j = i - 1, k = 0; j >= 0 && k < max_back; --j, ++k) {
+			mb_anchor_t *aj = &v->a[j];
+			if (aj->sid != ai->sid) break;
+			if (aj->tpos < tsi) break;
+			tsj = aj->tpos + 1 - aj->len;
+			qsj = aj->qpos + 1 - aj->len;
+			if (tsj >= tsi) { // then j is contained in i
+				if (tsj - tsi == qsj - qsi) aj->flt = 1;
+			} else if (ai->tpos == aj->tpos) { // then i is contained in j
+				if (ai->qpos == aj->qpos) ai->flt = 1;
+			}
+		}
+	}
+	for (i = j = 0; i < v->n; ++i)
+		if (!v->a[i].flt) v->a[j++] = v->a[i];
+	v->n = j;
+}
+
+/************************
+ * Get contig positions *
+ ************************/
+
+typedef struct { int64_t st, en; } anchor_aux_t;
+typedef struct { int64_t a, i; } sa_aux_t;
+
+static void process_batch(void *km, const mb_idx_t *idx, const anchor_aux_t *aux, int32_t m, const sa_aux_t *b, uint64_t *a, int32_t qlen, l2b_meth_t mt, const mb_sai_v *u, mb_anchor_v *v)
+{
+	int64_t j, k;
+	for (k = 0; k < m; ++k) a[k] = b[k].a;
+	mb_bwt_sa_batch(km, idx->bwt, m, a);
+	for (k = 0; k < m; ++k) {
+		const anchor_aux_t *p = &aux[b[k].i];
+		for (j = p->st; j < p->en; ++j) {
+			int32_t qs = u->a[j].info>>32, qe = (int32_t)u->a[j].info;
+			int32_t rev, len = qe - qs;
+			int64_t tid, cst;
+			l2b_meth_t mt_anchor;
+			const l2b_ctg_t *ctg;
+			mb_anchor_t *q;
+			if (mt != L2B_METH_NONE) {
+				tid = l2b_intv2cid_meth(idx->l2b, a[k], a[k] + len, &mt_anchor, &cst, &rev);
+				if (tid < 0) continue;
+				// R1(C2T): keep c2t_f(copy0) and g2a_r(copy2); R2(G2A): keep g2a_f(copy1) and c2t_r(copy3)
+				if ((mt_anchor == mt) != (rev == 0)) continue; // filter
+			} else {
+				tid = l2b_intv2cid(idx->l2b, a[k], a[k] + len, &cst, &rev);
+				if (tid < 0) continue;
+			}
+			rev = !!rev;
+			ctg = &idx->l2b->ctg[tid];
+			Kgrow(km, mb_anchor_t, v->a, v->n, v->m);
+			q = &v->a[v->n++];
+			memset(q, 0, sizeof(*q));
+			q->sid = tid << 1 | rev;
+			q->len = len;
+			q->qpos = rev? qlen - 1 - qs : qs + len - 1;
+			q->tpos = ctg->off * 2 + ctg->len * rev + cst + len - 1; // for sorting; will be adjusted later
+		}
+	}
+}
+
+static void mb_anchor_split_meth(void *km, const l2b_t *l2b, int32_t min_len, int32_t qlen, const uint8_t *qseq0, l2b_meth_t mt0, mb_anchor_v *v)
+{
+	int64_t i, m_a = v->n * 2, n_a = 0;
+	int32_t max_len = 0;
+	mb_anchor_t *a;
+	uint8_t *tseq, *qseq2[2];
+
+	for (i = 0; i < v->n; ++i)
+		if (max_len < v->a[i].len)
+			max_len = v->a[i].len;
+	tseq = Kmalloc(km, uint8_t, max_len + qlen * 2);
+	qseq2[0] = tseq + max_len;
+	qseq2[1] = qseq2[0] + qlen;
+	memcpy(qseq2[0], qseq0, qlen);
+	for (i = 0; i < qlen; ++i)
+		qseq2[1][qlen - 1 - i] = qseq0[i] > 3? 4 : 3 - qseq0[i];
+
+	a = Kmalloc(km, mb_anchor_t, m_a);
+	for (i = 0; i < v->n; ++i) {
+		mb_anchor_t *p, *q = &v->a[i];
+		const l2b_ctg_t *ctg = &l2b->ctg[q->sid>>1];
+		int32_t rev = q->sid&1;
+		int64_t tpos = q->tpos - (ctg->off * 2 + ctg->len * rev); // NB: requiring concatenated ::tpos!!
+		int64_t ts = tpos + 1 - q->len;
+		int32_t qs = q->qpos + 1 - q->len, j, j0;
+		uint8_t t_allow, q_allow;
+		l2b_meth_t mt;
+		const uint8_t *qseq = qseq2[rev] + qs;
+		l2b_getseq(l2b, q->sid>>1, ts, ts + q->len, tseq);
+		mt = q->sid&1? l2b_meth_rev(mt0) : mt0;
+		t_allow = mt == L2B_METH_C2T? 1 : 2;
+		q_allow = mt == L2B_METH_C2T? 3 : 0;
+		for (j0 = j = 0; j <= q->len; ++j) {
+			if (j == q->len || tseq[j] == 4 || qseq[j] == 4 || (tseq[j] != qseq[j] && !(tseq[j] == t_allow && qseq[j] == q_allow))) {
+				if (j - j0 >= min_len) {
+					Kgrow(km, mb_anchor_t, a, n_a, m_a);
+					p = &a[n_a++];
+					*p = *q;
+					p->len = j - j0;
+					p->qpos = q->qpos - (q->len - j);
+					p->tpos = q->tpos - (q->len - j);
+				}
+				j0 = j + 1;
+			}
+		}
+	}
+	kfree(km, tseq);
+	Kgrow(km, mb_anchor_t, v->a, n_a, v->m);
+	memcpy(v->a, a, n_a * sizeof(mb_anchor_t));
+	v->n = n_a;
+	kfree(km, a);
+}
+
+/* Converting seed intervals to anchors. This function batches small SA
+ * intervals and calls mb_bwt_sa_batch() in process_batch(). With prefetch, the
+ * strategy noticeably improves the performance. */
+double mb_anchor(void *km, const mb_idx_t *idx, mb_sai_v *u, int32_t min_len, int32_t qlen, const uint8_t *qseq, l2b_meth_t mt, int32_t max_occ, mb_anchor_v *v)
+{
+	const int batch_size = 20;
+	int32_t n_aux, m, m_a;
+	int64_t i, i0, j, k;
+	uint64_t *a;
+	double seed_ratio = 1.0;
+	sa_aux_t *b;
+	anchor_aux_t *aux;
+
+	v->n = 0;
+	if (u->n == 0) return seed_ratio; // no anchors
+	mb_seed_sort_dedup(u);
+
+	for (i = 0, k = 0; i < u->n; ++i) // pre-calculate the size of v->a
+		k += u->a[i].size < max_occ? u->a[i].size : max_occ;
+	Kgrow(km, mb_anchor_t, v->a, k - 1, v->m); // preallocate
+
+	for (i = 1, i0 = 0, n_aux = 0; i <= u->n; ++i) // pre-compute n_aux
+		if (i == u->n || u->a[i].x[0] != u->a[i0].x[0] || u->a[i].size != u->a[i0].size)
+			++n_aux, i0 = i;
+	aux = Kmalloc(km, anchor_aux_t, n_aux);
+	for (i = 1, i0 = 0, n_aux = 0; i <= u->n; ++i) // populate aux[]
+		if (i == u->n || u->a[i].x[0] != u->a[i0].x[0] || u->a[i].size != u->a[i0].size)
+			aux[n_aux].st = i0, aux[n_aux++].en = i, i0 = i;
+
+	m_a = max_occ > batch_size? max_occ : batch_size; // max size of a[] and b[]
+	a = Kmalloc(km, uint64_t, m_a);
+	b = Kmalloc(km, sa_aux_t, m_a);
+	for (i = 0, m = 0; i < n_aux; ++i) {
+		const anchor_aux_t *p = &aux[i];
+		const mb_sai_t *q = &u->a[p->st];
+		if (q->size + m > batch_size) {
+			process_batch(km, idx, aux, m, b, a, qlen, mt, u, v);
+			m = 0;
+		}
+		if (q->size <= max_occ) { // get SA for all of them
+			for (j = 0; j < q->size; ++j)
+				b[m].a = q->x[0] + j, b[m++].i = i;
+		} else { // sample up to max_occ
+			int32_t n = 0;
+			for (j = 0; j < q->size && n < max_occ; ++n) {
+				int32_t step = (q->size - j) / (max_occ - n);
+				if (step < 1) step = 1;
+				b[m].a = q->x[0] + j, b[m++].i = i;
+				j += step;
+			}
+		}
+		assert(m <= m_a); // shouldn't happen!
+	}
+	process_batch(km, idx, aux, m, b, a, qlen, mt, u, v);
+	kfree(km, b);
+	kfree(km, a);
+	kfree(km, aux);
+
+	if (mt != L2B_METH_NONE && v->n > 0) {
+		int64_t t0, t1;
+		for (i = 0, t0 = 0; i < v->n; ++i) t0 += v->a[i].len;
+		mb_anchor_split_meth(km, idx->l2b, min_len, qlen, qseq, mt, v);
+		for (i = 0, t1 = 0; i < v->n; ++i) t1 += v->a[i].len;
+		seed_ratio = (double)t1 / t0;
+	}
+
+	radix_sort_mb_anchor(v->a, v->a + v->n);
+	for (i = 0; i < v->n; ++i) { // adjust mb_anchor_t::tpos
+		mb_anchor_t *q = &v->a[i];
+		const l2b_ctg_t *ctg = &idx->l2b->ctg[q->sid>>1];
+		q->tpos -= ctg->off * 2 + ctg->len * (q->sid&1);
+	}
+	mb_anchor_dedup(v);
+	return seed_ratio;
+}
+
+void mb_anchor_sort(const l2b_t *l2b, int64_t n_a, mb_anchor_t *a)
+{
+	int64_t i;
+	if (n_a <= 1) return;
+	for (i = 0; i < n_a; ++i) {
+		const l2b_ctg_t *ctg = &l2b->ctg[a[i].sid>>1];
+		a[i].tpos += ctg->off * 2 + ctg->len * (a[i].sid&1);
+	}
+	radix_sort_mb_anchor(a, a + n_a);
+	for (i = 0; i < n_a; ++i) {
+		const l2b_ctg_t *ctg = &l2b->ctg[a[i].sid>>1];
+		a[i].tpos -= ctg->off * 2 + ctg->len * (a[i].sid&1);
+	}
+}

data/ext/minibwa/minibwa.c

@@ -0,0 +1,67 @@
+#include "minibwa.h"
+
+VALUE rb_mMinibwa;
+VALUE rb_cMinibwaOptions;
+VALUE rb_cMinibwaIndex;
+VALUE rb_cMinibwaBuffer;
+VALUE rb_cMinibwaHit;
+VALUE rb_eMinibwaError;
+
+/*
+ * Document-module: Minibwa
+ *
+ * Ruby bindings for minibwa, a short-read aligner.
+ */
+
+/*
+ * Document-class: Minibwa::Error
+ *
+ * Raised when minibwa cannot build, load, or use an index.
+ */
+
+/* ------------------------------------------------------------------ */
+/* TypedData unwrapping helpers                                       */
+/* ------------------------------------------------------------------ */
+
+mb_opt_t *
+rb_minibwa_get_opt(VALUE self)
+{
+    mb_opt_t *opt;
+    TypedData_Get_Struct(self, mb_opt_t, &rb_minibwa_options_type, opt);
+    return opt;
+}
+
+mb_idx_t *
+rb_minibwa_get_idx(VALUE self)
+{
+    mb_idx_t *idx;
+    TypedData_Get_Struct(self, mb_idx_t, &rb_minibwa_idx_type, idx);
+    return idx;
+}
+
+mb_tbuf_t *
+rb_minibwa_get_tbuf(VALUE self)
+{
+    if (NIL_P(self)) return NULL;
+    mb_tbuf_t *b;
+    TypedData_Get_Struct(self, mb_tbuf_t, &rb_minibwa_buffer_type, b);
+    return b;
+}
+
+/* ------------------------------------------------------------------ */
+/* Init                                                               */
+/* ------------------------------------------------------------------ */
+
+RUBY_FUNC_EXPORTED void
+Init_minibwa(void)
+{
+    rb_mMinibwa = rb_define_module("Minibwa");
+
+    rb_eMinibwaError = rb_define_class_under(rb_mMinibwa, "Error", rb_eStandardError);
+
+    rb_minibwa_init_options();
+    rb_minibwa_init_index();
+    rb_minibwa_init_buffer();
+    rb_minibwa_init_hit();
+    rb_minibwa_init_index_build();
+}

data/ext/minibwa/minibwa.h

@@ -0,0 +1,51 @@
+/*
+ * Shared header for the Ruby binding: module/class handles, the per-file
+ * initializers called from Init_minibwa(), and the helpers that cross
+ * translation units.
+ */
+
+#ifndef RB_MINIBWA_H
+/* NOT "MINIBWA_H": that is upstream's guard. Sharing it would make
+ * whichever header is included second expand to nothing. */
+#define RB_MINIBWA_H 1
+
+#include "ruby.h"
+#include "ruby/thread.h"
+
+/* Upstream public API. Spelled with the directory prefix because this file
+ * shares its basename with it, and a bare "minibwa.h" from extension sources
+ * resolves to this file first. */
+#include "minibwa/minibwa.h"
+
+/* Module, classes and exception, defined in minibwa.c */
+extern VALUE rb_mMinibwa;
+extern VALUE rb_cMinibwaOptions;
+extern VALUE rb_cMinibwaIndex;
+extern VALUE rb_cMinibwaBuffer;
+extern VALUE rb_cMinibwaHit;
+extern VALUE rb_eMinibwaError;
+
+/* Per-file initializers, called in this order from Init_minibwa() */
+void rb_minibwa_init_options(void);
+void rb_minibwa_init_index(void);
+void rb_minibwa_init_buffer(void);
+void rb_minibwa_init_hit(void);
+void rb_minibwa_init_index_build(void);
+
+/* TypedData unwrapping. Each raises TypeError on a mismatched receiver;
+ * rb_minibwa_get_tbuf() maps Qnil to NULL, which mb_map() accepts. */
+mb_opt_t *rb_minibwa_get_opt(VALUE self);
+mb_idx_t *rb_minibwa_get_idx(VALUE self);
+mb_tbuf_t *rb_minibwa_get_tbuf(VALUE self);
+
+/* TypedData type descriptors, defined in their respective files */
+extern const rb_data_type_t rb_minibwa_options_type;
+extern const rb_data_type_t rb_minibwa_idx_type;
+extern const rb_data_type_t rb_minibwa_buffer_type;
+
+/* mb_hit.c: conversion to Ruby. Both take ownership -- they free hit->p
+ * for every hit, and rb_minibwa_hit_ary_new() also frees the array. */
+VALUE rb_minibwa_hit_new(const mb_idx_t *idx, mb_hit_t *hit);
+VALUE rb_minibwa_hit_ary_new(const mb_idx_t *idx, mb_hit_t *hits, int32_t n_hit);
+
+#endif /* RB_MINIBWA_H */

data/lib/minibwa/hit.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Minibwa
+  # A single alignment of one query against the reference.
+  #
+  # The fields are filled in by mb_hit.c. This file reopens the class for the
+  # values that can be derived without touching C: CIGAR formatting, the
+  # soft-clipped CIGAR rebuilt from qs/qe -- upstream only reports the aligned
+  # region -- the strand character, and #inspect.
+  #
+  # @!attribute [r] tid
+  #   @return [Integer] target contig ID.
+  # @!attribute [r] ts
+  #   @return [Integer] zero-based target start.
+  # @!attribute [r] te
+  #   @return [Integer] zero-based target end.
+  # @!attribute [r] qs
+  #   @return [Integer] zero-based query start.
+  # @!attribute [r] qe
+  #   @return [Integer] zero-based query end.
+  # @!attribute [r] score
+  #   @return [Integer] alignment score.
+  # @!attribute [r] score0
+  #   @return [Integer] best-chain score before post-processing.
+  # @!attribute [r] mlen
+  #   @return [Integer] number of matching bases.
+  # @!attribute [r] blen
+  #   @return [Integer] alignment block length.
+  # @!attribute [r] mapq
+  #   @return [Integer] mapping quality.
+  # @!attribute [r] cnt
+  #   @return [Integer] number of seed hits.
+  # @!attribute [r] n_sub
+  #   @return [Integer] number of suboptimal hits.
+  # @!attribute [r] subsc
+  #   @return [Integer] suboptimal alignment score.
+  # @!attribute [r] hash
+  #   @return [Integer] upstream hash value for tie-breaking.
+  # @!attribute [r] rev
+  #   @return [Boolean] whether the hit is on the reverse strand.
+  # @!attribute [r] proper_pair
+  #   @return [Boolean] whether the hit is part of a proper pair.
+  # @!attribute [r] sam_pri
+  #   @return [Boolean] whether the hit is primary in SAM output.
+  # @!attribute [r] flt
+  #   @return [Boolean] whether the hit is filtered.
+  # @!attribute [r] inv
+  #   @return [Boolean] whether the hit represents an inversion.
+  # @!attribute [r] split
+  #   @return [Boolean] whether the hit is split.
+  # @!attribute [r] split_inv
+  #   @return [Boolean] whether the split hit is inverted.
+  # @!attribute [r] rescued
+  #   @return [Boolean] whether paired-end rescue found the hit.
+  # @!attribute [r] frac_high
+  #   @return [Boolean] whether the high-frequency seed fraction is high.
+  # @!attribute [r] seed_ratio
+  #   @return [Boolean] whether the seed ratio flag is set.
+  # @!attribute [r] ctg
+  #   @return [String, nil] target contig name, when available.
+  # @!attribute [r] dp_score
+  #   @return [Integer] dynamic-programming score.
+  # @!attribute [r] dp_max0
+  #   @return [Integer] first dynamic-programming maximum.
+  # @!attribute [r] dp_max
+  #   @return [Integer] dynamic-programming maximum.
+  # @!attribute [r] dp_max2
+  #   @return [Integer] second dynamic-programming maximum.
+  # @!attribute [r] n_ambi
+  #   @return [Integer] number of ambiguous reference bases.
+  # @!attribute [r] cs_flag
+  #   @return [Integer] CS tag flags.
+  # @!attribute [r] cigar
+  #   @return [Array<Array(Integer, Integer)>] CIGAR operations as [length, op] pairs.
+  class Hit
+    # CIGAR operation characters indexed by operation code.
+    CIGAR_STR = 'MIDNSHP=XB'
+
+    # Returns the CIGAR string for the aligned region (no soft/hard clips).
+    def cigar_str
+      @cigar.map { |len, op| "#{len}#{CIGAR_STR[op]}" }.join
+    end
+
+    # Returns the full CIGAR string including soft clips.
+    #
+    # The query length is required because the Hit only stores the aligned
+    # region (qs/qe); the clips are derived from the difference.
+    #
+    #   hit.full_cigar_str(query.length)  # => "2S35M3S"
+    def full_cigar_str(query_len)
+      Sam.build_full_cigar(self, query_len)
+    end
+
+    # Returns the strand as '+' or '-'.
+    def strand
+      rev ? '-' : '+'
+    end
+
+    # Returns the target (reference) span length.
+    def tlen
+      te - ts
+    end
+
+    # Returns a compact representation of the most commonly inspected fields.
+    def inspect
+      attrs = %i[tid ctg ts te qs qe strand score mapq mlen blen]
+      "#<#{self.class.name} #{attrs.map { |a| "#{a}=#{send(a).inspect}" }.join(' ')}>"
+    end
+  end
+end

data/lib/minibwa/index.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Minibwa
+  # A minibwa index -- the FM-index plus the 2-bit reference -- and the object
+  # you map reads against.
+  #
+  # The class comes from mb_index.c and mb_index_build.c; this file reopens it
+  # for checking paths and permissions
+  # before calling in. That check is not cosmetic: upstream reports bad input
+  # to the index builder with kom_assert(), which abort()s the whole process
+  # instead of returning an error.
+  class Index
+    # IMPORTANT: alias the raw C methods BEFORE redefining them.
+    # Singleton methods (Index.load, etc.)
+    class << self
+      # @api private
+      alias _build build
+      # @api private
+      alias _load load
+      # @api private
+      alias _load_mmap load_mmap
+      private :_build, :_load, :_load_mmap
+    end
+    private_class_method :_build, :_load, :_load_mmap
+
+    # Instance methods (index.map, index.map_batch)
+    # @api private
+    alias _map map
+    # @api private
+    alias _map_batch map_batch
+    private :_map, :_map_batch
+
+    class << self
+      # Validates that the FASTA file exists and is readable before calling
+      # the C extension (which would abort() on bad input).
+      def build(fasta, prefix, **kwargs)
+        raise Error, "cannot read FASTA file: #{fasta}" unless File.readable?(fasta)
+
+        dir = File.dirname(prefix)
+        raise Error, "cannot write to directory: #{dir}" unless File.writable?(dir)
+
+        _build(fasta, prefix, **kwargs)
+      end
+
+      # Wraps Index.load with path validation.
+      def load(prefix, **kwargs)
+        check_prefix(prefix)
+        _load(prefix, **kwargs)
+      end
+
+      # Wraps Index.load_mmap with path validation.
+      def load_mmap(prefix, **kwargs)
+        check_prefix(prefix)
+        _load_mmap(prefix, **kwargs)
+      end
+
+      private
+
+      def check_prefix(prefix)
+        mbw = "#{prefix}.mbw"
+        return if File.readable?(mbw)
+
+        raise Error, "index not found: #{mbw}"
+      end
+    end
+
+    # Convenience method: map a single sequence with keyword arguments.
+    def map(seq, name: nil, opt: nil, buf: nil, meth: 0)
+      _map(seq, name: name, opt: opt, buf: buf, meth: meth)
+    end
+
+    # Convenience method: map a batch with keyword arguments.
+    def map_batch(seqs, names: nil, opt: nil, buf: nil)
+      _map_batch(seqs, names: names, opt: opt, buf: buf)
+    end
+  end
+end