2.4.3 combineTraces()

Overview

This is the most important function for experiment analysis. Given a selected range of interests, the function finds corresponding data within either animals or summary struct, and combined them for later plotting.

Inputs and options

Required inputs

• database: struct, can be either animals or summary struct

Options

• timeRange: double, default is [-15,15]. Unit is second.
• eventRange: string, default is 'All', else you can enter something like {'Stim','Pair'}
• animalRange: string, default is 'All', else you can enter something like {'SL133','SL135'}
• taskRange: string, default is 'All', else you can enter something like {'Reward1','Reward2'}
• sessionRange: string, default is 'All', else you can enter something like {'R1','R2'} to select session with contains 'R1/R2'
• signalRange: string, default is 'All', else you can enter something like {'NAc','LHb'}
• totalTrialRange: string, default is 'All', else you can enter something like [1,60]. See Details for relationship between totalTrialRange and trialRange.
• trialRange: string, default is 'All', else you can enter something like [1,20]
• trialConditions: string, default is empty. Here, user can define their own condition sentence that extracts subsets of trials based on what they need. See Details for more information.
  • For example, enter trialConditions="strcmpi(trials.Outcome,'H') & trials.nAnticipatoryLicks >= 3" to select Hit trials where total number of anticipatory licks within trials is bigger than 3. See example 2 below.
  • Use trials to indicate trial table.
  • Remember to use double quote. Single quote will not work.
  • Some coding and debugging will inevitably be involved here so be patient.
• statsType: string, default is 'All', which combines all stats type (mean, max, and mean)
• empty: logical, default is false. Will changed to true later in the function if no satisfied traces were found

Outputs

• combined: struct, contains information about the combined data.

  • combined.data: 1xn cells depending on the number of signals (length(signalRange)). Each cell will be combined traces for an individual signal source.

  • combined.stats: cells with struct corresponding to input statsType

    • combined.stats.stageAvg: 1xn cells depending on the number of signals (length(signalRange)). Each cell will be stored average value of selected traces for the corresponding stage (decided in stageTime options of analyzeTraces().
    • combined.stats.stageMax: 1xn cells depending on the number of signals (length(signalRange)). Each cell will be stored max value of selected traces for the corresponding stage.
    • combined.stats.stageMin: 1xn cells depending on the number of signals (length(signalRange)). Each cell will be stored min value of selected traces for the corresponding stage.

  • combined.timestamp: 1xn double array that stores the timestamp of each column, used in plotting

  • combined.trialNumber: 1xn cells depending on the number of signals (length(signalRange)). Each cell will store the total trial number within the session corresponding to each row in combined.data.

  • combined.trialTable: 1xn cells depending on the number of signals (length(signalRange)). Each cell will store rows of trialTable within the session corresponding to each row in combined.data.

  • combined.options: stores all options described above plus the following:

    • startIdx: struct, which contains following
      • startIdx.animal: double, stores index of the first trial for each animal
      • startIdx.session: double, stores index of the first trial for each session
    • signalRows: double, record rows that are used for analysis in database
    • sessionList: cell, lists of session included (sessions in sessionRange but does not contain data are not included).

Examples

1. To select NAc signals of pair trials of all animals during the task 'Reward1'.

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');

2. To select trials same as above, plus trials also needs to be a hit trial and have more than 3 anticipatory licks

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

Details: relationship between totalTrialRange and trialRange

In general, totalTrialRange defines the trials that happens within a session and trialRange indexes the select trials based on all the criteria above (i.e. events + animals + ...etc). Consider the following example:

Assume I'm selecting 10-50th trials for each session (totalTrialRange = [10,50]) for some event of interest (like stimulation-only trials) and I found 10 trials (e.g. [13,15,29,32,..,36,40,60]) out of 3 animals that I selected.

Theoretically, trialRange selects which specific trials within this 10 trials I want. Thus:

• if trialRange = [1,3]; I get trials [13,15,29]
• if trialRange = [-3,0]; I get trials [36,40,60]
• if trialRange = [-3,-1]; I get trials [36,40]

However, there will be edge scenarios where user input a trialRange that exceeds the number of found trials. Instead of issuing an error and stopping analysis, combineTraces() issues a warning and automatically handles the error by following rules:

• if trialRange = [2,20]; I get trials [15,29,...60]
• if trialRange = [20,23]; I get 0 trials
• if trialRange = [20,53]; I get 0 trials
• if trialRange = [0/-1,3]; I get trials [13,15,29,32] (ie get [1,3-0/3-(-1)])

Details: how to use trialConditions and historyConditions

trialConditions and historyConditions allow for flexible selection of trials based on information that contains within a trial table. Assume I selected all stimulation-only trials for 3 animals across all sessions.

1. I want to select subsets of trials based on behavior criteria of the current trial. Use trialConditions as these constraints are applied at the current trial.

   • For example, I only want to plot stimulation-only trials that the animal succeeded in getting a reward (single condition case)

     trialConditions = "strcmpi(trials.Outcome,'H')";
     

   • For example, I only want to plot stimulation-only trials that the animal succeeded in getting a reward and have more than 10 total licks within the trial (multiple condition case)

     trialConditions = "strcmpi(trials.Outcome,'H') & trials.nLicks > 10";
     

   • For example, I only want to plot stimulation-only trials that the animal succeeded in getting a reward or have more than 10 total licks within the trial (multiple condition case)

     trialConditions = "strcmpi(trials.Outcome,'H') | trials.nLicks > 10";
     

2. I want to select subsets of trials based on behavior criteria of previous or future trials. Use historyConditions as these constraints are applied at the previous or future trials. Remember to provide trialTables as well!

   • (To be implemented)
   • In the meantime, extract these trials of interest in session analysis phase!