Merge pull request #350 from neurodsp-tools/data_info

[MNT] - Update example data file info & usage

data/README.txt

@@ -1,4 +1,15 @@
 Data
 ====
 
-Example and test data files for NeuroDSP.
+Example and test data files for NeuroDSP.
+
+The following data files are made available with the module, for use in the tutorials:
+- `sample_data_1`: a segment of human primary motor cortex (M1)
+    - Data sample is from a DBS device implanted in a patient with Parkinson's Disease
+    - The data sample is 10 seconds from a single channel, sampled at 1000 Hz
+    - For more information on the data, see Cole et al, 2017 (https://doi.org/10.1523/JNEUROSCI.2208-16.2017)
+- `sample_data_1_filt`: same data as `sample_data_1`, that has been filtered in the beta range (13-30 Hz)
+- `sample_data_2`: a segment of rat hippocampal LFP data
+    - The data sample is 150 seconds from a single channel, sampled at 1000 Hz
+    - Data file is from the publicly available 'hc2' dataset from CRCNS (https://crcns.org/)
+    - For more information on the data, see Mizuseki et al, 2012 (https://doi.org/10.1038/nn.2894)

tutorials/rhythm/plot_LaggedCoherence.py

@@ -257,7 +257,6 @@
 
 # Download, if needed, and load example data file
 sig = load_ndsp_data('sample_data_1.npy', folder='data')
-sig_filt_true = load_ndsp_data('sample_data_1_filt.npy', folder='data')
 
 # Set sampling rate, and create a times vector for plotting
 fs = 1000

tutorials/spectral/plot_SpectralPower.py

@@ -31,10 +31,7 @@
 # Load example neural signal
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~
 #
-# First, we load the sample data, which is a segment of rat hippocampal LFP
-# taken from the publicly available database CRCNS (specifically, from the 'hc2' dataset).
-#
-# Relevant publication: Mizuseki et al, 2012, Nature Neuro
+# First, we load the sample data, an example channel of rat hippocampal LFP data.
 #
 
 ###################################################################################################

tutorials/spectral/plot_SpectralVariance.py

@@ -34,10 +34,7 @@
 # Load example neural signal
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~
 #
-# First, we load the sample data, which is a segment of rat hippocampal LFP
-# taken from the publicly available database CRCNS (specifically, from the 'hc2' dataset).
-#
-# Relevant publication: Mizuseki et al, 2012, Nature Neuro
+# First, we load the sample data, an example channel of rat hippocampal LFP data.
 #
 
 ###################################################################################################

tutorials/timefreq/plot_InstantaneousMeasures.py

@@ -13,6 +13,9 @@
 
 import matplotlib.pyplot as plt
 
+# Import filter function
+from neurodsp.filt import filter_signal
+
 # Import time-frequency functions
 from neurodsp.timefrequency import amp_by_time, freq_by_time, phase_by_time
 
@@ -32,7 +35,6 @@
 
 # Load a neural signal, as well as a filtered version of the same signal
 sig = load_ndsp_data('sample_data_1.npy', folder='data')
-sig_filt_true = load_ndsp_data('sample_data_1_filt.npy', folder='data')
 
 # Set sampling rate, and create a times vector for plotting
 fs = 1000
@@ -49,9 +51,27 @@
 
 ###################################################################################################
 
-# Plot signal
+# Plot original signal
 plot_time_series(times, sig)
 
+###################################################################################################
+#
+# Throughout this example, we will be examining instantaneous measures computed on the beta band.
+#
+# Here, we first compute a filtered version of our signal in the beta band, which we can
+# use for visualization purposes.
+#
+
+###################################################################################################
+
+# Filter the signal into the range of interest, to use for plotting
+sig_filt = filter_signal(sig, fs, 'bandpass', f_range)
+
+###################################################################################################
+
+# Plot filtered signal
+plot_time_series(times, sig_filt)
+
 ###################################################################################################
 # Instantaneous Phase
 # -------------------
@@ -60,6 +80,11 @@
 #
 # Instantaneous phase can be analyzed with the :func:`~.phase_by_time` function.
 #
+# Note that here we are passing in the original, unfiltered signal as well as the frequency
+# range of interest. In doing so, the signal will be filtered prior to the instantaneous
+# measure being computed. You can also pass in a pre-filtered signal - if so, a frequency
+# range is not needed.
+#
 
 ###################################################################################################
 
@@ -68,9 +93,9 @@
 
 ###################################################################################################
 
-# Plot example signal
+# Plot example signal, comparing filtered trace and estimated instantaneous phase
 _, axs = plt.subplots(2, 1, figsize=(15, 6))
-plot_time_series(times, sig, xlim=[4, 5], xlabel=None, ax=axs[0])
+plot_time_series(times, sig_filt, xlim=[4, 5], xlabel=None, ax=axs[0])
 plot_instantaneous_measure(times, pha, colors='r', xlim=[4, 5], ax=axs[1])
 
 ###################################################################################################
@@ -94,7 +119,7 @@
 plot_instantaneous_measure(times, [sig, amp], 'amplitude',
                            labels=['Raw Signal', 'Amplitude'],
                            xlim=[4, 5], xlabel=None, ax=axs[0])
-plot_instantaneous_measure(times, [sig_filt_true, amp], 'amplitude',
+plot_instantaneous_measure(times, [sig_filt, amp], 'amplitude',
                            labels=['Filtered Signal', 'Amplitude'], colors=['b', 'r'],
                            xlim=[4, 5], ax=axs[1])
 
@@ -124,7 +149,7 @@
 # Plot example signal
 _, axs = plt.subplots(3, 1, figsize=(15, 9))
 plot_time_series(times, sig, 'Raw Signal', xlim=[4, 5], xlabel=None, ax=axs[0])
-plot_time_series(times, sig_filt_true, labels='Beta Filtered Signal',
+plot_time_series(times, sig_filt, labels='Beta Filtered Signal',
                  colors='b', xlim=[4, 5], xlabel=None, ax=axs[1])
 plot_instantaneous_measure(times, i_f, 'frequency', label='Instantaneous Frequency',
                            colors='r', xlim=[4, 5], ylim=[10, 30], ax=axs[2])