replacement_scan

Slide a window across the sequence and, at each position, replace the window with every sequence drawn from replacement_pool. The output length equals the background sequence length.

import poolparty as pp
pp.init()

Parameters

Parameter	Type	Default	Description
`pool`	`Pool \| str`	(required)	The background Pool or sequence string that is scanned.
`replacement_pool`	`Pool \| str`	(required)	Pool supplying replacement content. Each of this pool’s sequences is substituted into the window at every scanned position. The pool’s `seq_length` determines the window width.
`positions`	`list[int] \| None`	`None`	Explicit list of window start positions. `None` = all valid positions.
`region`	`str \| None`	`None`	Name of a tagged region to restrict the scan to. Positions outside the region are never modified.
`style`	`str \| None`	`None`	Style to apply to inserted content.
`mode`	`str`	`'random'`	`'sequential'` iterates positions then replacements in order; `'random'` shuffles the (position × replacement) product.
`num_states`	`int \| None`	`None`	Fix the total number of output states.
`prefix`	`str \| None`	`None`	Prefix for auto-generated sequence names.
`prefix_position`	`str \| None`	`None`	Prefix for position index (e.g., ‘pos_’ produces ‘pos_0’, ‘pos_1’, …).
`prefix_insert`	`str \| None`	`None`	Prefix for insert index (e.g., ‘ins_’ produces ‘ins_0’, ‘ins_1’, …).
`iter_order`	`int \| None`	`None`	Dimension-name ordering for downstream multi-pool iteration.

Note

Only the most commonly used parameters are shown above. For the full parameter list, see replacement_scan() in the API Reference.

Examples

Single-base replacement at every position

Replace each base with every member of a four-base pool — 8 positions × 4 substitutions = 32 sequences.

import poolparty as pp
pp.init()
wt   = pp.from_seq("ACGTACGT")
alt  = pp.from_seqs(["A", "C", "G", "T"], mode="sequential")
scan = wt.replacement_scan(replacement_pool=alt, mode="sequential", style="red")
scan.print_library()

scan: seq_length=8, num_states=32 ACGTACGT
AAGTACGT
ACATACGT
ACGAACGT
ACGTACGT ... (32 total)

Trinucleotide window scan

The window width is determined by replacement_pool sequence length. A 3-base pool scans 6 positions across an 8-mer.

import poolparty as pp
pp.init()
wt   = pp.from_seq("ACGTACGT")
tri  = pp.from_seqs(["AAA", "CCC", "GGG", "TTT"], mode="sequential")
scan = wt.replacement_scan(replacement_pool=tri, mode="sequential", style="red")
scan.print_library()

scan: seq_length=8, num_states=24 AAATACGT
AAAAACGT
ACAAACGT
ACGAAAGT
ACGTAAAT ... (24 total)

All-dinucleotide replacements via from_iupac

from_iupac("NN") enumerates all 16 dinucleotides. Seven windows × 16 substitutions = 112 sequences.

import poolparty as pp
pp.init()
wt   = pp.from_seq("ACGTACGT")
nn   = pp.from_iupac("NN", mode="sequential")
scan = wt.replacement_scan(replacement_pool=nn, mode="sequential", style="red")
scan.print_library()

scan: seq_length=8, num_states=112 AAGTACGT
AAATACGT
ACAAACGT
ACGAACGT
ACGTAAGT ... (112 total)

Scan restricted to a named region

Restrict the scan to the cre region; the AAAA and TTTT flanks are never modified.

import poolparty as pp
pp.init()
wt   = pp.from_seq("AAAA<cre>ATCGATCG</cre>TTTT")
alt  = pp.from_seqs(["A", "C", "G", "T"], mode="sequential")
scan = wt.replacement_scan(replacement_pool=alt, region="cre", mode="sequential",
                           style="red")
scan.print_library()

scan: seq_length=16, num_states=32 AAAA<cre>ATCGATCG</cre>TTTT
AAAA<cre>AACGATCG</cre>TTTT
AAAA<cre>ATAGATCG</cre>TTTT
AAAA<cre>ATCAATCG</cre>TTTT
AAAA<cre>ATCGATCG</cre>TTTT ... (32 total)

Random motif replacement (mode=”random”)

mode='random' draws a random window position and replacement each time. Here a degenerate 6-base IUPAC motif (R = A|G, Y = C|T) is scanned across a 16-mer, with 5 random draws.

import poolparty as pp
pp.init()
wt    = pp.from_seq("ACGTACGTACGTACGT")
motif = pp.from_iupac("RRYYYY")
scan  = wt.replacement_scan(replacement_pool=motif, mode="random",
                            num_states=5, style="red")
scan.print_library()

scan: seq_length=16, num_states=5 ACGTACGTACGACCCT
ACGTACGTACGATCTT
AGACCTTTACGTACGT
ACAACTTTACGTACGT
ACGTAAATTCCTACGT