PULSE-code / pulse /paths.py
velvet-pine-22's picture
PULSE-code: benchmark code for the PULSE dataset (camera-ready release)
dffbc1f verified
Raw History Blame Contribute Delete
6.14 kB
"""Path layer for the public PULSE layout (Hugging Face velvet-pine-22/PULSE).
Layout of a dataset root (``--root`` or ``$PULSE_ROOT``)::
<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