pysb-units
streamlines unit management and helps ensure unit consistency in PySB models.
! Note |
---|
psyb-units is still in version zero development so new versions may not be backwards compatible. |
pysb-units installs as the pysb.units
Python (namespace) package. It is has been developed with Python 3.11.3 and PySB 1.15.0.
Note that pysb-units
has the following core dependencies:
- PySB - developed using version 1.15.0.
- astropy - developed using version 5.3.4.
- sympy - developed using version 1.11.1.
You can install pysb-units
version 0.3.0 with pip
sourced from the GitHub repo:
Fresh install:
pip install git+https://github.com/Borealis-BioModeling/[email protected]
Or to upgrade from an older version:
pip install --upgrade git+https://github.com/Borealis-BioModeling/[email protected]
Fresh install:
pip install https://github.com/Borealis-BioModeling/pysb-units/archive/refs/tags/v0.4.0.zip
Or to upgrade from an older version:
pip install --upgrade https://github.com/Borealis-BioModeling/pysb-units/archive/refs/tags/v0.4.0.zip
First, download the repository. Then from the pysb-units
folder/directory run
pip install .
This project is licensed under the BSD 2-Clause License - see the LICENSE file for details
See: CHANGELOG
pysb-units
is an add-on for the PySB modeling framework that provides tools to manage units. The key features of pysb-units
are a new Unit
object derived from pysb annotations, a new SimulationUnits
object, and drop-in replacements for core model components, including Model
, Parameter
, Expression
, Rule
, Initial
, and Observable
that include new features to help manage units. Additionally, pysb-units
defines a couple of useful utility functions, including the unitize
and check
functions, which make it easier to add units to model and run additional unit checks (such as unit consistency).
pysb-units introduces two new objects for defining and managing units in a pysb model. They are:
Unit(component, 'unit')
- assigns a particular unit value to a model component such as Parameter or Observable. E.g., to assign a frequency unit to a rate constant parameter (as a single line):Unit(Parameter('k_f', 1e-1), '1/s')
. This object is derived from pysb'sAnnotation
object but leverages theastropy.units
library for unit management.- You can explicity define dimensionless quantities by passing
None
for the input units: e.g.,Unit(scaling_factor, None)
.Parameter
s accept an optional keywordunit
that can be used to assign aUnit
that parameter automatically with needing to explicity attach theUnit
object.
- You can explicity define dimensionless quantities by passing
SimulationUnits(concentration='concentration_unit', time='time_unit')
- sets the concentration and time units that are to be used in simulations. E.g., to set the use of nM concentrations and time in seconds:SimulationUnits(concentration='nM', time='s')
. Note that when this object is defined it will enforce conversion of all concentration and time units to the specified units.- Supports stochastic simulation units with
concentration='molecules'
; it uses a unit conversion based on the equationmolecules = [molar concentraion] * volume * N_A
, where N_A is Avogadro's number. - To define the appropriate volume for the conversion a call to the
pysb.units.set_molecule_volume(value[float], unit[str])
can be added before or just after theSimulationUnits
initialization. E.g.,pysb.units.set_molecule_volume(1.6, 'pL')
would set a volume of 1.6 pL for the conversion used bySimulationUnits
to go from molar concentrations to number of molecules. Note that these conversions currently only work properly for non-compartmental models.
- Supports stochastic simulation units with
Additionally, pysb-units defines drop-in replacements for core model components, including Model
, Parameter
, Expression
, Rule
, Initial
, and Observable
that are integrated with new units-based features. pysb-units
defines a couple of useful utility functions, including the unitize
and check
functions, which make it easier to add units to model and run additional unit checks (such as unit consistency).
A simple model with one degradation reaction:
- Regular pysb:
from pysb import Model, Parameter, Monomer, Initial, Observable, Expression
# Initialize the PySB model:
Model()
# Monomer(s):
Monomer('protein')
# Model parameter(s):
# Initial concentration of protein
Parameter('protein_0', 0.5) # uM
# 1st-order rate parameter for the degradation
Parameter('k_deg', 0.1) # 1/s
# Initial concentration(s)
Initial(protein, protein_0)
# Reaction rule(s)
# Just the one degradation
Rule('degradation', protein() >> None, k_deg)
# Observables
# Time-dependent protein concentration:
Observable('protein_t', protein()) # uM
# Expressions
# The time-dependent degradation rate:
Expression('deg_rate', (protein_t * k_deg)) # uM/s
- pysb with pysb-units
# Import the pysb components we need:
from pysb import Model, Parameter, Monomer, Initial, Observable, Expression
# Import pysb-units:
import pysb.units as units
# Activate units - replaces core model components
# with the appropriate versions from pysb.units:
units.unitize()
# Initialize the PySB model:
Model()
# The primary units needed for simulating the model are
# concentration (or amount) and time. We can define those
# here with SimulationUnits:
SimulationUnits(concentration='uM', time='s')
# Monomer(s):
Monomer('protein')
# Model parameter(s):
# Initial concentration of protein:
Parameter('protein_0', 500.)
# Attach units to protein_0:
Unit(protein_0, 'nM')
# 1st-order rate parameter for the degradation
# defined with frequency (1/time) units - here,
# we chain Unit and Parameter definitions:
Unit(Parameter('k_deg', 0.1), '1/s')
# Initial concentration(s)
Initial(protein, protein_0)
# Reaction rule(s)
# Just the one degradation
Rule('degradation', protein() >> None, k_deg)
# Observables
# Time-dependent protein concentration:
Observable('protein_t', protein())
# Expressions
# The time-dependent degradation rate:
Expression('deg_rate', (protein_t * k_deg))
# Apply additional unit checks, including unit duplication
# and unit consistency checking:
units.check()
In the above unit-ed example, additional unit-based features and unit validation are applied:
SimulationUnits(concentration='uM', time='s')
- sets the the expected units for the concentration (or amount) and time globally for the model. Any parameters that have concentration or time units will be checked against these definitions and if necessary automatically converted to the expected units.Unit(protein_0, 'nM')
- the unit 'nM' will be automatically converted to 'uM'since that is the global concentration unit we defined withSimulationUnits
, and the appropriate scaling will be applied toprotein_0.value
.Initial(protein, protein_0)
the units ofprotein_0
will be checked to make sure they are a valid concentration.Rule('degradation', protein >> None, k_deg)
the reaction order of the rule will be determined and the units ofk_deg
will be checked to make sure they match the expected unit type corresponding to that reaction order. In this case, the degradation is a 1st-order reaction, sok_deg
is expected to have inverse time (i.e., frequency) units: [1 / time], such as, [1 / s] or [1 / h].Observable('protein_t', protein())
- here, the units of the observable will be automatically inferred based on those set withSimulationUnits
, so the observable will have units of 'uM'.Expression('deg_rate', (protein_t * k_deg))
- units of expressions are automatically inferred from the units of parameters and observables, so in this case the Expression will have units of 'uM/s'.units.check()
- this function applies additional unit checking and will issue warnings for duplicate units (two different units assigned to the same parameter), lack of consistency for units of the same physical type (e.g., concentration, time, etc.), and parameters without any
In the previous example we added explicit calls to
the unitize
and check
functions. If you prefer, you can use the units
context manager instead to achieve the same effects:
# Import the pysb components we need:
from pysb import Model, Parameter, Monomer, Initial, Observable, Expression
# Import the pysb-units context manager:
from pysb.units import units
# Activate units using the units context manager -
# replaces core model components with the appropriate
# versions from pysb.units (similar to unitize) and will
# automatically call the check function when exiting the
# context:
with units():
# Initialize the PySB model:
Model()
# The primary units needed for simulating the model are
# concentration (or amount) and time. We can define those
# here with SimulationUnits:
SimulationUnits(concentration='uM', time='s')
# Monomer(s):
Monomer('protein')
# Model parameter(s):
# Initial concentration of protein:
Parameter('protein_0', 500.)
# Attach units to protein_0:
Unit(protein_0, 'nM')
# 1st-order rate parameter for the degradation
# defined with frequency (1/time) units - here,
# we chain Unit and Parameter definitions:
Unit(Parameter('k_deg', 0.1), '1/s')
# Initial concentration(s)
Initial(protein, protein_0)
# Reaction rule(s)
# Just the one degradation
Rule('degradation', protein() >> None, k_deg)
# Observables
# Time-dependent protein concentration:
Observable('protein_t', protein())
# Expressions
# The time-dependent degradation rate:
Expression('deg_rate', (protein_t * k_deg))
PySB contains some helpful macro functions, such as bind
and degrade
, that can be used to streamline rule creation for recurring motifs. To use these macros with the pysb.units
add-on you can use the add_macro_units
function as below:
# Import the pysb components we need:
from pysb import Model, Parameter, Monomer, Initial, Observable, Expression
# Import the module with the wanted macros:
from pysb import macros
# Import pysb-units:
import pysb.units as units
# Activate units - replaces core model components
# with the appropriate versions from pysb.units:
units.unitize()
# Apply the units to the macros module:
units.add_macro_units(macros)
# Initialize the PySB model:
Model()
# The core units used when simulating the model are
# concentration (or amount) and time. We can define those
# here with SimulationUnits:
SimulationUnits(concentration='uM', time='s')
# Monomer(s):
Monomer('protein')
# Model parameter(s):
# Initial concentration of protein:
Parameter('protein_0', 500.)
# Attach units to protein_0:
Unit(protein_0, 'nM')
# 1st-order rate parameter for the degradation
# defined with frequency (1/time) units - here,
# we chain Unit and Parameter definitions:
Unit(Parameter('k_deg', 0.1), '1/s')
# Initial concentration(s)
Initial(protein, protein_0)
# Reaction rule(s)
# Just the one degradation - instead
# of defining a Rule that encodes the degradation reaction
# we can take advantage of degrade macro:
macros.degrade(protein(), k_deg)
# Observables
# Time-dependent protein concentration:
Observable('protein_t', protein())
# Expressions
# The time-dependent degradation rate:
Expression('deg_rate', (protein_t * k_deg))
# Apply additional unit checks, including unit duplication
# and unit consistency checking:
units.check()
pysb-units
supports stochastic simulation units (number of molecules in place of a molar concentration) at the level of model definition via the set_molecule_volume
function and the SimulationUnits
object. To enforce automatic conversion from molar concentrations to number of molecules we can update our example model as follows:
# Import the pysb components we need:
from pysb import Model, Parameter, Monomer, Initial, Observable, Expression
# Import pysb-units:
import pysb.units as units
# Activate units - replaces core model components
# with the appropriate versions from pysb.units:
units.unitize()
# Initialize the PySB model:
Model()
# The primary units needed for simulating the model are
# concentration (or amount) and time. We can define those
# here with SimulationUnits.
# In this case, we want stochastic units so we can
# set the concentration to 'molecules'
SimulationUnits(concentration='molecules', time='s')
# Next, for stochastic units we need to set the volume
# for the molar concentration to number of molecules conversion. Let's
# Assume a cellular volume of 1 pL:
units.set_molecule_volume(1.0, 'pL')
# Monomer(s):
Monomer('protein')
# Model parameter(s):
# Initial concentration of protein:
Parameter('protein_0', 500.)
# Attach units to protein_0:
Unit(protein_0, 'nM')
# 1st-order rate parameter for the degradation
# defined with frequency (1/time) units - here,
# we chain Unit and Parameter definitions:
Unit(Parameter('k_deg', 0.1), '1/s')
# Initial concentration(s)
Initial(protein, protein_0)
# Reaction rule(s)
# Just the one degradation
Rule('degradation', protein() >> None, k_deg)
# Observables
# Time-dependent protein concentration:
Observable('protein_t', protein())
# Expressions
# The time-dependent degradation rate:
Expression('deg_rate', (protein_t * k_deg))
# Apply additional unit checks, including unit duplication
# and unit consistency checking:
units.check()
Now, when Unit(protein_0, 'uM)
is evaluated the concentration of 500 micromolar will be automatically converted to the number of molecules ('molecules' unit).
Note that at the moment, this approach only works for non-compartmental models.
The Parameter
component can accept an optional keyword argument for the unit
, which means you can define the unit along with the parameter without explicitly applying a Unit
object to the parameter. So, you can define unit-ed parameters using something like (as of version 0.3.0)
Parameter('k_r', 0.1, unit="1/s")
instead of doing (earlier versions)
Unit(Parameter('k_r', 0.1), '1/s')
The outcome is the same either way, but the top version is a little more compact and easier to read.
You can get a list of Unit
objects defined for a model with the Model.units
property:
from my_model_with_units import model
print(model.units)
Additional examples can be found in or imported from pysb.units.examples, including
- bngwiki_simple. - adapted from pysb example pysb.examples.bngwiki_simple:
from pysb.units.examples.bngwiki_simple import model
- jnk3_no_ask1. - adapted from JARM jnk3_no_ask1:
from pysb.units.examples.jnk3_no_ask1 import model
pysb.units
leverages the astropy.units
package for unit parsing and as its physical units library, but adds the following custom units/unit-types for reaction model use:
- "M" = molar concentration : an alias for mole / L. Includes all fraction orders from femto to milli.
- "molecules" - number of molecules : useful for stochastic simulations.
- "1/cell" = number per cell : useful for stochastic simulations of cell signaling networks.
- "1 / (cell**-1 * s)" = cellular reaction rate : reaction rate corresponding to concentrations in number per cell
- "mcg" = micrograms : alias for "ug", often used in pharmaceuticals.
- "mole / m**2" = mole area density
- "g / s" = mass velocity : for reaction rates where mass is used in place of concentration.
-
Issues 🐛 : Please open a GitHub Issue to report any problems/bugs with the code or its execution, or to make any feature requests.
-
Discussions ❔ : If you have questions, suggestions, or want to discuss anything else related to the project, feel free to use the pysb-units Discussions board.
I'm very happy that you've chosen to use pysb-units. This add-on is a project that I develop and maintain on my own time, independently of the core PySB library, and without external funding. If you've found it helpful, here are a few ways you can support its ongoing development:
- Star ⭐ : Show your support by starring the pysb-units GitHub repository. It helps increase the project's visibility and lets others know it's useful. It also benefits my motivation to continue improving the package!
- Share 📣 : Sharing
pysb-units
on your social media, forums, or with your network is another great way to support the project. It helps more people discoverpysb-units
, which in turn motivates me to keep developing! - Cite 📚 : Citing or mentioning this software in your work, publications, or projects is another valuable way to support it. It helps spread the word and acknowledges the effort put into its development, which is greatly appreciated!
- Sponsor 💵 : Even small financial contributions, such as spotting me the cost of a tea through Ko-fi so I can get my caffeine fix, can make a big difference! Every little bit can help me continue developing this and other open-source projects.
Please see packages such as simplePSO, PyDREAM, Gleipnir, or GAlibrate for tools to do PySB model parameter estimation using stochastic optimization or Bayesian Monte Carlo approaches.
If you want to build PKPD models with PySB the pysb-pkpd add-on can help.
If you want to separately fit response data independetly of PK data, then the pharmacodynamic-response-models package may also be useful.
pyvipr can be used for static and dynamic PySB model visualizations.