← Back to API reference

neuralset.events.study.Study

pydantic model neuralset.events.study.Study

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.

• timelines (TimelineLoader) – Per-timeline loader; timelines.infra sets how loads are dispatched and cached (default: a process pool). Disable the pool via infra=None (inline, uncached) or infra.derive("Cached") (cached, in-process).

• version (str) – Cache-busting key kept in the uid; bump when loading logic changes.

• 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.

Fields:

• path (pathlib.Path)

• query (Annotated[str, pydantic.functional_validators.AfterValidator(func=neuralset.base.validate_query)] | None)

• timelines (neuralset.events.study.TimelineLoader)

• version (str)

CACHE_TYPE: ClassVar[str | None] = 'ValidatedParquet'

field path: Path [Required]

field timelines: TimelineLoader = TimelineLoader(** { 'infra': { 'backend': 'ProcessPool',              'folder': None,              'keep_in_ram': True,              'max_jobs': 128,              'mode': 'cached'},   'name': 'TimelineLoader'} )

field version: str = ''

field query: Annotated[str, AfterValidator(func=validate_query)] | None = None

aliases: ClassVar[tuple[str, ...]] = ()

url: ClassVar[str] = ''

bibtex: ClassVar[str] = ''

licence: ClassVar[str] = ''

description: ClassVar[str] = ''

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.

iter_timelines() → Iterator[dict[str, Any]]

final download(**kwargs: Any) → None

branches(item: Any) → list[dict[str, Any]]

Query-selected timeline dicts to load, one per branch (item is unused).

take(item: Any, branch: dict[str, Any]) → DataFrame

The body’s input for one branch (required; e.g. item[branch]).

Called once per branch, lazily where the body consumes it – in-worker when the body runs off-process.

gather(results: list[BranchResult]) → DataFrame

Concatenated per-timeline events.

build() → DataFrame

alias for run

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 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)

requirements: tp.ClassVar[tuple[str, ...]] = ()

← Back to API reference