neuralset.events.study.Study

class neuralset.events.study.Study(*, infra: Backend | None = None, path: Path, infra_timelines: MapInfra = MapInfra(folder=None, cluster='processpool', logs='{folder}/logs/{user}/%j', job_name=None, timeout_min=None, nodes=1, tasks_per_node=1, cpus_per_task=None, gpus_per_node=None, mem_gb=None, max_pickle_size_gb=None, slurm_constraint=None, slurm_partition=None, slurm_account=None, slurm_qos=None, slurm_use_srun=False, slurm_additional_parameters=None, conda_env=None, workdir=None, permissions=511, version='0', keep_in_ram=True, max_jobs=128, min_samples_per_job=1, forbid_single_item_computation=False, mode='cached'), query: Annotated[str, AfterValidator(func=validate_query)] | None = None)

Interface to an external dataset: loads events from raw recordings.

Subclass Study to create an interface to a new dataset. Override iter_timelines() to enumerate timelines and _load_timeline_events() to load events for each one.

Parameters:

• path (Path) – Root directory for the study data. All studies can use the same path (e.g. path="/data"): each study automatically resolves its own subfolder (e.g. /data/MyStudy), so you only need to configure one path for your entire data store.

• infra_timelines (MapInfra) – Caching/compute backend for per-timeline event loading. Uses multiprocessing by default (cluster="processpool"); set cluster=None to disable (slower, but easier to debug).

• query (Query or None) – Optional filter applied after loading (e.g. "timeline_index < 5").

Examples

# Direct instantiation:
study = MyStudy(path="/data/studies")
# path auto-resolves to /data/studies/MyStudy if that subfolder exists
events = study.run()

# By name (auto-imports the study class):
study = Study(name="MyStudy", path="/data/studies")
events = study.run()

Note

Studies reference third-party datasets that are subject to their own licenses. You may have other legal obligations or restrictions that govern your use of that content. Check each study’s licence and url attributes for details.

build() → DataFrame

alias for run

classmethod catalog() → dict[str, Type[Study]]

All registered Study subclasses, keyed by name.

Triggers lazy imports so that studies from all installed packages (e.g. neuralfetch) are discovered.

Returns:

{name: StudySubclass} for every registered study.

Return type:

dict[str, type[Study]]

classmethod neuro_types() → frozenset[str]

Neural recording event types from _info, empty if _info is not set.

study_summary(apply_query: bool = True) → DataFrame

Returns a dataframe with 1 row per timeline and study attributes as columns. query parameter is used on this dataframe for subselection

Parameter

apply_query: bool

if False returns the full the summary, otherwise filter it according to the query

Virtual query columns

The following columns are not present in the returned DataFrame but are auto-generated by query_with_index() when apply_query=True and the query string references them:

subject_index: int

the index of the subject in the study

timeline_index: int

the index of the timeline in the study (equivalent to “index”)

subject_timeline_index: int

the index of the timeline among a subject’s timelines in the study (used for querying at most n timelines per subjects)