Contributing

Contributions to strobealign are very welcome!

• To report a bug, open an issue.

• To suggest a small change, just submit a pull request.

• To suggest a larger change, it may be a good idea to first open an issue or to send an e-mail so we can discuss it.

Instead of one large PR, consider submitting multiple small, logically self-contained PRs if it makes sense. This facilitates review and allows for a more focused discussion.

Building strobealign¶

Use cargo build --release. The compiled binary is at target/release/strobealign.

Without --release, the compiler uses the default debug profile, which does not enable as many optimizations. This makes compilation faster, but results in an unnecessarily slow binary.

To create a slightly faster binary with optimizations specific to your CPU, run cargo with the RUSTFLAGS environment variable set like this:

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

You can also build and run the program in one step using cargo run, which may look like this:

cargo run -r -- -t 8 tests/phix.fasta tests/phix.1.fastq

Option -r is short for --release. Options after -- are passed to strobealign.

Run the tests with cargo test.

There are additional tests that should be run with tests/run.sh. (These have have not yet been ported to native Rust tests.)

Building the legacy C++ version of strobealign¶

Until version 0.17.0, strobealign was written in C++. The code currently still exists in the repository. To configure that code, change to the cpp directory and run cmake -B build. You can add specify a build type to set some useful compiler options by adding one of these options to the command:

• Use -DCMAKE_BUILD_TYPE=Release when building a release (-O3 -DNDEBUG) (this is the default)

• Use -DCMAKE_BUILD_TYPE=Debug for development (-O2 -g)

• Use -DCMAKE_BUILD_TYPE=RelWithDebInfo for profiling (-O3 -g -DNDEBUG)

-g gives you debug symbols and -DNDEBUG disables assertions.

Then compile the program:

cmake --build build

Testing¶

Whenever you make changes that could potentially affect mapping results, you can run a more elaborate test that compares strobealign against a “baseline” (know good) commit. Just run this script:

tests/compare-baseline.sh

The first time, it will download a D. melanogaster genome and some reads from the Sequence Read Archive (SRA). Since the dataset is truncated to the first 100’000 reads, mapping it should take less than 30 seconds.

The baseline commit is the most recent commit that contains the trailer Is-new-baseline: yes. The script builds strobealign from that commit and runs it against the downloaded test data, then builds strobealign as it is in your working copy and compares the two produced BAM files. The baseline BAM is cached and re-used as long as the baseline commit does not change.

Release checklist¶

• Increase STI_FILE_FORMAT constant if needed

• Run benchmarks that compare to the previous version

• Update changelog (check for completeness, adjust section header)

• Bump version in Cargo.toml

• Commit

• Push and wait for CI to pass

• Do git tag ... and git push --tags

• cargo publish

• Make a release via the GitHub releases page

• Wait for the Bioconda bot to pick up the new release and then approve its version bump PR

Detailed SAM output (--details)¶

When --details is provided, the following additional SAM tags are output for mapped reads.

na: Number of chains found mr: Number of times mate rescue was attempted (local alignment of a mate to the expected region given its mate) al: Number of times an attempt was made to extend a chain (by gapped or ungapped alignment) ga: Number of times an attempt was made to extend a chain by gapped alignment X0: Number of equally scored best alignments (greater than 1 for multimappers). For paired-end reads, the tag is output for both reads, but the value is identical and is the number of equally scored best alignment pairs. du: Number of insertions re-interpreted as tandem duplications.

Hidden command-line options¶

The following command-line options are not shown when strobealign is run with --help. They are typically only useful when developing the program.

• --ithreads: Set the number of indexing threads. Default: same as -t. This allows one to quickly index the reference as usual, but then map reads with only one thread such that (debugging) output is serial (and not intermixed output from multiple threads).

• --chunk-size: Set the number of nucleotides processed by a worker thread at once. Default: 1 million

• --trace: Highly verbose output; shows lots of details for each read. This also sets --ithreads 1.

• -m: Set maximum seed length. For reasonable values on -l and -u, the seed length distribution is usually determined by parameters l and u, and then this parameter is only active in regions where syncmers are very sparse. Default: read_length - 50

• -c: Bitcount length between 2 and 63. Default: 8.