Get data from the G-Node

This chapter explains with some more examples, how data can be retrieved from the G-Node REST API. In all the following code examples we assume that an open session object s exists and that the class Model was imported.

The Select Function

The purpose of the Session.select() method is to retrieve a list of objects from a certain type from the G-Node REST API. See the documentation for a detailed description of the used object model. Further the Session.select() methods provides the possibility to filter the result by various criteria. At the moment only so called raw filters are supported. Raw filters consist of a list of key value pairs represented as a python dictionary. The following example illustrates some common use cases for filters:

# splitting results
signals = s.select(Model.ANALOGSIGNAL, {"offset": 0, "max_results": 100})
signals = s.select(Model.ANALOGSIGNAL, {"offset": 0, "max_results": 100})

# search for owner
blocks = s.select(Model.BLOCK, {"owner": "bob"})

# search for certain properties
segments = s.select(Model.SEGMENT, {"name__icontains": "foo"})
signals = s.select(Model.ANALOGSIGNAL, {"t_start": 0})

# get all odML sections without a parent (root sections)
sections = s.select(Model.SECTION, {"parent_section__isnull": 1})

# combine filters
# get the first hundred root sections that are owned by the user "bob"
filers = {
    "parent_section__isnull": 1,
    "offset": 0,
    "max_results": 100,
    "owner": "bob"
}
sections = s.select(Model.SECTION, filters)

The basic syntax for raw filters is rather complex. The documentation of the G-Node REST API describes how to query data from the server in detail.

Since the filters can not be evaluated locally, the Session.select() method always requests data from the server and never from the local cache. Regarding performance this means, that Session.select() is comparably slow, on the other hand it ensures that the result always contains the most recent versions of objects.

The Get Function

In contrast to Session.select() the Session.get() method only returns one single object. In order to do so, the client must know the type and id of an object. This information is encoded in the location property of each object returned by the api. Typical location strings have the following format <category>/<type>/<id> here are some examples:

• metadata/section/K6LO7NH133
• electrophysiology/segment/3GQP0BTS90

Without any other parameter Session.get() will look up the requested object in the cache and return it. Only if an object is missing from the cache it will be requested from the server. If an object was not found at all Session.get() returns None. The following example demonstrates this behaviour.

# clear the cache
s.clear_cache()

# get the segment from the server (slow)
segment = s.get("electrophysiology/segment/K6LO7NH133")

# get the segment from the cache (fast)
segment = s.get("electrophysiology/segment/K6LO7NH133")

# lazy loading data from the server (slow)
noof_signals = len(segment.analogsignals)

In some situations it is very useful to make sure that the most recent version of and object is returned, even if a (potentially older) version was already cached. For this purpose the method defines an optional parameter called refresh. If this parameter is set to True the client will check if there is a newer version on the server. If this is not the case, the client will return the cached object.

s.clear_cache()                                                         # clear the cache

# get the segment from the server (slow)
segment = s.get("electrophysiology/segment/K6LO7NH133", refresh=True)

# check first for newer version and get the data from the cache (medium)
segment = s.get("electrophysiology/segment/K6LO7NH133", refresh=True)

Using the refresh parameter as shown above, also speeds up the performance in cases where the most recent version was already cached, but is still considerably slower than without.

When working with larger datasets it can be quite annoying when some operations are fast (due to caching) whereas other operations take longer. Therefore the Session.get() method provides a third optional parameter, that can be used to make sure, that certain objects are cached.

# clear the cache
s.clear_cache()

# load the most recent version of the segment and all its descendants to the cache (very slow)
segment = s.get("electrophysiology/segment/K6LO7NH133", refresh=True, recursive=True)

# lazy loading is fast because it uses the cache
noof_signals = len(segment.analogsignals)

Work with Signal Data

The next short example shows how signal data can be retrieved from the server and then plotted using matplotlib.

from matplotlib import pylab

segment = s.get("electrophysiology/segment/K6LO7NH133")
signals = segment.analogsignals

for s in signals:
    pylab.plot(s.times, s)

pylab.xlabel(signals[0].times.units.dimensionality.string)
pylab.ylabel(signals[0].units.dimensionality.string)

pylab.show()

Get Permissions

Every kind of object that is returned by Session.get() of Session.select() has its own security settings. Those settings can be obtained using the Session.permissions() method.

segment = s.get("electrophysiology/segment/K6LO7NH133")
perms = s.permissions(segment)