2.5.3 plotGroupTraces()

Overview

Input a signal array, plot multiple grouped traces based on user input. Can be used in Session/Experiment analysis phase.

Inputs and options

Required inputs

• traces: double, array where each row is an individual trial aligned to a given event, column is each time point.
• timestampdouble, a vector where each element (ie column) is the time on x axis. Should have the same number of columns as traces.
• colormap: color map for all the traces
  • Color of traces will be evenly distributed along the colormap based on the number of groups.

Options

• groupby
  • string, default is 'trials'
  • groupby determines how individual rows in traces are combined together. The default is grouped by trials (groupby='trials' or 'trial'), but you can also grouped by sessions (groupby='sessions' or 'session') or animals (groupby='animals' or 'animal').
  • When groupby=='trials', you need to provide either groupSize or nGroups for the function to run. If you provide both, plotGroupTraces will plot to the maximum number of groups based on groupSize. Thus, for a input with 50 trials and groupSize = 10, the function will automatically plot 5 lines even when nGroups=10.
    • When startIdx is not provided, then just follow user's groupSize or nGroups input.
    • When startIdx or animalStartIdx is provided, reorganize array traces into cells with each element containing traces from the same animal. Then plot traces across animals of the same trial together. Use cases include plotting 20-45th trials of stimulation trials for all animals.
  • When groupby=='sessions', each traces will be the same session across all animals (e.g. session 1 of all animals combined)
  • When groupby=='animals', each traces will be the same animal across all sessions (e.g. all sessions of animal 1 combined)
• groupSize and nGroups
  • double
  • You need to provide either groupSize or nGroups for the function to run when groupby=='trials'. Input not required otherwise.
• remaining
  • string, default is 'include'
  • When groupby=='trials', there inevitably will be some traces that does not fully form a group (eg 5 traces remaining for a groupSize of 50 traces). These traces, if plotted separately, can induce lines with great variations and error bars. To address this, one can either set remaining='include' to include these traces to prev group; set to remaining='exclude' to not plot these traces, or remaining='separate' if you really want to plot these traces separately

Outputs

• legendList: cell, corresponding to legend of each line

Examples

1. To use it in session analysis phase

initializeFig(1,1);
timeRange = [-1,5];
[traces,t] = plotTraces(waterIdx,timeRange,signal,bluePurpleRed(1,:),params); % Extract event-aligned traces
legendList = plotGroupTraces(traces,t,bluePurpleRed,groupSize=10); % Plot traces where each line is the average of 10 trials
plotEvent('Water',0);
xlabel('Time (s)'); ylabel('z-score');
legend(legendList);

2. To use it in experiment analysis phase, groupby='trial'

initializeFig(.5,.5);
combined = combineTraces(animals,timeRange=[-0.5,3],...
                              eventRange='Pair',...
                              taskRange='Reward1',...
                              signalRange='NAc');
legendList = plotGroupTraces(combined.data{1},combined.timestamp,bluePurpleRed,...
                        groupSize=50,nGroups=15,...
                        groupby='trials',startIdx=combined.options.startIdx);
plotEvent(eventRange{event},.5,color=bluePurpleRed(500,:));
xlabel('Time (s)'); ylabel('NAc z-score');
legend(legendList,'Location','northeast');

3. To use it in experiment analysis phase, groupby='animal'

initializeFig(.5,.5);
combined = combineTraces(animals,timeRange=[-0.5,3],...
                              eventRange='Pair',...
                              taskRange='Reward1',...
                              signalRange='NAc');
legendList = plotGroupTraces(combined.data{1},combined.timestamp,bluePurpleRed,...
                        groupSize=50,nGroups=15,...
                        groupby='animals',startIdx=combined.options.startIdx);
plotEvent(eventRange{event},.5,color=bluePurpleRed(500,:));
xlabel('Time (s)'); ylabel('NAc z-score');
legend(legendList,'Location','northeast');

4. To use it in experiment analysis phase, groupby='session'

initializeFig(.5,.5);
combined = combineTraces(animals,timeRange=[-0.5,3],...
                              eventRange='Pair',...
                              taskRange='Reward1',...
                              signalRange='NAc');
legendList = plotGroupTraces(combined.data{1},combined.timestamp,bluePurpleRed,...
                        groupSize=50,nGroups=15,...
                        groupby='session',startIdx=combined.options.startIdx);
plotEvent(eventRange{event},.5,color=bluePurpleRed(500,:));
xlabel('Time (s)'); ylabel('NAc z-score');
legend(legendList,'Location','northeast');

5. Examples for remaining='include': note that the last line includes more trials comparing to others

combined = combineTraces(animals,timeRange=[-0.5,3],...
                              eventRange='Pair',...
                              taskRange='Reward1',...
                              signalRange='NAc');
legendList = plotGroupTraces(combined.data{1},combined.timestamp,bluePurpleRed,...
                        groupSize=50,nGroups=15,...
                        groupby='animals',startIdx=combined.options.startIdx,...
                        remaining='include');
plotEvent(eventRange{event},.5,color=bluePurpleRed(500,:));
xlabel('Time (s)'); ylabel('NAc z-score');
legend(legendList,'Location','northeast');

6. Examples for remaining='exclude': note that the remaining trials are not plotted

combined = combineTraces(animals,timeRange=[-0.5,3],...
                              eventRange='Pair',...
                              taskRange='Reward1',...
                              signalRange='NAc');
legendList = plotGroupTraces(combined.data{1},combined.timestamp,bluePurpleRed,...
                        groupSize=50,nGroups=15,...
                        groupby='animals',startIdx=combined.options.startIdx,...
                        remaining='exclude');
plotEvent(eventRange{event},.5,color=bluePurpleRed(500,:));
xlabel('Time (s)'); ylabel('NAc z-score');
legend(legendList,'Location','northeast');

7. Examples for remaining='separate': note the remaining trials are plotted as separate line but is noisy

combined = combineTraces(animals,timeRange=[-0.5,3],...
                              eventRange='Pair',...
                              taskRange='Reward1',...
                              signalRange='NAc');
legendList = plotGroupTraces(combined.data{1},combined.timestamp,bluePurpleRed,...
                        groupSize=50,nGroups=15,...
                        groupby='animals',startIdx=combined.options.startIdx,...
                        remaining='separate');
plotEvent(eventRange{event},.5,color=bluePurpleRed(500,:));
xlabel('Time (s)'); ylabel('NAc z-score');
legend(legendList,'Location','northeast');