region_scan

Insert a named region tag at successive positions within a sequence, producing one variant per window position. Combine with replace_region() or other operations to act on the tagged window. Use mode='sequential' to enumerate every position deterministically.

import poolparty as pp
pp.init()

Parameters

Parameter	Type	Default	Description
`pool`	`Pool \| str`	(required)	The Pool to scan. Can also be a plain sequence string.
`tag_name`	`str`	`'region'`	Name for the scanning region tag inserted at each position.
`positions`	`list[int] \| None`	`None`	Explicit list of 0-based positions to visit. `None` = all valid positions.
`region`	`str \| list \| None`	`None`	Restrict the scan to a named region (string) or a `[start, stop]` coordinate pair.
`remove_tags`	`bool \| None`	`None`	When `True` and `region` is a region name, strip the constraint region tags from the output.
`region_length`	`int`	`0`	Number of bases the scanning window spans. `0` = zero-length point tag; positive = spanning tags enclosing that many bases.
`mode`	`str`	`'random'`	`'sequential'` enumerates every valid position as a separate state; `'random'` samples one position per draw.
`num_states`	`int \| None`	`None`	Override the automatically-computed state count.
`iter_order`	`int \| None`	`None`	Dimension-name ordering for downstream multi-pool iteration.
`prefix`	`str \| None`	`None`	Prefix for the operation node name in the pool graph.
`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 region_scan() in the API Reference.

Examples

Point tags across every inter-base position (region_length=0)

region_length=0 places a zero-length tag at each of the 9 valid positions in an 8-mer (between and at the ends of every base).

wt   = pp.from_seq("ATCGATCG")
scan = pp.region_scan(wt, tag_name="ins", region_length=0,
                      mode="sequential")
scan.print_library()

scan: seq_length=8, num_states=9 <ins/>ATCGATCG
A<ins/>TCGATCG
AT<ins/>CGATCG
ATC<ins/>GATCG
ATCG<ins/>ATCG
ATCGA<ins/>TCG
ATCGAT<ins/>CG
ATCGATC<ins/>G
ATCGATCG<ins/>

2-base spanning window (region_length=2)

A positive region_length creates spanning tags that enclose that many bases at each scan position.

wt   = pp.from_seq("ATCGATCG")
scan = pp.region_scan(wt, tag_name="win", region_length=2,
                      mode="sequential")
scan.print_library()

scan: seq_length=8, num_states=7 <win>AT</win>CGATCG
A<win>TC</win>GATCG
AT<win>CG</win>ATCG
ATC<win>GA</win>TCG
ATCG<win>AT</win>CG
ATCGA<win>TC</win>G
ATCGAT<win>CG</win>

Scan constrained to a named region (region)

Restrict the window scan to the cre region; flanks are fixed.

wt   = pp.from_seq("AAAA<cre>ATCGATCG</cre>TTTT")
scan = pp.region_scan(wt, tag_name="win", region_length=2,
                      region="cre", mode="sequential")
scan.print_library()

scan: seq_length=16, num_states=7 AAAA<cre><win>AT</win>CGATCG</cre>TTTT
AAAA<cre>A<win>TC</win>GATCG</cre>TTTT
AAAA<cre>AT<win>CG</win>ATCG</cre>TTTT
... (7 total)

Strip the constraint region tags (remove_tags=True)

remove_tags=True removes the cre tags while keeping the scanning window tag in the output.

wt   = pp.from_seq("AAAA<cre>ATCGATCG</cre>TTTT")
scan = pp.region_scan(wt, tag_name="win", region_length=2,
                      region="cre", remove_tags=True,
                      mode="sequential")
scan.print_library()

scan: seq_length=16, num_states=7 AAAA<win>AT</win>CGATCGTTTT
AAAAA<win>TC</win>GATCGTTTT
AAAAAT<win>CG</win>ATCGTTTT
... (7 total)

Scan only specific positions (positions parameter)

Pass an explicit list to positions to visit only chosen window starts.

wt   = pp.from_seq("ATCGATCG")
scan = pp.region_scan(wt, tag_name="win", region_length=2,
                      positions=[0, 3, 6], mode="sequential")
scan.print_library()

scan: seq_length=8, num_states=3 <win>AT</win>CGATCG
ATC<win>GA</win>TCG
ATCGAT<win>CG</win>

See region_scan().