ode2tn 1.0.2__tar.gz → 1.0.4__tar.gz

{ode2tn-1.0.2 → ode2tn-1.0.4}/PKG-INFO

@@ -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.2 → ode2tn-1.0.4}/README.md

@@ -1,4 +1,4 @@
-# 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
@@ -9,11 +9,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.
 
@@ -26,41 +26,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/ode2tn/__init__.py

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