Loading Trials Data

Task related behavioral data

Relevant Alf objects

• trials

• subjectTrials

• subjectTraining

Loading a single session’s trials

If you want to load the trials data for a single session, we recommend you use the SessionLoader:

'''
RECOMMENDED
'''
from brainbox.io.one import SessionLoader
from one.api import ONE
one = ONE()
eid = '4ecb5d24-f5cc-402c-be28-9d0f7cb14b3a'
sl = SessionLoader(eid=eid, one=one)
sl.load_trials()

# The datasets are attributes of the sl.trials, for example probabilityLeft :
probabilityLeft = sl.trials['probabilityLeft']
# Find all of them using:
sl.trials.keys()

/home/runner/Downloads/ONE/openalyx.internationalbrainlab.org/hoferlab/Subjects/SWC_043/2020-09-21/001/alf/_ibl_trials.goCueTrigger_times.npy: 100%|██████████| 4.36k/4.36k [00:00<00:00, 27.0kB/s]
/home/runner/Downloads/ONE/openalyx.internationalbrainlab.org/hoferlab/Subjects/SWC_043/2020-09-21/001/alf/_ibl_trials.table.pqt: 100%|██████████| 45.0k/45.0k [00:00<00:00, 255kB/s]
/home/runner/Downloads/ONE/openalyx.internationalbrainlab.org/hoferlab/Subjects/SWC_043/2020-09-21/001/alf/_ibl_trials.stimOff_times.npy: 100%|██████████| 4.36k/4.36k [00:00<00:00, 21.6kB/s]

Index(['goCueTrigger_times', 'stimOff_times', 'probabilityLeft',
       'feedbackType', 'response_times', 'choice', 'firstMovement_times',
       'contrastLeft', 'contrastRight', 'stimOn_times', 'rewardVolume',
       'feedback_times', 'goCue_times', 'intervals_0', 'intervals_1'],
      dtype='object')

For completeness, we present below how to load the trials object using the one.load_object method, however we recommend you use the code above and use the SessionLoader instead.

'''
ALTERNATIVE - NOT RECOMMENDED
'''
from one.api import ONE
one = ONE()
eid = '4ecb5d24-f5cc-402c-be28-9d0f7cb14b3a'
trials = one.load_object(eid, 'trials', collection='alf')

Loading all the sessions’ trials for a single subject at once

If you want to study several sessions for a single subject, we recommend you use the one.load_aggregate method rather than downloading each trials data individually per session. This methods loads all the trials data subjectTrials for a given subject into a single DataFrame (i.e. all session trials are concatenated). You can use the same method to load the subjectTraining table, which contains the training statuses.

from one.api import ONE
one = ONE()
subject = 'SWC_043'
trials = one.load_aggregate('subjects', subject, '_ibl_subjectTrials.table')

# Load training status and join to trials table
training = one.load_aggregate('subjects', subject, '_ibl_subjectTraining.table')
trials = (trials
          .set_index('session')
          .join(training.set_index('session'))
          .sort_values(by='session_start_time')
          .fillna(method='ffill'))

More details

• Description of trials datasets

• Decsription of task QC metrics

Useful modules

• brainbox.behavior.training

• brainbox.behavior.pyschofit

• brainbox.task.trials

• ibllib.qc.task_metrics

Exploring trials data

Example 1. Computing behavioral performance

from brainbox.behavior.training import compute_performance

# compute performance
performance, contrasts, n_contrasts = compute_performance(trials)

# compute performance expressed as probability of choosing right
performance, contrasts, n_contrasts = compute_performance(trials, prob_right=True)

# compute performance during 0.8 biased block
performance, contrasts, n_contrasts = compute_performance(trials, block=0.8)

Example 2. Filtering trials

from brainbox.task.trials import find_trial_ids

# find index for stim right trials ordered by trial number
trial_id, _ = find_trial_ids(trials, side='right', choice='all', order='trial num')

# find index for correct, stim left, 100% contrast trials ordered by reaction time
trial_id, _ = find_trial_ids(trials, side='left', choice='correct', contrast=[1], order='reaction time')

# find index for correct trials ordered by trial number sorted by stimulus side
trial_id, _ = find_trial_ids(trials, side='left', choice='correct', order='reaction time', sort='side')

Example 3. Plotting pyschometric curve

from brainbox.behavior.training import plot_psychometric

fig, ax = plot_psychometric(trials)

Example 4: Computing Task QC for session

from ibllib.qc import task_metrics

qc = task_metrics.TaskQC(eid)
outcome, results = qc.run()
print(f'QC_status: {outcome}')
print(f'Individual QC values:')
results

Information about individual qc checks can be found by looking at the docstring (replace _task with check), e.g.

help(task_metrics.check_errorCue_delays)

Other relevant examples

• COMING SOON