brainfc 0.3.0__py3-none-any.whl

brainfc/__init__.py

@@ -0,0 +1,20 @@
+"""An explicit, reproducible fMRI-to-connectome API."""
+
+from .models import Config, Connectome, InputError
+from .pipeline import extract_connectome
+from .io import inspect_input, discover_bids
+from .atlases import fetch_atlas
+from .presets import dataset_presets, dataset_preset
+from ._version import __version__ as __version__
+
+__all__ = [
+    "Config",
+    "Connectome",
+    "InputError",
+    "extract_connectome",
+    "inspect_input",
+    "discover_bids",
+    "fetch_atlas",
+    "dataset_presets",
+    "dataset_preset",
+]

brainfc/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

brainfc/_version.py

@@ -0,0 +1,3 @@
+"""Single source for package, CLI, HTTP and provenance versions."""
+
+__version__ = "0.3.0"

brainfc/atlases.py

@@ -0,0 +1,89 @@
+"""Explicit atlas downloads, with label values and template spaces preserved."""
+
+from pathlib import Path
+import json
+import numpy as np
+import pandas as pd
+from .models import InputError
+
+
+def fetch_atlas(name="schaefer100", *, data_dir=None):
+    """Explicitly download/cache one supported integer-label atlas.
+
+    Parameters
+    ----------
+    name : {'schaefer100','schaefer200','schaefer400','aal116'}
+        Default 'schaefer100'. Schaefer: 7 networks, 2 mm, MNI152NLin6Asym.
+        AAL: SPM12 116 regions, MNIColin27. These spaces are not interchangeable.
+    data_dir : str, pathlib.Path or None, default None
+        Cache root; default ~/.cache/brainfc/atlases.
+
+    Returns
+    -------
+    dict
+        atlas (image path), rois (TSV path), space, name, source URL, n_rois.
+
+    Notes
+    -----
+    Creates cache directories; Nilearn downloads only as required. Regenerates
+    name_rois.tsv and name.json in that cache. ROI centroid coordinates are mm
+    from the atlas affine. Network/download failures propagate. No download at
+    import time; dataset/atlas licenses remain those of their providers."""
+    from nilearn.datasets import fetch_atlas_schaefer_2018, fetch_atlas_aal
+
+    root = Path(data_dir or Path.home() / ".cache" / "brainfc" / "atlases").resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    if name in {"schaefer100", "schaefer200", "schaefer400"}:
+        n = int(name.replace("schaefer", ""))
+        atlas = fetch_atlas_schaefer_2018(n_rois=n, yeo_networks=7, resolution_mm=2, data_dir=root, verbose=0)
+        space = "MNI152NLin6Asym"
+        labels = [v.decode() if isinstance(v, bytes) else str(v) for v in atlas.labels]
+        # New Nilearn LUTs include background; use the LUT as the source of IDs.
+        if hasattr(atlas, "lut"):
+            lut = atlas.lut
+            rows = [
+                {
+                    "label_value": int(r["index"]),
+                    "roi_id": str(int(r["index"])),
+                    "name": str(r["name"]),
+                    "network": str(r["name"]).split("_")[2] if len(str(r["name"]).split("_")) > 2 else "",
+                }
+                for _, r in lut.iterrows()
+                if int(r["index"]) != 0
+            ]
+        else:
+            labels = [v for v in labels if v.lower() != "background"]
+            rows = [{"label_value": i + 1, "roi_id": str(i + 1), "name": v} for i, v in enumerate(labels)]
+        source = "https://github.com/ThomasYeoLab/CBIG/tree/master/stable_projects/brain_parcellation/Schaefer2018_LocalGlobal"
+    elif name == "aal116":
+        atlas = fetch_atlas_aal(version="SPM12", data_dir=root, verbose=0)
+        space = "MNIColin27"
+        rows = [
+            {"label_value": int(i), "roi_id": str(i), "name": str(v)}
+            for i, v in zip(atlas.indices, atlas.labels)
+            if int(i) != 0
+        ]
+        source = "https://www.gin.cnrs.fr/en/tools/aal/"
+    else:
+        raise InputError("Available atlases: schaefer100, schaefer200, schaefer400, aal116.")
+    frame = pd.DataFrame(rows)
+    import nibabel as nib
+
+    img = nib.load(atlas.maps)
+    data = np.asarray(img.dataobj)
+    xyz = [
+        nib.affines.apply_affine(img.affine, np.argwhere(data == v).mean(axis=0)) for v in frame.label_value
+    ]
+    frame[["x", "y", "z"]] = np.asarray(xyz)
+    labels_path = root / f"{name}_rois.tsv"
+    frame.to_csv(labels_path, sep="\t", index=False)
+    result = {
+        "atlas": str(Path(atlas.maps).resolve()),
+        "rois": str(labels_path),
+        "space": space,
+        "name": name,
+        "source": source,
+        "n_rois": len(frame),
+    }
+    (root / f"{name}.json").write_text(json.dumps(result, indent=2), encoding="utf-8")
+    return result

brainfc/cli.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+import argparse
+import json
+from pathlib import Path
+import threading
+import webbrowser
+from .models import Config, InputError
+from ._version import __version__
+
+
+def _parser():
+    parser = argparse.ArgumentParser(
+        prog="brainfc", description="fMRI → ROI time series → functional connectivity"
+    )
+    parser.add_argument("--version", action="version", version=f"brainfc {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+    serve = sub.add_parser("serve", help="Start the local graphical interface")
+    serve.add_argument("--port", type=int, default=8766)
+    serve.add_argument("--workspace", type=Path)
+    serve.add_argument("--no-browser", action="store_true")
+    inspect = sub.add_parser("inspect", help="Inspect an image or discover BIDS derivatives")
+    inspect.add_argument("source")
+    fetch = sub.add_parser("atlas", help="Explicitly download a supported standard atlas")
+    fetch.add_argument("name", choices=["schaefer100", "schaefer200", "schaefer400", "aal116"])
+    fetch.add_argument("--data-dir", type=Path)
+    demo = sub.add_parser("demo", help="Create synthetic NIfTI and extract a complete example report")
+    demo.add_argument("--output", type=Path, required=True)
+    extract = sub.add_parser("extract", help="Extract one run")
+    extract.add_argument("source")
+    for key in ("atlas", "rois", "confounds", "mask", "reference"):
+        extract.add_argument("--" + key)
+    extract.add_argument("--config", type=Path, help="Config JSON")
+    extract.add_argument("--output", type=Path, required=True)
+    extract.add_argument("--preprocessed", action="store_true", default=None)
+    extract.add_argument("--data-space")
+    extract.add_argument("--atlas-space")
+    extract.add_argument("--tr", type=float)
+    extract.add_argument("--no-report", action="store_true")
+    extract.add_argument("--no-figures", action="store_true")
+    batch = sub.add_parser("batch", help="Extract each fMRIPrep run separately; failed runs are recorded")
+    batch.add_argument("bids_dir", type=Path)
+    batch.add_argument("--atlas", required=True)
+    batch.add_argument("--rois")
+    batch.add_argument("--config", type=Path, required=True)
+    batch.add_argument("--output", type=Path, required=True)
+    dicom = sub.add_parser("dicom", help="Plan or run dcm2niix conversion")
+    dicom.add_argument("source")
+    dicom.add_argument("--output", required=True)
+    dicom.add_argument("--run", action="store_true")
+    preproc = sub.add_parser("preprocess", help="Plan or run external fMRIPrep (requires Docker)")
+    preproc.add_argument("bids_dir")
+    preproc.add_argument("--output", required=True)
+    preproc.add_argument("--license", required=True)
+    preproc.add_argument("--participant")
+    preproc.add_argument("--space", default="MNI152NLin6Asym")
+    preproc.add_argument("--run", action="store_true")
+    return parser
+
+
+def main(argv=None):
+    """Run the CLI with a list of arguments, or sys.argv when argv is None.
+
+    Returns 0 on success. argparse raises SystemExit(0) for help/version and
+    SystemExit(2) for usage, InputError and common path errors. Unexpected
+    library/external-process errors propagate; a failed batch exits with 2
+    after preserving successful run outputs and batch.json.
+    """
+    parser = _parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "serve":
+            if not 1 <= args.port <= 65535:
+                raise InputError("Port must be between 1 and 65535.")
+            try:
+                import uvicorn
+                from .web.app import create_app
+            except ImportError as exc:
+                raise InputError(
+                    "The installation is incomplete. Reinstall the BrainFC wheel or source "
+                    "with dependencies in this Python environment."
+                ) from exc
+            url = f"http://127.0.0.1:{args.port}"
+            if not args.no_browser:
+                timer = threading.Timer(1.5, lambda: webbrowser.open(url))
+                timer.daemon = True
+                timer.start()
+            print(f"BrainFC: {url}", flush=True)
+            uvicorn.run(create_app(args.workspace), host="127.0.0.1", port=args.port)
+        elif args.command == "inspect":
+            from .io import inspect_input
+
+            print(json.dumps(inspect_input(args.source), ensure_ascii=False, indent=2))
+        elif args.command == "atlas":
+            from .atlases import fetch_atlas
+
+            print(json.dumps(fetch_atlas(args.name, data_dir=args.data_dir), ensure_ascii=False, indent=2))
+        elif args.command == "demo":
+            from .demo import create_demo
+            from .pipeline import extract_connectome
+
+            args.output.mkdir(parents=True, exist_ok=False)
+            spec = create_demo(args.output / "input")
+            config = Config(**spec.pop("config"))
+            result = extract_connectome(**spec, config=config, progress=print)
+            result.provenance["synthetic"] = True
+            print(result.save(args.output / "result"))
+        elif args.command == "extract":
+            from .pipeline import extract_connectome
+
+            config = json.loads(args.config.read_text(encoding="utf-8-sig")) if args.config else {}
+            for key in ("preprocessed", "data_space", "atlas_space"):
+                if getattr(args, key) is not None:
+                    config[key] = getattr(args, key)
+            if args.tr is not None:
+                config["t_r"] = args.tr
+            result = extract_connectome(
+                args.source,
+                config=Config(**config),
+                progress=print,
+                **{k: getattr(args, k) for k in ("atlas", "rois", "confounds", "mask", "reference")},
+            )
+            print(result.save(args.output, figures=not args.no_figures, report=not args.no_report))
+        elif args.command == "batch":
+            from .io import discover_bids
+            from .pipeline import extract_connectome
+
+            runs = discover_bids(args.bids_dir)
+            if not runs:
+                raise InputError("No fMRIPrep preprocessed volume runs found.")
+            args.output.mkdir(parents=True, exist_ok=False)
+            config = Config(**json.loads(args.config.read_text(encoding="utf-8-sig")))
+            records = []
+            for i, run in enumerate(runs):
+                record = {
+                    "index": i,
+                    "source": run["bold"],
+                    "subject": run["subject"],
+                    "session": run["session"],
+                    "run": run["run"],
+                }
+                try:
+                    result = extract_connectome(
+                        run["bold"],
+                        atlas=args.atlas,
+                        rois=args.rois,
+                        confounds=run["confounds"],
+                        mask=run["mask"],
+                        config=config,
+                        progress=print,
+                    )
+                    destination = args.output / f"run-{i:04d}"
+                    result.save(destination)
+                    record.update(status="complete", output=str(destination.resolve()))
+                except Exception as exc:
+                    record.update(status="failed", error=str(exc))
+                records.append(record)
+                (args.output / "batch.json").write_text(
+                    json.dumps(records, ensure_ascii=False, indent=2), encoding="utf-8"
+                )
+            if any(r["status"] == "failed" for r in records):
+                raise InputError("Some runs failed. Inspect batch.json; successful results are preserved.")
+        elif args.command == "dicom":
+            from .preprocessing import dicom_plan, convert_dicom
+
+            plan = dicom_plan(args.source, args.output)
+            print(json.dumps(plan.to_dict(), ensure_ascii=False, indent=2))
+            if args.run:
+                convert_dicom(args.source, args.output)
+        else:
+            from .preprocessing import fmriprep_plan
+
+            plan = fmriprep_plan(
+                args.bids_dir, args.output, args.license, participant=args.participant, space=args.space
+            )
+            print(json.dumps(plan.to_dict(), ensure_ascii=False, indent=2))
+            if args.run:
+                plan.run()
+        return 0
+    except (InputError, FileExistsError, FileNotFoundError) as exc:
+        parser.error(str(exc))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

brainfc/demo.py

@@ -0,0 +1,77 @@
+"""Deterministic synthetic volume, never represented as human subject data."""
+
+from pathlib import Path
+import json
+import nibabel as nib
+import numpy as np
+import pandas as pd
+
+
+def create_demo(directory):
+    """Create deterministic synthetic NIfTI inputs in a new directory.
+
+    Returns a dict of source/atlas/rois/confounds paths plus a plain config dict.
+    Use Config(**spec.pop('config')) before passing spec to extract_connectome.
+    Seed 42, 160 frames, 12 artificial ROIs, TR=2 s and synthetic-demo space.
+    Creates input files only; does not extract a result or download human data.
+    Existing directory raises FileExistsError. Mark provenance['synthetic']=True
+    when exporting an extracted demo (the CLI/GUI demo commands already do so)."""
+    root = Path(directory).resolve()
+    root.mkdir(parents=True, exist_ok=False)
+    rng = np.random.default_rng(42)
+    shape, n = (32, 40, 32), 160
+    affine = np.diag([5.0, 5.0, 5.0, 1.0])
+    affine[:3, 3] = [-80, -110, -75]
+    ijk = np.indices(shape).transpose(1, 2, 3, 0)
+    xyz = nib.affines.apply_affine(affine, ijk)
+    centres = np.array(
+        [
+            [x, y, z]
+            for x in [-35, 35]
+            for y, z in [(-60, 0), (-30, 35), (15, 45), (40, 0), (-10, -20), (-55, 40)]
+        ]
+    )
+    atlas = np.zeros(shape, dtype=np.int16)
+    latent = rng.normal(size=(n, 3))
+    for i, center in enumerate(centres):
+        atlas[np.linalg.norm(xyz - center, axis=-1) < 15] = (i + 1) * 10
+    data = np.zeros((*shape, n), dtype=np.float32)
+    motion = rng.normal(0, 0.04, (n, 6))
+    for i in range(len(centres)):
+        signal = latent[:, i % 3] * (1 if i < 6 else -0.7) + rng.normal(0, 0.55, n) + motion[:, 0] * 4
+        index = atlas == (i + 1) * 10
+        data[index] = 100 + signal + rng.normal(0, 0.12, (index.sum(), n))
+    for name, a in [("demo_bold.nii.gz", data), ("demo_atlas.nii.gz", atlas)]:
+        image = nib.Nifti1Image(a, affine)
+        image.header.set_xyzt_units("mm", "sec")
+        if a.ndim == 4:
+            image.header.set_zooms((5, 5, 5, 2))
+        nib.save(image, root / name)
+    pd.DataFrame(
+        {
+            "label_value": [(i + 1) * 10 for i in range(len(centres))],
+            "roi_id": [f"Demo{i + 1:02d}" for i in range(len(centres))],
+            "name": [f"Synthetic ROI {i + 1:02d}" for i in range(len(centres))],
+            "network": [f"Synthetic group {i % 3 + 1}" for i in range(len(centres))],
+        }
+    ).to_csv(root / "rois.tsv", sep="\t", index=False)
+    frame = pd.DataFrame(motion, columns=[f"trans_{a}" for a in "xyz"] + [f"rot_{a}" for a in "xyz"])
+    frame["framewise_displacement"] = np.abs(rng.normal(0.08, 0.02, n))
+    frame.loc[[23, 74, 105], "framewise_displacement"] = 0.8
+    frame.to_csv(root / "confounds.tsv", sep="\t", index=False)
+    (root / "demo_bold.json").write_text(
+        json.dumps({"RepetitionTime": 2, "Synthetic": True}), encoding="utf-8"
+    )
+    return {
+        "source": str(root / "demo_bold.nii.gz"),
+        "atlas": str(root / "demo_atlas.nii.gz"),
+        "rois": str(root / "rois.tsv"),
+        "confounds": str(root / "confounds.tsv"),
+        "config": {
+            "preprocessed": True,
+            "data_space": "synthetic-demo",
+            "atlas_space": "synthetic-demo",
+            "t_r": 2,
+            "fd_threshold": 0.5,
+        },
+    }

brainfc/export.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+import base64
+from datetime import datetime, timezone
+import hashlib
+from importlib.resources import files
+import json
+from pathlib import Path
+import shutil
+import tempfile
+import numpy as np
+import pandas as pd
+from .models import InputError
+
+
+def _json(data):
+    return json.dumps(data, ensure_ascii=False, indent=2, allow_nan=False)
+
+
+def write_report(result, path, *, view_image=None):
+    """Write self-contained HTML and return its absolute pathlib.Path.
+
+    result is a Connectome; path must not exist. Optional view_image is a PNG path
+    embedded as the initial static preview. Parent directories are created.
+    Interactive JS/CSS and result data are embedded, with JSON escaped for safe
+    script embedding. Raises FileExistsError on overwrite or InputError if bundled
+    assets are missing. Does not open a browser; see Connectome.view."""
+    target = Path(path).expanduser().resolve()
+    if target.exists():
+        raise FileExistsError(f"Refusing to overwrite {target}")
+    static = files("brainfc").joinpath("web", "static")
+    js = static.joinpath("app.js")
+    if not js.is_file():
+        raise InputError("Packaged UI is missing. Build frontend assets before building the wheel.")
+    payload = result.to_dict()
+    if view_image:
+        payload["views_image"] = "data:image/png;base64," + base64.b64encode(
+            Path(view_image).read_bytes()
+        ).decode("ascii")
+    data = _json(payload).replace("<", "\\u003c").replace("\u2028", "\\u2028").replace("\u2029", "\\u2029")
+    script = js.read_text(encoding="utf-8").replace("</script", "<\\/script")
+    css = static.joinpath("app.css").read_text(encoding="utf-8")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(
+        '<!doctype html><html lang="zh-CN"><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">'
+        '<link rel="icon" href="data:,"><title>BrainFC · 连接分析报告</title><style>'
+        + css
+        + '</style><div id="root"></div>'
+        "<script>window.__FMRI_REPORT__=" + data + ";</script><script>" + script + "</script></html>",
+        encoding="utf-8",
+    )
+    return target
+
+
+def save_result(result, directory, *, figures=True, report=True):
+    """Export a Connectome to a new directory and return its absolute Path.
+
+    directory, figures=True and report=True have exactly the same contract as
+    Connectome.save. Writes a temporary sibling directory, removes it on errors,
+    and renames it on success. No ZIP is created. manifest.json hashes all other
+    exported files, excluding itself. See docs/outputs.md for schemas and file list."""
+    target = Path(directory).expanduser().resolve()
+    if target.exists():
+        raise FileExistsError(f"Result directory already exists: {target}. Choose a new directory.")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    temp = Path(tempfile.mkdtemp(prefix=f".{target.name}-", dir=target.parent))
+    try:
+        ids = [r["roi_id"] for r in result.rois]
+        for name, values in [("connectivity", result.connectivity), ("fisher_z", result.fisher_z)]:
+            np.save(temp / f"{name}.npy", values, allow_pickle=False)
+            pd.DataFrame(values, index=ids, columns=ids).to_csv(temp / f"{name}.csv", index_label="roi_id")
+        pd.DataFrame(result.timeseries, columns=ids).to_csv(temp / "timeseries.tsv", sep="\t", index=False)
+        np.save(temp / "timeseries.npy", result.timeseries, allow_pickle=False)
+        rows = [
+            {k: v for k, v in r.items() if k != "coordinates"}
+            | (dict(zip(("x", "y", "z"), r["coordinates"])) if r["coordinates"] else {})
+            for r in result.rois
+        ]
+        pd.DataFrame(rows).to_csv(temp / "rois.tsv", sep="\t", index=False)
+        pd.DataFrame({"original_volume_index": result.sample_indices}).to_csv(
+            temp / "samples.tsv", sep="\t", index=False
+        )
+        for name, data in [
+            ("qc", result.qc),
+            ("provenance", result.provenance),
+            ("result", result.to_dict()),
+        ]:
+            (temp / f"{name}.json").write_text(_json(data), encoding="utf-8")
+        view_image = None
+        if figures:
+            for extension in ("png", "svg", "pdf"):
+                result.plot_matrix(temp / f"matrix.{extension}")
+                if all(r.get("coordinates") for r in result.rois):
+                    result.plot_views(temp / f"eight_views.{extension}")
+            if (temp / "eight_views.png").is_file():
+                view_image = temp / "eight_views.png"
+        if report:
+            write_report(result, temp / "report.html", view_image=view_image)
+        manifest = {
+            "created_utc": datetime.now(timezone.utc).isoformat(),
+            "files": {
+                p.name: hashlib.sha256(p.read_bytes()).hexdigest() for p in temp.iterdir() if p.is_file()
+            },
+        }
+        (temp / "manifest.json").write_text(_json(manifest), encoding="utf-8")
+        temp.rename(target)
+    except BaseException:
+        shutil.rmtree(temp)
+        raise
+    return target