ode2tn 1.0.0__py3-none-any.whl

ode2tn/__init__.py

@@ -0,0 +1 @@
+from ode2tn.transform import *

ode2tn/transform.py

@@ -0,0 +1,384 @@
+from typing import Any, Iterable
+import re
+from typing import Callable
+
+from scipy.integrate import OdeSolver
+import gpac as gp
+import sympy as sp
+from scipy.integrate._ivp.ivp import OdeResult  # noqa
+
+
+def plot_tn(
+        odes: dict[sp.Symbol | str, sp.Expr | str | float],
+        initial_values: dict[sp.Symbol | str, float],
+        t_eval: Iterable[float] | None = None,
+        *,
+        gamma: float,
+        beta: float,
+        scale: float = 1.0,
+        t_span: tuple[float, float] | None = None,
+        resets: dict[float, dict[sp.Symbol | str, float]] | None = None,
+        dependent_symbols: dict[sp.Symbol | str, sp.Expr | str] | None = None,
+        figure_size: tuple[float, float] = (10, 3),
+        symbols_to_plot: Iterable[sp.Symbol | str] |
+                         Iterable[Iterable[sp.Symbol | str]] |
+                         str |
+                         re.Pattern |
+                         Iterable[re.Pattern] |
+                         None = None,
+        show: bool = False,
+        method: str | OdeSolver = 'RK45',
+        dense_output: bool = False,
+        events: Callable | Iterable[Callable] | None = None,
+        vectorized: bool = False,
+        return_ode_result: bool = False,
+        args: tuple | None = None,
+        loc: str | tuple[float, float] = 'best',
+        **options,
+) -> OdeResult | None:
+    """
+    Plot transcription network (TN) ODEs and initial values.
+
+    For arguments other than odes, initial_values, gamma, and beta, see the documentation for
+    `plot` in the gpac library.
+
+    Args:
+        odes: polynomial ODEs,
+            dict of sp symbols or strings (representing symbols) to sympy expressions or strings or floats
+            (representing RHS of ODEs)
+            Raises ValueError if any of the ODEs RHS is not a polynomial
+        initial_values: initial values,
+            dict of sympy symbols or strings (representing symbols) to floats
+        gamma: coefficient of the negative linear term in the transcription network
+        beta: additive constant in x_top ODE
+        scale: "scaling factor" for the transcription network ODEs. Each variable `x` is replaced by a pair
+            (`x_top`, `x_bot`). The initial `x_bot` value is `scale`, and the initial `x_top` value is
+            `x*scale`.
+        resets:
+            If specified, this is a dict mapping times to "configurations"
+            (i.e., dict mapping symbols/str to values).
+            The configurations are used to set the values of the symbols manually during the ODE integration
+            at specific times.
+            Any symbols not appearing as keys in `resets` are left at their current values.
+            The keys can either represent the `x_top` or `x_bot` variables whose ratio represents the original variable
+            (a key in parameter `odes`), or the original variables themselves.
+            If a new `x_top` or `x_bot` variable is used, its value is set directly.
+            If an original variable `x` is used, its then the `x_top` and `x_bot` variables are set
+            as with transforming `inits` to `tn_inits` in `ode2tn`:
+            `x_top` is set to `x*scale`, and `x_bot` is set to `scale`.
+            The OdeResult returned (the one returned by `solve_ivp` in scipy) will have two additional fields:
+            `reset_times` and `reset_indices`, which are lists of the times and indices in `sol.t`
+            corresponding to the times when the resets were applied.
+            Raises a ValueError if any time lies outside the integration interval, or if `resets` is empty,
+            if a symbol is invalid, or if there are symbols representing both an original variable `x` and one of
+            its `x_top` or `x_bot` variables.
+
+    Returns:
+        Typically None, but if return_ode_result is True, returns the result of the ODE integration.
+        See documentation of `gpac.plot` for details.
+    """
+    tn_odes, tn_inits, tn_ratios = ode2tn(odes, initial_values, gamma=gamma, beta=beta, scale=scale)
+    dependent_symbols_tn = dict(dependent_symbols) if dependent_symbols is not None else {}
+    dependent_symbols_tn.update(tn_ratios)
+    symbols_to_plot = dependent_symbols_tn if symbols_to_plot is None else symbols_to_plot
+
+    if resets is not None:
+        # make copy since we are going to change it
+        new_resets = {}
+        for time, reset in resets.items():
+            new_resets[time] = {}
+            for x, val in reset.items():
+                new_resets[time][x] = val
+        resets = new_resets
+        # normalize resets keys and check that variables are valid
+        for reset in resets.values():
+            for x, val in reset.items():
+                if isinstance(x, str):
+                    del reset[x]
+                    x = sp.symbols(x)
+                    reset[x] = val
+                if x not in odes.keys() and x not in tn_odes.keys():
+                    raise ValueError(f"Symbol {x} not found in original variables: {', '.join(odes.keys())},\n"
+                                     f"nor found in transcription network variables: {', '.join(tn_odes.keys())}")
+            # ensure if original variable x is in resets, then neither x_top nor x_bot are in the resets
+            # and substitute x_top and x_bot for x in resets
+            for x, ratio in tn_ratios.items():
+                # x is an original; so make sure neither x_top nor x_bot are in the reset dict
+                if x in reset:
+                    xt,xb = sp.fraction(ratio)
+                    if xt in reset:
+                        raise ValueError(f'Cannot use "top" variable {xt} in resets '
+                                         f'if original variable {x} is also used')
+                    if xb in reset:
+                        raise ValueError(f'Cannot use "bottom" variable {xb} in resets '
+                                         f'if original variable {x} is also used')
+                    reset[xt] = reset[x] * scale
+                    reset[xb] = scale
+                    del reset[x]
+
+    return gp.plot(
+        odes=tn_odes,
+        initial_values=tn_inits,
+        t_eval=t_eval,
+        t_span=t_span,
+        dependent_symbols=dependent_symbols_tn,
+        resets=resets,
+        figure_size=figure_size,
+        symbols_to_plot=symbols_to_plot,
+        show=show,
+        method=method,
+        dense_output=dense_output,
+        events=events,
+        vectorized=vectorized,
+        return_ode_result=return_ode_result,
+        args=args,
+        loc=loc,
+        **options,
+    )
+
+
+def ode2tn(
+        odes: dict[sp.Symbol | str, sp.Expr | str | float],
+        initial_values: dict[sp.Symbol | str, float],
+        *,
+        gamma: float,
+        beta: float,
+        scale: float = 1.0,
+) -> tuple[dict[sp.Symbol, sp.Expr], dict[sp.Symbol, float], dict[sp.Symbol, sp.Expr]]:
+    """
+    Maps polynomial ODEs and and initial values to transcription network (represented by ODEs with positive
+    Laurent polynomials and negative linear term) simulating it, as well as initial values.
+
+    Args:
+        odes: polynomial ODEs,
+            dict of sympy symbols or strings (representing symbols) to sympy expressions or strings or floats
+            (representing RHS of ODEs)
+            Raises ValueError if any of the ODEs RHS is not a polynomial
+        initial_values: initial values,
+            dict of sympy symbols or strings (representing symbols) to floats
+        gamma: coefficient of the negative linear term in the transcription network
+        beta: additive constant in x_top ODE
+        scale: "scaling factor" for the transcription network ODEs. Each variable `x` is replaced by a pair
+            (`x_top`, `x_bot`). The initial `x_bot` value is `scale`, and the initial `x_top` value is
+            `x*scale`.
+
+    Return:
+        triple (`tn_odes`, `tn_inits`, `tn_ratios`), where `tn_ratios` is a dict mapping each original symbol ``x``
+        in the original ODEs to the sympy.Expr ``x_top / x_bot``.
+    """
+    # normalize initial values dict to use symbols as keys
+    initial_values = {sp.Symbol(symbol) if isinstance(symbol, str) else symbol: value
+                      for symbol, value in initial_values.items()}
+
+    # normalize odes dict to use symbols as keys
+    odes_symbols = {}
+    symbols_found_in_expressions = set()
+    for symbol, expr in odes.items():
+        if isinstance(symbol, str):
+            symbol = sp.symbols(symbol)
+        if isinstance(expr, (str, int, float)):
+            expr = sp.sympify(expr)
+        symbols_found_in_expressions.update(expr.free_symbols)
+        odes_symbols[symbol] = expr
+
+    # ensure that all symbols that are keys in `initial_values` are also keys in `odes`
+    initial_values_keys = set(initial_values.keys())
+    odes_keys = set(odes_symbols.keys())
+    diff = initial_values_keys - odes_keys
+    if len(diff) > 0:
+        raise ValueError(f"\nInitial_values contains symbols that are not in odes: "
+                         f"{comma_separated(diff)}"
+                         f"\nHere are the symbols of the ODES:                     "
+                         f"{comma_separated(odes_keys)}")
+
+    # ensure all symbols in expressions are keys in the odes dict
+    symbols_in_expressions_not_in_odes_keys = symbols_found_in_expressions - odes_keys
+    if len(symbols_in_expressions_not_in_odes_keys) > 0:
+        raise ValueError(f"Found symbols in expressions that are not keys in the odes dict: "
+                         f"{symbols_in_expressions_not_in_odes_keys}\n"
+                         f"The keys in the odes dict are: {odes_keys}")
+
+    # ensure all odes are polynomials
+    for symbol, expr in odes_symbols.items():
+        if not expr.is_polynomial():
+            raise ValueError(f"ODE for {symbol}' is not a polynomial: {expr}")
+
+    return normalized_ode2tn(odes, initial_values, gamma=gamma, beta=beta, scale=scale)
+
+
+def normalized_ode2tn(
+        odes: dict[sp.Symbol, sp.Expr],
+        initial_values: dict[sp.Symbol, float],
+        *,
+        gamma: float,
+        beta: float,
+        scale: float,
+) -> tuple[dict[sp.Symbol, sp.Expr], dict[sp.Symbol, float], dict[sp.Symbol, sp.Expr]]:
+    # Assumes ode2tn has normalized and done error-checking
+
+    sym2pair: dict[sp.Symbol, tuple[sp.Symbol, sp.Symbol]] = {}
+    tn_ratios: dict[sp.Symbol, sp.Expr] = {}
+    for x in odes.keys():
+        # create x_t, x_b for each symbol x
+        x_top, x_bot = sp.symbols(f'{x}_t {x}_b')
+        sym2pair[x] = (x_top, x_bot)
+        tn_ratios[x] = x_top / x_bot
+
+    tn_odes: dict[sp.Symbol, sp.Expr] = {}
+    tn_inits: dict[sp.Symbol, float] = {}
+    for x, expr in odes.items():
+        p_pos, p_neg = split_polynomial(expr)
+
+        # replace sym with sym_top / sym_bot for each original symbol sym
+        for sym in odes.keys():
+            sym_top, sym_bot = sym2pair[sym]
+            p_pos = p_pos.subs(sym, sym_top / sym_bot)
+            p_neg = p_neg.subs(sym, sym_top / sym_bot)
+
+        x_top, x_bot = sym2pair[x]
+        # tn_odes[x_top] = beta + p_pos * x_bot - gamma * x_top
+        # tn_odes[x_bot] = p_neg * x_bot ** 2 / x_top + beta * x_bot / x_top - gamma * x_bot
+        tn_odes[x_top] = beta * x_top / x_bot + p_pos * x_bot - gamma * x_top
+        tn_odes[x_bot] = beta + p_neg * x_bot ** 2 / x_top - gamma * x_bot
+        tn_inits[x_top] = initial_values[x]*scale
+        tn_inits[x_bot] = scale
+
+    return tn_odes, tn_inits, tn_ratios
+
+
+def split_polynomial(expr: sp.Expr) -> tuple[sp.Expr, sp.Expr]:
+    """
+    Split a polynomial into two parts:
+    p1: monomials with positive coefficients
+    p2: monomials with negative coefficients (made positive)
+
+    Args:
+        expr: A sympy Expression that is a polynomial
+
+    Returns:
+        pair of sympy Expressions (`p1`, `p2`) such that expr = p1 - p2
+
+    Raises:
+        ValueError: If `expr` is not a polynomial. Note that the constants (sympy type ``Number``)
+        are not considered polynomials by the ``is_polynomial`` method, but we do consider them polynomials
+        and do not raise an exception in this case.
+    """
+    if expr.is_constant():
+        if expr < 0:
+            return sp.S(0), -expr
+        else:
+            return expr, sp.S(0)
+
+    # Verify it's a polynomial
+    if not expr.is_polynomial():
+        raise ValueError(f"Expression {expr} is not a polynomial")
+
+    # Initialize empty expressions for positive and negative parts
+    p_pos = sp.S(0)
+    p_neg = sp.S(0)
+
+    # Convert to expanded form to make sure all terms are separate
+    expanded = sp.expand(expr)
+
+    # For a sum, we can process each term
+    if expanded.is_Add:
+        for term in expanded.args:
+            # Get the coefficient
+            if term.is_Mul:
+                # For products, find the numeric coefficient
+                coeff = next((arg for arg in term.args if arg.is_number), 1)
+            else:
+                # For non-products (like just x or just a number)
+                coeff = 1 if not term.is_number else term
+
+            # Add to the appropriate part based on sign
+            if coeff > 0:
+                p_pos += term
+            else:
+                # For negative coefficients, add the negated term to p2
+                p_neg += -term
+    elif expanded.is_Mul:
+        # If it's a single term, just check the sign; is_Mul for things like x*y or -x (represented as -1*x)
+        coeff = next((arg for arg in expanded.args if arg.is_number), 1)
+        if coeff > 0:
+            p_pos = expanded
+        else:
+            p_neg = -expanded
+    elif expanded.is_Atom:
+        # since negative terms are technically Mul, i.e., -1*x, if it is an atom then it is positive
+        p_pos = expanded
+    else:
+        # For single constant terms without multiplication, just check the sign;
+        # in tests a term like -x is actually represented as -1*x, so that's covered by the above elif,
+        # but in case of a negative constant like -2, this is handled here
+        if expanded > 0:
+            p_pos = expanded
+        else:
+            p_neg = -expanded
+
+    return p_pos, p_neg
+
+
+def comma_separated(elts: Iterable[Any]) -> str:
+    return ', '.join(str(elt) for elt in elts)
+
+
+def main():
+    x_sp, y_sp = gp.species('x y')
+    rxns = [
+        x_sp >> x_sp + y_sp,
+        (3 * y_sp | 2 * y_sp).k(11).r(16.5),
+        (y_sp >> gp.empty).k(6.5),
+    ]
+    odes = gp.crn_to_odes(rxns)
+    # extract symbols from odes
+    for var in odes.keys():
+        if var.name == 'x':
+            x = var
+        if var.name == 'y':
+            y = var
+    # for v,ode in odes.items():
+    #     print(f"{v}' = {ode}")
+    inits = {
+        x: 1,
+        y: 0.5,
+    }
+    gamma = 20
+    beta = 1
+    scale = 0.1
+    import numpy as np
+    t_eval = np.linspace(0, 20, 500)
+
+    tn_odes, tn_inits, tn_ratios = ode2tn(odes, inits, gamma=gamma, beta=beta, scale=scale)
+    for ratio_symbol in tn_inits.keys():
+        if ratio_symbol.name == 'x_t':
+            xt = ratio_symbol
+        if ratio_symbol.name == 'x_b':
+            xb = ratio_symbol
+        if ratio_symbol.name == 'y_t':
+            yt = ratio_symbol
+        if ratio_symbol.name == 'y_b':
+            yb = ratio_symbol
+    from IPython.display import display
+    for sym, expr in tn_odes.items():
+        print(f"{sym}' = ", end='')
+        display(sp.simplify(expr))
+    print(f'{tn_inits=}')
+    print(f'{tn_ratios=}')
+    # for var, val in tn_inits.items():
+    #     tn_inits[var] *= 0.1
+    # print(f'after reducing t/b values by 10x: {tn_inits=}')
+    figsize = (15, 6)
+    resets = {
+        5: {x: 0.5},
+        10: {x: 0.01},
+        15: {x: 0.5},
+    }
+    scale = 0.1
+    plot_tn(odes, inits, gamma=gamma, beta=beta, scale=scale,
+            t_eval=t_eval, resets=resets, figure_size=figsize,
+            symbols_to_plot=[[x, y], [xt, xb, yt, yb]])
+
+
+if __name__ == '__main__':
+    main()

ode2tn-1.0.0.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: ode2tn
+Version: 1.0.0
+Summary: A Python package to turn arbitrary polynomial ODEs into a transcriptional network simulating it.
+Author-email: Dave Doty <doty@ucdavis.edu>
+License: MIT
+Project-URL: Homepage, https://github.com/UC-Davis-molecular-computing/ode-to-transcription-network
+Project-URL: Issues, https://github.com/UC-Davis-molecular-computing/ode-to-transcription-network/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: gpac
+Requires-Dist: scipy>=1.15
+Requires-Dist: sympy>=1.13
+Dynamic: license-file
+
+# ode-to-transcription-network
+ode2tn is a Python package to turn arbitrary polynomial ODEs into a transcriptional network simulating it.
+
+See this paper for details: TODO
+
+## Installation
+
+Type `pip install ode2tn` at the command line.
+
+## Usage
+
+See the [notebook.ipynb](notebook.ipynb) for more examples of usage.
+
+The functions `ode2tn` and `plot_tn` are the main elements of the package.
+`ode2tn` converts a system of arbitrary polynomial ODEs into another system of ODEs representing a transcriptional network as defined in the paper above.
+Each variable $x$ in the original ODEs is represented by a pair of variables $x^\top,x^\bot$, whose ratio $x^\top / x^\bot$ follows the same dynamics in the transcriptional network as $x$ does in the original ODEs.
+`plot_tn` does this conversion and then plots the ratios by default, although it can be customized what exactly is plotted; 
+see the documentation for [gpac.plot](https://gpac.readthedocs.io/en/latest/#gpac.ode.plot) for a description of all options.
+
+Here is a typical way to call each function:
+
+```python
+from math import pi
+import numpy as np
+import sympy as sp
+from transform import plot_tn, ode2tn
+
+x,y = sp.symbols('x y')
+odes = { # odes dict maps each symbol to an expression for its time derivative
+    x: y-2,
+    y: -x+2,
+}
+inits = { # inits maps each symbol to its initial value
+    x: 2,
+    y: 1,
+}
+gamma = 2 # uniform decay constant; should be set sufficiently large that ???
+beta = 1 # constant introduced to keep values from going to infinity or 0
+t_eval = np.linspace(0, 6*pi, 1000)
+tn_odes, tn_inits, tn_ratios = ode2tn(odes, inits, gamma, beta)
+for sym, expr in tn_odes.items():
+    print(f"{sym}' = {expr}")
+print(f'{tn_inits=}')
+print(f'{tn_ratios=}')
+plot_tn(odes, inits, gamma, beta, t_eval=t_eval)
+```
+
+This will print
+
+```
+x_t' = x_b*y_t/y_b - 2*x_t + x_t/x_b
+x_b' = 2*x_b**2/x_t - 2*x_b + 1
+y_t' = 2*y_b - 2*y_t + y_t/y_b
+y_b' = -2*y_b + 1 + x_t*y_b**2/(x_b*y_t)
+tn_inits={x_t: 2, x_b: 1, y_t: 1, y_b: 1}
+tn_ratios={x: x_t/x_b, y: y_t/y_b}
+```
+
+showing that the variables `x` and `y` have been replace by pairs `x_t,x_b` and `y_t,y_b`, whose ratios `x_t/x_b` and `y_t/y_b` will track the values of the original variable `x` and `y` over time.
+The function `plot_tn` above does this conversion and then plots the ratios.
+Running the code above in a Jupyter notebook will print the above text and show this figure:
+
+![](sine-cosine-plot.png)
+
+One could also hand the transcriptional network ODEs to gpac to integrate, if you want to directly access the data being plotted above.
+The `OdeResult` object returned by `gpac.integrate_odes` is the same returned by [`scipy.integrate.solve_ivp`](https://docs.scipy.org/doc/scipy/reference/generated/scipy.integrate.solve_ivp.html), where the return value `sol` has a field `sol.y` that has the values of the variables in the order they were inserted into `tn_odes`, which will be the same as the order in which the original variables `x` and `y` were inserted, with `x_t` coming before `x_b`:
+
+```
+t_eval = np.linspace(0, 2*pi, 5)
+sol = gp.integrate_odes(tn_odes, tn_inits, t_eval)
+print(f'times = {sol.t}')
+print(f'x_y = {sol.y[0]}')
+print(f'x_b = {sol.y[1]}')
+print(f'y_t = {sol.y[2]}')
+print(f'y_b = {sol.y[3]}')
+```
+
+which would print
+
+```
+times = [0.         1.57079633 3.14159265 4.71238898 6.28318531]
+x_y = [2.         1.78280757 3.67207594 2.80592514 1.71859172]
+x_b = [1.         1.78425369 1.83663725 0.93260227 0.859926  ]
+y_t = [1.         1.87324904 2.14156469 2.10338162 2.74383426]
+y_b = [1.         0.93637933 0.71348949 1.05261915 2.78279691]
+```
+
+

ode2tn-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+ode2tn/__init__.py,sha256=b_mINIsNfCWzgG7QVYMsRsWKDLvp2QKFAzRqWtYqwDA,30
+ode2tn/transform.py,sha256=k_yzuUck-RGgS-WI7cUzNRfC4nKIMip_q5mJfVukg28,15847
+ode2tn-1.0.0.dist-info/licenses/LICENSE,sha256=VV9UH0kkG-2edZvwJOqgtN12bZIzs2vn9_cq1SjoUJc,1091
+ode2tn-1.0.0.dist-info/METADATA,sha256=UQ7FvLFnOyzWs9qK3fS8NZtsVxd8ESDwT3_QdHpl-cE,4198
+ode2tn-1.0.0.dist-info/WHEEL,sha256=lTU6B6eIfYoiQJTZNc-fyaR6BpL6ehTzU3xGYxn2n8k,91
+ode2tn-1.0.0.dist-info/top_level.txt,sha256=fPQ9s5yLIYfazJS7wBBfU9EsWa9RGALq8VL-wUYRlao,7
+ode2tn-1.0.0.dist-info/RECORD,,

ode2tn-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (78.1.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ode2tn-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 UC-Davis Molecular Computing Group
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ode2tn-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ode2tn