biocrnpyler.components.dna.rbs

Classes

RBS(name[, assembly, transcript, protein, ...])

Ribosome binding site component for translation control.

class biocrnpyler.components.dna.rbs.RBS(name: str, assembly=None, transcript=None, protein=None, length=0, mechanisms=None, parameters=None, **kwargs)[source]

Ribosome binding site component for translation control.

An RBS (ribosome binding site) represents a regulatory element that controls translation of a protein from an RNA transcript. The component uses the ‘translation’ mechanism to generate species and reactions for ribosome binding and protein production. The RBS must be included in a DNAassembly or DNA_construct to function properly during CRN compilation.

Parameters:

namestr: Name of the RBS.
assemblyDNAassembly, optional: The DNA assembly containing this RBS. If provided, the assembly’s name is used to generate default transcript and protein species.
transcriptRNA, str, or None, optional: The RNA transcript containing this RBS. If None and assembly is provided, creates an RNA species using the assembly’s name.
proteinProtein, str, or None, optional: The protein product of translation. If None and assembly is provided, creates a Protein species using the assembly’s name.
lengthint, default=0: Length of the RBS sequence in base pairs.
mechanismsdict or list, optional: Custom mechanisms for this RBS, overriding mixture defaults.
parametersdict, optional: Parameter values specific to this RBS.
**kwargs: Additional keyword arguments passed to the parent DNA_part class.

Attributes:

transcriptSpecies or None: The RNA transcript containing the RBS.
proteinSpecies or None: The protein product of translation.
assemblyDNAassembly or None: The DNA assembly containing this RBS.
lengthint: Length of the RBS in base pairs.

See also

Promoter: Component for transcription control.
DNAassembly: Container for RBS and genetic constructs.
DNA_part: Base class for DNA component parts.

Notes

The RBS cannot have initial concentrations set directly. Initial conditions must be set on the containing DNAassembly or DNA_construct.

The translation mechanism generates reactions for ribosome binding to the transcript and subsequent protein production.

Examples

Create a basic RBS:

>>> rbs = bcp.RBS(
...     name='rbs1',
...     transcript='mRNA_gfp',
...     protein='protein_gfp'
... )

Create an RBS within an assembly:

>>> assembly = bcp.DNAassembly(name='gene_x')
>>> rbs = bcp.RBS(
...     name='rbs_strong',
...     assembly=assembly
... )

__eq__(other)[source]

Test equality between two DNA_parts.

Parts are equal if they have the same type, name, parent assembly/ construct, direction, and position.

Parameters:

otherDNA_part: The other part to compare with.

Returns:

bool: True if parts are equal, False otherwise.

Notes

Equality requires matching:

Type (both must be the same DNA_part subclass)
Name (identical names)
Assembly/parent (same parent construct or both have None)
Direction (both forward or both reverse)
Position (same position in parent construct)

Parts are considered equal even if their parent constructs are different objects, as long as the string representations of the parents match.

__hash__()[source]

Compute hash value for this monomer.

Returns:

int: Hash value based on position, direction, name (if present), and parent.

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.

clone(position, direction, parent_dna)[source]

Attach this part to a specific position in a DNA construct.

Parameters:

positionint: Position in the parent DNA where this part should be placed.
directionstr: Orientation of the part: ‘forward’ or ‘reverse’.
parent_dnaDNA_construct or OrderedPolymer: The DNA construct that will contain this part.

Returns:

DNA_part: Returns self after setting position and parent.

Notes

This method establishes the relationship between a part and its containing construct, setting the part’s position and orientation.

property compartment: Compartment or None: The compartment containing this component.

property dna_species

Species: The chemical species representation of this DNA part.

Returns a Species object with material_type=’part’ representing this DNA_part as a chemical species in the CRN.

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.

find_polymer_component()[source]

Find the polymer component within this monomer or its species.

Searches this monomer and, if it is a ComplexSpecies, its constituent species to find which one is marked as a polymer component.

Returns:

OrderedMonomer or None: The monomer that is part of a polymer structure, or None if no polymer component is found.

Raises:

ValueError: If multiple species are marked as polymer components in the same location.

Notes

This method is primarily used internally to handle complex species that may contain monomers as part of larger structures.

classmethod from_rbs(name, assembly, transcript, protein)[source]

Create an RBS instance from another RBS or string.

Factory method for creating RBS objects from various input types.

Parameters:

nameRBS or str: Either a string name for a new RBS, or an existing RBS object to copy.
assemblyDNAassembly: The assembly containing this RBS.
transcriptRNA or str: The RNA transcript containing the RBS.
proteinProtein or str: The protein product of translation.

Returns:

RBS: A new RBS instance. If name is an RBS, returns a deep copy with updated assembly, transcript, and protein attributes.

Raises:

TypeError: If name is neither a string nor an RBS.

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_orphan()[source]

Create a copy of this monomer without a parent reference.

Returns a copy that retains position and direction but has no parent polymer. Useful for temporarily working with monomers outside their polymer context.

Returns:

OrderedMonomer: A copy of this monomer with parent set to None but position and direction preserved.

See also

get_removed: Create a fully detached copy.
remove: Remove this monomer from its parent in place.

Notes

This is a shallow copy of the monomer object itself, though the parent reference is explicitly cleared.

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_removed()[source]

Create a fully detached copy of this monomer.

Returns a copy with all polymer-related attributes (parent, position, direction) cleared. Also removes ‘forward’ and ‘reverse’ attributes if present.

Returns:

OrderedMonomer: A copy of this monomer with no parent, position, or direction, and with directional attributes removed.

See also

get_orphan: Create a copy without parent but with position and direction.
remove: Remove this monomer from its parent in place.

Notes

This method is useful for creating completely independent copies of monomers that can be reused in different contexts without any polymer associations.

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.

monomer_insert(parent: OrderedPolymer, position: int, direction=None)[source]

Insert this monomer into a polymer at a specific position.

Sets the monomer’s parent, position, and direction attributes to reflect its insertion into the polymer. Marks the monomer (or its polymer component if it is a complex species) as a polymer component.

Parameters:

parentOrderedPolymer: The polymer to insert this monomer into.
positionint: The position index where this monomer is being inserted.
directionstr, int, or None, optional: The direction for this monomer. If None, uses the monomer’s existing direction.

Raises:

ValueError: If position is None, or if parent is None.

remove()[source]

Remove this monomer from its parent polymer.

Clears the monomer’s parent, position, and direction attributes, effectively detaching it from any polymer structure.

Returns:

OrderedMonomer: Returns self for method chaining.

See also

get_removed: Create a fully detached copy of the monomer.
get_orphan: Create a copy with parent removed but position and direction preserved.

reverse()[source]

Reverse the orientation of this DNA part.

Flips the direction of the part between ‘forward’ and ‘reverse’.

Returns:

DNA_part: Returns self after reversing direction.

Notes

This method is typically called when a containing construct is reversed, ensuring all parts maintain proper relative orientation.

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_dir(direction)[source]

Set the direction of the monomer and return self.

Convenience method for setting direction in a fluent interface style.

Parameters:

directionstr, int, or None: The direction to assign to this monomer.

Returns:

OrderedMonomer: Returns self for method chaining.

Examples

>>> monomer = bcp.OrderedMonomer().set_dir('forward')
>>> monomer.direction
'forward'

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.

subhash()[source]

Compute hash contribution from monomer properties.

Computes a hash value based on the monomer’s position, direction, and name (if present), excluding the parent reference.

Returns:

int: Hash value based on monomer-specific properties.

Notes

This method is used by __hash__ to compute the monomer’s hash contribution. It excludes the parent to avoid circular dependencies in hash computation.

unclone()[source]

Remove this part from its parent construct.

Detaches the part from any parent construct or assembly, resetting its position and parent references.

Returns:

DNA_part: Returns self after removal from parent.

See also

clone: Attach the part to a construct at a specific position.

Notes

This method calls the remove method from the OrderedMonomer base class to detach the part from its parent polymer structure.

After calling this method, the part becomes “orphaned” and can be attached to a different construct using clone.

update_component(internal_species=None, **kwargs)[source]

Create a copy of the RBS with updated transcript reference.

Used for component enumeration when RBS is part of larger constructs that need to be duplicated with different species.

Parameters:

internal_speciesSpecies, optional: The new transcript species to use for this RBS copy.
**kwargs: Additional keyword arguments (currently unused).

Returns:

RBS or None: A shallow copy of this RBS with the updated transcript attribute if parent is RNA and direction is ‘forward’. Returns None otherwise.

Raises:

AttributeError: If direction attribute has an unknown value.

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 the ‘translation’ mechanism to generate translation reactions.

Uses the ‘translation’ mechanism to generate reactions for ribosome binding to the transcript and protein production.

Returns:

list of Reaction: List of translation reactions including ribosome binding and protein synthesis. Returns empty list if protein is None.

update_species()[source]

Use the ‘translation’ mechanism to generate translation species.

Uses the ‘translation’ mechanism to generate species for ribosome binding and protein production from the RNA transcript.

Returns:

list of Species: List of species generated by the translation mechanism, including ribosome-RNA complexes and protein products.