vsearch Library API Examples

Minimal C++ programs demonstrating each vsearch library API entry point. Each example compiles against libvsearch.a and produces output identical to the equivalent native vsearch command.

Prerequisites

Build the vsearch static library and executable:

cd ..
./configure                 # the generated build files are shipped; no autoreconf needed
make -C src libvsearch.a    # static library for examples
make -C src                 # executable for ground truth comparison

Building

make

Running tests

make test

This builds all examples, runs them, and compares output against the ground truth files in data/ (generated by native vsearch). All comparisons must pass.

Examples

example_chimera

Chimera detection using chimera_detect_single().

Equivalent to:

vsearch --uchime_ref data/chimera_queries.fasta \
  --db data/chimera_ref.fasta \
  --uchimeout output.tsv

example_search

Global sequence search using search_session_single().

Equivalent to:

vsearch --usearch_global data/chimera_queries.fasta \
  --db data/chimera_ref.fasta \
  --id 0.5 --maxaccepts 3 --maxrejects 16 --wordlength 8 \
  --userout output.tsv \
  --userfields query+target+id

example_cluster

Greedy clustering using cluster_assign_single().

Equivalent to:

vsearch --cluster_fast data/chimera_ref.fasta \
  --id 0.70 --uc output.uc

example_merge

Paired-end read merging using mergepairs_single().

Equivalent to:

vsearch --fastq_mergepairs data/merge_fwd.fastq \
  --reverse data/merge_rev.fastq \
  --fastaout output.fasta

example_lifecycle

Library API contract checks that have no CLI equivalent: null-safety of every free function, the merge_result_free() no-op/idempotency contract, the mergepairs_single() -1 failure return with null buffers, result-struct reuse, the non-chimeric result zeroing contract, and the dust_single() hardmask parameter. Self-validating (no ground-truth comparison).

example_dbinfo

Database query and indexing surface: db_read() for FASTA and FASTQ, all statistical accessors (db_getnucleotidecount(), db_getlongestsequence(), etc.), quality retrieval, the three db_sortby*() ordering contracts, and the incremental dbindex.add_sequence() primitive checked against dbindex.add_all_sequences(). Self-validating.

Test data

All test data uses synthetic 300bp DNA sequences with known properties:

File	Description
data/chimera_ref.fasta	6 reference sequences
data/chimera_queries.fasta	8 queries (4 chimeras, 4 non-chimeras)
data/merge_fwd.fastq	Forward read (200bp, Q40)
data/merge_rev.fastq	Reverse read (200bp, Q40, 100bp overlap)
data/expected_chimera.tsv	vsearch --uchimeout ground truth
data/expected_search.tsv	vsearch --userout ground truth
data/expected_cluster.uc	vsearch --uc ground truth
data/expected_merge.fasta	vsearch --fastaout ground truth