Searching with ONE

ONE contains a method that allows you to search for sessions of interest. The possible search terms can be listed using,

from one.api import ONE
one = ONE(base_url='https://openalyx.internationalbrainlab.org', silent=True)

print(one.search_terms())

('dataset', 'date_range', 'laboratory', 'number', 'project', 'subject', 'task_protocol')

We can search for sessions within a specified date range

from pprint import pprint
eids = one.search(date_range=['2020-01-01', '2021-01-01'])
pprint(eids)

['4ecb5d24-f5cc-402c-be28-9d0f7cb14b3a',
 'c7bd79c9-c47e-4ea5-aea3-74dda991b48e',
 '4b7fbad4-f6de-43b4-9b15-c7c7ef44db4b']

To get more information about the sessions we can add a details=True flag

eids = one.search(date_range=['2020-01-01', '2021-01-01'], details=True)
pprint(eids)

(['4ecb5d24-f5cc-402c-be28-9d0f7cb14b3a',
  'c7bd79c9-c47e-4ea5-aea3-74dda991b48e',
  '4b7fbad4-f6de-43b4-9b15-c7c7ef44db4b'],
 [{'date': datetime.date(2020, 9, 21),
   'lab': 'hoferlab',
   'number': 1,
   'project': 'ibl_neuropixel_brainwide_01',
   'subject': 'SWC_043',
   'task_protocol': '_iblrig_tasks_ephysChoiceWorld6.4.2'},
  {'date': datetime.date(2020, 9, 19),
   'lab': 'zadorlab',
   'number': 1,
   'project': 'ibl_neuropixel_brainwide_01',
   'subject': 'CSH_ZAD_029',
   'task_protocol': '_iblrig_tasks_ephysChoiceWorld6.4.2'},
  {'date': datetime.date(2020, 1, 8),
   'lab': 'churchlandlab',
   'number': 1,
   'project': 'ibl_neuropixel_brainwide_01',
   'subject': 'CSHL049',
   'task_protocol': '_iblrig_tasks_ephysChoiceWorld6.2.5'}])

Multiple search terms can also be combined, for example we can search for any sessions from the subject SWC_043 that contain the datasets spikes.times and spikes.clusters

eids = one.search(subject='SWC_043', dataset=['spikes.times', 'spikes.clusters'])
pprint(eids)

['4ecb5d24-f5cc-402c-be28-9d0f7cb14b3a']

To find out more information about the one.search method we can use the help function

help(one.search)

Help on method search in module one.api:

search(details=False, query_type=None, **kwargs) method of one.api.OneAlyx instance
    Searches sessions matching the given criteria and returns a list of matching eids

    For a list of search terms, use the method

     one.search_terms(query_type='remote')

    For all of the search parameters, a single value or list may be provided.  For dataset,
    the sessions returned will contain all listed datasets.  For the other parameters,
    the session must contain at least one of the entries. NB: Wildcards are not permitted,
    however if wildcards property is False, regular expressions may be used for all but
    number and date_range.

    Parameters
    ----------
    dataset : str, list
        list of dataset names. Returns sessions containing all these datasets.
        A dataset matches if it contains the search string e.g. 'wheel.position' matches
        '_ibl_wheel.position.npy'
    date_range : str, list, datetime.datetime, datetime.date, pandas.timestamp
        A single date to search or a list of 2 dates that define the range (inclusive).  To
        define only the upper or lower date bound, set the other element to None.
    lab : str, list
        A str or list of lab names, returns sessions from any of these labs
    number : str, int
        Number of session to be returned, i.e. number in sequence for a given date
    subject : str, list
        A list of subject nicknames, returns sessions for any of these subjects
    task_protocol : str, list
        The task protocol name (can be partial, i.e. any task protocol containing that str
        will be found)
    project : str, list
        The project name (can be partial, i.e. any task protocol containing that str
        will be found)
    performance_lte / performance_gte : float
        search only for sessions whose performance is less equal or greater equal than a
        pre-defined threshold as a percentage (0-100)
    users : str, list
        A list of users
    location : str, list
        a str or list of lab location (as per Alyx definition) name
        Note: this corresponds to the specific rig, not the lab geographical location per se
    dataset_types : str, list
        One or more of dataset_types
    details : bool
        If true also returns a dict of dataset details
    query_type : str, None
        Query cache ('local') or Alyx database ('remote')
    limit : int
        The number of results to fetch in one go (if pagination enabled on server)

    Returns
    -------
    List of eids and, if details is True, also returns a list of dictionaries, each entry
    corresponding to a matching session