minimap2-java

A Java JNI wrapper around minimap2, packaged as a single fat JAR with cross-platform native libraries (Linux, macOS, Windows) included.
It allows you to build and query .mmi indexes directly from Java without relying on external executables.

---

✨ Features

• Bundles minimap2 v2.30 C library
• Cross-platform support:
  • Linux (x86_64, aarch64)
  • macOS (x86_64, arm64)
  • Windows (x86_64)
• Fat JAR with natives included under /natives/{os-arch}/
• Minimal, thread-safe Java API

---

🚀 Installation

Add the dependency to your project (available on Maven Central):

Maven

<dependency>
  <groupId>eu.virtualparadox</groupId>
  <artifactId>minimap2-java</artifactId>
  <version>1.0.0</version>
</dependency>

Gradle (Kotlin DSL)

implementation("eu.virtualparadox:minimap2-java:1.0.0")

---

📖 Usage Example

import eu.virtualparadox.minimap2.*;
import eu.virtualparadox.minimap2.helper.*;
import eu.virtualparadox.minimap2.model.read.SequenceReadPair;
import eu.virtualparadox.minimap2.model.result.PairedAlignmentResult;

import java.io.IOException;
import java.nio.file.Path;
import java.util.List;

/**
 * Minimal usage example of the Minimap2 JNI wrapper.
 *
 * This demo:
 *  1. Initializes the native library.
 *  2. Loads or builds a reference index.
 *  3. Reads paired-end FASTQ(.gz) files.
 *  4. Runs alignment with 8 threads.
 *  5. Prints timing statistics.
 */
public class App {
    public static void main(final String[] args) throws IOException {
        // Print basic runtime information
        System.out.println("os.name=" + System.getProperty("os.name"));
        System.out.println("os.arch=" + System.getProperty("os.arch"));

        // Initialize native library (loads libmm2.so / .dylib)
        MiniMap2Initializer.initialize();
        System.out.println("MiniMap2 JNI version: " + MiniMap2Initializer.getVersion());

        // Open or create the index from reference FASTA
        try (final MiniMap2Index index = MiniMap2Index.createAndOpen(
                Path.of("data/ref.fasta"),     // reference FASTA
                Path.of("data/ref.mmi")        // corresponding .mmi index
        )) {
            System.out.println("Reference sequences: " + index.getRefNames());

            // Read paired-end FASTQ files (plain or gzipped)
            final PairedEndFastqReader reader = new PairedEndFastqReader();
            final List<SequenceReadPair> readPairs = reader.read(
                    Path.of("data/sample_R1.fastq.gz"),
                    Path.of("data/sample_R2.fastq.gz")
            );

            // Align reads with 8 threads
            try (final MiniMap2Aligner aligner = new MiniMap2Aligner(index)) {
                aligner.setThreads(8);

                final long start = System.currentTimeMillis();
                final List<PairedAlignmentResult> result = aligner.alignPairs(readPairs);
                final long elapsed = System.currentTimeMillis() - start;

                System.out.printf(
                        "Aligned %d pairs in %d ms (8 threads)%n",
                        readPairs.size(), elapsed
                );
            }
        }
    }
}

---

⚙️ Development

Build everything (Java + native + fat JAR):

mvn clean package

Run tests:

mvn test

Cross-platform builds are done via GitHub Actions (.github/workflows/build.yml).

---

📜 License

This project is licensed under the MIT License.
It bundles minimap2 (MIT licensed).