ode2tn 1.0.2__py3-none-any.whl → 1.0.4__py3-none-any.whl

ode2tn/__init__.py

@@ -1 +1,8 @@
-from ode2tn.transform import *
+from ode2tn.transform import (
+    ode2tn,
+    plot_tn,
+    update_resets_with_ratios,
+    check_x_is_transcription_factor,
+    is_laurent_monomial,
+    is_laurent_polynomial,
+)

ode2tn/transform.py

@@ -16,8 +16,11 @@ def plot_tn(
         gamma: float,
         beta: float,
         scale: float = 1.0,
+        existing_factors: Iterable[sp.Symbol | str] = (),
+        verify_negative_term: bool = True,
         t_span: tuple[float, float] | None = None,
         show_factors: bool = False,
+        latex_legend: bool = True,
         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),
@@ -48,19 +51,32 @@ def plot_tn(
             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`.
+
         show_factors: if True, then in addition to plotting the ratios x_top/x_bot,
             also plot the factors x_top and x_bot separately in a second plot.
             Mutually exlusive with `symbols_to_plot`, since it is equivalent to setting
             `symbols_to_plot` to ``[ratios, factors]``, where ratios is a list of dependent symbols
             `x=x_top/x_bot`, and factors is a list of symbols with the transcription factors `x_top`, `x_bot`,
             for each original variable `x`.
+
+        latex_legend: If True, surround each symbol name with dollar signs, unless it is already surrounded with them,
+            so that the legend is interpreted as LaTeX. If this is True, then the symbol name must either
+            start and end with `$`, or neither start nor end with `$`. Unlike in the gpac package, this is True
+            by default. The names of transcription factors are automatically surrounded by dollar signs.
+            This option makes sure the legend showing original variables (or dependent symbols) also have `$` added
+            so as to be interpreted as LaTeX.
+
         resets:
             If specified, this is a dict mapping times to "configurations"
             (i.e., dict mapping symbols/str to values).
@@ -80,6 +96,26 @@ def plot_tn(
             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.
 
+        existing_factors: iterable of symbols (or strings with names of symbols) to "pass through" unchanged.
+            These symbols are not transformed into `x_top` and `x_bot` variables, but are interpreted as
+            being transcription factors already. Raises exception if any of these symbols are
+            not in the original ODEs. Also raises exception if any have an ode not of the form
+            required as a transcriptional network: a Laurent polynomial in the variables with a single negative
+            term `-gamma * x`, where `x` is the transription factor.
+
+        verify_negative_term: If False, then do not check that the existing factors
+            have an ODE with a single negative term of the form `-gamma*x`. The default is True, but this can lead to
+            false positives. If one constructs a sympy expression such as `expr- gamma*x`, it could be that expr
+            can be simplyfied to `alpha*x` for some constant `alpha` > `gamma`. Then the expression would be
+            simplified to `(alpha-gamma)*x`, so would no longer have a negative term (or if `alpha < gamma`, it would
+            have a negative term, but with the wrong coefficient `(alpha-gamma)` instead of `gamma`). However,
+            since one writing an ODE by hand would tend to write it already in simplified form (e.g.,
+            it would be awkward to write `odes = {x: 1.7*x - 0.5*x}` rather than simply `odes = {x: 1.2*x}`),
+            we leave the check on by default. Only turn off this check if you are confident that the
+            ODEs already contain a negative term of the form `-gamma*x`.
+            It is still verified that the ODE is a Laurent polynomial; since this condition is independent of
+            the form of the expression.
+
     Returns:
         Typically None, but if return_ode_result is True, returns the result of the ODE integration.
         See documentation of `gpac.plot` for details.
@@ -87,7 +123,9 @@ def plot_tn(
     if show_factors and symbols_to_plot is not None:
         raise ValueError("Cannot use both show_factors and symbols_to_plot at the same time.")
 
-    tn_odes, tn_inits, tn_syms = ode2tn(odes, initial_values, gamma=gamma, beta=beta, scale=scale)
+    tn_odes, tn_inits, tn_syms = ode2tn(odes, initial_values, gamma=gamma, beta=beta, scale=scale,
+                                        existing_factors=existing_factors,
+                                        verify_negative_term=verify_negative_term)
     dependent_symbols_tn = dict(dependent_symbols) if dependent_symbols is not None else {}
     tn_ratios = {sym: sym_t/sym_b for sym, (sym_t, sym_b) in tn_syms.items()}
     dependent_symbols_tn.update(tn_ratios)
@@ -112,6 +150,7 @@ def plot_tn(
         dependent_symbols=dependent_symbols_tn,
         resets=resets,
         figure_size=figure_size,
+        latex_legend=latex_legend,
         symbols_to_plot=symbols_to_plot,
         legend=legend,
         show=show,
@@ -170,6 +209,9 @@ def ode2tn(
         gamma: float,
         beta: float,
         scale: float = 1.0,
+        ignore: Iterable[sp.Symbol] = (),
+        existing_factors: Iterable[sp.Symbol | str] = (),
+        verify_negative_term: bool = True,
 ) -> tuple[dict[sp.Symbol, sp.Expr], dict[sp.Symbol, float], dict[sp.Symbol, tuple[sp.Symbol, sp.Symbol]]]:
     """
     Maps polynomial ODEs and and initial values to transcription network (represented by ODEs with positive
@@ -180,15 +222,43 @@ def ode2tn(
             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) or gpac.Specie (representing chemical
             species, if the ODEs were derived from `gpac.crn_to_odes`) 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`.
 
+        ignore: variables to ignore and not transform into `x_top` and `x_bot` variables. Note this is different
+            from `existing_factors`, in the sense that variables in `ignore` are not put into the output
+            ODEs.
+
+        existing_factors: iterable of symbols (or strings with names of symbols) to "pass through" unchanged.
+            These symbols are not transformed into `x_top` and `x_bot` variables, but are interpreted as
+            being transcription factors already. Raises exception if any of these symbols are
+            not in the original ODEs. Also raises exception if any have an ode not of the form
+            required as a transcriptional network: a Laurent polynomial in the variables with a single negative
+            term `-gamma * x`, where `x` is the transription factor.
+
+        verify_negative_term: If False, then do not check that the existing factors
+            have an ODE with a single negative term of the form `-gamma*x`. The default is True, but this can lead to
+            false positives. If one constructs a sympy expression such as `expr- gamma*x`, it could be that expr
+            can be simplyfied to `alpha*x` for some constant `alpha` > `gamma`. Then the expression would be
+            simplified to `(alpha-gamma)*x`, so would no longer have a negative term (or if `alpha < gamma`, it would
+            have a negative term, but with the wrong coefficient `(alpha-gamma)` instead of `gamma`). However,
+            since one writing an ODE by hand would tend to write it already in simplified form (e.g.,
+            it would be awkward to write `odes = {x: 1.7*x - 0.5*x}` rather than simply `odes = {x: 1.2*x}`),
+            we leave the check on by default. Only turn off this check if you are confident that the
+            ODEs already contain a negative term of the form `-gamma*x`.
+            It is still verified that the ODE is a Laurent polynomial; since this condition is independent of
+            the form of the expression.
+
     Return:
         triple (`tn_odes`, `tn_inits`, `tn_syms`), where `tn_syms` is a dict mapping each original symbol ``x``
         in the original ODEs to the pair ``(x_top, x_bot)``.
@@ -203,6 +273,10 @@ def ode2tn(
         initial_values_norm[symbol] = value
     initial_values = initial_values_norm
 
+    # normalize existing_factors to be symbols
+    existing_factors: list[sp.Symbol] = [sp.Symbol(factor) if isinstance(factor, str) else factor
+                                         for factor in existing_factors]
+
     # normalize odes dict to use symbols as keys
     odes_normalized = {}
     symbols_found_in_expressions = set()
@@ -237,8 +311,156 @@ def ode2tn(
         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)
+    return normalized_ode2tn(odes, initial_values, gamma=gamma, beta=beta, scale=scale, ignore=list(ignore),
+                             existing_factors=existing_factors, verify_negative_term=verify_negative_term)
+
+
+def check_x_is_transcription_factor(x: sp.Symbol, ode: sp.Expr, gamma: float, verify_negative_term: bool) -> None:
+    """
+    Check if 'ode' is a Laurent polynomial with a single negative term -gamma*x.
+
+    Parameters
+    ----------
+    x
+        The symbol that should appear in the negative term.
+
+    ode
+        The symbolic expression to check.
 
+    gamma
+        The expected coefficient of the negative term.
+
+    verify_negative_term
+        Whether to check for the negative term -gamma*x.
+
+    Raises
+    ------
+    ValueError
+        If 'ode' is not a Laurent polynomial or if it doesn't have exactly
+        one negative term of the form -gamma*x.
+    """
+    # Expand the expression to get it in a standard form
+    expanded_ode = sp.expand(ode)
+
+    # Check if the expression is a Laurent polynomial
+    if not is_laurent_polynomial(expanded_ode):
+        raise ValueError(f"The expression `{ode}` is not a Laurent polynomial")
+
+    if not verify_negative_term:
+        return
+
+    # Collect terms and check for the negative term -gamma*x
+    terms = expanded_ode.as_ordered_terms()
+
+    # Find negative terms that contain x
+    negative_terms = [term for term in terms if is_negative(term) and x in term.free_symbols]
+
+    # Check if there's exactly one negative term
+    if len(negative_terms) != 1:
+        raise ValueError(f"Expected exactly one negative term with {x}, found {len(negative_terms)} in `{ode}`")
+
+    # Check if the negative term has the form -gamma*x
+    negative_term = negative_terms[0]
+
+    # Try to extract the coefficient of x
+    coeff = sp.Wild('coeff')
+    match_dict = negative_term.match(-coeff * x)
+
+    if match_dict is None:
+        raise ValueError(f"The negative term {negative_term} doesn't have the form -gamma*{x} in expression {ode}")
+
+    actual_gamma = float(match_dict[coeff])
+
+    # Check if the coefficient is approximately equal to gamma
+    if not is_approximately_equal(actual_gamma, gamma):
+        raise ValueError(f"Expected coefficient {gamma}, got {actual_gamma} in expression {ode}")
+
+
+def is_laurent_polynomial(expr: sp.Expr) -> bool:
+    """
+    Check if an expression is a Laurent polynomial (polynomial with possible negative exponents).
+
+    Parameters
+    ----------
+    expr
+        The symbolic expression to check.
+
+    Returns
+    -------
+    :
+        True if the expression is a Laurent polynomial, False otherwise.
+    """
+    if expr.is_Add:
+        return all(is_laurent_polynomial(term) for term in expr.args)
+
+    if expr.is_Mul:
+        return all(is_laurent_monomial(factor) for factor in expr.args)
+
+    # Constants are Laurent polynomials
+    if expr.is_number:
+        return True
+
+    # Single symbols are Laurent polynomials
+    if expr.is_Symbol:
+        return True
+
+    return is_laurent_monomial(expr)
+
+
+def is_laurent_monomial(expr: sp.Expr) -> bool:
+    """
+    Check if an expression is a Laurent monomial (term with possible negative exponents).
+
+    Parameters
+    ----------
+    expr
+        The symbolic expression to check.
+
+    Returns
+    -------
+    :
+        True if the expression is a Laurent monomial, False otherwise.
+    """
+    # Handle division expressions (a/b) by rewriting as a*b^(-1)
+    if expr.is_Mul and any(arg.is_Pow and arg.args[1] < 0 for arg in expr.args):
+        return all(factor.is_Symbol or
+                   (factor.is_Pow and factor.args[0].is_Symbol and factor.args[1].is_Integer) or
+                   factor.is_number for factor in expr.args)
+
+    # Direct division (x/y) is rewritten to x*y^(-1) by SymPy
+    # But we'll handle it explicitly in case it's encountered directly
+    if expr.is_Pow:
+        base, exp = expr.args
+        return base.is_Symbol and exp.is_Integer
+
+    # Handle direct division representation
+    if hasattr(expr, 'func') and expr.func == sp.core.mul.Mul and len(expr.args) == 2:
+        if hasattr(expr, 'is_commutative') and expr.is_commutative:
+            numer, denom = expr.as_numer_denom()
+            return numer.is_Symbol and denom.is_Symbol
+
+    return expr.is_Symbol or expr.is_number
+
+
+def is_approximately_equal(a: float, b: float, rtol: float = 1e-5, atol: float = 1e-8) -> bool:
+    """
+    Check if two numbers are approximately equal within specified tolerances.
+
+    Parameters
+    ----------
+    a, b
+        The numbers to compare.
+    rtol
+        The relative tolerance.
+    atol
+        The absolute tolerance.
+
+    Returns
+    -------
+    :
+        True if the numbers are approximately equal, False otherwise.
+    """
+    return abs(a - b) <= (atol + rtol * abs(b))
 
 def normalized_ode2tn(
         odes: dict[sp.Symbol, sp.Expr],
@@ -247,34 +469,51 @@ def normalized_ode2tn(
         gamma: float,
         beta: float,
         scale: float,
+        ignore: list[sp.Symbol],
+        existing_factors: list[sp.Symbol],
+        verify_negative_term: bool,
 ) -> tuple[dict[sp.Symbol, sp.Expr], dict[sp.Symbol, float], dict[sp.Symbol, tuple[sp.Symbol, sp.Symbol]]]:
     # Assumes ode2tn has normalized and done error-checking
 
     tn_syms: dict[sp.Symbol, tuple[sp.Symbol, sp.Symbol]] = {}
     for x in odes.keys():
-        # create x_t, x_b for each symbol x
-        x_t, x_b = sp.symbols(f'{x}_t {x}_b')
-        tn_syms[x] = (x_t, x_b)
+        if x not in existing_factors and x not in ignore:
+            # create x_t, x_b for each symbol x
+            x_t, x_b = sp.symbols(f'{x}_t {x}_b')
+            tn_syms[x] = (x_t, x_b)
 
     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)
+    for x, ode in odes.items():
+        if x in ignore:
+            continue
+        if x in existing_factors:
+            check_x_is_transcription_factor(x, odes[x], gamma=gamma, verify_negative_term=verify_negative_term)
+            ode = odes[x]
+            for y, (y_t, y_b) in tn_syms.items():
+                ratio = y_t / y_b
+                ode = ode.subs(y, ratio)
+            tn_odes[x] = ode
+            tn_inits[x] = initial_values.get(x, 0) * scale
+            continue
+        p_pos, p_neg = split_polynomial(ode)
 
         # replace sym with sym_top / sym_bot for each original symbol sym
         for sym in odes.keys():
+            if sym in existing_factors or sym in ignore:
+                continue
             sym_top, sym_bot = tn_syms[sym]
             ratio = sym_top / sym_bot
             p_pos = p_pos.subs(sym, ratio)
             p_neg = p_neg.subs(sym, ratio)
 
         x_t, x_b = tn_syms[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_t] = beta * x_t / x_b + p_pos * x_b - gamma * x_t
         tn_odes[x_b] = beta + p_neg * x_b ** 2 / x_t - gamma * x_b
         tn_inits[x_t] = initial_values.get(x, 0) * scale
         tn_inits[x_b] = scale
+        check_x_is_transcription_factor(x_t, tn_odes[x_t], gamma=gamma, verify_negative_term=False)
+        check_x_is_transcription_factor(x_b, tn_odes[x_b], gamma=gamma, verify_negative_term=False)
 
     return tn_odes, tn_inits, tn_syms
 
@@ -285,22 +524,27 @@ def split_polynomial(expr: sp.Expr) -> tuple[sp.Expr, sp.Expr]:
     p1: monomials with positive coefficients
     p2: monomials with negative coefficients (made positive)
 
-    Args:
-        expr: A sympy Expression that is a polynomial
+    Parameters
+    ----------
+    expr: A sympy Expression that is a polynomial
 
-    Returns:
+    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``)
+    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)
+    # 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():
@@ -316,38 +560,15 @@ def split_polynomial(expr: sp.Expr) -> tuple[sp.Expr, sp.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)
+            if is_negative(term):
+                p_neg += -term
             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 or expanded.is_Pow:
-        # 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:
+        if is_negative(expanded):
             p_neg = -expanded
+        else:
+            p_pos = expanded
 
     return p_pos, p_neg
 
@@ -356,23 +577,99 @@ def comma_separated(elts: Iterable[Any]) -> str:
     return ', '.join(str(elt) for elt in elts)
 
 
+def is_negative(expr: sp.Symbol | sp.Expr | float | int) -> bool:
+    if isinstance(expr, (float, int, sp.Number)):
+        return expr < 0
+    elif expr.is_Atom or expr.is_Pow:
+        return False
+    elif expr.is_Add:
+        raise ValueError(f"Expression {expr} is not a single term")
+    elif expr.is_Mul:
+        arg0 = expr.args[0]
+        if isinstance(arg0, sp.Symbol):
+            return False
+        return arg0.is_negative
+    else:
+        raise ValueError(f"Unrecognized type {type(expr)} of expression `{expr}`")
+
 def main():
+    from sympy.abc import p,q,w,z,x
+
     import gpac as gp
     import numpy as np
     import sympy as sp
-    from ode2tn import plot_tn
-
-    x = gp.species('X')
-    rxns = [2 * x >> 3 * x]
-    odes = gp.crn_to_odes(rxns)
-    inits = {x: 1}
-    t_eval = np.linspace(0, 1, 100)
-    gamma = 1
+    from ode2tn import ode2tn
+    import matplotlib.pyplot as plt
+
+    gamma = 20
     beta = 1
-    # figsize = (16,4)
+    shift = 2  # amount by which to shift oscillator up to maintain positivity
+    x, p, q, w, z, zap = sp.symbols('x p q w z zap')
+    # objective function f as a sympy expression
+    f_exp = sp.exp(-(x - 3) ** 2 / 0.5) + 1.5 * sp.exp(-(x - 5) ** 2 / 1.5)
+    f_plot = sp.plot(f_exp, (x, 0, 8), size=(6, 2))
+
+    # next line commented out because it generates a new plot for some reason; uncomment to save the plot to a file
+    # f_plot.save("extremum-seek-objective-function.pdf")
+
+    # f as a Python function that can be called with sympy Expression inputs to substitute for the variable x
+    def f(expr):
+        return f_exp.subs(x, expr)
+
+    omega = 3  # frequency of oscillation
+    lmbda = 0.1 * omega
+    k = 0.5 * lmbda  # rate of convergence
+    a = 0.1  # magnitude of oscillation
+    odes = {
+        p: omega * (q - shift),
+        q: -omega * (p - shift),
+        w: -lmbda * (w - shift),  # + f(x)*(p-shift), # we add this after doing the construction
+        z: k * (w - shift),
+        x: gamma * (z + a * p - x),
+    }
+    inits = {
+        p: 0 + shift,
+        q: 1 + shift,
+        w: 0 + shift,
+        z: 2,  # z(0) sets initial point of search
+    }
+    t_eval = np.linspace(0, 300, 1000)
+
+    # we manually plot instead of calling gpac.plot in order to show values of x for different initial values of z in one plot
+
+    tn_odes, tn_inits, tn_syms = ode2tn(odes, inits, gamma=gamma, beta=beta, existing_factors=[x])
+    wt, wb = tn_syms[w]
+    pt, pb = tn_syms[p]
+    zt, zb = tn_syms[z]
+    tn_odes[wt] += f(x) * (pt / pb - shift) * wb
+
+    x_idx = 0
+    found = False
+    for var in tn_odes.keys():
+        if var == x:
+            found = True
+            break
+        x_idx += 1
+    assert found
+
+    plt.figure(figsize=(12, 5))
+
+    for z_init in np.arange(2, 7.5, 0.5):
+        tn_inits[zt] = z_init
+        tn_inits[zb] = 1
+        sol = gp.integrate_odes(tn_odes, tn_inits, t_eval)
+        x_vals = sol.y[x_idx]
+        label = f"x for z(0)={z_init}"
+        times = sol.t
+        plt.plot(times, x_vals, label=label, color="blue")
+
+    plt.yticks(range(8))
+    plt.ylim(1, 8)
+    plt.xlabel("time")
+    plt.ylabel(r"$x$", rotation='horizontal')
+    plt.axhline(y=5, color='g', linestyle='--', linewidth=1)
+    plt.axhline(y=3.084, color='r', linestyle='--', linewidth=1)
 
-    # gp.plot_crn(rxns, inits, t_eval, figure_size=figsize)
-    plot_tn(odes, inits, t_eval, gamma=gamma, beta=beta)
 
 
 if __name__ == '__main__':

{ode2tn-1.0.2.dist-info → ode2tn-1.0.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ode2tn
-Version: 1.0.2
+Version: 1.0.4
 Summary: A Python package to turn arbitrary polynomial ODEs into a transcriptional network simulating it.
 Author-email: Dave Doty <doty@ucdavis.edu>
 License-Expression: MIT
@@ -14,7 +14,7 @@ Requires-Dist: scipy>=1.15
 Requires-Dist: sympy>=1.13
 Dynamic: license-file
 
-# ode-to-transcription-network
+# ode2tn
 ode2tn is a Python package to compile arbitrary polynomial ODEs into a transcriptional network simulating the ODEs.
 
 See this paper for details: TODO
@@ -25,11 +25,11 @@ Type `pip install ode2tn` at the command line.
 
 ## Usage
 
-See the [notebook.ipynb](notebook.ipynb) for more examples of usage.
+See the [notebook.ipynb](notebook.ipynb) (relative link on GitHub; will not work on other sites like pypi.org) for more examples of usage, including all the examples discussed in the paper.
 
 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.
+Each variable $x$ in the original ODEs is represented by a pair of variables $x^\top,x^\bot$, whose ratio $\frac{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.
 
@@ -42,41 +42,63 @@ 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,
+odes = {      # odes dict maps each symbol to an expression for its time derivative
+    x: y-2,   # dx/dt = y-2
+    y: -x+2,  # dy/dt = -x+2
 }
-inits = { # inits maps each symbol to its initial value
-    x: 2,
-    y: 1,
+inits = {     # inits maps each symbol to its initial value
+    x: 2,     # x(0) = 2
+    y: 1,     # y(0) = 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)
-plot_tn(odes, inits, gamma=gamma, beta=beta, t_eval=t_eval, show_factors=True)
+gamma = 2     # uniform decay constant; should have gamma > max q^-; 
+              #   see proof of main Theorem in paper for what q^- is
+beta = 1      # constant introduced to keep values from going to infinity or 0
+tn_odes, tn_inits, tn_syms = ode2tn(odes, inits, gamma=gamma, beta=beta)
+gp.display_odes(tn_odes)  # displays nice rendered LaTeX in Jupyter notebook
+print(f'{tn_inits=}')
+print(f'{tn_syms=}')
 ```
 
-This will print
+When run in a Jupyter notebook, this will show
+
+![](images/ode-display.png)
+
+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.
 
+If not in a Jupyter notebook, one could also inspect the transcriptional network ODEs via
+```python
+for var, ode in tn_odes.items():
+    print(f"{var}' = {ode}")
+```
+which would print a text-based version of the equations:
 ```
 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_syms={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:
+The function `plot_tn` above does this conversion on the *original* odes and then plots the ratios.
+Running 
 
-![](sine-cosine-plot.svg)
+```python
+t_eval = np.linspace(0, 6*pi, 1000)
+# note below it is odes and inits, not tn_odes and tn_inits
+# plot_tn calls ode2tn to convert the ODEs before plotting
+plot_tn(odes, inits, gamma=gamma, beta=beta, t_eval=t_eval, show_factors=True)
+```
+
+in a Jupyter notebook will show this figure:
 
-One could also hand the transcriptional network ODEs to gpac to integrate, if you want to directly access the data being plotted above.
+![](images/sine-cosine-plot.svg)
+
+The parameter `show_factors` above indicates to show a second subplot with the underlying transcription factors ($x^\top, x^\bot, y^\top, y^\bot$ above).
+If left unspecified, it defaults to `False` and plots only the original values (ratios of pairs of transcription factors, $x,y$ above).
+
+One could also hand the transcriptional network ODEs to [gpac](https://github.com/UC-Davis-molecular-computing/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`:
 
-```
+```python
 t_eval = np.linspace(0, 2*pi, 5)
 sol = gp.integrate_odes(tn_odes, tn_inits, t_eval)
 print(f'times = {sol.t}')

ode2tn-1.0.4.dist-info/RECORD

@@ -0,0 +1,7 @@
+ode2tn/__init__.py,sha256=CEHlHkTMSItKXBPVGGxTNa9FO-ywsIQ5-v6xk7Oy91A,177
+ode2tn/transform.py,sha256=rM-VB22RzXkJBFB3FQXRNbW9o8Im2uB2BDZmd-IqKQo,28197
+ode2tn-1.0.4.dist-info/licenses/LICENSE,sha256=VV9UH0kkG-2edZvwJOqgtN12bZIzs2vn9_cq1SjoUJc,1091
+ode2tn-1.0.4.dist-info/METADATA,sha256=DdtTkq9m5Da2Ui2xI_eZZIwIFgYzzGF2pXAMm8QFHqQ,5212
+ode2tn-1.0.4.dist-info/WHEEL,sha256=pxyMxgL8-pra_rKaQ4drOZAegBVuX-G_4nRHjjgWbmo,91
+ode2tn-1.0.4.dist-info/top_level.txt,sha256=fPQ9s5yLIYfazJS7wBBfU9EsWa9RGALq8VL-wUYRlao,7
+ode2tn-1.0.4.dist-info/RECORD,,

ode2tn-1.0.2.dist-info/RECORD

@@ -1,7 +0,0 @@
-ode2tn/__init__.py,sha256=b_mINIsNfCWzgG7QVYMsRsWKDLvp2QKFAzRqWtYqwDA,30
-ode2tn/transform.py,sha256=8gQVHaCRTdiACQPZdkB3OPfc2KOZTA3YwMgbXDDnNkE,16155
-ode2tn-1.0.2.dist-info/licenses/LICENSE,sha256=VV9UH0kkG-2edZvwJOqgtN12bZIzs2vn9_cq1SjoUJc,1091
-ode2tn-1.0.2.dist-info/METADATA,sha256=MSGeKttEB-ImlNvBof07AeyxR1rOCBf48tUNinaIgS0,4095
-ode2tn-1.0.2.dist-info/WHEEL,sha256=pxyMxgL8-pra_rKaQ4drOZAegBVuX-G_4nRHjjgWbmo,91
-ode2tn-1.0.2.dist-info/top_level.txt,sha256=fPQ9s5yLIYfazJS7wBBfU9EsWa9RGALq8VL-wUYRlao,7
-ode2tn-1.0.2.dist-info/RECORD,,