Skip to content

Commit 5fa0f1f

Browse files
dweindldilpath
dweindl
and
dilpath
committed
Specification of math expressions (#579)
Previously, the math expression syntax wasn't specified. This was very problematic, because different libraries and programming languages have different names for the same functions, and more importantly, differ in operator precedence. Co-authored-by: Dilan Pathirana <59329744+dilpath@users.noreply.github.com> Co-authored-by: dilpath <dilan.private+github@outlook.com>
1 parent c2bb990 commit 5fa0f1f

File tree

3 files changed

+463
-4
lines changed

3 files changed

+463
-4
lines changed

‎doc/documentation_data_format.rst‎

Lines changed: 357 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -154,10 +154,10 @@ Detailed field description
154154
- ``${speciesId}``
155155

156156
If a species ID is provided, it is interpreted as the initial
157-
condition of that species (as amount if `hasOnlySubstanceUnits` is set to `True`
158-
for the respective species, as concentration otherwise) and will override the
157+
condition of that species (as amount if `hasOnlySubstanceUnits` is set to `True`
158+
for the respective species, as concentration otherwise) and will override the
159159
initial condition given in the SBML model or given by a preequilibration
160-
condition. If ``NaN`` is provided for a condition, the result of the
160+
condition. If no value is provided for a condition, the result of the
161161
preequilibration (or initial condition from the SBML model, if
162162
no preequilibration is defined) is used.
163163

@@ -259,7 +259,7 @@ Detailed field description
259259

260260
- ``noiseParameters`` [NUMERIC, STRING OR NULL, OPTIONAL]
261261

262-
The measurement standard deviation or ``NaN`` if the corresponding sigma is a
262+
The measurement standard deviation or empty if the corresponding sigma is a
263263
model parameter.
264264

265265
Numeric values or parameter names are allowed. Same rules apply as for
@@ -741,3 +741,356 @@ allows to specify multiple SBML models with corresponding condition and
741741
measurement tables, and one joint parameter table. This means that the parameter
742742
namespace is global. Therefore, parameters with the same ID in different models
743743
will be considered identical.
744+
745+
746+
Math expressions syntax
747+
-----------------------
748+
749+
This section describes the syntax of math expressions used in PEtab files, such
750+
as the observable formulas.
751+
752+
Supported symbols, literals, and operations are described in the following. Whitespace is ignored in math expressions.
753+
754+
755+
Symbols
756+
~~~~~~~
757+
758+
* The supported identifiers are:
759+
760+
* parameter IDs from the parameter table
761+
* model entity IDs that are globally unique and have a clear interpretation
762+
in the math expression context
763+
* observable IDs from the observable table
764+
* PEtab placeholder IDs in the observable and noise formulas
765+
* PEtab entity IDs in the mapping table
766+
* ``time`` for the model time
767+
* PEtab function names listed below
768+
769+
Identifiers are not supported if they do not match the PEtab identifier
770+
format. PEtab expressions may have further context-specific restrictions on
771+
supported identifiers.
772+
773+
* The functions defined in PEtab are tabulated below. Other functions,
774+
including those defined in the model, remain undefined in PEtab expressions.
775+
776+
* Special symbols (such as :math:`e` and :math:`\pi`) are not supported, and
777+
neither is NaN (not-a-number).
778+
779+
Model time
780+
++++++++++
781+
782+
The model time is represented by the symbol ``time``, which is the current
783+
simulated time, not the current duration of simulated time; if the simulation
784+
starts at :math:`t_0 \neq 0`, then ``time`` is *not* the time since
785+
:math:`t_0`.
786+
787+
788+
Literals
789+
~~~~~~~~
790+
791+
Numbers
792+
+++++++
793+
794+
All numbers, including integers, are treated as floating point numbers of
795+
undefined precision (although no less than double precision should be used.
796+
Only decimal notation is supported. Scientific notation
797+
is supported, with the exponent indicated by ``e`` or ``E``. The decimal
798+
separator is indicated by ``.``.
799+
Examples of valid numbers are: ``1``, ``1.0``, ``-1.0``, ``1.0e-3``, ``1.0e3``,
800+
``1e+3``. The general syntax in PCRE2 regex is ``\d*(\.\d+)?([eE][-+]?\d+)?``.
801+
``inf`` and ``-inf`` are supported as positive and negative infinity.
802+
803+
Booleans
804+
++++++++
805+
806+
Boolean literals are ``true`` and ``false``.
807+
808+
809+
Operations
810+
~~~~~~~~~~
811+
812+
Operators
813+
+++++++++
814+
815+
The supported operators are:
816+
817+
.. list-table:: Supported operators in PEtab math expressions.
818+
:header-rows: 1
819+
820+
* - Operator
821+
- Precedence
822+
- Interpretation
823+
- Associativity
824+
- Arguments
825+
- Evaluates to
826+
* - ``f(arg1[, arg2, ...])``
827+
- 1
828+
- call to function `f` with arguments `arg1`, `arg2`, ...
829+
- left-to-right
830+
- any
831+
- input-dependent
832+
* - | ``()``
833+
|
834+
- | 1
835+
|
836+
- | parentheses for grouping
837+
| acts like identity
838+
- |
839+
|
840+
- | any single expression
841+
|
842+
- | argument
843+
|
844+
* - | ``^``
845+
|
846+
- | 2
847+
|
848+
- | exponentiation
849+
| (shorthand for pow)
850+
- | right-to-left
851+
|
852+
- | float, float
853+
|
854+
- | float
855+
|
856+
* - | ``+``
857+
| ``-``
858+
- | 3
859+
- | unary plus
860+
| unary minus
861+
- | right-to-left
862+
- | float
863+
- | float
864+
* - ``!``
865+
- 3
866+
- not
867+
-
868+
- bool
869+
- bool
870+
* - | ``*``
871+
| ``/``
872+
- | 4
873+
- | multiplication
874+
| division
875+
- | left-to-right
876+
- | float, float
877+
- | float
878+
* - | ``+``
879+
| ``-``
880+
- | 5
881+
- | binary plus, addition
882+
| binary minus, subtraction
883+
- | left-to-right
884+
- | float, float
885+
- | float
886+
* - | ``<``
887+
| ``<=``
888+
| ``>``
889+
| ``>=``
890+
- | 6
891+
- | less than
892+
| less than or equal to
893+
| greater than
894+
| greater than or equal to
895+
- | left-to-right
896+
- | float, float
897+
- | bool
898+
* - | ``==``
899+
| ``!=``
900+
- | 6
901+
- | is equal to
902+
| is not equal to
903+
- | left-to-right
904+
- | (float, float) or (bool, bool)
905+
- | bool
906+
* - | ``&&``
907+
| ``||``
908+
- | 7
909+
- | logical `and`
910+
| logical `or`
911+
- | left-to-right
912+
- | bool, bool
913+
- | bool
914+
* - ``,``
915+
- 8
916+
- function argument separator
917+
- left-to-right
918+
- any
919+
-
920+
921+
Note that operator precedence might be unexpected, compared to other programming
922+
languages. Use parentheses to enforce the desired order of operations.
923+
924+
Operators must be specified; there are no implicit operators.
925+
For example, ``a b`` is invalid, unlike ``a * b``.
926+
927+
Functions
928+
+++++++++
929+
930+
The following functions are supported:
931+
932+
..
933+
START TABLE Supported functions (GENERATED, DO NOT EDIT, INSTEAD EDIT IN PEtab/doc/src)
934+
.. list-table:: Supported functions
935+
:header-rows: 1
936+
937+
* - | Function
938+
- | Comment
939+
- | Argument types
940+
- | Evaluates to
941+
* - ``pow(a, b)``
942+
- power function `b`-th power of `a`
943+
- float, float
944+
- float
945+
* - ``exp(x)``
946+
- | exponential function pow(e, x)
947+
| (`e` itself not a supported symbol,
948+
| but ``exp(1)`` can be used instead)
949+
- float
950+
- float
951+
* - ``sqrt(x)``
952+
- | square root of ``x``
953+
| ``pow(x, 0.5)``
954+
- float
955+
- float
956+
* - | ``log(a, b)``
957+
| ``log(x)``
958+
| ``ln(x)``
959+
| ``log2(x)``
960+
| ``log10(x)``
961+
- | logarithm of ``a`` with base ``b``
962+
| ``log(x, e)``
963+
| ``log(x, e)``
964+
| ``log(x, 2)``
965+
| ``log(x, 10)``
966+
| (``log(0)`` is defined as ``-inf``)
967+
| (NOTE: ``log`` without explicit
968+
| base is ``ln``, not ``log10``)
969+
- float[, float]
970+
- float
971+
* - | ``sin``
972+
| ``cos``
973+
| ``tan``
974+
| ``cot``
975+
| ``sec``
976+
| ``csc``
977+
- trigonometric functions
978+
- float
979+
- float
980+
* - | ``arcsin``
981+
| ``arccos``
982+
| ``arctan``
983+
| ``arccot``
984+
| ``arcsec``
985+
| ``arccsc``
986+
- inverse trigonometric functions
987+
- float
988+
- float
989+
* - | ``sinh``
990+
| ``cosh``
991+
| ``tanh``
992+
| ``coth``
993+
| ``sech``
994+
| ``csch``
995+
- hyperbolic functions
996+
- float
997+
- float
998+
* - | ``arcsinh``
999+
| ``arccosh``
1000+
| ``arctanh``
1001+
| ``arccoth``
1002+
| ``arcsech``
1003+
| ``arccsch``
1004+
- inverse hyperbolic functions
1005+
- float
1006+
- float
1007+
* - | ``piecewise(``
1008+
| ``true_value_1,``
1009+
| ``condition_1,``
1010+
| ``[true_value_2,``
1011+
| ``condition_2,]``
1012+
| ``[...]``
1013+
| ``[true_value_n,``
1014+
| ``condition_n,]``
1015+
| ``otherwise``
1016+
| ``)``
1017+
- | The function value is
1018+
| the ``true_value*`` for the
1019+
| first ``true`` ``condition*``
1020+
| or ``otherwise`` if all
1021+
| conditions are ``false``.
1022+
- | ``*value*``: all float or all bool
1023+
| ``condition*``: all bool
1024+
- float
1025+
* - ``abs(x)``
1026+
- | absolute value
1027+
| ``piecewise(x, x>=0, -x)``
1028+
- float
1029+
- float
1030+
* - ``sign(x)``
1031+
- | sign of ``x``
1032+
| ``piecewise(1, x > 0, -1, x < 0, 0)``
1033+
- float
1034+
- float
1035+
* - | ``min(a, b)``
1036+
| ``max(a, b)``
1037+
- | minimum / maximum of {``a``, ``b``}
1038+
| ``piecewise(a, a<=b, b)``
1039+
| ``piecewise(a, a>=b, b)``
1040+
- float, float
1041+
- float
1042+
1043+
..
1044+
END TABLE Supported functions
1045+
1046+
1047+
Boolean <-> float conversion
1048+
++++++++++++++++++++++++++++
1049+
1050+
Boolean and float values are implicitly convertible. The following rules apply:
1051+
1052+
bool -> float: ``true`` is converted to ``1.0``, ``false`` is converted to
1053+
``0.0``.
1054+
1055+
float -> bool: ``0.0`` is converted to ``false``, all other values are
1056+
converted to ``true``.
1057+
1058+
Operands and function arguments are implicitly converted as needed. If there is
1059+
no signature compatible with the given types, Boolean
1060+
values are promoted to float. If there is still no compatible signature,
1061+
float values are demoted to boolean values. For example, in ``1 + true``,
1062+
``true`` is promoted to ``1.0`` and the expression is interpreted as
1063+
``1.0 + 1.0 = 2.0``, whereas in ``1 && true``, ``1`` is demoted to ``true`` and
1064+
the expression is interpreted as ``true && true = true``.
1065+
1066+
1067+
Identifiers
1068+
-----------
1069+
1070+
* All identifiers in PEtab may only contain upper and lower case letters,
1071+
digits and underscores, and must not start with a digit. In PCRE2 regex, they
1072+
must match ``[a-zA-Z_][a-zA-Z_\d]*``.
1073+
1074+
* Identifiers are case-sensitive.
1075+
1076+
* Identifiers must not be a reserved keyword (see below).
1077+
1078+
* Identifiers must be globally unique within the PEtab problem.
1079+
PEtab math function names must not be used as identifiers for other model
1080+
entities. PEtab does not put any further restrictions on the use of
1081+
identifiers within the model, which means modelers could potentially
1082+
use model-format--specific (e.g. SBML) function names as identifiers.
1083+
However, this is strongly discouraged.
1084+
1085+
Reserved keywords
1086+
~~~~~~~~~~~~~~~~~
1087+
1088+
The following keywords, `case-insensitive`, are reserved and must not be used
1089+
as identifiers:
1090+
1091+
* ``true``, ``false``: Boolean literals, used in PEtab expressions.
1092+
* ``inf``: Infinity, used in PEtab expressions and post-equilibration
1093+
measurements
1094+
* ``time``: Model time, used in PEtab expressions.
1095+
* ``nan``: Undefined in PEtab, but reserved to avoid implementation issues.
1096+

‎doc/src/Supported functions.tsv‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
Function Comment Argument types Evaluates to
2+
``pow(a, b)`` power function `b`-th power of `a` float, float float
3+
``exp(x)`` exponential function pow(e, x);(`e` itself not a supported symbol,;but ``exp(1)`` can be used instead) float float
4+
``sqrt(x)`` square root of ``x``;``pow(x, 0.5)`` float float
5+
``log(a, b)``;``log(x)``;``ln(x)``;``log2(x)``;``log10(x)`` logarithm of ``a`` with base ``b``;``log(x, e)``;``log(x, e)``;``log(x, 2)``;``log(x, 10)``;(``log(0)`` is defined as ``-inf``);(NOTE: ``log`` without explicit;base is ``ln``, not ``log10``) float[, float] float
6+
``sin``;``cos``;``tan``;``cot``;``sec``;``csc`` trigonometric functions float float
7+
``arcsin``;``arccos``;``arctan``;``arccot``;``arcsec``;``arccsc`` inverse trigonometric functions float float
8+
``sinh``;``cosh``;``tanh``;``coth``;``sech``;``csch`` hyperbolic functions float float
9+
``arcsinh``;``arccosh``;``arctanh``;``arccoth``;``arcsech``;``arccsch`` inverse hyperbolic functions float float
10+
``piecewise(``; ``true_value_1,``; ``condition_1,``; ``[true_value_2,``; ``condition_2,]``; ``[...]``; ``[true_value_n,``; ``condition_n,]``; ``otherwise``;``)`` The function value is;the ``true_value*`` for the;first ``true`` ``condition*``;or ``otherwise`` if all;conditions are ``false``. ``*value*``: all float or all bool;``condition*``: all bool float
11+
``abs(x)`` absolute value;``piecewise(x, x>=0, -x)`` float float
12+
``sign(x)`` sign of ``x``;``piecewise(1, x>=0, -1)`` float float
13+
``min(a, b)``;``max(a, b)`` minimum / maximum of {``a``, ``b``};``piecewise(a, a<=b, b)``;``piecewise(a, a>=b, b)`` float, float float

0 commit comments

Comments
 (0)