biocrnpyler.components.MembraneSensor

class biocrnpyler.components.MembraneSensor(membrane_sensor_protein: Species | str | Component, response_protein: Species | str | Component, assigned_substrate: Species | str | Component, signal_substrate: Species | str | Component, product: Species | str | Component = None, internal_compartment: str | Compartment = 'Internal', external_compartment: str | Compartment = 'External', ATP: int = 2, attributes=None, **kwargs)

Bases: Component

Two-component system (TCS) membrane sensor protein.

A MembraneSensor component represents a membrane sensor protein in a two-component signaling system. The sensor detects external signal substrates and catalyzes the transfer of a chemical group (typically phosphate) to a response protein, activating it. The component uses a ‘membrane_sensor’ mechanism to generate signal transduction reactions.

Parameters:

• membrane_sensor_protein (Species, str, or Component) – The membrane sensor protein (histidine kinase) that detects the signal. Can be a Species object, string name, or Component.

• response_protein (Species, str, or Component) – The cytoplasmic response regulator protein that receives the signal. Can be a Species object, string name, or Component.

• assigned_substrate (Species, str, or Component) – The chemical group to be transferred (typically phosphate). Can be a Species object, string name, or Component.

• signal_substrate (Species, str, or Component) – The external signal molecule that activates the sensor. Can be a Species object, string name, or Component.

• product (Species, str, or Component, optional) – The activated response protein product. If None, automatically named as ‘<response_protein>active’.

• internal_compartment (str or Compartment, default 'Internal') – The internal compartment containing response protein. Can be a string name (creates new Compartment) or an existing Compartment object.

• external_compartment (str or Compartment, default 'External') – The external compartment containing signal. Can be a string name (creates new Compartment) or an existing Compartment object.

• ATP (int, default 2) – Number of ATP molecules required for the signaling process.

• attributes (list of str, optional) – List of attribute tags to associate with species.

• **kwargs – Additional keyword arguments passed to the Component base class constructor.

Attributes:

• membrane_sensor_protein (Species) – The membrane sensor protein species.

• response_protein (Species) – The response regulator protein species.

• assigned_substrate (Species) – The substrate to be transferred (e.g., phosphate).

• signal_substrate (Species) – The external signal molecule species.

• product (Species) – The activated response protein species.

• energy (Species) – ATP species used for energy.

• waste (Species) – ADP species produced.

See also

Component

Base class for biomolecular components.

Notes

Two-component systems (TCS) are common bacterial signal transduction pathways. The typical mechanism involves:

1. Signal detection by membrane sensor (histidine kinase)

2. Autophosphorylation of sensor using ATP

3. Phosphotransfer to response regulator

4. Activated response regulator regulates gene expression

The general reaction scheme:

\[\begin{split} & {\text{signal}} + {\text{sensor}} + {\text{ATP}} + {\text{response_protein}} \\ & \qquad \rightarrow {\text{signal}} + {\text{sensor}} + {\text{ADP}} + {\text{response_protein-P}} \end{split}\]

The component name is automatically generated as: ‘<membrane_sensor_protein_name>_<compartment_name>’

Examples

Create a simple two-component system:

>>> tcs = bcp.MembraneSensor(
...     membrane_sensor_protein='EnvZ',
...     response_protein='OmpR',
...     assigned_substrate='Phosphate',
...     signal_substrate='Osmolarity',
...     ATP=2
... )

Create a chemotaxis receptor:

>>> chemoreceptor = bcp.MembraneSensor(
...     membrane_sensor_protein='CheA',
...     response_protein='CheY',
...     assigned_substrate='Phosphate',
...     signal_substrate='Aspartate',
...     product='CheY_P'
... )

Use with a mixture:

>>> mixture = bcp.Mixture(
...     components=[tcs],
...     mechanisms={
...         'membrane_sensor': bcp.Membrane_Signaling_Pathway_MM()},
...     parameter_file='mechanisms/transport_parameters.tsv'
... )
>>> crn = mixture.compile_crn()

Methods

add_attribute	Add a single attribute to the component.
add_mechanism	Add a mechanism to this component's mechanism dictionary.
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 membrane sensor protein species.
set_attributes	Set multiple attributes for the component.
set_mixture	Set the mixture containing this component.
set_species	Convert various inputs into Species objects.
update_parameters	Update the parameter database with new parameters.
update_reactions	Use 'membrane_sensor' to generate species signaling reactions.
update_species	Use 'membrane_sensor' to generate species signaling species.

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=None, overwrite=False, optional_mechanism=False)

Add a mechanism to this component’s mechanism dictionary.

Parameters:

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

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

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

Raises:

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

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

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 membrane sensor protein species.

Returns:

The membrane sensor protein (histidine kinase) species.

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

Set the mixture containing this component.

Parameters:

mixture (Mixture or None) – The mixture object that contains this component and provides default mechanisms and parameters.

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_parameters(parameter_file=None, parameters=None, parameter_database=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).

• parameter_database (ParameterDatabase, optional) – Another parameter database to merge into component’s database.

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

update_reactions()

Use ‘membrane_sensor’ to generate species signaling reactions.

Uses the ‘membrane_sensor’ mechanism to generate reactions for signal detection, ATP-dependent phosphorylation, and phosphotransfer to the response regulator.

Returns:

List of signal transduction reactions including sensing, autophosphorylation, and phosphotransfer.

Return type:

list of Reaction

update_species()

Use ‘membrane_sensor’ to generate species signaling species.

Uses the ‘membrane_sensor’ mechanism to generate all species involved in the signaling pathway including sensor, response protein, substrates, signal, product, ATP, and ADP.

Returns:

List of species generated by the membrane_sensor mechanism.

Return type:

list of Species