syncopy.load(filename, tag=None, dataclass=None, checksum=False, mode='r+', out=None)[source]

Load Syncopy data object(s) from disk

Either loads single files within or outside of ‘.spy’-containers or loads multiple objects from a single ‘.spy’-container. Loading from containers can be further controlled by imposing restrictions on object class(es) (via dataclass) and file-name tag(s) (via tag).

  • filename (str) – Either path to Syncopy container folder (*.spy, if omitted, the extension ‘.spy’ will be appended) or name of data or metadata file. If filename points to a container and no further specifications are provided, the entire contents of the container is loaded. Otherwise, specific objects may be selected using the dataclass or tag keywords (see below).

  • tag (None or str or list) – If filename points to a container, tag may be used to filter objects by filename-tag. Multiple tags can be provided using a list, e.g., tag = ['experiment1', 'experiment2']. Can be combined with dataclass (see below). Invalid if filename points to a single file.

  • dataclass (None or str or list) – If provided, only objects of provided dataclass are loaded from disk. Available options are ‘.analog’, ‘.spectral’, .spike’ and ‘.event’ (as listed in spy.FILE_EXT["data"]). Multiple class specifications can be provided using a list, e.g., dataclass = ['.analog', '.spike']. Can be combined with tag (see above) and is also valid if filename points to a single file (e.g., to ensure loaded object is of a specific type).

  • checksum (bool) – If True, checksum-matching is performed on loaded object(s) to ensure data-integrity (impairs performance particularly when loading large files).

  • mode (str) – Data access mode of loaded objects (can be ‘r’ for read-only, ‘r+’ or ‘w’ for read/write access).

  • out (Syncopy data object) – Empty object to be filled with data loaded from disk. Has to match the type of the on-disk file (e.g., filename = 'mydata.analog' requires out to be a syncopy.AnalogData object). Can only be used when loading single objects from disk (out is ignored when multiple files are loaded from a container).


  • Nothing (None) – If a single file is loaded and out was provided, out is filled with data loaded from disk, i.e., syncopy.load() does not create a new object

  • obj (Syncopy data object) – If a single file is loaded and out was None, syncopy.load() returns a new object.

  • objdict (dict) – If multiple files are loaded, syncopy.load() creates a new object for each file and places them in a dictionary whose keys are the base-names (sans path) of the corresponding files.


All of Syncopy’s classes offer (limited) support for data loading upon object creation. Just as the class method .save can be used as a shortcut for syncopy.save(), Syncopy objects can be created from Syncopy data-files upon creation, e.g.,

>>> adata = spy.AnalogData('/path/to/session1.analog')

creates a new syncopy.AnalogData object and immediately fills it with data loaded from the file “/path/to/session1.analog”.

Since only one object can be created at a time, this loading shortcut only supports single file specifications (i.e., spy.AnalogData("container.spy") is invalid).


Load all objects found in the spy-container “sessionName” (the extension “.spy” may or may not be provided)

>>> objectDict = spy.load("sessionName")
>>> # --> returns a dict with base-filenames as keys

Load all syncopy.AnalogData and syncopy.SpectralData objects from the spy-container “sessionName”

>>> objectDict = spy.load("sessionName.spy", dataclass=['analog', 'spectral'])

Load a specific syncopy.AnalogData object from the above spy-container

>>> obj = spy.load("sessionName.spy/sessionName_someTag.analog")

This is equivalent to

>>> obj = spy.AnalogData("sessionName.spy/sessionName_someTag.analog")

If the “sessionName” spy-container only contains one object with the tag “someTag”, the above call is equivalent to

>>> obj = spy.load("sessionName.spy", tag="someTag")

If there are multiple objects of different types using the same tag “someTag”, the above call can be further narrowed down to only load the requested syncopy.AnalogData object

>>> obj = spy.load("sessionName.spy", tag="someTag", dataclass="analog")

See also


save syncopy object on disk