Moving away from using term 'tutorial'

README.md

@@ -1,100 +1,107 @@
-# Fitting ion channel models with Myokit & PINTS
-
-This repository contains examples showing how to fit Myokit models to data using the PINTS optimisation & inference framework.
-
-A part on fitting AP models is planned, but for now the repository contains:
-
-- a [detailed tutorial](ion-currents-tutorial/README.md) showing how to fit kinetic parameters of ion current models.
-
-## General recommendations
-
-**Start with a synthetic data study:**
-Before going to the lab, work out what data you expect to get, simulate this data and add noise, prepare your analysis code, and test that it can recover the parameters you used to generate the data.
-
-**Fit to time-series data:**
-Whenever possible, fit to time-series data, not to "summary statistics" or "biomarkers" such as time constants, IV-, or (in)activation curves.
-Contacting experimenters, digging in archives, or even repeating experiments is a better use of time than trying to fit to data not suitable for fitting to.
-
-**Define expected ranges for the parameters:**
-Define boundaries on the parameters (or on e.g. rates derived from the parameters).
-These can speed up your search, but are also used to prevent numerical problems and solver failures when certain parameters and functions of parameters get too large or small.
-
-**Verify the reliability of your results:** by running repeated fits.
-Restart your fit several (50?) times from different positions sampled from within the feasible ranges of the parameters.
-If only a handful of fits find the same "best result", it's likely this isn't the true optimum.
-
-**Check your solver tolerances**: if using an adaptive step-size solver, make sure you use strict tolerances.
-If you're not sure, plot the error measure along a line between two nearby points: if it's nice and smooth the optimiser will love it.
-
-**Search in a log-transformed parameter space**: This can often make the problem much easier for whatever optimisation algorithm you're using.
-
-**Use the CMA-ES optimiser**: It performs much better on these problems than anything else we've tested.
-
-## More information
-
-### Software
-
-- **Probabilistic Inference on Noisy Time Series (PINTS)**.
-  Michael Clerx, Martin Robinson, Ben Lambert, Chon Lok Lei, Sanmitra Ghosh, Gary R. Mirams, David J. Gavaghan.
-  2019, Journal of Open Research Software.
-  [doi:10.5334/jors.252](https://doi.org/10.5334/jors.252)
-  | [examples](https://github.com/pints-team/pints/blob/master/examples/README.md) 
-  | [documentation](https://pints.readthedocs.io/)
-  | [installation](https://github.com/pints-team/pints/)
-  | [code](https://github.com/pints-team/pints/)
-
-- **Myokit: A simple interface to cardiac cellular electrophysiology**.
-  Michael Clerx, Pieter Collins, Enno de Lange, Paul G.A. Volders.
-  2016, Progress in Biophysics and Molecular Biology.
-  [doi:10.1016/j.pbiomolbio.2015.12.008](https://doi.org/10.1016/j.pbiomolbio.2015.12.008)
-  | [examples](http://myokit.org/examples/)
-  | [documentation](https://myokit.readthedocs.io)
-  | [installation](http://myokit.org/install)
-  | [website](http://myokit.org)
-  | [code](https://github.com/MichaelClerx/myokit/)
-
-### Papers
-
-- **Calibration of ionic and cellular cardiac electrophysiology models**.
-  Dominic G. Whittaker, Michael Clerx, Chon Lok Lei, David J. Christini, Gary R. Mirams.
-  2020, WIREs Systems Biology and Medicine.
-  [doi:10.1002/wsbm.1482](https://doi.org/10.1002/wsbm.1482)
-  | [code](https://github.com/CardiacModelling/WIRES)
-
-- **Four ways to fit an ion channel model**.
-  Michael Clerx, Kylie A. Beattie, David J. Gavaghan, Gary R. Mirams.
-  2019, Biophysical Journal.
-  [doi:10.1016/j.bpj.2019.08.001](https://doi.org/10.1016/j.bpj.2019.08.001)
-  | [code](https://github.com/CardiacModelling/FourWaysOfFitting)
-
-- **Rapid characterisation of hERG channel kinetics I: using an automated high-throughput system**.
-  Chon Lok Lei, Michael Clerx, David J. Gavaghan, Liudmila Polonchuk, Gary R. Mirams, Ken Wang.
-  2019, Biophysical Journal.
-  [doi:j.bpj.2019.07.029](https://doi.org/10.1016/j.bpj.2019.07.029)
-  | [code](https://github.com/CardiacModelling/hERGRapidCharacterisation)
-
-- **Rapid characterisation of hERG channel kinetics II: temperature dependence**.
-  Chon Lok Lei, Michael Clerx, Kylie A. Beattie, Dario Melgari, Jules C. Hancox, David J. Gavaghan, Liudmila Polonchuk, Ken Wang, Gary R. Mirams.
-  2019, Biophysical Journal.
-  [doi:j.bpj.2019.07.030](https://doi.org/10.1016/j.bpj.2019.07.030)
-  | [code](https://github.com/CardiacModelling/hERGRapidCharacterisation)
-
-- **Sinusoidal voltage protocols for rapid characterisation of ion channel kinetics**
-  Kylie A. Beattie, Adam P. Hill, Rémi Bardenet, Yi Cui, Jamie I. Vandenberg, David J. Gavaghan, Teun P. de Boer, Gary R. Mirams
-  2018, The Journal of Physiology.
-  [doi:10.1113/JP275733](https://doi.org/10.1113/JP275733)
-  | [code](https://github.com/mirams/sine-wave)
-
-### Advanced topics
-
-- **Accounting for variability in ion current recordings using a mathematical model of artefacts in voltage-clamp experiments**
-  Chon Lok Lei, Michael Clerx, Dominic G. Whittaker, David J. Gavaghan, Teun P. de Boer, Gary R. Mirams
-  [doi:10.1098/rsta.2019.0348](https://doi.org/10.1098/rsta.2019.0348)
-  | [code](https://github.com/CardiacModelling/VoltageClampModel)
-
-- **Considering discrepancy when calibrating a mechanistic electrophysiology model**
-  Chon Lok Lei, Sanmitra Ghosh, Dominic G. Whittaker, Yasser Aboelkassem, Kylie A. Beattie, Chris D. Cantwell, Tammo Delhaas, Charles Houston, Gustavo Montes Novaes, Alexander V. Panfilov, Pras Pathmanathan, Marina Riabiz, Rodrigo Weber dos Santos, John Walmsley, Keith Worden, Gary R. Mirams, Richard D. Wilkinson
-  2020, Phil. Trans. R. Soc. A.
-  [doi:10.1098/rsta.2019.0349](http://doi.org/10.1098/rsta.2019.0349)
-  | [code](https://github.com/CardiacModelling/fickleheart-method-tutorials)
+[↩ back to index](../README.md)
+# Estimating parameters of ion current models from whole-cell voltage-clamp data
+
+In these notebooks, we look at the problem of estimating the parameters of an ion current model from whole-cell voltage-clamp data.
+
+As we go along, we'll create some classes and utility functions that may be useful in general.
+These are all stored in [library.py](./library.py).
+
+The follow topics are covered:
+
+## [Introduction](introduction.ipynb) - [nbviewer](https://nbviewer.jupyter.org/github/CardiacModelling/fitting-notebooks/blob/main/ion-currents/introduction.ipynb)
+
+This notebook provides some background on the model we'll use in all examples.
+It also introduces a first voltage-protocol (a simplified variant of the "staircase protocol").
+
+## [Basic simulations](basic-simulations.ipynb) - [nbviewer](https://nbviewer.jupyter.org/github/CardiacModelling/fitting-notebooks/blob/main/ion-currents/basic-fitting.ipynb)
+
+This notebook shows how Myokit can be used to simulate patch-clamp experiments.
+It shows you how to create a simulation from a model and protocol stored on disk, and discusses how to change model parameters.
+Finally, it shows how steady-states can be calculated and set as initial conditions.
+
+## [Basic fitting](basic-fitting.ipynb)
+
+In this notebook we link Myokit to PINTS.
+Noise models are discussed and synthetic data is generated, after which an error measure is defined and minimised.
+Inspecting the results, we show how tight solver tolerances are needed for fitting, and how the finite size of our experimental time series can cause a slight bias in the results.
+
+## Fitting to different voltage protocols
+
+The next four notebooks discuss different voltage protocols, and the simulation methods appropriate to each one.
+
+- [Combining step protocols with sine waves or ramps](more-protocols-1-steps-and-ramps.ipynb) - [nbviewer](https://nbviewer.jupyter.org/github/CardiacModelling/fitting-notebooks/blob/main/ion-currents/more-protocols-1-steps-and-ramps.ipynb)
+- [Simulating an AP protocol with "data clamp"](more-protocols-2-data-clamp.ipynb)
+- [Analytical solvers for simple step protocols](more-protocols-3-analytic-solvers.ipynb)
+- [Fitting to multiple simple step protocols](more-protocols-4-multiple-protocols.ipynb)
+
+## [Setting boundaries on model parameters](boundaries.ipynb)
+
+In this notebook we show how some parameters can cause numerical issues during simulation, and how we can catch and report these errors.
+We then inspect the model equations and use previous estimates of our parameters (or quantities related to the parameters) to define some very wide boundaries, or "prior estimates".
+Finally, we show how we can use this kind of reasoning to define univariate boundaries (one on each parameter), and multivariate boundaries (which restrict the maximum rate coefficients seen during a simulation).
+
+## [Selecting starting points for an optimisation](starting-points.ipynb)
+
+Continuing from the previous chapters, this notebook shows how we can sample from within the (univariate and multivariate) boundaries to select starting points for an optisiation.
+At the end of this notebook we briefly discuss a "repeated-fits" strategy which allows you to test the reliability of results obtained on real data, where the "true" parameters are not known.
+
+## [Searching in a transformed space](transformations.ipynb)
+
+This notebook shows how you can create wrappers around models and boundaries to run optimisations on a transformed parameter space.
+
+## [Running big fitting experiments](big-fitting.ipynb)
+
+This notebook focusses on the practical side of fitting.
+It introduces methods to store simulation results to disk, load and analyse them, and shows a way to "reserve" filenames when multiple processes are running at once.
+It ends with a brief note on multiprocessing.
+
+## [Validating modelling results](validation.ipynb)
+
+- Repeated runs (see previous notebook) validates fitting
+- Training, validation, and test sets validates modelling?
+
+## Dealing with real data
+
+Blah blah blah
+
+These are sequential, not independent notebooks
+
+- [Introduction, and additive noise](real-data-1-noise.ipynb)
+- [Capacitance and series resistance](real-data-2-capacitance-and-resistance.ipynb)
+
+- One
+  - Four strategies
+  - Noise model
+  - Stochastic noise
+  - Periodic noise
+- Two
+  - Pipette capacitance
+  - Membrane capacitance
+
+Sources:
+- [x] Thermal, shot, mains, etc.
+- [x] Stray capacitance
+- [ ] Membrane capacitance
+- [ ] Series resistance
+- [ ] Leak
+- [ ] Endogeneous currents
+- [ ] Gating currents? (~100x smaller than ionic currents)
+
+Things to be uncertain about
+- [ ] Concentrations
+- [ ] Reversal potential (Nernst/GHK graph?)
+- [ ] Temperature
+- [ ] Model discrepancy
+
+Methods
+- [x] Low-pass filter
+- [x] Modelling noise
+- [x] Stray cap correction
+- [ ] Cm correction
+- [ ] Artefact filtering
+- [ ] Rs correction
+- [ ] Subtraction protocol
+- [ ] Leak correction
+- [ ] Leak ramp
+- [ ] Reversal potential ramp
 

ion-currents-tutorial/README.md → ion-currents/README.md

@@ -1,57 +1,57 @@
 [↩ back to index](../README.md)
 # Estimating parameters of ion current models from whole-cell voltage-clamp data
 
-In this tutorial, we look at the problem of estimating the parameters of an ion current model from whole-cell voltage-clamp data.
+In these notebooks, we look at the problem of estimating the parameters of an ion current model from whole-cell voltage-clamp data.
 
 As we go along, we'll create some classes and utility functions that may be useful in general.
 These are all stored in [library.py](./library.py).
 
 The follow topics are covered:
 
-## [Introduction](introduction.ipynb)
+## [Introduction](introduction.ipynb) - [nbviewer](https://nbviewer.jupyter.org/github/CardiacModelling/fitting-notebooks/blob/main/ion-currents/introduction.ipynb)
 
-This tutorial provides some background on the model we'll use throughout the tutorial.
+This notebook provides some background on the model we'll use in all examples.
 It also introduces a first voltage-protocol (a simplified variant of the "staircase protocol").
 
-## [Basic simulations](basic-simulations.ipynb)
+## [Basic simulations](basic-simulations.ipynb) - [nbviewer](https://nbviewer.jupyter.org/github/CardiacModelling/fitting-notebooks/blob/main/ion-currents/basic-fitting.ipynb)
 
-This tutorial shows how Myokit can be used to simulate patch-clamp experiments.
+This notebook shows how Myokit can be used to simulate patch-clamp experiments.
 It shows you how to create a simulation from a model and protocol stored on disk, and discusses how to change model parameters.
 Finally, it shows how steady-states can be calculated and set as initial conditions.
 
 ## [Basic fitting](basic-fitting.ipynb)
 
-In this tutorial we link Myokit to PINTS.
+In this notebook we link Myokit to PINTS.
 Noise models are discussed and synthetic data is generated, after which an error measure is defined and minimised.
 Inspecting the results, we show how tight solver tolerances are needed for fitting, and how the finite size of our experimental time series can cause a slight bias in the results.
 
 ## Fitting to different voltage protocols
 
 The next four notebooks discuss different voltage protocols, and the simulation methods appropriate to each one.
 
-- [Combining step protocols with sine waves or ramps](more-protocols-1-steps-and-ramps.ipynb)
+- [Combining step protocols with sine waves or ramps](more-protocols-1-steps-and-ramps.ipynb) - [nbviewer](https://nbviewer.jupyter.org/github/CardiacModelling/fitting-notebooks/blob/main/ion-currents/more-protocols-1-steps-and-ramps.ipynb)
 - [Simulating an AP protocol with "data clamp"](more-protocols-2-data-clamp.ipynb)
 - [Analytical solvers for simple step protocols](more-protocols-3-analytic-solvers.ipynb)
 - [Fitting to multiple simple step protocols](more-protocols-4-multiple-protocols.ipynb)
 
 ## [Setting boundaries on model parameters](boundaries.ipynb)
 
-In this tutorial we show how some parameters can cause numerical issues during simulation, and how we can catch and report these errors.
+In this notebook we show how some parameters can cause numerical issues during simulation, and how we can catch and report these errors.
 We then inspect the model equations and use previous estimates of our parameters (or quantities related to the parameters) to define some very wide boundaries, or "prior estimates".
 Finally, we show how we can use this kind of reasoning to define univariate boundaries (one on each parameter), and multivariate boundaries (which restrict the maximum rate coefficients seen during a simulation).
 
 ## [Selecting starting points for an optimisation](starting-points.ipynb)
 
-Continuing from the previous tutorial, this tutorial shows how we can sample from within the (univariate and multivariate) boundaries to select starting points for an optisiation.
-At the end of this tutorial we briefly discuss a "repeated-fits" strategy which allows you to test the reliability of results obtained on real data, where the "true" parameters are not known.
+Continuing from the previous chapters, this notebook shows how we can sample from within the (univariate and multivariate) boundaries to select starting points for an optisiation.
+At the end of this notebook we briefly discuss a "repeated-fits" strategy which allows you to test the reliability of results obtained on real data, where the "true" parameters are not known.
 
 ## [Searching in a transformed space](transformations.ipynb)
 
-This tutorial shows how you can create wrappers around models and boundaries to run optimisations on a transformed parameter space.
+This notebook shows how you can create wrappers around models and boundaries to run optimisations on a transformed parameter space.
 
 ## [Running big fitting experiments](big-fitting.ipynb)
 
-This tutorial focusses on the practical side of fitting.
+This notebook focusses on the practical side of fitting.
 It introduces methods to store simulation results to disk, load and analyse them, and shows a way to "reserve" filenames when multiple processes are running at once.
 It ends with a brief note on multiprocessing.
 

ion-currents-tutorial/basic-fitting.ipynb → ion-currents/basic-fitting.ipynb

@@ -6,7 +6,7 @@
    "source": [
     "# First steps: a synthetic data study\n",
     "\n",
-    "In this part of the tutorial, we'll take a [myokit.Simulation](https://myokit.readthedocs.io/api_simulations/Simulation.html) and wrap it in a [pints.ForwardModel](https://pints.readthedocs.io/en/latest/core_classes_and_methods.html#forward-model).\n",
+    "In this notebook, we'll take a [myokit.Simulation](https://myokit.readthedocs.io/api_simulations/Simulation.html) and wrap it in a [pints.ForwardModel](https://pints.readthedocs.io/en/latest/core_classes_and_methods.html#forward-model).\n",
     "We'll then use this ForwardModel to generate some data, add synthetic noise, and set up a [pints.SingleOutputProblem](https://pints.readthedocs.io/en/latest/core_classes_and_methods.html#pints.SingleOutputProblem).\n",
     "Finally, we'll define an [ErrorMeasure](https://pints.readthedocs.io/en/latest/error_measures.html#pints.ErrorMeasure) on this problem and use an [Optimiser](https://pints.readthedocs.io/en/latest/optimisers/index.html) to find that parameters that minimise it.\n",
     "\n",
@@ -141,7 +141,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Real voltage-clamp experiments are affected by various noise and error sources (see the \"real data\" part of the tutorial for details).\n",
+    "Real voltage-clamp experiments are affected by various noise and error sources (see the \"Dealing with real data\" notebooks for details).\n",
     "In this example, we'll keep it simple and only add some Gaussian (i.e. normally distributed) noise:"
    ]
   },
@@ -907,14 +907,14 @@
    "source": [
     "## Summary\n",
     "\n",
-    "In this part of the tutorial we have\n",
+    "In this notebook we have\n",
     "\n",
     "- Set up a PINTS problem and defined an error measure\n",
     "- Used an optimisation to find the parameters that minimise this error\n",
     "- Seen the benefits of using a fine tolerance when running simulations\n",
     "- Seen bias in our estimate of the parameters, caused by our finite sampling of noisy data\n",
     "\n",
-    "In the next tutorial we'll look at some more simulation methods, selecting the appropriate types for different models and protocols."
+    "In the next notebook we'll look at some more simulation methods, selecting the appropriate types for different models and protocols."
    ]
   }
  ],
@@ -934,7 +934,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.7"
+   "version": "3.9.5"
   }
  },
  "nbformat": 4,