controlSBML


NamecontrolSBML JSON
Version 0.2.21 PyPI version JSON
download
home_pagehttps://github.com/ModelEngineering/controlSBML
SummaryControl analysis and design for SBML Models.
upload_time2022-05-30 16:38:48
maintainer
docs_urlNone
authorJoseph L. Hellerstein
requires_python>=3.6
license
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 0.42425s