"""Path layer for the public PULSE layout (Hugging Face velvet-pine-22/PULSE). Layout of a dataset root (``--root`` or ``$PULSE_ROOT``):: / data/vX/sY/aligned_{emg,imu,eyetrack,pressure,mocap,myo_quat,myo_pose}_100hz.csv data/vX/sY/alignment_metadata.json data/vX/sY/raw/aligned_vXsY_s_Q.tsv # skeleton MoCap, 237 recordings data/vX/sY/aligned_vXsY_s_Q.tsv # ... or here, 10 recordings annotations/vX/sY.json # v1.1 human-reviewed labels, S1-S8 metadata/recordings.csv The skeleton TSV sits in ``raw/`` for most recordings and at the recording root for v1s5, v2s2, v2s6, v3s1, v3s2, v3s5, v3s6, v11s8, v13s2 and v13s3. Both locations are supported; finding the file in both places is an error. Nothing here falls back to a default absolute path: the root must be given. """ from __future__ import annotations import os import re from dataclasses import dataclass from pathlib import Path from typing import Optional, Tuple, Union from .errors import AmbiguousFileError, DataRootError, MissingFileError ENV_ROOT = "PULSE_ROOT" #: Optional override for the S9 motion-primitive labels used by F5. The #: directory must contain ``vX/s9.json`` files. ENV_S9_ANNOTATIONS = "PULSE_S9_ANNOTATIONS" _RID_RE = re.compile(r"^(v\d+)(s\d+)$") #: Recordings whose skeleton TSV sits at the recording root instead of raw/ in #: v1.1 (documented, used by tests and the availability report). TSV_AT_RECORDING_ROOT = ( "v1s5", "v2s2", "v2s6", "v3s1", "v3s2", "v3s5", "v3s6", "v11s8", "v13s2", "v13s3", ) PathLike = Union[str, os.PathLike] def split_rid(rid: str) -> Tuple[str, str]: """``'v12s3' -> ('v12', 's3')``.""" m = _RID_RE.match(rid) if not m: raise ValueError(f"not a recording id: {rid!r} (expected e.g. 'v12s3')") return m.group(1), m.group(2) def make_rid(vol: str, scenario: str) -> str: rid = f"{vol}{scenario}" split_rid(rid) return rid def vol_number(vol: str) -> int: if not re.match(r"^v\d+$", vol): raise ValueError(f"not a volunteer id: {vol!r}") return int(vol[1:]) def resolve_root(root: Optional[PathLike] = None) -> Path: """Return the dataset root from ``root`` or ``$PULSE_ROOT`` (expanded).""" if root is None or str(root) == "": root = os.environ.get(ENV_ROOT) if not root: raise DataRootError( f"no dataset root given: pass --root or set ${ENV_ROOT} to the " "directory that contains data/, annotations/ and metadata/") p = Path(os.path.expandvars(os.path.expanduser(str(root)))) if "$" in str(p): raise DataRootError(f"unexpanded variable in dataset root: {p}") if not p.is_dir(): raise DataRootError(f"dataset root does not exist: {p}") for sub in ("data", "metadata"): if not (p / sub).is_dir(): raise DataRootError(f"{p} is not a PULSE dataset root (no {sub}/ directory)") return p.resolve() @dataclass(frozen=True) class DataRoot: """Resolved locations inside one dataset root.""" root: Path s9_annotations_dir: Optional[Path] = None @classmethod def from_arg(cls, root: Optional[PathLike] = None, s9_annotations: Optional[PathLike] = None) -> "DataRoot": r = resolve_root(root) s9 = s9_annotations or os.environ.get(ENV_S9_ANNOTATIONS) or None s9p = Path(os.path.expanduser(str(s9))).resolve() if s9 else None return cls(root=r, s9_annotations_dir=s9p) # -- directories ----------------------------------------------------- @property def data_dir(self) -> Path: return self.root / "data" @property def annotations_dir(self) -> Path: return self.root / "annotations" @property def metadata_dir(self) -> Path: return self.root / "metadata" @property def recordings_csv(self) -> Path: return self.metadata_dir / "recordings.csv" def recording_dir(self, rid: str) -> Path: vol, scen = split_rid(rid) return self.data_dir / vol / scen # -- files ------------------------------------------------------------- def stream_path(self, rid: str, filename: str, must_exist: bool = True) -> Path: p = self.recording_dir(rid) / filename if must_exist and not p.is_file(): raise MissingFileError(f"{rid}: missing {filename} ({p})") return p def mocap_tsv_candidates(self, rid: str) -> Tuple[Path, Path]: d = self.recording_dir(rid) name = f"aligned_{rid}_s_Q.tsv" return d / "raw" / name, d / name def mocap_tsv_path(self, rid: str, must_exist: bool = True) -> Optional[Path]: """Skeleton TSV of ``rid`` in raw/ or at the recording root.""" cands = [p for p in self.mocap_tsv_candidates(rid) if p.is_file()] if len(cands) > 1: raise AmbiguousFileError( f"{rid}: skeleton TSV found in two places: {cands[0]} and {cands[1]}") if not cands: if must_exist: raise MissingFileError( f"{rid}: skeleton TSV aligned_{rid}_s_Q.tsv not found in raw/ " f"or at the recording root ({self.recording_dir(rid)})") return None return cands[0] def alignment_metadata_path(self, rid: str) -> Path: return self.stream_path(rid, "alignment_metadata.json") def annotation_path(self, rid: str, must_exist: bool = True) -> Optional[Path]: """Dense S1-S8 labels (``annotations/vX/sY.json``). S9 labels are looked up in ``s9_annotations_dir`` when it is set (``--s9-annotations`` / ``$PULSE_S9_ANNOTATIONS``), else in ``annotations/``. """ vol, scen = split_rid(rid) base = self.annotations_dir if scen == "s9" and self.s9_annotations_dir is not None: base = self.s9_annotations_dir p = base / vol / f"{scen}.json" if not p.is_file(): if must_exist: raise MissingFileError(f"{rid}: missing annotation file {p}") return None return p