add example in tutorial for adding stimulus template data

docs/gallery/domain/plot_icephys.py

@@ -97,6 +97,7 @@
 
 # Import additional core datatypes used in the example
 from pynwb.core import DynamicTable, VectorData
+from pynwb.base import TimeSeriesReferenceVectorData
 
 # Import icephys TimeSeries types used
 from pynwb.icephys import VoltageClampSeries, VoltageClampStimulusSeries
@@ -457,6 +458,38 @@
     category="electrodes",
 )
 
+#####################################################################
+# One predefined subcategory column is the stimulus template column in the stimuli table. This column can be used to
+# store stimulus template waveforms that were generated by the recording software. Similar to the stimulus and response
+# columns, we can specify a relevant time range.
+
+nwbfile.intracellular_recordings.add_column(
+    name="stimulus_template",
+    data=[(0, 5, stimulus),  # (start_index, index_count, stimulus_template) can be specified as a tuple
+          (1, 3, stimulus),
+          (-1, -1, stimulus)],
+    description="Column storing the reference to the stimulus template for the recording (rows).",
+    category="stimuli",
+    col_cls=TimeSeriesReferenceVectorData
+)
+
+# we can also add stimulus template data as follows
+rowindex = nwbfile.add_intracellular_recording(
+    electrode=electrode,
+    stimulus=stimulus,
+    stimulus_template=stimulus,  # the full time range of the stimulus template will be used unless specified
+    recording_tag='A4',
+    recording_lab_data={'location': 'Isengard'},
+    electrode_metadata={'voltage_threshold': 0.14},
+    id=13,
+)
+
+#####################################################################
+# .. note:: If a stimulus template column exists but there is no stimulus template data for that recording, then the
+#           stimulus template will be internally set to the provided stimulus or response TimeSeries and the start_index
+#           and index_count for the missing parameter are set to -1. The missing values will be represented via masked
+#           numpy arrays.
+
 #####################################################################
 # Add a simultaneous recording
 # ---------------------------------