biocrnpyler.mixtures.ExpressionExtract

class biocrnpyler.mixtures.ExpressionExtract(name='', **kwargs)

Bases: Mixture

Gene expression extract without explicit TX-TL machinery.

A simplified mixture that models gene expression as a single direct reaction from DNA to protein, without explicitly representing transcription and translation as separate processes. This extract lumps transcription and translation into a single ‘expression’ reaction, eliminating intermediate mRNA species and cellular machinery (ribosomes, polymerases, etc.).

This extract is appropriate for coarse-grained models where mRNA dynamics are negligible and computational efficiency is prioritized over mechanistic detail.

Parameters:

• name (str, default '') – Name of the mixture for identification and parameter lookup.

• mechanisms (dict, list, or Mechanism, optional) – Default mechanisms for components in this mixture. Can be a dict with mechanism types (str) as keys and mechanism objects as values, a list of mechanism objects, or a single Mechanism.

• components (list of Component or Component, optional) – Components to include in the mixture. Components are deep-copied when added to prevent modification of original objects.

• parameters (dict, optional) – Dictionary of parameter values. Keys follow the format (mechanism, part_id, param_name).

• compartment (Compartment, optional) – Default compartment for all components and species in this mixture.

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

• overwrite_parameters (bool, default False) – If True, parameters from file/dict overwrite existing parameters. If False, existing parameters are preserved.

• global_mechanisms (dict, list, or GlobalMechanism, optional) – Global mechanisms that apply to all species after component compilation (e.g., dilution, global degradation). Can be a dict, list, or single GlobalMechanism.

• species (list of Species or Species, optional) – Additional species to add directly to the CRN without going through component compilation.

• initial_condition_dictionary (dict, optional) – Dictionary mapping species to initial concentration values. Deprecated in favor of using parameters with mechanism=’initial concentration’.

• global_component_enumerators (list, optional) – List of global component enumerators for advanced component generation patterns (e.g., creating all pairwise interactions).

• global_recursion_depth (int, default 4) – Maximum recursion depth for global component enumeration during compilation.

• local_recursion_depth (int, optional) – Maximum recursion depth for local component enumeration. If None, defaults to global_recursion_depth + 2.

Attributes:

• name (str) – Name of the mixture.

• compartment (Compartment or None) – Default compartment for the mixture.

• components (list of Component) – List of components in the mixture (deep copies of added components).

• mechanisms (dict) – Dictionary of default mechanisms, keyed by mechanism type (str).

• global_mechanisms (dict) – Dictionary of global mechanisms, keyed by mechanism type (str).

• parameter_database (ParameterDatabase) – Database storing all parameters for this mixture.

• added_species (list of Species) – List of species added directly to the mixture.

• global_component_enumerators (list) – List of global component enumerators.

• global_recursion_depth (int) – Recursion depth for global component enumeration.

• local_recursion_depth (int) – Recursion depth for local component enumeration.

• crn (ChemicalReactionNetwork or None) – The compiled CRN, created by calling compile_crn.

See also

SimpleTxTlExtract

TX-TL with separate transcription and translation.

TxTlExtract

TX-TL with explicit machinery.

OneStepGeneExpression

Mechanism used for expression.

Mixture

Base class for all mixtures.

Notes

Default mechanisms included:

• ‘transcription’ : OneStepGeneExpression - Single-step gene expression (DNA \(\rightarrow\) DNA + Protein) without intermediate mRNA

• ‘translation’ : EmptyMechanism - Dummy mechanism that generates no reactions (translation is disabled)

• ‘catalysis’ : BasicCatalysis - Simple catalytic reactions without explicit enzyme binding

• ‘binding’ : One_Step_Binding - Simple multi-species binding

Key features of this extract:

• No explicit transcription or translation steps

• No cellular machinery (RNAP, ribosomes, RNases)

• No intermediate mRNA species

• Simplified parameter space (single ‘kexpress’ rate)

• Fast compilation and simulation

When compiled, this extract automatically disables transcript generation in DNA assemblies that produce proteins, routing expression directly from DNA to protein.

Common applications include:

• High-level gene circuit modeling

• Steady-state or quasi-steady-state analyses

• Rapid prototyping of genetic designs

• Models where mRNA dynamics are negligible

Examples

Create an expression mixture for GFP production:

>>> gfp_gene = bcp.DNAassembly(
...     name='gfp_construct',
...     promoter='pconst',
...     protein='GFP'
... )
>>> mixture = bcp.ExpressionExtract(
...     name='expression_mixture',
...     components=[gfp_gene],
...     parameter_file='mixtures/extract_parameters.tsv'
... )
>>> crn = mixture.compile_crn()

Methods

add_component	Add a single component to the mixture.
add_components	Add multiple components to the mixture.
add_global_mechanism	Add a global mechanism to the mixture.
add_mechanism	Add a mechanism to the mixture's mechanism dictionary.
add_mechanisms	Add multiple mechanisms to the mixture.
add_species	Add species directly to the mixture without component compilation.
add_species_to_crn	Add species to the CRN with initial concentrations.
apply_global_mechanisms	Apply all global mechanisms to a set of species.
compile_crn	Compile CRN with transcript generation disabled in gene expression.
component_enumeration	Recursively enumerate components to generate derived components.
get_component	Retrieve components from the mixture by various criteria.
get_initial_concentration	Determine initial concentrations using parameter hierarchy.
get_mechanism	Retrieve a mechanism by type from the mixture.
get_parameter	Retrieve a parameter from the mixture's parameter database.
global_component_enumeration	Apply global component enumerators to generate new components.
set_species	Convert various inputs into Species objects.
update_parameters	Update the parameter database with new parameters.

add_component(component)

Add a single component to the mixture.

Parameters:

component (Component or list of Component) – Component object to add to the mixture. If a list is provided, calls add_components instead. The component is deep-copied before being added.

Raises:

• AssertionError – If the component is not a Component object.

• ValueError – If a component with the same type and name already exists in the mixture.

Notes

Components are deep-copied when added to prevent modification of the original component. The copied component’s mixture attribute is set to this Mixture, and its compartment is set to the mixture’s compartment.

add_components(components: List[Component] | Component)

Add multiple components to the mixture.

Parameters:

components (Component or list of Component) – Component object(s) to add to the mixture. Each component is deep-copied before being added.

Raises:

ValueError – If components is not a Component, list of Components, or if any duplicate components are detected.

See also

add_component

Add a single component to the mixture.

add_global_mechanism(mechanism, mech_type=None, overwrite=False)

Add a global mechanism to the mixture.

Global mechanisms are applied to all species after component compilation, enabling operations like dilution or global degradation.

Parameters:

• mechanism (GlobalMechanism) – The global mechanism object to add. Must be a GlobalMechanism instance.

• 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 global mechanism with the same key. If False, raises ValueError when key already exists.

Raises:

• TypeError – If mechanism is not a GlobalMechanism object, or if mech_type is not a string.

• ValueError – If mechanism key already exists and overwrite is False.

Notes

Global mechanisms are applied during compile_crn after all component reactions have been generated.

add_mechanism(mechanism, mech_type=None, overwrite=False)

Add a mechanism to the mixture’s mechanism dictionary.

Parameters:

• mechanism (Mechanism or GlobalMechanism) – The mechanism object to add. If a GlobalMechanism is provided, it is automatically added to the global mechanisms dictionary.

• 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 mechanisms with the same keys. If False, raises ValueError when keys already exist. If None, ignores mechanisms that already exist.

Raises:

• TypeError – If mechanism is not a Mechanism object, or if mech_type is not a string.

• ValueError – If mechanism key already exists and overwrite is None.

See also

add_global_mechanism

Add a global mechanism specifically.

add_mechanisms(mechanisms, overwrite=False)

Add multiple mechanisms to the mixture.

Accepts mechanisms as a single object, list, or dictionary and adds them to the mixture’s mechanism dictionary. Can handle both regular Mechanism and GlobalMechanism objects.

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. If None, ignores mechanisms that already exist.

Raises:

ValueError – If mechanisms is not a valid type, or if mechanism key conflicts occur with overwrite=False.

See also

add_mechanism

Add a single mechanism to the mixture.

add_species(species: List[Species] | Species)

Add species directly to the mixture without component compilation.

Parameters:

species (Species or list of Species) – Species object(s) to add directly to the mixture. These species will be included in the CRN during compilation.

Raises:

AssertionError – If any element in the list is not a Species object.

Notes

Species added this way bypass component enumeration and are added directly to the CRN during compile_crn.

add_species_to_crn(new_species, component=None, no_initial_concentrations=False, copy_species=True, compartment=None)

Add species to the CRN with initial concentrations.

Helper method that adds species to the CRN and automatically looks up and assigns their initial concentrations.

Parameters:

• new_species (Species or list of Species) – Species to add to the CRN.

• component (Component, optional) – The component that generated these species. Used for component-specific initial concentration lookup.

• no_initial_concentrations (bool, default False) – If True, skips initial concentration lookup and assignment.

• copy_species (bool, default True) – If True, deep-copies species before adding them to the CRN.

• compartment (Compartment, optional) – Compartment to assign to the species. Overrides species’ existing compartments.

Returns:

All species in the CRN after addition (may include pre-existing species).

Return type:

list of Species

Notes

This method tracks which species are newly added and only assigns initial concentrations to those new species, preventing overwriting of previously set initial concentrations.

apply_global_mechanisms(species, compartment=None) → Tuple[List[Species], List[Reaction]]

Apply all global mechanisms to a set of species.

Calls each global mechanism’s update_species_global and update_reactions_global methods, then adds the resulting species and reactions to the CRN.

Parameters:

• species (list of Species) – Species to which global mechanisms should be applied.

• compartment (Compartment, optional) – Compartment for newly generated species and reactions.

Returns:

New species and reactions generated by global mechanisms.

Return type:

tuple of (list of Species, list of Reaction)

Notes

Global mechanisms are typically used for operations that affect all species uniformly, such as dilution, global degradation, or compartment transport.

compile_crn(**kwargs) → ChemicalReactionNetwork

Compile CRN with transcript generation disabled in gene expression.

Overrides the parent compile_crn method to automatically disable transcript generation in DNA assemblies that produce proteins. This ensures that gene expression proceeds directly from DNA to protein without intermediate mRNA species.

Parameters:

**kwargs – Additional keyword arguments passed to the parent Mixture compile_crn method.

Returns:

Compiled chemical reaction network with expression reactions.

Return type:

ChemicalReactionNetwork

Notes

This method automatically modifies DNA assemblies before compilation:

• For assemblies with a protein product, sets transcript to False

• RNA-only assemblies (no protein) are not affected

• Mechanisms receive protein instead of transcript when transcript is disabled

This behavior enables the single-step expression mechanism to route production directly to protein.

See Mixture.compile_crn for a more detailed description of the parent method behavior.

component_enumeration(comps_to_enumerate=None, recursion_depth=10) → List[Component]

Recursively enumerate components to generate derived components.

Calls each component’s enumerate_components method repeatedly to expand high-level components into their constituent parts (e.g., DNA_construct \(\rightarrow\) RNA_construct \(\rightarrow\) Protein).

Parameters:

• comps_to_enumerate (list of Component, optional) – Initial components to enumerate. If None, uses all components in the mixture.

• recursion_depth (int, default 10) – Maximum number of enumeration iterations. Prevents infinite recursion.

Returns:

All components including the original components and all derived components generated through enumeration.

Return type:

list of Component

Warns:

UserWarning – Warns if unenumerated components remain after reaching the recursion depth limit.

get_component(component=None, name=None, index=None)

Retrieve components from the mixture by various criteria.

Exactly one of the three parameters must be provided.

Parameters:

• component (Component, optional) – A component instance to search for. Returns components with matching type and name.

• name (str, optional) – Name of the component to search for. Returns all components with this name.

• index (int, optional) – Index of the component in the mixture’s component list.

Returns:

• Single Component if exactly one match is found or index is used

• List of Components if multiple matches are found

• None if no matches are found

Return type:

Component, list of Component, or None

Raises:

ValueError – If zero or more than one parameter is provided, or if parameters are of incorrect types.

get_initial_concentration(S: List | Species, component=None)

Determine initial concentrations using parameter hierarchy.

Searches for initial concentration parameters for species following a hierarchical lookup strategy, defaulting to 0 if not found.

Parameters:

• S (Species or list of Species) – Species object(s) for which to find initial concentrations. Lists are automatically flattened.

• component (Component, optional) – The component that generated the species. Used for component-specific parameter lookup.

Returns:

Dictionary mapping each Species object to its initial concentration value (float).

Return type:

dict

Raises:

ValueError – If any element in S is not a Species object.

Notes

The parameter lookup hierarchy is:

1. Component’s ParameterDatabase with mechanism='initial concentration', part_id=mixture.name, and parameter names: str(s), s.name, or component.name (where s is the component’s primary species)

2. Mixture’s ParameterDatabase with the same keys

3. Defaults to 0 if not found

get_mechanism(mechanism_type)

Retrieve a mechanism by type from the mixture.

Parameters:

mechanism_type (str) – The type identifier of the mechanism to retrieve (e.g., ‘transcription’, ‘translation’, ‘binding’).

Returns:

The requested mechanism object, or None if not found.

Return type:

Mechanism or None

Raises:

TypeError – If mechanism_type is not a string.

get_parameter(mechanism, part_id, param_name)

Retrieve a parameter from the mixture’s parameter database.

Parameters:

• mechanism (str) – Mechanism identifier for the parameter lookup key.

• part_id (str) – Part identifier for the parameter lookup key.

• param_name (str) – Name of the parameter to retrieve.

Returns:

The parameter object, or None if not found.

Return type:

Parameter or None

global_component_enumeration(comps_to_enumerate=None, recursion_depth=None) → List[Component]

Apply global component enumerators to generate new components.

Global component enumerators create new components based on patterns across all components (e.g., generating all pairwise binding interactions between proteins).

Parameters:

• comps_to_enumerate (list of Component, optional) – Initial components to pass to enumerators. If None, uses all components in the mixture.

• recursion_depth (int, optional) – Maximum number of enumeration iterations. If None, uses self.global_recursion_depth.

Returns:

All components including original and newly generated components from global enumeration.

Return type:

list of Component

Notes

This method is called during compile_crn before local component enumeration. Global enumerators are useful for creating complex interaction networks without manually specifying every interaction.

property global_mechanisms

Stores global mechanisms in the mixture.

Type:

Mechanism

property mechanisms

Stores mixture mechanisms.

Type:

Mechanism

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

Convert various inputs into Species objects.

Parameters:

• species (Species, str, or Component) – The species to convert. Can be a Species object (returned as-is), a string (creates new Species), or a Component (extracts its species).

• material_type (str, optional) – Material type for the species (e.g., ‘dna’, ‘rna’, ‘protein’). 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.

Return type:

Species

Raises:

ValueError – If the input cannot be converted to a valid Species.

update_parameters(parameter_file=None, parameters=None, overwrite_parameters=True)

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

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