petfit-docker 0.1.4__tar.gz

petfit_docker-0.1.4/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: petfit-docker
+Version: 0.1.4
+Summary: A wrapper for generating Docker commands using regular PETFit syntax
+Author: The PETFit developers
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# petfit-docker
+
+`petfit-docker` is a lightweight Python wrapper that turns a BIDS-App-like
+command line into the matching `docker run` invocation for PETFit.
+Interactive Shiny mode is the default; use `--automatic` or
+`--mode automatic` to run a non-interactive pipeline.
+
+```bash
+petfit-docker /path/to/bids /path/to/derivatives participant \
+  --app modelling_plasma \
+  --blood-dir /path/to/blood \
+  --analysis-foldername Primary_Analysis
+```
+
+The command above runs:
+
+```bash
+docker run --rm -it \
+  -p 3838:3838 \
+  -v /path/to/bids:/data/bids_dir:ro \
+  -v /path/to/derivatives:/data/derivatives_dir:rw \
+  -v /path/to/blood:/data/blood_dir:ro \
+  mathesong/petfit:latest \
+  --func modelling_plasma --mode interactive
+```
+
+## Install for development
+
+```bash
+cd wrapper
+python -m pip install -e .
+```
+
+## Examples
+
+Launch the default region definition app:
+
+```bash
+petfit-docker /path/to/bids /path/to/derivatives/petfit participant
+```
+
+The three positional arguments follow the BIDS App convention:
+
+```text
+petfit-docker <bids_dir> <output_dir> participant
+```
+
+Launch region definition:
+
+```bash
+petfit-docker /path/to/bids /path/to/derivatives participant --app regiondef
+```
+
+The positional `output_dir` can be either the derivatives root or the final
+PETFit output directory. These are equivalent with the default output folder
+name:
+
+```bash
+petfit-docker /path/to/bids /path/to/derivatives/petfit participant
+petfit-docker /path/to/bids /path/to/derivatives participant --app regiondef
+petfit-docker /path/to/bids /path/to/derivatives/petfit participant --app regiondef
+```
+
+Launch plasma-input modelling:
+
+```bash
+petfit-docker /path/to/bids /path/to/derivatives participant \
+  --app modelling_plasma \
+  --blood-dir /path/to/blood
+```
+
+Run plasma-input modelling automatically:
+
+```bash
+petfit-docker /path/to/bids /path/to/derivatives participant \
+  --app modelling_plasma \
+  --blood-dir /path/to/blood \
+  --automatic
+```
+
+Open a shell in the image:
+
+```bash
+petfit-docker --shell -i mathesong/petfit:latest
+```
+
+## Patching a local petfit
+
+Use `--patch` (or `-f`) to point the wrapper at a local petfit checkout and test
+your local changes without rebuilding the image. The wrapper bind-mounts the
+source into the container, where it is reinstalled from source at startup so it
+overrides the petfit baked into the image:
+
+```bash
+petfit-docker /path/to/bids /path/to/derivatives participant \
+  --app modelling_ref \
+  --patch /path/to/your/petfit/checkout
+```
+
+This mirrors the `--patch` option of the PETPrep Docker wrapper. Because petfit
+is an R package it is reinstalled (not run directly from source), so the first
+few seconds of startup are spent installing the patched package. The patch
+works with every mode, including `--shell`.
+
+## Apple Silicon
+
+The published PETFit Docker images are currently `linux/amd64` only. The
+wrapper therefore requests `--platform linux/amd64` by default, which avoids
+Docker's platform-mismatch warning on Apple Silicon while running under
+emulation. If a native or multi-architecture image is published later, override
+the platform with `--platform linux/arm64` or disable the explicit platform with
+`--platform ""`.

petfit_docker-0.1.4/README.md

@@ -0,0 +1,112 @@
+# petfit-docker
+
+`petfit-docker` is a lightweight Python wrapper that turns a BIDS-App-like
+command line into the matching `docker run` invocation for PETFit.
+Interactive Shiny mode is the default; use `--automatic` or
+`--mode automatic` to run a non-interactive pipeline.
+
+```bash
+petfit-docker /path/to/bids /path/to/derivatives participant \
+  --app modelling_plasma \
+  --blood-dir /path/to/blood \
+  --analysis-foldername Primary_Analysis
+```
+
+The command above runs:
+
+```bash
+docker run --rm -it \
+  -p 3838:3838 \
+  -v /path/to/bids:/data/bids_dir:ro \
+  -v /path/to/derivatives:/data/derivatives_dir:rw \
+  -v /path/to/blood:/data/blood_dir:ro \
+  mathesong/petfit:latest \
+  --func modelling_plasma --mode interactive
+```
+
+## Install for development
+
+```bash
+cd wrapper
+python -m pip install -e .
+```
+
+## Examples
+
+Launch the default region definition app:
+
+```bash
+petfit-docker /path/to/bids /path/to/derivatives/petfit participant
+```
+
+The three positional arguments follow the BIDS App convention:
+
+```text
+petfit-docker <bids_dir> <output_dir> participant
+```
+
+Launch region definition:
+
+```bash
+petfit-docker /path/to/bids /path/to/derivatives participant --app regiondef
+```
+
+The positional `output_dir` can be either the derivatives root or the final
+PETFit output directory. These are equivalent with the default output folder
+name:
+
+```bash
+petfit-docker /path/to/bids /path/to/derivatives/petfit participant
+petfit-docker /path/to/bids /path/to/derivatives participant --app regiondef
+petfit-docker /path/to/bids /path/to/derivatives/petfit participant --app regiondef
+```
+
+Launch plasma-input modelling:
+
+```bash
+petfit-docker /path/to/bids /path/to/derivatives participant \
+  --app modelling_plasma \
+  --blood-dir /path/to/blood
+```
+
+Run plasma-input modelling automatically:
+
+```bash
+petfit-docker /path/to/bids /path/to/derivatives participant \
+  --app modelling_plasma \
+  --blood-dir /path/to/blood \
+  --automatic
+```
+
+Open a shell in the image:
+
+```bash
+petfit-docker --shell -i mathesong/petfit:latest
+```
+
+## Patching a local petfit
+
+Use `--patch` (or `-f`) to point the wrapper at a local petfit checkout and test
+your local changes without rebuilding the image. The wrapper bind-mounts the
+source into the container, where it is reinstalled from source at startup so it
+overrides the petfit baked into the image:
+
+```bash
+petfit-docker /path/to/bids /path/to/derivatives participant \
+  --app modelling_ref \
+  --patch /path/to/your/petfit/checkout
+```
+
+This mirrors the `--patch` option of the PETPrep Docker wrapper. Because petfit
+is an R package it is reinstalled (not run directly from source), so the first
+few seconds of startup are spent installing the patched package. The patch
+works with every mode, including `--shell`.
+
+## Apple Silicon
+
+The published PETFit Docker images are currently `linux/amd64` only. The
+wrapper therefore requests `--platform linux/amd64` by default, which avoids
+Docker's platform-mismatch warning on Apple Silicon while running under
+emulation. If a native or multi-architecture image is published later, override
+the platform with `--platform linux/arm64` or disable the explicit platform with
+`--platform ""`.

petfit_docker-0.1.4/petfit_docker/__init__.py

@@ -0,0 +1,5 @@
+"""Docker wrapper for PETFit."""
+
+from ._version import __version__
+
+__all__ = ["__version__"]

petfit_docker-0.1.4/petfit_docker/__main__.py

@@ -0,0 +1,7 @@
+"""Module entry point for ``python -m petfit_docker``."""
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

petfit_docker-0.1.4/petfit_docker/_version.py

@@ -0,0 +1,3 @@
+"""Version information for petfit-docker."""
+
+__version__ = "0.1.4"

petfit_docker-0.1.4/petfit_docker/cli.py

@@ -0,0 +1,362 @@
+"""Command line wrapper for running PETFit in Docker."""
+
+from __future__ import annotations
+
+import argparse
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+from typing import List, Optional, Sequence
+
+from ._version import __version__
+
+DEFAULT_IMAGE = "mathesong/petfit:latest"
+DEFAULT_PLATFORM = "linux/amd64"
+DEFAULT_PORT = 3838
+APPS = ("regiondef", "modelling_plasma", "modelling_ref")
+MODES = ("automatic", "interactive")
+STEPS = ("datadef", "weights", "delay", "reference_tac", "model1", "model2", "model3")
+MISSING_IMAGE = "Image '{}' is missing\nWould you like to download? [Y/n] "
+
+
+class PETFitHelpFormatter(argparse.ArgumentDefaultsHelpFormatter, argparse.RawDescriptionHelpFormatter):
+    """Preserve paragraphs while still showing defaults."""
+
+
+class PathAction(argparse.Action):
+    """Expand user paths while preserving argparse's standard display."""
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        if values is None:
+            setattr(namespace, self.dest, None)
+            return
+        if isinstance(values, list):
+            setattr(namespace, self.dest, [str(Path(value).expanduser()) for value in values])
+        else:
+            setattr(namespace, self.dest, str(Path(values).expanduser()))
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="petfit-docker",
+        formatter_class=PETFitHelpFormatter,
+        description=(
+            "The PETFit on Docker wrapper\n\n"
+            "This is a lightweight Python wrapper to run PETFit. Docker must be "
+            "installed and running. This can be checked running::\n\n"
+            "    docker info\n\n"
+            "The wrapper accepts a BIDS-App-like command line and translates host "
+            "paths into Docker bind mounts before executing the PETFit image."
+        ),
+    )
+
+    parser.add_argument("bids_dir", nargs="?", action=PathAction)
+    parser.add_argument("output_dir", nargs="?", action=PathAction)
+    parser.add_argument("analysis_level", nargs="?", choices=("participant",), default="participant")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument("-i", "--image", default=DEFAULT_IMAGE, help="image name")
+
+    wrapper = parser.add_argument_group(
+        "Wrapper options",
+        "Standard options that require mapping files into the container; see petfit usage for complete descriptions",
+    )
+    wrapper.add_argument(
+        "--app",
+        choices=APPS,
+        default="regiondef",
+        help=(
+            "PETFit app to run: "
+            "'regiondef' = define brain regions and build combined TACs; "
+            "'modelling_plasma' = invasive plasma-input models "
+            "(1TCM, 2TCM, 2TCM_irr, Logan, MA1, Patlak), requires blood data; "
+            "'modelling_ref' = non-invasive reference-tissue models "
+            "(SRTM, SRTM2, refLogan, MRTM1, MRTM2)"
+        ),
+    )
+    wrapper.add_argument(
+        "--mode",
+        choices=MODES,
+        default="interactive",
+        help="execution mode; or use the --interactive / --automatic shorthands below",
+    )
+    wrapper.add_argument(
+        "--interactive",
+        dest="mode",
+        action="store_const",
+        const="interactive",
+        default=argparse.SUPPRESS,
+        help="shorthand for --mode interactive (launch the Shiny app in the browser)",
+    )
+    wrapper.add_argument(
+        "--automatic",
+        dest="mode",
+        action="store_const",
+        const="automatic",
+        default=argparse.SUPPRESS,
+        help="shorthand for --mode automatic (run the non-interactive pipeline)",
+    )
+    wrapper.add_argument("--step", choices=STEPS, help="single automatic modelling step to run")
+    wrapper.add_argument("--blood-dir", action=PathAction, help="blood data directory for plasma input models")
+    wrapper.add_argument("-w", "--work-dir", action=PathAction, help="working directory to mount in the container")
+    wrapper.add_argument("--petfit-output-foldername", default="petfit", help="petfit output folder within derivatives")
+    wrapper.add_argument(
+        "--analysis-foldername",
+        default="Primary_Analysis",
+        help=(
+            "name of the analysis subfolder holding this run's config and outputs; "
+            "multiple can sit side by side, e.g. 'Reference_Analysis', "
+            "'Baseline_Only'"
+        ),
+    )
+    wrapper.add_argument("--cores", type=int, default=1, help="number of cores for parallel processing")
+    wrapper.add_argument(
+        "--ancillary-analysis-folder",
+        help="sibling analysis folder to inherit delay or k2prime estimates from",
+    )
+    wrapper.add_argument("--port", type=int, default=DEFAULT_PORT, help="host and container port for interactive Shiny apps")
+
+    developer = parser.add_argument_group("Developer options", "Tools for testing and debugging PETFit")
+    developer.add_argument("--shell", action="store_true", help="open shell in image instead of running PETFit")
+    developer.add_argument(
+        "-f",
+        "--patch",
+        action=PathAction,
+        help="local petfit checkout to install over the image's petfit at container "
+        "start (for testing local changes without rebuilding the image)",
+    )
+    developer.add_argument(
+        "-e",
+        "--env",
+        nargs=2,
+        action="append",
+        metavar=("ENV_VAR", "value"),
+        help="set custom environment variables within container",
+    )
+    developer.add_argument(
+        "-u",
+        "--user",
+        help="run container as a given user/uid. A group/gid can also be assigned, i.e. --user <UID>:<GID>",
+    )
+    developer.add_argument("--network", help='run container with a different network driver, e.g. "none"')
+    developer.add_argument(
+        "--platform",
+        default=DEFAULT_PLATFORM,
+        help="run Docker with a specific platform; PETFit images are currently published for linux/amd64",
+    )
+    developer.add_argument("--no-tty", action="store_true", help="run docker without TTY flag -it")
+    developer.add_argument("--dry-run", action="store_true", help="print the Docker command without executing it")
+    developer.add_argument(
+        "--skip-image-check",
+        action="store_true",
+        help="do not check whether the Docker image exists before running",
+    )
+
+    return parser
+
+
+def _absolute_path(path: Optional[str], *, create: bool = False) -> Optional[str]:
+    if path is None:
+        return None
+
+    resolved = Path(path).expanduser().absolute()
+    if create:
+        resolved.mkdir(parents=True, exist_ok=True)
+    return str(resolved)
+
+
+def _derivatives_mount_from_output(output_dir: str, petfit_output_foldername: str) -> str:
+    """Map BIDS-App-like output_dir to PETFit's derivatives mount point.
+
+    PETFit's container entry point expects the derivatives root and then appends
+    ``petfit_output_foldername`` internally. If the wrapper user passes the final
+    PETFit output directory, such as ``derivatives/petfit``, mount its parent so
+    the container does not look for ``petfit/petfit``.
+    """
+
+    output_path = Path(output_dir)
+    if output_path.name == petfit_output_foldername:
+        return str(output_path.parent)
+    return output_dir
+
+
+def _mount_argument(host_path: str, container_path: str, mode: str) -> str:
+    return f"{host_path}:{container_path}:{mode}"
+
+
+def build_docker_command(opts: argparse.Namespace) -> List[str]:
+    """Build the Docker command corresponding to parsed options."""
+
+    if opts.mode == "interactive" and (opts.port < 1 or opts.port > 65535):
+        raise SystemExit("--port must be between 1 and 65535")
+    if opts.cores < 1:
+        raise SystemExit("--cores must be at least 1")
+    if opts.app == "regiondef" and opts.step:
+        raise SystemExit("--step is only valid for modelling_plasma and modelling_ref")
+
+    bids_dir = _absolute_path(opts.bids_dir) if opts.bids_dir else None
+    output_dir = _absolute_path(opts.output_dir, create=not opts.shell) if opts.output_dir else None
+    derivatives_dir = (
+        _derivatives_mount_from_output(output_dir, opts.petfit_output_foldername)
+        if output_dir
+        else None
+    )
+    blood_dir = _absolute_path(opts.blood_dir) if opts.blood_dir else None
+    work_dir = _absolute_path(opts.work_dir, create=True) if opts.work_dir else None
+
+    if not opts.shell:
+        missing = []
+        if not bids_dir:
+            missing.append("bids_dir")
+        if not output_dir:
+            missing.append("output_dir")
+        if missing:
+            raise SystemExit("the following arguments are required unless --shell is used: " + ", ".join(missing))
+
+    command = ["docker", "run", "--rm"]
+    if opts.platform:
+        command.extend(["--platform", opts.platform])
+    if not opts.no_tty:
+        command.append("-it")
+
+    if opts.user:
+        command.extend(["--user", opts.user])
+    if opts.network:
+        command.extend(["--network", opts.network])
+
+    env = list(opts.env or [])
+    if opts.mode == "interactive":
+        env.append(("PETFIT_SHINY_PORT", str(opts.port)))
+        env.append(("SHINY_SERVER_VERSION", ""))
+        command.extend(["-p", f"{opts.port}:{opts.port}"])
+
+    for key, value in env:
+        command.extend(["-e", f"{key}={value}"])
+
+    if bids_dir:
+        command.extend(["-v", _mount_argument(bids_dir, "/data/bids_dir", "ro")])
+    if derivatives_dir:
+        command.extend(["-v", _mount_argument(derivatives_dir, "/data/derivatives_dir", "rw")])
+    if blood_dir:
+        command.extend(["-v", _mount_argument(blood_dir, "/data/blood_dir", "ro")])
+    if work_dir:
+        command.extend(["-v", _mount_argument(work_dir, "/data/work_dir", "rw")])
+
+    patch_dir = _absolute_path(opts.patch) if opts.patch else None
+    if patch_dir:
+        command.extend(["-v", _mount_argument(patch_dir, "/patch/petfit", "ro")])
+
+    if opts.shell:
+        command.extend(["--entrypoint", "/bin/bash", opts.image])
+        return command
+
+    command.append(opts.image)
+    command.extend(
+        [
+            "--func",
+            opts.app,
+            "--mode",
+            opts.mode,
+            "--petfit_output_foldername",
+            opts.petfit_output_foldername,
+            "--analysis_foldername",
+            opts.analysis_foldername,
+            "--cores",
+            str(opts.cores),
+        ]
+    )
+
+    if opts.step:
+        command.extend(["--step", opts.step])
+    if opts.ancillary_analysis_folder:
+        command.extend(["--ancillary_analysis_folder", opts.ancillary_analysis_folder])
+
+    return command
+
+
+def check_docker() -> None:
+    """Fail early if Docker is unavailable, preserving Docker's own message."""
+
+    try:
+        subprocess.run(["docker", "info"], capture_output=True, text=True, check=True)
+    except OSError as error:
+        raise SystemExit(f"Could not run Docker: {error}") from error
+    except subprocess.CalledProcessError as error:
+        docker_output = (error.stderr or error.stdout or "").strip()
+        if docker_output:
+            print(docker_output, file=sys.stderr)
+        print("Could not detect memory capacity of Docker container.", file=sys.stderr)
+        raise SystemExit("Do you have permission to run docker?") from error
+
+    return None
+
+
+def image_exists(image: str) -> bool:
+    """Return whether a Docker image is available locally."""
+
+    try:
+        result = subprocess.run(["docker", "images", "-q", image], stdout=subprocess.PIPE)
+    except OSError:
+        return False
+    return bool(result.stdout)
+
+
+def check_memory(image: str, platform: Optional[str] = DEFAULT_PLATFORM) -> int:
+    """Return available container memory in MB, or -1 if Docker cannot report it."""
+
+    command = ["docker", "run", "--rm"]
+    if platform:
+        command.extend(["--platform", platform])
+    command.extend(["--entrypoint=free", image, "-m"])
+
+    try:
+        result = subprocess.run(command, stdout=subprocess.PIPE)
+    except OSError:
+        return -1
+
+    if result.returncode:
+        return -1
+
+    for line in result.stdout.splitlines():
+        if line.startswith(b"Mem:"):
+            return int(line.decode().split()[1])
+    return -1
+
+
+def maybe_pull_image(image: str) -> None:
+    """Offer to download a missing image before Docker pulls via ``docker run``."""
+
+    if image_exists(image):
+        return
+
+    answer = input(MISSING_IMAGE.format(image))
+    if answer.strip().lower() not in ("", "y", "yes"):
+        raise SystemExit(f"Image '{image}' is required")
+
+    print("Downloading. This may take a while...", flush=True)
+
+
+def ensure_image_ready(image: str, platform: Optional[str] = DEFAULT_PLATFORM) -> None:
+    """Confirm image availability and that Docker can run a tiny memory probe."""
+
+    maybe_pull_image(image)
+    if check_memory(image, platform=platform) == -1:
+        print("Could not detect memory capacity of Docker container.", file=sys.stderr)
+        raise SystemExit("Do you have permission to run docker?")
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = _parser()
+    opts = parser.parse_args(argv)
+
+    if not opts.dry_run:
+        check_docker()
+        if not opts.skip_image_check:
+            ensure_image_ready(opts.image, platform=opts.platform)
+
+    command = build_docker_command(opts)
+    print("RUNNING: " + shlex.join(command))
+
+    if opts.dry_run:
+        return 0
+    return subprocess.call(command)

petfit_docker-0.1.4/petfit_docker.egg-info/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: petfit-docker
+Version: 0.1.4
+Summary: A wrapper for generating Docker commands using regular PETFit syntax
+Author: The PETFit developers
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# petfit-docker
+
+`petfit-docker` is a lightweight Python wrapper that turns a BIDS-App-like
+command line into the matching `docker run` invocation for PETFit.
+Interactive Shiny mode is the default; use `--automatic` or
+`--mode automatic` to run a non-interactive pipeline.
+
+```bash
+petfit-docker /path/to/bids /path/to/derivatives participant \
+  --app modelling_plasma \
+  --blood-dir /path/to/blood \
+  --analysis-foldername Primary_Analysis
+```
+
+The command above runs:
+
+```bash
+docker run --rm -it \
+  -p 3838:3838 \
+  -v /path/to/bids:/data/bids_dir:ro \
+  -v /path/to/derivatives:/data/derivatives_dir:rw \
+  -v /path/to/blood:/data/blood_dir:ro \
+  mathesong/petfit:latest \
+  --func modelling_plasma --mode interactive
+```
+
+## Install for development
+
+```bash
+cd wrapper
+python -m pip install -e .
+```
+
+## Examples
+
+Launch the default region definition app:
+
+```bash
+petfit-docker /path/to/bids /path/to/derivatives/petfit participant
+```
+
+The three positional arguments follow the BIDS App convention:
+
+```text
+petfit-docker <bids_dir> <output_dir> participant
+```
+
+Launch region definition:
+
+```bash
+petfit-docker /path/to/bids /path/to/derivatives participant --app regiondef
+```
+
+The positional `output_dir` can be either the derivatives root or the final
+PETFit output directory. These are equivalent with the default output folder
+name:
+
+```bash
+petfit-docker /path/to/bids /path/to/derivatives/petfit participant
+petfit-docker /path/to/bids /path/to/derivatives participant --app regiondef
+petfit-docker /path/to/bids /path/to/derivatives/petfit participant --app regiondef
+```
+
+Launch plasma-input modelling:
+
+```bash
+petfit-docker /path/to/bids /path/to/derivatives participant \
+  --app modelling_plasma \
+  --blood-dir /path/to/blood
+```
+
+Run plasma-input modelling automatically:
+
+```bash
+petfit-docker /path/to/bids /path/to/derivatives participant \
+  --app modelling_plasma \
+  --blood-dir /path/to/blood \
+  --automatic
+```
+
+Open a shell in the image:
+
+```bash
+petfit-docker --shell -i mathesong/petfit:latest
+```
+
+## Patching a local petfit
+
+Use `--patch` (or `-f`) to point the wrapper at a local petfit checkout and test
+your local changes without rebuilding the image. The wrapper bind-mounts the
+source into the container, where it is reinstalled from source at startup so it
+overrides the petfit baked into the image:
+
+```bash
+petfit-docker /path/to/bids /path/to/derivatives participant \
+  --app modelling_ref \
+  --patch /path/to/your/petfit/checkout
+```
+
+This mirrors the `--patch` option of the PETPrep Docker wrapper. Because petfit
+is an R package it is reinstalled (not run directly from source), so the first
+few seconds of startup are spent installing the patched package. The patch
+works with every mode, including `--shell`.
+
+## Apple Silicon
+
+The published PETFit Docker images are currently `linux/amd64` only. The
+wrapper therefore requests `--platform linux/amd64` by default, which avoids
+Docker's platform-mismatch warning on Apple Silicon while running under
+emulation. If a native or multi-architecture image is published later, override
+the platform with `--platform linux/arm64` or disable the explicit platform with
+`--platform ""`.

petfit_docker-0.1.4/petfit_docker.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+setup.py
+petfit_docker/__init__.py
+petfit_docker/__main__.py
+petfit_docker/_version.py
+petfit_docker/cli.py
+petfit_docker.egg-info/PKG-INFO
+petfit_docker.egg-info/SOURCES.txt
+petfit_docker.egg-info/dependency_links.txt
+petfit_docker.egg-info/entry_points.txt
+petfit_docker.egg-info/top_level.txt
+tests/test_cli.py

petfit_docker-0.1.4/petfit_docker.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

petfit_docker-0.1.4/petfit_docker.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+petfit-docker = petfit_docker.cli:main

petfit_docker-0.1.4/petfit_docker.egg-info/top_level.txt

@@ -0,0 +1 @@
+petfit_docker

petfit_docker-0.1.4/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "petfit-docker"
+dynamic = ["version"]
+description = "A wrapper for generating Docker commands using regular PETFit syntax"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [
+  { name = "The PETFit developers" }
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Medical Science Apps."
+]
+
+[project.scripts]
+petfit-docker = "petfit_docker.cli:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "petfit_docker._version.__version__" }
+
+[tool.setuptools.packages.find]
+include = ["petfit_docker*"]

petfit_docker-0.1.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

petfit_docker-0.1.4/setup.py

@@ -0,0 +1,6 @@
+"""Compatibility setup.py for editable installs and older packaging tools."""
+
+from setuptools import setup
+
+
+setup()

petfit_docker-0.1.4/tests/test_cli.py

@@ -0,0 +1,343 @@
+import tempfile
+import unittest
+from pathlib import Path
+import sys
+from io import StringIO
+from unittest.mock import patch
+import subprocess
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from petfit_docker.cli import (
+    _parser,
+    build_docker_command,
+    check_docker,
+    check_memory,
+    ensure_image_ready,
+    main,
+    maybe_pull_image,
+)
+
+
+def abs_path(path):
+    return str(Path(path).expanduser().absolute())
+
+
+class DockerCommandTests(unittest.TestCase):
+    def test_no_arguments_parse_without_path_traceback(self):
+        opts = _parser().parse_args([])
+
+        self.assertIsNone(opts.bids_dir)
+        self.assertIsNone(opts.output_dir)
+
+    def test_builds_bids_app_like_modelling_command(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            bids = root / "bids"
+            derivatives = root / "derivatives"
+            blood = root / "blood"
+            bids.mkdir()
+            blood.mkdir()
+
+            opts = _parser().parse_args(
+                [
+                    str(bids),
+                    str(derivatives),
+                    "participant",
+                    "--app",
+                    "modelling_plasma",
+                    "--blood-dir",
+                    str(blood),
+                    "--step",
+                    "weights",
+                    "--automatic",
+                    "--no-tty",
+                    "--dry-run",
+                ]
+            )
+
+            command = build_docker_command(opts)
+
+            self.assertIn("docker", command)
+            self.assertIn("--func", command)
+            self.assertIn("modelling_plasma", command)
+            self.assertIn("--platform", command)
+            self.assertIn("linux/amd64", command)
+            self.assertIn("--step", command)
+            self.assertIn("weights", command)
+            self.assertIn(f"{abs_path(bids)}:/data/bids_dir:ro", command)
+            self.assertIn(f"{abs_path(derivatives)}:/data/derivatives_dir:rw", command)
+            self.assertIn(f"{abs_path(blood)}:/data/blood_dir:ro", command)
+            self.assertTrue(derivatives.exists())
+
+    def test_interactive_mode_is_default(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            bids = root / "bids"
+            derivatives = root / "derivatives"
+            bids.mkdir()
+
+            opts = _parser().parse_args(
+                [
+                    str(bids),
+                    str(derivatives),
+                    "participant",
+                    "--app",
+                    "regiondef",
+                    "--no-tty",
+                    "--dry-run",
+                ]
+            )
+
+            command = build_docker_command(opts)
+
+            mode_index = command.index("--mode")
+            self.assertEqual(command[mode_index + 1], "interactive")
+            self.assertIn("PETFIT_SHINY_PORT=3838", command)
+            self.assertIn("SHINY_SERVER_VERSION=", command)
+
+    def test_output_dir_can_be_final_petfit_directory(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            bids = root / "bids"
+            derivatives = root / "derivatives"
+            petfit_output = derivatives / "petfit"
+            bids.mkdir()
+
+            opts = _parser().parse_args(
+                [
+                    str(bids),
+                    str(petfit_output),
+                    "participant",
+                    "--app",
+                    "regiondef",
+                    "--no-tty",
+                    "--dry-run",
+                ]
+            )
+
+            command = build_docker_command(opts)
+
+            self.assertIn(f"{abs_path(derivatives)}:/data/derivatives_dir:rw", command)
+            self.assertNotIn(f"{abs_path(petfit_output)}:/data/derivatives_dir:rw", command)
+            self.assertTrue(petfit_output.exists())
+
+    def test_interactive_mode_maps_port_and_env(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            bids = root / "bids"
+            derivatives = root / "derivatives"
+            bids.mkdir()
+
+            opts = _parser().parse_args(
+                [
+                    str(bids),
+                    str(derivatives),
+                    "participant",
+                    "--mode",
+                    "interactive",
+                    "--port",
+                    "3840",
+                    "--no-tty",
+                    "--dry-run",
+                ]
+            )
+
+            command = build_docker_command(opts)
+
+            self.assertIn("-p", command)
+            self.assertIn("3840:3840", command)
+            self.assertIn("-e", command)
+            self.assertIn("PETFIT_SHINY_PORT=3840", command)
+
+    def test_patch_mounts_local_petfit(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            bids = root / "bids"
+            derivatives = root / "derivatives"
+            patch = root / "petfit"
+            bids.mkdir()
+            patch.mkdir()
+
+            opts = _parser().parse_args(
+                [
+                    str(bids),
+                    str(derivatives),
+                    "participant",
+                    "--app",
+                    "regiondef",
+                    "--patch",
+                    str(patch),
+                    "--no-tty",
+                    "--dry-run",
+                ]
+            )
+
+            command = build_docker_command(opts)
+
+            self.assertIn(f"{abs_path(patch)}:/patch/petfit:ro", command)
+
+    def test_patch_works_with_shell(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            patch = Path(tmpdir) / "petfit"
+            patch.mkdir()
+
+            opts = _parser().parse_args(
+                [
+                    "--shell",
+                    "--patch",
+                    str(patch),
+                    "--no-tty",
+                    "--dry-run",
+                ]
+            )
+
+            command = build_docker_command(opts)
+
+            self.assertIn(f"{abs_path(patch)}:/patch/petfit:ro", command)
+
+    def test_regiondef_rejects_step(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            bids = root / "bids"
+            derivatives = root / "derivatives"
+            bids.mkdir()
+
+            opts = _parser().parse_args(
+                [
+                    str(bids),
+                    str(derivatives),
+                    "participant",
+                    "--app",
+                    "regiondef",
+                    "--step",
+                    "weights",
+                ]
+            )
+
+            with self.assertRaises(SystemExit):
+                build_docker_command(opts)
+
+    def test_check_docker_surfaces_daemon_error(self):
+        error = subprocess.CalledProcessError(
+            1,
+            ["docker", "info"],
+            stderr="Cannot connect to the Docker daemon at unix:///tmp/docker.sock. Is the docker daemon running?\n",
+        )
+
+        with patch("petfit_docker.cli.subprocess.run", side_effect=error):
+            with patch("sys.stderr", new_callable=StringIO) as stderr:
+                with self.assertRaises(SystemExit) as caught:
+                    check_docker()
+
+        self.assertIn("Cannot connect to the Docker daemon", stderr.getvalue())
+        self.assertIn("Could not detect memory capacity", stderr.getvalue())
+        self.assertEqual(str(caught.exception), "Do you have permission to run docker?")
+
+    def test_main_checks_docker_and_image_before_required_paths(self):
+        with patch("petfit_docker.cli.check_docker") as docker_check:
+            with patch("petfit_docker.cli.ensure_image_ready") as ensure_image:
+                with self.assertRaises(SystemExit) as caught:
+                    main([])
+
+        docker_check.assert_called_once()
+        ensure_image.assert_called_once_with("mathesong/petfit:latest", platform="linux/amd64")
+        self.assertIn("bids_dir", str(caught.exception))
+
+    def test_main_stops_on_docker_failure_before_image_check(self):
+        with patch("petfit_docker.cli.check_docker", side_effect=SystemExit("docker failed")):
+            with patch("petfit_docker.cli.ensure_image_ready") as ensure_image:
+                with self.assertRaises(SystemExit) as caught:
+                    main([])
+
+        ensure_image.assert_not_called()
+        self.assertEqual(str(caught.exception), "docker failed")
+
+    def test_main_dry_run_skips_docker_and_image_checks(self):
+        with patch("petfit_docker.cli.check_docker") as docker_check:
+            with patch("petfit_docker.cli.ensure_image_ready") as ensure_image:
+                with self.assertRaises(SystemExit) as caught:
+                    main(["--dry-run"])
+
+        docker_check.assert_not_called()
+        ensure_image.assert_not_called()
+        self.assertIn("bids_dir", str(caught.exception))
+
+    def test_main_skip_image_check_still_checks_docker(self):
+        with patch("petfit_docker.cli.check_docker") as docker_check:
+            with patch("petfit_docker.cli.ensure_image_ready") as ensure_image:
+                with self.assertRaises(SystemExit) as caught:
+                    main(["--skip-image-check"])
+
+        docker_check.assert_called_once()
+        ensure_image.assert_not_called()
+        self.assertIn("bids_dir", str(caught.exception))
+
+    def test_missing_image_prompts_and_defers_pull_to_memory_probe(self):
+        with patch("petfit_docker.cli.image_exists", return_value=False):
+            with patch("builtins.input", return_value="y"):
+                with patch("sys.stdout", new_callable=StringIO) as stdout:
+                    maybe_pull_image("mathesong/petfit:latest")
+
+        self.assertIn("Downloading. This may take a while...", stdout.getvalue())
+
+    def test_check_memory_reads_container_memory(self):
+        result = subprocess.CompletedProcess(
+            [
+                "docker",
+                "run",
+                "--rm",
+                "--platform",
+                "linux/amd64",
+                "--entrypoint=free",
+                "mathesong/petfit:latest",
+                "-m",
+            ],
+            0,
+            stdout=b"              total        used        free\nMem:           15999        1000       14999\n",
+        )
+
+        with patch("petfit_docker.cli.subprocess.run", return_value=result) as run:
+            self.assertEqual(check_memory("mathesong/petfit:latest"), 15999)
+        run.assert_called_once_with(
+            [
+                "docker",
+                "run",
+                "--rm",
+                "--platform",
+                "linux/amd64",
+                "--entrypoint=free",
+                "mathesong/petfit:latest",
+                "-m",
+            ],
+            stdout=subprocess.PIPE,
+        )
+
+    def test_platform_can_be_disabled_for_native_multiarch_images(self):
+        result = subprocess.CompletedProcess(
+            ["docker", "run", "--rm", "--entrypoint=free", "custom/petfit:arm64", "-m"],
+            0,
+            stdout=b"Mem:           32000        1000       31000\n",
+        )
+
+        with patch("petfit_docker.cli.subprocess.run", return_value=result) as run:
+            self.assertEqual(check_memory("custom/petfit:arm64", platform=None), 32000)
+
+        run.assert_called_once_with(
+            ["docker", "run", "--rm", "--entrypoint=free", "custom/petfit:arm64", "-m"],
+            stdout=subprocess.PIPE,
+        )
+
+    def test_failed_memory_probe_exits_without_traceback(self):
+        with patch("petfit_docker.cli.maybe_pull_image"):
+            with patch("petfit_docker.cli.check_memory", return_value=-1):
+                with patch("sys.stderr", new_callable=StringIO) as stderr:
+                    with self.assertRaises(SystemExit) as caught:
+                        ensure_image_ready("mathesong/petfit:latest")
+
+        self.assertIn("Could not detect memory capacity", stderr.getvalue())
+        self.assertEqual(str(caught.exception), "Do you have permission to run docker?")
+
+
+if __name__ == "__main__":
+    unittest.main()