from_seqs

Create a pool that draws from an explicit list of sequences. By default the pool samples uniformly at random; pass mode='sequential' to iterate through the list in order.

import poolparty as pp
pp.init()

Parameters

Parameter	Type	Default	Description
`seqs`	`list[str]`	(required)	List of DNA strings. Must not be empty.
`pool`	`Pool \| str \| None`	`None`	Background pool or sequence string. When provided with `region`, each sequence replaces the content of that region. Requires `region`.
`region`	`str \| list \| None`	`None`	Region to replace in `pool`: a marker name or `[start, stop]` interval. Required when `pool` is provided.
`seq_names`	`list[str] \| None`	`None`	Explicit label for each sequence; populates the `seq_name` column in `generate_library()` output. Cannot be used with `prefix`.
`prefix`	`str \| None`	`None`	Prefix for auto-generated names (e.g. `'seq_'` produces `'seq_0'`, `'seq_1'`, …). Cannot be used with `seq_names`.
`mode`	`str`	`'random'`	`'sequential'` iterates through `seqs` in order (cycling if `num_states` exceeds the list length); `'random'` samples uniformly at random.
`num_states`	`int \| None`	`None`	Number of output states. `None` uses `len(seqs)` in sequential mode or defaults to 1 in random mode. Cycles if greater than `len(seqs)`.
`iter_order`	`int \| None`	`None`	Enumeration order when combined with other pools.
`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_seqs() in the API Reference.

Examples

Basic list, random mode

mode='random' (the default) — each draw picks one sequence uniformly at random. This example sets it explicitly and shows one representative draw.

pool = pp.from_seqs(
    ["AAAA", "CCCC", "GGGG", "TTTT"],
    mode="random",
)
pool.print_library()

pool: seq_length=4, num_states=1 TTTT

Sequential mode

mode='sequential' iterates through the list in order — useful for reproducible, ordered enumeration of a fixed variant set.

pool = pp.from_seqs(
    ["ATCG", "CGTA", "GCAT"],
    mode="sequential",
)
pool.print_library()

pool: seq_length=4, num_states=3 ATCG
CGTA
GCAT

Custom sequence names

seq_names assigns meaningful labels that appear in library output.

pool = pp.from_seqs(
    ["ATCG", "ATAG", "AACG"],
    seq_names=["wt", "mut_A", "mut_B"],
    mode="sequential",
)
pool.print_library()

pool: seq_length=4, num_states=3 wt     ATCG
mut_A  ATAG
mut_B  AACG

Cycling with `num_states`

In sequential mode, num_states greater than len(seqs) cycles through the list to produce the requested number of output rows.

pool = pp.from_seqs(
    ["AAAA", "CCCC"],
    mode="sequential",
    num_states=6,
)
pool.print_library()

pool: seq_length=4, num_states=6 AAAA
CCCC
AAAA
CCCC
AAAA
CCCC

Inserting into a named region

Provide pool and region to insert each sequence into a fixed context.

bg   = pp.from_seq("AAAA<cre>XXXX</cre>TTTT")
pool = pp.from_seqs(
    ["ACGT", "TGCA", "GGCC"],
    pool=bg,
    region="cre",
    mode="sequential",
)
pool.print_library()

pool: seq_length=4, num_states=3 AAAA<cre>ACGT</cre>TTTT
AAAA<cre>TGCA</cre>TTTT
AAAA<cre>GGCC</cre>TTTT

See from_seqs().