biocrnpyler.core.ParameterDatabase

class biocrnpyler.core.ParameterDatabase(parameter_dictionary=None, parameter_file=None, overwrite_parameters=False)[source]

Bases: object

Database for storing and retrieving parameters with defaulting.

A ParameterDatabase stores parameters with flexible lookup keys that enable parameter defaulting based on mechanism, part_id, and parameter name. Parameters can be loaded from dictionaries, files, or other databases.

Parameters:

  • parameter_dictionary (dict, optional) – Dictionary of parameters to load. Keys should be ParameterKey-like (dict, tuple, or str) and values should be numerical or Parameter objects.

  • parameter_file (str or list of str, optional) – Path(s) to parameter file(s) to load. Files must be tab-separated (.tsv, .txt) or comma-separated (.csv).

  • overwrite_parameters (bool, default False) – If True, allows overwriting existing parameters when loading. If False, raises ValueError if duplicate keys are encountered.

Attributes:

parameters (dict) – Internal dictionary mapping ParameterKey to ParameterEntry objects. Access via indexing or iteration rather than directly.

See also

Parameter

Base parameter class.

ParameterEntry

Parameter with database key.

ModelParameter

Parameter with search and found keys.

Notes

When searching for a parameter with find_parameter(mechanism, part_id, param_name), the database searches in this order:

  1. (mechanism.name, part_id, param_name)

  2. (mechanism.type, part_id, param_name)

  3. (None, part_id, param_name)

  4. (mechanism.name, None, param_name)

  5. (mechanism.type, None, param_name)

  6. (None, None, param_name)

This enables flexible parameter specification where specific parameters override more general ones.

Parameter files should have these columns (column names are flexible):

  • ‘param_name’ or ‘parameter_name’ (required)

  • ‘param_val’ or ‘value’ (required)

  • ‘mechanism_id’ or ‘mechanism’ (optional)

  • ‘part_id’ or ‘part’ (optional)

  • ‘units’ or ‘unit’ (optional)

Additional columns are stored in parameter_info.

Parameter files are searched for in the following directories:

  1. The current directory

  2. All directories listed in the ‘BCP_PATH’ environment variable

  3. The BioCRNpyler source code directory

The directories are search in this order and the first parameter file that is found is returned. For files in the BioCRNpyler source code directory, common filename patterns are of the form ‘<type>/<name>_parameters.tsv’ where <type> is ‘components’, ‘mechanisms’, or ‘mixtures’.

Examples

Create a parameter database from a dictionary:

>>> params = {
...     'kb': 100.0,
...     'ku': 0.01,
...     ('transcription', None, 'ktx'): 0.05
... }
>>> db = bcp.ParameterDatabase(parameter_dictionary=params)

Load parameters from a file:

>>> db = bcp.ParameterDatabase(
...     parameter_file='mixtures/pure_parameters.tsv')

Look up a parameter with defaulting:

>>> param = db.find_parameter('transcription', 'promoter1', 'ktx')
>>> param.value
0.05

Add a new parameter:

>>> db.add_parameter('kcat', 10.0,
...     parameter_key={'mechanism': 'catalysis', 'part_id': 'enzyme1'})

Methods

add_parameter

Add a parameter to the database.

find_parameter

Search for a parameter with automatic defaulting.

load_parameters_from_database

Load parameters from another ParameterDatabase.

load_parameters_from_dictionary

Load parameters from a dictionary.

load_parameters_from_file

Load parameters from a file.
__contains__(val)[source]

Check if a key or ParameterEntry is in the database.

Parameters:

val (ParameterEntry, dict, ParameterKey, tuple, or str) – Value to check. Can be a ParameterEntry object or any valid parameter key format.

Returns:

True if the key exists in the database (and ParameterEntry values match if val is a ParameterEntry), False otherwise.

Return type:

bool

__getitem__(key)[source]

Get a parameter by exact key match.

Parameters:

key (dict, ParameterKey, tuple, or str) – Parameter key to look up. No defaulting is performed.

Returns:

The parameter entry with the exact matching key.

Return type:

ParameterEntry

Raises:

KeyError – If the exact key is not found in the database.

__iter__()[source]

Initialize iterator over parameter entries.

Returns:

Self with iterator state initialized.

Return type:

ParameterDatabase

__len__()[source]

Return number of parameters in the database.

Returns:

Number of parameter entries stored.

Return type:

int

__next__()[source]

Get next parameter entry in iteration.

Returns:

Next parameter entry in the database.

Return type:

ParameterEntry

Raises:

StopIteration – When all parameters have been iterated.

__setitem__(parameter_key, value)[source]

Set a parameter value by key.

Parameters:

  • parameter_key (dict, ParameterKey, tuple, or str) – Key for the parameter.

  • value (float, str, or ParameterEntry) – New value or ParameterEntry object. If ParameterEntry, its key must match parameter_key.

Raises:

ValueError – If value is ParameterEntry with mismatched key.

Notes

This method automatically overwrites existing parameters. For more control, use add_parameter instead.

add_parameter(parameter_name: str, parameter_value: str | Real, parameter_origin=None, parameter_key=None, parameter_info=None, overwrite_parameters=False)[source]

Add a parameter to the database.

Parameters:

  • parameter_name (str) – Name of the parameter.

  • parameter_value (float or str) – Value of the parameter. Strings are converted to float.

  • parameter_origin (str, optional) – Description of where the parameter came from (e.g., filename). Stored in parameter_info.

  • parameter_key (dict, ParameterKey, str, or None, optional) – Lookup key for the parameter. If None, creates key with only the parameter name.

  • parameter_info (dict, optional) – Additional metadata about the parameter. parameter_origin is added to this dict if provided.

  • overwrite_parameters (bool, default False) – If True, allows overwriting existing parameters. If False, raises ValueError if key already exists.

Raises:

ValueError – If key already exists in database and overwrite_parameters=False.

Examples

>>> db = bcp.ParameterDatabase()
>>> db.add_parameter('kb', 100.0)
>>> db.add_parameter('ku', 0.01,
...     parameter_key={'mechanism': 'binding'})
find_parameter(mechanism, part_id, param_name)[source]

Search for a parameter with automatic defaulting.

Searches the database for the best matching parameter using a hierarchical defaulting system. If an exact match is not found, progressively more general keys are tried.

Parameters:

  • mechanism (str, Mechanism, or None) – Mechanism identifier. Can be a string (used as both name and type), a Mechanism object (uses .name and .mechanism_type), or None.

  • part_id (str or None) – Part/component identifier for the parameter.

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

Returns:

ModelParameter object with search_key and found_key attributes showing how the parameter was found. Returns None if no match found at any defaulting level.

Return type:

ModelParameter or None

Raises:

ValueError – If mechanism is not a string, Mechanism object, or None.

Notes

The method searches for parameters in this order:

  1. (mechanism.name, part_id, param_name)

  2. (mechanism.type, part_id, param_name)

  3. (None, part_id, param_name)

  4. (mechanism.name, None, param_name)

  5. (mechanism.type, None, param_name)

  6. (None, None, param_name)

This allows setting default parameters at various levels of specificity. For example, a general ‘kb’ parameter can be overridden for specific mechanisms or parts.

Examples

>>> db = bcp.ParameterDatabase()
>>> db.add_parameter('kb', 100.0)
>>> db.add_parameter('kb', 200.0,
...     parameter_key={'mechanism': 'binding'})

General lookup finds the general parameter

>>> param = db.find_parameter(None, None, 'kb')
>>> param.value
100.0

Mechanism-specific lookup finds the specific parameter

>>> param = db.find_parameter('binding', None, 'kb')
>>> param.value
200.0
load_parameters_from_database(parameter_database, overwrite_parameters=False) → None[source]

Load parameters from another ParameterDatabase.

Parameters:

  • parameter_database (ParameterDatabase) – Another ParameterDatabase instance to copy parameters from.

  • overwrite_parameters (bool, default False) – If True, allows overwriting existing parameters. If False, raises ValueError if duplicate keys are encountered.

Raises:

  • TypeError – If parameter_database is not a ParameterDatabase instance.

  • ValueError – If duplicate keys exist and overwrite_parameters=False.

Examples

>>> db1 = bcp.ParameterDatabase(parameter_dictionary={'kb': 100.0})
>>> db2 = bcp.ParameterDatabase()
>>> db2.load_parameters_from_database(db1)
>>> db2['kb'].value
100.0
load_parameters_from_dictionary(parameter_dictionary: Dict[ParameterKey, str | Real], overwrite_parameters=False) → None[source]

Load parameters from a dictionary.

Parameters:

  • parameter_dictionary (dict) – Dictionary with keys as ParameterKey-like objects (dict, tuple, or str) and values as numerical values or strings.

  • overwrite_parameters (bool, default False) – If True, allows overwriting existing parameters. If False, raises ValueError if duplicate keys are encountered.

Raises:

ValueError – If duplicate keys exist and overwrite_parameters=False.

Examples

>>> db = bcp.ParameterDatabase()
>>> params = {
...     'kb': 100.0,
...     ('binding', None, 'ku'): 0.01,
... }
>>> db.load_parameters_from_dictionary(params)
load_parameters_from_file(filename: str, overwrite_parameters=False) → None[source]

Load parameters from a file.

Reads parameters from a CSV or TSV file and adds them to the database. The file must have ‘param_name’ and ‘param_val’ columns. Optional columns include ‘mechanism’, ‘part_id’, and ‘units’.

Parameters:

  • filename (str) – Path to parameter file. Must be tab-separated (.tsv, .txt) or comma-separated (.csv). File is searched in current directory and BioCRNpyler package paths.

  • overwrite_parameters (bool, default False) – If True, allows overwriting existing parameters. If False, raises ValueError if duplicate keys are encountered.

Raises:

ValueError – If file cannot be found, has invalid format, or contains duplicate keys when overwrite_parameters=False.

Notes

Accepted column names (case-sensitive, first match used):

  • param_name: ‘parameter_name’, ‘parameter’, ‘param’, ‘param_name’

  • param_val: ‘val’, ‘value’, ‘param_val’, ‘parameter_value’

  • mechanism: ‘mechanism’, ‘mechanism_id’

  • part_id: ‘part_id’, ‘part’

  • unit: ‘units’, ‘unit’

Additional columns are stored in parameter_info dictionary.

File Format Example (CSV):

.. code::

mechanism,part_id,param_name,param_val,unit binding,,kb,100,1/s binding,,ku,0.01,1/s transcription,prom1,ktx,0.05,1/s

Examples

>>> db = bcp.ParameterDatabase(
...    parameter_file='mixtures/pure_parameters.tsv')

Load multiple files:

>>> db = bcp.ParameterDatabase(
...     parameter_file=[
...         'mixtures/pure_parameters.tsv',
...         'components/tetr_parameters.tsv'])