Supply motif models and a DNA length. Motif Balance searches for sequences that strengthen the weakest desired match while optionally limiting unwanted matches. Inspect the motif sites, collect different arrangements, and expand each layout into sequence alternatives.

Documentation · Supply motifs · Python API

Try a design

Fit the E. coli ArgR and Cra preferences into 25 bases. Their models span 25 and 14 positions, so their matches must overlap. The profiles come from the DAP-seq data in Baumgart et al. (2021), Supplementary Data 2.

1. Install and prepare the profiles

With uv installed:

# Create a project. The visualization extra adds PNG and video export.
uv init --python 3.12 my-project
cd my-project
uv add 'motif-balance[visualization]'

# Download and check the published data, then write editable inputs.
uv run motif-balance example argr-cra --out argr-cra
cd argr-cra

inputs/motifs/ contains the models, SOURCE.json records their origin, and design.yaml sets the request. The download is cached for reuse. Preparation details.

To see a model, start Python with uv run python and enter:

from motif_balance.formats import read_motif

cra = read_motif("inputs/motifs/cra.json")
print(cra)  # Show nucleotide probabilities along the motif.

Cra (14 positions)
Background (A C G T): 0.25 0.25 0.25 0.25
Probabilities (3 significant digits)
Position         A         C         G         T
       1    0.0227    0.0227     0.932    0.0227
       2    0.0227     0.932    0.0227    0.0227
       3    0.0227    0.0227    0.0227     0.932
... 9 positions omitted ...
      13    0.0409     0.914    0.0227    0.0227
      14     0.823    0.0227    0.0955    0.0591

Position 1 strongly favors G. Scoring compares these probabilities with the background. Exit Python with exit() to continue in the terminal.

2. Design and inspect DNA

# Search 4,096 candidates and return four 25-base sequences.
uv run motif-balance design design.yaml --out result

# Draw the best sequence with its motif matches and scores.
uv run motif-balance inspect result --format png --out candidate.png

Each q is a motif's best match, rescaled to its own score range. Balance B is the weaker score, 0.855 here. Both strands are scanned. Other inspection formats include HTML score tables.

3. Collect different arrangements

# Choose up to two layouts that differ in motif order, strand, or overlap.
uv run motif-balance collect result --count 2 --out collection.json
uv run motif-balance inspect collection.json --format png --out arrangements.png

The first arrangement is the same duplex shown above, viewed from the opposite strand. Reversing the whole duplex does not create a different arrangement. Selection reports a shortfall if the retained pool cannot supply the requested count. Arrangement definitions.

4. Expand each arrangement into sequence alternatives

# Vary covered bases, keeping the selected motif positions and strands.
# Every returned sequence must have balance at least 0.8.
uv run motif-balance expand collection.json --all --min-balance 0.8 --out expanded

Each arrangement returns 256 sequences at the default output limit. expanded/ contains FASTA sequences and per-motif score tables for each layout. Other designs can yield fewer alternatives. See sequence expansion to change the limits or inspect the checks.

Use new output names when repeating a step. The Python tutorial uses these same models throughout.

Design with more motifs

The same request can include more models. Prepare the twelve-model example, then use the ordinary design command:

uv run motif-balance example twelve-motifs --out twelve-motifs
# Edit this request to use your own motif files or change the DNA length.
uv run motif-balance design twelve-motifs/design.yaml --out twelve-result
uv run motif-balance inspect twelve-result --format png --out twelve-dna.png

This request uses 60 bases and 655,360 evaluations. The movie ends when the recorded run first reaches its best balance, 0.733, at evaluation 121,534. Gray windows show recorded search candidates; colored windows show the best sequence so far.

Exact replay checks the recorded inputs and winner. Use the editable request above for a new design.

Python 3.12–3.14 · Linux and macOS · MIT license · Contributing

For study data, reproduction, and citation, use the Motif Balance Study. Publication DOI: pending.