xnattools 1.0.0__py3-none-any.whl

xnattools/__init__.py

@@ -0,0 +1,17 @@
+from importlib.metadata import version
+from xnattools.core import run_tools
+from xnattools.dataclasses.core import GeneralSettings
+from xnattools.dataclasses.datmat import DatMatSettings
+from xnattools.dataclasses.dcm2nifti import Dcm2niftiSettings
+from xnattools.dataclasses.dcm2snapshots import Dcm2snapshotsSettings
+from xnattools.dataclasses.scanmetadata import ScanMetaDataSettings
+
+__version__ = version("xnattools")
+__all__ = [
+    "DatMatSettings",
+    "Dcm2niftiSettings",
+    "Dcm2snapshotsSettings",
+    "GeneralSettings",
+    "ScanMetaDataSettings",
+    "run_tools",
+]

xnattools/cli.py

@@ -0,0 +1,328 @@
+"""Command-line interface for XNAT Tools.
+
+This module provides a CLI parser for running XNAT tools via command line.
+"""
+
+import argparse
+import json
+import logging
+import sys
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version
+from pathlib import Path
+from typing import Any
+import xnattools as xt
+
+try:
+    import tomllib
+except ImportError:
+    try:
+        import tomli as tomllib  # type: ignore[import-not-found,no-redef]
+    except ImportError:
+        tomllib = None  # type: ignore[assignment]
+
+from xnattools.logger_config import get_logger
+
+logger = get_logger(__name__)
+
+
+def get_version() -> str:
+    """Get the version of xnattools.
+
+    First tries to get it from installed package metadata.
+    If not installed (e.g., running from source), reads from pyproject.toml.
+
+    Returns:
+        Version string (e.g., "0.1.0")
+    """
+    try:
+        return version("xnattools")
+    except PackageNotFoundError:
+        if tomllib is None:
+            return "unknown"
+        try:
+            pyproject_path = Path(__file__).parent.parent / "pyproject.toml"
+            if pyproject_path.exists():
+                with pyproject_path.open("rb") as f:
+                    pyproject_data = tomllib.load(f)
+                    return pyproject_data.get("project", {}).get("version", "unknown")
+        except (OSError, KeyError, AttributeError):
+            logger.exception("Exception occurred while reading version from pyproject.toml")
+
+        return "unknown"
+
+
+def parse_scans_argument(scans_input: str) -> list[str] | dict[str, list[str | int]]:
+    """Parses the scan arguments.
+
+    Parse the scans argument which can be:
+    - A comma-separated list of experiment IDs: "exp1,exp2,exp3"
+    - A JSON string mapping experiments to scan IDs: '{"exp1": [1,2], "exp2": ["3","4"]}'
+
+    Args:
+        scans_input: String input from command line
+
+    Returns:
+        Either a list of experiment IDs or a dictionary mapping experiments to scan IDs
+    """
+    # Try to parse as JSON first
+    if scans_input.startswith(("{", "[")):
+        try:
+            scans_data = json.loads(scans_input)
+            # If it's a list, it's invalid - we only accept dict or comma-separated strings
+            if isinstance(scans_data, list):
+                msg = (
+                    "JSON arrays are not supported. Use comma-separated experiment IDs "
+                    "(e.g., 'EXP1,EXP2') or a JSON dictionary mapping experiments to scan IDs "
+                    '(e.g., \'{"EXP1": [1,2], "EXP2": [3]}\')'
+                )
+                raise TypeError(msg)
+
+            # Validate dictionary structure
+            if not isinstance(scans_data, dict):
+                msg = "JSON must be a dictionary"
+                raise TypeError(msg)
+            for key, value in scans_data.items():
+                if not isinstance(key, str):
+                    msg = f"Experiment ID '{key}' must be a string"
+                    raise TypeError(msg)
+                if not isinstance(value, list):
+                    msg = f"Scan IDs for '{key}' must be a list"
+                    raise TypeError(msg)
+        except json.JSONDecodeError as e:
+            msg = f"Invalid JSON format for scans: {e}"
+            raise ValueError(msg) from e
+        return scans_data
+    # Parse as comma-separated list
+    experiment_list = [s.strip() for s in scans_input.split(",") if s.strip()]
+
+    # Validate that the result doesn't look like malformed JSON
+    for exp_id in experiment_list:
+        if exp_id.startswith(("{", "[", '"')):
+            msg = (
+                f"Invalid experiment ID '{exp_id}'. "
+                "Experiment IDs should be simple strings separated by commas, "
+                "not JSON syntax. Use proper JSON format if you need to specify scan IDs."
+            )
+            raise ValueError(msg)
+
+    return experiment_list
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create and configure the argument parser for XNAT Tools CLI."""
+    parser = argparse.ArgumentParser(
+        description="xnattools - Python scripts for handy operations on XNAT data",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Run dcm2nifti on entire project
+  %(prog)s dcm2nifti https://xnat.example.com PROJECT_ID
+
+  # Run with custom output directory
+  %(prog)s dcm2nii https://xnat.example.com PROJECT_ID --output-dir /custom/output/dir
+
+  # Run multiple tools on specific subjects
+  %(prog)s dcm2nifti dcm2snapshots https://xnat.example.com PROJECT_ID --subjects SUB001 SUB002
+
+  # Run on specific experiments (as list)
+  %(prog)s scanmetadata https://xnat.example.com PROJECT_ID --scans EXP001,EXP002
+
+  # Run on specific scans within experiments (as JSON mapping)
+  %(prog)s dcm2nifti https://xnat.example.com PROJECT_ID --scans '{"EXP001": [1, 2, 3], "EXP002": [1]}'
+
+  # With additional options
+  %(prog)s dcm2nifti https://xnat.example.com PROJECT_ID --tempdir /custom/tmp --overwrite --subjects SUB001
+
+  # Run dcm2nifti and scanmetadata with independent options
+  %(prog)s dcm2nifti scanmetadata https://xnat.example.com MY_PROJECT \\
+      --dcm2nifti-overwrite --dcm2nifti-use-dicom-series-description \\
+      --scanmetadata-output-location ./meta.csv --scanmetadata-headtype CT
+""",
+    )
+
+    # Positional arguments
+    parser.add_argument(
+        "tools",
+        nargs="+",
+        choices=["dcm2nifti", "dcm2snapshots", "scanmetadata", "datmat"],
+        help="XNAT tools to run (can specify multiple)",
+    )
+    # general settings - mandatory
+    parser.add_argument("system_url", type=str, help="URL of the XNAT instance (e.g., https://xnat.example.com)")
+    parser.add_argument("project_id", type=str, help="XNAT project ID to process")
+
+    # general settings - Optional arguments - Filtering
+    filter_group = parser.add_argument_group("Filtering options")
+    filter_group.add_argument(
+        "--subjects",
+        nargs="+",
+        metavar="SUBJECT_ID",
+        help="List of subject IDs to process (space-separated). If omitted, all subjects.",
+    )
+    filter_group.add_argument(
+        "--scans",
+        type=str,
+        metavar="SCANS",
+        help="Experiments/scans to process. Can be: "
+        '(1) Comma-separated experiment IDs: "EXP1,EXP2" '
+        '(2) JSON mapping experiments to scan IDs: \'{"EXP1": [1,2], "EXP2": [3]}\'',
+    )
+
+    # general settings - Optional arguments - General
+    general_group = parser.add_argument_group("General options")
+    general_group.add_argument(
+        "--output-dir", type=Path, default=Path.cwd(), help="Output directory (default: current directory)"
+    )
+    general_group.add_argument("-v", "--verbose", action="store_true", help="Enable verbose logging")
+    general_group.add_argument("--version", action="version", version=f"%(prog)s {get_version()}")
+
+    # Tool-specific options
+    dcm2nifti_group = parser.add_argument_group("dcm2nifti options")
+    dcm2nifti_group.add_argument(
+        "--dcm2nifti-overwrite", action="store_true", help="Overwrite existing files locally and on XNAT"
+    )
+    dcm2nifti_group.add_argument(
+        "--dcm2nifti-allow-multiple-niftis", action="store_true", help="Allow multiple nifti files per series"
+    )
+    dcm2nifti_group.add_argument("--dcm2nifti-make-3d-niftis", action="store_true", help="Create 3D nifti files")
+    dcm2nifti_group.add_argument("--dcm2nifti-rename-temporal", action="store_true", help="Rename temporal series")
+    dcm2nifti_group.add_argument("--dcm2nifti-rename-dwi", action="store_true", help="Rename DWI series")
+    dcm2nifti_group.add_argument(
+        "--dcm2nifti-use-dicom-series-description",
+        action="store_true",
+        help="Use DICOM series description for descrip field in nifti",
+    )
+
+    dcm2snapshots_group = parser.add_argument_group("dcm2snapshots options")
+    dcm2snapshots_group.add_argument(
+        "--dcm2snapshots-overwrite", action="store_true", help="Overwrite existing snapshots"
+    )
+    dcm2snapshots_group.add_argument(
+        "--dcm2snapshots-snapshot-size", action="store_true", help="Size of the snapshot (used as width and height)"
+    )
+
+    scanmetadata_group = parser.add_argument_group("scanmetadata options")
+    scanmetadata_group.add_argument(
+        "--scanmetadata-output-location", type=Path, help="Output CSV location (default: output-dir/metadata.csv)"
+    )
+    scanmetadata_group.add_argument(
+        "--scanmetadata-headtype", default="MR", help="Type of scan to process, compared to DICOM Tag (0008,0060)"
+    )
+    scanmetadata_group.add_argument(
+        "--scanmetadata-t1-repetition-time", default=300, type=int, help="Repetition time to standardize T1 scans"
+    )
+    scanmetadata_group.add_argument(
+        "--scanmetadata-t2-echo-time", default=10, type=int, help="Echo time to standardize T2 scans"
+    )
+    scanmetadata_group.add_argument(
+        "--scanmetadata-process-tag-value", action="store_true", help="Process tag values in metadata"
+    )
+
+    datmat_group = parser.add_argument_group("datmat options")
+    datmat_group.add_argument(
+        "--datmat-output-location", help="Directory where downloaded files will be saved, can be local or remote"
+    )
+    datmat_group.add_argument("--datmat-file-types", default="DICOM", help="Type of file to download from XNAT")
+    datmat_group.add_argument(
+        "--datmat-output-folder-structure", nargs="+", help="Folder hierarchy for organizing downloads."
+    )
+    datmat_group.add_argument(
+        "--datmat-pseudo-anonymize", action="store_true", help="Hash folder names for pseudo-anonymization."
+    )
+
+    return parser
+
+
+def _build_general_settings(args: argparse.Namespace) -> xt.GeneralSettings:
+    """Construct GeneralSettings from shared arguments."""
+    subjects = list(args.subjects) if args.subjects else None
+    scans = None
+    if args.scans:
+        scans = parse_scans_argument(args.scans)
+    return xt.GeneralSettings(
+        system_url=args.system_url,
+        project_id=args.project_id,
+        subjects=subjects,
+        scans=scans,
+        output_dir=args.output_dir,
+    )
+
+
+def _build_tool_settings(args: argparse.Namespace, tools: list[str]) -> list[Any]:
+    """Instantiate tool-specific settings for each requested tool."""
+    tools_to_run = []
+
+    for tool in tools:
+        if tool == "dcm2nifti":
+            settings = xt.Dcm2niftiSettings(
+                overwrite=args.dcm2nifti_overwrite,
+                allow_multiple_niftis=args.dcm2nifti_allow_multiple_niftis,
+                make_3d_niftis=args.dcm2nifti_make_3d_niftis,
+                rename_temporal=args.dcm2nifti_rename_temporal,
+                rename_dwi=args.dcm2nifti_rename_dwi,
+                use_dicom_series_description=args.dcm2nifti_use_dicom_series_description,
+            )
+            tools_to_run.append(settings)
+
+        elif tool == "dcm2snapshots":
+            settings = xt.Dcm2snapshotsSettings(
+                overwrite=args.dcm2snapshots_overwrite,
+            )
+            tools_to_run.append(settings)
+
+        elif tool == "scanmetadata":
+            settings = xt.ScanMetaDataSettings(
+                output_location=args.scanmetadata_output_location,
+                headtype=args.scanmetadata_headtype,
+                t1_repetition_time=args.scanmetadata_t1_repetition_time,
+                t2_echo_time=args.scanmetadata_t2_echo_time,
+                process_tag_value=args.scanmetadata_process_tag_value,
+            )
+            tools_to_run.append(settings)
+
+        elif tool == "datmat":
+            settings = xt.DatMatSettings(
+                output_location=args.datmat_output_location,
+                file_types=args.datmat_file_types,
+                output_folder_structure=args.datmat_output_folder_structure,
+                pseudo_anonymize=args.datmat_pseudo_anonymize,
+            )
+            tools_to_run.append(settings)
+
+        else:
+            msg = f"Unknown tool: {tool}"
+            raise ValueError(msg)
+
+    return tools_to_run
+
+
+def main() -> int:
+    """Main entry point for the CLI.
+
+    Returns:
+        True if run was successfull, False otherwise
+    """
+    parser = create_parser()
+    args = parser.parse_args()
+
+    # Configure logging based on verbosity
+    if args.verbose:
+        logging.basicConfig(level=logging.DEBUG)
+        logger.setLevel(logging.DEBUG)  # TODO: fix levels later
+
+    # Run the tools
+    try:
+        general = _build_general_settings(args)
+        tool_settings = _build_tool_settings(args, args.tools)
+        xt.run_tools(tools_to_run=tool_settings, general_settings=general)
+    except Exception:
+        logger.exception("Error during execution.")
+        return 1
+
+    logger.info("Successfully completed tools: %s", ", ".join(args.tools))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())