14.6. steps.API_2.utils

The utils module contains utility classes used by other modules.

14.6.1. Detailed documentation

STEPS Parameters

steps.API_2.utils.Parameter

steps.API_2.utils.ExportParameters()

Utility classes

steps.API_2.utils.NamedObject

steps.API_2.utils.Params

Options

steps.API_2.utils.SetVerbosity()

class Parameter(value, units=None, name=None, **kwargs)[source]

Bases:

Class to describe a parameter in a STEPS script

This class allows the user to declare values as parameters of the script. Parameter objects can have units (see example below) and are used to create STEPS objects or to set some of their properties. Declaring Parameter objects makes it possible for the user to do automatic unit conversions and to give a name to a parameter that is used with several STEPS objects. When parameter tables are automatically generated using ExportParameters(), the informations that the user supplied to the Parameter objects will be displayed in the tables.

Parameters

value (Any but will mostly be used with float) – The value of the parameter
units (str) – A string describing the unit of the parameter (see below for more explanations). If it is not supplied, the parameter will infer its units when used with a STEPS object.
name (str) – A user-supplied name for the parameter. If it is not given, the Parameter object will try to take its name from the name of the variable it is assigned to.
**kwargs – Keyword arguments that will be displayed in parameter tables.

Usage:

k_on  = Parameter(2, 'uM^-1 s^-1')
k_off = Parameter(1, 's^-1', comment='Comment about the k_off parameter')

...

with mdl, vsys:
    SA + SB <r[1]> SC
    r[1].K = k_on, k_off

In the above example, k_on will internally be converted to the appropriate STEPS unit (M^-1 s^-1) and both k_on and k_off will appear in the parameter tables generated from ExportParameters() with their name and associated units. In addition, any other keyword arguments (comment=... here) will also be shown in the parameter tables.

When given to a STEPS object, if a Parameter is declared with a unit, a test will be performed to check whether the given unit is of the expected physical dimension. If not, an exception will be raised. It is thus good practise to specify the units of parameters as a sanity check.

Note that Parameters can be combined using standard arithmetic operators +, -, *, /, ** (see Parameter.__add__(), etc.) to create new Parameters. These operations will then be visible in the exported parameter tables (see ExportParameters()).

Warning

Converting between units should be done by calling the convertTo() method. For example, to convert a Parameter in V to mV, one should use:

pot = Parameter(-0.07, 'V')
potInmV = pot.convertTo('mV')

One should never use arithmetic operations like pot * 1e3 which would yield a parameter of -70 V instead.

Finally, note that when a Parameter is explicitely converted to a number, it will yield its value in SI units:

>>> pot = Parameter(-70, 'mV')
>>> float(pot)
-0.07

Units specification:

The string that specifies the units should be composed of physical units (see available units below) optionally raised to some integer power and optionally prefixed with a scale ('u' for micro, 'k' for kilo, etc. see list below).

Examples:
'mm^2'               # Square millimeters
'uM^-1 s^-1'         # Per micromolar per second
'(mol m^-2)^-1 s^-1' # Per (moles per square meters) per second
'mV'                 # Millivolts
Note that groups of units can be wrapped in parentheses and raised to a power. This enhances the readability of some units. Reaction rates for surface-surface reactions of order 2 thus have units of '(mol m^-2)^-1 s^-1' which is equivalent to 'mol^-1 m^2 s^-1' but the former makes it clear that a surface ‘concentration’ is involved.

Available prefixes:

Prefix

Name

Base 10

'Y'

yotta-

10²⁴

'Z'

zetta-

10²¹

'E'

exa-

10¹⁸

'P'

peta-

10¹⁵

'T'

tera-

10¹²

'G'

giga-

10⁹

'M'

mega-

10⁶

'k'

kilo-

10³

'h'

hecto-

10²

'da'

deca-

10¹

''

10⁰

'd'

deci-

10^-1

'c'

centi-

10^-2

'm'

milli-

10^-3

'u'

micro-

10^-6

'n'

nano-

10^-9

'p'

pico-

10^-12

'f'

femto-

10^-15

'a'

atto-

10^-18

'z'

zepto-

10^-21

'y'

yocto-

10^-24

Available units:

Unit

Name

Quantity

's'

second

time

'm'

meter

length

'g'

gram

mass

'A'

ampere

electric current

'K'

kelvin

thermodynamic temperature

'mol'

mole

amount of substance

'cd'

candela

luminous intensity

'V'

volt

electrical potential difference

'F'

farad

capacitance

'ohm'

ohm

electrical resistance

'S'

siemens

electrical conductance

'L'

litre

volume

'M'

molar

concentration (mol L^-1)

'C'

coulomb

electric charge

'J'

joule

energy, work, heat

property name

Name of the parameter

Type: str, read-only

property value

Value of the parameter (in its units)

Type: Any (usually float), read-only

property units

Units of the parameter

Type: Union[str, None], read-only

convertTo(unit)[source]

Convert a parameter to the specified unit

Parameters: unit (str) – The unit to be converted to, it needs to be compatible with the units of the parameter.
Returns: The converted parameter.
Return type: Parameter

__getattr__(name)[source]

Access properties of the parameter as if they were attributes

Keywords arguments passed to the constructor of Parameter can then be accessed as if they were attributes:

>>> k_on = Parameter(2, 'uM^-1 s^-1', comment='Comment about k_on')
>>> k_on.comment
'Comment about k_on'

Note that the properties can only be defined at object creation and are all read-only.

__add__(other)[source]

Add Parameters with the + operator

Parameters: other (Union[Parameter, float]) – The other Parameter or a number
Returns: The Parameter resulting from the addition of both operands. If both operands are Parameters, the units of the result matches the units of the leftmost named parameter. If one operand is a number, it implicitely takes the units of the other operand. The name of the returned Parameter describes the operation.
Return type: Parameter

Usage:

>>> param1 = Parameter(1, 'uM s^-1')
>>> param2 = Parameter(2, 'nM ms^-1')
>>> param3 = param1 + param2
>>> param3.units
'uM s^-1'
>>> param3.value
3
>>> param3.name
'param1 + param2'

__sub__(other)[source]

Subtract Parameters with the - operator

Parameters: other (Union[Parameter, float]) – The other Parameter or a number
Returns: The Parameter resulting from the subtraction of both operands. If both operands are Parameters, the units of the result matches the units of the leftmost named parameter. If one operand is a number, it implicitely takes the units of the other operand. The name of the returned Parameter describes the operation.
Return type: Parameter

Usage:

>>> param1 = Parameter(1, 'uM')
>>> param2 = Parameter(100, 'nM')
>>> param3 = param1 - param2
>>> param3.units
'uM'
>>> param3.value
0.9
>>> param3.name
'param1 - param2'

__mul__(other)[source]

Multiply Parameters with the * operator

Parameters: other (Union[Parameter, float]) – The other Parameter or a number
Returns: The Parameter resulting from the multiplication of both operands. If both operands are Parameters, the units of the result consists in the product of the units of the operands. If one operand is a number, it is implicitely treated as dimensionless. The name of the returned Parameter describes the operation.
Return type: Parameter

Usage:

>>> param1 = Parameter(1, 'uM')
>>> param2 = Parameter(5, 's^-1')
>>> param3 = param1 * param2
>>> param3.units
'uM s^-1'
>>> param3.value
5
>>> param3.name
'param1 * param2'

__truediv__(other)[source]

Divide Parameters with the / operator

Parameters: other (Union[Parameter, float]) – The other Parameter or a number
Returns: The Parameter resulting from the division of both operands. If both operands are Parameters, the units of the result consists in the division of the units of the operands. If one operand is a number, it is implicitely treated as dimensionless. The name of the returned Parameter describes the operation.
Return type: Parameter

Usage:

>>> param1 = Parameter(1, 'uM')
>>> param2 = Parameter(5, 's')
>>> param3 = param1 / param2
>>> param3.units
'uM s^-1'
>>> param3.value
0.2
>>> param3.name
'param1 / param2'

__pow__(power)[source]

Raise to an integer power with the ** operator

Parameters: power (int) – The integer power
Returns: The Parameter resulting from raising self to the given power. The units of the result are the units of self raised to power. The name of the returned Parameter describes the operation.
Return type: Parameter

Usage:

>>> param1 = Parameter(2, 'um')
>>> param2 = param1 ** 3
>>> param2.units
'um^3'
>>> param2.value
8
>>> param2.name
'param1 ** 3'

__round__(ndigits=None)[source]

Round parameter value in SI

Parameters: ndigits (int) – Optional, number of digits after the decimal point, defaults to None (i.e. rounds to nearest integer).
Returns: The Parameter resulting from the rounding to ndigits digits. When rounding a parameter, its value is first converted to SI and the SI value is rounded. The returned parameter keeps the same units. The name of the returned Parameter describes the operation.
Return type: Parameter

Usage:

>>> param1 = Parameter(12.7, 'dm')
>>> param2 = round(param1)
>>> param2.units # The units are unchanged
'dm'
>>> param2.value # 12.7 dm is first converted to 1.27 m and rounded to 1 m = 10 dm
10
>>> param2.name
'round(param1)'
>>> round(param1, 1).value # Keep more digits: 1.27 m rounded to 1.3 m = 13 dm
13.0

__neg__()[source]

Unary negative operator

Returns: The Parameter resulting from multiplication of its value by -1.
Return type: Parameter

Usage:

>>> param1 = Parameter(2, 'mV')
>>> param2 = -param1
>>> param2.units
'mV'
>>> param2.value
-2
>>> param2.name
'-param1'

ExportParameters(container, filename, method='csv', hideComputations=False, hideColumns=[], unitsToSimplify=[], **kwargs)[source]

Export container parameters to tables

Extracts all parameters that are used in the container and its contained objects. Parameter tables are then created for each object type.

Parameters

container (Any STEPS object) – The container whose parameters are going to be exported. Most of the time, this will be the steps.API_2.sim.Simulation object.
filename (str) – Path and prefix for the exported table files (e.g. ‘./parameter/Sim1’ would yield files like ‘./parameter/Sim1_Parameters.csv’, etc.).
method (str) – Specify which file format should be used. Available options are ‘csv’, ‘tex’, and ‘pdf’.
hideComputations (bool) – If true, arithmetic combinations of parameters will not be displayed in the tables.
hideColumns (List[str]) – List of column names that should not be displayed in the tables.
unitsToSimplify (List[str]) – List of units that should always be displayed in this specific way if equivalent units appear in the table. For example, some surface reaction rate constants are better expressed as ‘(mol m^-2)^-1 s^-1’ so we would give this string in the list to avoid seeing e.g. ‘mol^-1 m^2 s^-1’ (which is equivalent but harder to read) in the parameter tables.
**kwargs – Additional keyword arguments specified below.

Keyword arguements depend on the method used but some of them are common to all methods.

Common additional keyword arguments:

Parameters

numPrecision (int) – Number of significant digits to be displayed for floating point numbers.
funcRelFilePath (bool) – Use relative file path for specifying the source file of a function that is used in a parameter. Defaults to True.

The ‘csv’ export method will export parameters as tab-separated values in a text file. Since some cells can contain commas, the separator has been chosen to be tabs instead of the more common comma.

Additional keyword arguments for the ‘csv’ format:

Parameters: textFormat (str) – Either ‘unicode’ or ‘latex’, defaults to ‘unicode’. ‘latex’ will introduce latex formating in the cells, in case other csv to latex conversion programs need to be used.

Both the ‘tex’ and ‘pdf’ export methods are experimental. The ‘tex’ method will export the parameters to independent .tex files each containing one table. It requires the installation of the csv2latex conversion program. The ‘pdf’ method will simply call pdflatex on the tex files resulting from the ‘tex’ method.

Additional keyword arguments for the ‘tex’ and ‘pdf’ formats:

Parameters

csv2latexArgs (str) – A string of command line arguments to be passed to csv2latex, see the manual page for details. Defaults to -l 99999 -s t -x -r 2 -z -c 0.9 -e
latexPrefix (str) – If provided, special latex character will not be escaped for strings that are prefixed with latexPrefix. For example, if we specified a Source = ‘cite{ArticleRef}’ keyword argument to a Parameter object, the { and } characters will be escaped by default. This can be prevented by using e.g. latexPrefix=’__’ and Source = ‘__cite{ArticleRef}’.

class NamedObject(*args, name=None, **kwargs)[source]

Bases:

Base class for all objects that are named and can have children

Parameters: name (str) – Name of the object. If no name is provided, the object gets an automatically generated name based on its class.

All classes that inherit from NamedObject can be built with a name keyword parameter. For steps objects, it corresponds to the identifiers used in STEPS. Note that some names are forbidden because they correspond to names of attributes or methods of classes defined in this interface. Since most objects implement __getattr__ attribute style access to children, the names of these methods / attributes could clash with object names. It is thus possible that the contructor of NamedObject raises an exception when trying to name an object with one of these forbidden names.

In addition to a name, this class holds a list of children objects that can be accessed with __getattr__() and ALL().

Note

This class should not be instantiated by the user, it is only documented for clarity since a lot of other classes inherit from it.

__getattr__(name)[source]

Access children of the objects as if they were attributes

See NamedObject and Create() for details on object naming. Assuming the object has a children named ‘child1’, one can access it as if it was an attribute of the object:

obj.child1

ALL(*cls)[source]

Return all children of the object, optionally filtered by class

Takes a variable number of parameters, if no parameters are given, it returns all children of the object. Otherwise, if types are given, it returns the children that match at least one of the given types.

Parameters: *cls – Variable number of classes
Returns: A generator that iterates over all children that match the class criteria.
Return type: Generator[NamedObject]

Usage:

obj.ALL()                    # Return all children
obj.ALL(Species)             # Return all children Species
obj.ALL(Reaction, Diffusion) # Return all children that are either Reaction or
                             # Diffusion

classmethod Create(*args, **kwargs)[source]

Auto naming syntax for simplifying the creation of named objects

Create one or several objects of class cls with a list of arguments and name them automatically based on the name of the variables they are going to be assigned to.

Usage without arguments:

a, b, c = Class.Create()

# Equivalent to:

a, b, c = Class(name = 'a'), Class(name = 'b'), Class(name = 'c')

Usage with single arguments:

a, b, c = Class.Create(argA, argB, argC)

# Equivalent to:

a, b, c = Class(argA, name = 'a'), Class(argB, name = 'b'), Class(argC, name = 'c')

Usage with variable numbers of arguments:

a, b, c = Class.Create(argA, Params(argB1, argB2), Params(argC1, nargC2 = val))

# Equivalent to:

a, b, c = Class(argA, name = 'a'),\
          Class(argB1, argB2, name = 'b'),\
          Class(argC1, nargC2 = val, name = 'c')

Note that if a name keyword argument is provided to Params(…), it will override the name inferred from the destination variable.

Usage with global keyword argument:

a, b, c = Class.Create(argA, argB, argC, gkwarg=val)

# Equivalent to:

a, b, c = Class(argA, gkwarg=val, name = 'a'),\
          Class(argB, gkwarg=val, name = 'b'),\
          Class(argC, gkwarg=val, name = 'c')

Warning

This automatic naming syntax works by reading the source file to extract the name of the variables. Because of this, modifying the source of a script while it is running is highly discouraged if the automatic naming syntax is used. Notably, this synatx WILL NOT work in an interactive python shell, in which there is no source file to parse. It WILL work as expected in a jupyter notebook.

class Params(*args, **kwargs)[source]

Bases:

Container class for grouping arguments

SetVerbosity(v)[source]

Set verbosity to the specified level.

Parameters: v (int) – Verbosity level

The higher the vebosity, the more messages are displayed on standard output.