Debian Codegraph @

docs/autodocs/source/current_clamps.rst

raw
1 :orphan:
2
3 Current Clamp [IClamp] Stimulation
4 ==================================
5
6 One of the most common way to provide stimulus into a network of cells is to directly inject a current
7 into all or a subset of cells. This can be easily done in bmtk using the "**inputs**" section of the
8 `SONATA simulation config <https://alleninstitute.github.io/bmtk/simulators.html#creating-the-environment>`_.
9 For example, to provide an single 0.15 pA injection into all cells starting at 1000 ms and ending at 1500 ms;
10 open the simulation *json* configuration file with your prefered text-editor and add the following subsection
11 to the **inputs** section:
12
13 .. code:: json
14
15 {
16 "inputs" {
17 "current_clamp": {
18 "module": "IClamp",
19 "input_type": "current_clamp",
20 "node_set": "all",
21 "amp": 0.1500,
22 "delay": 1000.0,
23 "duration": 500.0,
24 "section_name": "soma"
25 }
26 }
27 }
28
29 Here "current_clamp" is the name we arbitarily give for this particular input, **module** and **input_type** are
30 specify the type of stimulus we are using, and the other parameters are used to define the attributes of our
31 current clamp (see parameter options below).
32
33 After saving the file and run the simulation we should see the effect of a direct current injection into the
34 soma of our cell model.
35
36 .. figure:: _static/images/iclamp_stim_single.png
37 :scale: 100%
38
39
40 We can also have the option of add multiple independent current clamps in the same simulation, where each one
41 may have a different injection trace, different onset and offset, target different subset of cells or be placed
42 at different locations. For example to apply a series of three different current injections with an increasing
43 amplitude we can just update the json file accordingly
44
45 .. code:: json
46
47 {
48 "inputs" {
49 "current_clamp_1": {
50 "module": "IClamp",
51 "input_type": "current_clamp",
52 "node_set": "all",
53 "amp": 0.1500,
54 "delay": 500.0,
55 "duration": 500.0,
56 "section_name": "soma"
57 },
58 "current_clamp_2": {
59 "module": "IClamp",
60 "input_type": "current_clamp",
61 "node_set": "all",
62 "amp": 0.1750,
63 "delay": 1500.0,
64 "duration": 500.0,
65 "section_name": "soma"
66 },
67 "current_clamp_3": {
68 "module": "IClamp",
69 "input_type": "current_clamp",
70 "node_set": "all",
71 "amp": 0.2000,
72 "delay": 2500.0,
73 "duration": 500.0,
74 "section_name": "soma"
75 }
76 }
77 }
78
79 .. figure:: _static/images/iclamp_stim_multiple.png
80 :scale: 100%
81
82
83 The above is a sequence of different current clamps done in series, but it is possible to have multiple current
84 clamps run in parallel too.
85
86
87 Advanced Stimulus Inputs
88 ------------------------
89
90 Where there are only a few step currents it is easy enough to use the above method of adding mutliple current
91 clamps in series or in parallel. However for more advanced patterns of stimuli - like randomized noise, ramps,
92 sine waves, etc. - the above method becomes impracticle. Instead of just passing in a single step-block, BMTK
93 provides methods for modifying the **input_type** to pass in lists or even external files.
94
95 List of Amplitudes
96 ++++++++++++++++++
97
98 In the above example, instead of using three separate current clamps, we can instead specify just a single one
99 whose amplitudes change over time:
100
101 .. code:: json
102
103 {
104 "inputs" {
105 "current_clamp_list": {
106 "module": "IClamp",
107 "input_type": "current_clamp",
108 "node_set": "biophys_cells",
109 "amp": [0.1500, 0.1750, 2500.0],
110 "delay": [500.0, 0.1500.0, 2500.0],
111 "duration": [500.0, 500.0, 500.0]
112 }
113 }
114 }
115
116 **Note**
117 * Here the "**duration**" is optional and used to set the injection current back to 0. If not specified BMTK will
118 just update the **amp** value of the current injection at the next **delay**
119 * In many siutations like the one above, replace three separate current clamps with a list will produce the same results, however
120 it is not guarenteed.
121
122 Storing Amplitude Traces in a CSV file
123 ++++++++++++++++++++++++++++++++++++++
124
125 For even more complex current injection traces, users can create and pass in a csv file of the trace. The csv file
126 should have two columns, one containing the changes in amplitudes and a corresponding one for the respective onsets, labeled
127 **amps** and **timestamps** respectivly (although this headers can be changed, see options below) with a space delimiter
128 (which can be changed using options below).
129
130
131 .. list-table:: custom_current_traces.csv
132 :widths: 25 25
133 :header-rows: 1
134
135 * - timestamps
136 - amps
137 * - 800.0
138 - 0.1500
139 * - 810.0
140 - 0.1600
141 * - 820.0
142 - 0.1700
143 * - 830.0
144 - 0.1800
145 * - ...
146 - ...
147
148 Then once the file has been saved update the json configuration. To do so we must make sure the **input_type** option is
149 set to *csv*, and instead of options like `amp`, `delay`, and `duration` we just need to point bmtk to the `file` path of
150 our csv:
151
152 .. code:: json
153
154 {
155 "inputs" {
156 "current_clamp_csv": {
157 "module": "IClamp",
158 "input_type": "csv",
159 "node_set": "all",
160 "file": "custom_current_trace.csv"
161 }
162 }
163 }
164
165 Using Allen Cell-Types Database Sweeps
166 ++++++++++++++++++++++++++++++++++++++
167
168 In the `Allen Cell-Types Database <https://celltypes.brain-map.org/data>`_ there is the option to download the ephys
169 nwb files which include "sweeps" of current injection used to classify various cells and optimize the model parameters.
170
171 .. figure:: _static/images/ctdb_sweep_selection.png
172 :scale: 100%
173
174 Using the `Download data` button will download a nwb file containing various "sweeps" (as can be seen using the
175 `select stimulus type` and `Select sweep` buttons). You can recreate these sweeps with BMTK using this downloaded file.
176 As before, we need to update the *json* simulation configuration file, this time setting **input_type** to a value
177 `allen` or `nwb`, specify the `file` path of the nwb, and the `sweep` number to use.
178
179 .. code:: json
180
181 {
182 "inputs" {
183 "current_clamp_nwb": {
184 "module": "IClamp",
185 "input_type": "allen",
186 "node_set": "all",
187 "file": "/626159623_ephys.nwb",
188 "sweep_id": 29,
189 }
190 }
191 }
192
193 IClamp parameters
194 -----------------
195 **module \: string**
196 Should always be set to a value `IClamp`
197
198 **input_type \: string**
199 The format of the input, options: `current_clamp`, `csv`, `file` (same as `csv`), `allen`, or `nwb` (same as `allen`)
200
201 **node_set \: string**, **dict**, or **list**
202 Specify the subset of cells which the injection current will be applied. The default value of `all` will
203 input the same current clamp to "all" cells in the network. Alternatively, you can filter by properties:
204
205 .. code:: python
206
207 "node_set": {
208 "population": "v1"
209 "location": "VisL4",
210 "model": "PValb"
211 }
212
213
214 Or pass in a list of node-ids
215
216 .. code:: python
217
218 "node_set": [0, 100, 200, 300, 400]
219
220
221 **section_name [optional] \: string**
222 For morphologically detailed cells, the section of the cell that the current clamp will be placed. options
223 include `soma`, `axon`, `dend`, `apic`, `other`; default value `soma`
224
225 **section_index [optional] \: integer**
226 For morphologically detailed cells, the NEURON designated branch of the given section where the current clamp will be placed.
227
228 **section_dist [optional] \: float [0, 1)**
229 For morphologically detailed cells, the distance along the branch where the current clamp will be placed.
230
231 **file \: string**
232 When using a `csv` or `nwb` **input_type**, path the file containing current clamp trace (or sweep) and is **[required]**.
233
234
235 |
236
237 *Parameters applicable only to current_clamp input_type*
238
239 **amp \: float**, **list of floats**
240 Amplitudes (pA) of current injection.
241
242 **delay \: float**, **list of floats**
243 Current injections onsets (ms) started from simulation time 0.0
244
245 **duration \: float**, **list of floats**
246 Current injections durations (ms).
247
248
249 |
250
251 *Parameters applicable only to csv input_type*
252
253 **separator [optional] \: string**
254 csv file delimiter used to distinguish columns; defaul " " (single space)
255
256 **timestamps_column [optional] \: string**
257 Header name for column in csv used to specify changes in amplitude values; default `timestamps`
258
259 **amplitudes_column [optional] \: string**
260 Header name for column in csv used to specify ampltidue changes at each given timestep; default `amps`
261
262
263 |
264
265 *Parameters applicable only to allen input_type*
266
267 **sweep_id \: integer**
268 The sweep number of the wanted stimulus pattern found in the nwb file
269
270 **downsample [optional] \: float**
271 When specified, will attempt to downsample the injection current trace. As a good practice it is optimal
272 to set the value to the same as the `dt` in the simulation configuration. Since for most Cell-Type sweeps
273 the rate of current injection changes is typically much smaller than the simulation `dt`.
274
275 **sweep_window [optional] \: [float, float]**
276 Instead of using the full sweep, which is often longer than the simulation time, selection a portion of
277 the sweep time from starting specifying a `0 <= start-time < stop-time < sweep-total-time` (in ms).