dti-alps 0.1.0__tar.gz

dti_alps-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: dti-alps
+Version: 0.1.0
+Summary: Automatic DTI-ALPS ROI detection and analysis
+Author: DTI-ALPS Team
+Project-URL: Repository, https://github.com/rmoskwa/auto-DTI-ALPS
+Keywords: dti,alps,neuroimaging,mri,diffusion
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: nibabel
+Requires-Dist: scipy
+Provides-Extra: gui
+Requires-Dist: PySide6; extra == "gui"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: build
+Requires-Dist: pyinstaller; extra == "build"
+
+# autoDTI-ALPS
+
+Automated DTI-ALPS (Diffusion Tensor Imaging Along the Perivascular Space) analysis tool. Uses template-based registration to place ROIs in projection and association fiber regions, then calculates the DTI-ALPS index from diffusion tensor imaging data.
+
+## Dependencies
+
+### Python
+
+Requires Python 3.10+.
+
+Core dependencies (installed automatically):
+- [NumPy](https://numpy.org/)
+- [NiBabel](https://nipy.org/nibabel/)
+- [SciPy](https://scipy.org/)
+
+Optional GUI dependencies (`pip install -e ".[gui]"`):
+- [Matplotlib](https://matplotlib.org/)
+- [Pillow](https://python-pillow.org/)
+
+### External Neuroimaging Software
+
+The following third-party programs must be installed and available on your system PATH.
+
+#### MRtrix3 (required)
+
+[MRtrix3](https://www.mrtrix.org/) provides tools for diffusion MRI preprocessing and tensor fitting.
+
+| Command | Pipeline Stage | Purpose |
+|---------|---------------|---------|
+| `dwidenoise` | Denoising | Marchenko-Pastur PCA thermal noise removal |
+| `mrdegibbs` | Gibbs Removal | Gibbs ringing artifact correction |
+| `dwifslpreproc` | Preprocessing | Eddy current, motion, and distortion correction |
+| `dwi2tensor` | Tensor Fitting | Fit diffusion tensor model to DWI data |
+| `tensor2metric` | Metric Extraction | Extract FA, eigenvectors (V1-V3), and eigenvalues (L1-L3) |
+| `dwi2mask` | Preprocessing | Brain mask generation from DWI |
+| `dwiextract` | B0 Extraction | Extract b=0 volumes from DWI |
+| `mrmath` | B0 Extraction | Average multiple b=0 volumes |
+| `mrconvert` | Format Conversion | Image format conversion and header manipulation |
+
+Installation: https://www.mrtrix.org/download/
+
+#### FSL (required)
+
+[FSL](https://fsl.fmrib.ox.ac.uk/fsl/) provides tools for brain extraction, registration, and image manipulation.
+
+| Command | Pipeline Stage | Purpose |
+|---------|---------------|---------|
+| `flirt` | Registration | Linear (affine) FA-to-template registration |
+| `fnirt` | Registration | Non-linear FA-to-template registration |
+| `invwarp` | Registration | Generate inverse warp field for ROI transformation |
+| `applywarp` | ROI Placement | Transform ROI templates from standard to native space |
+| `fslmaths` | Masking | Apply brain mask to FA image |
+| `eddy` | Preprocessing | Eddy current and motion correction |
+| `topup` | Preprocessing | Susceptibility-induced distortion field estimation |
+| `applytopup` | Preprocessing | Apply topup distortion correction |
+
+Installation: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FslInstallation
+
+## Installation
+
+Whichever route you choose, MRtrix3 and FSL are **not** bundled and must be
+installed separately and on your `PATH` (see
+[External Neuroimaging Software](#external-neuroimaging-software)).
+
+### Install with pipx (recommended)
+
+If you have Python 3.10+, [`pipx`](https://pipx.pypa.io/) installs the app into
+an isolated environment and puts the `dti-alps` command on your `PATH`:
+
+```bash
+pipx install dti-alps
+dti-alps            # launch the GUI
+```
+
+Update with `pipx upgrade dti-alps`. (Plain `pip install dti-alps` also works,
+ideally inside a virtualenv, and provides the same `dti-alps` command.)
+
+### Download the AppImage (no Python needed)
+
+For double-click file with no Python setup, grab the latest Linux **AppImage** from the [Releases page](https://github.com/rmoskwa/auto-DTI-ALPS/releases):
+
+```bash
+chmod +x dti-alps-*-x86_64.AppImage
+./dti-alps-0.1.0-x86_64.AppImage
+```
+
+The AppImage bundles the app and its Python dependencies. To update, download
+the newer AppImage and replace the old file.
+
+> **Qt runtime note:** the GUI uses Qt 6, which needs `libxcb-cursor0` on the
+> host. If the app fails to start with an `xcb` platform-plugin error, install
+> it: `sudo apt install libxcb-cursor0` (Debian/Ubuntu).
+
+### From source (development)
+
+```bash
+pip install -e ".[gui]"
+```
+
+## Usage
+
+```bash
+dti-alps                    # Launch GUI (default)
+dti-alps --viewer           # Launch Results Viewer
+dti-alps --viewer /path     # Launch viewer with specific output folder
+dti-alps --report /path     # Generate quality reports
+dti-alps --reanalyze /path --sphere 3  # Reanalyze with different ROI shapes
+```
+
+When running the AppImage, substitute `./dti-alps-*.AppImage` for `dti-alps`;
+all CLI flags are forwarded (e.g. `./dti-alps-*.AppImage --viewer /path`).

dti_alps-0.1.0/README.md

@@ -0,0 +1,111 @@
+# autoDTI-ALPS
+
+Automated DTI-ALPS (Diffusion Tensor Imaging Along the Perivascular Space) analysis tool. Uses template-based registration to place ROIs in projection and association fiber regions, then calculates the DTI-ALPS index from diffusion tensor imaging data.
+
+## Dependencies
+
+### Python
+
+Requires Python 3.10+.
+
+Core dependencies (installed automatically):
+- [NumPy](https://numpy.org/)
+- [NiBabel](https://nipy.org/nibabel/)
+- [SciPy](https://scipy.org/)
+
+Optional GUI dependencies (`pip install -e ".[gui]"`):
+- [Matplotlib](https://matplotlib.org/)
+- [Pillow](https://python-pillow.org/)
+
+### External Neuroimaging Software
+
+The following third-party programs must be installed and available on your system PATH.
+
+#### MRtrix3 (required)
+
+[MRtrix3](https://www.mrtrix.org/) provides tools for diffusion MRI preprocessing and tensor fitting.
+
+| Command | Pipeline Stage | Purpose |
+|---------|---------------|---------|
+| `dwidenoise` | Denoising | Marchenko-Pastur PCA thermal noise removal |
+| `mrdegibbs` | Gibbs Removal | Gibbs ringing artifact correction |
+| `dwifslpreproc` | Preprocessing | Eddy current, motion, and distortion correction |
+| `dwi2tensor` | Tensor Fitting | Fit diffusion tensor model to DWI data |
+| `tensor2metric` | Metric Extraction | Extract FA, eigenvectors (V1-V3), and eigenvalues (L1-L3) |
+| `dwi2mask` | Preprocessing | Brain mask generation from DWI |
+| `dwiextract` | B0 Extraction | Extract b=0 volumes from DWI |
+| `mrmath` | B0 Extraction | Average multiple b=0 volumes |
+| `mrconvert` | Format Conversion | Image format conversion and header manipulation |
+
+Installation: https://www.mrtrix.org/download/
+
+#### FSL (required)
+
+[FSL](https://fsl.fmrib.ox.ac.uk/fsl/) provides tools for brain extraction, registration, and image manipulation.
+
+| Command | Pipeline Stage | Purpose |
+|---------|---------------|---------|
+| `flirt` | Registration | Linear (affine) FA-to-template registration |
+| `fnirt` | Registration | Non-linear FA-to-template registration |
+| `invwarp` | Registration | Generate inverse warp field for ROI transformation |
+| `applywarp` | ROI Placement | Transform ROI templates from standard to native space |
+| `fslmaths` | Masking | Apply brain mask to FA image |
+| `eddy` | Preprocessing | Eddy current and motion correction |
+| `topup` | Preprocessing | Susceptibility-induced distortion field estimation |
+| `applytopup` | Preprocessing | Apply topup distortion correction |
+
+Installation: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FslInstallation
+
+## Installation
+
+Whichever route you choose, MRtrix3 and FSL are **not** bundled and must be
+installed separately and on your `PATH` (see
+[External Neuroimaging Software](#external-neuroimaging-software)).
+
+### Install with pipx (recommended)
+
+If you have Python 3.10+, [`pipx`](https://pipx.pypa.io/) installs the app into
+an isolated environment and puts the `dti-alps` command on your `PATH`:
+
+```bash
+pipx install dti-alps
+dti-alps            # launch the GUI
+```
+
+Update with `pipx upgrade dti-alps`. (Plain `pip install dti-alps` also works,
+ideally inside a virtualenv, and provides the same `dti-alps` command.)
+
+### Download the AppImage (no Python needed)
+
+For double-click file with no Python setup, grab the latest Linux **AppImage** from the [Releases page](https://github.com/rmoskwa/auto-DTI-ALPS/releases):
+
+```bash
+chmod +x dti-alps-*-x86_64.AppImage
+./dti-alps-0.1.0-x86_64.AppImage
+```
+
+The AppImage bundles the app and its Python dependencies. To update, download
+the newer AppImage and replace the old file.
+
+> **Qt runtime note:** the GUI uses Qt 6, which needs `libxcb-cursor0` on the
+> host. If the app fails to start with an `xcb` platform-plugin error, install
+> it: `sudo apt install libxcb-cursor0` (Debian/Ubuntu).
+
+### From source (development)
+
+```bash
+pip install -e ".[gui]"
+```
+
+## Usage
+
+```bash
+dti-alps                    # Launch GUI (default)
+dti-alps --viewer           # Launch Results Viewer
+dti-alps --viewer /path     # Launch viewer with specific output folder
+dti-alps --report /path     # Generate quality reports
+dti-alps --reanalyze /path --sphere 3  # Reanalyze with different ROI shapes
+```
+
+When running the AppImage, substitute `./dti-alps-*.AppImage` for `dti-alps`;
+all CLI flags are forwarded (e.g. `./dti-alps-*.AppImage --viewer /path`).

dti_alps-0.1.0/dti_alps/__init__.py

@@ -0,0 +1,8 @@
+"""
+DTI-ALPS - Automated DTI-ALPS Processing Pipeline
+
+This package provides tools for automated DTI-ALPS (Diffusion Tensor Imaging
+Along the Perivascular Space) analysis using template-based ROI placement.
+"""
+
+__version__ = "0.1.0"

dti_alps-0.1.0/dti_alps/__main__.py

@@ -0,0 +1,319 @@
+"""
+Entry point for python -m dti_alps
+
+Usage:
+    python -m dti_alps                           # Launch GUI (default)
+    python -m dti_alps --gui                     # Launch GUI explicitly
+    python -m dti_alps --viewer                  # Launch Results Viewer
+    python -m dti_alps --viewer /path/to/output  # Launch viewer with folder
+    python -m dti_alps --report /path/to/output  # Generate quality reports
+
+ROI Reanalysis (post-processing with different ROI shapes):
+    python -m dti_alps --reanalyze /path/to/output --sphere 3.0
+    python -m dti_alps --reanalyze /path/to/output --squarev9
+    python -m dti_alps --reanalyze /path/to/output --squarev4
+    python -m dti_alps --reanalyze /path/to/output --sphere 2.5 --adaptive
+    python -m dti_alps --reanalyze /path/to/output --sphere 2,3,4
+    python -m dti_alps --reanalyze /path/to/output --sphere 3 --squarev4
+
+Output naming:
+    Without --adaptive: rois_{shape}/ and alps_results_{shape}.csv
+    With --adaptive:    rois_{shape}_adaptive/ and alps_results_{shape}_adaptive.csv
+    The default 3 mm sphere collapses to the bare rois/ and alps_results.csv.
+
+    Examples:
+        --sphere 3          -> rois/, alps_results.csv
+        --sphere 3 --adaptive -> rois_adaptive/, alps_results_rois_adaptive.csv
+        --squarev9          -> rois_squarev9/, alps_results_squarev9.csv
+        --squarev9 --adaptive -> rois_squarev9_adaptive/, alps_results_squarev9_adaptive.csv
+        --squarev4          -> rois_squarev4/, alps_results_squarev4.csv
+        --sphere 2.5        -> rois_sphere2p5/, alps_results_sphere2p5.csv
+        --sphere 2.5 --adaptive -> rois_sphere2p5_adaptive/, alps_results_sphere2p5_adaptive.csv
+
+Quality Report Generation:
+    python -m dti_alps --report /path/to/output
+        Generates quality_report_{shape}.csv for each ROI shape found.
+        Reports include:
+        - Directional Alignment (V1): How well fibers align with expected direction
+        - Angular Dispersion (V1): Standard deviation of fiber angles
+        - Fractional Anisotropy: Mean FA within each ROI
+"""
+
+import argparse
+import sys
+
+from .processing.constants import ADAPTIVE_SEARCH_RANGE, ROI_SPHERE_RADIUS_RANGE
+
+# Sphere radius validation bounds, read from the engine's single source of truth.
+SPHERE_RADIUS_MIN, SPHERE_RADIUS_MAX = ROI_SPHERE_RADIUS_RANGE
+
+# Adaptive search envelope bounds, from the same single source of truth the GUI
+# and the AdaptiveSearchConfig guard use, so the three cannot drift apart.
+SEARCH_MIN, SEARCH_MAX = ADAPTIVE_SEARCH_RANGE
+
+
+def _validate_search_value(value: str) -> int:
+    """Validate an adaptive-search flag is an int within the allowed range."""
+    try:
+        parsed = int(value)
+    except ValueError as err:
+        raise argparse.ArgumentTypeError(f"invalid int value: '{value}'") from err
+
+    if parsed < SEARCH_MIN or parsed > SEARCH_MAX:
+        raise argparse.ArgumentTypeError(
+            f"must be between {SEARCH_MIN} and {SEARCH_MAX}, got {parsed}"
+        )
+    return parsed
+
+
+def _validate_sphere_radii(value: str) -> list[float]:
+    """Validate comma-separated sphere radii are within allowed range."""
+    radii = []
+    for part in value.split(","):
+        part = part.strip()
+        try:
+            radius = float(part)
+        except ValueError as err:
+            raise argparse.ArgumentTypeError(f"invalid float value: '{part}'") from err
+
+        if radius < SPHERE_RADIUS_MIN or radius > SPHERE_RADIUS_MAX:
+            raise argparse.ArgumentTypeError(
+                f"radius must be between {SPHERE_RADIUS_MIN} and {SPHERE_RADIUS_MAX} mm, "
+                f"got {radius}"
+            )
+        radii.append(radius)
+    return radii
+
+
+def _parse_reanalysis_args() -> argparse.Namespace:
+    """Parse command line arguments for reanalysis mode."""
+    from .processing.constants import FA_THRESHOLD, AdaptiveSearchConfig
+
+    search_defaults = AdaptiveSearchConfig()
+
+    parser = argparse.ArgumentParser(
+        description="DTI-ALPS ROI Reanalysis",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  %(prog)s --reanalyze /path/to/output --sphere 3.0
+      Reanalyze with 3mm radius spherical ROIs
+
+  %(prog)s --reanalyze /path/to/output --squarev9
+      Reanalyze with 3x3 voxel square ROIs (9 voxels)
+
+  %(prog)s --reanalyze /path/to/output --squarev4
+      Reanalyze with 2x2 voxel square ROIs (4 voxels, V1-optimized)
+
+  %(prog)s --reanalyze /path/to/output --sphere 2.5 --adaptive
+      Reanalyze with 2.5mm spheres and adaptive ROI placement enabled
+
+  %(prog)s --reanalyze /path/to/output --sphere 2,3,4
+      Reanalyze with 2mm, 3mm, and 4mm spheres in one run
+
+  %(prog)s --reanalyze /path/to/output --sphere 3 --squarev4
+      Reanalyze with both 3mm sphere and 2x2 square ROIs
+
+  %(prog)s --reanalyze /path/to/output --squarev9 --adaptive --method ALPS-LAB
+      Reanalyze with square ROIs, adaptive placement, and only ALPS-LAB calculation
+        """,
+    )
+
+    parser.add_argument(
+        "--reanalyze",
+        metavar="OUTPUT_DIR",
+        required=True,
+        help="Path to output directory containing processed subjects",
+    )
+
+    # ROI shape options (can be combined)
+    parser.add_argument(
+        "--sphere",
+        type=_validate_sphere_radii,
+        metavar="RADIUS[,RADIUS,...]",
+        help=(
+            f"Create spherical ROIs with given radius/radii "
+            f"({SPHERE_RADIUS_MIN}-{SPHERE_RADIUS_MAX} mm). "
+            f"Comma-separated for multiple (e.g., --sphere 2,3,4)"
+        ),
+    )
+    parser.add_argument(
+        "--squarev9",
+        action="store_true",
+        help="Create 3x3 voxel square ROIs in the axial plane (9 voxels total)",
+    )
+    parser.add_argument(
+        "--squarev4",
+        action="store_true",
+        help="Create 2x2 voxel square ROIs in the axial plane (4 voxels, V1-optimized)",
+    )
+
+    parser.add_argument(
+        "--adaptive",
+        action="store_true",
+        help="Enable adaptive ROI placement based on fiber orientation",
+    )
+
+    # Adaptive search envelope. Each is validated to the shared 1-4 range and
+    # defaults to the historical value; all are inert without --adaptive
+    # (Standard placement runs no search).
+    search_help_suffix = f"(±voxels, {SEARCH_MIN}-{SEARCH_MAX}, only with --adaptive)"
+    parser.add_argument(
+        "--search-x",
+        type=_validate_search_value,
+        default=search_defaults.search_x,
+        metavar="N",
+        help=f"Adaptive search window in X {search_help_suffix}",
+    )
+    parser.add_argument(
+        "--search-y",
+        type=_validate_search_value,
+        default=search_defaults.search_y,
+        metavar="N",
+        help=f"Adaptive search window in Y {search_help_suffix}",
+    )
+    parser.add_argument(
+        "--search-z",
+        type=_validate_search_value,
+        default=search_defaults.search_z,
+        metavar="N",
+        help=f"Adaptive search window in Z {search_help_suffix}",
+    )
+    parser.add_argument(
+        "--max-y-drift",
+        type=_validate_search_value,
+        default=search_defaults.max_y_drift,
+        metavar="N",
+        help=f"Max association-ROI Y drift from projection ROI {search_help_suffix}",
+    )
+    parser.add_argument(
+        "--max-z-drift",
+        type=_validate_search_value,
+        default=search_defaults.max_z_drift,
+        metavar="N",
+        help=f"Max association-ROI Z drift from projection ROI {search_help_suffix}",
+    )
+
+    parser.add_argument(
+        "--method",
+        choices=["ALPS-LAB", "ALPS-PAS", "Both"],
+        default="Both",
+        help="ALPS calculation method (default: Both)",
+    )
+
+    parser.add_argument(
+        "--fa-threshold",
+        type=float,
+        default=FA_THRESHOLD,
+        metavar="THRESHOLD",
+        help=f"FA threshold for filtering CSF voxels (default: {FA_THRESHOLD})",
+    )
+
+    return parser.parse_args()
+
+
+def _run_reanalysis() -> None:
+    """Run ROI reanalysis from command line arguments."""
+    args = _parse_reanalysis_args()
+
+    from .processing.constants import AdaptiveSearchConfig
+    from .processing.reanalysis import ROIShape, run_reanalysis
+
+    # Assemble the envelope from the (validated, defaulted) flags. The 1-4 guard
+    # already fired during parse; this construction cannot raise. Inert unless
+    # --adaptive is set.
+    search = AdaptiveSearchConfig(
+        search_x=args.search_x,
+        search_y=args.search_y,
+        search_z=args.search_z,
+        max_y_drift=args.max_y_drift,
+        max_z_drift=args.max_z_drift,
+    )
+
+    # Build list of ROI shapes from all specified flags
+    roi_shapes: list[ROIShape] = []
+    if args.sphere:
+        for radius in args.sphere:
+            roi_shapes.append(ROIShape(shape_type="sphere", sphere_radius=radius))
+    if args.squarev9:
+        roi_shapes.append(ROIShape(shape_type="squarev9"))
+    if args.squarev4:
+        roi_shapes.append(ROIShape(shape_type="squarev4"))
+
+    if not roi_shapes:
+        print(
+            "ERROR: At least one ROI shape must be specified (--sphere, --squarev9, or --squarev4)"
+        )
+        sys.exit(1)
+
+    # Run reanalysis for each shape
+    for roi_shape in roi_shapes:
+        if len(roi_shapes) > 1:
+            print(f"\n{'=' * 60}")
+            print(f"Reanalysis: {roi_shape.name}")
+            print(f"{'=' * 60}\n")
+
+        run_reanalysis(
+            output_dir=args.reanalyze,
+            roi_shape=roi_shape,
+            enable_adaptive=args.adaptive,
+            alps_method=args.method,
+            fa_threshold=args.fa_threshold,
+            search=search,
+        )
+
+
+def main():
+    """Main entry point that dispatches to GUI, viewer, report, or reanalysis."""
+    # Check for reanalysis mode first (needs argparse)
+    if len(sys.argv) >= 2 and sys.argv[1] == "--reanalyze":
+        _run_reanalysis()
+        return
+
+    # Check if viewer mode
+    if len(sys.argv) >= 2 and sys.argv[1] == "--viewer":
+        # Validate Qt up front so a missing PySide6 fails with a clear,
+        # actionable message instead of a raw import traceback (Decision 7).
+        from .gui import _check_viewer_dependencies
+
+        _check_viewer_dependencies()
+        from .gui.viewer import launch_viewer
+
+        # Check if output folder path was provided
+        output_folder = sys.argv[2] if len(sys.argv) > 2 else None
+        launch_viewer(output_folder)
+        return
+
+    # Check if report mode
+    if len(sys.argv) >= 2 and sys.argv[1] == "--report":
+        from .processing.report import run_report
+
+        if len(sys.argv) < 3:
+            print("ERROR: --report requires an output directory path")
+            print("Usage: python -m dti_alps --report /path/to/output")
+            sys.exit(1)
+
+        output_folder = sys.argv[2]
+        run_report(output_folder)
+        return
+
+    # Check for help on reanalysis
+    if len(sys.argv) >= 2 and sys.argv[1] in ["--help", "-h"]:
+        print(__doc__)
+        print("\nFor reanalysis options, use: python -m dti_alps --reanalyze --help")
+        return
+
+    # GUI mode: launched explicitly with --gui, or as the default with no args.
+    # Reject anything else rather than silently launching the GUI.
+    if len(sys.argv) >= 2 and sys.argv[1] != "--gui":
+        print(f"ERROR: unknown option '{sys.argv[1]}'")
+        print(__doc__)
+        sys.exit(2)
+
+    from .gui import main as gui_main
+
+    gui_main()
+
+
+if __name__ == "__main__":
+    main()

dti_alps-0.1.0/dti_alps/gui/__init__.py

@@ -0,0 +1,65 @@
+"""
+DTI-ALPS Processing GUI
+
+A PySide6 (Qt) graphical interface for end-to-end DTI-ALPS analysis.
+"""
+
+import sys
+
+
+def _check_science_deps():
+    """Check for the numpy/nibabel/scipy science stack (toolkit-independent).
+
+    Factored out of :func:`_check_dependencies` so the viewer entry point can
+    validate the science stack independently (PRD 0013, Decision 12).
+    """
+    import importlib.util
+
+    missing_packages = []
+    for pkg in ["nibabel", "numpy", "scipy"]:
+        if importlib.util.find_spec(pkg) is None:
+            missing_packages.append(pkg)
+
+    if missing_packages:
+        print(f"Error: Required packages not found: {', '.join(missing_packages)}")
+        print("Please install: pip install nibabel numpy scipy")
+        sys.exit(1)
+
+
+def _check_viewer_dependencies():
+    """Check for PySide6 (Qt), required by the whole GUI (main window + viewer).
+
+    Named for its original PRD 0010 role (Qt was first required only by the
+    viewer); since the PRD 0013 flip the main window is Qt too, so this is the
+    GUI-wide Qt check.
+    """
+    import importlib.util
+
+    if importlib.util.find_spec("PySide6") is None:
+        print("Error: PySide6 is required by the DTI-ALPS GUI but not installed.")
+        print('Please install: pip install "dti-alps[gui]"  (or: pip install PySide6)')
+        sys.exit(1)
+
+
+def _check_dependencies():
+    """Check for required GUI dependencies (PySide6 + the science stack)."""
+    _check_viewer_dependencies()
+    _check_science_deps()
+
+
+def main():
+    """Launch the DTI-ALPS GUI application."""
+    _check_dependencies()
+
+    from .app import launch_app
+
+    launch_app()
+
+
+def viewer(output_folder: str | None = None):
+    """Launch the DTI-ALPS Results Viewer."""
+    _check_dependencies()
+
+    from .viewer import launch_viewer
+
+    launch_viewer(output_folder)