biocrnpyler.components.dna.DNAassembly

class biocrnpyler.components.dna.DNAassembly(name: str, dna=None, promoter=None, transcript=None, rbs=None, protein=None, length=None, attributes=None, mechanisms=None, compartment=None, parameters=None, initial_concentration=None, **kwargs)

Bases: DNA

High-level representation of a gene expression construct.

A DNAassembly represents a complete gene expression unit combining a promoter region, ribosome binding site (RBS), coding sequence, and the RNA and protein products. This class provides a convenient interface for modeling the central dogma pathway: DNA \(\rightarrow\) RNA \(\rightarrow\) Protein, where the promoter controls transcription and the RBS controls translation.

Parameters:

• name (str) – Name of the DNA assembly.

• dna (DNA, str, or None, optional) – The DNA species or name for the assembly. If None, a DNA species with name is created automatically.

• promoter (Promoter, str, or None, optional) – The promoter component or name controlling transcription. If None, no transcription occurs. If a string, a default Promoter is created.

• transcript (RNA, str, bool, or None, optional) – The RNA transcript produced by transcription. If None, an RNA species with name is created. If False, no transcript is created (used in expression mixtures for direct translation).

• rbs (RBS, str, or None, optional) – The ribosome binding site component or name controlling translation. If None, no translation occurs. If a string, a default RBS is created.

• protein (Protein, str, or None, optional) – The protein product of translation. If None, a Protein species with name is created automatically.

• length (int, optional) – Length of the DNA sequence in base pairs.

• attributes (list of str, optional) – List of attribute tags for the assembly and its species.

• mechanisms (dict or list, optional) – Custom mechanisms for this assembly, overriding mixture defaults.

• compartment (Compartment, optional) – The compartment containing this assembly and its products.

• parameters (dict, optional) – Parameter values specific to this assembly.

• initial_concentration (float, optional) – Initial concentration of the DNA species.

• **kwargs – Additional keyword arguments passed to the parent DNA class.

Attributes:

• dna (Species) – The DNA species representing the genetic construct.

• promoter (Promoter or None) – The promoter component controlling transcription.

• rbs (RBS or None) – The ribosome binding site controlling translation.

• transcript (Species or None) – The RNA transcript produced by transcription.

• protein (Species or None) – The protein product of translation.

See also

DNA

Base class for DNA components.

Promoter

Component representing transcriptional control elements.

RBS

Component representing ribosome binding sites.

RNA

Base class for RNA components.

Protein

Base class for protein components.

Notes

The DNAassembly automatically coordinates its sub-components (promoter, RBS) by propagating updates to mechanisms, parameters, and mixtures. When mechanisms or parameters are added to the assembly, they are also added to the promoter and RBS (but never overwrite existing values in those components).

The ‘transcription’ mechanism is used by the promoter to generate the species and reactions for transcript and the ‘translation’ mechanism is used by the RBS to generate the species and reactions for ribosome binding and protein production.

For expression mixtures where transcription is bypassed, set transcript=False to enable direct translation from DNA to protein. In this case, the ‘transcription’ mechanism will be used to generate the protein.

Examples

Create a simple constitutive gene expression construct:

>>> # Basic assembly with automatic species creation
>>> gene = bcp.DNAassembly(
...     name='gene_gfp',
...     promoter='pconst',
...     rbs='rbs1'
... )
>>> gene.dna
dna_gene_gfp
>>> gene.transcript
rna_gene_gfp
>>> gene.protein
protein_gene_gfp

Create an assembly with custom species names:

>>> gene = bcp.DNAassembly(
...     name='gene_reporter',
...     promoter='p_lac',
...     rbs='rbs_strong',
...     transcript='mRNA_gfp',
...     protein='protein_gfp'
... )

Create an expression construct (no transcript):

>>> gene = bcp.DNAassembly(
...     name='gene_direct',
...     promoter='p_const',
...     transcript=False,
...     protein='protein_x'
... )

Methods

add_attribute	Add a single attribute to the component.
add_mechanism	Add a mechanism to the assembly and its sub-components.
add_mechanisms	Add multiple mechanisms to this component.
enumerate_components	Enumerate derived components created from this component.
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 primary DNA species of this assembly.
set_attributes	Set multiple attributes for the component.
set_mixture	Set the mixture containing this component and its sub-components.
set_species	Convert various inputs into Species objects.
update_dna	Set or update the DNA species for this assembly.
update_parameters	Update parameters for the assembly and its sub-components.
update_promoter	Set or update the promoter component for this assembly.
update_protein	Set or update the protein product for this assembly.
update_rbs	Set or update the ribosome binding site component.
update_reactions	Generate all reactions associated with this assembly.
update_species	Generate all species associated with this assembly.
update_transcript	Set or update the RNA transcript for this assembly.

add_attribute(attribute: str)

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: str = None, overwrite: bool = False, optional_mechanism: bool = False) → None

Add a mechanism to the assembly and its sub-components.

Adds the mechanism to the assembly’s mechanism dictionary and propagates it to the promoter and RBS components without overwriting their existing mechanisms.

Parameters:

• mechanism (Mechanism) – The mechanism object to add.

• mech_type (str, optional) – The mechanism type key. If None, uses the mechanism’s mechanism_type attribute.

• overwrite (bool, default False) – If True, overwrites existing mechanisms with the same type in the assembly. If False, raises ValueError for duplicate types.

• optional_mechanism (bool, default False) – If True, suppresses ValueError when a mechanism key conflict occurs in the assembly and overwrite is False.

Notes

The mechanism is always added to the promoter and RBS with optional_mechanism=True, meaning it will never overwrite existing mechanisms in those components even if overwrite=True.

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

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

enumerate_components(previously_enumerated=None) → List

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.

get_mechanism(mechanism_type, optional_mechanism=False)

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

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:

1. Component.parameter_database

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

get_species()

Get the primary DNA species of this assembly.

Returns:

The DNA species representing this genetic construct.

Return type:

Species

set_attributes(attributes: List[str])

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: Mixture) → None

Set the mixture containing this component and its sub-components.

Also propagates the mixture reference to the promoter and RBS components if they exist.

Parameters:

mixture (Mixture) – The mixture object that contains this assembly.

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

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_dna(dna: None | DNA | str, attributes=None) → None

Set or update the DNA species for this assembly.

Creates a DNA species from the provided input and updates the DNA references in the promoter and RBS components if they exist.

Parameters:

• dna (DNA, str, or None) – The DNA component, species name, or None. If None, creates a DNA species using the assembly’s name. If a string, creates a new DNA species with that name. If a DNA object, uses it directly.

• attributes (list of str, optional) – Attribute tags to add to the DNA species.

Notes

This method automatically updates the dna attribute of the promoter and RBS components to maintain consistency across the assembly.

update_parameters(parameter_file: str = None, parameters: ParameterDatabase = None, overwrite_parameters: bool = True) → None

Update parameters for the assembly and its sub-components.

Propagates parameter updates to the DNA assembly itself and to the promoter and RBS components if they exist.

Parameters:

• parameter_file (str, optional) – Path to a CSV or TSV parameter file to load.

• parameters (ParameterDatabase, optional) – ParameterDatabase object to merge with the assembly’s parameters.

• overwrite_parameters (bool, default True) – If True, new parameter values overwrite existing ones. If False, existing parameters are preserved.

Notes

This method calls update_parameters on:

1. The parent DNA class (updating the DNA’s parameters)

2. The promoter component (if it exists)

3. The RBS component (if it exists)

update_promoter(promoter: Protein | str, transcript: RNA = None, protein: Protein = None) → None

Set or update the promoter component for this assembly.

Creates a Promoter component from the provided input and propagates the assembly’s parameters, mixture, and mechanisms to the promoter.

Parameters:

• promoter (Promoter, str, or None) – The Promoter component, promoter name, or None. If None, no promoter is created. If a string, creates a default Promoter with that name using Promoter.from_promoter. If a Promoter object, uses it directly.

• transcript (RNA, optional) – The RNA transcript to associate with the promoter. If provided, updates the assembly’s transcript before creating the promoter.

• protein (Protein, optional) – The protein product to associate with the promoter (used for some regulatory mechanisms).

Notes

This method automatically:

• Propagates the assembly’s parameter database to the promoter

• Sets the promoter’s mixture reference

• Adds the assembly’s mechanisms to the promoter (without overwriting existing promoter mechanisms)

update_protein(protein: None | Protein | str, attributes=None) → None

Set or update the protein product for this assembly.

Creates a Protein species from the provided input and updates the protein references in the promoter and RBS components if they exist.

Parameters:

• protein (Protein, str, or None) – The Protein component, species name, or None. If None, creates a Protein species using the assembly’s name. If a string, creates a new Protein species with that name. If a Protein object, uses it directly.

• attributes (list of str, optional) – Attribute tags to add to the Protein species.

Notes

This method automatically updates the protein attribute of the promoter and RBS components to maintain consistency across the assembly.

update_rbs(rbs: RBS | str, transcript: RNA = None, protein: Protein = None) → None

Set or update the ribosome binding site component.

Creates an RBS component from the provided input and propagates the assembly’s parameters, mixture, and mechanisms to the RBS.

Parameters:

• rbs (RBS, str, or None) – The RBS component, RBS name, or None. If None, no RBS is created. If a string, creates a default RBS with that name using RBS.from_rbs. If an RBS object, uses it directly.

• transcript (RNA, optional) – The RNA transcript containing the RBS. If provided, updates the assembly’s transcript before creating the RBS.

• protein (Protein, optional) – The protein product of translation. If provided, updates the assembly’s protein before creating the RBS.

Notes

This method automatically:

• Propagates the assembly’s parameter database to the RBS

• Sets the RBS’s mixture reference

• Adds the assembly’s mechanisms to the RBS (without overwriting existing RBS mechanisms)

update_reactions() → List[Reaction]

Generate all reactions associated with this assembly.

Collects reactions from the promoter and RBS components during CRN compilation.

Returns:

List of all reactions generated by the promoter and RBS components, including transcription, translation, and regulatory reactions.

Return type:

list of Reaction

Notes

This method is called during CRN compilation by Mixture.compile_crn to collect all chemical reactions generated by this assembly.

update_species() → List[Species]

Generate all species associated with this assembly.

Collects species from the DNA, promoter, and RBS components during CRN compilation.

Returns:

List containing the DNA species and all species generated by the promoter and RBS components.

Return type:

list of Species

Notes

This method is called during CRN compilation by Mixture.compile_crn to collect all chemical species generated by this assembly.

update_transcript(transcript: None | RNA | str | bool, attributes=None) → None

Set or update the RNA transcript for this assembly.

Creates an RNA species from the provided input and updates the transcript references in the promoter and RBS components if they exist.

Parameters:

• transcript (RNA, str, bool, or None) – The RNA component, species name, False, or None. If None, creates an RNA species using the assembly’s name. If a string, creates a new RNA species with that name. If an RNA object, uses it directly. If False, sets transcript to None (used for expression mixtures without transcription).

• attributes (list of str, optional) – Attribute tags to add to the RNA species.

Notes

Setting transcript=False is used in expression mixtures where translation occurs directly from DNA without an explicit RNA intermediate.

This method automatically updates the transcript attribute of the promoter and RBS components to maintain consistency.