biocrnpyler.mechanisms.Combinatorial_Cooperative_Binding

class biocrnpyler.mechanisms.Combinatorial_Cooperative_Binding(name='Combinatorial_Cooperative_binding', mechanism_type='cooperative_binding')[source]

Bases: Mechanism

Combinatorial binding mechanism for multiple distinct ligands.

A ‘binding’ mechanism where different types of binder molecules can bind to a bindee in various combinations, each with its own cooperativity. This models complex regulatory scenarios where multiple transcription factors or ligands can bind to the same target in different combinations, each producing a distinct complex.

The mechanism generates all possible binding combinations and the reactions between them, considering individual binding affinities and cooperativities for each binder type.

Parameters:

name (str, default 'Combinatorial_Cooperative_binding') – Name identifier for this mechanism instance.
mechanism_type (str, default 'cooperative_binding') – Type classification of this mechanism.

Attributes:

name (str) – Name of the mechanism instance.
mechanism_type (str) – Type classification (‘cooperative_binding’).

See also

One_Step_Cooperative_Binding: Single binder type cooperative binding.
CombinatorialPromoter: Component that uses this mechanism.
Mechanism: Base class for all mechanisms.

Notes

This mechanism is designed for modeling complex regulatory logic where:

Multiple different regulators can bind to the same target
Each regulator can have its own cooperativity (e.g., some bind as dimers, others as monomers)
All possible combinations of bound states are generated
Each transition between states has specific rate constants

The mechanism generates a complete reaction network connecting all possible bound states. For \(n\) different binders, this creates \(2^n - 1\) different complexes (excluding the unbound state).

Required parameters for this mechanism (per binder):

‘kb’: Forward binding rate
‘ku’: Reverse unbinding rate
‘cooperativity’: Number of molecules binding together

This is commonly used for:

Complex promoter regulation with multiple transcription factors
Multi-ligand receptor systems
Combinatorial protein complex assembly

Examples

Model a promoter with two different transcription factors:

>>> A, B = bcp.Species('A'), bcp.Species('B')
>>> AND_promoter = bcp.CombinatorialPromoter(
...     'AND_promoter', [A, B], tx_capable_list=[[A, B]], leak=False)
... AND_assembly = bcp.DNAassembly(
...     'AND', promoter=AND_promoter, rbs='medium', protein='GFP')
... mixture = bcp.ExpressionExtract(
...     name='AND_mixture', components=[AND_assembly],
...     parameter_file=[
...         'mechanisms/binding_parameters.tsv',
...         'mixtures/extract_parameters.tsv',
...     ]
... )
... crn = mixture.compile_crn()

Methods

`make_cooperative_complex`	Create a complex with multiple cooperative binders.
`update_reactions`	Generate reactions for all combinatorial binding transitions.
`update_species`	Generate all species for combinatorial binding.

make_cooperative_complex(combo, bindee, cooperativity)[source]

Create a complex with multiple cooperative binders.

Constructs a complex species containing the specified combination of binders (each repeated according to its cooperativity) bound to the bindee.

Parameters:

combo (tuple or list of Species) – Combination of binder species to include in the complex.
bindee (Species) – The target species being bound to.
cooperativity (dict) – Dictionary mapping binder names (str) to their cooperativity values (int). Determines how many copies of each binder are included.

Returns:

If only bindee is present (empty combo), returns bindee alone. Otherwise returns a Complex containing all binders (repeated per cooperativity) and the bindee.

Return type:

Species or Complex

Notes

For each binder in combo, the method adds cooperativity[binder.name] copies to the complex. For example, if binder A has cooperativity 2 and binder B has cooperativity 1, the complex for combo=[A, B] would contain [A, A, B, bindee].

update_reactions(binders, bindee, component=None, kbs=None, kus=None, part_id=None, cooperativity=None, **kwargs)[source]

Generate reactions for all combinatorial binding transitions.

Creates reactions connecting all possible binding states, where each reaction represents one binder type associating or dissociating while other binders remain bound.

Parameters:

binders (list of Species) – List of different binder species that can bind in combinations.
bindee (Species) – The target species being bound to.
component (Component, optional) – Component containing parameter values. Required if rate constants or cooperativities are not provided.
kbs (dict, optional) – Dictionary mapping binder names to forward rate constants (kb). If None for any binder, retrieved from component parameters.
kus (dict, optional) – Dictionary mapping binder names to reverse rate constants (ku). If None for any binder, retrieved from component parameters.
part_id (str, optional) – Base identifier for parameter lookup. Individual binder parameters are looked up as ‘part_id_bindername’.
cooperativity (dict, optional) – Dictionary mapping binder names to cooperativity values. If None for any binder, retrieved from component parameters.
**kwargs – Additional keyword arguments (unused).

Returns:

List of all reactions connecting binding states. Each reaction represents adding or removing one binder type to/from an existing complex.

Return type:

list of Reaction

Raises:

ValueError – If component is None and any required parameters (kb, ku, cooperativity) are not provided.

Notes

The reaction network connects all possible binding states such that:

Each reaction adds or removes exactly one binder type
Rate constants are specific to each binder
Cooperativity determines the stoichiometry of each binder

For \(n\) binders, this generates approximately \(n 2^(n-1)\) reactions, connecting the \(2^n\) possible states (including unbound).

Each binder requires three parameters:

‘kb’: Forward binding rate constant
‘ku’: Reverse unbinding rate constant
‘cooperativity’: Stoichiometry of that binder

The algorithm avoids generating duplicate reactions by tracking which transitions have been created.

update_species(binders, bindee, cooperativity=None, component=None, part_id=None, **kwargs)[source]

Generate all species for combinatorial binding.

Creates all possible complexes from combinations of binders bound to the bindee, considering each binder’s cooperativity.

Parameters:

binders (list of Species) – List of different binder species that can bind in combinations.
bindee (Species) – The target species being bound to.
cooperativity (dict, optional) – Dictionary mapping binder names to cooperativity values. If None for any binder, retrieved from component parameters.
component (Component, optional) – Component containing parameter values. Required if cooperativity values are not provided.
part_id (str, optional) – Base identifier for parameter lookup. Individual binder parameters are looked up as ‘part_id_bindername’.
**kwargs – Additional keyword arguments (unused).

Returns:

List of all possible complexes from binding combinations. For n binders, returns \(2^n - 1\) complexes (all combinations except unbound bindee).

Return type:

list of Species

Raises:

ValueError – If component is None and cooperativity is not provided for all binders.

Notes

This method generates all possible combinations of binders: - Single binders: A:bindee, B:bindee, etc. - Pairs: A:B:bindee, A:C:bindee, etc. - Higher combinations up to all binders bound simultaneously

Each complex respects the individual cooperativity of its binders.