replacement_multiscan

Place multiple non-overlapping replacement windows simultaneously at randomly chosen positions, producing combinatorial libraries with paired substitutions.

import poolparty as pp
pp.init()

Parameters

Parameter	Type	Default	Description
`pool`	`Pool \| str`	(required)	Input pool or sequence string.
`num_replacements`	`int`	(required)	Number of simultaneous non-overlapping replacement windows per draw.
`replacement_pools`	`Pool \| list[Pool]`	(required)	Pool(s) supplying replacement content. A single pool is reused at every site; a list assigns one pool per site.
`positions`	`list \| None`	`None`	Allowed position sets for each replacement window. `None` allows any valid non-overlapping arrangement.
`region`	`str \| list \| None`	`None`	Named region or interval to restrict replacements to.
`names`	`list[str] \| None`	`None`	Names for each replacement window.
`style`	`str \| None`	`None`	Display style for replaced content.
`insertion_mode`	`str`	`"ordered"`	`"ordered"` preserves left-to-right order of positions; `"unordered"` allows any permutation.
`min_spacing`	`int \| None`	`None`	Minimum gap (in bases) between replacement windows.
`max_spacing`	`int \| None`	`None`	Maximum gap (in bases) between replacement windows.
`prefix`	`str \| None`	`None`	Prefix for the operation node name in the pool graph.
`mode`	`str`	`"random"`	`"random"` or `"sequential"`.
`num_states`	`int \| None`	`None`	Number of states. `None` lets PoolParty choose automatically.
`iter_order`	`float \| None`	`None`	Enumeration order when combined with other pools.
`cards`	`dict \| list \| None`	`None`	Design card columns to include in library output.

Note

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

Examples

Two simultaneous replacements

Draw two non-overlapping single-base substitution positions at random per sequence.

wt   = pp.from_seq("ATCGATCGATCG")
alt  = pp.from_seqs(["A", "C", "G", "T"], mode="sequential")
scan = wt.replacement_multiscan(num_replacements=2,
                                replacement_pools=alt, mode="random",
                                style="red")
scan.print_library()

scan: seq_length=12, num_states=16 ATCGATAGATAG
ATCGATCGATCC
ATCGATAGATCG
ATCGATCGTTCG
ATCGACCGAACG ... (16 total)

Two simultaneous degenerate motif replacements

Replace with a degenerate 6-base IUPAC motif (R = A|G, Y = C|T) at two random positions on a 24-mer. Each draw samples independently from the 64 possible RRYYYY sequences.

wt    = pp.from_seq("ATCGATCGATCGATCGATCGATCG")
motif = pp.from_iupac("RRYYYY")
scan  = wt.replacement_multiscan(num_replacements=2,
                                 replacement_pools=motif, mode="random",
                                 style="red")
scan.print_library()

scan: seq_length=24, num_states=1 ATCGATCGAGACCCTGAGGTTTCG

Multiscan within a named region

Restrict both replacement windows to the cre region; flanking bases are never touched.

wt   = pp.from_seq("AAAA<cre>ATCGATCGATCG</cre>TTTT")
alt  = pp.from_seqs(["A", "C", "G", "T"], mode="sequential")
scan = wt.replacement_multiscan(num_replacements=2,
                                replacement_pools=alt,
                                region="cre", mode="random",
                                style="red")
scan.print_library()

scan: seq_length=20, num_states=16 AAAA<cre>ATCGATAGATAG</cre>TTTT
AAAA<cre>ATCGATCGATCC</cre>TTTT
AAAA<cre>ATCGATAGATCG</cre>TTTT
AAAA<cre>ATCGATCGTTCG</cre>TTTT
AAAA<cre>ATCGACCGAACG</cre>TTTT ... (16 total)

Spacing constraints (min_spacing, max_spacing)

min_spacing and max_spacing control the gap between replacement windows. Here two 6-base motif replacements must be 3–6 bases apart on a 24-mer.

wt    = pp.from_seq("ATCGATCGATCGATCGATCGATCG")
motif = pp.from_seq("GATTAC")
scan  = wt.replacement_multiscan(num_replacements=2,
                                 replacement_pools=motif,
                                 min_spacing=3, max_spacing=6,
                                 mode="sequential", style="red")
scan.print_library()

scan: seq_length=24, num_states=34 GATTACCGAGATTACGATCGATCG
GATTACCGATGATTACATCGATCG
GATTACCGATCGATTACTCGATCG
GATTACCGATCGGATTACCGATCG
AGATTACGATGATTACATCGATCG ... (34 total)

PPM-based replacement pool (from_motif)

Use from_motif() to supply a position-probability matrix as the replacement content. Each draw samples a different 6-mer from the PPM, producing biologically realistic variation at each window.

import pandas as pd

pfm = pd.DataFrame({
    "A": [0.8, 0.1, 0.5, 0.1, 0.7, 0.1],
    "C": [0.1, 0.7, 0.2, 0.1, 0.1, 0.1],
    "G": [0.05, 0.1, 0.2, 0.1, 0.1, 0.7],
    "T": [0.05, 0.1, 0.1, 0.7, 0.1, 0.1],
})
wt    = pp.from_seq("ATCGATCGATCGATCGATCGATCG")
motif = pp.from_motif(pfm)
scan  = wt.replacement_multiscan(num_replacements=2,
                                 replacement_pools=motif, mode="random",
                                 num_states=5, style="red")
scan.print_library()

scan: seq_length=24, num_states=5 ATCGATCGACCGTAGGAACCCAGG
CCATATCGATCGATCGAAGGCATG
ATCGATCGATCCGCAGAAAATAGG
CCATATCGATCGAACATAGGATCG
ATCGATCGACATAGCACATACTCG

Explicit position sets (positions)

Specify allowed starts for each window independently, using a distinct pool for each site. Below, the first replacement (GGG) can start at position 0, 3, or 6, while the second (AAA) can start at position 9 or 13.

wt    = pp.from_seq("ATCGATCGATCGATCG")
pools = [pp.from_seq("GGG"), pp.from_seq("AAA")]
scan  = wt.replacement_multiscan(num_replacements=2,
                                 replacement_pools=pools,
                                 positions=[[0, 3, 6], [9, 13]],
                                 mode="sequential", style="red")
scan.print_library()

scan: seq_length=16, num_states=6 GGGGATCGAAAAATCG
GGGGATCGATCGAAAA
ATCGGGCGAAAAATCG
ATCGGGCGATCGAAAA
ATCGATGGGAAAATCG
ATCGATGGGTCGAAAA

See replacement_multiscan().