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.
.. 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 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``
- Number of output states. ``None`` auto-computes in sequential mode
or defaults to 1 in random mode.
* - ``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``
- Enumeration order when combined with other pools.
----
.. note::
Only the most commonly used parameters are shown above. For the full
parameter list, see :func:`~poolparty.replacement_scan` in the
:doc:`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.
.. code-block:: python
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()
.. raw:: html
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.
.. code-block:: python
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()
.. raw:: html
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.
.. code-block:: python
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()
.. raw:: html
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.
.. code-block:: python
wt = pp.from_seq("AAAAATCGATCGTTTT")
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()
.. raw:: html
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.
.. code-block:: python
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()
.. raw:: html
ACGTACGTACGACCCT
ACGTACGTACGATCTT
AGACCTTTACGTACGT
ACAACTTTACGTACGT
ACGTAAATTCCTACGT