managers

This is a scrappy first draft of a stimulus manager that will be built out to incorporate arbitrary stimulus logic. For now you can subclass Stim_Manager and redefine next_stim

Todo

Make this more general, for more than just sounds.

Functions:

init_manager(stim)

Classes:

Stim_Manager([stim])

Yield sounds according to some set of rules.

Proportional(stim)

Present groups of stimuli with a particular frequency.

Bias_Correction([mode, thresh, window])

Basic Bias correction module.

init_manager(stim)[source]
class Stim_Manager(stim=None)[source]

Bases: object

Yield sounds according to some set of rules.

Currently implemented:

  • correction trials - If a subject continually answers to one side incorrectly, keep

    the correct answer on the other side until they answer in that direction

  • bias correction - above some bias threshold, skew the correct answers to the less-responded side

Variables
  • stimuli (dict) –

    Dictionary of instantiated stimuli like:

    {'L': [Tone1, Tone2, ...], 'R': [Tone3, Tone4, ...]}
    

  • target ('L', 'R') – What is the correct port?

  • distractor ('L', 'R') – What is the incorrect port?

  • response ('L', 'R') – What was the last response?

  • correct (0, 1) – Was the last response correct?

  • last_stim – What was the last stim? (one of self.stimuli)

  • correction (bool) – Are we doing correction trials?

  • correction_trial (bool) – Is this a correction trial?

  • last_was_correction (bool) – Was the last trial a correction trial?

  • correction_pct (float) – proportion of trials that are correction trials

  • bias – False, or a bias correction mode.

Parameters

stim (dict) –

Dictionary describing sound stimuli, in a format like:

{
'L': [{'type':'tone',...},{...}],
'R': [{'type':'tone',...},{...}]
}

Methods:

do_correction([correction_pct])

Called to set correction trials to True and correction percent.

do_bias(**kwargs)

Instantiate a Bias_Correction module

init_sounds(sound_dict)

Instantiate sound objects, using the 'type' value to choose an object from autopilot.get('sound') .

set_triggers(trig_fn)

Give a callback function to all of our stimuli for when the stimulus ends.

make_punishment(type, duration)

Warning

Not Implemented

play_punishment()

Warning

Not Implemented

next_stim()

Compute and return the next stimulus

compute_correction()

If self.correction is true, compute correction trial logic during next_stim.

update(response, correct)

At the end of a trial, update the status of our internal variables with the outcome of the trial.

end()

End all of our stim.

do_correction(correction_pct=0.5)[source]

Called to set correction trials to True and correction percent.

Parameters

correction_pct (float) – Proportion of trials that should randomly be set to be correction trials.

do_bias(**kwargs)[source]

Instantiate a Bias_Correction module

Parameters

kwargs – parameters to initialize Bias_Correction with.

init_sounds(sound_dict)[source]

Instantiate sound objects, using the ‘type’ value to choose an object from autopilot.get('sound') .

Parameters

sound_dict (dict) –

a dictionary like::

{ ‘L’: [{‘type’:’tone’,…},{…}], ‘R’: [{‘type’:’tone’,…},{…}] }

set_triggers(trig_fn)[source]

Give a callback function to all of our stimuli for when the stimulus ends.

Note

Stimuli need a set_trigger method.

Parameters

trig_fn (callable) – A function to be given to stimuli via set_trigger

make_punishment(type, duration)[source]

Warning

Not Implemented

Parameters
  • type

  • duration

play_punishment()[source]

Warning

Not Implemented

next_stim()[source]

Compute and return the next stimulus

If we are doing correction trials, compute that.

Same thing with bias correction.

Otherwise, randomly select a stimulus to present.

Returns

(‘L’/’R’ Target, ‘L’/’R’ distractor, Stimulus to present)

compute_correction()[source]

If self.correction is true, compute correction trial logic during next_stim.

  • If the last trial was a correction trial and the response to it wasn’t correct, return True

  • If the last trial was a correction trial and the response was correct, return False

  • If the last trial as not a correction trial, but a randomly generated float is less than correction_pct, return True.

Returns

whether this trial should be a correction trial.

Return type

bool

update(response, correct)[source]

At the end of a trial, update the status of our internal variables with the outcome of the trial.

Parameters
  • response (‘L’, ‘R’) – How the subject responded

  • correct (0, 1) – Whether the response was correct.

end()[source]

End all of our stim. Stim should have an .end() method of their own

class Proportional(stim)[source]

Bases: autopilot.stim.managers.Stim_Manager

Present groups of stimuli with a particular frequency.

Frequencies do not need to add up to 1, groups will be selected with the frequency (frequency)/(sum(frequencies)).

Parameters

stim (dict) – Dictionary with the structure:

{'manager': 'proportional',
 'type': 'sounds',
 'groups': (
     {'name':'group_name',
      'frequency': 0.2,
      'sounds':{
          'L': [{Tone1_params}, {Tone2_params}...],
          'R': [{Tone3_params}, {Tone4_params}...]
      }
    },
    {'name':'second_group',
      'frequency': 0.8,
      'sounds':{
          'L': [{Tone1_params}, {Tone2_params}...],
          'R': [{Tone3_params}, {Tone4_params}...]
      }
    })
}
Variables
  • stimuli (dict) – A dictionary of stimuli organized into groups

  • groups (dict) – A dictionary mapping group names to frequencies

Parameters

stim (dict) –

Dictionary describing sound stimuli, in a format like:

{
'L': [{'type':'tone',...},{...}],
'R': [{'type':'tone',...},{...}]
}

Methods:

init_sounds_grouped(sound_stim)

Instantiate sound objects similarly to Stim_Manager, just organizes them into groups.

init_sounds_individual(sound_stim)

Initialize sounds with individually set presentation frequencies.

store_groups(stim)

store groups and frequencies

set_triggers(trig_fn)

Give a callback function to all of our stimuli for when the stimulus ends.

next_stim()

Compute and return the next stimulus

init_sounds_grouped(sound_stim)[source]

Instantiate sound objects similarly to Stim_Manager, just organizes them into groups.

Parameters

sound_stim (tuple, list) – an iterator like:

(
 {'name':'group_name',
  'frequency': 0.2,
  'sounds': {
      'L': [{Tone1_params}, {Tone2_params}...],
      'R': [{Tone3_params}, {Tone4_params}...]
    }
},
{'name':'second_group',
  'frequency': 0.8,
  'sounds':{
      'L': [{Tone1_params}, {Tone2_params}...],
      'R': [{Tone3_params}, {Tone4_params}...]
  }
})
init_sounds_individual(sound_stim)[source]

Initialize sounds with individually set presentation frequencies.

Todo

This method reflects the need for managers to have a unified schema, which will be built in a future release of Autopilot.

Parameters

sound_stim (dict) – Dictionary of {‘side’:[sound_params]} to generate sound stimuli

Returns:

store_groups(stim)[source]

store groups and frequencies

set_triggers(trig_fn)[source]

Give a callback function to all of our stimuli for when the stimulus ends.

Note

Stimuli need a set_trigger method.

Parameters

trig_fn (callable) – A function to be given to stimuli via set_trigger

next_stim()[source]

Compute and return the next stimulus

If we are doing correction trials, compute that.

Same thing with bias correction.

Otherwise, randomly select a stimulus to present, weighted by its group frequency.

Returns

(‘L’/’R’ Target, ‘L’/’R’ distractor, Stimulus to present)

class Bias_Correction(mode='thresholded_linear', thresh=0.2, window=100)[source]

Bases: object

Basic Bias correction module. Modifies the threshold of random stimulus choice based on history of biased responses.

Variables
Parameters
  • mode – One of the following:

    • ‘thresholded linear’above some threshold, do linear bias correction

      eg. if response rate 65% left, make correct be right 65% of the time

  • thresh (float) – threshold above chance, ie. 0.2 means has to be 70% biased in window

  • window (int) – number of trials to calculate bias over

Methods:

next_bias()

Compute the next bias depending on self.mode

thresholded_linear()

If we are above the threshold, linearly correct the rate of presentation to favor the rarely responded side.

update(response, target)

Store some new response and target values

next_bias()[source]

Compute the next bias depending on self.mode

Returns

Some threshold Stim_Manager uses to decide left vs right.

Return type

float

thresholded_linear()[source]

If we are above the threshold, linearly correct the rate of presentation to favor the rarely responded side.

eg. if response rate 65% left, make correct be right 65% of the time

Returns

0.5-bias, where bias is the difference between the mean response and mean target.

Return type

float

update(response, target)[source]

Store some new response and target values

Parameters
  • response (‘R’, ‘L’) – Which side the subject responded to

  • target (‘R’, ‘L’) – The correct side.