ONE API modes

Online vs Offline

ONE can be instantiated in either the online and offline state. When online, ONE can query the Alyx database to retrieve information about dataset types , search with metadata such as session QC, task performance, histology and session narrative. Advanced queries may also be made via REST. Other online methods include pid2eid and describe_revision.

When the mode is not specified, it is usually set to ‘remote’, unless a cache_dir is specified for which no database has been configured.

[2]:

import one.webclient as webclient
from one.api import ONE

one = ONE()
print(one, one.mode)  # online, 'remote' mode
assert not one.offline

one_offline = ONE(cache_dir=r'C:\data')
print(one_offline, one_offline.mode)  # offline, 'local' mode
assert one_offline.offline

One (online, https://alyx.internationalbrainlab.org) remote
One (offline, C:\data) local

c:\users\user\documents\github\one\one\api.py:186: UserWarning: No cache tables found in C:\data
  warnings.warn(f'No cache tables found in {self._tables_dir}')

Query modes

In ‘local’ mode, the list, search and load methods will use the local cache tables and not connect to Alyx, however the option to use Alyx is always there when a database is provided. When instantiating ONE in local mode, any cache tables on disk are loaded.

If ‘remote’ mode is specified, ONE will only query the remote database and will not use the local cache tables. Avoiding the database whenever possible is recommended as it doesn’t rely on a stable internet connection and reduces the load on the remote database.

While in ‘remote’ mode, the local cache may be used by providing the query_type=’local’ keyword argument to any method. This will then search based on the results of previous remote queries. Likewise, in ‘local’ mode, a remote query can be made by specifying query_type='remote' (if a database has been configured). The local cache tables will then be supplemented with the result of this remote query.

NB: The ‘remote’ query type is not valid in offline mode as there is no database associated to the local cache directory.

[3]:

eids = one.search(lab='cortexlab', query_type='remote')  # Search Alyx instead of the local cache

REST caching

In remote mode ONE makes a REST query instead of using the local cache tables. The results of the remote REST queries are also cached for 5 minutes. This means that making the same remote REST query twice in a row will only hit the database once. The default cache expiry can be set by changing the relevant AlyxClient property:

[ ]:

from datetime import timedelta
one.alyx.default_expiry = timedelta(days=20)  # Cache results for up to 20 days

The expiry time can be set for individual queries by passing the expires kwarg to AlyxClient.rest:

[ ]:

# Cache subjects list for 24 hours
subjects = one.alyx.rest('subjects', 'list', expires=timedelta(days=1))

You can temporarily deactivate the REST cache using the no_cache function in one.webclient. When in this context no REST responses are cached and any existing cache files are not used. Use this when the most up-to-date information is required:

[ ]:

with webclient.no_cache(one.alyx):
    eids, det = one.search(lab='cortexlab', query_type='remote')

When calling the alyx rest method directly you can deactivate the cache with the no_cache keyword argument:

[ ]:

ses = one.alyx.rest('sessions', 'list', lab='cortexlab', no_cache=True)

Caching greatly improves performance and should be used whenever possible. For more information on ONE REST queries, see this guide.

You can turn off REST caching when instantiating ONE with the cache_rest keyword argument:

[ ]:

one = ONE(cache_rest=None, mode='remote')

Note that the cache won’t be downloaded if the remote cache hasn’t been updated since the last download. The cache can be explicitly refreshed in two ways:

Summary

Mode overview:

Mode	Function
local	only use current cache tables i.e. work entirely offline*
remote	make REST queries instead of using cache tables
auto	use cache tables wherever possible and keep them updated
refresh	always check for new cache tables

*no remote cache tables are downloaded; local cache files must be present in this mode.

I want to make a REST query for up-to-the-minute information Use one.alyx.rest(..., no_cache=True).

I want to use a remote ONE query with up-to-the-minute information Call the ONE method from within the webclient.no_cache context.