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}.

import poolparty as pp
pp.init()

Parameters

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 from_iupac() in the 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.

pool = pp.from_iupac("WN", mode="random", num_states=4)
pool.print_library()

pool: seq_length=2, num_states=4 TG
TT
AC
TC

Sequential enumeration

mode='sequential' iterates all combinations in lexicographic order, giving exactly one draw per combination.

pool = pp.from_iupac("RY", mode="sequential")
pool.print_library()
# R={A,G}, Y={C,T}: 2x2=4 combinations

pool: seq_length=2, num_states=4 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.

pool = pp.from_iupac("NNNN", mode="sequential", num_states=8)
pool.print_library()
# NNNN has 256 total; take first 8

pool: seq_length=4, num_states=8 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.

bg   = pp.from_seq("AAAA<cre>XXX</cre>TTTT")
pool = pp.from_iupac("NNN", mode="sequential", pool=bg, region="cre")
pool.print_library()

pool: seq_length=11, num_states=64 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.

bg   = pp.from_seq("AAAA<cre>XXX</cre>TTTT")
pool = bg.insert_from_iupac("NNN", region="cre", mode="sequential")
pool.print_library()