region_scan
===========
Insert a named region tag at successive positions within a sequence,
producing one variant per window position. Combine with
:func:`~poolparty.replace_region` or other operations to act on the tagged
window. Use ``mode='sequential'`` to enumerate every position
deterministically.
.. code-block:: python
import poolparty as pp
pp.init()
----
Parameters
----------
.. list-table::
:header-rows: 1
:widths: auto
* - 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 :func:`~poolparty.region_scan` in the
:doc:`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).
.. code-block:: python
wt = pp.from_seq("ATCGATCG")
scan = pp.region_scan(wt, tag_name="ins", region_length=0,
mode="sequential")
scan.print_library()
.. raw:: html
<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.
.. code-block:: python
wt = pp.from_seq("ATCGATCG")
scan = pp.region_scan(wt, tag_name="win", region_length=2,
mode="sequential")
scan.print_library()
.. raw:: html
<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.
.. code-block:: python
wt = pp.from_seq("AAAAATCGATCGTTTT")
scan = pp.region_scan(wt, tag_name="win", region_length=2,
region="cre", mode="sequential")
scan.print_library()
.. raw:: html
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.
.. code-block:: python
wt = pp.from_seq("AAAAATCGATCGTTTT")
scan = pp.region_scan(wt, tag_name="win", region_length=2,
region="cre", remove_tags=True,
mode="sequential")
scan.print_library()
.. raw:: html
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.
.. code-block:: python
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()
.. raw:: html
<win>AT</win>CGATCG
ATC<win>GA</win>TCG
ATCGAT<win>CG</win>
See :func:`~poolparty.region_scan`.