experanto.experiment.Experiment

class Experiment(root_folder, modality_config={'screen': {'keep_nans': False, 'sampling_rate': 30, 'chunk_size': 60, 'valid_condition': {'tier': 'train'}, 'offset': 0, 'sample_stride': 1, 'include_blanks': True, 'transforms': {'normalization': 'normalize', 'Resize': {'_target_': 'torchvision.transforms.v2.Resize', 'size': [144, 256]}}, 'interpolation': {'rescale': True, 'rescale_size': [144, 256]}}, 'responses': {'keep_nans': False, 'sampling_rate': 8, 'chunk_size': 16, 'offset': 0.0, 'transforms': {'normalization': 'normalize_variance_only'}, 'interpolation': {'interpolation_mode': 'nearest_neighbor'}, 'filters': {'nan_filter': {'__target__': 'experanto.filters.common_filters.nan_filter', '__partial__': True, 'vicinity': 0.05}}}, 'eye_tracker': {'keep_nans': False, 'sampling_rate': 30, 'chunk_size': 60, 'offset': 0, 'transforms': {'normalization': 'normalize'}, 'interpolation': {'interpolation_mode': 'nearest_neighbor'}, 'filters': {'nan_filter': {'__target__': 'experanto.filters.common_filters.nan_filter', '__partial__': True, 'vicinity': 0.05}}}, 'treadmill': {'keep_nans': False, 'sampling_rate': 30, 'chunk_size': 60, 'offset': 0, 'transforms': {'normalization': 'normalize'}, 'interpolation': {'interpolation_mode': 'nearest_neighbor'}, 'filters': {'nan_filter': {'__target__': 'experanto.filters.common_filters.nan_filter', '__partial__': True, 'vicinity': 0.05}}}}, cache_data=False)[source]

Bases: object

High-level interface for loading and querying neuroscience experiments.

An Experiment represents a single recording session containing multiple modalities (e.g., visual stimuli, neural responses, behavioral data). Each modality is loaded as an Interpolator, allowing data to be queried at arbitrary time points.

Parameters:

root_folder (str) – Path to the experiment directory. Should contain subdirectories for each modality (e.g., screen/, responses/, eye_tracker/).
modality_config (dict, optional) – Configuration dictionary specifying interpolation and processing settings for each modality. See experanto.configs for the default configuration structure.
cache_data (bool, default=False) – If True, loads all trial data into memory for faster access. Useful for smaller datasets or when memory is not a constraint.

devices

Dictionary mapping device names to their Interpolator instances.

Type:: dict

start_time

Earliest valid timestamp across all devices.

Type:: float

end_time

Latest valid timestamp across all devices.

Type:: float

See also

ChunkDataset: Higher-level interface for ML training.
Interpolator: Base class for modality-specific interpolators.

Examples

>>> from experanto.experiment import Experiment
>>> exp = Experiment('/path/to/experiment')
>>> exp.device_names
('screen', 'responses', 'eye_tracker')
>>> times = np.linspace(0, 10, 100)
>>> data = exp.interpolate(times, device='responses')

Methods

`__init__`(root_folder[, modality_config, ...])
`get_valid_range`(device_name)	Get the valid time range for a specific device.
`interpolate`(times[, device, return_valid])	Interpolate data from one or all devices at specified time points.

Attributes

device_names

__init__(root_folder, modality_config={'screen': {'keep_nans': False, 'sampling_rate': 30, 'chunk_size': 60, 'valid_condition': {'tier': 'train'}, 'offset': 0, 'sample_stride': 1, 'include_blanks': True, 'transforms': {'normalization': 'normalize', 'Resize': {'_target_': 'torchvision.transforms.v2.Resize', 'size': [144, 256]}}, 'interpolation': {'rescale': True, 'rescale_size': [144, 256]}}, 'responses': {'keep_nans': False, 'sampling_rate': 8, 'chunk_size': 16, 'offset': 0.0, 'transforms': {'normalization': 'normalize_variance_only'}, 'interpolation': {'interpolation_mode': 'nearest_neighbor'}, 'filters': {'nan_filter': {'__target__': 'experanto.filters.common_filters.nan_filter', '__partial__': True, 'vicinity': 0.05}}}, 'eye_tracker': {'keep_nans': False, 'sampling_rate': 30, 'chunk_size': 60, 'offset': 0, 'transforms': {'normalization': 'normalize'}, 'interpolation': {'interpolation_mode': 'nearest_neighbor'}, 'filters': {'nan_filter': {'__target__': 'experanto.filters.common_filters.nan_filter', '__partial__': True, 'vicinity': 0.05}}}, 'treadmill': {'keep_nans': False, 'sampling_rate': 30, 'chunk_size': 60, 'offset': 0, 'transforms': {'normalization': 'normalize'}, 'interpolation': {'interpolation_mode': 'nearest_neighbor'}, 'filters': {'nan_filter': {'__target__': 'experanto.filters.common_filters.nan_filter', '__partial__': True, 'vicinity': 0.05}}}}, cache_data=False)[source]

property device_names

interpolate(times, device=None, return_valid=False)[source]

Interpolate data from one or all devices at specified time points.

Parameters:

times (array_like) – 1D array of time points (in seconds) at which to interpolate.
device (str, optional) – Name of a specific device to interpolate. If None, interpolates all devices and returns dictionaries.

Returns:

values (numpy.ndarray or dict) – If device is specified, returns the interpolated data array for the valid time points only (shape is modality-dependent, see below). Otherwise, returns a dict mapping device names to their data arrays.
valid (numpy.ndarray or dict, optional) – Only present when return_valid=True. Integer index array(s) into times indicating which entries were used to produce values. values[i] corresponds to times[valid[i]], and len(valid) == values.shape[0]. When a dict is returned, valid is a dict with the same keys and len(valid[d]) may differ across devices because each modality has its own valid range.

Return type:

tuple[dict, dict] | dict | tuple[np.ndarray, np.ndarray] | np.ndarray

Notes

Output shapes per modality:

Sequence modalities (responses, eye_tracker, treadmill): (n_valid, n_signals)
Screen modality: (n_valid, H, W) for grayscale, (n_valid, H, W, C) for colour.

Examples

Interpolate a single device:

>>> data, valid = exp.interpolate(times, device='responses', return_valid=True)
>>> data.shape
(n_valid, 500)  # n_valid <= len(times), 500 neurons
>>> times[valid].shape == (data.shape[0],)
True

Interpolate all devices:

>>> data = exp.interpolate(times)
>>> data.keys()
dict_keys(['screen', 'responses', 'eye_tracker'])

get_valid_range(device_name)[source]

Get the valid time range for a specific device.

Parameters:: device_name (str) – Name of the device (e.g., ‘screen’, ‘responses’).
Returns:: A tuple (start_time, end_time) representing the valid time interval in seconds.
Return type:: tuple