biocrnpyler.mechanisms.Two_Step_Cooperative_Binding

class biocrnpyler.mechanisms.Two_Step_Cooperative_Binding(name='two_step_cooperative_binding', mechanism_type='cooperative_binding')[source]

Bases: Mechanism

Sequential cooperative binding mechanism with oligomerization.

A ‘binding’ mechanism where multiple binder molecules first oligomerize, then the oligomer binds to the bindee in a two-step process. This models cooperative binding where ligands must first form a multimeric complex before binding to their target.

The binding process follows two sequential reactions:

  1. \(n A \rightleftharpoons A_n\) (oligomerization)

  2. \(A_n + B \rightleftharpoons A_n\mathord{:}B\) (binding)

where \(n\) is the cooperativity.

Parameters:

  • name (str, default 'two_step_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-step cooperative binding.

Combinatorial_Cooperative_Binding

Multiple distinct binders.

Mechanism

Base class for all mechanisms.

Notes

This mechanism models cooperative binding as a two-step process:

  1. Oligomerization: Binder molecules first associate to form an oligomer (dimer, trimer, etc.)

  2. Binding: The oligomer then binds to the target

This is useful for modeling:

  • Protein dimerization followed by DNA binding

  • Receptor oligomerization before ligand binding

  • Sequential assembly and binding processes

Required parameters for this mechanism:

  • ‘kb1’ : Forward rate constant for oligomerization

  • ‘ku1’ : Reverse rate constant for oligomerization

  • ‘kb2’ : Forward rate constant for oligomer-bindee binding

  • ‘ku2’ : Reverse rate constant for oligomer-bindee binding

  • ‘cooperativity’ : Number of binder molecules in the oligomer

Examples

Model transcription factor dimerization followed by DNA binding:

>>> mech = bcp.Two_Step_Cooperative_Binding()
>>> # TF dimerizes (2*TF <-> TF2), then binds DNA (TF2 + DNA <-> TF2:DNA)
>>> params = {
...     'cooperativity': 2,
...     'kb1': 0.1, 'ku1': 0.01,  # Dimerization rates
...     'kb2': 1.0, 'ku2': 0.001   # DNA binding rates
... }

Model trimeric receptor assembly and activation:

>>> mech = bcp.Two_Step_Cooperative_Binding()
>>> params = {
...     'cooperativity': 3,  # Trimeric receptor
...     'kb1': 0.05, 'ku1': 0.1,   # Trimerization
...     'kb2': 10.0, 'ku2': 0.01   # Ligand binding
... }

Methods

update_reactions

Generate reactions for two-step cooperative binding.

update_species

Generate species for two-step cooperative binding.
update_reactions(binder, bindee, kb=None, ku=None, component=None, part_id=None, cooperativity=None, complex_species=None, n_mer_species=None, **kwargs)[source]

Generate reactions for two-step cooperative binding.

Creates two sequential reactions: oligomerization of binders followed by oligomer binding to the bindee.

Parameters:

  • binder (Species) – The ligand species that oligomerizes then binds.

  • bindee (Species) – The target species that the oligomer binds to.

  • kb (list of float or Parameter, optional) – Forward rate constants [kb1, kb2] for oligomerization and binding. If None, retrieved from component parameters.

  • ku (list of float or Parameter, optional) – Reverse rate constants [ku1, ku2] for oligomerization and binding. If None, retrieved from component parameters.

  • component (Component, optional) – Component containing parameter values. Required if kb, ku, or cooperativity are not provided.

  • part_id (str, optional) – Identifier for parameter lookup. If None, defaults to ‘repr(binder)-repr(bindee)’.

  • cooperativity (int or float, optional) – Number of binders in the oligomer. If None, retrieved from component parameters.

  • complex_species (Species, optional) – Pre-specified final complex species.

  • n_mer_species (Species, optional) – Pre-specified oligomer species.

  • **kwargs – Additional keyword arguments passed to update_species.

Returns:

List containing two reactions:

  1. Oligomerization: cooperativity*binder \(\rightleftharpoons\) n_mer

  2. Binding: n_mer + bindee \(\rightleftharpoons\) complex

Return type:

list of Reaction

Raises:

ValueError – If component is None and kb, ku, or cooperativity is not provided, or if kb and ku do not contain exactly 2 values each.

Notes

The two-step process uses separate rate constants:

  • ‘kb1’, ‘ku1’: Control oligomerization kinetics

  • ‘kb2’, ‘ku2’: Control oligomer-bindee binding kinetics

This separation allows modeling of processes where oligomerization and binding have different kinetic properties.

update_species(binder, bindee, component=None, complex_species=None, n_mer_species=None, cooperativity=None, part_id=None, **kwargs)[source]

Generate species for two-step cooperative binding.

Creates the species involved in sequential cooperative binding: binder, bindee, oligomer (n-mer), and final complex.

Parameters:

  • binder (Species) – The ligand species that oligomerizes then binds.

  • bindee (Species) – The target species that the oligomer binds to.

  • component (Component, optional) – Component containing parameter values. Required if cooperativity is not provided directly.

  • complex_species (Species, optional) – Pre-specified final complex species. If None, automatically creates a Complex containing the n-mer and bindee.

  • n_mer_species (Species, optional) – Pre-specified oligomer species. If None, automatically creates a Complex containing \(n\) binders.

  • cooperativity (int or float, optional) – Number of binders in the oligomer. If None, retrieved from component parameters.

  • part_id (str, optional) – Identifier for parameter lookup. If None, defaults to ‘repr(binder)-repr(bindee)’.

  • **kwargs – Additional keyword arguments (unused).

Returns:

List containing [binder, bindee, complex, n_mer] where n_mer is the oligomer and complex is the final bound product.

Return type:

list of Species

Raises:

  • ValueError – If neither component nor cooperativity is provided.

  • TypeError – If n_mer_species or complex_species is not a Species or None.

Notes

The n_mer represents the oligomerized form of the binder (e.g., a dimer for cooperativity=2). The complex represents the n_mer bound to the bindee.