from_iupac
==========
Create a pool from an IUPAC ambiguity-code string. Every ambiguous position
expands to its corresponding base set; the pool enumerates all possible
combinations. By default the pool samples uniformly at random; pass
``mode='sequential'`` to enumerate in lexicographic order.
IUPAC codes: R = {A,G}, Y = {C,T}, S = {C,G}, W = {A,T}, K = {G,T},
M = {A,C}, B = {C,G,T}, D = {A,G,T}, H = {A,C,T}, V = {A,C,G},
N = {A,C,G,T}.
.. code-block:: python
import poolparty as pp
pp.init()
----
Parameters
----------
.. list-table::
:header-rows: 1
:widths: auto
* - Parameter
- Type
- Default
- Description
* - ``iupac_seq``
- ``str``
- *(required)*
- IUPAC sequence string (case-insensitive). Unambiguous bases pass
through unchanged.
* - ``pool``
- ``Pool | None``
- ``None``
- Background pool. When provided with ``region``, each generated
sequence replaces the content of that region.
* - ``region``
- ``str | None``
- ``None``
- Region to replace in ``pool``. Required when ``pool`` is provided.
* - ``prefix``
- ``str | None``
- ``None``
- Prefix for auto-generated sequence names.
* - ``mode``
- ``str``
- ``'random'``
- ``'sequential'`` enumerates every combination in lexicographic
order; ``'random'`` samples uniformly at random.
* - ``num_states``
- ``int | None``
- ``None``
- Cap on total states. With ``mode='sequential'`` takes the first N;
with ``mode='random'`` draws N independently.
* - ``iter_order``
- ``int | None``
- ``None``
- Dimension-name ordering for downstream multi-pool iteration.
* - ``style``
- ``str | None``
- ``None``
- Display style applied to every generated sequence.
* - ``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.from_iupac` in the
:doc:`API Reference `.
Examples
--------
Random sampling from an ambiguous code
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``W`` = {A,T}, ``N`` = {A,C,G,T}: 2 × 4 = 8 total combinations.
Random mode draws one sequence per call.
.. code-block:: python
pool = pp.from_iupac("WN", mode="random", num_states=4)
pool.print_library()
.. raw:: html
TG
TT
AC
TC
Sequential enumeration
~~~~~~~~~~~~~~~~~~~~~~
``mode='sequential'`` iterates all combinations in lexicographic order,
giving exactly one draw per combination.
.. code-block:: python
pool = pp.from_iupac("RY", mode="sequential")
pool.print_library()
# R={A,G}, Y={C,T}: 2x2=4 combinations
.. raw:: html
AC
AT
GC
GT
Capping with ``num_states``
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Combine ``mode='sequential'`` with ``num_states`` to take only the first N
combinations — useful for prototyping with a large degenerate sequence.
.. code-block:: python
pool = pp.from_iupac("NNNN", mode="sequential", num_states=8)
pool.print_library()
# NNNN has 256 total; take first 8
.. raw:: html
AAAA
AAAC
AAAG
AAAT
AACA
AACC
AACG
AACT
Inserting into a named region
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Provide ``pool`` and ``region`` to enumerate all IUPAC combinations into a
fixed flanking context.
.. code-block:: python
bg = pp.from_seq("AAAAXXXTTTT")
pool = pp.from_iupac("NNN", mode="sequential", pool=bg, region="cre")
pool.print_library()
.. raw:: html
AAAA<cre>AAA</cre>TTTT
AAAA<cre>AAC</cre>TTTT
AAAA<cre>AAG</cre>TTTT
AAAA<cre>AAT</cre>TTTT
AAAA<cre>ACA</cre>TTTT
... (64 total)
Pool method shorthand
~~~~~~~~~~~~~~~~~~~~~
When inserting into a region, the same operation is available as a method
on any ``DnaPool``. The call ``bg.insert_from_iupac(...)`` is equivalent
to ``pp.from_iupac(..., pool=bg)`` — it simply passes ``self`` as the
background pool.
.. code-block:: python
bg = pp.from_seq("AAAAXXXTTTT")
pool = bg.insert_from_iupac("NNN", region="cre", mode="sequential")
pool.print_library()
.. raw:: html
AAAA<cre>AAA</cre>TTTT
AAAA<cre>AAC</cre>TTTT
AAAA<cre>AAG</cre>TTTT
AAAA<cre>AAT</cre>TTTT
AAAA<cre>ACA</cre>TTTT
... (64 total)
See :func:`~poolparty.from_iupac` and :meth:`~poolparty.DnaPool.insert_from_iupac`.