biocrnpyler.components.combinatorial_complex

Classes

CombinatorialComplex(final_states[, ...])

Complex formed through combinatorial binding of multiple species.
class biocrnpyler.components.combinatorial_complex.CombinatorialComplex(final_states, initial_states=None, intermediate_states=None, excluded_states=None, name=None, **kwargs)[source]

Complex formed through combinatorial binding of multiple species.

A CombinatorialComplex component represents a complex that can form through multiple combinatorial binding pathways. The component enumerates all possible intermediate complexes and generates binding reactions between initial states and final states, optionally constrained by intermediate states and excluded states. Uses a ‘binding’ mechanism to generate combinatorial binding reactions.

Parameters:
final_statesComplexSpecies or list of ComplexSpecies

The final complex(es) to be formed. All binding reactions ultimately lead to these states.

initial_stateslist of Species or ComplexSpecies, optional

Starting species that bind together to form final_states. If None, defaults to all individual species contained within final_states.

intermediate_stateslist of ComplexSpecies, optional

Allowed intermediate complexes formed during binding. Restricts the binding pathway. If None, all possible intermediates are enumerated.

excluded_stateslist of Species or ComplexSpecies, optional

Species or complexes that are NOT allowed to form. If None, no complexes are excluded.

namestr, optional

Name of the component. If None, automatically generated from final_states names.

**kwargs

Additional keyword arguments passed to the Component base class constructor.

Attributes:
final_stateslist of ComplexSpecies

List of final complex states to be formed.

initial_stateslist of Species or ComplexSpecies

List of initial states for binding.

intermediate_stateslist of ComplexSpecies or None

List of allowed intermediate complexes.

excluded_stateslist

list: Species or complexes excluded from enumeration.

sub_specieslist of Species

All individual species contained in final_states.

combination_dictdict

Dictionary storing computed binding combinations.

See also

ChemicalComplex

Simple complex of two or more molecules.

Component

Base class for biomolecular components.

ComplexSpecies

Species subclass for molecular complexes.

Notes

The combinatorial binding process generates reactions based on the provided constraints:

Case 1 - only final_states given: all species in final_states bind combinatorially:

individual_species <–> all_intermediates <–> final_states

Case 2 - final_states + initial_states: binding starts from specified initial states directly to final states:

initial_states <–> final_states

Case 3 - final_states + intermediate_states: binding restricted to specified intermediates:

individual_species <–> intermediate_states <–> final_states

Case 4 - final_states + initial_states + intermediate_states: both initial and intermediate constraints applied:

initial_states <–> intermediate_states <–> final_states

The component name is automatically generated as a concatenation of final_states names separated by underscores if not provided.

Examples

Example 1: Full combinatorial binding

>>> A = bcp.Species('A')
>>> B = bcp.Species('B')
>>> C = bcp.Species('C')
>>> final = bcp.Complex([A, B, C])
>>> cc = bcp.CombinatorialComplex(
...     final_states=final,
...     mechanisms={'binding': bcp.One_Step_Binding()},
...     parameters={'kb': 1e-1, 'ku': 1e-1})

Initial states default to [A, B, C]. All intermediates [A, B], [A, C], [B, C] are enumerated, resulting in 6 reversible reactions:

  1. A + B <–> Complex([A, B])

  2. A + C <–> Complex([A, C])

  3. B + C <–> Complex([B, C])

  4. Complex([A, B]) + C <–> Complex([A, B, C])

  5. Complex([A, C]) + B <–> Complex([A, B, C])

  6. Complex([B, C]) + A <–> Complex([A, B, C])

Example 2: Constrained initial states

>>> initial = [bcp.Complex([A, B]), bcp.Complex([A, C])]
>>> cc = bcp.CombinatorialComplex(
...     final_states=final, initial_states=initial,
...     mechanisms={'binding': bcp.One_Step_Binding()},
...     parameters={'kb': 1e-1, 'ku': 1e-1})

Results in 2 reactions:

  1. Complex([A, B]) + C <–> Complex([A, B, C])

  2. Complex([A, C]) + B <–> Complex([A, B, C])

Example 3: Restricted intermediate states

>>> inter = [bcp.Complex([A, B]), bcp.Complex([A, C])]
>>> cc = bcp.CombinatorialComplex(
...     final_states=final, intermediate_states=inter,
...     mechanisms={'binding': bcp.One_Step_Binding()},
...     parameters={'kb': 1e-1, 'ku': 1e-1})

Results in 4 reactions:

  1. A + B <–> Complex([A, B])

  2. A + C <–> Complex([A, C])

  3. Complex([A, B]) + C <–> Complex([A, B, C])

  4. Complex([A, C]) + B <–> Complex([A, B, C])

Example 4: Multiple final states with homodimers

>>> final = [bcp.Complex([A, A, B]), bcp.Complex([A, B, B])]
>>> cc = bcp.CombinatorialComplex(
...     final_states=final,
...     mechanisms={'binding': bcp.One_Step_Binding()},
...     parameters={'kb': 1e-1, 'ku': 1e-1})

Results in 7 reactions including homodimer formation:

  1. A + A <–> Complex([A, A])

  2. Complex([A, A]) + B <–> Complex([A, A, B])

  3. B + B <–> Complex([B, B])

  4. Complex([B, B]) + A <–> Complex([A, B, B])

  5. A + B <–> Complex([A, B])

  6. Complex([A, B]) + A <–> Complex([A, A, B])

  7. Complex([A, B]) + B <–> Complex([A, B, B])

__hash__()[source]

Return hash(self).

add_attribute(attribute: str)[source]

Add a single attribute to the component.

Adds an attribute tag to the component’s attribute list and to its associated species object, if one exists. Attributes can be used for mechanism selection, species filtering, and tracking special properties.

Parameters:
attributestr

Attribute string to add to the component. Must be a non-None string value.

Raises:
AssertionError

If attribute is not a string or is None.

Warning

If the component has no internal species to which the attribute can be added.

Notes

Attributes are commonly used to tag components with properties such as:

  • Degradation tags (e.g., ‘degtagged’, ‘ssrAtagged’, )

  • Functional properties (e.g., ‘fluorescent’, ‘membranebound’)

  • Regulatory elements (e.g., ‘inducible’, ‘repressible’)

Examples

Add attributes to tag a protein with special properties:

>>> protein = bcp.Protein('GFP')
>>> protein.add_attribute('fluorescent')
>>> protein.add_attribute('ssrAtagged')
>>> protein.attributes
['fluorescent', 'ssrAtagged']
add_mechanism(mechanism: Mechanism, mech_type=None, overwrite=False, optional_mechanism=False)[source]

Add a mechanism to this component’s mechanism dictionary.

Parameters:
mechanismMechanism

The mechanism object to add.

mech_typestr, optional

The type key under which to store the mechanism. If None, uses the mechanism’s mechanism_type attribute.

overwritebool, default=False

If True, replaces any existing mechanism with the same key. If False, raises ValueError when key already exists.

optional_mechanismbool, default=False

If True, suppresses the ValueError when a mechanism key conflict occurs and overwrite is False.

Raises:
TypeError

If mechanism is not a Mechanism object, or if mech_type is not a string.

ValueError

If mechanism key already exists, overwrite is False, and optional_mechanism is False.

add_mechanisms(mechanisms: Mechanism | GlobalMechanism, overwrite=False, optional_mechanism=False)[source]

Add multiple mechanisms to this component.

Accepts mechanisms as a single object, list, or dictionary and adds them to the component’s mechanism dictionary.

Parameters:
mechanismsMechanism, GlobalMechanism, dict, or list

The mechanism(s) to add. Can be a single mechanism, a dict with mechanism types as keys and mechanisms as values, or a list of mechanisms.

overwritebool, default=False

If True, replaces any existing mechanisms with the same keys. If False, raises ValueError when keys already exist.

optional_mechanismbool, default=False

If True, suppresses ValueError when mechanism key conflicts occur and overwrite is False.

Raises:
ValueError

If mechanisms is not a valid type, or if mechanism key conflicts occur with overwrite=False and optional_mechanism=False.

property compartment

Compartment or None: The compartment containing this component.

compute_species_to_add(s0, sf)[source]

Compute species needed to convert s0 into complex sf.

Parameters:
s0Species or ComplexSpecies

Starting species or complex.

sfComplexSpecies

Target final complex.

Returns:
list of Species or None

List of species that need to be added to s0 to form sf. Returns None if s0 contains species not in sf or more copies of any species than sf contains.

Raises:
ValueError

If sf is not a ComplexSpecies.

Notes

This method compares the stoichiometry of species in s0 and sf to determine what needs to be added. If s0 contains more of any species than sf, or contains species not in sf, None is returned.

enumerate_components(previously_enumerated=None) → List[source]

Enumerate derived components created from this component.

This method generates new components based on the current component, typically used during CRN compilation to expand higher-level components into their constituent parts and products.

Parameters:
previously_enumeratedset or list, optional

Collection of components that have already been enumerated, used to prevent infinite recursion in component enumeration.

Returns:
list

List of new components created from this component. This base implementation returns an empty list.

Notes

Subclasses override this method to implement specific enumeration behavior. For example:

  • A DNA_construct returns copies of its parts and RNA_construct objects representing transcripts.

  • An RNA_construct returns copies of its parts and Protein components representing translation products.

property excluded_states

list: Species or complexes excluded from enumeration.

property final_states

List of final complex states to be formed.

Returns:
list of ComplexSpecies
get_combinations_between(s0, sf)[source]

Get all binding combinations to form complex sf from s0.

Enumerates all possible binding orders (permutations) to construct the final complex sf starting from s0, generating tuples of (binder, bindee, complex_species) for each binding step.

Parameters:
s0Species or ComplexSpecies

Starting species or complex.

sfComplexSpecies

Target final complex.

Returns:
list of tuple

List of (binder, bindee, complex_species) tuples representing all possible binding combinations. Each tuple represents one binding step. Returns empty list if no combinations are possible.

Notes

The method:

  1. Computes which species need to be added to s0 to form sf

  2. Generates all permutations of these species (different binding orders)

  3. For each permutation, creates binding steps: binder + bindee –> complex

  4. Filters out any combinations involving excluded_states

Examples

If s0 = A and sf = Complex([A, B, C]), and no exclusions:

Returns combinations for different binding orders:

  • Order 1: (B, A, [A,B]), (C, [A,B], [A,B,C])

  • Order 2: (C, A, [A,C]), (B, [A,C], [A,B,C])

get_mechanism(mechanism_type, optional_mechanism=False)[source]

Retrieve a mechanism by type from the component or its mixture.

Searches first in the component’s mechanism dictionary, then falls back to the mixture’s mechanisms if not found.

Parameters:
mechanism_typestr

The type identifier of the mechanism to retrieve (e.g., ‘transcription’, ‘translation’, ‘binding’).

optional_mechanismbool, default=False

If True, returns None when mechanism not found. If False, raises KeyError when mechanism not found.

Returns:
Mechanism or None

The requested mechanism object, or None if not found and optional_mechanism is True.

Raises:
TypeError

If mechanism_type is not a string.

KeyError

If mechanism not found and optional_mechanism is False.

get_parameter(param_name: str, part_id=None, mechanism=None, return_numerical=False, return_none=False, check_mixture=True) → Parameter | Real[source]

Retrieve parameter from component or mixture parameter database.

Searches first in the component’s parameter database, then falls back to the mixture’s parameter database if not found.

Parameters:
param_namestr

Name of the parameter to retrieve.

part_idstr, optional

Part identifier for the parameter lookup key.

mechanismstr, optional

Mechanism identifier for the parameter lookup key.

return_numericalbool, default=False

If True, returns the numerical value. If False, returns the Parameter object.

return_nonebool, default=False

If True, returns None when parameter not found. If False, raises ValueError when parameter not found.

check_mixturebool, default=True

If True, searches the mixture’s parameter database if not found in the component’s database.

Returns:
Parameter, Real, or None

The parameter object or its numerical value, or None if not found and return_none is True.

Raises:
ValueError

If parameter not found and return_none is False.

Notes

Parameter lookup follows the hierarchy:

  1. Component.parameter_database

  2. Component.mixture.parameter_database (if check_mixture is True)

get_species() → None[source]

Get the primary species associated with this component.

Returns:
None

Subclasses should override this method to return their primary Species object.

Notes

This is a placeholder that should be implemented by subclasses.

property initial_states

List of initial states for binding.

Returns:
list of Species or ComplexSpecies
property intermediate_states

List of allowed intermediate complexes.

Returns:
list of ComplexSpecies or None
set_attributes(attributes: List[str])[source]

Set multiple attributes for the component.

Adds a list of attribute tags to the component and its associated species by calling add_attribute for each attribute in the list.

Parameters:
attributeslist of str or None

List of attribute strings to add to the component. If None, no action is taken.

See also

add_attribute

Add a single attribute to the component.

Examples

>>> comp = bcp.Protein(name="MyProtein")
>>> comp.set_attributes(["degtagged", "fluorescent"])
>>> comp.attributes
['degtagged', 'fluorescent']
set_mixture(mixture) → None[source]

Set the mixture containing this component.

Parameters:
mixtureMixture or None

The mixture object that contains this component and provides default mechanisms and parameters.

classmethod set_species(species: Species | str, material_type=None, compartment=None, attributes=None) → Species[source]

Convert various inputs into Species objects.

Parameters:
speciesSpecies, str, Component, or list

The species to convert. Can be a Species object (returned as-is), a string (creates new Species), a Component (extracts its species), or a list of any of these types.

material_typestr, optional

Material type for the species (e.g., ‘dna’, ‘rna’, ‘protein’). Only used when creating new Species from strings.

compartmentCompartment, optional

Compartment to assign to the species. Only used when creating new Species from strings.

attributeslist of str, optional

Attributes to assign to the species. Only used when creating new Species from strings.

Returns:
Species or list of Species

The converted Species object(s). Returns a list if input was a list.

Raises:
ValueError

If the input cannot be converted to a valid Species.

update_parameters(parameter_file=None, parameters=None, parameter_database=None, overwrite_parameters=True)[source]

Update the parameter database with new parameters.

Parameters:
parameter_filestr, optional

Path to a CSV or TSV file containing parameters to load.

parametersdict, optional

Dictionary of parameters to add. Keys follow the format (mechanism, part_id, param_name).

parameter_databaseParameterDatabase, optional

Another parameter database to merge into component’s database.

overwrite_parametersbool, default=True

If True, new parameter values overwrite existing ones. If False, existing parameters are preserved.

update_reactions()[source]

Use ‘binding’ mechanism to generate combinatorial reactions.

Uses the ‘binding’ mechanism to generate reactions for all possible binding combinations between initial_states and final_states, optionally constrained by intermediate_states and excluding excluded_states.

Returns:
list of Reaction

List of all binding reactions (forward and reverse) along all enumerated pathways.

Notes

The method handles two cases:

With intermediate_states:

  1. Generate reactions: initial_states <–> intermediate_states

  2. Generate reactions: intermediate_states <–> final_states

Without intermediate_states:

Generate reactions: initial_states <–> final_states directly

Duplicate reactions are automatically filtered out. The method uses combination_dict computed by update_species() or computes it if needed. Reactions are symmetric, so (binder, bindee, complex) and (bindee, binder, complex) are treated as duplicates.

update_species()[source]

Use ‘binding’ mechanism to generate combinatorial species.

Uses the ‘binding’ mechanism to generate species for all possible binding combinations between initial_states and final_states, optionally constrained by intermediate_states and excluding excluded_states.

Returns:
list of Species

List of all unique species generated, including initial states, final states, and all intermediate complexes along binding pathways.

Notes

The method handles two cases:

With intermediate_states:

  1. Generate combinations: initial_states –> intermediate_states

  2. Generate combinations: intermediate_states –> final_states

Without intermediate_states:

Generate combinations: initial_states –> final_states directly

Duplicate species are automatically removed from the final list. The combination_dict is populated during this process for use by update_reactions.