Platform Enumerations

Provides the cross-system enumerations that define the Sollertia platform vocabulary: acquisition systems, session types, external read assets, and credentials categories. The module is a leaf that imports nothing from the rest of the library, so every consumer can use the enumerations without creating circular imports.

class sollertia_shared_assets.enums.AcquisitionSystems(*values)

Bases: StrEnum

Defines the data acquisition systems supported by the Sollertia platform.

Every Sollertia acquisition system runs in Virtual Reality, presenting a Unity task in the linear infinite corridor. Each acquisition runtime package owns its own system configuration classes. This enum remains the shared vocabulary that identifies which runtime acquired a session or a dataset.

MESOSCOPE_VR = 'mesoscope'

Uses the 2-Photon Random Access Mesoscope (2P-RAM) from Thor-Labs and a heavily modified Janelia / Allen hardware harness.

class sollertia_shared_assets.enums.CredentialsTypes(*values)

Bases: StrEnum

Defines the credentials categories supported by the Sollertia platform.

Each member’s string value is the canonical identifier for the credentials category. Members are durable contracts added by Sollertia platform maintainers together with a matching CREDENTIALS_FILE_REGISTRY entry. This is a platform-contract surface.

GOOGLE = 'google'

Stores the Google service account credentials used for all interactions with the Google Sheets API (canonical filename google_credentials.json).

class sollertia_shared_assets.enums.ReadAssets(*values)

Bases: StrEnum

Defines the external data-asset formats the platform reads and caches as on-disk dataclasses.

Each member’s string value is the canonical identifier for the read-asset format. Members are durable translation contracts added by Sollertia platform maintainers together with a matching READ_ASSET_REGISTRY entry. This is a platform-contract surface.

SURGERY_DATA = 'surgery_data'

Stores the animal’s surgical-intervention record read from the platform surgery log, held on disk as SurgeryData (canonical filename surgery_metadata.yaml).

class sollertia_shared_assets.enums.SessionTypes(*values)

Bases: StrEnum

Defines the data acquisition session types used across the Sollertia platform. Each acquisition system declares the subset it can run in SYSTEM_SESSION_TYPES.

LICK_TRAINING = 'lick training'

Teaches animals to use the water delivery port while being head-fixed on the Mesoscope-VR system.

MESOSCOPE_EXPERIMENT = 'mesoscope experiment'

Runs virtual reality tasks using Unity game engine and collects brain activity data using the 2-Photon Random Access Mesoscope (2P-RAM).

RUN_TRAINING = 'run training'

Teaches animals to run on the treadmill while being head-fixed on the Mesoscope-VR system.

WINDOW_CHECKING = 'window checking'

Evaluates the quality of the cranial window implantation procedure and the suitability of the animal for experiment sessions using the Mesoscope.

Configuration Assets

Provides configuration assets for data acquisition and processing runtimes in the Sollertia platform.

class sollertia_shared_assets.configuration.Cue(name, code, length_cm, texture)

Bases: object

Defines a single visual cue used in the experiment task’s Virtual Reality (VR) environment.

Notes

Cues are baked into segment prefabs.

code: int

The unique uint8 code (0-255) that identifies the cue during MQTT communication and data analysis.

length_cm: float

The length of the cue in centimeters.

name: str

The visual identifier for the cue (e.g., ‘A’, ‘B’, ‘Gray’). Used to reference the cue in trial cue sequences.

texture: str

The texture filename (e.g., Cue 016 - 4x1.png) located in the Unity project’s Assets/InfiniteCorridorTask/Textures/ directory. Applied 1:1 to the cue wall panels during prefab generation.

class sollertia_shared_assets.configuration.ExperimentState(experiment_state_code, system_state_code, state_duration_s, supports_trials=True, reinforcing_initial_guided_trials=0, reinforcing_recovery_failed_threshold=0, reinforcing_recovery_guided_trials=0, aversive_initial_guided_trials=0, aversive_recovery_failed_threshold=0, aversive_recovery_guided_trials=0)

Bases: object

Defines the structure and runtime parameters of an experiment state (phase).

aversive_initial_guided_trials: int

The number of aversive trials after the onset of the experiment state that use the guidance mode.

aversive_recovery_failed_threshold: int

The number of sequentially failed aversive trials after which to enable the recovery guidance mode.

aversive_recovery_guided_trials: int

The number of guided aversive trials to use in the recovery guidance mode.

experiment_state_code: int

The unique identifier code of the experiment state.

reinforcing_initial_guided_trials: int

The number of reinforcing trials after the onset of the experiment state that use the guidance mode.

reinforcing_recovery_failed_threshold: int

The number of sequentially failed reinforcing trials after which to enable the recovery guidance mode.

reinforcing_recovery_guided_trials: int

The number of guided reinforcing trials to use in the recovery guidance mode.

state_duration_s: float

The time, in seconds, to maintain the experiment state while executing the experiment.

supports_trials: bool

no production code in sollertia-experiment or sollertia-forgery reads it, and a trial-free phase is realized by the state’s system_state_code alone.

Type:

Determines whether trials are executed during this experiment state. This is a declarative annotation

system_state_code: int

The data acquisition system’s state (configuration snapshot) code associated with the experiment state.

class sollertia_shared_assets.configuration.TaskTemplate(cues, vr_environment, trial_structures)

Bases: YamlConfig

Defines a VR task template used by Unity for prefab generation and runtime configuration.

Notes

Task templates contain only the data Unity needs for prefab generation and runtime. Experiment-specific parameters (rewards, guidance, experiment states) live on the matching runtime trial classes defined by each acquisition system. Those classes are joined back to the template by trial name.

This dataclass can parse any valid task configuration (template) .yaml file from the sollertia-virtual-reality project.

cues: list[Cue]

The Virtual Reality environment wall cues used in the task.

trial_structures: dict[str, TrialStructure]

The spatial configuration for each trial type. Keys are trial names (e.g., ‘ABC’).

vr_environment: VREnvironment

The Virtual Reality corridor configuration.

class sollertia_shared_assets.configuration.TrialStructure(cue_sequence, stimulus_trigger_zone_start_cm, stimulus_trigger_zone_end_cm, stimulus_location_cm, show_stimulus_collision_boundary, trigger_type, occupancy_duration_ms=None, transitions=None)

Bases: object

Defines the spatial configuration of a trial structure for Unity prefabs.

Notes

This class contains only the spatial data needed by Unity for prefab generation and runtime zone configuration. Experiment-specific parameters (reward sizes, puff durations, etc.) live on the matching runtime trial classes defined by each acquisition system and are joined back by trial name.

cue_sequence: list[str]

The ordered sequence of cue names that comprise the trial’s segment.

occupancy_duration_ms: float | None

The duration in milliseconds the animal must occupy the zone for occupancy trigger modes. Unity enforces this value, and the template is its single source of truth: no experiment configuration carries a copy. Set it to None on a non-occupancy trial, because None is how a template communicates that the field is unused, while 0 is a real duration and is rejected on every trial whatever its trigger type.

show_stimulus_collision_boundary: bool

Determines whether the stimulus collision boundary marker is visible to the animal during this trial type. When True, Unity enables the MeshRenderer on the trigger zone’s root object, so the marker sits wherever the trigger type places that root. A collision trial anchors the boundary wall’s leading edge on the stimulus location, so the root itself sits half the fixed wall depth past it. An interaction trial places the root at the trigger-zone midpoint, and an occupancy trial offsets it from the stimulus location by half the zone length.

stimulus_location_cm: float

The position of the stimulus boundary (invisible wall), in centimeters. The collision, occupancy_disarm, and occupancy_arm trigger types elicit the stimulus on collision with this boundary, while the interaction and occupancy_trigger types elicit it from the sensor and the occupancy timer instead.

stimulus_trigger_zone_end_cm: float

The position of the trial stimulus trigger zone ending boundary, in centimeters.

stimulus_trigger_zone_start_cm: float

The position of the trial stimulus trigger zone starting boundary, in centimeters.

transitions: dict[str, float] | None

Transition probabilities to the trials that make up the task’s corridor environment. Keys must reference trial names defined on the same TaskTemplate, including this trial itself. If provided and non-empty, values must sum to 1.0. Set to null in the YAML file if not used.

trigger_type: str | TriggerType

The stimulus trigger zone behavior. Must be one of the valid TriggerType enumeration members.

class sollertia_shared_assets.configuration.TriggerType(*values)

Bases: StrEnum

Defines the supported stimulus trigger zone activators for experiment trials.

Notes

These are the platform-wide trigger mechanisms. Each acquisition system supports the subset it can resolve to its own stimuli (Mesoscope-VR supports INTERACTION and OCCUPANCY_DISARM, and leaves the rest unmapped). INTERACTION maps to the StimulusTriggerZone prefab (GuidanceZone child) and the three occupancy types to the OccupancyTriggerZone prefab (OccupancyZone + OccupancyGuidanceZone children) in Unity. COLLISION reuses the StimulusTriggerZone prefab as a bare boundary wall.

COLLISION = 'collision'

A collision-triggered trial where crossing the invisible boundary wall elicits stimulus delivery unconditionally, with no sensor or occupancy requirement.

INTERACTION = 'interaction'

An interaction-triggered trial where the animal must engage an interaction sensor (lick port, button, lever, pressure plate) inside the stimulus trigger zone to elicit stimulus delivery.

OCCUPANCY_ARM = 'occupancy_arm'

An occupancy-arm trial where occupying the zone arms the boundary. Colliding with the now-armed boundary (occupancy met) elicits stimulus delivery.

OCCUPANCY_DISARM = 'occupancy_disarm'

An occupancy-disarm trial where occupying the zone disarms the boundary. Colliding with the still-armed boundary (occupancy not met) elicits stimulus delivery.

OCCUPANCY_TRIGGER = 'occupancy_trigger'

An occupancy-trigger trial where occupying the zone for the required duration elicits stimulus delivery immediately, with no boundary collision.

class sollertia_shared_assets.configuration.VREnvironment(corridor_spacing_cm=20.0, segments_per_corridor=3, padding_prefab_name='Padding', cm_per_unity_unit=10.0, cue_offset_cm=0.0)

Bases: object

Defines the Unity Virtual Reality (VR) corridor system configuration.

Notes

Every numeric field divides or sizes downstream corridor geometry, so the validation below rejects a value that would leave Unity with an infinite segment length, a zero-depth corridor, or a maze generation loop that never terminates. The padding_prefab_name field names a Unity prefab and carries no geometric validation.

Each default matches the one the Unity VREnvironment class declares for the same field, so a template that omits the key loads here with the geometry Unity would apply to it.

cm_per_unity_unit: float

The conversion factor from centimeters to Unity units.

corridor_spacing_cm: float

The horizontal spacing between corridor instances in centimeters.

cue_offset_cm: float

The offset of the animal’s starting position relative to the Virtual Reality (VR) environment’s cue sequence origin, in centimeters.

padding_prefab_name: str

The name of the Unity prefab used for corridor padding.

segments_per_corridor: int

The number of segments visible in each corridor instance (corridor depth).

sollertia_shared_assets.configuration.get_data_root()

Resolves and returns the path to the local machine’s Sollertia platform data root.

Return type:

Path

Returns:

The path to the local data root, the directory under which all project directories are stored.

Raises:

FileNotFoundError – If the local data root has not been configured for the host machine, if the cached path record is empty, or if the currently configured directory does not exist at the expected path.

sollertia_shared_assets.configuration.get_task_templates_directory()

Resolves and returns the path to the sollertia-virtual-reality project’s Assets/InfiniteCorridorTask/Configurations directory.

Return type:

Path

Returns:

The path to the task templates directory.

Raises:

FileNotFoundError – If the task templates directory path has not been configured for the host machine, if the cached path record is empty, or if the previously configured directory does not exist at the expected path.

sollertia_shared_assets.configuration.get_working_directory()

Resolves and returns the path to the local Sollertia platform working directory.

Return type:

Path

Returns:

The path to the local working directory.

Raises:

FileNotFoundError – If the local working directory has not been configured for the host machine, if the cached path record is empty, or if the currently configured directory does not exist at the expected path.

sollertia_shared_assets.configuration.set_data_root(path)

Sets the specified directory as the local machine’s Sollertia platform data root.

Notes

The data root is the directory under which all project directories, and therefore all animal and session directories, are stored on this machine. Persisting it lets the discovery and inventory assets resolve the project hierarchy without the caller supplying the root each time.

This function caches the path to the data root in the user’s data directory.

If the input path does not point to an existing directory, the function creates the requested directory.

Parameters:

path (Path) – The path to the directory to set as the local Sollertia platform data root.

Return type:

None

sollertia_shared_assets.configuration.set_task_templates_directory(path)

Sets the path to the sollertia-virtual-reality project’s Assets/InfiniteCorridorTask/Configurations directory.

Persists the path under platformdirs-managed application data so it is reused by subsequent slsa mcp sessions on the same local machine (PC).

Parameters:

path (Path) – The path to the sollertia-virtual-reality project’s Assets/InfiniteCorridorTask/Configurations directory.

Raises:

• FileNotFoundError – If the specified directory does not exist at the provided path.

• ValueError – If the specified path does not point to a directory.

Return type:

None

sollertia_shared_assets.configuration.set_working_directory(path)

Sets the specified directory as the Sollertia platform working directory for the local machine (PC).

Notes

This function caches the path to the working directory in the user’s data directory.

The function creates the requested directory and its configuration and credentials subdirectories, whether or not the input path already exists.

Parameters:

path (Path) – The path to the directory to set as the local Sollertia platform working directory.

Return type:

None

sollertia_shared_assets.configuration.configuration_utilities.CONFIGURATION_DIRECTORY: str = 'configuration'

The name of the directory that stores configuration files. Used both under the local working directory (where it holds the host’s system configuration and the forgery server configuration) and under each project directory (where it holds the project’s experiment configuration YAML files).

sollertia_shared_assets.configuration.configuration_utilities.CREDENTIALS_DIRECTORY: str = 'credentials'

The name of the working-directory subdirectory that stores all platform credentials files. The constant lives with the working-directory layout (set_working_directory pre-creates the subdirectory). The credentials toolset that fills the subdirectory lives in the top-level credentials module.

Data Contract Assets

Provides contract dataclasses that translate external data records into on-disk formats for Sollertia libraries.

class sollertia_shared_assets.data_classes.DrugData(drug, drug_volume_ml, drug_code)

Bases: object

Stores information about a single medical substance (drug) administered to the subject before, during, or immediately after the surgical intervention.

drug: str

The descriptive name of the drug.

drug_code: str

The manufacturer code or internal reference code for the administered drug.

drug_volume_ml: float

The volume of the drug administered to the subject, in milliliters.

class sollertia_shared_assets.data_classes.ImplantData(implant, implant_target, implant_code, implant_ap_coordinate_mm, implant_ml_coordinate_mm, implant_dv_coordinate_mm)

Bases: object

Stores information about a single implantation procedure performed during the surgical intervention.

implant: str

The descriptive name of the implant.

implant_ap_coordinate_mm: float

The implant’s antero-posterior stereotactic coordinate, in millimeters, relative to bregma.

implant_code: str

The manufacturer code or internal reference code for the implant.

implant_dv_coordinate_mm: float

The implant’s dorsal-ventral stereotactic coordinate, in millimeters, relative to bregma.

implant_ml_coordinate_mm: float

The implant’s medial-lateral stereotactic coordinate, in millimeters, relative to bregma.

implant_target: str

The name of the brain region or cranium section targeted by the implant.

class sollertia_shared_assets.data_classes.InjectionData(injection, injection_target, injection_volume_nl, injection_code, injection_ap_coordinate_mm, injection_ml_coordinate_mm, injection_dv_coordinate_mm)

Bases: object

Stores information about a single injection performed during the surgical intervention.

injection: str

The descriptive name of the injection.

injection_ap_coordinate_mm: float

The injection’s antero-posterior stereotactic coordinate, in millimeters, relative to bregma.

injection_code: str

The manufacturer code or internal reference code for the injected substance.

injection_dv_coordinate_mm: float

The injection’s dorsal-ventral stereotactic coordinate, in millimeters, relative to bregma.

injection_ml_coordinate_mm: float

The injection’s medial-lateral stereotactic coordinate, in millimeters, relative to bregma.

injection_target: str

The name of the brain region targeted by the injection.

injection_volume_nl: float

The volume of substance, in nanoliters, delivered during the injection.

class sollertia_shared_assets.data_classes.ProcedureData(surgery_start_us, surgery_end_us, surgeon, protocol, surgery_notes, post_op_notes, surgery_quality=0)

Bases: object

Stores general information about the surgical intervention.

post_op_notes: str

The surgeon’s notes taken during the post-surgery recovery period.

protocol: str

The number (ID) of the experiment protocol used during the surgery.

surgeon: str

The surgeon’s name or ID. If the intervention was carried out by multiple surgeons, the data for all surgeons is stored as part of the same string.

surgery_end_us: int

The surgery’s stop date and time as microseconds elapsed since UTC epoch onset.

surgery_notes: str

The surgeon’s notes taken during the surgery.

surgery_quality: int

The quality of the surgical intervention on a scale from 0 to 3 inclusive. 0 indicates unusable (bad) result, 1 indicates usable result that does not meet the publication threshold, 2 indicates publication-grade result, 3 indicates high-tier publication grade result.

surgery_start_us: int

The surgery’s start date and time as microseconds elapsed since UTC epoch onset.

class sollertia_shared_assets.data_classes.SubjectData(id, ear_punch, sex, genotype, date_of_birth_us, weight_g, cage, location_housed, status)

Bases: object

Stores information about the subject of the surgical intervention.

cage: int

The unique identifier (number) of the cage used to house the subject after the surgery.

date_of_birth_us: int

The subject’s date of birth, stored as the number of microseconds elapsed since the UTC epoch onset.

ear_punch: str

The number and the locations of ear punches used to distinguish the subject from its cage-mates.

genotype: str

The subject’s genotype.

id: int

The subject’s unique identifier.

location_housed: str

The location (room) used to house the subject after the surgery.

sex: str

The subject’s sex.

status: str

The subject’s current status (alive / deceased).

weight_g: float

The subject’s pre-surgery weight, in grams.

class sollertia_shared_assets.data_classes.SurgeryData(subject, procedure, drugs, implants, injections)

Bases: YamlConfig

Stores information about a surgical intervention performed on an animal before data acquisition session(s).

drugs: list[DrugData]

All medical substances (drugs) administered to the subject before, during, and immediately after the surgical intervention.

implants: list[ImplantData]

All implantation procedures performed during the surgical intervention.

injections: list[InjectionData]

All injections (brain infusions) performed during the surgical intervention.

procedure: ProcedureData

The general parameters of the surgical intervention.

subject: SubjectData

The animal that underwent the surgical intervention.

Data Hierarchy Assets

Provides assets for creating, discovering, and accessing the Sollertia platform project data hierarchy.

class sollertia_shared_assets.data_hierarchy.AnimalData(root, project_name, animal_id)

Bases: object

Resolves the on-disk locations of a single animal’s assets under a given data root.

Like ProjectData, instances are path-grammar views that do not require the animal directory to exist. Rebind the animal under a different root with for_root to resolve its session paths on a remote storage root.

animal_id: str

The unique identifier of the animal, used as the animal directory name.

exists()

Determines whether the animal directory exists on disk under the project.

Return type:

bool

for_root(root)

Returns a copy of this animal anchored on a different data root.

Parameters:

root (Path) – The data root under which the animal is rebound, such as a mounted remote storage root.

Return type:

AnimalData

Returns:

A new AnimalData with the same project and animal resolved under the input root.

property path: Path

Returns the absolute path to the animal directory under the project.

property persistent_data_path: Path

Returns the absolute path to the animal’s cross-session persistent data directory.

property project: ProjectData

Returns the ProjectData view for the project this animal belongs to.

project_name: str

The name of the project to which the animal belongs.

root: Path

The data root under which the project hierarchy is stored.

session_path(session_name)

Returns the absolute path to the session directory for the given session name.

Parameters:

session_name (str) – The unique identifier of the session, used as the session directory name.

Return type:

Path

Returns:

The absolute path to the session directory under this animal.

class sollertia_shared_assets.data_hierarchy.DatasetAnimal(animal, animal_path=PosixPath('.'))

Bases: object

Defines a single animal included in a forged dataset.

Combines the animal identity metadata with the resolved path to the animal’s directory within the dataset hierarchy. Per-animal artifacts (such as surgery metadata) are co-located in this directory and exposed as derived properties.

animal: str

The unique identifier of the animal.

animal_path: Path

The path to the animal’s directory within the dataset hierarchy (dataset/animal).

property surgery_path: Path

Returns the path to the animal’s surgery_metadata.yaml file within the dataset hierarchy.

class sollertia_shared_assets.data_hierarchy.DatasetData(name, project, session_type, acquisition_system, sessions=<factory>, dataset_data_path=PosixPath('.'))

Bases: YamlConfig

Defines the structure and the metadata of a forged dataset.

A forged dataset aggregates multiple data acquisition sessions of the same type, recorded across different animals by the same acquisition system.

Notes

Do not initialize this class directly. Instead, use the create() method when creating new datasets or the load() method when accessing data for an existing dataset.

Datasets are created using a pre-filtered set of session + animal pairs, typically obtained through the session filtering functionality in sollertia-forgery. The dataset stores the assembled data together with the raw-data snapshots re-exported alongside it, leaving the sessions’ raw_data and processed_data trees in place, because a dataset carries the forged output rather than a copy of its sources. Each created dataset carries a per-dataset data_descriptions.feather describing the meaning of every column its acquisition system can emit. Use column_descriptions() and get_column_description() to read it.

acquisition_system: str | AcquisitionSystems

The name of the data acquisition system used to acquire all sessions in the dataset.

add_sessions(sessions)

Adds the specified sessions to the dataset and materializes their directories in the dataset hierarchy.

Notes

The append counterpart to create(). Each added session’s directory is created under the dataset root and the updated dataset marker is written to disk, so the hierarchy and the marker stay consistent. A failure that lands before the marker write, an interrupt included, removes the directories this call created and restores the instance’s session list to the state the marker on disk still describes. The identical call can therefore be retried once the cause of the failure is resolved. The session_path attribute of each input instance is ignored and replaced with the resolved path inside the dataset hierarchy, matching how create() treats its input.

The method enforces the dataset’s structural invariants alone. Deciding whether a session belongs in a given dataset, such as verifying its session type or its acquisition system, is left to the caller.

Parameters:

sessions (tuple[DatasetSession, ...] | set[DatasetSession]) – The DatasetSession instances that identify the sessions to add to the dataset.

Return type:

tuple[DatasetSession, ...]

Returns:

The added DatasetSession instances, each carrying its resolved path inside the dataset hierarchy.

Raises:

• ValueError – If no sessions are provided, if any provided session is already part of the dataset or is repeated within the provided collection, or if any animal or session identifier does not name a single directory.

• OSError – If a session directory cannot be materialized on disk, or if the dataset marker cannot be written. The directories this call created are removed before the error propagates.

property animals: tuple[DatasetAnimal, ...]

Returns one DatasetAnimal per unique animal in the dataset, each anchored on the dataset.yaml file’s filesystem location so the result remains portable across processing machines.

column_descriptions()

Returns the mapping from each column name in the dataset’s data.feather to its description.

Reads the per-dataset data_descriptions.feather companion file written at dataset creation. Every forged dataset is required to carry this file, so its absence indicates a malformed or incomplete dataset.

Return type:

dict[str, str]

Returns:

The ordered mapping from each column name the acquisition system can emit to its human-readable description.

Raises:

FileNotFoundError – If the dataset’s data_descriptions.feather companion file does not exist.

classmethod create(name, project, session_type, acquisition_system, sessions, datasets_root, column_descriptions)

Creates a new forged dataset and initializes its data structure on disk.

Notes

To access the data of an already existing dataset, use the load() method.

The creation is transactional. Every screen runs before the first directory is created, and any failure that lands between the first created directory and the marker write, an interrupt included, removes the dataset directory this call has built before the failure propagates. The dataset name therefore stays available for a corrected retry, instead of being held by a markerless tree that load() cannot read and that create() refuses as an already-existing dataset. The datasets root itself is left in place, since a caller that points at a missing root asks for that root to be created.

Parameters:

• name (str) – The unique name for the dataset. Must name a single directory under the datasets root.

• project (str) – The name of the project from which the dataset’s sessions originate.

• session_type (str | SessionTypes) – The type of data acquisition sessions included in the dataset.

• acquisition_system (str | AcquisitionSystems) – The name of the data acquisition system used to acquire all sessions included in the dataset.

• sessions (tuple[DatasetSession, ...] | set[DatasetSession]) – The set of DatasetSession instances that identify the sessions whose data should be included in the dataset. The session_path attribute of each input instance is ignored and replaced with the resolved path inside the dataset hierarchy.

• datasets_root (Path) – The path to the root directory in which to create the dataset’s hierarchy.

• column_descriptions (dict[str, str]) – The mapping from each column name the dataset’s acquisition system can emit into data.feather to its human-readable description. Written to the dataset root as data_descriptions.feather so consumers can interpret the assembled data. Every entry must bind a non-empty string column name to a non-empty string description. An empty mapping is valid and writes an empty companion feather.

Return type:

DatasetData

Returns:

An initialized DatasetData instance that stores the structure and the metadata of the created dataset.

Raises:

• ValueError – If the specified name does not name a single directory, or if the specified session_type or acquisition_system is not a valid enumeration member. Also raised if no sessions are provided, if the same animal and session pair is named more than once in the provided collection, or if any animal or session identifier does not name a single directory. Finally, raised if any column_descriptions entry binds a column name or a description that is not a non-empty string.

• FileExistsError – If a dataset with the same name already exists.

• OSError – If the dataset hierarchy cannot be materialized on disk. The part of the hierarchy this call has already built is removed before the error propagates.

• RuntimeError – If the hierarchy a failed creation has built cannot be removed from disk, since the dataset name then stays held by a tree no consumer can load.

dataset_data_path: Path = PosixPath('.')

The resolved path to this dataset’s dataset.yaml file. Kept out of the written marker and re-derived from the YAML’s on-disk location on load, so the dataset remains portable across machines.

property descriptions_path: Path

Returns the path to this dataset’s data_descriptions.feather file at the dataset root, resolved against the dataset.yaml file’s filesystem location so the path remains portable across processing machines.

get_animal(animal)

Returns the DatasetAnimal instance for the specified animal identifier.

Parameters:

animal (str) – The unique identifier of the animal to look up.

Return type:

DatasetAnimal

Returns:

The DatasetAnimal instance carrying the animal identity metadata and the path to the animal’s directory within the dataset hierarchy.

Raises:

ValueError – If the specified animal is not found in the dataset.

get_column_description(column)

Returns the description for a single column in the dataset’s data.feather.

Parameters:

column (str) – The name of the column whose description to look up.

Return type:

str

Returns:

The human-readable description of the specified column.

Raises:

• FileNotFoundError – If the dataset’s data_descriptions.feather companion file does not exist.

• ValueError – If the specified column has no description recorded for this dataset.

get_session(animal, session)

Returns the DatasetSession instance for the specified animal and session pair.

Parameters:

• animal (str) – The unique identifier of the animal that participated in the session.

• session (str) – The unique identifier of the session to look up.

Return type:

DatasetSession

Returns:

The DatasetSession instance containing the session identity metadata and the path to the session’s directory within the dataset hierarchy.

Raises:

ValueError – If the specified animal and session combination is not found in the dataset.

get_sessions_for_animal(animal)

Returns the DatasetSession instances for all sessions performed by the specified animal.

Parameters:

animal (str) – The unique identifier of the animal for which to retrieve the session data.

Return type:

tuple[DatasetSession, ...]

Returns:

A tuple of DatasetSession instances for the specified animal.

classmethod load(dataset_path)

Loads the target dataset’s data from the specified dataset.yaml file.

Notes

To create a new dataset, use the create() method.

Parameters:

dataset_path (Path) – The path to the directory in which to search for the dataset.yaml file. Typically, this is the path to the root dataset directory.

Return type:

DatasetData

Returns:

An initialized DatasetData instance that stores the loaded dataset’s data.

Raises:

• FileNotFoundError – If multiple or no ‘dataset.yaml’ file instances are found under the input directory.

• OSError – If the fallback scan encounters a directory it cannot read.

• ValueError – If the loaded marker carries a session type or an acquisition system outside the platform vocabulary.

name: str

The unique name of the dataset.

project: str

The name of the project from which the dataset’s sessions originate.

remove_animal(animal)

Removes the specified animal and every session it performed from the dataset.

Notes

The removal counterpart to create(), which materializes the per-animal directories this method deletes. The animal’s directory is removed from the dataset tree together with everything under it, including the assembled data of every session it holds and the per-animal artifacts co-located there. The updated dataset marker is written to disk once the directory is confirmed to be gone. An animal directory that is a symlink is unlinked in place, so the tree at which it points stays whole and only the dataset’s reference to it is dropped. Pairing this method with add_sessions() rebuilds one animal while every other animal in the dataset keeps its data. A failed marker write restores the instance’s session list to the state the marker on disk still describes, so the identical call can be retried once the cause of the failure is resolved.

Parameters:

animal (str) – The unique identifier of the animal to remove from the dataset.

Return type:

tuple[DatasetSession, ...]

Returns:

The DatasetSession instances removed from the dataset.

Raises:

• ValueError – If the specified animal is not part of the dataset, or if its identifier does not name a single directory.

• RuntimeError – If the animal’s directory survives the removal attempt, since dropping the animal from the marker would stop the dataset from describing data that is still on disk.

• OSError – If the animal’s directory tree cannot be read or removed, or if the dataset marker cannot be written. The instance’s session list is restored to the state the marker on disk describes before the error propagates.

save()

Caches the instance’s data to the dataset’s root directory as a ‘dataset.yaml’ file.

Return type:

None

session_type: str | SessionTypes

The type of data acquisition sessions included in the dataset. All sessions in a dataset must be of the same type.

sessions: tuple[DatasetSession, ...]

The DatasetSession instances that identify and locate each session included in the dataset.

verify_data_descriptions()

Verifies that every column written into any session’s data.feather is described by the dataset.

Reads the per-dataset data_descriptions.feather mapping, then scans the schema of every session’s assembled data.feather (without loading the data) and confirms each column name appears in the mapping. The contract is one-directional: a described column that no session emits is permitted (columns can be conditionally emitted), but a column written into a session’s feather with no matching description is a violation.

Return type:

None

Notes

Intended to run once the dataset is fully composed (every session’s data.feather written), so an acquisition system that emits an undescribed column fails rather than producing a dataset whose assembled data cannot be fully interpreted.

Raises:

• FileNotFoundError – If the dataset’s data_descriptions.feather companion file does not exist, or if any session’s data.feather file does not exist.

• ValueError – If any session’s data.feather contains a column with no description recorded for this dataset. The error names every undescribed column together with the sessions that emit it.

class sollertia_shared_assets.data_hierarchy.DatasetFiles(*values)

Bases: StrEnum

Enumerates the canonical, system-agnostic filenames written into a forged dataset hierarchy.

Notes

Centralizes the dataset filenames so new artifacts can be added in one place and referenced symbolically from path-resolution properties on DatasetData, DatasetSession, and DatasetAnimal. Two universal output contracts live here: every system’s forged session writes a per-session data.feather, and every forged dataset carries a single per-dataset data_descriptions.feather mapping each emittable column name to its human-readable description. Shared raw-data assets re-exported alongside the data keep their canonical RawDataFiles names: the session descriptor, VR configuration, and experiment configuration at session granularity, and the per-animal surgery metadata at animal granularity. The session descriptor is universal, but the VR and experiment configurations are present only for the session types that carry them (sessions that use VR and experiment sessions, respectively), so a forged session exposes whichever subset it actually holds.

DATA = 'data.feather'

The assembled per-session data feather written by the forging pipeline. The file is loadable by polars regardless of which columns it contains, which keeps the dataset system-agnostic at the data layer.

DESCRIPTIONS = 'data_descriptions.feather'

The per-dataset companion feather mapping each column name in data.feather to its description. Written once at the dataset root, since every session in a dataset shares the same data format.

class sollertia_shared_assets.data_hierarchy.DatasetSession(session, animal, session_path=PosixPath('.'))

Bases: object

Defines a single session included in a forged dataset.

Combines the session identity metadata with the resolved path to the session’s directory within the dataset hierarchy.

animal: str

The unique identifier of the animal that participated in the session.

property data_path: Path

Returns the path to the session’s assembled data.feather file within the dataset hierarchy.

property descriptor_path: Path

Returns the path to the session’s session_descriptor.yaml file within the dataset hierarchy.

property experiment_configuration_path: Path

Returns the path to the session’s experiment_configuration.yaml file within the dataset hierarchy, which only experiment session types carry, so callers should check .is_file() before reading.

session: str

The unique identifier of the session. Session names follow the format ‘YYYY-MM-DD-HH-MM-SS-microseconds’ and encode the session’s acquisition timestamp.

session_path: Path

The path to the session’s directory within the dataset hierarchy (dataset/animal/session). Kept out of the written marker, since DatasetData.load re-resolves it from the marker’s own on-disk location.

property vr_configuration_path: Path

Returns the path to the session’s vr_configuration.yaml file within the dataset hierarchy, which only sessions that use VR carry, so callers should check .is_file() before reading.

class sollertia_shared_assets.data_hierarchy.Directories(*values)

Bases: StrEnum

Enumerates the canonical names of subdirectories found under a session’s raw_data or processed_data that are shared across all acquisition systems on the platform.

BEHAVIOR_DATA = 'behavior_data'

Raw behavior data directory under raw_data. Contains the DataLogger NPZ archives captured during acquisition, including the raw microcontroller and runtime messages.

CAMERA_DATA = 'camera_data'

Raw camera data directory under raw_data. Stores the raw camera recordings captured during acquisition. Processed video outputs live under the separate video_data directory.

CINDRA = 'cindra'

Cindra output directory under processed_data. The root of cindra’s single-recording and multi-recording outputs. Cindra is reusable by any neural-imaging-data-generating acquisition system. The name mirrors cindra’s own OUTPUT_DIRECTORY_NAME constant, which cindra owns and which nothing here imports, so the two can drift.

MICROCONTROLLER_DATA = 'microcontroller_data'

Microcontroller data directory under processed_data. Holds the extracted and parsed microcontroller data and the microcontroller processing tracker produced by the sollertia-forgery microcontroller-processing pipeline. Microcontroller raw data is bundled into the DataLogger archives under raw_data/behavior_data rather than living in a dedicated raw-side directory.

RUNTIME_DATA = 'runtime_data'

Runtime data directory under processed_data. Holds the runtime-extracted behavior data and the runtime processing tracker produced by the sollertia-forgery runtime-processing pipeline.

VIDEO_DATA = 'video_data'

Video data directory under processed_data. Holds the per-frame camera timestamps extracted from the camera log archives and the video processing tracker, and is the destination for sollertia-forgery pose-estimation outputs.

class sollertia_shared_assets.data_hierarchy.ProcessedData(runtime_data_path, runtime_tracker_path, video_data_path, video_tracker_path, microcontroller_data_path, microcontroller_tracker_path, cindra_data_path, two_photon_tracker_path)

Bases: object

Stores the paths to all generic processed assets of a single data acquisition session, resolved against the session’s processed-data root, which is absolute once load() has finalized it.

Notes

Cindra fields live here because cindra is reusable by any neural-imaging-data-generating acquisition system, not Mesoscope-VR-specific. Future processing tools that apply across acquisition systems get added directly as new fields here.

classmethod build(root)

Builds a ProcessedData instance with every field resolved against the input processed data root.

Parameters:

root (Path) – The path to the session’s processed_data directory.

Return type:

ProcessedData

Returns:

A ProcessedData instance whose fields are resolved under the input root.

cindra_data_path: Path

The root for both single-recording and multi-recording cindra outputs.

microcontroller_data_path: Path

The extracted and parsed microcontroller data produced by the sollertia-forgery microcontroller-processing pipeline.

microcontroller_tracker_path: Path

The tracker for the sollertia-forgery microcontroller-processing pipeline. Resolves to microcontroller_data/microcontroller_processing_tracker.yaml.

runtime_data_path: Path

The runtime-extracted behavior data produced by the sollertia-forgery runtime-processing pipeline.

runtime_tracker_path: Path

The tracker for the sollertia-forgery runtime-processing pipeline. Resolves to runtime_data/runtime_processing_tracker.yaml.

two_photon_tracker_path: Path

The tracker for the two-photon (calcium-imaging) processing stage. The tracker file is written by cindra’s single-recording pipeline and only read by sollertia-forgery. Resolves to cindra/single_recording_tracker.yaml.

video_data_path: Path

The per-frame camera timestamps extracted from the camera log archives and the re-packaged pose-estimation output produced by the sollertia-forgery video-processing pipeline.

video_tracker_path: Path

The tracker for the sollertia-forgery video-processing pipeline. Resolves to video_data/video_processing_tracker.yaml.

class sollertia_shared_assets.data_hierarchy.ProcessingTrackers(*values)

Bases: StrEnum

Enumerates canonical ProcessingTracker filenames written by each data-integrity and processing pipeline shared across all acquisition systems on the platform.

CHECKSUM = 'checksum_processing_tracker.yaml'

Tracker for the checksum verification pipeline. Lives at the raw_data root.

FORGING = 'forging_tracker.yaml'

Tracker for the sollertia-forgery dataset-forging pipeline. Lives at the forged dataset root.

MANIFEST = 'manifest_processing_tracker.yaml'

Tracker for the project manifest generation pipeline. Lives at the project root.

MICROCONTROLLER = 'microcontroller_processing_tracker.yaml'

Tracker for the sollertia-forgery microcontroller-processing pipeline (ataraxis-communication-interface log extraction followed by module parsing). Lives under processed_data/microcontroller_data.

RUNTIME = 'runtime_processing_tracker.yaml'

Tracker for the sollertia-forgery runtime-processing pipeline (runtime DataLogger decode and behavior-data extraction). Lives under processed_data/runtime_data.

TWO_PHOTON = 'single_recording_tracker.yaml'

Tracker for the two-photon (calcium-imaging) processing stage. The filename is owned and written by cindra’s single-recording pipeline. Sollertia-forgery only reads it. Lives under processed_data/cindra. The value mirrors cindra’s own SINGLE_RECORDING_TRACKER_FILENAME constant, which nothing here imports, so the two can drift. Cindra’s multi-recording tracker is deliberately absent from this enum, since it is written once per dataset inside a dataset-named directory that no fixed per-session path addresses.

VIDEO = 'video_processing_tracker.yaml'

Tracker for the sollertia-forgery video-processing pipeline (camera-timestamp extraction and pose-estimation re-packaging). Lives under processed_data/video_data.

class sollertia_shared_assets.data_hierarchy.ProjectData(root, project_name)

Bases: object

Resolves the on-disk locations of a single project’s assets under a given data root.

Instances are lightweight path-grammar views: they construct paths from the root and project name and do not require the project directory to exist on disk. Rebind the same project under a different root with for_root to resolve its locations on a remote storage root, or materialize the project’s directory structure on the current root with create.

animal(animal_id)

Returns the AnimalData view for the given animal under this project.

Parameters:

animal_id (str) – The unique identifier of the animal, used as the animal directory name.

Return type:

AnimalData

Returns:

An AnimalData anchored on the same root and project as this instance.

property configuration_directory: Path

Returns the absolute path to the project’s experiment configuration directory.

create()

Creates the project’s directory structure under the data root.

Materializes the project’s configuration directory, which also creates the project directory itself as a parent. The operation is idempotent, so existing directories are left untouched.

Return type:

ProjectData

Returns:

This instance, to support call chaining.

exists()

Determines whether the project directory exists on disk under the data root.

Return type:

bool

experiment_configs()

Returns the naturally-sorted experiment configuration YAML paths under the project’s configuration directory.

Return type:

tuple[Path, ...]

Returns:

A tuple of the .yaml file paths directly under the configuration directory, ordered by natural (human-friendly) sort of their filenames, empty when the directory does not exist.

for_root(root)

Returns a copy of this project anchored on a different data root.

Parameters:

root (Path) – The data root under which the project is rebound, such as a mounted remote storage root.

Return type:

ProjectData

Returns:

A new ProjectData with the same project name resolved under the input root.

property path: Path

Returns the absolute path to the project directory under the data root.

project_name: str

The name of the project, used as the project directory name directly under the root.

root: Path

The data root under which the project hierarchy is stored.

class sollertia_shared_assets.data_hierarchy.RawData(session_data_path, session_descriptor_path, surgery_metadata_path, hardware_state_path, system_configuration_path, experiment_configuration_path, vr_configuration_path, checksum_path, checksum_tracker_path, nk_path, behavior_data_path, camera_data_path)

Bases: object

Stores the absolute paths to all generic raw assets of a single data acquisition session.

Notes

The build classmethod is the single source of truth for the enum-to-field mapping.

behavior_data_path: Path

The raw behavior data captured during acquisition, including the raw messages emitted by every microcontroller managed by ataraxis-communication-interface.

classmethod build(root)

Builds a RawData instance with every field resolved against the input raw data root.

Parameters:

root (Path) – The path to the session’s raw_data directory.

Return type:

RawData

Returns:

A RawData instance whose fields are absolute paths under the input root.

camera_data_path: Path

The raw camera recordings captured during acquisition.

checksum_path: Path

The ataraxis data-integrity checksum used by the checksum verification pipeline to detect corruption or accidental modification of raw assets after acquisition.

checksum_tracker_path: Path

The tracker for the integrity checks performed by the checksum verification pipeline.

experiment_configuration_path: Path

The experiment configuration in effect when the session was acquired. Only populated for experiment sessions. Callers should check .exists() before reading. The concrete parsing class is determined by the session’s acquisition_system and is dispatched via EXPERIMENT_CONFIGURATION_REGISTRY.

hardware_state_path: Path

The configuration of every active hardware module on the acquisition system, used to interpret the raw data during downstream processing. The concrete parsing class is determined by the session’s acquisition_system and is dispatched via HARDWARE_STATE_REGISTRY.

nk_path: Path

The marker present while the acquisition runtime is still creating snapshots and initializing instruments. Removed by mark_runtime_initialized() once the session is ready to begin acquisition.

session_data_path: Path

The metadata that identifies the session and resolves the on-disk locations of all of its assets.

session_descriptor_path: Path

The task parameters and outcome metadata captured during acquisition. The concrete descriptor class is determined by the session’s session_type and is dispatched via DESCRIPTOR_REGISTRY.

surgery_metadata_path: Path

A frozen snapshot of the animal’s surgical history (subject, procedure, drugs, implants, injections) as it stood at the moment the session was acquired. The acquisition system writes it during post-session preprocessing, so the path resolves before the file exists.

system_configuration_path: Path

The acquisition-system-level configuration in effect when the session was acquired. The concrete parsing class is determined by the session’s acquisition_system and is owned by sollertia-experiment.

vr_configuration_path: Path

The linear infinite corridor task template (cues, VR environment, trial structures) active when the session was acquired. Written only for session types listed in SESSION_TYPES_USING_VR_TASK, so callers should check .exists() before reading. Parsed via TaskTemplate.

class sollertia_shared_assets.data_hierarchy.RawDataFiles(*values)

Bases: StrEnum

Enumerates the canonical filenames at the root of a session’s raw_data directory that are written by every acquisition system on the platform.

CHECKSUM = 'ax_checksum.txt'

The ataraxis data integrity checksum for the session’s raw_data directory.

EXPERIMENT_CONFIGURATION = 'experiment_configuration.yaml'

The experiment configuration YAML copied into the session for experiment sessions only.

HARDWARE_STATE = 'hardware_state.yaml'

The hardware state snapshot YAML written at the start of acquisition.

NK_MARKER = 'nk.bin'

The ‘uninitialized session’ marker present in raw_data while the acquisition runtime has not yet finished creating snapshots and initializing instruments. Removed by mark_runtime_initialized() once initialization completes.

SESSION_DATA = 'session_data.yaml'

The session marker YAML serialized from SessionData itself.

SESSION_DESCRIPTOR = 'session_descriptor.yaml'

The session-embedded descriptor YAML written by the acquisition runtime. The concrete descriptor class is determined by the session’s session_type, but the filename is flat across all session types.

SURGERY_METADATA = 'surgery_metadata.yaml'

The per-animal surgery metadata YAML cached into the session’s raw_data by acquisition-system preprocessing after the session ends. Absent until preprocessing runs.

SYSTEM_CONFIGURATION = 'system_configuration.yaml'

The system configuration YAML copied into the session by the acquisition runtime.

VR_CONFIGURATION = 'vr_configuration.yaml'

The linear infinite corridor task template YAML (cues, VR environment, trial structures) cached into the session at acquisition time. Written only for session types listed in SESSION_TYPES_USING_VR_TASK.

class sollertia_shared_assets.data_hierarchy.SessionData(project_name, animal_id, session_name, session_type, acquisition_system, experiment_name=None, python_version='3.14.6', sollertia_experiment_version='5.0.0', raw_data_path=PosixPath('.'), processed_data_path=PosixPath('.'))

Bases: YamlConfig

Defines the structure and the metadata of a data acquisition session.

Notes

Do not initialize this class directly. Instead, use the create() method when starting new data acquisition sessions or the load() method when accessing data for an existing session. Both methods build the runtime-only raw_data, processed_data, and system_raw_data sub-dataclass attributes from the currently configured root paths. create() finalizes only raw_data_path. The processed_data root is resolved later, on the processing host, by load(), which finalizes both. Instances constructed via from_yaml directly (without going through load()) do not have these attributes populated. Access raises AttributeError.

When this class is used to create a new session, it generates the new session’s name using the current UTC timestamp, accurate to microseconds. This ensures that each session ‘name’ is unique and preserves the overall session order.

acquisition_system: str | AcquisitionSystems

The name of the data acquisition system used to acquire the session’s data.

animal_id: str

The unique identifier of the animal that participates in the session.

classmethod create(animal, session_type, python_version, sollertia_experiment_version, acquisition_system, experiment_name=None)

Initializes a new data acquisition session and creates its data structure on the host machine’s filesystem.

Notes

To access the data of an already existing session, use the load() method.

Parameters:

• animal (AnimalData) – The AnimalData view identifying the data root, project, and animal under which the session is created. The session is created under animal.session_path(<session_name>).

• session_type (str | SessionTypes) – The type of the session.

• python_version (str) – The Python version used to acquire the session’s data.

• sollertia_experiment_version (str) – The sollertia-experiment library version used to acquire the session’s data.

• acquisition_system (str | AcquisitionSystems) – The acquisition system that will run the session. Accepts an AcquisitionSystems enumeration member or its string value.

• experiment_name (str | None, default: None) – The name of the experiment performed during the session or None, if the session is not an experiment session.

Return type:

SessionData

Returns:

An initialized SessionData instance that stores the structure and the metadata of the created session.

Raises:

• ValueError – If the specified session_type or acquisition_system is not a valid enumeration member, if the acquisition system does not support the requested session type (per SYSTEM_SESSION_TYPES), or if a session type listed in SESSION_TYPES_USING_VR_TASK is created without an experiment_name.

• FileNotFoundError – If the project does not exist on the local machine (PC), or if the named experiment’s configuration YAML is absent from the project’s configuration directory. Also raised if the task templates directory has not been configured, or if the experiment’s task template YAML is absent from it.

experiment_name: str | None = None

The name of the experiment performed during the session or Null (None), if the session is not an experiment session.

classmethod load(session_path)

Loads the target session’s data from the specified session_data.yaml file.

Notes

To create a new session, use the create() method.

Parameters:

session_path (Path) – The path to the directory in which to search for the session_data.yaml file. Typically, this is the path to the root session’s directory, e.g.: root/project/animal/session.

Return type:

SessionData

Returns:

An initialized SessionData instance that stores the loaded session’s data.

Raises:

• FileNotFoundError – If multiple or no ‘session_data.yaml’ file instances are found under the input directory.

• OSError – If the fallback scan encounters a directory it cannot read.

• ValueError – If the loaded marker carries a session type or an acquisition system outside the platform vocabulary.

mark_runtime_initialized()

Removes the ‘nk.bin’ uninitialized-session marker after acquisition-runtime initialization completes.

Return type:

None

Notes

Do not call this method manually. Removal of the marker only changes the uninitialized signal. The separate descriptor incomplete field is updated independently by the runtime at session end to report whether acquisition completed without issues.

Resolves the marker path directly from raw_data_path so the method works on instances that have not yet been routed through _build_sub_dataclasses.

processed_data: ProcessedData

The runtime-only sub-dataclass exposing the session’s processed-data asset paths, populated by create() and load(), though create() leaves its root at the default until load() resolves it on the processing host.

processed_data_path: Path = PosixPath('.')

The path to the root directory that stores the session’s processed data. Kept out of the written marker, since load re-resolves it from the marker’s own on-disk location.

project_name: str

The name of the project for which the session was acquired.

python_version: str = '3.14.6'

The Python version used to acquire the session’s data.

raw_data: RawData

The runtime-only sub-dataclass exposing the session’s raw-data asset paths, populated by create() and load().

raw_data_path: Path = PosixPath('.')

The path to the root directory that stores the session’s raw data. Kept out of the written marker, since load re-resolves it from the marker’s own on-disk location.

required_raw_assets()

Returns the canonical filename and absolute path of every raw asset this session is required to contain.

Every session requires the session descriptor and the system configuration snapshot. Experiment sessions (those with an experiment_name) additionally require the experiment configuration snapshot, and sessions whose type uses VR (those in SESSION_TYPES_USING_VR_TASK) additionally require the VR configuration snapshot.

Return type:

list[tuple[str, Path]]

Returns:

A list of (canonical_filename, absolute_path) tuples, one per raw asset the session must contain.

save()

Caches the instance’s data to the session’s ‘raw_data’ directory as a ‘session_data.yaml’ file.

Return type:

None

Notes

Resolves the destination path directly from raw_data_path so the method works on instances that have not yet been routed through _build_sub_dataclasses. Both root paths carry YAML_EXCLUDE_METADATA, so the acquisition host’s absolute paths never enter the saved file and load re-resolves them from the file’s own on-disk location. The write itself is atomic, so an interrupted save leaves the previously written marker intact.

session_name: str

The unique identifier (name) of the session.

session_type: str | SessionTypes

The type of the session.

sollertia_experiment_version: str = '5.0.0'

The sollertia-experiment library version used to acquire the session’s data.

system_raw_data: Any

The runtime-only sub-dataclass exposing the acquisition-system-specific raw-data asset paths, populated by create() and load().

sollertia_shared_assets.data_hierarchy.discover_projects(root_path, strategy='markers')

Discovers the projects under a data root and returns them as ProjectData views.

The markers strategy is authoritative: it loads every session marker and buckets projects by their SessionData identity, so only projects that hold at least one session surface and stray directories cannot appear as phantom projects. The directories strategy lists the project directories directly, which also surfaces projects that hold no sessions yet, at the cost of trusting the directory layout.

Parameters:

• root_path (Path) – The absolute path to the data root to scan.

• strategy (Literal['markers', 'directories'], default: 'markers') – Whether to derive projects from session markers (markers) or from the directory layout (directories).

Return type:

list[ProjectData]

Returns:

A list of ProjectData views anchored on the data root, naturally sorted by project name.

Raises:

• OSError – If the scan encounters a directory it cannot read.

• FileNotFoundError – If the markers strategy discovers a marker that no longer resolves to exactly one session_data.yaml file.

• ValueError – If the markers strategy loads a marker carrying a session type or an acquisition system outside the platform vocabulary.

sollertia_shared_assets.data_hierarchy.discover_sessions(root_path)

Discovers session root directories under a root path by locating session_data.yaml markers.

Recursively searches for RawDataFiles.SESSION_DATA markers and derives each session’s root directory from the marker location. Returns only the resolved paths without loading or validating session data.

Notes

The scan raises on a directory it cannot read rather than skipping it, so a partially readable data root reports the failure instead of silently returning a subset of the sessions it holds.

Parameters:

root_path (Path) – The absolute path to the directory to search recursively.

Return type:

list[Path]

Returns:

A sorted list of absolute paths to session root directories found under root_path.

Raises:

OSError – If the root directory does not exist, is not a directory, or if the search encounters a directory it cannot read.

sollertia_shared_assets.data_hierarchy.filter_sessions(sessions, *, start_date=None, end_date=None, include_sessions=None, exclude_sessions=None, include_animals=None, exclude_animals=None, utc_timezone=True)

Filters (session_name, animal) pairs by date range and inclusion-exclusion criteria.

Animal filtering is applied before session filtering. Exclusion filtering takes precedence over inclusion filtering.

Parameters:

• sessions (Iterable[tuple[str, str]]) – An iterable of (session_name, animal) string tuples. The first element is the canonical session name (YYYY-MM-DD-HH-MM-SS-microseconds). The second is the animal identifier.

• start_date (str | None, default: None) – The start date for the date range filter. Sessions recorded on or after this date are included. Accepts formats like YYYY-MM-DD or YYYY-MM-DD HH:MM:SS. When None, no start bound is applied.

• end_date (str | None, default: None) – The end date for the date range filter. Sessions recorded on or before this date are included. Date-only values include the entire day. When None, no end bound is applied.

• include_sessions (set[str] | None, default: None) – Session names to include regardless of the date range. A session in this set is added even when it falls outside the start_date / end_date range. It is still dropped when it appears in exclude_sessions, when exclude_animals removes its animal, or when a non-empty include_animals omits its animal.

• exclude_sessions (set[str] | None, default: None) – Session names to exclude from the results. Takes precedence over every other inclusion criterion.

• include_animals (set[str] | None, default: None) – Animal identifiers to include. When provided and non-empty, only sessions from these animals are considered. When None or empty, sessions from all animals are considered.

• exclude_animals (set[str] | None, default: None) – Animal identifiers to exclude. Takes precedence over include_animals.

• utc_timezone (bool, default: True) – Determines whether to interpret date boundaries and session timestamps in UTC (True) or the host machine’s local time (False). Session names reflect UTC timestamps. When this flag is False, timestamps are converted to local time before comparison.

Return type:

set[tuple[str, str]]

Returns:

A set of (session_name, animal) tuples matching every filter.

Raises:

ValueError – If start_date or end_date cannot be parsed as a date or a datetime.

sollertia_shared_assets.data_hierarchy.get_projects_for_animal(root_path, animal_id)

Returns the names of all projects under the data root that include the given animal.

Project membership is derived from session markers, so a project is reported only when it holds at least one session for the animal.

Parameters:

• root_path (Path) – The absolute path to the data root to scan.

• animal_id (str) – The unique identifier of the animal whose projects are discovered.

Return type:

tuple[str, ...]

Returns:

A naturally-sorted tuple of project names that include the animal.

Raises:

• OSError – If the scan encounters a directory it cannot read.

• FileNotFoundError – If a discovered marker no longer resolves to exactly one session_data.yaml file.

• ValueError – If a discovered marker carries a session type or an acquisition system outside the platform vocabulary.

sollertia_shared_assets.data_hierarchy.get_session_root_from_marker(marker)

Returns the session root directory from a session_data.yaml marker path.

The marker lives at {session_root}/raw_data/session_data.yaml, so the session root is two directory levels above the marker file.

Parameters:

marker (Path) – The absolute path to a session_data.yaml file.

Return type:

Path

Returns:

The path to the session root directory (the grandparent of the marker).

sollertia_shared_assets.data_hierarchy.iter_animal_sessions(animal)

Discovers the session directories under an animal and yields their root paths.

Enumeration is directory-based: child directories whose names parse as session timestamps are yielded as session roots, so sessions are surfaced without reading any markers. Non-session children, such as the persistent-data directory and hidden directories, do not parse as session names and are therefore skipped.

Parameters:

animal (AnimalData) – The AnimalData view whose session directories are discovered.

Yields:

Each session root path under the animal, in sorted order.

sollertia_shared_assets.data_hierarchy.iter_project_animals(project)

Discovers the animal directories under a project and yields them as AnimalData views.

Enumeration is directory-based, so animals that hold no sessions yet are included. The project’s configuration directory, dataset directories, and hidden directories are skipped because they are not animals.

Parameters:

project (ProjectData) – The ProjectData view whose animal directories are discovered.

Yields:

Each AnimalData view for an animal directory under the project, in natural (human-friendly) sort order.

sollertia_shared_assets.data_hierarchy.iterate_sessions(root_path)

Discovers and lazily loads every SessionData instance under the target root directory.

Composes discover_sessions with SessionData.load. The returned iterator yields sessions in the same sorted order as discover_sessions.

Parameters:

root_path (Path) – The absolute path to the directory to search recursively for session markers.

Yields:

Each SessionData instance loaded from a session marker found under root_path.

Raises:

• OSError – If the search encounters a directory it cannot read.

• FileNotFoundError – If a discovered marker no longer resolves to exactly one session_data.yaml file.

• ValueError – If a discovered marker carries a session type or an acquisition system outside the platform vocabulary.

sollertia_shared_assets.data_hierarchy.parse_session_timestamp(session_name, *, utc_timezone=True)

Parses a Sollertia session name and returns its acquisition datetime.

Session names follow the format YYYY-MM-DD-HH-MM-SS-microseconds and encode the acquisition timestamp in UTC. Returns None rather than raising when the name does not follow this format, so callers can skip non-conforming directory names during discovery walks.

Parameters:

• session_name (str) – The unique identifier of the session.

• utc_timezone (bool, default: True) – Determines whether to return the datetime in UTC. When False, converts to the host machine’s local time.

Return type:

datetime | None

Returns:

A timezone-aware datetime representing when the session was acquired, or None when the session name does not follow the expected format.

sollertia_shared_assets.data_hierarchy.validate_directory(directory)

Checks that the given path string refers to an existing directory.

Parameters:

directory (str) – The absolute path string to validate as an existing directory.

Return type:

str | None

Returns:

None when the path points to an existing directory, otherwise a human-readable error message.

sollertia_shared_assets.data_hierarchy.session_data.RAW_DATA_DIRECTORY: str = 'raw_data'

Canonical name of the per-session raw data directory under each session root.

sollertia_shared_assets.data_hierarchy.session_data.PROCESSED_DATA_DIRECTORY: str = 'processed_data'

Canonical name of the per-session processed data directory under each session root.

sollertia_shared_assets.data_hierarchy.project_hierarchy.PERSISTENT_DATA_DIRECTORY: str = 'persistent_data'

Subdirectory under each animal that holds data persisted across the animal’s sessions. This directory is typically only present on data acquisition systems.

sollertia_shared_assets.data_hierarchy.project_hierarchy.DATASET_MARKER_FILENAME: str = 'dataset.yaml'

Filename of the dataset marker. Datasets are created and owned by sollertia-forgery, but their directories live inside the project hierarchy as siblings of the animal directories. The canonical marker name is defined here so the shared hierarchy walkers can recognize, skip, or count dataset directories without depending on sollertia-forgery.

Mesoscope-VR Assets

Provides the data acquisition and processing assets specific to the Mesoscope-VR acquisition system.

class sollertia_shared_assets.mesoscope_vr.LickTrainingDescriptor(experimenter, animal_weight_g, minimum_reward_delay_s=6, maximum_reward_delay_s=18, maximum_water_volume_ml=1.0, maximum_training_time_min=20, maximum_unconsumed_rewards=1, water_reward_size_ul=5.0, reward_tone_duration_ms=300, dispensed_water_volume_ml=0.0, pause_dispensed_water_volume_ml=0.0, experimenter_given_water_volume_ml=0.0, incomplete=True, experimenter_notes='Replace this with your notes.')

Bases: YamlConfig

Stores the task and outcome information specific to lick training sessions that use the Mesoscope-VR system.

animal_weight_g: float

The weight of the animal, in grams, at the beginning of the session.

dispensed_water_volume_ml: float = 0.0

The total water volume, in milliliters, dispensed during runtime. This excludes the water volume dispensed during the paused (idle) state.

experimenter: str

The ID of the experimenter running the session.

experimenter_given_water_volume_ml: float = 0.0

The additional volume of water, in milliliters, administered by the experimenter to the animal after the session.

experimenter_notes: str = 'Replace this with your notes.'

The experimenter’s notes made during runtime.

incomplete: bool = True

Determines whether the session’s data is complete and eligible for unsupervised data processing.

maximum_reward_delay_s: int = 18

The maximum delay, in seconds, that can separate the delivery of two consecutive water rewards.

maximum_training_time_min: int = 20

The maximum time, in minutes, the system is allowed to run the training.

maximum_unconsumed_rewards: int = 1

The maximum number of consecutive rewards that can be delivered without the animal consuming them. If the animal receives this many rewards without licking (consuming) them, reward delivery is paused until the animal consumes the delivered rewards. Setting this field to zero removes the limit, allowing every delivered reward to remain unconsumed.

maximum_water_volume_ml: float = 1.0

The maximum volume of water the system is allowed to dispense during training.

minimum_reward_delay_s: int = 6

The minimum delay, in seconds, that can separate the delivery of two consecutive water rewards.

pause_dispensed_water_volume_ml: float = 0.0

The total water volume, in milliliters, dispensed during the paused (idle) state.

reward_tone_duration_ms: int = 300

The duration, in milliseconds, of the auditory tone played to the animal when it receives water rewards.

water_reward_size_ul: float = 5.0

The volume of water, in microliters, dispensed to the animal on each reward of the training’s pseudorandom reward-delay sequence.

class sollertia_shared_assets.mesoscope_vr.MesoscopeDirectories(*values)

Bases: StrEnum

Enumerates the canonical names of subdirectories under a session’s raw_data directory that are written exclusively by the Mesoscope-VR acquisition system.

MESOSCOPE_DATA = 'mesoscope_data'

Raw mesoscope data directory under raw_data. Stores LERC-compressed TIFF stacks and acquisition metadata written by sollertia-experiment’s preprocessing.

class sollertia_shared_assets.mesoscope_vr.MesoscopeExperimentConfiguration(trial_structures, experiment_states, unity_scene_name)

Bases: YamlConfig

Defines an experiment session that uses the Mesoscope-VR data acquisition system.

Implements the full experiment-configuration contract shared by every Sollertia acquisition system: the experiment_states state machine, the trial_structures table, the unity_scene_name of the linear infinite corridor task the experiment runs, and the from_task_template builder.

experiment_states: dict[str, ExperimentState]

The experiment state machine, keyed by state name. This contract field is required by every experiment configuration.

classmethod from_task_template(template, unity_scene_name, state_count=1, default_reward_size_ul=5.0, default_reward_tone_duration_ms=300, default_puff_duration_ms=100)

Builds a Mesoscope-VR experiment configuration from a Unity VR task template.

Maps each of the template’s trial structures to a runtime trial class by its trigger type, pairing TriggerType.INTERACTION with a MesoscopeWaterRewardTrial and TriggerType.OCCUPANCY_DISARM with a MesoscopeGasPuffTrial. Then seeds state_count sequentially numbered runtime states (‘state_1’, ‘state_2’, and so on) whose reinforcing or aversive guidance defaults follow the trial types present in the template.

Parameters:

• template (TaskTemplate) – The task template whose VR trial structures (cues, trial zones) seed the configuration.

• unity_scene_name (str) – The Unity scene name for the experiment. This should match the template YAML file name so SessionData.create() can locate the corresponding VR template during snapshot export. Matching is the caller’s responsibility and is not validated here.

• state_count (int, default: 1) – The number of default-valued runtime states to generate. Must be at least one, since an experiment with no runtime states cannot be executed.

• default_reward_size_ul (float, default: 5.0) – Water reward volume in microliters for interaction-type trials.

• default_reward_tone_duration_ms (int, default: 300) – Reward tone duration in milliseconds for interaction-type trials.

• default_puff_duration_ms (int, default: 100) – Gas puff duration in milliseconds for occupancy-disarm trials.

Return type:

MesoscopeExperimentConfiguration

Returns:

The experiment configuration populated with the template’s trial structures and the requested number of default-valued runtime states.

Raises:

ValueError – If state_count is less than one, or if any of the template’s trial structures uses a TriggerType that is not mapped to a Mesoscope-VR runtime trial class. Only TriggerType.INTERACTION and TriggerType.OCCUPANCY_DISARM are mapped to runtime trial classes.

classmethod restore_excluded_fields(data, file_path)

Returns the loaded mapping with a trial kind discriminator supplied for every trial that omits one.

Notes

An omitted field takes its class default, so a trial carrying no discriminator would resolve to the water reward class whatever fields it declares. Resolving the discriminator from those fields instead routes the trial to the class that accommodates them, which lets a configuration authored without the discriminator load as written.

Parameters:

• data (dict[Any, Any]) – The mapping loaded from the configuration file.

• file_path (Path) – The path the mapping was loaded from.

Return type:

dict[Any, Any]

Returns:

The loaded mapping whose every stored trial carries a trial kind discriminator.

Raises:

ValueError – If a stored trial declares an unrecognized discriminator, or declares fields that identify a different runtime trial class than its discriminator names, or that identify two classes at once.

trial_structures: dict[str, MesoscopeWaterRewardTrial | MesoscopeGasPuffTrial]

The trials the experiment runs, keyed by trial name. This contract field is required by every experiment configuration.

unity_scene_name: str

The Unity scene (VR task) the experiment runs in the linear infinite corridor, identifying the paired task template by filename stem. This contract field is required by every experiment configuration.

class sollertia_shared_assets.mesoscope_vr.MesoscopeExperimentDescriptor(experimenter, animal_weight_g, maximum_unconsumed_rewards=1, dispensed_water_volume_ml=0.0, pause_dispensed_water_volume_ml=0.0, experimenter_given_water_volume_ml=0.0, incomplete=True, experimenter_notes='Replace this with your notes.')

Bases: YamlConfig

Stores the task and outcome information specific to experiment sessions that use the Mesoscope-VR system.

animal_weight_g: float

The weight of the animal, in grams, at the beginning of the session.

dispensed_water_volume_ml: float = 0.0

The total water volume, in milliliters, dispensed during runtime. This excludes the water volume dispensed during the paused (idle) state.

experimenter: str

The ID of the experimenter running the session.

experimenter_given_water_volume_ml: float = 0.0

The additional volume of water, in milliliters, administered by the experimenter to the animal after the session.

experimenter_notes: str = 'Replace this with your notes.'

The experimenter’s notes made during runtime.

incomplete: bool = True

Determines whether the session’s data is complete and eligible for unsupervised data processing.

maximum_unconsumed_rewards: int = 1

The maximum number of consecutive rewards that can be delivered without the animal consuming them. If the animal receives this many rewards without licking (consuming) them, reward delivery is paused until the animal consumes the delivered rewards. Setting this field to zero removes the limit, allowing every delivered reward to remain unconsumed.

pause_dispensed_water_volume_ml: float = 0.0

The total water volume, in milliliters, dispensed during the paused (idle) state.

class sollertia_shared_assets.mesoscope_vr.MesoscopeGasPuffTrial(puff_duration_ms=100, trial_kind=TrialKind.PUFF)

Bases: object

Defines a Mesoscope-VR trial that delivers a gas puff (an aversive stimulus) when the animal fails the trial’s avoidance condition.

The animal avoids the puff by satisfying the task’s occupancy condition. Failing to do so delivers a puff of the configured duration. The task defines the behavioral condition.

puff_duration_ms: int

The duration, in milliseconds, for which to deliver the gas puff when the animal fails the trial.

trial_kind: TrialKind

The discriminator that identifies this trial as a gas puff trial when it is read back from a YAML file.

class sollertia_shared_assets.mesoscope_vr.MesoscopeHardwareState(cm_per_pulse=None, maximum_brake_strength=None, minimum_brake_strength=None, lick_threshold=None, valve_scale_coefficient=None, valve_nonlinearity_exponent=None, torque_per_adc_unit=None, screens_initially_on=None, recorded_mesoscope_ttl=None, delivered_gas_puffs=None, system_state_codes=None)

Bases: YamlConfig

Stores configuration parameters (states) of the Mesoscope-VR system hardware modules used during training or experiment runtimes.

Notes

All hardware parameters are stored using the appropriate datatypes and rounding methods that ensure their complete equivalence to the values used by the data acquisition system during runtime.

Any hardware-parameter field set to None indicates that the corresponding hardware module was not used by the executed data acquisition runtime.

cm_per_pulse: float | None = None

The conversion factor used to translate encoder pulses into centimeters.

delivered_gas_puffs: bool | None = None

Determines whether the session delivered any gas puffs to the animal.

lick_threshold: int | None = None

Determines the threshold, in 12-bit Analog to Digital Converter (ADC) units reported by the lick sensor, for considering the reported signal a lick.

maximum_brake_strength: float | None = None

The braking torque, in Newton centimeters, applied by the brake to the edge of the running wheel when it is maximally engaged.

minimum_brake_strength: float | None = None

The braking torque, in Newton centimeters, applied by the brake to the edge of the running wheel when it is completely disengaged.

recorded_mesoscope_ttl: bool | None = None

Determines whether the session recorded brain activity data with the mesoscope.

screens_initially_on: bool | None = None

Determines whether the Virtual Reality screens were turned on at the beginning of the session’s runtime.

system_state_codes: dict[str, int] | None = None

The mapping from the human-readable state names of the Mesoscope-VR system to the integer state-codes the system uses to communicate those states (system states). Consumers that need a code-keyed lookup invert this mapping.

torque_per_adc_unit: float | None = None

The conversion factor used to translate torque values reported by the sensor as 12-bit Analog to Digital Converter (ADC) units into Newton centimeters (N·cm).

valve_nonlinearity_exponent: float | None = None

The nonlinearity exponent of the power law equation that describes the relationship between the time the valve is kept open and the dispensed water volume.

valve_scale_coefficient: float | None = None

The scale coefficient of the power law equation that describes the relationship between the time the valve is kept open and the dispensed water volume.

class sollertia_shared_assets.mesoscope_vr.MesoscopeRawData(zaber_positions_path, mesoscope_positions_path, window_screenshot_path, mesoscope_data_path)

Bases: object

Stores the absolute paths to the Mesoscope-VR-specific raw assets of a single data acquisition session.

Notes

The build classmethod is the single source of truth for the enum-to-field mapping.

classmethod build(root)

Builds a MesoscopeRawData instance with every field resolved against the input raw data root.

Parameters:

root (Path) – The path to the session’s raw_data directory.

Return type:

MesoscopeRawData

Returns:

A MesoscopeRawData instance whose fields are absolute paths under the input root.

mesoscope_data_path: Path

The compressed 2-Photon Random Access Mesoscope (2P-RAM) acquisition output and accompanying metadata produced by sollertia-experiment’s preprocessing.

mesoscope_positions_path: Path

The 2-Photon Random Access Mesoscope (2P-RAM) objective position used to image the cranial window during the session, which allows the same imaging field of view to be recovered in follow-up sessions.

window_screenshot_path: Path

A visual reference of the cranial imaging window taken at the start of the session.

zaber_positions_path: Path

The states of the Zaber motorized stages used by the Mesoscope-VR system, recorded at the end of the session before the motors are reset.

class sollertia_shared_assets.mesoscope_vr.MesoscopeRawDataFiles(*values)

Bases: StrEnum

Enumerates the canonical filenames at the root of a session’s raw_data directory that are written exclusively by the Mesoscope-VR acquisition system.

MESOSCOPE_POSITIONS = 'mesoscope_positions.yaml'

The Mesoscope objective position snapshot seeded with a precursor at session start and rewritten with the queried objective positions at session end by the Mesoscope-VR acquisition runtime. Written for experiment and window-checking sessions only.

WINDOW_SCREENSHOT = 'window_screenshot.png'

The cranial imaging window screenshot captured at session start by the Mesoscope-VR acquisition runtime.

ZABER_POSITIONS = 'zaber_positions.yaml'

The Zaber motor position snapshot written at session end by the Mesoscope-VR acquisition runtime, before the motors are returned to their parking position.

class sollertia_shared_assets.mesoscope_vr.MesoscopeWaterRewardTrial(reward_size_ul=5.0, reward_tone_duration_ms=300, trial_kind=TrialKind.WATER)

Bases: object

Defines a Mesoscope-VR trial that delivers a water reward (a reinforcing stimulus) when the animal meets the trial’s success condition.

The reward is a configured volume of water accompanied by an auditory tone. The task defines the behavioral condition that earns the reward.

reward_size_ul: float

The volume of water, in microliters, to deliver when the animal successfully completes the trial.

reward_tone_duration_ms: int

The duration, in milliseconds, to sound the auditory tone when delivering the water reward.

trial_kind: TrialKind

The discriminator that identifies this trial as a water reward trial when it is read back from a YAML file.

class sollertia_shared_assets.mesoscope_vr.RunTrainingDescriptor(experimenter, animal_weight_g, final_run_speed_threshold_cm_s=1.5, final_run_duration_threshold_s=1.5, initial_run_speed_threshold_cm_s=0.8, initial_run_duration_threshold_s=1.5, increase_threshold_ml=0.1, run_speed_increase_step_cm_s=0.05, run_duration_increase_step_s=0.1, maximum_water_volume_ml=1.0, maximum_training_time_min=40, maximum_unconsumed_rewards=1, maximum_idle_time_s=0.3, water_reward_size_ul=5.0, reward_tone_duration_ms=300, dispensed_water_volume_ml=0.0, pause_dispensed_water_volume_ml=0.0, experimenter_given_water_volume_ml=0.0, incomplete=True, experimenter_notes='Replace this with your notes.')

Bases: YamlConfig

Stores the task and outcome information specific to run training sessions that use the Mesoscope-VR system.

animal_weight_g: float

The weight of the animal, in grams, at the beginning of the session.

dispensed_water_volume_ml: float = 0.0

The total water volume, in milliliters, dispensed during runtime. This excludes the water volume dispensed during the paused (idle) state.

experimenter: str

The ID of the experimenter running the session.

experimenter_given_water_volume_ml: float = 0.0

The additional volume of water, in milliliters, administered by the experimenter to the animal after the session.

experimenter_notes: str = 'Replace this with your notes.'

The experimenter’s notes made during runtime.

final_run_duration_threshold_s: float = 1.5

The running duration threshold, in seconds, at the end of training.

final_run_speed_threshold_cm_s: float = 1.5

The running speed threshold, in centimeters per second, at the end of training.

incomplete: bool = True

Determines whether the session’s data is complete and eligible for unsupervised data processing.

increase_threshold_ml: float = 0.1

The threshold volume of water delivered to the animal, in milliliters, that triggers the increase in the running speed and duration thresholds.

initial_run_duration_threshold_s: float = 1.5

The initial running duration threshold, in seconds.

initial_run_speed_threshold_cm_s: float = 0.8

The initial running speed threshold, in centimeters per second.

maximum_idle_time_s: float = 0.3

The maximum time, in seconds, the animal can dip below the running speed threshold to still receive the reward. This allows animals that ‘run’ by taking a series of large steps, briefly dipping below speed threshold at the end of each step, to still get water rewards.

maximum_training_time_min: int = 40

The maximum time, in minutes, the system is allowed to run the training.

maximum_unconsumed_rewards: int = 1

The maximum number of consecutive rewards that can be delivered without the animal consuming them. If the animal receives this many rewards without licking (consuming) them, reward delivery is paused until the animal consumes the delivered rewards. Setting this field to zero removes the limit, allowing every delivered reward to remain unconsumed.

maximum_water_volume_ml: float = 1.0

The maximum volume of water the system is allowed to dispense during training.

pause_dispensed_water_volume_ml: float = 0.0

The total water volume, in milliliters, dispensed during the paused (idle) state.

reward_tone_duration_ms: int = 300

The duration, in milliseconds, of the auditory tone played to the animal when it receives water rewards.

run_duration_increase_step_s: float = 0.1

The value, in seconds, used by the system to increment the duration threshold each time the animal receives ‘increase_threshold_ml’ volume of water.

run_speed_increase_step_cm_s: float = 0.05

The value, in centimeters per second, used by the system to increment the running speed threshold each time the animal receives ‘increase_threshold_ml’ volume of water.

water_reward_size_ul: float = 5.0

The volume of water, in microliters, dispensed to the animal when it achieves the required running speed and duration thresholds.

class sollertia_shared_assets.mesoscope_vr.TrialKind(*values)

Bases: StrEnum

Defines the discriminators that identify which Mesoscope-VR runtime trial class a stored trial belongs to.

Notes

Each trial class declares this discriminator with its own member as the default and rejects every other member at initialization. Deserialization tries the members of the trial union in order and skips an arm whose initialization raises, so the enforced discriminator is what routes a stored trial back to the class that wrote it.

PUFF = 'puff'

A trial that delivers a gas puff, which is a MesoscopeGasPuffTrial.

WATER = 'water'

A trial that delivers a water reward, which is a MesoscopeWaterRewardTrial.

class sollertia_shared_assets.mesoscope_vr.WindowCheckingDescriptor(experimenter, surgery_quality=0, incomplete=True, experimenter_notes='Replace this with your notes.')

Bases: YamlConfig

Stores the outcome information specific to window checking sessions that use the Mesoscope-VR system.

experimenter: str

The ID of the experimenter running the session.

experimenter_notes: str = 'Replace this with your notes.'

The experimenter’s notes made during runtime.

incomplete: bool = True

Determines whether the session’s data is complete and eligible for unsupervised data processing.

surgery_quality: int = 0

The quality of the cranial window and surgical intervention on a scale from 0 (non-usable) to 3 (high-tier publication grade) inclusive.

Dispatch Registries

Collects every sollertia-shared-assets dispatch registry in one place and runs the import-time checks that guard them. The module imports each acquisition system’s subpackage and wires that system’s classes into the registries, so the shared configuration and data modules never import from a system subpackage.

sollertia_shared_assets.registries.CREDENTIALS_FILE_REGISTRY: dict[CredentialsTypes, str] = {CredentialsTypes.GOOGLE: 'google_credentials.json'}

Maps each credentials category to the canonical filename under which its credentials file is stored inside the working directory’s credentials subdirectory. This contract registry is curated by Sollertia platform maintainers.

sollertia_shared_assets.registries.DESCRIPTOR_REGISTRY: dict[SessionTypes, type[YamlConfig]] = {SessionTypes.LICK_TRAINING: <class 'sollertia_shared_assets.mesoscope_vr.runtime_data.LickTrainingDescriptor'>, SessionTypes.MESOSCOPE_EXPERIMENT: <class 'sollertia_shared_assets.mesoscope_vr.runtime_data.MesoscopeExperimentDescriptor'>, SessionTypes.RUN_TRAINING: <class 'sollertia_shared_assets.mesoscope_vr.runtime_data.RunTrainingDescriptor'>, SessionTypes.WINDOW_CHECKING: <class 'sollertia_shared_assets.mesoscope_vr.runtime_data.WindowCheckingDescriptor'>}

Maps each session type to its descriptor dataclass. The canonical on-disk filename is always the flat session_descriptor.yaml (RawDataFiles.SESSION_DESCRIPTOR) regardless of session type, and the parsing class is the only thing that varies per type. The registry is deliberately flat: a session type maps to exactly one descriptor platform-wide, so an acquisition system that needs a different descriptor must mint a new SessionTypes member.

sollertia_shared_assets.registries.EXPERIMENT_CONFIGURATION_REGISTRY: dict[AcquisitionSystems, type[YamlConfig]] = {AcquisitionSystems.MESOSCOPE_VR: <class 'sollertia_shared_assets.mesoscope_vr.experiment_configuration.MesoscopeExperimentConfiguration'>}

Maps each acquisition system to its experiment configuration dataclass. Every registered class satisfies the experiment-configuration contract.

sollertia_shared_assets.registries.HARDWARE_STATE_REGISTRY: dict[AcquisitionSystems, type[YamlConfig]] = {AcquisitionSystems.MESOSCOPE_VR: <class 'sollertia_shared_assets.mesoscope_vr.runtime_data.MesoscopeHardwareState'>}

Maps each acquisition system to its hardware-state dataclass. The canonical on-disk filename is always hardware_state.yaml (RawDataFiles.HARDWARE_STATE) regardless of system, and only the parsing class varies.

sollertia_shared_assets.registries.READ_ASSET_REGISTRY: dict[ReadAssets, type[YamlConfig]] = {ReadAssets.SURGERY_DATA: <class 'sollertia_shared_assets.data_classes.surgery_data.SurgeryData'>}

Maps each read-asset format to the dataclass that represents it on disk. This contract registry is curated by Sollertia platform maintainers. Each entry is a durable contract for translating an external data shape into the uniform on-disk format the downstream Sollertia libraries consume.

sollertia_shared_assets.registries.SESSION_TYPES_USING_VR_TASK: frozenset[SessionTypes] = frozenset({SessionTypes.MESOSCOPE_EXPERIMENT})

Collects the session types that use VR and therefore write a vr_configuration.yaml task-template snapshot.

sollertia_shared_assets.registries.SYSTEM_RAW_DATA_REGISTRY: dict[AcquisitionSystems, type[_SystemRawDataBuilder]] = {AcquisitionSystems.MESOSCOPE_VR: <class 'sollertia_shared_assets.mesoscope_vr.raw_data.MesoscopeRawData'>}

Maps each acquisition system to the dataclass that captures its system-specific raw assets. The registered class exposes a build(root: Path) -> Self classmethod that resolves all system-specific paths under the session’s raw_data directory.

sollertia_shared_assets.registries.SYSTEM_SESSION_TYPES: dict[AcquisitionSystems, frozenset[SessionTypes]] = {AcquisitionSystems.MESOSCOPE_VR: frozenset({SessionTypes.LICK_TRAINING, SessionTypes.MESOSCOPE_EXPERIMENT, SessionTypes.RUN_TRAINING, SessionTypes.WINDOW_CHECKING})}

Maps each acquisition system to the set of session types it can run.

sollertia_shared_assets.registries.resolve_read_asset(read_asset)

Resolves a read-asset format identifier to the dataclass that represents it on disk.

Parameters:

read_asset (str | ReadAssets) – A ReadAssets member or its string value (e.g., "surgery_data").

Return type:

type[YamlConfig]

Returns:

The dataclass registered for the format in READ_ASSET_REGISTRY.

Raises:

ValueError – If the identifier is not a valid ReadAssets member.

Credentials Toolset

Provides the credentials toolset that copies per-category credentials files into the working directory’s credentials subdirectory and resolves them back for downstream consumers. The toolset lives in its own top-level module because its functions consume CREDENTIALS_FILE_REGISTRY at runtime, which places them downstream of the registries module.

sollertia_shared_assets.credentials.get_credentials(credentials)

Resolves and returns the path to the requested credentials file stored in the working directory’s credentials subdirectory.

Parameters:

credentials (str | CredentialsTypes) – The CredentialsTypes member or its string value identifying the credentials category to resolve.

Return type:

Path

Returns:

The path to the requested credentials file.

Raises:

• ValueError – If the credentials category is not a valid CredentialsTypes member.

• FileNotFoundError – If the local working directory has not been configured for the host machine, or if the credentials file for the requested category has not been set.

sollertia_shared_assets.credentials.resolve_credentials_file(credentials)

Resolves a credentials category identifier to the canonical filename of its credentials file.

Parameters:

credentials (str | CredentialsTypes) – A CredentialsTypes member or its string value (e.g., "google").

Return type:

str

Returns:

The canonical filename registered for the category in CREDENTIALS_FILE_REGISTRY.

Raises:

ValueError – If the identifier is not a valid CredentialsTypes member.

sollertia_shared_assets.credentials.set_credentials(credentials, path)

Copies the specified credentials file into the working directory’s credentials subdirectory.

The copy is stored under the canonical filename registered for the credentials category, atomically replacing any previously configured credentials file for that category. The published file carries umask-derived permissions.

Parameters:

• credentials (str | CredentialsTypes) – The CredentialsTypes member or its string value identifying the credentials category to configure.

• path (Path) – The path to the credentials file to copy into the credentials subdirectory.

Raises:

• ValueError – If the credentials category is not a valid CredentialsTypes member, or if the specified file’s extension does not match the canonical credentials filename’s extension.

• FileNotFoundError – If the specified credentials file does not exist at the provided path, or if the local working directory has not been configured for the host machine.

Return type:

None

Command-Line Interface

slsa

Provides the entry point for all interactive sollertia-shared-assets library components.

Usage

slsa [OPTIONS] COMMAND [ARGS]...

configure

Configures major components of the Sollertia platform data workflow.

Usage

slsa configure [OPTIONS] COMMAND [ARGS]...

credentials

Copies the input credentials file into the platform credentials directory under its canonical name.

Usage

slsa configure credentials [OPTIONS]

Options

-c, --category <category>

Required The category of the credentials file to configure.

Options:

google

-f, --file <file>

Required The absolute path to the credentials file to copy into the platform credentials directory.

data-root

Sets the input directory as the local Sollertia platform data root.

Usage

slsa configure data-root [OPTIONS]

Options

-d, --directory <directory>

Required The absolute path to the directory under which all project directories are stored on this machine.

directory

Sets the input directory as the local Sollertia platform working directory.

Usage

slsa configure directory [OPTIONS]

Options

-d, --directory <directory>

Required The absolute path to the directory in which to cache Sollertia platform configuration and runtime data.

project

Creates the data structure for a new project under the configured Sollertia platform data root.

Usage

slsa configure project [OPTIONS]

Options

-p, --project <project>

Required The name of the project to be created.

templates

Sets the path to the sollertia-virtual-reality task templates directory.

Usage

slsa configure templates [OPTIONS]

Options

-d, --directory <directory>

Required The absolute path to the sollertia-virtual-reality project’s Assets/InfiniteCorridorTask/Configurations directory.

delete

Removes Sollertia platform configuration assets from the local data hierarchy.

Usage

slsa delete [OPTIONS] COMMAND [ARGS]...

experiment

Removes the target experiment configuration from the project’s configuration directory.

Both names are joined onto the configured data root as path components, so each is required to be a single component, which confines the removal to the project’s own configuration directory.

Usage

slsa delete experiment [OPTIONS]

Options

-p, --project <project>

Required The name of the project that stores the experiment configuration to remove.

-e, --experiment <experiment>

Required The name of the experiment configuration to remove.

project

Removes the target project directory and all of its contents from the Sollertia platform data root.

The removal is irreversible and takes every animal, session, and experiment configuration stored under the project with it, so the command blocks on an interactive confirmation prompt before it deletes anything. The project name is joined onto the configured data root as a path component, so it is required to be a single component, which keeps the removal on a project directory rather than an animal or session subtree nested inside one.

Usage

slsa delete project [OPTIONS]

Options

-p, --project <project>

Required The name of the project to remove.

template

Removes the target sollertia-virtual-reality task template file from the local filesystem.

The removal is confined to a task template file stored under the configured task templates directory, which keeps the per-session frozen vr_configuration.yaml snapshot, an immutable acquisition record, out of reach.

Usage

slsa delete template [OPTIONS]

Options

-f, --file <file>

Required The absolute path to the sollertia-virtual-reality task template file to remove. The file must be stored under the configured task templates directory.

get

Reports the configured paths and the composition of the local Sollertia platform data hierarchy.

Usage

slsa get [OPTIONS] COMMAND [ARGS]...

credentials

Reports the path to the requested credentials file stored in the platform credentials directory.

Usage

slsa get credentials [OPTIONS]

Options

-c, --category <category>

Required The category of the credentials file to report.

Options:

google

data-root

Reports the configured local Sollertia platform data root.

Usage

slsa get data-root [OPTIONS]

directory

Reports the configured local Sollertia platform working directory.

Usage

slsa get directory [OPTIONS]

experiments

Lists the experiment configurations available for the target project.

Usage

slsa get experiments [OPTIONS]

Options

-p, --project <project>

Required The name of the project for which to list the available experiment configurations.

projects

Lists the projects stored under the local Sollertia platform data root.

Usage

slsa get projects [OPTIONS]

templates

Reports the configured sollertia-virtual-reality task templates directory.

Usage

slsa get templates [OPTIONS]

mcp

Starts the MCP server for agentic management of configuration, session, dataset, and Unity assets.

Usage

slsa mcp [OPTIONS]

Options

-t, --transport <transport>

The MCP transport type to use.

Default:

'stdio'

Options:

stdio | streamable-http