Feature/schemes

.github/workflows/ci.yml

@@ -55,9 +55,11 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           if [ "${{ matrix.gui }}" = "true" ]; then
-            pip install -e '.[dev,gui]' matplotlib
+            pip install -e '.[dev,gui,plot]'
           else
-            pip install -e '.[dev]'
+            # plot as well, or the scheme-drawing tests importorskip and
+            # pass without drawing anything
+            pip install -e '.[dev,plot]'
           fi
           pip list
 
@@ -114,6 +116,8 @@ jobs:
           if missing:
               raise SystemExit('missing from the installed wheel: ' + ', '.join(missing))
 
-          from scalcs import scsim, scburst, qmatlib, mechanism, scalcsio
+          # schemes too: it must import without matplotlib, which this
+          # environment does not have
+          from scalcs import scsim, scburst, qmatlib, mechanism, scalcsio, schemes
           print('installed wheel imports and carries its data files')
           PY

README.md

@@ -18,6 +18,7 @@ Modules
 | `popen`           | Equilibrium open probability                                  |
 | `mechanism`       | Ion channel mechanism (state/rate) representation             |
 | `scalcsio`        | HJCFIT / DC_PyPs file I/O                                     |
+| `schemes`         | Draw a mechanism as a reaction scheme (needs `scalcs[plot]`)  |
 
 ### First-latency pdf (`firstlatency`)
 
@@ -52,6 +53,28 @@ eigvals, g00, g10, g11 = fl.gamma_coefficients(tres, phi_shut, mec)
 f_exact = fl.exact_pdf(t, tres, roots, areas, eigvals, g00, g10, g11)
 ```
 
+### Reaction schemes (`schemes`)
+
+Draws a mechanism in the style of Colquhoun & Lape (2012), Figs. 3, 7 and 8:
+states on a grid, each reversible step a close pair of harpoon arrows, with a
+rate constant, transition probability or equilibrium transition frequency
+written against each direction.
+
+```python
+from scalcs import schemes
+from scalcs.samples.samples import GlyR_flip
+
+schemes.draw(GlyR_flip(), values='probability', conc=10e-6, numbers=True)
+```
+
+The arrows drawn are the rates of the mechanism, never inferred from where the
+states are placed. The placement comes from `layout=` if given, otherwise from
+the drawing stored with a mechanism read from a .mec file, otherwise from a
+ready-made layout covering every mechanism in `scalcs.samples`.
+
+Drawing needs matplotlib, which is optional: `pip install scalcs[plot]`.
+`schemes.geometry()` computes every position without it.
+
 References
 ----------
 
@@ -79,6 +102,10 @@ A Q-Matrix Cookbook.
 In: Single-channel recording. 2nd ed. (Eds: Sakmann B, Neher E)
 Plenum Press, New York, pp. 589-633.
 
+CL2012: Colquhoun D, Lape R (2012)
+Allosteric coupling in ligand-gated ion channels.
+J Gen Physiol 140, 599-612.
+
 CHS96: Colquhoun D, Hawkes AG, Srodzinski K (1996)
 Joint distributions of apparent open and shut times of single-ion channels
 and maximum likelihood fitting of mechanisms.

pyproject.toml

@@ -32,7 +32,11 @@ classifiers = [
 ]
 
 [project.optional-dependencies]
-gui = ["PyQt5>=5.12"]
+# scalcs.schemes.draw and the one plotting function in sccurves; the rest
+# of the package only returns arrays and does not need it
+plot = ["matplotlib>=3.5"]
+# the GUI draws with matplotlib too, which it imported without declaring
+gui = ["PyQt5>=5.12", "matplotlib>=3.5"]
 dev = ["pytest>=7", "pytest-cov"]
 
 [project.urls]