deletion_scan
=============
Slide a deletion window of fixed length across the sequence (or a named
region) and, at each position, remove those bases. By default deleted
positions are filled with ``-`` gap characters so all output sequences remain
alignment-compatible. Pass ``deletion_marker=None`` to produce shorter
sequences instead.
.. 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.
* - ``deletion_length``
- ``int``
- *(required)*
- Width of the deletion window in bases. A sequence of length *L*
produces *L* - ``deletion_length`` + 1 variants.
* - ``deletion_marker``
- ``str | None``
- ``'-'``
- Character used to fill deleted positions. Pass ``None`` to remove
deleted bases entirely (output sequences are shorter than the input).
* - ``region``
- ``str | list | None``
- ``None``
- Restrict the scan to a named region or ``[start, stop]`` interval.
Flanking sequences are never modified.
* - ``positions``
- ``list[int] | None``
- ``None``
- Explicit list of window start positions. ``None`` = all valid positions.
* - ``mode``
- ``str``
- ``'random'``
- ``'sequential'`` iterates left-to-right; ``'random'`` shuffles.
* - ``num_states``
- ``int | None``
- ``None``
- Number of output states. ``None`` auto-computes in sequential mode
or defaults to 1 in random mode.
* - ``style``
- ``str | None``
- ``None``
- Named display style applied to the deletion marker. Only takes
effect when ``deletion_marker`` is not ``None``.
* - ``iter_order``
- ``int | None``
- ``None``
- Enumeration order when combined with other pools.
* - ``prefix``
- ``str | None``
- ``None``
- Prefix for auto-generated sequence names.
----
.. note::
Only the most commonly used parameters are shown above. For the full
parameter list, see :func:`~poolparty.deletion_scan` in the
:doc:`API Reference `.
Examples
--------
Single-base deletion with default marker
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Delete one base at each of the 8 positions in an 8-mer; deleted positions
are marked with ``-``.
.. code-block:: python
wt = pp.from_seq("ACGTACGT")
dels = wt.deletion_scan(deletion_length=1, mode="sequential", style="grey")
dels.print_library()
.. raw:: html
-CGTACGT
A-GTACGT
AC-TACGT
ACG-ACGT
ACGT-CGT
ACGTA-GT
ACGTAC-T
ACGTACG-
True deletion (deletion_marker=None)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``deletion_marker=None`` removes the bases entirely; output sequences are
shorter than the input.
.. code-block:: python
wt = pp.from_seq("ACGTACGT")
dels = wt.deletion_scan(deletion_length=2, deletion_marker=None, mode="sequential")
dels.print_library()
.. raw:: html
GTACGT
ATACGT
ACACGT
ACGCGT
ACGTGT
ACGTAT
ACGTAC
2-base window deletion
~~~~~~~~~~~~~~~~~~~~~~~~
Delete two consecutive bases at each position. An 8-mer yields 7 variants.
.. code-block:: python
wt = pp.from_seq("ACGTACGT")
dels = wt.deletion_scan(deletion_length=2, mode="sequential", style="grey")
dels.print_library()
.. raw:: html
--GTACGT
A--TACGT
AC--ACGT
ACG--CGT
ACGT--GT
ACGTA--T
ACGTAC--
Deletion scan within a named region
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Restrict the scan to the ``cre`` region; the ``AAAA`` and ``TTTT`` flanks
are always returned unchanged.
.. code-block:: python
wt = pp.from_seq("AAAAATCGATCGTTTT")
dels = wt.deletion_scan(deletion_length=2, region="cre", mode="sequential",
style="grey")
dels.print_library()
.. raw:: html
AAAA<cre>--CGATCG</cre>TTTT
AAAA<cre>A--GATCG</cre>TTTT
AAAA<cre>AT--ATCG</cre>TTTT
AAAA<cre>ATC--TCG</cre>TTTT
AAAA<cre>ATCG--CG</cre>TTTT
AAAA<cre>ATCGA--G</cre>TTTT
AAAA<cre>ATCGAT--</cre>TTTT
Scan only specific positions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Supply an explicit ``positions`` list to delete at chosen sites only.
.. code-block:: python
wt = pp.from_seq("ACGTACGT")
dels = wt.deletion_scan(deletion_length=1, positions=[1, 3, 5], mode="sequential",
style="grey")
dels.print_library()
.. raw:: html
A-GTACGT
ACG-ACGT
ACGTA-GT
Random deletion positions (mode="random")
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``mode='random'`` draws deletion positions stochastically. Here a 3-base
deletion window samples 5 random positions along a 12-mer.
.. code-block:: python
wt = pp.from_seq("ACGTACGTACGT")
dels = wt.deletion_scan(deletion_length=3, mode="random", num_states=5,
style="grey")
dels.print_library()
.. raw:: html
ACGTA---ACGT
ACGTAC---CGT
ACGTA---ACGT
A---ACGTACGT
A---ACGTACGT
See :func:`~poolparty.deletion_scan`.