ONE Tutorial Python

Before you begin, make sure you have installed ibllib properly on your system as per the previous instructions. Here is a shorter introduction to the One module in Ipython notebook format.

The full module documentation is found Here

Create ONE object

Once the One class is instantiated and setup, we can create an one object (here labelled one).

With default connection settings

Type in python prompt:

from import ONE
one = ONE() # need to instantiate the class to have the API. You will have to write these lines of code everytime you re-open python.

Reminder: connection parameters inserted via one.setup() will modify the JSON .one_params file see here

With different connection settings for single time use

For this tutorial we will be connecting to a test database with a test user. As these credentials will be used for this tutorial only, we do not want to change the base parameters of the JSON .one_params file.

from import ONE
one = ONE(username='test_user',

Search method : find session EIDs

Each experimental session is identified by a unique string known as the “experiment ID” (EID). To find an EID, use the command.

The searchable fields are listed with the following method:


# Example search keywords: 

Comprehensive example

The following example shows how to find the experiment(s) performed by the user olivier, on the 24 Aug 2018:

from ibllib.misc import pprint
eid ='olivier', date_range=['2018-08-24', '2018-08-24'])



To get all context information about the returned sessions, use the flag details:

eid, ses_info='olivier', date_range=['2018-08-24', '2018-08-24'], details=True)

List method : list datasets for given session EID

Once you know the EID, you can list all the datasets for the experiment using the list command:



['_ibl_lickPiezo.raw', '_ibl_lickPiezo.timestamps', '_ibl_wheel.position', 'channels.brainLocation', 'channels.probe', 'channels.rawRow', '', 'channels.sitePositions', 'clusters._phy_annotation', 'clusters.depths', 'clusters.peakChannel', 'clusters.probes', 'clusters.templateWaveforms', 'clusters.waveformDuration', 'eye.area', 'eye.blink', 'eye.timestamps', 'eye.xyPos', 'licks.times', 'probes.description', 'probes.insertion', 'probes.rawFilename', 'probes.sitePositions', 'spikes.amps', 'spikes.clusters', 'spikes.depths', 'spikes.times', 'spontaneous.intervals', 'unknown']

For more detailed datasets info, this will return a dataclass with dataset_type, data_url and dataset_id fields amongst others:

d = one.list(eid, details=True)

To get the full contextual information about the session, get all fields:

one.list(eid, 'all')

To navigate the database, it may be useful to get the range of possible keywords values to search for sessions. For example to print a list of the dataset-types, users and subjects in the command window:

one.list(None, 'dataset-types')
one.list(None, 'users')
one.list(None, 'subjects')
one.list(None, 'labs')

Load method : load data for given session EID

General Use

To load data for a given EID, use the one.load command:

dataset_types = ['clusters.templateWaveforms', 'clusters.probes', 'clusters.depths']
eid = 'cf264653-2deb-44cb-aa84-89b82507028a'
wf, pr, d = one.load(eid, dataset_types=dataset_types)

Depending on the use case, it may be handier to wrap the arrays in a dataclass (a structure for Matlab users) so that a bit of context is included with the array. This would be useful when concatenated information for datasets belonging to several sessions.

my_data = one.load(eid, dataset_types=dataset_types, dclass_output=True)
from ibllib.misc import pprint

The dataclass contains the following keys, each of which contains a list of 3 items corresponding the the 3 queried datasets

  • data (numpy.array): the numpy array
  • dataset_id (str): the UUID of the dataset in Alyx
  • local_path (str): the local full path of the file
  • dataset_type (str): as per Alyx table
  • url (str): the link on the FlatIron server
  • eid (str): the session UUID in Alyx

It is also possible to query all datasets attached to a given session, in which case the output has to be a dictionary:

eid ='flowers')
my_data = one.load(eid[0])

Specific cases

If a dataset type queried doesn’t exist or is not on the FlatIron server, an empty list is returned. This allows to keep the proper order of output arguments

eid = 'cf264653-2deb-44cb-aa84-89b82507028a'
dataset_types = ['clusters.probes', 'thisDataset.IveJustMadeUp', 'clusters.depths']
t, empty, cl = one.load(eid, dataset_types=dataset_types)

Returns an empty list for cr so that t and cl still get assigned the corresponding datasets values.

Getting help on methods via the command line

These commands will return the docstring of each of the method; for example, for type in an ipython terminal: