# controlSBML
The [Systems Biology Markup Language (SBML)](https://co.mbine.org/standards/sbml) is a community standard for representing
simulations of biological models, especially chemical reaction networks.
``controlSBML`` is a package that does control analysis and design of SBML models using
the [CalTech ``control`` package](http://python-control.sourceforge.net/manual/).
``controlSBML`` uses the following "systems characterization" of an SBML model:
* state variables are floating species;
* inputs are reaction fluxes;
* outputs are a subset of the state variables.
We note that reaction fluxes cannot be manipulated directly. Thus,implementation requires a mapping from a reaction flux to an *effector*, typically a chemical
species such as an enzyme that is specific to the reaction.
The keyword ``effector_dct`` refers to a python dictionary that does this mapping.
(See the ``makeNonlinearIOSystem`` method of ``ControlSBML``.)
``controlSBML`` interfaes to the ``control`` package by creating two kinds of ``control`` objects for an SBML model:
* ``NonlinearIOSystem``, which wraps the actual simulation of the SBML model; and
* ``StateSpace``, which is a linear MIMO model approximation of the SBML model at a specified time in the simulation.
These objects can be used in combination with other ``control`` objects to analyze system properties,
design controllers, and construct closed loop systems.
``controlSBML`` also provides analyses of SBML models as well as a means to manipulate
elements of the SBML model.
## Installation
``pip install controlSBML``
To find the current version:
```
import controlSBML as ctl
ctl.__version__
```
### Installing ``slycot`` (optional)
To get the full set of capabilities from the ``control`` package,
you need to install ``slycot``, a package that addresses requirements
for more sophisticated manipulation of MIMO models (e.g.,
solving algebraic Ricotti equations).
The best way is to install ``slycot`` is from binaries using ``anaconda``.
However,
at the present time, ``anaconda`` is difficult to set up on
Google Collaboratory.
Otherwise, you need to install from source. Below are the instructions
for Ubuntu.
* install cmake: ``pip install cmake --upgrade``
* install sikit-build: ``pip install scikit-build``
* install fortran: ``sudo apt-get install gfortran``
* provide path to fortran: ``export FC=`which gfortran``
* install BLAS: ``sudo apt-get install libatlas-base-dev``
* clone Sylcot: ``git clone --recurse-submodules https://github.com/python-control/Slycot.git``
* ``cd Slycot``
* ``python setup.py install``
## Constructing ControlSBML
```
ctlsb = ControlSBML(model_reference)
```
where
``model_reference``can be any of the following:
* path to a local file with the extension ``.ant`` or ``.xml``
* a python string for an SBML or Antimony model representation
* a URL to an XML file
## Technical Summary
### ``ControlSBML``
#### Properties
* ``roadrunner`` is the roadrunner object for the SBML model.
* ``jacobian_df`` is the full Jacobian of the model at the current simulation time. Changes to ``roadrunner`` can change this property.
* ``antimony`` is the antimony representation of the model.
* ``A_df`` is the ${\bf A}$ matrix in the linear system represented as a pandas DataFrame.
* ``B_df`` is the ${\bf B}$ matrix in the linear system represented as a pandas DataFrame.
* ``C_df`` is the ${\bf C}$ matrix in the linear system represented as a pandas DataFrame.
* ``state_names`` is a list of floating species that constitute the state vector.
* ``input_names`` is a list of reaction names that specify the input vector.
* ``output_names`` is a list of floating species that constitute the output vector.
#### Methods
* ``setTime(new_time)`` resets ``roadrunner`` and runs a simulation from time zero to the time specified.
* ``makeStateSpace()`` creates a ``control`` state space object using the Jacobian of the model at the current simulation time.
* ``makeNonlinearIOSystem()`` creates a ``NonlinearIOSystem`` object that simulates the SBML model.
* ``plotTrueModel`` plots a roadrunner simulation.
* ``plotLinearApproximation`` plots the linear approximation provided by an ${\bf A}$ matrix. The default ${\bf A}$ matrix
is the Jacobian of the current ``RoadRunner`` instance. You can either specify a different ${\bf A}$ or set the ``RoadRunner`` instance to a different time.
* ``plotBode`` constructs bode plots for the SISO systems formed by all combinations of inputs and outputs.
### Other Functions
* ``makeTS`` creates a time series object from an array. A time series object is a DataFrame whose index in time (in integer milliseconds),
and the columns are variable names.
* ``simulateSystem`` provides a simplified way to simulate a system (which may be an ``interconnect``) by creating the times and initial,
returns a time series DataFrame.
* ``plotOneTS`` plots a single time series DataFrame.
* ``plotManyTS`` plots multiple time series DataFrames structured so that each column is a separate plot that compares the different times series.
## Example
[This notebook](https://github.com/ModelEngineering/controlSBML/blob/main/notebooks/Using-Control-SBML.ipynb) provides a simple example of using ``controlSBML``.
## Developer Notes
1. The package works with and without ``slycot``. So two virtual environments are needed for testing: ``ctl`` includes ``slycot`` and ``ctl_tst`` does not. Note
that continuous integration is done only *without* ``slycot``.
## Version History
* 0.2.21 5/30/2022
* NonlinearIOSystem creates a logger.
* SISOClosedLoopSystem.makeFullStateSystem has option for filters
* Changed legend of step respoinse plot to use "reference" instead of "step"
* 0.2.20 5/27/2022
* Fix bug in SISOClosedLoopSystem.evaluateControllability because scipy didn't
handle nan values.
* 0.2.19 5/27/2022
* Fix bug in SISOClosedLoopSystem.evaluateControllability because scipy didn't
handle nan values.
* 0.2.18 5/26/2022
* Fix small bug
* 0.2.17 5/26/2022
* Deleted the callback_log implemented in 0.2.14.
* 0.2.16 5/24/2022
* Refactored SISOClosedLoopSystem
* Implemented SISOClosedLoopSystem.makeFullStateController
* Fixed bug with makePIDController where ki, kd are ineffective.
* 0.2.15 5/21/2022
* Fix bug in reverting the semantics of control input to be setting the species
as a static.
* 0.2.14 5/11/2022
* Provide callback for each manufactured IOsystemFactory
* Reverted semantics of control input to a NonlinearIOSystem to be
setting the value rather than adding or subtracting a value.
* 0.2.13 5/9/2022
* SISOClosedLoopSystem provides a way to construct a closed loop system
for an SBML model. The system has a PID controller and a filter.
* IOSysemFactory has a log
* 0.2.12 5/3/2022
* IOSystemFactory creates IOSystem objects for Adder, Multiplier,
Filter, PIDController, Sinusoid, Constant, Passthru
* State inputs add to state, not replace the state value.
* 0.2.11 4/25/2022
* Fix bug in calculating transfer function that incorrectly considered state
* 0.2.9 4/19/2022
* Fluxes can be outputs
* Construction of transfer function includes atol option for simplification
* 0.2.8 4/17/2022
* Added options to plotTrueModel
* Updated Using ControlSBML with an example of doing feedback
* 0.2.7 4/11/2022
* Species can be inputs
* makeStateSpace, makeTransferFunction have timepoint argument
* 0.2.6 4/10/2020
* Default for constructor: is_reduced=False
* makeTransferFunction
* 0.2.5 4/8/2022
* Improve performance by not recalculating Jacobian
* Fix bugs related to implementation of is_reduced as applied on NonlinearIOSystem
* 0.2.4 3/31/2024 - Create reduced A matrix
* mat2Df - fixed bug with printing column names
* Create reduced A matrix for makeStateSpace so that A is non-singular
Default output_names is all floating species
* 0.2.3, 3/22/2022 - Bug fix for mat2DF
* 0.2.2, 3/22/2022 - Bug fix
* 0.2.1, 3/22/2022 - Bug fix
* 0.2.0, 3/22/2022 - Version for class
* ppMat - pretty print a matrix
* plotMat - display a heatmap for a matrix
* mat2TS - convert a matrix to a timeseries
* mat2DF - convert a matrix to a dataframe
* 0.1.6, 3/16/2022
* ``Using-Control-SBML.ipynb`` has an example of doing feedback control design
with ``controlSBML``.
* ``control.NonlinearIOSystem`` wraps an SBML model. Can be used
in the construction of systems using ``control.interconnect`` and in simulations using ``control.input_output_response``. One caveat is that this may work poorly for models implemented as SBML rate rules.
* 0.1.5, 3/5/2022.
* More options for plotting and simulations
* plotBode
* Inputs are identified by reaction Ids
* 0.1.3, 2/13/2022. First release.
Raw data
{
"_id": null,
"home_page": "https://github.com/ModelEngineering/controlSBML",
"name": "controlSBML",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Joseph L. Hellerstein",
"author_email": "jlheller@uw.edu",
"download_url": "https://files.pythonhosted.org/packages/8a/0c/de3751fae7b00952e4b84c103d2132a815e24f2919e642912e3fbc2f4892/controlSBML-0.2.21.tar.gz",
"platform": null,
"description": "# controlSBML \n The [Systems Biology Markup Language (SBML)](https://co.mbine.org/standards/sbml) is a community standard for representing\nsimulations of biological models, especially chemical reaction networks.\n``controlSBML`` is a package that does control analysis and design of SBML models using\nthe [CalTech ``control`` package](http://python-control.sourceforge.net/manual/).\n\n``controlSBML`` uses the following \"systems characterization\" of an SBML model:\n\n* state variables are floating species;\n* inputs are reaction fluxes;\n* outputs are a subset of the state variables.\n\nWe note that reaction fluxes cannot be manipulated directly. Thus,implementation requires a mapping from a reaction flux to an *effector*, typically a chemical\nspecies such as an enzyme that is specific to the reaction.\nThe keyword ``effector_dct`` refers to a python dictionary that does this mapping.\n(See the ``makeNonlinearIOSystem`` method of ``ControlSBML``.)\n\n``controlSBML`` interfaes to the ``control`` package by creating two kinds of ``control`` objects for an SBML model:\n\n* ``NonlinearIOSystem``, which wraps the actual simulation of the SBML model; and\n* ``StateSpace``, which is a linear MIMO model approximation of the SBML model at a specified time in the simulation.\n\nThese objects can be used in combination with other ``control`` objects to analyze system properties,\ndesign controllers, and construct closed loop systems.\n\n``controlSBML`` also provides analyses of SBML models as well as a means to manipulate\nelements of the SBML model.\n\n## Installation\n``pip install controlSBML``\n\nTo find the current version:\n```\nimport controlSBML as ctl\nctl.__version__\n```\n\n### Installing ``slycot`` (optional)\nTo get the full set of capabilities from the ``control`` package,\nyou need to install ``slycot``, a package that addresses requirements\nfor more sophisticated manipulation of MIMO models (e.g.,\nsolving algebraic Ricotti equations).\n\nThe best way is to install ``slycot`` is from binaries using ``anaconda``.\nHowever,\nat the present time, ``anaconda`` is difficult to set up on\nGoogle Collaboratory.\n\nOtherwise, you need to install from source. Below are the instructions\nfor Ubuntu.\n\n* install cmake: ``pip install cmake --upgrade``\n* install sikit-build: ``pip install scikit-build``\n* install fortran: ``sudo apt-get install gfortran``\n* provide path to fortran: ``export FC=`which gfortran``\n* install BLAS: ``sudo apt-get install libatlas-base-dev``\n* clone Sylcot: ``git clone --recurse-submodules https://github.com/python-control/Slycot.git``\n* ``cd Slycot``\n* ``python setup.py install`` \n\n## Constructing ControlSBML\n```\nctlsb = ControlSBML(model_reference)\n```\n where\n``model_reference``can be any of the following:\n* path to a local file with the extension ``.ant`` or ``.xml``\n* a python string for an SBML or Antimony model representation\n* a URL to an XML file\n\n## Technical Summary\n\n### ``ControlSBML``\n#### Properties\n* ``roadrunner`` is the roadrunner object for the SBML model.\n* ``jacobian_df`` is the full Jacobian of the model at the current simulation time. Changes to ``roadrunner`` can change this property.\n* ``antimony`` is the antimony representation of the model.\n* ``A_df`` is the ${\\bf A}$ matrix in the linear system represented as a pandas DataFrame.\n* ``B_df`` is the ${\\bf B}$ matrix in the linear system represented as a pandas DataFrame.\n* ``C_df`` is the ${\\bf C}$ matrix in the linear system represented as a pandas DataFrame.\n* ``state_names`` is a list of floating species that constitute the state vector.\n* ``input_names`` is a list of reaction names that specify the input vector.\n* ``output_names`` is a list of floating species that constitute the output vector.\n\n#### Methods\n* ``setTime(new_time)`` resets ``roadrunner`` and runs a simulation from time zero to the time specified.\n* ``makeStateSpace()`` creates a ``control`` state space object using the Jacobian of the model at the current simulation time.\n* ``makeNonlinearIOSystem()`` creates a ``NonlinearIOSystem`` object that simulates the SBML model.\n* ``plotTrueModel`` plots a roadrunner simulation.\n* ``plotLinearApproximation`` plots the linear approximation provided by an ${\\bf A}$ matrix. The default ${\\bf A}$ matrix\nis the Jacobian of the current ``RoadRunner`` instance. You can either specify a different ${\\bf A}$ or set the ``RoadRunner`` instance to a different time.\n* ``plotBode`` constructs bode plots for the SISO systems formed by all combinations of inputs and outputs.\n\n### Other Functions\n* ``makeTS`` creates a time series object from an array. A time series object is a DataFrame whose index in time (in integer milliseconds),\nand the columns are variable names.\n* ``simulateSystem`` provides a simplified way to simulate a system (which may be an ``interconnect``) by creating the times and initial,\nreturns a time series DataFrame.\n* ``plotOneTS`` plots a single time series DataFrame.\n* ``plotManyTS`` plots multiple time series DataFrames structured so that each column is a separate plot that compares the different times series.\n\n## Example\n\n[This notebook](https://github.com/ModelEngineering/controlSBML/blob/main/notebooks/Using-Control-SBML.ipynb) provides a simple example of using ``controlSBML``.\n\n## Developer Notes\n1. The package works with and without ``slycot``. So two virtual environments are needed for testing: ``ctl`` includes ``slycot`` and ``ctl_tst`` does not. Note\nthat continuous integration is done only *without* ``slycot``.\n\n## Version History\n* 0.2.21 5/30/2022\n * NonlinearIOSystem creates a logger.\n * SISOClosedLoopSystem.makeFullStateSystem has option for filters\n * Changed legend of step respoinse plot to use \"reference\" instead of \"step\"\n* 0.2.20 5/27/2022\n * Fix bug in SISOClosedLoopSystem.evaluateControllability because scipy didn't\n handle nan values.\n* 0.2.19 5/27/2022\n * Fix bug in SISOClosedLoopSystem.evaluateControllability because scipy didn't\n handle nan values.\n* 0.2.18 5/26/2022\n * Fix small bug\n* 0.2.17 5/26/2022\n * Deleted the callback_log implemented in 0.2.14.\n* 0.2.16 5/24/2022\n * Refactored SISOClosedLoopSystem\n * Implemented SISOClosedLoopSystem.makeFullStateController\n * Fixed bug with makePIDController where ki, kd are ineffective.\n* 0.2.15 5/21/2022\n * Fix bug in reverting the semantics of control input to be setting the species\n as a static.\n* 0.2.14 5/11/2022\n * Provide callback for each manufactured IOsystemFactory\n * Reverted semantics of control input to a NonlinearIOSystem to be\nsetting the value rather than adding or subtracting a value.\n* 0.2.13 5/9/2022\n * SISOClosedLoopSystem provides a way to construct a closed loop system\n for an SBML model. The system has a PID controller and a filter.\n * IOSysemFactory has a log\n* 0.2.12 5/3/2022\n * IOSystemFactory creates IOSystem objects for Adder, Multiplier,\n Filter, PIDController, Sinusoid, Constant, Passthru\n * State inputs add to state, not replace the state value.\n* 0.2.11 4/25/2022\n * Fix bug in calculating transfer function that incorrectly considered state\n* 0.2.9 4/19/2022\n * Fluxes can be outputs\n * Construction of transfer function includes atol option for simplification\n* 0.2.8 4/17/2022\n * Added options to plotTrueModel\n * Updated Using ControlSBML with an example of doing feedback \n* 0.2.7 4/11/2022\n * Species can be inputs\n * makeStateSpace, makeTransferFunction have timepoint argument\n* 0.2.6 4/10/2020\n * Default for constructor: is_reduced=False\n * makeTransferFunction\n* 0.2.5 4/8/2022\n * Improve performance by not recalculating Jacobian\n * Fix bugs related to implementation of is_reduced as applied on NonlinearIOSystem\n* 0.2.4 3/31/2024 - Create reduced A matrix\n * mat2Df - fixed bug with printing column names\n * Create reduced A matrix for makeStateSpace so that A is non-singular\n Default output_names is all floating species\n* 0.2.3, 3/22/2022 - Bug fix for mat2DF\n* 0.2.2, 3/22/2022 - Bug fix\n* 0.2.1, 3/22/2022 - Bug fix\n* 0.2.0, 3/22/2022 - Version for class\n * ppMat - pretty print a matrix\n * plotMat - display a heatmap for a matrix\n * mat2TS - convert a matrix to a timeseries\n * mat2DF - convert a matrix to a dataframe\n* 0.1.6, 3/16/2022\n * ``Using-Control-SBML.ipynb`` has an example of doing feedback control design\nwith ``controlSBML``.\n * ``control.NonlinearIOSystem`` wraps an SBML model. Can be used\n in the construction of systems using ``control.interconnect`` and in simulations using ``control.input_output_response``. One caveat is that this may work poorly for models implemented as SBML rate rules.\n* 0.1.5, 3/5/2022.\n * More options for plotting and simulations\n * plotBode\n * Inputs are identified by reaction Ids\n* 0.1.3, 2/13/2022. First release.\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Control analysis and design for SBML Models.",
"version": "0.2.21",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "1cbc2370b3ae3bed2944187140208dde",
"sha256": "740a167e72d14786156c8a5a0880d0c6015f4c427cd73f3056f0c0e96e6934c4"
},
"downloads": -1,
"filename": "controlSBML-0.2.21.tar.gz",
"has_sig": false,
"md5_digest": "1cbc2370b3ae3bed2944187140208dde",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 33856,
"upload_time": "2022-05-30T16:38:48",
"upload_time_iso_8601": "2022-05-30T16:38:48.996214Z",
"url": "https://files.pythonhosted.org/packages/8a/0c/de3751fae7b00952e4b84c103d2132a815e24f2919e642912e3fbc2f4892/controlSBML-0.2.21.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-05-30 16:38:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "ModelEngineering",
"github_project": "controlSBML",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "controlsbml"
}
JSON
