recombine

Produce chimeric sequences by slicing multiple source pools at breakpoints and stitching together alternating segments. Requires at least two source pools of equal sequence length. Use mode='sequential' to enumerate all breakpoint combinations deterministically, or mode='random' (default) to draw chimeras stochastically.

import poolparty as pp
pp.init()

Parameters

Parameter	Type	Default	Description
`pool`	`Pool \| str \| None`	`None`	Parent pool or sequence string for region-based recombination. If provided with `region`, the recombined sequences replace the region content.
`sources`	`list[Pool]`	(required)	Tuple or list of at least two `Pool` objects to recombine. All sources must produce sequences of the same length.
`num_breakpoints`	`int`	`1`	Number of crossover breakpoints. A single breakpoint produces 2-segment chimeras; N breakpoints produce N+1 segments.
`positions`	`list[int] \| None`	`None`	Explicit list of breakpoint positions. `None` = positions chosen by the current `mode`.
`styles`	`list[str] \| None`	`None`	List of display styles cycled across segments. Any non-empty list is accepted; styles wrap around if shorter than the segment count.
`style_by`	`str`	`'order'`	`'order'` styles segments by position in the chimera; `'source'` styles them by which source pool they came from.
`region`	`str \| None`	`None`	Region to restrict recombination to: a tag name (`str`), an explicit `[start, stop]` interval, or `None` for the full sequence.
`mode`	`str`	`'random'`	`'random'` selects breakpoints randomly; `'sequential'` enumerates all breakpoint positions; `'fixed'` uses `positions` exactly once.
`num_states`	`int \| None`	`None`	Number of output states. `None` auto-computes in sequential mode or defaults to 1 in random mode.
`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 recombine() in the API Reference.

Examples

Two sources, single breakpoint

Enumerate all single-crossover chimeras between two 10-base sequences. Each breakpoint position produces two states (one per source ordering), yielding 18 chimeras total.

src_a = pp.from_seq("AAAAAAAAAA")
src_b = pp.from_seq("CCCCCCCCCC")
rec   = pp.recombine(sources=[src_a, src_b], mode="sequential")
rec.print_library()

rec: seq_length=10, num_states=18 ACCCCCCCCC
CAAAAAAAAA
AACCCCCCCC
CCAAAAAAAA
AAACCCCCCC ... (18 total)

Random chimeras (mode=”random”)

mode='random' draws breakpoints stochastically, producing a different chimera each draw. Use num_states to sample several chimeras at once.

src_a = pp.from_seq("AAAAAAAAAA")
src_b = pp.from_seq("CCCCCCCCCC")
rec   = pp.recombine(sources=[src_a, src_b], mode="random", num_states=5)
rec.print_library()

rec: seq_length=10, num_states=5 AAAAAAAAAC
CCCCCCCCCA
AACCCCCCCC
CCCAAAAAAA
CCCCCAAAAA

Two breakpoints (num_breakpoints=2)

Two crossover points divide each chimera into three segments. With mode='sequential' every combination of two breakpoint positions is enumerated.

src_a = pp.from_seq("AAAAAAAAAA")
src_b = pp.from_seq("CCCCCCCCCC")
rec   = pp.recombine(sources=[src_a, src_b], num_breakpoints=2,
                     mode="sequential")
rec.print_library()

rec: seq_length=10, num_states=72 ACAAAAAAAA
CACCCCCCCC
ACCAAAAAAA
CAACCCCCCC
ACCCAAAAAA ... (72 total)

Fixed breakpoint position (positions)

positions=[5] pins the breakpoint after index 5, so chimeras always split into a 6-character head and a 4-character tail. With two sources this yields exactly 2 states.

src_a = pp.from_seq("AAAAAAAAAA")
src_b = pp.from_seq("TTTTTTTTTT")
rec   = pp.recombine(sources=[src_a, src_b], positions=[5],
                     mode="sequential")
rec.print_library()

rec: seq_length=10, num_states=2 AAAAAATTTT
TTTTTTAAAA

Color segments by source (style_by=”source”)

style_by='source' applies the same colour to every segment originating from the same source pool, regardless of its position in the chimera.

src_a = pp.from_seq("AAAAAAAAAA")
src_b = pp.from_seq("CCCCCCCCCC")
rec   = pp.recombine(
    sources=[src_a, src_b],
    num_breakpoints=2,
    styles=["blue", "red"],
    style_by="source",
    mode="sequential",
)
rec.print_library()

rec: seq_length=10, num_states=72 ACAAAAAAAA
CACCCCCCCC
ACCAAAAAAA
CAACCCCCCC
ACCCAAAAAA ... (72 total)

See recombine().