ONE advanced queries

While the basic one.search command allows us to filter experimental sessions by date, lab, subject etc, you may quickly find that you want to apply more complex queries to restrict your search output. This can be achieved using the one.alyx.rest command. This has access to a range of tables stored in the database and gives us more flexibilty when forming our queries.

one.search vs one.alyx.rest

We will get started by importing ONE

from one.api import ONE
one = ONE(base_url='https://alyx.internationalbrainlab.org')

We can list the possible tables that we have access to, by typing the following command

one.alyx.list_endpoints()

['brain-regions',
 'cache',
 'cache.zip',
 'channels',
 'data-formats',
 'data-repository',
 'data-repository-type',
 'dataset-types',
 'datasets',
 'downloads',
 'files',
 'insertions',
 'labs',
 'locations',
 'new-download',
 'notes',
 'projects',
 'register-file',
 'revisions',
 'sessions',
 'subjects',
 'surgeries',
 'sync-file-status',
 'tags',
 'tasks',
 'trajectories',
 'uploaded',
 'users',
 'water-administrations',
 'water-requirement',
 'water-restricted-subjects',
 'water-restriction',
 'water-type',
 'weighings']

Let’s first look at sessions table. The information about what filters can be applied to this table are available under Query Parameters here. Let’s apply a filter based on subject and task_protocol. We can do this using the following expression,

sess_info = one.alyx.rest('sessions', 'list', subject='SWC_015', task_protocol='ephys')
sess_info[0]

{'subject': 'SWC_015',
 'start_time': '2020-01-25T18:53:42.203528',
 'number': 1,
 'lab': 'hoferlab',
 'project': 'ibl_neuropixel_brainwide_01',
 'url': 'https://alyx.internationalbrainlab.org/sessions/f3ff65f1-7d59-4abe-b94e-b0478ab5e921',
 'task_protocol': '_iblrig_tasks_ephysChoiceWorld6.2.5'}

Notice how this command doesn’t just return the session eID but a dictionary containing information about each session. We can extract the set of eIDs from the url key

eids = [s['url'] for s in sess_info]
eids = [e.split('/')[-1] for e in eids]
eids

['f3ff65f1-7d59-4abe-b94e-b0478ab5e921',
 '994df46a-6e5f-472d-96dd-0d86e76a8107',
 '629f25be-1b05-44d0-bcac-e8c40701d5f4',
 'a9272cce-6914-4b45-a05f-9e925b4c472a',
 'c9fec76e-7a20-4da4-93ad-04510a89473b',
 '34d20aff-10e5-4a07-8b08-64051a1dc6ac']

You might have noticed that this same query could be have been achieved using the one.search method,

eids = one.search(subject='SWC_015', task_protocol='ephys')
eids

['f3ff65f1-7d59-4abe-b94e-b0478ab5e921',
 '994df46a-6e5f-472d-96dd-0d86e76a8107',
 '629f25be-1b05-44d0-bcac-e8c40701d5f4',
 'a9272cce-6914-4b45-a05f-9e925b4c472a',
 'c9fec76e-7a20-4da4-93ad-04510a89473b',
 '34d20aff-10e5-4a07-8b08-64051a1dc6ac']

Let’s add in another filter to see the benefits of the one.alyx.rest approach. We will add an atlas_acronym filter to see if any of the ephys sessions from SWC_015 were recorded from the somatomotor areas (acronym MO). This query would not be possible with the one.search command!

sess_info = one.alyx.rest('sessions', 'list', subject='SWC_015', task_protocol='ephys',
                          atlas_acronym='MO')
sess_info

[{'subject': 'SWC_015',
  'start_time': '2020-01-24T14:56:07.183680',
  'number': 1,
  'lab': 'hoferlab',
  'project': 'ibl_neuropixel_brainwide_01',
  'url': 'https://alyx.internationalbrainlab.org/sessions/994df46a-6e5f-472d-96dd-0d86e76a8107',
  'task_protocol': '_iblrig_tasks_ephysChoiceWorld6.2.5'},
 {'subject': 'SWC_015',
  'start_time': '2020-01-23T16:22:24.861589',
  'number': 1,
  'lab': 'hoferlab',
  'project': 'ibl_neuropixel_brainwide_01',
  'url': 'https://alyx.internationalbrainlab.org/sessions/629f25be-1b05-44d0-bcac-e8c40701d5f4',
  'task_protocol': '_iblrig_tasks_ephysChoiceWorld6.2.5'},
 {'subject': 'SWC_015',
  'start_time': '2020-01-22T17:04:18.126507',
  'number': 1,
  'lab': 'hoferlab',
  'project': 'ibl_neuropixel_brainwide_01',
  'url': 'https://alyx.internationalbrainlab.org/sessions/a9272cce-6914-4b45-a05f-9e925b4c472a',
  'task_protocol': '_iblrig_tasks_ephysChoiceWorld6.2.5'}]

Accessing other Alyx tables

With the one.alyx.rest command we are not only limited to the sessions table, but can formulate queries based on other tables to find session eIDs of interest. Consider the case where we want to find all sessions that have probe insertions that target a specific ML and AP coordinate. For this we can formulate our query based on the trajectories table. Let’s see if there are any probe insertions at the coordinates ML(x) = -2000, and AP(y) = -2000 from bregma.

trajs = one.alyx.rest('trajectories', 'list', x=-2000, y=-2000)
trajs[0]

{'id': '8741d377-a3de-4d94-9ba0-1eb28787da49',
 'probe_insertion': 'dc50c3de-5d84-4408-9725-22ae55b93522',
 'x': -2000.0,
 'y': -2000.0,
 'z': -169.0,
 'depth': 4000.0,
 'theta': 15.0,
 'phi': 180.0,
 'roll': 0.0,
 'provenance': 'Micro-manipulator',
 'session': {'subject': 'SWC_023',
  'start_time': '2020-02-13T15:36:50.234590',
  'number': 1,
  'lab': 'mrsicflogellab',
  'id': '38d95489-2e82-412a-8c1a-c5377b5f1555',
  'task_protocol': '_iblrig_tasks_ephysChoiceWorld6.2.5'},
 'probe_name': 'probe01',
 'coordinate_system': 'Needles-Allen',
 'datetime': '2020-06-09T07:59:14.315700',
 'json': None}

We can find the session eID associated with this trajectory by looking at the id of the session field in the returned dictionary

eid = trajs[0]['session']['id']
eid

'38d95489-2e82-412a-8c1a-c5377b5f1555'

Note.

It is not just sessions that have unique IDs associated with them! Every object stored in Alyx has a unique UUID, whether it is a trajectory, a subject, a user or a dataset. For example in the above example we can access the unique ID of the trajectory by typing traj_id = trajs[0]['id']

Searching with one.alyx.rest

The one.alyx.rest command is also provides an alternative method to one.list for searching the database for possible keywords that you can use to restrict your queries. For example, if we want to find the names of female subjects in the Witten lab that are alive, we can use the subjects table to write,

subj_info = one.alyx.rest('subjects', 'list', lab='wittenlab', sex='F', alive=True)
subj_nickname = [subj['nickname'] for subj in subj_info]
subj_nickname

['dop_21', 'dop_22', 'dop_30', 'dop_31', 'dop_39', 'fip_10', 'fip_8', 'fip_9']