Skip to content

Finish model tour #18

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MichaelClerx merged 2 commits into from
Mar 19, 2026
Merged

Finish model tour #18

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
65a1b33
Cosmetic fix to level 0 schematic
MichaelClerx Mar 19, 2026
0f91312
Finished model tour. Closes #3. Closes #4. Closes 16.
MichaelClerx Mar 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 7 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@
This repository contains up-to-date reference versions of the voltage clamp model developed in Lei et al. 2020 and 2025.
These models can be used to simulate manual or planar patch-clamp experiments in voltage-clamp mode.

_Note: This URL originally hosted the data for the 2020 Lei et al. publication. This is now found at https://github.com/CardiacModelling/VoltageClampModel2020_
_Note: This URL originally hosted data and code for the 2020 Lei et al. publication. This is now found at https://github.com/CardiacModelling/VoltageClampModel2020_

## The latest models

We recently updated the voltage clamp model with improved filtering of input (stimulus filter) and output (Bessel filters), and an improved time-delay in the series resistance compensation pathway.
We recently updated the voltage clamp model with improved filtering of input (stimulus filter) and output, and an improved time-delay in the series resistance compensation pathway.

In addition to this full-featured model, we provide a set of increasingly simplified models:

Expand All @@ -26,14 +26,15 @@ All models are provided in Myokit ([models-mmt](./models-mmt)) and CellML ([mode

In brief:
- Levels 0, 1, and 2 can recreate the _fast_ artefacts seen in patch clamp experiments, and are very useful _to understand the patch clamp process_.
- _To fit experimental data_, these fast artefacts are less important, and so level 3 is good to match data from the fastest currents. For slower currents, levels 4 or 5 can be used.
- _To fit experimental data_, these fast artefacts are less important, and so level 3 is good to match data from the fastest currents.
For slower currents, levels 4 or 5 can be used.

## Tutorials

We provide four [Tutorial Notebooks](./tutorial/README.md) to understand these notebooks, and how they were derived.
We provide four [Tutorial Notebooks](./tutorial/README.md) to understand these models, and how they were derived.

The first notebook establishes a basic model of a patch clamp amplifier, and the second adds compensation and filtering, leading to the "Level 0" model.
In the third notebook, this model is used to simulate the early stages of a (manual) patch-clamp experiment.
In the third notebook, this model is used to simulate a manual patch-clamp experiment.

The final notebook derives the Level 1 to 5 simplifications, and shows how they relate to our previous work (Lei et al., 2020 and 2025).

Expand Down Expand Up @@ -91,5 +92,5 @@ Code: https://github.com/CardiacModelling/VoltageClampModel2020

## Acknowledging this work

If you publish any work based on the contents of this repository please cite the papers listed above.
If you use the contents of this repository in your work, please cite the papers listed above.

8 changes: 4 additions & 4 deletions tutorial/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# Voltage clamp model tutorials

In these notebooks we retrace the steps taken in the supplement to [Lei et al., 2020](https://doi.org/10.1098/rsta.2019.0348) and [2025](https://doi.org/10.1002/advs.202500691), and construct (1) a model of a patch-clamp experiment with various experimental artefacts, and (2) a model of the corrections applied by patch-clamp amplifiers to mitigate these effects.
In these notebooks we construct (1) a model of a patch-clamp experiment with various experimental artefacts, and (2) a model of the corrections applied by patch-clamp amplifiers to mitigate these effects.
The initial exposition draws on a book chapter by [Sigworth (1995a)](https://doi.org/10.1007/978-1-4419-1229-9_4), but replaces Laplace-domain analysis with an ODE formulation.

To view the notebooks, use the GitHub or nbviewer links below, or clone the repository and run jupyter notebook locally.
To view the notebooks, use the GitHub or nbviewer links below, or clone the repository and run Jupyter notebook locally.
Running locally will require the dependencies from `requirements.txt`.

A list of references and further reading is provided [here](./references.ipynb).
Expand All @@ -30,8 +30,8 @@ The model is updated to include the compensation circuitry commonly used in patc
We walk through and simulate the early steps of a manual patch-clamp experiment.

## Simplified models
[![github](./img/github.svg)](./4-simplified.ipynb)
[![nbviewer](./img/nbviewer.svg)](https://nbviewer.jupyter.org/github/CardiacModelling/VoltageClampModel-new/tree/main/tutorial/4-simplified.ipynb)
[![github](./img/github.svg)](./4-simplifications.ipynb)
[![nbviewer](./img/nbviewer.svg)](https://nbviewer.jupyter.org/github/CardiacModelling/VoltageClampModel-new/tree/main/tutorial/4-simplifications.ipynb)

In the final notebook, we derive simplified models and compare with previous work.

Expand Down
Binary file modified tutorial/img/vc-level-0.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
122 changes: 53 additions & 69 deletions tutorial/tour.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,10 @@
"source": [
"# A quick tour of voltage-clamp models\n",
"\n",
"The voltage-clamp models are available in different levels of detail, ranging from the \"full\" model (level 0) to a greatly simplified one (level 5).\n",
"The model is available in different levels of detail, ranging from the \"full\" model (level 0) to a greatly simplified one (level 5).\n",
"Here, we provide a quick tour of the most important models, and provide guidance for setting parameter values.\n",
"\n",
"_This notebook presents, but does not derive or explain the models. For that, please see the tutorial notebooks_."
"_This notebook presents, but does not derive or explain the models. For that, please see the Tutorial Notebooks_."
]
},
{
Expand All @@ -26,7 +26,7 @@
"\n",
"It includes:\n",
"\n",
"- A voltage offset $E^\\dagger_\\text{off}$, representing the remaining voltage error after zeroing\n",
"- A voltage offset $E^\\dagger_\\text{off}$ representing the remaining voltage error after zeroing\n",
"- A leak current $I_\\text{leak}$\n",
"- The effect of series resistance $R_s$ on the membrane potential\n",
"- Series resistance compensation, $\\alpha$, and prediction, $\\beta$, both specified as fractions between 0 and 1."
Expand All @@ -53,26 +53,26 @@
"id": "6d59f32b-7b30-4c3e-b4a2-0484d787cf74",
"metadata": {},
"source": [
"| Variable | Units | Meaning |\n",
"|-----------------|-------|-----------------------------------------------------------|\n",
"| $V_m$ | mV | Membrane potential |\n",
"| $V_c$ | mV | The command potential, set by the voltage clamp protocol |\n",
"| $I$ | pA | The ionic current |\n",
"| $I_\\text{obs}$ | pA | The observed (measured/output) current |\n",
"| $I_\\text{leak}$ | pA | A leak current, e.g. $g_\\text{leak}(V_m - I_\\text{leak})$ |\n",
"| Variable | Units | Meaning |\n",
"|-----------------|-------|---------------------------------------------------------|\n",
"| $V_m$ | mV | Membrane potential |\n",
"| $V_c$ | mV | Command potential, set by the voltage clamp protocol |\n",
"| $I$ | pA | Ionic current |\n",
"| $I_\\text{obs}$ | pA | Observed (measured/output) current |\n",
"| $I_\\text{leak}$ | pA | Leak current, e.g. $g_\\text{leak}(V_m - I_\\text{leak})$ |\n",
"\n",
"The variables $I$ and $I_\\text{leak}$ should be supplied by an ionic current model and leak model, respectively.\n",
"The variables $I$ and $I_\\text{leak}$ should be supplied by an ionic current model and a leak model, respectively.\n",
"\n",
"| Parameter | Units | Meaning | Typical value |\n",
"|-----------|-----------|-----------------------------------------------------|-----------------|\n",
"| $C_m$ | pF | The cell capacitance, from the amplifier estimate | 25 pF |\n",
"| $R_s$ | G$\\Omega$ | The series resistance, from the amplifier estimate | 0.005 G$\\Omega$ |\n",
"| $C_m$ | pF | Cell capacitance, from the amplifier estimate | 25 pF |\n",
"| $R_s$ | G$\\Omega$ | Series resistance, from the amplifier estimate | 0.005 G$\\Omega$ |\n",
"| $\\alpha$ | - | Fraction of $R_s$ compensation, read from amplifier | 0.7 |\n",
"| $\\beta$ | - | Fraction of $R_s$ compensation, read from amplifier | 0.7 |\n",
"| $\\beta$ | - | Fraction of $R_s$ prediction, read from amplifier | 0.7 |\n",
"| $E^\\dagger_\\text{off}$ | mV | Remaining voltage offset after zeroing | 0 mV |\n",
"\n",
"In a simple simulation $E^\\dagger_\\text{off}$ is chosen by the user.\n",
"In inference settings, $E^\\dagger_\\text{off}$ may be a parameter inferred from the data."
"In inference settings it may be a parameter inferred from the data."
]
},
{
Expand All @@ -93,7 +93,7 @@
"This level adds\n",
"\n",
"- A distinction between estimated and true membrane capacitance and series resistance\n",
"- A state-estimator used to approximate $V_e$ in the \"prediction\" pathway"
"- A state-estimator used to approximate $V_m$ in the prediction pathway"
]
},
{
Expand Down Expand Up @@ -121,20 +121,20 @@
"source": [
"New or changed variables and parameters are\n",
"\n",
"| Variable | Units | Meaning |\n",
"|----------|-------|-------------------------------------------------------|\n",
"| $V_e$ | mV | An estimate of $V_m$ used in the \"prediction\" pathway |\n",
"| Variable | Units | Meaning |\n",
"|----------|-------|--------------------------------------------------|\n",
"| $V_e$ | mV | Estimate of $V_m$ used in the prediction pathway |\n",
"\n",
"And\n",
"\n",
"| Parameter | Units | Meaning | Typical value |\n",
"|-----------|-----------|---------------------------------------------------------|-----------------|\n",
"| $C_m$ | pF | The true cell capacitance, unknown in real experiments | 25 pF |\n",
"| $C^*_m$ | pF | The estimated cell capacitance, read from amplifier | 25 pF |\n",
"| $R_s$ | G$\\Omega$ | The true series resistance, unknown in real experiments | 0.005 G$\\Omega$ |\n",
"| $R^*_s$ | G$\\Omega$ | The series resistance, read from amplifier | 0.005 G$\\Omega$ |\n",
"| Parameter | Units | Meaning | Typical value |\n",
"|-----------|-----------|--------------------------------------------------|-----------------|\n",
"| $C_m$ | pF | True cell capacitance, unknown | 25 pF |\n",
"| $C^*_m$ | pF | Estimated cell capacitance, read from amplifier | 25 pF |\n",
"| $R_s$ | G$\\Omega$ | True series resistance, unknown | 0.005 G$\\Omega$ |\n",
"| $R^*_s$ | G$\\Omega$ | Estimated series resistance, read from amplifier | 0.005 G$\\Omega$ |\n",
"\n",
"For a straightforward simulation, $C_m$ and $R_s$ can be chosen by the user.\n",
"For a straightforward simulation, $C_m$ and $R_s$ are chosen by the user.\n",
"In an inference setting, $C_m$ and $R_s$ may be inferred from the data long with $E^\\dagger_\\text{off}$."
]
},
Expand Down Expand Up @@ -197,22 +197,21 @@
"source": [
"New variables and parameters are\n",
"\n",
"| Variable | Units | Meaning |\n",
"|----------|-------|-------------------------------------------------------------|\n",
"| $V_r$ | mV | The voltage on one side of the measurement electrode |\n",
"| $V_s$ | mV | The filtered command potential |\n",
"| $V_rc$ | mV | The filtered voltage used in series resistance compensation |\n",
"| $V_s$ | mV | The voltage on one side of the measurement electrode |\n",
"| $I_1$ | pA | The output current before filtering |\n",
"| Variable | Units | Meaning |\n",
"|---------------|-------|---------------------------------------------|\n",
"| $V_r$ | mV | Reference voltage set by the voltage clamp |\n",
"| $V_s$ | mV | Filtered command potential |\n",
"| $V_\\text{rc}$ | mV | Filtered voltage used in $R_s$ compensation |\n",
"| $I_1$ | pA | Unfiltered output current |\n",
"\n",
"And\n",
"\n",
"| Parameter | Unit | Meaning | Typical value |\n",
"|------------------|-----------|------------------------------------------------------------|---------------|\n",
"| $\\tau_\\text{RC}$ | ms | Time constant of filter in series resistance compenstation, read from amplifier|0.01 ms|\n",
"| $\\tau_s$ | ms | Time constant of stimlus filter, estimated from fits | 0.025 ms |\n",
"| $\\tau_o$ | ms | Time constant of 1st order approximation of output filter | 0.01 ms |\n",
"| $R_f$ | G$\\Omega$ | The measurement resistor, found in headstage documentation | 0.5 G$\\Omega$ |\n",
"| Parameter | Units | Meaning | Typical value |\n",
"|------------------|-----------|----------------------------------------------------|---------------|\n",
"| $\\tau_\\text{RC}$ | ms | Time constant of filter in $R_s$ compenstation, read from amplifier|0.01 ms|\n",
"| $\\tau_s$ | ms | Time constant of stimulus filter, unknown | 0.025 ms |\n",
"| $\\tau_o$ | ms | Time constant of output filter, see below | 0.01 ms |\n",
"| $R_f$ | G$\\Omega$ | Measurement resistor, from headstage documentation | 0.5 G$\\Omega$ |\n",
"\n",
"To estimate $\\tau_s$ in a real amplifier, you can record the filtered output voltage and fit to it.\n",
"The value above corresponds to the \"slow\" (default) setting on a HEKA EPC-10.\n",
Expand All @@ -235,7 +234,7 @@
"\n",
"This level adds\n",
"\n",
"- A pipette (conventional patch clamp) or parasitic (planar patch clamp) capacitance $C_p$, and its amplifier estimate $C^*p$\n",
"- A pipette (conventional patch clamp) or parasitic (planar patch clamp) capacitance $C_p$, and its amplifier estimate $C^*_p$\n",
"- A stray capacitance on the measurement resistor $\\tilde{C}_f$, and a finite op-amp speed with time constant $\\tau_a$\n",
"- A two-part output filter, where \"Filter 1\" affects series resistance compensation, while \"Filter 2\" does not.\n",
"- Arbitrary equations for the output filters and the stimulus filter (allowing e.g. Bessel formulations)"
Expand Down Expand Up @@ -293,42 +292,27 @@
"id": "7cc410ae-a332-4fdd-9f04-459790d43ef2",
"metadata": {},
"source": [
"# TODO\n",
"\n",
"New variables and parameters are\n",
"\n",
"| Variable | Units | Meaning |\n",
"|----------|-------|-------------------------------------------------------------|\n",
"| $V_r$ | mV | The voltage on one side of the measurement electrode |\n",
"| $V_s$ | mV | The filtered command potential |\n",
"| $V_rc$ | mV | The filtered voltage used in series resistance compensation |\n",
"| $V_s$ | mV | The voltage on one side of the measurement electrode |\n",
"| $I_1$ | pA | The output current before filtering |\n",
"| Variable | Units | Meaning |\n",
"|----------|-------|------------------------|\n",
"| $V_o$ | mV | Op-amp output voltage |\n",
"| $V_p$ | mV | Pipette potential |\n",
"| $V_1$ | mV | Voltage after filter 1 |\n",
"| $V_2$ | mV | Voltage after filter 2 |\n",
"\n",
"And\n",
"\n",
"| Parameter | Unit | Meaning | Typical value |\n",
"|------------------|-----------|------------------------------------------------------------|---------------|\n",
"| $\\tau_\\text{RC}$ | ms | Time constant of filter in series resistance compenstation, read from amplifier|0.01 ms|\n",
"| $\\tau_s$ | ms | Time constant of stimlus filter, estimated from fits | 0.025 ms |\n",
"| $\\tau_o$ | ms | Time constant of 1st order approximation of output filter | 0.01 ms |\n",
"| $R_f$ | G$\\Omega$ | The measurement resistor, found in headstage documentation | 0.5 G$\\Omega$ |\n",
"And\n",
"\n",
"To estimate $\\tau_s$ in a real amplifier, you can record the filtered output voltage and fit to it.\n",
"The value above corresponds to the \"slow\" (default) setting on a HEKA EPC-10.\n",
"| Parameter | Units | Meaning | Typical value |\n",
"|---------------|-------|----------------------------------------------------|---------------|\n",
"| $C_p$ | pF | True pipette capacitance, unknown | 5 pF |\n",
"| $C^*_p$ | pF | Estimated pipette capacitance, read from amplifier | 5 pF |\n",
"| $\\tilde{C}_f$ | pF | Compensated stray capacitance on measuring resistor, unknown | 5e-3 pF |\n",
"| $\\tau_a$ | ms | Time constant of measurement op-amp, unknown | 13e-6 ms |\n",
"\n",
"To estimate $\\tau_o$, you can use $\\tau_o \\approx \\frac{1}{2 \\pi f}$, where $f$ is the filter's cut-off frequency in kHz.\n",
"\n",
"Note that exact values of $\\tau_s$ and $\\tau_o$ are seldom crucial."
"The given values of $\\tilde{C}_f$ and $\\tau_a$ were estimated by fitting to model cell experiments with a Heka EPC-10."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "2332084c-5e5d-4dc1-aed9-fdc3019ffe8b",
"metadata": {},
"outputs": [],
"source": []
}
],
"metadata": {
Expand Down