pathfinder/example.py at master · OHBA-analysis/pathfinder · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
"""A runnable tour of the public API: ``python example.py``.

The example creates a temporary EEG-fMRI dataset, constructs one Pathfinder,
then follows the README API table: properties, conversions/lookups, and scan.
"""

from pathlib import Path
from tempfile import TemporaryDirectory

from osl_pathfinder import Pathfinder


def build_fake_dataset(root: Path) -> None:
    """A few subjects, each with EEG+fMRI blocks and one shared T1w."""
    entities = {
        (7, 1, 1, 1), (7, 1, 1, 2), (7, 2, 1, 1),   # sub-007
        (10, 1, 1, 1),                               # sub-010 (2-digit -> id 10111)
    }
    for sub, ses, run, block in entities:
        d = root / f"sub-{sub:03d}" / f"ses-{ses:02d}"
        (d / "eeg").mkdir(parents=True, exist_ok=True)
        eeg = (f"sub-{sub:03d}_ses-{ses:02d}_run-{run:02d}_block-{block:02d}_eeg.fif")
        (d / "eeg" / eeg).write_text("")
        # fMRI: scan==run, part==block — just different literal text
        func = root / "func" / f"sub-{sub:03d}_ses-{ses:02d}_scan-{run:02d}_part-{block:02d}"
        func.mkdir(parents=True, exist_ok=True)
        (func / "bold.nii.gz").write_text("")
        # a derivative whose filename carries a varying hash we don't track
        prep = root / "derivatives" / f"sub-{sub:03d}"
        prep.mkdir(parents=True, exist_ok=True)
        (prep / f"ses-{ses:02d}_run-{run:02d}_block-{block:02d}_{sub}{ses}{run}{block}beef_preproc.fif").write_text("")
    for sub in {e[0] for e in entities}:
        anat = root / f"sub-{sub:03d}" / "anat"
        anat.mkdir(parents=True, exist_ok=True)
        (anat / f"sub-{sub:03d}_T1w.nii.gz").write_text("")


def main() -> None:
    with TemporaryDirectory() as tmp:
        root = Path(tmp)
        build_fake_dataset(root)

        # 1. Construct: define one path template per file kind.
        pf = Pathfinder(
            templates={
                "eeg": (
                    str(root)
                    + "/sub-{subject:03d}/ses-{session:02d}/eeg/"
                    + "sub-{subject:03d}_ses-{session:02d}_run-{run:02d}_"
                    + "block-{block:02d}_eeg.fif"
                ),
                "fmri": (
                    str(root)
                    + "/func/sub-{subject:03d}_ses-{session:02d}_"
                    + "scan-{run:02d}_part-{block:02d}/bold.nii.gz"
                ),
                # This subject-level kind is shared by every session and block.
                "t1w": (
                    str(root)
                    + "/sub-{subject:03d}/anat/sub-{subject:03d}_T1w.nii.gz"
                ),
                # Each {foo} is an untracked wildcard resolved from disk.
                "preproc": (
                    str(root)
                    + "/derivatives/sub-{subject:03d}/ses-{session:02d}_"
                    + "run-{run:02d}_block-{block:02d}_{foo}_preproc.fif"
                ),
            },
            id="{subject:d}{session:1d}{run:1d}{block:1d}",
            anchor="eeg",
        )

        # 2. Properties: immutable configuration and the fixed anchor cohort.
        print("\nPROPERTIES")
        print("templates:", tuple(pf.templates))
        print("anchor:", pf.anchor)
        print("id_template:", pf.id_template)
        print("id_fields:", pf.id_fields)
        print("ids:", pf.ids)
        print("full_table before scan:", pf.full_table)

        # 3. A2B conversions and path lookup.
        print("\nCONVERSIONS AND LOOKUP")
        file_id = pf.field2id(subject=7, session=1, run=1, block=2)
        print("field2id:", file_id)
        print("field2id fuzzy:", pf.field2id(subject=7, fuzzy=True))
        print("id2field:", pf.id2field(file_id))

        eeg_path = pf.id2path(file_id, "eeg")
        print("id2path existing:", eeg_path)
        print("id2path all kinds:", pf.id2path(file_id))
        print(
            "id2path build:",
            pf.id2path("7999", "eeg", require_existence=False),
        )
        print(
            "field2path:",
            pf.field2path({"subject": "7", "block": "2"}, "eeg"),
        )
        print("path2field:", pf.path2field(eeg_path, "eeg"))
        print("path2id:", pf.path2id(eeg_path, "eeg"))

        # 4. Scan: validate every kind against the fixed IDs and cache the table.
        print("\nSCAN")
        table = pf.scan()
        print("rows:", len(table))
        print("full_table is latest scan:", pf.full_table is table)


if __name__ == "__main__":
    main()