biocrnpyler.components.integrase_enumerator

Classes

IntegraseRule([name, reactions, ...])	Rules defining integrase recombination reactions and products.
Integrase_Enumerator(name[, int_mechanisms])	Global enumerator for integrase-mediated DNA recombination products.
Polymer_transformation(partslist[, ...])	Template for transforming polymer sequences through recombination.

class biocrnpyler.components.integrase_enumerator.IntegraseRule(name=None, reactions=None, allow_deletion=True, allow_integration=True, allow_inversion=True)

Rules defining integrase recombination reactions and products.

An IntegraseRule specifies how an integrase enzyme acts on attachment sites to generate recombined DNA products. Defines which site pairs can react, what products they form, and which reaction types (deletion, integration, inversion) are allowed.

Parameters:

namestr, optional

Name of the integrase (default=’int1’).

reactionsdict, optional

Dictionary mapping (site1_type, site2_type) tuples to product site type. Default: {(‘attB’, ‘attP’): ‘attL’, (‘attP’, ‘attB’): ‘attR’}

allow_deletionbool, default=True

Whether to allow deletion reactions (intramolecular, same direction).

allow_integrationbool, default=True

Whether to allow integration reactions (intermolecular).

allow_inversionbool, default=True

Whether to allow inversion reactions (intramolecular, opposite directions).

Attributes:

namestr

Integrase name.

integrase_speciesSpecies

The integrase protein species.

reactionsdict

Reaction rules mapping site pairs to products.

attsiteslist

All attachment site types involved in reactions.

allow_deletionbool

Whether deletions are allowed.

allow_integrationbool

Whether integrations are allowed.

allow_inversionbool

Whether inversions are allowed.

integrations_to_dolist

List of integrations to perform during compilation.

See also

IntegraseSite

DNA part representing attachment sites.

Integrase_Enumerator

Enumerator using integrase rules.

Polymer_transformation

Template for DNA transformations.

Notes

Integrase mechanism types:

1. Serine Integrases:

   • Recombine attB + attP –> attL + attR

   • Require matching dinucleotides

   • With directionality factors: attL + attR –> attB + attP

2. Tyrosine Recombinases (Cre, Flp):

   • Homotypic sites: loxP + loxP –> loxP + loxP

   • Can be palindromic (bidirectional)

3. Invertases:

   • Only perform inversion reactions

   • Set allow_deletion=False, allow_integration=False

4. Resolvases:

   • Only perform deletion reactions

   • Set allow_inversion=False, allow_integration=False

Reaction Types:

• Inversion: Two sites on same DNA, opposite directions –> region between sites flips

• Deletion: Two sites on same DNA, same direction –> region between sites excised (forms circular product)

• Integration: Sites on different DNAs –> DNAs join

• Recombination: Two linear DNAs –> two recombinant linear DNAs

Examples

Define a standard serine integrase:

>>> int_rule = bcp.IntegraseRule(
...     name='PhiC31',
...     reactions={
...         ('attB', 'attP'): 'attL',
...         ('attP', 'attB'): 'attR'
...     }
... )

Define a Cre recombinase (homotypic):

>>> cre_rule = bcp.IntegraseRule(
...     name='Cre',
...     reactions={
...         ('loxP', 'loxP'): 'loxP',
...         ('loxP', 'loxP'): 'loxP'  # Symmetric
...     }
... )

Define an invertase (inversion only):

>>> inv_rule = bcp.IntegraseRule(
...     name='Hin',
...     reactions={('hixL', 'hixR'): 'hixL', ('hixR', 'hixL'): 'hixR'},
...     allow_deletion=False,
...     allow_integration=False
... )

binds_to()

Get all attachment site types this integrase binds to.

Returns:

list of str

List of all site types involved in integrase reactions.

generate_products(site1, site2, site2_parent=None)

Generate product sites from recombination of two sites.

Creates IntegraseSite objects for the products of site1 + site2 recombination according to the reaction rules.

Parameters:

site1IntegraseSite

First attachment site (determines product ordering).

site2IntegraseSite

Second attachment site.

site2_parentPolymer, optional

Parent polymer for site2 (used in intermolecular reactions).

Returns:

tuple of (IntegraseSite, IntegraseSite)

Product sites at positions corresponding to site1 and site2.

Raises:

AssertionError

If sites have mismatched integrases or dinucleotides.

KeyError

If site pair is not in reaction rules.

Notes

Product sites inherit dinucleotides and integrase from reactants. Product order depends on site1 direction:

• site1 forward: return (prod1, prod2)

• site1 reverse: return (prod2, prod1) with swapped directions

integrate(site1, site2, also_inter=True, force_inter=False, existing_dna_constructs=None)

Perform integrase recombination between two attachment sites.

Executes an integration reaction between site1 and site2, creating new DNA constructs based on the reaction type (inversion, deletion, integration, or recombination). Stores transformation templates in the sites’ linked_sites attribute.

Parameters:

site1IntegraseSite

First attachment site (must have Construct parent).

site2IntegraseSite

Second attachment site (must have Construct parent).

also_interbool, default=True

If True and reaction is intramolecular, also generate intermolecular version (between two copies of same plasmid).

force_interbool, default=False

Force reaction to be treated as intermolecular even if sites are on same construct.

existing_dna_constructslist of Construct, optional

List of previously generated constructs to check for duplicates.

Returns:

list of Construct

List of newly created DNA constructs from the integration.

Raises:

ValueError

If either site is not part of a Construct.

Notes

Four reaction types:

1. Inversion (intramolecular, opposite directions):

   • Same construct, sites point opposite directions

   • Result: Region between sites is flipped

   • Circularity preserved

2. Deletion (intramolecular, same direction):

   • Same construct, sites point same direction

   • Result: Two constructs - one with deleted region, one circular excised fragment

3. Integration (intermolecular, one circular):

   • Sites on different constructs, one circular

   • Result: Single construct (circular if both were circular)

4. Recombination (intermolecular, both linear):

   • Sites on two linear constructs

   • Result: Two recombinant linear constructs

Polymer_transformation templates are stored in:

• site1.linked_sites[(site2, intermolecular)]

• site2.linked_sites[(site1, intermolecular)]

These templates are used during CRN compilation to generate reactions and species.

Existing_dna_constructs are checked for matches (including circular permutations and reversals) to avoid creating duplicates.

Examples

Inversion reaction:

>>> # Two sites on same plasmid, opposite directions
>>> int_rule.integrate(attB_site, attP_site_reversed)
# Creates inverted plasmid

Integration reaction:

>>> # Sites on different plasmids
>>> int_rule.integrate(
...     plasmid1_attB,
...     plasmid2_attP,
...     existing_dna_constructs=prev_constructs
... )
# Creates integrated plasmid

reaction_allowed(site1, site2)

Check if two sites can undergo integrase recombination.

Parameters:

site1IntegraseSite

First attachment site.

site2IntegraseSite

Second attachment site.

Returns:

bool

True if sites can react according to reaction rules.

Raises:

AssertionError

If sites have different integrases or do not match this integrase.

reactive_sites()

Get attachment site types that participate in reactions.

Returns:

list of str

List of site types that can be reactants (not just products).

class biocrnpyler.components.integrase_enumerator.Integrase_Enumerator(name: str, int_mechanisms=None)

Global enumerator for integrase-mediated DNA recombination products.

An Integrase_Enumerator systematically enumerates all possible DNA constructs that can result from integrase-mediated recombination reactions. Examines all components for integrase attachment sites and generates products for all allowed site pairs.

Parameters:

namestr

Name identifier for the enumerator.

int_mechanismsdict, optional

Dictionary mapping integrase names (str) to IntegraseRule objects. Default: {‘int1’: IntegraseRule()}

Attributes:

int_mechanismsdict

Dictionary of integrase rules.

See also

GlobalComponentEnumerator

Base class for global enumeration.

IntegraseRule

Defines integrase recombination rules.

IntegraseSite

DNA part for attachment sites.

Polymer_transformation

Template for DNA rearrangements.

Notes

Enumeration process:

1. Identify all integrase attachment sites in components

2. Group sites by integrase type

3. For each integrase:

   1. Find all valid site pairs (from reactive_sites)

   2. Check if pair can react (reaction_allowed)

   3. Perform integration to generate products

   4. Store transformation templates in sites

4. Return list of new DNA constructs

This is a global enumerator because integrase reactions can occur between sites on different constructs (intermolecular reactions). Access to all components is necessary.

Integrase Types Supported:

• Serine integrases (attB/attP –> attL/attR)

• Tyrosine recombinases (Cre, Flp with homotypic sites)

• Invertases (inversion only)

• Resolvases (deletion only)

• Custom integrase rules

The find_dna_construct method is used to detect duplicates including circular permutations and reversals, preventing redundant construct generation.

Examples

Create an integrase enumerator:

>>> phi_c31 = bcp.IntegraseRule(
...     name='PhiC31',
...     reactions={
...         ('attB', 'attP'): 'attL',
...         ('attP', 'attB'): 'attR'
...     }
... )
>>> enumerator = bcp.Integrase_Enumerator(
...     name='integrase_enum',
...     int_mechanisms={'PhiC31': phi_c31}
... )

Use in a mixture:

>>> mixture = bcp.Mixture(
...     components=[plasmid1, plasmid2],
...     global_component_enumerators=[enumerator]
... )
>>> # Enumerator automatically called during compilation
>>> crn = mixture.compile_crn()

Manual enumeration:

>>> constructs = [plasmid_with_attB, plasmid_with_attP]
>>> new_constructs = enumerator.enumerate_components(constructs)
>>> # new_constructs contains integrated plasmids

enumerate_components(components=None, previously_enumerated=None, **kwargs)

Enumerate all possible integrase-mediated DNA configurations.

Systematically generates all DNA constructs that can result from integrase recombination between attachment sites in the input components.

Parameters:

componentslist of Component, optional

List of components to enumerate. Only DNA_construct objects are processed.

previously_enumeratedlist of Component, optional

List of components already enumerated (used for duplicate detection).

**kwargs

Additional keyword arguments (unused).

Returns:

list of Construct

List of newly created DNA constructs from all allowed integrase reactions.

Notes

Enumeration algorithm:

1. Extract all DNA_construct components

2. List all integrase sites by integrase type

3. For each integrase in int_mechanisms:

   1. Get all attachment sites for that integrase

   2. Find reactive site types from IntegraseRule

   3. Generate all site pairs (combinations)

   4. For each valid pair:

      • Check if reaction_allowed

      • Perform integrate to generate products

      • Add new constructs to output list

4. Return all newly generated constructs

Depending on the IntegraseRule settings, the following reaction types are generated:

• Inversions (same construct, opposite directions)

• Deletions (same construct, same direction)

• Integrations (different constructs, at least one circular)

• Recombinations (two linear constructs)

The integrate method checks existing_dna_constructs (includes both previously_enumerated and newly created constructs) to avoid generating duplicates.

Examples

Enumerate integration products:

>>> enumerator = bcp.Integrase_Enumerator(
...     name='enum',
...     int_mechanisms={'PhiC31': phi_c31_rule}
... )
>>> plasmids = [donor_plasmid, target_plasmid]
>>> products = enumerator.enumerate_components(plasmids)
>>> # products contains integrated plasmids

classmethod find_dna_construct(construct: Construct, conlist: List[Construct])

Find matching construct in list (handles permutations/reversals).

Searches for a construct equivalent to the input, accounting for circular permutations and reversals.

Parameters:

constructConstruct

Construct to find.

conlistlist of Construct

List of constructs to search.

Returns:

tuple of (Construct, callable) or None

If found: (matched_construct, index_function), where index_function maps old indexes to (new_index, direction). If not found: None.

Raises:

KeyError

If construct matches multiple constructs in list (should not happen with proper generation order).

Notes

For circular constructs, the following matching logic is used:

• Try all circular permutations

• For each permutation, try forward and reverse orientations

For linear constructs, the following matching logic is used:

• Try forward orientation

• Try reverse orientation

Uses directionless_hash for fast initial filtering before detailed species comparison.

list_integrase(construct)

List all integrase attachment sites in a construct.

Parameters:

constructConstruct

DNA construct to examine.

Returns:

dict

Dictionary mapping integrase names (str) to lists of IntegraseSite objects.

reset(components=None, **kwargs)

Reset linked_sites attribute in all attachment sites.

Clears stored integration reactions from all integrase sites in components, preparing for fresh enumeration.

Parameters:

componentslist of Component

Components containing integrase sites to reset.

**kwargs

Additional keyword arguments (unused).

Notes

Called at the start of enumeration to clear previous integration data.

class biocrnpyler.components.integrase_enumerator.Polymer_transformation(partslist, circular=False, parentsdict=None, material_type='dna')

Template for transforming polymer sequences through recombination.

A Polymer_transformation defines a template for creating new polymers from existing ones through recombination reactions. The template specifies a parts list containing placeholders (monomers from input polymers) and new parts (with no parent). This enables complex DNA rearrangements like integration, deletion, and inversion.

Parameters:

partslistlist

List of parts defining the output polymer. Can contain:

• OrderedMonomers from existing polymers (placeholders)

• Parts with parent=None (inserted into new polymer)

• Tuples of (part, direction)

circularbool, default=False

Whether the output polymer should be circular.

parentsdictdict, optional

Dictionary mapping parent polymers to input names (‘input1’, ‘input2’, etc.). If None, automatically generated.

material_typestr, default=’dna’

Material type for the created polymer.

Attributes:

number_of_inputsint

Number of distinct input polymers required.

parentsdictdict

Mapping from parent polymers to generic input names.

partslistlist

Template parts list with dummy placeholders.

circularbool

Whether output is circular.

material_typestr

Material type of output polymer.

See also

IntegraseRule

Defines integrase recombination rules.

Integrase_Enumerator

Enumerates integrase products.

OrderedMonomer

Monomer in ordered polymer.

Notes

The transformation works by:

1. Analyzing partslist to identify parent polymers

2. Creating generic ‘input#’ placeholders for each parent

3. Storing template with dummy placeholders

4. When applied via create_polymer, replacing placeholders with actual parts from input polymers

Placeholder system:

• Parts from polymers become placeholders referencing position in ‘input#’

• Parts with parent=None are copied directly into output

• Complexes bound to parts are transferred to new positions

Examples

Create a simple transformation template:

>>> # Define template: take element 0 from input1, element 2 from
>>> # input2 (reversed), and insert a promoter
>>> template = Polymer_transformation(
...     partslist=[
...         polymer1[0],  # Placeholder for position 0
...         [polymer2[2], 'reverse'],  # Position 2, reversed
...         promoter  # New part (parent=None)
...     ],
...     circular=False
... )
>>> # Apply template to create new polymer
>>> new_polymer = template.create_polymer([polymer1, polymer2])

Integration reaction template:

>>> # Combine two plasmids at cut sites
>>> template = Polymer_transformation(
...     partslist=(
...         plasmid1[:cut1] +
...         [[prod_site1, 'forward']] +
...         plasmid2[cut2+1:] +
...         [[prod_site2, 'forward']] +
...         plasmid1[cut1+1:]
...     ),
...     circular=True
... )

create_polymer(polymer_list, **kwargs)

Create a new polymer from the template using input polymers.

Applies the transformation template to concrete input polymers, replacing placeholders with actual parts and inserting new parts.

Parameters:

polymer_listlist of Polymer

List of input polymers. Must have at least number_of_inputs polymers. Order matters: first polymer is ‘input1’, second is ‘input2’, etc.

**kwargs

Additional keyword arguments (currently unused).

Returns:

Polymer

New polymer created by applying the transformation. Type matches the input polymers’ class.

Notes

Transformation process:

1. Map polymer_list to ‘input#’ names

2. For each template part:

   • If placeholder: grab part from appropriate input polymer at specified position

   • If new part: insert the part or its dna_species

   • Handle complex species bound to parts

3. Create output polymer with specified circularity

When transforming parts with bound complexes, the method attempts to preserve bindings by replacing core parts within complexes.

classmethod dummify(in_polymer, name)

Create a simplified placeholder polymer.

Generates a generic polymer with the same structure (length, directions, circularity) as the input but without specific parts. Used for creating template placeholders.

Parameters:

in_polymerPolymer

The polymer to simplify.

namestr

Name for the dummy polymer (e.g., ‘input1’).

Returns:

NamedPolymer

Simplified polymer with generic OrderedMonomers at each position.

Notes

The dummy polymer preserves only structural information (number of monomers, their directions, and circularity) while removing specific part identities.

get_renumbered(output_renumbering_function)

Return copy of transformation with output indexes renumbered.

Parameters:

output_renumbering_functioncallable

Function mapping old indexes to (new_index, direction) tuples.

Returns:

Polymer_transformation

Copy of this transformation with renumbered output.

renumber_output(output_renumbering_function)

Change the ordering of the output parts list.

Applies a renumbering function to rearrange the parts in the template, useful for handling circular permutations or reversals.

Parameters:

output_renumbering_functioncallable

Function that takes an index (int) and returns tuple of (new_index, direction), where direction is ‘f’ (forward) or ‘r’ (reverse).

Notes

Modifies self.partslist in place. Used to adjust transformations when matching against existing constructs.

reversed()

Return circularly permuted version with rotated inputs.

Creates a new transformation where inputs are shuffled: input1 becomes input2, input2 becomes input3, …, last input becomes input1. Used for handling symmetric integrase reactions.

Returns:

Polymer_transformation

New transformation with rotated input assignments.

Notes

For single-input transformations, returns self unchanged. Essential for bidirectional integrase reactions where site1/site2 roles can be swapped.