API Reference

Session readers

Batch loading

murineshiftwork.readers.batch.load_session(session_dir, *, acquisition_name=None, acquisition_dir=None)

Read one session directory and return a structured MswSession.

Parameters:

Name	Type	Description	Default
session_dir		Path to the session directory (the innermost directory containing MSW artifact files).	required
acquisition_name	str | None	Optional name of the parent acquisition container. Set automatically by load_acquisition.	None
acquisition_dir	Path | None	Optional path to the parent acquisition container. Set automatically by load_acquisition.	None

Returns:

Type	Description
MswSession	Populated MswSession with all available artifacts loaded.

Raises:

Type	Description
ValueError	If no recognised MSW files are found in session_dir.

murineshiftwork.readers.batch.load_acquisition(acquisition_dir)

Load all sessions inside a single acquisition container directory.

Reads acquisition_manifest.yaml if present; otherwise discovers session directories by name pattern (__ separator). Sessions are returned sorted by datetime_str.

Parameters:

Name	Type	Description	Default
acquisition_dir		Path to the acquisition container (a directory whose children are individual session directories).	required

Returns:

Type	Description
list[MswSession]	List of MswSession objects, sorted chronologically. Directories
list[MswSession]	that cannot be parsed are logged and skipped.

murineshiftwork.readers.batch.load_subject(subject_dir)

Load all sessions under a subject directory.

Walks one level of subdirectories. Direct session directories (containing MSW artifact files) are loaded with load_session; subdirectories that look like acquisition containers are loaded with load_acquisition. Sessions are returned sorted by datetime_str.

Parameters:

Name	Type	Description	Default
subject_dir		Path to the subject root directory.	required

Returns:

Type	Description
list[MswSession]	List of MswSession objects across all acquisitions, sorted
list[MswSession]	chronologically. Unreadable directories are logged and skipped.

Session model

murineshiftwork.readers.models.MswSession

Bases: BaseModel

All data and metadata for one MSW session directory.

Attributes:

Name	Type	Description
session_dir	Path	Absolute path to the session directory.
basename	str	Session basename (subject__datetime__task).
subject	str	Animal identifier extracted from the basename.
datetime_str	str	Raw datetime string extracted from the basename.
task	str	Task name extracted from the basename.
namespace_version	str | None	Namespace version string ("v1" or "legacy"), or None if the directory name is not a canonical basename.
artifact_format	str	One of "session_yaml", "separate_json", or "legacy".
msw_version	str	MSW software version recorded in settings.process, or "legacy" / "< 1.0.0" for older sessions.
df	DataFrame | None	Trial-by-trial DataFrame, or None if no trial data file was found.
settings_task	dict[str, Any] | None	Task settings dict (settings.task artifact).
settings_process	dict[str, Any] | None	Process settings dict (settings.process artifact).
settings_stage	dict[str, Any] | None	Stage / reward settings dict, if present.
settings_ephys	dict[str, Any] | None	Host-session / ephys linking block, if present.
subprotocols	list[dict] | None	List of subprotocol dicts from session_manifest.yaml, populated for multi-protocol sessions.
is_complete	bool	True when the required artifacts (df, settings.task, settings.process) are all present and non-null.
is_ephys	bool	True when an ephys/host-session block is present.
session_type	str	Task-type label from the session container name (session_type field in task.yaml); empty string for sessions that predate v4.1 naming.
acquisition_name	str | None	Name of the parent acquisition container, set by load_acquisition; None for standalone sessions.
acquisition_dir	Path | None	Path to the parent acquisition container, set by load_acquisition; None for standalone sessions.

acq_type = '' class-attribute instance-attribute

acquisition_dir = None class-attribute instance-attribute

acquisition_name = None class-attribute instance-attribute

artifact_format instance-attribute

basename instance-attribute

datetime_str instance-attribute

df = None class-attribute instance-attribute

host_session_name property

Name of the host/ephys session container, or None if standalone.

is_complete instance-attribute

is_ephys instance-attribute

metadata = None class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True) class-attribute instance-attribute

msw_version instance-attribute

namespace_version instance-attribute

session_dir instance-attribute

session_type = '' class-attribute instance-attribute

settings_ephys = None class-attribute instance-attribute

settings_process = None class-attribute instance-attribute

settings_stage = None class-attribute instance-attribute

settings_task = None class-attribute instance-attribute

subject instance-attribute

subprotocols = None class-attribute instance-attribute

task instance-attribute

to_dict()

Validation

murineshiftwork.readers.validate.ValidationResult dataclass

info = field(default_factory=list) class-attribute instance-attribute

issues = field(default_factory=list) class-attribute instance-attribute

msw_version = 'unknown' class-attribute instance-attribute

passed = True class-attribute instance-attribute

session_dir instance-attribute

warnings = field(default_factory=list) class-attribute instance-attribute

__init__(session_dir, msw_version='unknown', passed=True, issues=list(), warnings=list(), info=list())

_fail(msg)

_info(msg)

_warn(msg)

print_summary()

murineshiftwork.readers.validate.validate_session(session_dir, verbose=True)

Validate MSW file completeness for a session directory.

Low-level reader

murineshiftwork.readers.session.read_session_data(session_dir=None)

Read raw session data from a directory, dispatching on artifact format.

Parameters:

Name	Type	Description	Default
session_dir		Path to the session directory.	None

Returns:

Type	Description
	Dict with keys: df, settings.task, settings.process,
	settings.stage, settings.ephys, msw_version,
	namespace_version, artifact_format, is_legacy_session,
	is_complete_session, is_ephys_session.

Raises:

Type	Description
ValueError	If no registered reader handles the detected artifact format.
AssertionError	If session_dir does not exist.

---

Namespace utilities

murineshiftwork.namespace.paths.generate_session_paths(subject, task, basepath, acq_type='msw', acq_version=1, session_type=None, version=CURRENT_NAMESPACE_VERSION, default_subject='_test_subject', linked_to=None, datetime_str=None, printout=True)

Generate a validated session path dictionary (v4 namespace).

Builds the session container (subject__datetime[__session_type]) and acquisition basename (subject__datetime__acq_type[__vN]), then derives all associated paths under basepath.

Tasks whose name starts with _test__ are redirected to default_subject so test runs do not pollute real subject directories.

Parameters:

Name	Type	Description	Default
subject	str	Animal/subject identifier. Must not contain __.	required
task	str	Task name. Used for the task key in returned dict only; not part of the v4 path structure.	required
basepath	str | Path	Root data directory.	required
acq_type	str	Acquisition type identifier ("msw", "pxi", "photo", "video_rce", "video_flir"). Default "msw".	'msw'
acq_version	int | None	Integer format version appended as __vN on the acquisition basename. Defaults to 1 so MSW writes always carry a version. Pass None to omit the version component for external, unversioned acquisition types (e.g. pxi). Version is at the acquisition level, not the session container.	1
session_type	str | None	Optional task-type label appended to the session container: subject__datetime__session_type.	None
version	str	Datetime precision format -- "v1" (default) or "legacy".	CURRENT_NAMESPACE_VERSION
default_subject	str	Subject name used when task starts with _test__.	'_test_subject'
linked_to	str | None	Override the entire session container name verbatim.	None
datetime_str	str | None	Re-use an existing datetime string instead of generating a new one. Pass session_paths["datetime"] from the primary acquisition when creating a sibling (e.g. video_flir) so both basenames share the same timestamp.	None
printout	bool	Print generated paths to stdout.	True

Returns:

Type	Description
dict	Dict with keys: subject, datetime, task, acq_type,
dict	acq_version, basepath, namespace_version (datetime
dict	precision), namespace_spec_version (spec semver, e.g. "4.2"),
dict	host_session_name, acquisition_name, session_basename,
dict	session_folder, session_folder_relative, session_file_path.

murineshiftwork.namespace.paths.parse_session_basename(basename)

Parse a session/acquisition basename into subject, datetime, task.

Compatibility shim over parse_acquisition_basename(). Returns the same keys as the original function: subject, datetime, datetime_str, task, namespace_version.

---

IO codec

murineshiftwork.io.save_trial_data(trial_data_list, filepath)

Save a list of trial dicts to a JSONL file.

Overwrites any existing file. The first line is a version header; subsequent lines are one JSON object per trial. Numpy arrays are converted to lists; tuples are encoded as {"__tuple__": [...]} so they survive the round-trip through load_trial_data.

Parameters:

Name	Type	Description	Default
trial_data_list	list	List of per-trial dicts as returned by the task.	required
filepath	str | Path	Destination path (parent directories are created if absent).	required

murineshiftwork.io.load_trial_data(filepath)

Load trial dicts from a JSONL file written by save_trial_data.

Skips the version header line and restores {"__tuple__": [...]} sentinels back to Python tuples.

Parameters:

Name	Type	Description	Default
filepath		Path to the .jsonl file.	required

Returns:

Type	Description
list	List of per-trial dicts with tuples restored.