<h1 align="center"> <a href="https://github.com/ayaanhossain/oligopool/" style="text-decoration: none !important;"> <img src="https://raw.githubusercontent.com/ayaanhossain/repfmt/main/oligopool/img/logo.svg" alt="Oligopool Calculator" width="460" class="center"/> </a> </h1> <h4><p align="center">Version: 2026.02.22.1</p></h4> <p align="center"> <a href="#features" style="text-decoration: none !important;">✨ Features</a> - <a href="#installation" style="text-decoration: none !important;">📦 Installation</a> - <a href="#getting-started" style="text-decoration: none !important;">🚀 Getting Started</a> - <a href="https://github.com/ayaanhossain/oligopool/blob/master/docs/docs.md" style="text-decoration: none !important;">📚 Docs</a> - <a href="https://github.com/ayaanhossain/oligopool/blob/master/docs/api.md" style="text-decoration: none !important;">📋 API</a> - <a href="#command-line-interface-cli" style="text-decoration: none !important;">💻 CLI</a> - <a href="#citation" style="text-decoration: none !important;">📖 Citation</a> - <a href="#license" style="text-decoration: none !important;">⚖️ License</a> </p>

Oligopool Calculator is a Swiss-army knife for oligo pool libraries: a unified toolkit for high-throughput design, assembly, compression, and analysis of massively parallel assays, designed to integrate seamlessly with Python, the CLI, Jupyter, containers, and AI-assisted workflows.

Design modules generate primers, barcodes, motifs/anchors, and spacers; assembly modules split/pad long constructs; Degenerate Mode compresses similar sequences into IUPAC-degenerate oligos for cost-efficient synthesis (often useful for selection assays); and Analysis Mode packs and counts barcoded reads for activity quantification.

Oligopool Calculator has been used to build libraries of tens of thousands of promoters (see here, and here), ribozymes, and mRNA stability elements (see here). It has been benchmarked to design pools containing millions of oligos and to process hundreds of millions of sequencing reads per hour on low-cost desktop-grade hardware.

To learn more, please check out our paper in ACS Synthetic Biology.

Design and analysis of oligo pool variants using Oligopool Calculator. (a) In Design Mode, Oligopool Calculator generates optimized barcodes, primers, spacers, and motifs. Assembly Mode can split longer oligos into shorter padded fragments for synthesis and assembly. Degenerate Mode can compress similar variants into IUPAC-degenerate oligos for cost-efficient synthesis or selection-based discovery workflows. (b) Once the library is assembled and cloned, barcoded amplicon sequencing data can be processed via Analysis Mode for characterization. Analysis Mode proceeds by first indexing one or more sets of barcodes, packing the reads, and then producing count matrices either using acount (association counting) or xcount (combinatorial counting).

✨ Features

🧬 Design mode: constraint-based design of barcodes, primers, motifs/anchors, and spacers with background screening and utilities (barcode, primer, motif, spacer, background, merge, revcomp, join, final).
🔧 Assembly mode: fragment long oligos into overlapping pieces and add Type IIS primer pads for scarless assembly (split, pad).
🧪 Degenerate mode: compress variant libraries with low mutational diversity into IUPAC-degenerate oligos for cost-efficient synthesis and selection-based characterization (compress, expand).
📈 Analysis mode: fast NGS-based activity quantification with read indexing, packing, and barcode/associate counting (index, pack, acount, xcount) extensible with callback methods (via Python library).
✅ QC mode: validate and inspect constraints and outputs (lenstat, verify, inspect).
🔁 Iterative & multiplexed workflows: patch_mode for extending existing pools, cross-set barcode separation, and per-group primer design with cross-compatibility screening.
⚡ Performance: scalable to very large libraries and high-throughput sequencing datasets, with published benchmarks demonstrating efficient design and analysis on commodity hardware (see paper).
🔒 Rich constraints: IUPAC sequence constraints, motif exclusion, repeat screening, Hamming-distance barcodes, and primer thermodynamic constraints (including optional paired-primer Tm matching).
📊 DataFrame-centric: modules operate on CSV/DataFrames and return updated tables plus stats; the CLI can emit JSON and supports reproducible stochastic runs (random_seed).
💻 CLI + library-first: full-featured command-line interface with YAML config files, multi-step pipelines (sequential or parallel DAG), and a composable Python API for interactive use in scripts and Jupyter notebooks.
🤖 AI-assisted design: agent-ready documentation for Claude, ChatGPT, and Copilot.

🤖 AI-Assisted Design

Oligopool Calculator is optimized for AI-assisted workflows. Either share the docs/agent-skills.md file with your agent, or share the following raw URL along with a suitable prompt, for direct parsing.

https://raw.githubusercontent.com/ayaanhossain/oligopool/refs/heads/master/docs/agent-skills.md

Ensure that your AI/agent explores this document thoroughly. Afterwards, you can chat about the package, your specific design goals, and have the agent plan and execute the design and analysis pipelines.

📦 Installation

Oligopool Calculator is a Python 3.10+-exclusive library.

On Linux, macOS, and Windows Subsystem for Linux, you can install Oligopool Calculator from PyPI, where it is published as the oligopool package.

$ pip install --upgrade oligopool # Installs and/or upgrades oligopool

This also installs the command line tools: oligopool and op.

Or install it directly from GitHub:

$ pip install git+https://github.com/ayaanhossain/oligopool.git

Both approaches should install all dependencies automatically.

Note The GitHub version will always be updated with all recent fixes. The PyPI version should be more stable.

If you are on Windows or simply prefer to, Oligopool Calculator can also be used via Docker (please see the notes).

Successful installation will look like this.

$ python
>>> import oligopool as op
>>> op.__version__
'2026.02.22.1'
>>>

🚀 Getting Started

Oligopool Calculator is carefully designed, easy to use, and stupid fast.

You can import the library and use its various functions either in a script or interactively inside a Jupyter environment. Use help(...) to read the docs as necessary and follow along.

The examples directory includes a design parser, a library compressor, an analysis pipeline, and a complete CLI YAML pipeline.

If you want the full end-to-end walkthrough, start with the notebook: Oligopool Calculator in action.

Documentation:

User Guide - Comprehensive tutorials, examples, and workflows
API Reference - Complete parameter documentation for all modules
AI Agent Guide - Decision trees, best practices, and gotchas for AI-assisted design (Claude, ChatGPT, Copilot)
Docker Guide - Run oligopool in a container for cross-platform consistency

$ python
>>>
>>> import oligopool as op
>>> help(op)
...
    Automated design and analysis of oligo pool libraries for
    high-throughput genomics and synthetic biology applications.

    Design Mode - build synthesis-ready oligo architectures
        barcode     orthogonal barcodes with Hamming distance guarantees
        primer      Tm-optimized primers with off-target screening
        motif       sequence motifs or anchors
        spacer      neutral fill to reach target length
        background  k-mer database for off-target screening
        merge       collapse columns into single element
        revcomp     reverse complement a column range
        join        join two tables on ID with ordered insertion
        final       concatenate into synthesis-ready oligos

    Assembly Mode - fragment long oligos for assembly
        split       fragment oligos into overlapping pieces
        pad         Type IIS primer pads for scarless excision

    Degenera

Oligopool

Install / Use

README

✨ Features

🤖 AI-Assisted Design

📦 Installation

🚀 Getting Started