Loading Trials Data

Task related behavioral data

Relevant Alf objects

  • trials

  • subjectTrials

  • subjectTraining

Loading a single session’s trials

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

For combining trials data with various recording modalities for a given session, the SessionLoader class is more convenient:

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)

# The datasets are attributes of the sl.trials, for example probabilityLeft:
probabilityLeft = sl.trials['probabilityLeft']
# Find all of them using:
/opt/hostedtoolcache/Python/3.9.18/x64/lib/python3.9/site-packages/neurodsp/__init__.py:5: FutureWarning: neurodsp has been renamed to ibldsp and the old name will be deprecated on 01-Sep-2024.
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'],

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
          .sort_values(by=['session_start_time', 'intervals_0']))
trials['training_status'] = trials.training_status.fillna(method='ffill')

# Join sessions table for number, task_protocol, etc.
trials = one.load_aggregate('subjects', subject, '_ibl_subjectTrials.table')
if 'task_protocol' in trials:
    trials.drop('task_protocol', axis=1)
trials = trials.set_index('session').join(one._cache.sessions.drop('date', axis=1))

More details

Useful modules, packages and functions

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 psychometric 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:')

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

[ ]:

Example 5: Computing the inter-trial interval (ITI)

The ITI is the period of open-loop grey screen commencing at stimulus off and lasting until the quiescent period at the start of the following trial.

from brainbox.io.one import load_iti
eid = 'ae8787b1-4229-4d56-b0c2-566b61a25b77'
trials = one.load_object(eid, 'trials')
trials['iti'] = load_iti(trials)
print(trials.to_df().iloc[:5, -5:])
   rewardVolume  firstMovement_times  intervals_0  intervals_1       iti
0           1.5           117.641626   116.695529   119.305634  1.191781
1           1.5           127.492626   119.997332   129.171944  1.223111
2           1.5           131.802626   129.895043   133.568441  1.202380
3           0.0           136.639626   134.270738   139.385252  1.255541
4           1.5           141.399626   140.140751   143.068359  1.167783

Other relevant examples