Plugins:pokesplot2

From Bcontrol

Introduction[edit]

PokesPlot is a plugin used to graphically display state, poke, scheduled wave and neural spike information for any instant and to perform basic analysis. PokesPlot2 is an upgrade from the previous version of pokesplot, completely rewritten. It incorporates a number of new features including display of scheduled waves, use of wildcards to retrieve information about multiple states, a window displaying the states/pokes/waves present under the cursor at any given coordinate on the PokesPlot axes, the ability to programmatically align all elements on the pokesplot axes at any desired time, and various fixes concerning the display of all elements on the axes. Pokesplot2 is completely compatible with existing data files and settings files.

Architecture And Working[edit]

In order to understand the working of pokesplot2, you might want to become familiar with the parsed_events, latest_parsed_events, and parsed_events_history variables. These variables are instantiated by Dispatcher.

PokesPlot2 operates in one of two modes:

  1. Displaying data as it is accumulated while the protocol is running: In this mode, pokesplot2 analyzes the latest_parsed_events structure for every update cycle of the protocol. Data about the entry and exit times of each state, poke, and scheduled wave is displayed on the pokesplot axes as it is retrieved from the Real-Time Linux State Machine Server. Spikes are not displayed in this mode, as retrieval of spiking data requires additional offline processing.
  2. Displaying historical experiment data from an existing data file: Historical experiment data can be displayed using pokesplot2 using either dispatcher or neurobrowser. When using dispatcher, simply load the desired data file from the saveload plugin. Historical data will be displayed and saved GUI element settings will be restored for all GUI elements once the data file is loaded. In order to load data from Neurobrowser, select the session you wish to display data for and hit the 'Send Data to PokesPlot' button. If spiking data is available, it will be shown on the PokesPlot axes as vertical lines, black by default.

A note about scheduled waves: At the time of this writing (May 5, 2010), only the sustain period of scheduled waves is available in the parsed_events structure. It is not possible to obtain the instants of the preamble and refractory periods of each scheduled wave with the current parsed_events structure. However, it will be possible to display the preamble and refractory periods by modifying the code only slightly if the parsed_events structure is modified at a later stage.

A note about spikes: In order to increase speed, all spiking data for every trial is a single line object, which contains NaNs in its 'XData' and 'YData' properties to indicate discontinuities. This, as opposed to using a single line object for every spike.

States and pokes are displayed as patch objects, whereas scheduled waves and spikes are displayed as line objects. Each state, poke, wave and spike display object has the trial number entered for its UserData property, and can be associated with the following additional appdata fields:

AppData Field Applicable to Possible Value(s)
pp_Category states, pokes, waves, spikes 'state', 'poke', 'wave', or 'spike'
pp_Name states, pokes, waves, spikes <statename>, <pokename>, [<wavename> '(sustain)'], or 'spike'
pp_TrialNumber states, pokes, waves, spikes The actual trial number associated with the display object
pp_StartTime states, pokes, waves The start time on the plot for each object
pp_StopTime states, pokes, waves The stop time on the plot for each object. Note that for an object that hasn't been completely drawn at any given instant, the value of this field will be NaN


Important SoloParamHandles

  • STATE_COLORS: The value of this SoloParamHandle is a structure with fields equal to desired visible state names and values normalized RGB triplets. It is obtained from state_colors.m.
  • POKE_COLORS: A structure with fields equal to desired visible poke names ('C', 'L', 'R') and values normalized RGB triplets. Optionally obtained from poke_colors.m
  • WAVE_COLORS: A structure with fields equal to desired visible wave names and values normalized RGB triplets. It is obtained from wave_colors.m
  • SPIKE_COLOR: Single RGB triplet denoting spike color, optionally obtained from spike_color.m
  • VISIBLE_STATES_LIST: Maintains the list of state names which should have their 'Visible' property set to 'on' at any given time
  • VISIBLE_POKES_LIST: List of poke names which should have their 'Visible' property set to 'on' at any given time
  • VISIBLE_WAVES_LIST: List of wave names which should have their 'Visible' property set to 'on' at any given time
  • SPIKES_VISIBLE: Boolean value, true if spikes should be visible at any given time, false otherwise
  • INVISIBLE_TRIALS_LIST: List of trial numbers which should be hidden at any given time
  • TRIAL_SEQUENCE: The display sequence of trials for the axes on the PokesPlot window. This is 1:n_started_trials by default, but can be changed by the Main Sort and Sub Sort fields in the pokesplot_preferences_pane GUI. Its length should ALWAYS be equal to length(1:n_started_trials)
  • SHOULD_USE_CUSTOM_PREFERENCES: Boolean value, true if custom preferences are to be used while drawing the plot, false otherwise. When the protocol is running, its value is forced to false. Otherwise, its value is controlled by the checkbox checkboxUseCustomPreferences.
  • trial_info: Array of structures with the following fields, one structure for each trial:
    • start_time: Equal to eval(['pe.states.' pe.states.starting_state '(1, end)']). pe is a shortcut for parsed_events
    • align_time: Equal to the result of evaluating the alignon field on the PokesPlotSection GUI, for every trial. If an evaluation is not possible, its value is the same as trial_info(trialnum).start_time
    • ghandles: Structure containing information about all graphics handles on the PokesPlotSection axes
      • states:
        • all_handles: Vector of all state handles for the given trial
      • pokes:
        • all_handles: Vector of all poke handles for the given trial
      • waves:
        • all_handles: Vector of all wave handles for the given trial
      • spikes:
        • all_handles: A single spike handle for the given trial
    • visible: True if a particular trial is visible, false if it isn't, basically a result of evaluating the Trial Selector criterion for a particular trial
    • mainsort_value: Result of evaluating the Main Sort criterion for a particular trial
    • subsort_value: Result of evaluating the Sub Sort criterion
Pokesplot2 flow diag1.jpg

Typical Usage[edit]

Step 1: Inherit from the pokesplot2 plugin:

obj = class(struct, mfilename, pokesplot2, <other plugins>);

Step 2: Call

PokesPlotSection(obj, 'init', x, y)

in your protocol's 'init' section. This will initialize the PokesPlotSection GUI and the PokesPlot Preferences Pane, and restore saved GUI element settings if available.

Step 3: Prepare the function files state_colors.m and wave_colors.m. Optionally, you may also want to prepare poke_colors.m and spike_color.m. The files should evaluate to a structure having the following format:

state_color_struct = struct('statename1', <normalized RGB triplet>, 'statename2', <normalized RGB triplet>, ...)
wave_color_struct = struct('wavename1', <normalized RGB triplet>, 'wavename2', <normalized RGB triplet>, ...)
poke_color_struct = struct('C', <normalized RGB triplet>, 'L', <normalized RGB triplet>, 'R', <normalized RGB triplet>)
spike_color = <normalized RGB triplet>

Note: The string all_handles is reserved, and cannot be used as a state, poke, or wave name.

Step 4: Call

PokesPlotSection(obj, 'update')

in your protocol's 'update' section. This will allow PokesPlot to continuously update its display as the protocol runs ahead.


Step 5: Call

PokesPlotSection(obj, 'close')

in your protocol's 'close' section.

PokesPlotSection Figure Window[edit]

Pokesplot2 gui.jpg

PokesPlot Preferences Pane[edit]

The figure below shows the PokesPlot Preferences Pane showing default values for Main_Sort, Sub_Sort, and Trial_Selector. The aforementioned fields are evaluated for every trial if the 'Use Custom Preferences' checkbox on the main PokesPlotSection window is checked. This feature is disabled while the protocol is running, as it is to be used only while analyzing historical data from an experiment.

Pokesplot preferences pane.jpg

Main Sort: Trials are sorted into groups based on the result of evaluating this expression. Sorting is done in ascending order only (to sort in descending order, use the negative of the sorting criterion used while sorting in ascending order).

Sub Sort: Within each group obtained from Main Sort, trials are sorted by this sorting criterion. Again, sorting is done in ascending order only.

Trial Selector: Only trials for which this field evaluates to true will be shown.

Collapse: When this setting is on, invisible trials will be moved to the bottom and visible trials will be moved to the top. This setting has no effect if the Trial Selector field evaluates to 'true' for every trial.

Export: Clicking this button exports the Major Sort Value (MSV) and Spike Count (SC) in the base workspace for every trial, as a vector of length equal to n_done_trials. This feature works only if the 'Use Custom Preferences' checkbox on the main PokesPlotSection window is checked.

PlotPSTH: It uses the 'smoother' parameter to plot the PeriStimulus Time Histogram (PSTH).

In addition to making selected trials invisible, a new feature allows the user to select only specific states, pokes, and scheduled waves to be displayed. The states, pokes, and scheduled waves which are selected in their respective listboxes will be displayed. The lists of visible states, pokes, and scheduled waves are saved with data files, so they are preserved across training sessions.

PokesPlot Expression Evaluation[edit]

A new feature in pokesplot2 is the new parsing style for the Main Sort, Sub Sort, and Trial Selector fields in the PokesPlot Preferences Pane, and, optionally, the alignon field in the PokesPlotSection GUI window. The new parsing style is enabled by default in the Main Sort, Sub Sort, and Trial Selector fields and is completely backwards compatible with the old parsing style for these fields. However, the new parsing style is not backwards compatible with the old parsing style for the alignon field. By default, the parsing style is set to 'v1 Style Parsing', and this can be changed by the user.

  • Use of regular M-file syntax is permitted
  • Certain reserved words and shortcuts exist (see documentation for eval_pokesplot_expression.m)
  • Shortcuts:
    • ps: parsed_events_history{trialnum}.states
    • pk: parsed_events_history{trialnum}.pokes
    • pw: parsed_events_history{trialnum}.waves
    • pspk: parsed_events_history{trialnum}.spikes
    • pd: protocol_data, obtained from the sessions table in the MySQL database, available only when examining historical data, empty the rest of the time
  • Reserved Words/keywords:
    • All variable names of variables instantiated by GetSoloFunctionArgs
    • out, str: DO NOT MODIFY THESE VARIABLES!!!
    • obj: Protocol object (do not modify)
    • trialnum: Trial number for which the expression is being evaluated
    • trial_info: A read-only version of the trial_info SoloParamHandle is available to all pokesplot2 expressions
    • this_trial: If the expression is complicated, it might be more practical to have the evaluated value stored in the this_trial variable. If this variable exists, its value will be the value returned.
    • randstring, isalnum: Internal functions

Wildcards: A new feature in pokesplot2 is the ability to incorporate wildcards in pokesplot expressions. The wildcard #, when used to represent a state name, poke name, or wave name, or a group of state names, poke names, or wave names, denotes zero or more characters. Wildcards may be used only to identify states, pokes, and waves, and must be used with the shortcuts ps, pk, and pw respectively. The function wildcardmatch is used to perform the matching.

e.g. Consider the expression:

rows(ps.#reward#) > 3

When evaluated, this expression will be treated as:

rows(ps.fakestate) > 3

where:

ps.fakestate == [ps.reward1; ps.reward2; ps.blureward]

The order in which the elements are concatenated depends on the order in which they are specified in state_colors.m, poke_colors.m, or wave_colors.m

Limitations:

  • Do not use wildcards if you need to include them as strings in an eval or feval statement (e.g. do not try something like eval(['pk' '.' '#']))
  • Do not use persistent variables

Screenshots[edit]

ScreenShot Description
Pokesplot2 screen1.jpg
Screenshot showing historical data obtained from neurobrowser, with spiking data
Pokesplot2 screen2.jpg
Screenshot showing historical data obtained from neurobrowser, with spiking data, and using sorting criteria along with wildcards
Pokesplot2 screen3.jpg
Screenshot showing historical data obtained from neurobrowser, using sorting criteria along with wildcards, as well as the 'v2 Style Parsing' for the alignon field. Spiking data and pokes have been deliberately hidden in this screenshot
Pokesplot2 screen4.jpg
Screenshot showing historical data obtained from dispatcher, displaying selected scheduled waves and looping scheduled waves (dotted lines). Only sustain periods can be depicted.

Plugin Files[edit]

Plugins/@pokesplot2/pokesplot2.m
Plugins/@pokesplot2/PokesPlotSection.m
Plugins/@pokesplot2/pokesplot_preferences_pane.m
Plugins/@pokesplot2/eval_pokesplot_expression.m
Plugins/@pokesplot2/pokesplot2_cdata.mat
Utility/wildcardmatch.m

Known Bugs[edit]

  • --Stuteja 11:06, 18 May 2010 (EDT) Very rarely, the PokesPlotSection figure window will display pokes for extended periods of time when it shouldn't. The problem does not arise when displaying historical data.
    • --Stuteja 15:00, 19 May 2010 (EDT) This problem seems to have to do with the way latest_parsed_events get populated.
  • --ChuckKopec 13:28, 18 May 2010 (EDT) Center pokes that continue from a previous trial in ProAnti3 occasionally are not drawn on the next trial. However, all pokes are drawn when historical data is loaded.
    • --Stuteja 15:00, 19 May 2010 (EDT) Confirmed, should be fixed as of today

Changelog[edit]

--Stuteja 19:47, 14 May 2010 (EDT): Added the 'pd' shortcut in pokesplot expressions

--Stuteja 19:48, 14 May 2010 (EDT): The 'Plot PSTH' button now uses 'exampleraster.m' from Analysis/helpers

Author[edit]

Sundeep Tuteja (sundeeptuteja [at] gmail [dot] com)