wifi-densepose/vendor/ruvector/npm/packages/rvdna/README.md

@ruvector/rvdna

DNA analysis in JavaScript. Encode sequences, translate proteins, search genomes by similarity, and read the .rvdna AI-native file format — all from Node.js or the browser.

Built on Rust via NAPI-RS for native speed. Falls back to pure JavaScript when native bindings aren't available.

npm install @ruvector/rvdna

What It Does

Function	What It Does	Native Required?
encode2bit(seq)	Pack DNA into 2-bit bytes (4 bases per byte)	No (JS fallback)
decode2bit(buf, len)	Unpack 2-bit bytes back to DNA string	No (JS fallback)
translateDna(seq)	Translate DNA to protein amino acids	No (JS fallback)
cosineSimilarity(a, b)	Cosine similarity between two vectors	No (JS fallback)
fastaToRvdna(seq, opts)	Convert FASTA to .rvdna binary format	Yes
readRvdna(buf)	Parse a .rvdna file from a Buffer	Yes
isNativeAvailable()	Check if native Rust bindings are loaded	No

Quick Start

const { encode2bit, decode2bit, translateDna, cosineSimilarity } = require('@ruvector/rvdna');

// Encode DNA to compact 2-bit format (4 bases per byte)
const packed = encode2bit('ACGTACGTACGT');
console.log(packed); // <Buffer 1b 1b 1b>

// Decode it back — lossless round-trip
const dna = decode2bit(packed, 12);
console.log(dna); // 'ACGTACGTACGT'

// Translate DNA to protein (standard genetic code)
const protein = translateDna('ATGGCCATTGTAATG');
console.log(protein); // 'MAIV'

// Compare two k-mer vectors
const sim = cosineSimilarity([1, 2, 3], [1, 2, 3]);
console.log(sim); // 1.0 (identical)

API Reference

encode2bit(sequence: string): Buffer

Packs a DNA string into 2-bit bytes. Each byte holds 4 bases: A=00, C=01, G=10, T=11. Ambiguous bases (N) map to A.

encode2bit('ACGT') // <Buffer 1b> — one byte for 4 bases
encode2bit('AAAA') // <Buffer 00>
encode2bit('TTTT') // <Buffer ff>

decode2bit(buffer: Buffer, length: number): string

Decodes 2-bit packed bytes back to a DNA string. You must pass the original sequence length since the last byte may have padding.

decode2bit(Buffer.from([0x1b]), 4) // 'ACGT'

translateDna(sequence: string): string

Translates a DNA string to a protein amino acid string using the standard genetic code. Stops at the first stop codon (TAA, TAG, TGA).

translateDna('ATGGCCATTGTAATGGGCCGCTGAAAGGGTGCCCGA')
// 'MAIVMGR' — stops at TGA stop codon

cosineSimilarity(a: number[], b: number[]): number

Returns cosine similarity between two numeric arrays. Result is between -1 and 1.

cosineSimilarity([1, 0, 0], [0, 1, 0]) // 0 (orthogonal)
cosineSimilarity([1, 2, 3], [2, 4, 6]) // 1 (parallel)

fastaToRvdna(sequence: string, options?: RvdnaOptions): Buffer

Converts a raw DNA sequence to the .rvdna binary format with pre-computed k-mer vectors. Requires native bindings.

const { fastaToRvdna, isNativeAvailable } = require('@ruvector/rvdna');

if (isNativeAvailable()) {
  const rvdna = fastaToRvdna('ACGTACGT...', { k: 11, dims: 512, blockSize: 500 });
  require('fs').writeFileSync('output.rvdna', rvdna);
}

Option	Default	Description
k	11	K-mer size for vector encoding
dims	512	Vector dimensions per block
blockSize	500	Bases per vector block

readRvdna(buffer: Buffer): RvdnaFile

Parses a .rvdna file. Returns the decoded sequence, k-mer vectors, variants, metadata, and file statistics. Requires native bindings.

const fs = require('fs');
const { readRvdna } = require('@ruvector/rvdna');

const file = readRvdna(fs.readFileSync('sample.rvdna'));

console.log(file.sequenceLength);           // 430
console.log(file.sequence.slice(0, 20));    // 'ATGGTGCATCTGACTCCTGA'
console.log(file.kmerVectors.length);       // number of vector blocks
console.log(file.stats.bitsPerBase);        // ~3.2
console.log(file.stats.compressionRatio);   // vs raw FASTA

RvdnaFile fields:

Field	Type	Description
version	number	Format version
sequenceLength	number	Number of bases
sequence	string	Decoded DNA string
kmerVectors	Array	Pre-computed k-mer vector blocks
variants	Array | null	Variant positions with genotype likelihoods
metadata	Record | null	Key-value metadata
stats.totalSize	number	File size in bytes
stats.bitsPerBase	number	Storage efficiency
stats.compressionRatio	number	Compression vs raw

The .rvdna File Format

Traditional genomic formats (FASTA, FASTQ, BAM) store raw sequences. Every time an AI model needs that data, it re-encodes everything from scratch — vectors, attention matrices, features. This takes 30-120 seconds per file.

.rvdna stores the sequence and pre-computed AI features together. Open the file and everything is ready — no re-encoding.

.rvdna file layout:

[Magic: "RVDNA\x01\x00\x00"]        8 bytes — file identifier
[Header]                              64 bytes — version, flags, offsets
[Section 0: Sequence]                 2-bit packed DNA (4 bases/byte)
[Section 1: K-mer Vectors]            HNSW-ready embeddings
[Section 2: Attention Weights]        Sparse COO matrices
[Section 3: Variant Tensor]           f16 genotype likelihoods
[Section 4: Protein Embeddings]       GNN features + contact graphs
[Section 5: Epigenomic Tracks]        Methylation + clock data
[Section 6: Metadata]                 JSON provenance + checksums

Format Comparison

	FASTA	FASTQ	BAM	CRAM	.rvdna
Encoding	ASCII (1 char/base)	ASCII + Phred	Binary + ref	Ref-compressed	2-bit packed
Bits per base	8	16	2-4	0.5-2	3.2 (seq only)
Random access	Scan from start	Scan from start	Index ~10 us	Decode ~50 us	mmap <1 us
AI features included	No	No	No	No	Yes
Vector search ready	No	No	No	No	HNSW built-in
Zero-copy mmap	No	No	Partial	No	Full
Single file	Yes	Yes	Needs .bai	Needs .crai	Yes

Platform Support

Native NAPI-RS bindings are available for these platforms:

Platform	Architecture	Package
Linux	x64 (glibc)	@ruvector/rvdna-linux-x64-gnu
Linux	ARM64 (glibc)	@ruvector/rvdna-linux-arm64-gnu
macOS	x64 (Intel)	@ruvector/rvdna-darwin-x64
macOS	ARM64 (Apple Silicon)	@ruvector/rvdna-darwin-arm64
Windows	x64	@ruvector/rvdna-win32-x64-msvc

These install automatically as optional dependencies. On unsupported platforms, basic functions (encode2bit, decode2bit, translateDna, cosineSimilarity) still work via pure JavaScript fallbacks.

WASM (WebAssembly)

rvDNA can run entirely in the browser via WebAssembly. No server needed, no data leaves the user's device.

Browser Setup

# Build from the Rust source
cd examples/dna
wasm-pack build --target web --release

This produces a pkg/ directory with .wasm and .js glue code.

Using in HTML

<script type="module">
  import init, { encode2bit, translateDna } from './pkg/rvdna.js';

  await init();  // Load the WASM module

  // Encode DNA
  const packed = encode2bit('ACGTACGTACGT');
  console.log('Packed bytes:', packed);

  // Translate to protein
  const protein = translateDna('ATGGCCATTGTAATG');
  console.log('Protein:', protein);  // 'MAIV'
</script>

Using with Bundlers (Webpack, Vite)

# For bundler targets
wasm-pack build --target bundler --release

// In your app
import { encode2bit, translateDna, fastaToRvdna } from '@ruvector/rvdna-wasm';

const packed = encode2bit('ACGTACGT');
const protein = translateDna('ATGGCCATT');

WASM Features

Feature	Status	Description
2-bit encode/decode	Available	Pack/unpack DNA sequences
Protein translation	Available	Standard genetic code
Cosine similarity	Available	Vector comparison
.rvdna read/write	Planned	Full format support in browser
HNSW search	Planned	K-mer similarity search
Variant calling	Planned	Client-side mutation detection

Target WASM binary size: <2 MB gzipped

Privacy

WASM runs entirely client-side. DNA data never leaves the browser. This makes it suitable for:

• Clinical genomics dashboards
• Patient-facing genetic reports
• Educational tools
• Offline/edge analysis on devices with no internet

TypeScript

Full TypeScript definitions are included. Import types directly:

import {
  encode2bit,
  decode2bit,
  translateDna,
  cosineSimilarity,
  fastaToRvdna,
  readRvdna,
  isNativeAvailable,
  RvdnaOptions,
  RvdnaFile,
} from '@ruvector/rvdna';

Speed

The native (Rust) backend handles these operations on real human gene data:

Operation	Time	What It Does
Single SNP call	155 ns	Bayesian genotyping at one position
Protein translation (1 kb)	23 ns	DNA to amino acids
K-mer vector (1 kb)	591 us	Full pipeline with HNSW indexing
Complete analysis (5 genes)	12 ms	All stages including .rvdna output

vs Traditional Tools

Task	Traditional Tool	Their Time	rvDNA	Speedup
K-mer counting	Jellyfish	15-30 min	2-5 sec	180-900x
Sequence similarity	BLAST	1-5 min	5-50 ms	1,200-60,000x
Variant calling	GATK	30-90 min	3-10 min	3-30x
Methylation age	R/Bioconductor	5-15 min	0.1-0.5 sec	600-9,000x

Rust Crate

The full Rust crate with all algorithms is available on crates.io:

[dependencies]
rvdna = "0.1"

See the Rust documentation for the complete API including Smith-Waterman alignment, Horvath clock, CYP2D6 pharmacogenomics, and more.

Links

• GitHub - Source code
• crates.io - Rust crate
• RuVector - Parent vector computing platform

License

MIT