biocrnpyler.components.dna.assembly

Classes

DNAassembly(name[, dna, promoter, ...])

High-level representation of a gene expression construct.

class biocrnpyler.components.dna.assembly.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)

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 –> RNA –> Protein, where the promoter controls transcription and the RBS controls translation.

Parameters:

namestr

Name of the DNA assembly.

dnaDNA, str, or None, optional

The DNA species or name for the assembly. If None, a DNA species with name is created automatically.

promoterPromoter, str, or None, optional

The promoter component or name controlling transcription. If None, no transcription occurs. If a string, a default Promoter is created.

transcriptRNA, 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).

rbsRBS, 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.

proteinProtein, str, or None, optional

The protein product of translation. If None, a Protein species with name is created automatically.

lengthint, optional

Length of the DNA sequence in base pairs.

attributeslist of str, optional

List of attribute tags for the assembly and its species.

mechanismsdict or list, optional

Custom mechanisms for this assembly, overriding mixture defaults.

compartmentCompartment, optional

The compartment containing this assembly and its products.

parametersdict, optional

Parameter values specific to this assembly.

initial_concentrationfloat, optional

Initial concentration of the DNA species.

**kwargs

Additional keyword arguments passed to the parent DNA class.

Attributes:

dnaSpecies

The DNA species representing the genetic construct.

promoterPromoter or None

The promoter component controlling transcription.

rbsRBS or None

The ribosome binding site controlling translation.

transcriptSpecies or None

The RNA transcript produced by transcription.

proteinSpecies 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'
... )

__hash__()

Return hash(self).

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:

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: 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:

mechanismMechanism

The mechanism object to add.

mech_typestr, optional

The mechanism type key. If None, uses the mechanism’s mechanism_type attribute.

overwritebool, default=False

If True, overwrites existing mechanisms with the same type in the assembly. If False, raises ValueError for duplicate types.

optional_mechanismbool, 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:

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

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)

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

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()

Get the primary DNA species of this assembly.

Returns:

Species

The DNA species representing this genetic construct.

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:

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: 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:

mixtureMixture

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:

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_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:

dnaDNA, 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.

attributeslist 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_filestr, optional

Path to a CSV or TSV parameter file to load.

parametersParameterDatabase, optional

ParameterDatabase object to merge with the assembly’s parameters.

overwrite_parametersbool, 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:

promoterPromoter, 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.

transcriptRNA, optional

The RNA transcript to associate with the promoter. If provided, updates the assembly’s transcript before creating the promoter.

proteinProtein, 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:

proteinProtein, 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.

attributeslist 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:

rbsRBS, 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.

transcriptRNA, optional

The RNA transcript containing the RBS. If provided, updates the assembly’s transcript before creating the RBS.

proteinProtein, 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 Reaction

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

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 of Species

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

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:

transcriptRNA, 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).

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