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 recovered sites, choose different arrangements, then expand each layout into nucleotide alternatives.

Documentation · Supply motifs · Python API

Try a design

Fit the E. coli ArgR and Cra preferences into 25 bases. Their motif models span 25 and 14 positions, so the shorter match must fit within the same DNA as the wider one. These profiles were inferred 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 and install the package from PyPI.
uv init --python 3.12 my-project
cd my-project
uv add 'motif-balance==0.8.1'

# Fetch the attributed example, its source record, and its editable design request.
MB_EXAMPLE_URL=https://raw.githubusercontent.com/e-south/motif-balance/v0.8.1/examples/argr-cra
curl -fLO "$MB_EXAMPLE_URL/prepare_inputs.py"
curl -fLO "$MB_EXAMPLE_URL/SOURCE.json"
curl -fLO "$MB_EXAMPLE_URL/design.yaml"

# Check the publisher's data and prepare local ArgR and Cra models.
uv run python prepare_inputs.py --out inputs

design.yaml requests four 25-base sequences, 4,096 candidate evaluations, and seed 7. Edit that file to change the request. The preparation record explains the probability adjustment and source checks.

2. Design and inspect DNA

# Search for DNA with a strong weakest motif match, and save its sequences and scores.
uv run motif-balance design design.yaml --out result

# Draw the selected sites and logos, with the score and search summaries alongside.
uv run motif-balance inspect result --format html --out review.html

Open review.html. The best candidate scores about 0.855. The review shows where each motif matches, on which strand, and how well it scores. Every candidate is scanned on both strands.

3. Collect different arrangements

# Keep up to two representatives with different motif order, strand, or overlap.
uv run motif-balance collect result --count 2 --out collection.json

The representatives score about 0.855 and 0.801. Selection uses the retained search pool and reports any shortfall. The saved collection carries its sequences, motif models, and selected sites. Arrangement definitions explain which differences count.

4. Expand each arrangement into sequence alternatives

# Vary nucleotides within each layout while retaining its selected motif sites.
# 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. Every sequence meets the 0.8 floor and retains its parent's selected motif positions and strands. Open the FASTA and per-motif score table for each arrangement in expanded/; collection.json contains the complete record. Other designs can yield fewer alternatives.

Sequence expansion explains the score floor and work limits. For synthesis as a checked ambiguity template, use the separate degenerate-library operation.

Use a new output name when repeating a step. The Python tutorial uses the same example in code. Installation covers pip and optional video export.

Inspect a larger design

The twelve-model example shows improvements during a recorded search in 60-base DNA. The chart follows the best balance found. Colored motif windows show that sequence; faint gray windows show recorded search candidates. Transitions connect saved placements.

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.