biocrnpyler.core.component

Classes

Component(name[, mechanisms, parameters, ...])

Base class for biomolecular components in BioCRNpyler.

class biocrnpyler.core.component.Component(name: str | Species, mechanisms=None, parameters=None, parameter_file=None, mixture=None, compartment=None, attributes=None, initial_concentration=None, initial_condition_dictionary=None)[source]

Base class for biomolecular components in BioCRNpyler.

Component subclasses represent different kinds of biomolecules such as DNA, RNA, proteins, and complexes. Components interact with mechanism objects to generate chemical reaction network (CRN) species and reactions during compilation. This class must be subclassed to provide functionality by overriding the update_species and update_reactions methods.

Parameters:

namestr or Species: Name of the component. If a Species object is provided, its name attribute will be used.
mechanismsdict or list, optional: Custom mechanisms to override default mechanisms from the mixture. Can be a dict with mechanism types (str) as keys and mechanism objects as values, or a list of mechanism objects.
parametersdict, optional: Dictionary of parameter values to add to the component’s parameter database. Keys follow the format (mechanism, part_id, param_name).
parameter_filestr, optional: Path to a parameter file (CSV or TSV format) to load into the component’s parameter database.
mixtureMixture, optional: Reference to the Mixture object containing this component. The mixture provides default mechanisms and parameters.
compartmentCompartment, optional: The Compartment object representing the physical location of this component.
attributeslist of str, optional: List of attribute strings to tag the component and its associated species. Attributes can be used for mechanism selection and species filtering.
initial_concentrationfloat, optional: Initial concentration of the component’s primary species. Must be non-negative. This value is added to the parameter database with key (‘initial concentration’, None, component.name).
initial_condition_dictionarydict, optional: Dictionary mapping species (or species names) to initial concentration values for components with multiple species.

Attributes:

namestr: The name of the component.
mechanismsdict: Dictionary of mechanisms specific to this component, keyed by mechanism type (str).
mixtureMixture or None: Reference to the mixture containing this component.
compartmentCompartment or None: Compartment or None: The compartment containing this component.
attributeslist of str: List of attribute tags associated with this component.
parameter_databaseParameterDatabase: Database storing all parameters associated with this component.
initial_concentrationfloat or None: Initial concentration value for the component’s primary species.
initial_condition_dictionarydict: Dictionary of initial conditions for species generated by this component.

See also

Mechanism: Base class for reaction generation schemas.
Mixture: Container for components, mechanisms, and global parameters.
Species: Represents chemical species in a CRN.

Notes

This is an abstract base class. Direct instantiation is possible but subclasses like DNA, RNA, Protein, or DNAassembly should be used for specific biomolecular functionality.

The parameter lookup hierarchy is:

Component.parameter_database
Component.mixture.parameter_database (if mixture is set)

Examples

Create a basic component with custom parameters:

>>> comp = bcp.Component(
...     name='MyComponent',
...     parameters={'kb': 100, 'ku': 10},
...     initial_concentration=50.0
... )
>>> comp.name
'MyComponent'

__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.

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.

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:

Component.parameter_database
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.

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() → List[Species][source]

Generate and return reactions associated with this component.

Returns:

list of Reaction: List of reaction objects generated by this component. This base implementation returns an empty list.

Notes

This method should be overridden by subclasses to return the actual reactions generated by the component during CRN compilation.

update_species() → List[Species][source]

Generate and return species associated with this component.

Returns:

list of Species: List of species objects generated by this component. This base implementation returns an empty list.

Notes

This method should be overridden by subclasses to return the actual species generated by the component during CRN compilation.