DOCSEARCHbyAlgolia
Submit Docs

strobealign

repository·main·Indexed 42 days ago

https://github.com/ksahlin/strobealign

A high-performance short-read aligner designed for speed and accuracy, particularly for reads between 100 and 500 bp. It utilizes a unique seeding mechanism called strobemers to achieve ultra-fast alignment. Version 0.18.0 supports paired-end, single-end, and interleaved reads, producing SAM output by default or PAF output in mapping-only mode.

Tokens
19K
Snippets
52
Records
79
Agent score
51%

What's inside strobealign

  1. Evaluate strobealign performance and accuracy

    main

    Strobealign (v0.7) is a fast short-read aligner designed for high accuracy and speed. Performance benchmarks indicate:

    • Mapping Accuracy & Runtime: On most datasets (except 2x100), strobealign provides comparable or higher accuracy than BWA-MEM while being substantially faster. On REPEATS datasets, it is twice as fast as BWA-MEM and comparable to minimap2.
    • Variant Calling (Simulated REPEATS): In repetitive genomes, strobealign is generally the fastest tool and achieves the highest SNV precision, as well as the highest precision, recall, and F-score for indels.
    • Variant Calling (Simulated SIM3): For SIM3 datasets, strobealign provides indel predictions with the highest recall and precision, closely following BWA-MEM's SNV performance.
    • Variant Calling (Biological GIAB): On GIAB HG004 datasets, strobealign achieves the highest SNV F-score among benchmarked aligners, characterized by high precision at the cost of slightly lower recall.
    • Runtime: Across large datasets (SIM150, SIM250, BIO150, BIO250), strobealign is consistently the fastest aligner when using multiple threads (e.g., 16 threads).

  2. How strobealign indexing and profiles work

    main

    Strobealign uses a dynamic seed size based on the expected read length. It selects from several canonical read lengths: 50, 75, 100, 125, 150, 250, and 400 bp.

    By default, strobealign estimates the average read length from the first 500 reads of the input and selects the closest canonical profile. You can override this with -r or use the -P noisy profile for error-prone data.

    Multi-context seeds: Since v0.16.0, strobealign uses multi-context seeds by default. If a full seed (two strobemers) is not found, it falls back to searching for a 'partial seed' (one strobemer). This improves mapping rates for reads up to ~200 nt. You can enable a more accurate per-seed fallback mode using the --mcs flag.

  3. Use the SSW Java wrapper

    main

    The Java wrapper consists of libsswjni.so (the native library) and ssw.jar (the Java interface).

    Loading the Native Library

    Before invoking native methods, you must load the native library. Ensure the directory containing libsswjni.so is in your LD_LIBRARY_PATH or specify it via the JVM argument -Djava.library.path.

    Core Components

    • ssw.Aligner: A thread-safe static class providing two align() methods:
      • align() (Direct): Exposes the SSW C library directly. Warning: No error checking is performed; misuse is likely to crash the JVM.
      • align() (User-friendly): A simpler API that performs basic error checking.
    • ssw.Alignment: A class that stores alignment results. Its fields correspond directly to the C s_align struct.
    • ssw.Example: A Java version of the example_c sample code.

    Running the Example

    You can execute the included sample code by running:

    java -jar ssw.jar
    // Example of loading the library
System.loadLibrary("sswjni");

  4. Align paired-end, single-end, and interleaved reads

    main

    Strobealign produces SAM output by default. It is highly recommended to pipe the output directly into samtools to avoid large intermediate SAM files and reduce disk I/O.

    Paired-end reads:

    strobealign -t 8 ref.fa reads.1.fastq.gz reads.2.fastq.gz | samtools sort -o sorted.bam

    Single-end reads:

    strobealign -t 8 ref.fa reads.fastq.gz | samtools sort -o sorted.bam

    Mixed/Interleaved reads: Use the --interleaved flag if the input file contains both single and paired-end reads.

    strobealign -t 8 ref.fa --interleaved reads.fastq.gz | samtools sort -o sorted.bam

  5. Use abundance estimation mode for metagenomic binning

    main

    The --aemb flag switches strobealign into abundance estimation mode. Instead of SAM or PAF, it outputs a single TSV table where each row represents a reference contig.

    Output Format:

    • Column 1: Reference/contig ID
    • Column 2: Abundance (number of bases mapped to a contig divided by the contig length).

    Example:

    strobealign -t 8 --aemb ref.fa reads.1.fastq.gz reads.2.fastq.gz > abundances.tsv

  6. Set up the Python interface (ssw_lib.py)

    main

    The ssw_lib.py wrapper allows using the SSW C library within Python.

    1. Compile the Shared Library

    First, compile the C code into a dynamic shared library (libssw.so) using gcc:

    gcc -Wall -O3 -pipe -fPIC -shared -rdynamic -o libssw.so ssw.c ssw.h

    2. Configure Environment

    Place libssw.so and ssw_lib.py in your project directory. You must ensure the system can find the shared library by updating LD_LIBRARY_PATH:

    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:path_of_libssw.so

    3. Use in Python

    Import the CSsw class to access the API:

    from ssw_lib import CSsw
# Initialize and call APIs
ssw = CSsw()
    gcc -Wall -O3 -pipe -fPIC -shared -rdynamic -o libssw.so ssw.c ssw.h

  8. Install strobealign from source

    main

    To compile from source, you need a recent version of Rust (via rustup). Note that default Rust versions in Debian/Ubuntu may be too old. Compile using the following command to optimize for your local CPU architecture:

    RUSTFLAGS='-C target-cpu=native' cargo build --release

    The resulting binary will be located at target/release/strobealign.

  9. Build the Java interface for SSW

    main

    The Java interface is a JNI (Java Native Interface) wrapper around the native C implementation. It is not built by default and must be built explicitly using the make java command.

    Prerequisites:

    1. javac and jar must be in your PATH.
    2. JAVA_HOME must be set to an installed JRE or JDK, OR the JNI include directory must be included in the C system library search path.

    Build Steps:

    1. Navigate to the src directory.
    2. Run make java.

    Outputs:

    • libsswjni.so: The native C library exposing JNI entry points.
    • ssw.jar: The Java library containing the interface.
    make java

  10. Set up the Python interface for SSW

    main

    To use the Python wrapper ssw_lib.py, you must first compile the C library as a shared object.

    1. Compile the shared library:
    gcc -Wall -O3 -pipe -fPIC -shared -rdynamic -o libssw.so ssw.c ssw.h
    1. Place libssw.so and ssw_lib.py in your project directory or in your sys.path.
    2. Ensure the directory containing libssw.so is in your LD_LIBRARY_PATH:
      • export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:path_of_libssw.so
      • Or add the path to /etc/ld.so.conf and run /sbin/ldconfig.

  11. Use mapping-only mode with PAF output

    main

    To skip base-level alignment and produce faster results, use the -x flag. This switches the output format from SAM to PAF.

    Note: PAF output only includes mapped reads. If one read in a pair is unmapped, only the mapped partner is output. Unmapped single-end reads are also omitted.

    strobealign -x -t 8 ref.fa reads.1.fastq.gz reads.2.fastq.gz | igzip > output.paf.gz

    (If igzip is unavailable, use pigz or gzip.)

  12. Pre-compute and use strobealign index files (.sti)

    main

    By default, strobealign builds an index on-the-fly. For repeated mapping against the same reference, you can pre-generate an on-disk index (.sti) to save time.

    1. Create the index: You must provide reads (or a read length) so strobealign can select the correct profile. The index file will be named ref.fa.X.sti (where X is the profile identifier).

    # Using estimated read length from provided reads
strobealign --create-index -t 8 ref.fa reads.1.fastq.gz reads.2.fastq.gz

# Explicitly setting read length
strobealign --create-index -t 8 -r 150 ref.fa

# Using the 'noisy' profile
strobealign --create-index -t 8 -P noisy ref.fa

    2. Use the index for mapping: Use the --use-index flag. If you used a specific profile (like noisy) to create the index, you must also specify it during mapping.

    strobealign --use-index -t 8 ref.fa reads.1.fastq.gz reads.2.fastq.gz | samtools ...

    Important Notes:

    • Index files are typically ~4x the size of the reference genome.
    • .sti files are version-specific; they must be regenerated if you upgrade strobealign.
    strobealign --create-index -t 8 -r 150 ref.fa