biocrnpyler.components.CombinatorialConformation

class biocrnpyler.components.CombinatorialConformation(final_states, initial_states=None, intermediate_states=None, excluded_states=None, state_part_ids=None, name=None, **kwargs)[source]

Bases: Component

Polymer conformation with combinatorial internal binding complexes.

A CombinatorialConformation component represents a polymer conformation (made of one unique OrderedPolymerSpecies) with multiple internal complexes that can bind and unbind in many different ways. Unlike CombinatorialComplex where individual species are added one at a time, this component adds groups of species in single steps to form the appropriate complexes. Uses a ‘conformation_change’ mechanism.

Parameters:

final_states (PolymerConformation or list of PolymerConformation) – One or more final polymer conformations to be formed. All must contain the same unique OrderedPolymerSpecies.
initial_states (list of PolymerConformation, optional) – Initial polymer conformations that can bind/unbind to become final_states. If None or empty, defaults to the bare polymer without complexes.
intermediate_states (list of PolymerConformation, optional) – Allowed intermediate conformations formed when converting initial_states to final_states. If None, all possible intermediate conformations are enumerated.
excluded_states (list of PolymerConformation, optional) – Polymer conformations that will NOT be formed during enumeration. If None, no conformations are excluded.
state_part_ids (dict, optional) – Dictionary mapping PolymerConformation to string, used to generate shorter part-ids for conformations.
name (str, optional) – Name of the component. If None, uses the internal polymer name.
**kwargs – Additional keyword arguments passed to the Component base class constructor.

Attributes:

final_states (list of PolymerConformation) – List of final conformation states.
initial_states (list of PolymerConformation) – List of initial conformation states.
intermediate_states (list of PolymerConformation or None) – List of allowed intermediate conformations, or None if unrestricted.
excluded_states (list of PolymerConformation) – List of excluded conformations.
internal_polymer (OrderedPolymerSpecies) – The unique polymer species common to all conformations.
state_part_ids (dict) – Dictionary for custom part-id naming.
combination_dict (dict) – Dictionary storing computed conformation changes.

See also

CombinatorialComplex: Combinatorial binding of simple complexes.
PolymerConformation: Species subclass for polymer conformations.
Component: Base class for biomolecular components.

Notes

Key differences from CombinatorialComplex:

Operates on PolymerConformation objects instead of simple Species
All conformations must share the same OrderedPolymerSpecies
Adds groups of species simultaneously to form complexes
Uses ‘conformation_change’ mechanism instead of ‘binding’

Reaction generation: The component generates conformation change reactions based on constraints:

Without intermediate_states: initial_states \(\rightleftharpoons\) final_states
With intermediate_states: initial_states \(\rightleftharpoons\) intermediate_states \(\rightleftharpoons\) final_states

Validation requirements: All conformations must:

Be PolymerConformation objects
Contain exactly one unique OrderedPolymerSpecies
Have the same internal polymer

Examples

Create a simple conformational change system:

>>> A, B, C, S = (bcp.Species(s) for s in ['A', 'B', 'C', 'S'])
>>> pc = bcp.PolymerConformation(polymer=[A, A, B, C])
>>> # Form a complex A:B by binding positions 0 and 2
>>> c1 = bcp.Complex([pc.polymers[0][0], pc.polymers[0][2]])
>>> pc1 = c1.parent
>>> # Form two complexes: A:B and A:C:S (S is external)
>>> c2 = bcp.Complex([pc1.polymers[0][1], pc1.polymers[0][3], S])
>>> pc2 = c2.parent
>>> # Create component to enumerate reactions
>>> cc = bcp.CombinatorialConformation(
...     final_states=pc2,
...     parameters={'kf': 1, 'kr': 0.01})

Using a Mixture to generate species and reactions:

>>> mixture = bcp.Mixture(components=[cc])
>>> crn = mixture.compile_crn()

Methods

`add_attribute`	Add a single attribute to the component.
`add_mechanism`	Add a mechanism to this component's mechanism dictionary.
`add_mechanisms`	Add multiple mechanisms to this component.
`compute_species_changes`	Compute changes needed to convert conformation s0 into sf.
`enumerate_components`	Enumerate derived components created from this component.
`get_combinations_between`	Get all conformation change combinations from s0 to sf.
`get_mechanism`	Retrieve a mechanism by type from the component or its mixture.
`get_parameter`	Retrieve parameter from component or mixture parameter database.
`get_species`	Get the bare polymer conformation.
`set_attributes`	Set multiple attributes for the component.
`set_mixture`	Set the mixture containing this component.
`set_species`	Convert various inputs into Species objects.
`update_parameters`	Update the parameter database with new parameters.
`update_reactions`	Use 'conformation_change' mechanism to generate reactions.
`update_species`	Use 'conformation_change' mechanism to generate species.

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:

attribute (str) – 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:

mechanism (Mechanism) – The mechanism object to add.
mech_type (str, optional) – The type key under which to store the mechanism. If None, uses the mechanism’s mechanism_type attribute.
overwrite (bool, default False) – If True, replaces any existing mechanism with the same key. If False, raises ValueError when key already exists.
optional_mechanism (bool, 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:

mechanisms (Mechanism, 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.
overwrite (bool, default False) – If True, replaces any existing mechanisms with the same keys. If False, raises ValueError when keys already exist.
optional_mechanism (bool, 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

The compartment containing this component.

Type:: Compartment or None

compute_species_changes(s0, sf)[source]

Compute changes needed to convert conformation s0 into sf.

Analyzes what species need to be added and which complexes need to be merged to transform the initial conformation s0 into the final conformation sf. Assumes both conformations share the same underlying polymer.

Parameters:

s0 (PolymerConformation) – Starting conformation.
sf (PolymerConformation) – Target final conformation.

Returns:

Returns False if s0 cannot be additively transformed into sf. Otherwise returns (species_changes, merged_complexes) where:

species_changes: dict mapping (complex, positions) to list of external species to add
merged_complexes: dict mapping (complex, positions) to list of complexes from s0 that merge to form sf

Return type:

tuple of (dict, dict) or False

Notes

Returns False if:

s0 has more complexes at any position than sf
Any complex in sf cannot be formed additively from s0

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_enumerated (set or list, optional) – Collection of components that have already been enumerated, used to prevent infinite recursion in component enumeration.
Returns:: List of new components created from this component. This base implementation returns an empty list.
Return type:: 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 of excluded conformations.

Return type:: list of PolymerConformation

property final_states

List of final conformation states.

Return type:: list of PolymerConformation

get_combinations_between(s0, sf)[source]

Get all conformation change combinations from s0 to sf.

Enumerates all possible orders of complex formation to transform conformation s0 into sf, generating tuples representing each step.

Parameters:

s0 (PolymerConformation) – Starting conformation.
sf (PolymerConformation) – Target final conformation.

Returns:

List of (old_state, species_to_add, new_state) tuples representing all possible transformation pathways. Each tuple represents one conformation change step. Returns empty list if no valid pathways exist.

Return type:

list of tuple

Notes

The method:

Computes which species/complexes change between s0 and sf
Generates all permutations (different formation orders)
For each permutation, creates conformational change steps
Filters out any combinations involving excluded_states

Unlike CombinatorialComplex, this method adds groups of species simultaneously to form complete complexes at polymer positions.

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_type (str) – The type identifier of the mechanism to retrieve (e.g., ‘transcription’, ‘translation’, ‘binding’).
optional_mechanism (bool, default False) – If True, returns None when mechanism not found. If False, raises KeyError when mechanism not found.

Returns:

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

Return type:

Mechanism or None

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_name (str) – Name of the parameter to retrieve.
part_id (str, optional) – Part identifier for the parameter lookup key.
mechanism (str, optional) – Mechanism identifier for the parameter lookup key.
return_numerical (bool, default False) – If True, returns the numerical value. If False, returns the Parameter object.
return_none (bool, default False) – If True, returns None when parameter not found. If False, raises ValueError when parameter not found.
check_mixture (bool, default True) – If True, searches the mixture’s parameter database if not found in the component’s database.

Returns:

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

Return type:

Parameter, Real, or None

Raises:

ValueError – If parameter not found and return_none is False.

Notes

Parameter lookup follows the hierarchy:

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

get_species()[source]

Get the bare polymer conformation.

Returns:: The internal polymer without any complexes.
Return type:: PolymerConformation

property initial_states

List of initial conformation states.

Return type:: list of PolymerConformation

property intermediate_states

List of allowed intermediates.

Return type:: list of PolymerConformation 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:: attributes (list 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:: mixture (Mixture 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:

species (Species, 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_type (str, optional) – Material type for the species (e.g., ‘dna’, ‘rna’, ‘protein’). Only used when creating new Species from strings.
compartment (Compartment, optional) – Compartment to assign to the species. Only used when creating new Species from strings.
attributes (list of str, optional) – Attributes to assign to the species. Only used when creating new Species from strings.

Returns:

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

Return type:

Species or list of Species

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_file (str, optional) – Path to a CSV or TSV file containing parameters to load.
parameters (dict, optional) – Dictionary of parameters to add. Keys follow the format (mechanism, part_id, param_name).
parameter_database (ParameterDatabase, optional) – Another parameter database to merge into component’s database.
overwrite_parameters (bool, default True) – If True, new parameter values overwrite existing ones. If False, existing parameters are preserved.

update_reactions()[source]

Use ‘conformation_change’ mechanism to generate reactions.

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

Returns:: List of all conformation change reactions (forward and reverse) along all enumerated pathways.
Return type:: list of Reaction

Notes

The method handles two cases:

With intermediate_states:

Generate reactions: initial_states \(\rightleftharpoons\) intermediate_states

Generate reactions: intermediate_states \(\rightleftharpoons\) final_states

Without intermediate_states: generate reactions: initial_states \(\rightleftharpoons\) final_states directly.

Duplicate reactions are automatically filtered out using reactions_added_dict. The method uses combination_dict computed by update_species or computes it if needed.

update_species()[source]

Use ‘conformation_change’ mechanism to generate species.

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

Returns:: List of all unique species generated, including polymer conformations and any additional species involved in conformation changes.
Return type:: list of Species

Notes

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