request: `ElectricalStimulation`

[bendichter]

Is there a way to store information about electrical stimulation delivered to the brain? What fields would be required? I'm not an expert in this, but I'll get the ball rolling with suggestions:

• electrode_group (references pre-defined electrodes. could be single electrode or multiple)
• bipolar vs. monopolar
• pulse width
• pulse frequency
• pulse amplitude

what's missing?

[bendichter]

@joeyo

[ajtritt]

Are you trying to store patch clamp stimulus?

[bendichter]

I had in mind specifically extracellular stimulation, but patch clamp another important data type. Do we support that currently?

By the way, there's a bit of an unfortunate jargon collision issue here in systems neuroscience. "Stimulus" usually means some sensory experience that is played to the subject (e.g. audio, visual, smell, etc.) and is meant to recreate some aspect of normal experience and see how the brain processes it. "Stimulation" usually refers to an unnatural manipulation that is directly applied to the brain (e.g. electrical pulse, magnetic pulse, light pulse, etc.) in order to alter normal brain activity in a specific way.

edit: it appears from this conversation that my distinction between "stimulus" and "stimulation" may not be universal

[joeyo]

I think I'd argue against storing stimulus features explicitly (amplitude of this, pulse-width of that).

Here are two alternative ways:

• Save the sample-by-sample shape of the stimulus waveform pulse(s), and the times when each pulse was delivered. This would work something like the IndexSeries: you create an alphabet that spans the variety of used pulses and store the indices to those pulses when they were delivered. This would be space-efficient.
• Store the actual commanded current (or voltage) at each time t. This would be the most general and would allow for non-pulsatile stimulation (sinusoidal, sawtooth, Bart-simpsons-head-shape, etc), but would take more space.

Electrode-group would be needed in either case to link the stimulation protocol to electrodes.

[neuromusic]

related: @campagnola's project for the next hackathon: https://github.com/orgs/NeurodataWithoutBorders/teams/stimulusmeta

[bendichter]

Thanks @joeyo, this is exactly why I brought you in :-).

@joeyo, it seems from @neuromusic's link that there are some cases where your option 1 might be difficult to achieve or might fail. For example, compositions of pulse styles, changing pulse styles, so option 2 seems like a safer bet.

I think your own data from your Nature paper wouldn't fit it require pulse pulse times instead of frequency because of a changing pulse frequency. Maybe the best approach here would be to give the option of specifying times or a start_time and frequency, which is a pattern that is already used in TimeSeries.

I'd still like to store some kind of information about the stimulation in a queryable way (e.g. find all sessions with extracellular bipolar square-pulse stimulations with amplitude > x). Do you think a system is possible that would facilitate this? Perhaps it would be in addition to your option 2?

[joeyo]

Is there a publicly available link for "stimulusmeta" ?

For rectangular pulses you'd minimally need:

• phase-1 pulse-width
• phase-1 amplitude
• inter-phase-interval
• phase-2 pulse-width
• phase-2 amplitude to describe a single pulse. Set one of the phases to zero to get monophasic stimulation. In the general case, you could allow up to k-phases, though in practice nobody is likely to use pulses of above tri-phasic.

That could be something like:

• phase-1, amp-1
• phase-2, amp-2 ...
• phase-k, amp-k and setting a phase to zero-amplitude would allow for interphase-interval.

For regular pulse-trains you can get away with just defining a single Pulse Repetition Rate, or equivalently an inter-pulse interval. One could imagine defining a nested structure to describe complicated temporal sequences of pulses and groups of pulses, but the complexity quickly reaches the point where you'll be better off with my option 1, above.

[bendichter]

haha this is quickly turning into the description from the link that you can't see. Here's the description:

Schema extensions / changes to allow more flexible description of stimulus protocols, with a focus on being able to compose the description from multiple independent elements. May devolve into a more general exercise of investigating object composition vs inheritance in NWB.

As an example of the problem to be solved, imagine a typical current-clamp recording in which a single square pulse stimulus is applied to the cell. This stimulus has a few properties: start_time, amplitude, and duration. One way to describe this is to create a schema extension with a class called CurrentClampPulseSeries that extends currentClampStimulusSeries and adds the three properties listed above.

The problem with this approach is that it is not straightforward to describe an experiment with two (or more) different stimuli in a single sweep. For example, a sweep that has a square pulse followed by a ramp. Ideally this should be solvable by composing the stimulus information together (like: "stimulus has a pulse and a ramp") rather than by creating an entirely new class to describe this specific combination (like: "stimulus is a pulse and a ramp"). In other words we want to use composition rather than inheritance (this topic is extensively discussed on the web, for example https://en.wikipedia.org/wiki/Composition_over_inheritance). This problem is further exacerbated by the multiple base classes that might want to include these stimuli--CurrentClampStimulusSeries and VoltageClampStimulusSeries would each need their own per-stimulus subclasses, and we can imagine other types of stimulus (eg. laser modulation, extracellular stimulation) that would benefit from having access to these descriptions as well.

[oruebel]

related: @campagnola's project for the next hackathon: https://github.com/orgs/NeurodataWithoutBorders/teams/stimulusmeta

I agree with @neuromusic that this topic fits well with this project, so we should probably move this discussion there.

Just to add a couple of pointers to what is currently in the schema (take these with a grain of salt):

Save the sample-by-sample shape of the stimulus waveform pulse(s)

I think this what /stimulus/templates is for, which stores template TimeSeries describing a stimulus. See http://nwb-schema.readthedocs.io/en/latest/format.html#groups-stimulus-templates

Store the actual commanded current (or voltage) at each time t

I think this is what stimulus/presentations is for, which stores TimeSeries describing stimulus presentations. See http://nwb-schema.readthedocs.io/en/latest/format.html#groups-stimulus-presentation

I'd still like to store some kind of information about the stimulation in a queryable way (e.g. find all sessions ...

Note, NWB assumes a global clock, i.e., the timestamps of the TimerSeries describing a stimulus presentation are expected to be aligned with the TimeSeries of your recordings. Sessions are typically stored in separate NWB files so that you can simply do the query based on what stimulus data is in a file. If you'd add multiple sessions to a single file, the you'd probably need to inspect the timestamps of stimulus data as well. I'm not exactly sure if there are any more specific associations (in addition to the time alignment) to link a stimulus to a specific timeseries in the current schema.

patch clamp another important data type. Do we support that currently?

There are a couple of types for patch clamp data in the schema, specifically there are a number of types that derive from PatchClampSeries as a base type (e.g., CurrentClampSeries, IZeroClampSeries, CurrentClampStimulusSeries, VoltageClampSeries, VoltageClampStimulusSeries)

[oruebel]

Should we close this issue and move the discussion over to the hackathon project? If that's Ok than @nicain could just add @bendichter and @joeyo to that project thread.

[neuromusic]

is there some way to open up the hackathon project discussions publicly so folks like @joeyo can view them?

[bendichter]

CurrentClampStimulusSeries, VoltageClampStimulusSeries

I believe current and voltage clamped extra-cellular stimulation would have very similar specs to these. Are there any important differences?

[joeyo]

No so similar unless you squint: patch clamping necessarily implies recording a signal while providing a fixed/clamped voltage or current, where as electrical stimulation does not necessarily require any measurements. It's more similar in some ways to OptogeneticSeries.

[campagnola]

I didn't realize discussions are not publicly readable! I don't think it makes any sense for us to have discussions in the dark; even after this issue is resolved, people outside the org need to be able to read this trail to understand how we came to our decisions.

[oruebel]

@campagnola I think the team forum is mainly good for internal discussions to allow you to scope out, define, and plan the project for the hackathon. Technical details should go on the project page for the project. I think you could also create a public issue on the hackathon repo if you want to have a public discussion about the project.

[campagnola]

Ok, new issue opened https://github.com/NeurodataWithoutBorders/nwb-schema/issues/131 over the broader issue of stimulus metadata; I will close the internal discussion.