Welcome to the outward assembly repository! This repo provides Python tooling to assemble the genomic context around provided seed sequences from a collection of read pairs. The seed sequences could be flagged chimeric junctions, kmers identified by reference-free growth detection, etc.
When the collection of reads is very large -- e.g. billions of reads from one delivery, or tens of billions of reads across deliveries -- doing a full metagenomic joint assembly is slow and computationally expensive. Instead of jointly assembling all reads, outward assembly attempts to iteratively grow contigs outward from the provided seeds. The basic algorithm is simple:
- Start with the seeds as your initial contig.
- Iteratively:
- Find all read pairs that share a kmer with your contigs.
- Assemble these read pairs.
- Filter contigs to those that contain a seed.
- Continue until either maximum iterations are reached or the assembly algorithm does not make progress from one iteration to another ("convergence").
Although the basic algorithm is simple, in practice, getting good assembly results is a bit more complex (see algorithm details for how we handle some of these complexities).
On an EC2 instance running Linux:
- Install dependencies:
uv sync --extra dev - Create tools environment:
mamba env create -n oa-tools -f oa_tools_env.yml --channel-priority flexible - Activate tools environment:
mamba activate oa-tools
See installation docs for more details.
Outward assembly's main entry point is the Python function outward_assembly, and a command line interface is not provided.
Typically you'll run outward assembly by executing a short Python script (example) which configures and calls OA.
For example, to invoke this example script: uv run docs/example-assembly-dir/script.py.
The usage docs contain more details and guidance.