diff --git a/README.md b/README.md index 85762ae..f85ed1f 100644 --- a/README.md +++ b/README.md @@ -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: @@ -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). @@ -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. diff --git a/tutorial/README.md b/tutorial/README.md index 4d73918..1f360c6 100644 --- a/tutorial/README.md +++ b/tutorial/README.md @@ -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). @@ -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. diff --git a/tutorial/img/vc-level-0.png b/tutorial/img/vc-level-0.png index b16aec7..39904ef 100644 Binary files a/tutorial/img/vc-level-0.png and b/tutorial/img/vc-level-0.png differ diff --git a/tutorial/tour.ipynb b/tutorial/tour.ipynb index 6192c3e..ef4bc03 100644 --- a/tutorial/tour.ipynb +++ b/tutorial/tour.ipynb @@ -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_." ] }, { @@ -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." @@ -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." ] }, { @@ -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" ] }, { @@ -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}$." ] }, @@ -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", @@ -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)" @@ -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": {