dicompare 0.1.38__tar.gz

dicompare-0.1.38/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Ashley Stewart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dicompare-0.1.38/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: dicompare
+Version: 0.1.38
+Summary: A tool for checking DICOM compliance against a template
+Home-page: https://github.com/astewartau/dicompare
+Author: Ashley Stewart
+Keywords: DICOM compliance validation medical imaging
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydicom==2.4.4
+Requires-Dist: pandas
+Requires-Dist: tabulate
+Requires-Dist: scipy
+Requires-Dist: tqdm
+Requires-Dist: nibabel
+Requires-Dist: twixtools
+Provides-Extra: interactive
+Requires-Dist: curses; extra == "interactive"
+Provides-Extra: test
+Requires-Dist: pytest-asyncio; extra == "test"
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# dicompare
+
+[![](img/button.png)](https://dicompare-web.vercel.app/)
+
+dicompare is a DICOM validation tool designed to ensure compliance with study-specific imaging protocols and domain-specific guidelines while preserving data privacy. It provides multiple interfaces, including support for validation directly in the browser at [dicompare-web.vercel.app](https://dicompare-web.vercel.app/), leveraging WebAssembly (WASM), Pyodide, and the underlying pip package `dicompare`. dicompare is suitable for multi-site studies and clinical environments without requiring software installation or external data uploads.
+
+dicompare supports DICOM session validation against templates based on:
+
+- **Reference sessions**: JSON schema files can be generated based on a reference MRI scanning session;
+- **[TESTING] domain guidelines**: Flexible guidelines for specific domains (currently [QSM](https://doi.org/10.1002/mrm.30006));
+- **[FUTURE] landmark studies**: Schema files based on landmark studies such as the [HCP](https://doi.org/10.1038/s41586-018-0579-z), [ABCD](https://doi.org/10.1016/j.dcn.2018.03.001), and [UK BioBank](https://doi.org/10.1038/s41586-018-0579-z) projects.
+
+# Command-line interface (CLI) and application programming interface (API)
+
+While you can run [dicompare](https://dicompare-web.vercel.app/) in your browser now without any installation, you may also use the underlying `dicompare` pip package if you wish to use the command-line interface (CLI) or application programming interface (API).
+
+```bash
+pip install dicompare
+```
+
+## Command-line interface (CLI)
+
+The package provides a unified `dicompare` command with two subcommands:
+
+- **`dicompare build`**: Generate a JSON schema from a reference DICOM session
+- **`dicompare check`**: Validate DICOM sessions against a JSON schema
+
+### 1. Build a JSON schema from a reference session
+
+```bash
+dicompare build /path/to/dicom/session schema.json
+```
+
+This creates a JSON schema describing the session based on default reference fields present in the data.
+
+### 2. Check a DICOM session against a schema
+
+```bash
+dicompare check /path/to/dicom/session schema.json
+```
+
+The tool will output a compliance summary, indicating deviations from the schema.
+
+### 3. Check with report output
+
+```bash
+dicompare check /path/to/dicom/session schema.json compliance_report.json
+```
+
+This saves the compliance report to a JSON file.
+
+### 4. Automatic acquisition mapping
+
+```bash
+dicompare check /path/to/dicom/session schema.json --auto-yes
+```
+
+Use `--auto-yes` or `-y` to automatically map acquisitions without interactive prompts.
+
+## Python API
+
+The `dicompare` package provides a comprehensive Python API for programmatic schema generation, validation, and DICOM processing.
+
+### Loading DICOM data
+
+**Load a DICOM session:**
+
+```python
+from dicompare import load_dicom_session
+
+session_df = load_dicom_session(
+    session_dir="/path/to/dicom/session",
+    show_progress=True
+)
+```
+
+**Load individual DICOM files:**
+
+```python
+from dicompare import load_dicom
+
+dicom_data = load_dicom(
+    dicom_paths=["/path/to/file1.dcm", "/path/to/file2.dcm"],
+    show_progress=True
+)
+```
+
+**Load Siemens .pro files:**
+
+```python
+from dicompare import load_pro_session
+
+pro_session = load_pro_session(
+    session_dir="/path/to/pro/files",
+    show_progress=True
+)
+```
+
+### Build a JSON schema
+
+```python
+from dicompare import load_dicom_session, build_schema, make_json_serializable
+from dicompare.config import DEFAULT_SETTINGS_FIELDS
+import json
+
+# Load the reference session
+session_df = load_dicom_session(
+    session_dir="/path/to/dicom/session",
+    show_progress=True
+)
+
+# Build the schema
+json_schema = build_schema(session_df)
+
+# Save the schema
+serializable_schema = make_json_serializable(json_schema)
+with open("schema.json", "w") as f:
+    json.dump(serializable_schema, f, indent=4)
+```
+
+### Validate a session against a JSON schema
+
+```python
+from dicompare import (
+    load_schema,
+    load_dicom_session,
+    check_acquisition_compliance,
+    map_to_json_reference,
+    assign_acquisition_and_run_numbers
+)
+
+# Load the JSON schema
+reference_fields, json_schema, validation_rules = load_schema(json_schema_path="schema.json")
+
+# Load the input session
+in_session = load_dicom_session(
+    session_dir="/path/to/dicom/session",
+    show_progress=True
+)
+
+# Assign acquisition and run numbers
+in_session = assign_acquisition_and_run_numbers(in_session)
+
+# Map acquisitions to schema
+session_map = map_to_json_reference(in_session, json_schema)
+
+# Check compliance for each acquisition
+compliance_summary = []
+for ref_acq_name, schema_acq in json_schema["acquisitions"].items():
+    if ref_acq_name not in session_map:
+        continue
+
+    input_acq_name = session_map[ref_acq_name]
+    acq_validation_rules = validation_rules.get(ref_acq_name) if validation_rules else None
+
+    results = check_acquisition_compliance(
+        in_session,
+        schema_acq,
+        acquisition_name=input_acq_name,
+        validation_rules=acq_validation_rules
+    )
+    compliance_summary.extend(results)
+
+# Display results
+for entry in compliance_summary:
+    print(entry)
+```
+
+### Additional utilities
+
+**Assign acquisition and run numbers:**
+
+```python
+from dicompare import assign_acquisition_and_run_numbers
+
+session_df = assign_acquisition_and_run_numbers(session_df)
+```
+
+**Get DICOM tag information:**
+
+```python
+from dicompare import get_tag_info, get_all_tags_in_dataset
+
+# Get info about a specific tag
+tag_info = get_tag_info("EchoTime")
+print(tag_info)  # {'tag': '(0018,0081)', 'name': 'Echo Time', 'type': 'float'}
+
+# Get all tags in a dataset
+all_tags = get_all_tags_in_dataset(dicom_metadata)
+```
+

dicompare-0.1.38/README.md

@@ -0,0 +1,191 @@
+# dicompare
+
+[![](img/button.png)](https://dicompare-web.vercel.app/)
+
+dicompare is a DICOM validation tool designed to ensure compliance with study-specific imaging protocols and domain-specific guidelines while preserving data privacy. It provides multiple interfaces, including support for validation directly in the browser at [dicompare-web.vercel.app](https://dicompare-web.vercel.app/), leveraging WebAssembly (WASM), Pyodide, and the underlying pip package `dicompare`. dicompare is suitable for multi-site studies and clinical environments without requiring software installation or external data uploads.
+
+dicompare supports DICOM session validation against templates based on:
+
+- **Reference sessions**: JSON schema files can be generated based on a reference MRI scanning session;
+- **[TESTING] domain guidelines**: Flexible guidelines for specific domains (currently [QSM](https://doi.org/10.1002/mrm.30006));
+- **[FUTURE] landmark studies**: Schema files based on landmark studies such as the [HCP](https://doi.org/10.1038/s41586-018-0579-z), [ABCD](https://doi.org/10.1016/j.dcn.2018.03.001), and [UK BioBank](https://doi.org/10.1038/s41586-018-0579-z) projects.
+
+# Command-line interface (CLI) and application programming interface (API)
+
+While you can run [dicompare](https://dicompare-web.vercel.app/) in your browser now without any installation, you may also use the underlying `dicompare` pip package if you wish to use the command-line interface (CLI) or application programming interface (API).
+
+```bash
+pip install dicompare
+```
+
+## Command-line interface (CLI)
+
+The package provides a unified `dicompare` command with two subcommands:
+
+- **`dicompare build`**: Generate a JSON schema from a reference DICOM session
+- **`dicompare check`**: Validate DICOM sessions against a JSON schema
+
+### 1. Build a JSON schema from a reference session
+
+```bash
+dicompare build /path/to/dicom/session schema.json
+```
+
+This creates a JSON schema describing the session based on default reference fields present in the data.
+
+### 2. Check a DICOM session against a schema
+
+```bash
+dicompare check /path/to/dicom/session schema.json
+```
+
+The tool will output a compliance summary, indicating deviations from the schema.
+
+### 3. Check with report output
+
+```bash
+dicompare check /path/to/dicom/session schema.json compliance_report.json
+```
+
+This saves the compliance report to a JSON file.
+
+### 4. Automatic acquisition mapping
+
+```bash
+dicompare check /path/to/dicom/session schema.json --auto-yes
+```
+
+Use `--auto-yes` or `-y` to automatically map acquisitions without interactive prompts.
+
+## Python API
+
+The `dicompare` package provides a comprehensive Python API for programmatic schema generation, validation, and DICOM processing.
+
+### Loading DICOM data
+
+**Load a DICOM session:**
+
+```python
+from dicompare import load_dicom_session
+
+session_df = load_dicom_session(
+    session_dir="/path/to/dicom/session",
+    show_progress=True
+)
+```
+
+**Load individual DICOM files:**
+
+```python
+from dicompare import load_dicom
+
+dicom_data = load_dicom(
+    dicom_paths=["/path/to/file1.dcm", "/path/to/file2.dcm"],
+    show_progress=True
+)
+```
+
+**Load Siemens .pro files:**
+
+```python
+from dicompare import load_pro_session
+
+pro_session = load_pro_session(
+    session_dir="/path/to/pro/files",
+    show_progress=True
+)
+```
+
+### Build a JSON schema
+
+```python
+from dicompare import load_dicom_session, build_schema, make_json_serializable
+from dicompare.config import DEFAULT_SETTINGS_FIELDS
+import json
+
+# Load the reference session
+session_df = load_dicom_session(
+    session_dir="/path/to/dicom/session",
+    show_progress=True
+)
+
+# Build the schema
+json_schema = build_schema(session_df)
+
+# Save the schema
+serializable_schema = make_json_serializable(json_schema)
+with open("schema.json", "w") as f:
+    json.dump(serializable_schema, f, indent=4)
+```
+
+### Validate a session against a JSON schema
+
+```python
+from dicompare import (
+    load_schema,
+    load_dicom_session,
+    check_acquisition_compliance,
+    map_to_json_reference,
+    assign_acquisition_and_run_numbers
+)
+
+# Load the JSON schema
+reference_fields, json_schema, validation_rules = load_schema(json_schema_path="schema.json")
+
+# Load the input session
+in_session = load_dicom_session(
+    session_dir="/path/to/dicom/session",
+    show_progress=True
+)
+
+# Assign acquisition and run numbers
+in_session = assign_acquisition_and_run_numbers(in_session)
+
+# Map acquisitions to schema
+session_map = map_to_json_reference(in_session, json_schema)
+
+# Check compliance for each acquisition
+compliance_summary = []
+for ref_acq_name, schema_acq in json_schema["acquisitions"].items():
+    if ref_acq_name not in session_map:
+        continue
+
+    input_acq_name = session_map[ref_acq_name]
+    acq_validation_rules = validation_rules.get(ref_acq_name) if validation_rules else None
+
+    results = check_acquisition_compliance(
+        in_session,
+        schema_acq,
+        acquisition_name=input_acq_name,
+        validation_rules=acq_validation_rules
+    )
+    compliance_summary.extend(results)
+
+# Display results
+for entry in compliance_summary:
+    print(entry)
+```
+
+### Additional utilities
+
+**Assign acquisition and run numbers:**
+
+```python
+from dicompare import assign_acquisition_and_run_numbers
+
+session_df = assign_acquisition_and_run_numbers(session_df)
+```
+
+**Get DICOM tag information:**
+
+```python
+from dicompare import get_tag_info, get_all_tags_in_dataset
+
+# Get info about a specific tag
+tag_info = get_tag_info("EchoTime")
+print(tag_info)  # {'tag': '(0018,0081)', 'name': 'Echo Time', 'type': 'float'}
+
+# Get all tags in a dataset
+all_tags = get_all_tags_in_dataset(dicom_metadata)
+```
+

dicompare-0.1.38/dicompare/__init__.py

@@ -0,0 +1,18 @@
+__version__ = "0.1.38"
+
+# Import core functionalities
+from .io import get_dicom_values, load_dicom, load_schema, load_dicom_session, async_load_dicom_session, load_nifti_session, load_pro_file, load_pro_session, generate_test_dicoms_from_schema, generate_test_dicoms_from_schema_json, load_pro_file_schema_format
+from .validation import check_acquisition_compliance
+from .session import assign_acquisition_and_run_numbers
+from .session import map_to_json_reference, interactive_mapping_to_json_reference
+from .validation import BaseValidationModel, ValidationError, ValidationWarning, validator, safe_exec_rule, create_validation_model_from_rules, create_validation_models_from_rules
+from .config import DEFAULT_SETTINGS_FIELDS, DEFAULT_ACQUISITION_FIELDS, DEFAULT_DICOM_FIELDS
+from .schema import get_tag_info, get_all_tags_in_dataset
+
+# Import enhanced functionality for web interfaces
+from .schema import build_schema
+from .io import make_json_serializable
+from .utils import detect_constant_fields, clean_string, make_hashable
+from .interface import (
+    analyze_dicom_files_for_web,
+)

dicompare-0.1.38/dicompare/cli/main.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python
+
+import sys
+import json
+import argparse
+import logging
+import pandas as pd
+
+from dicompare.io import load_dicom_session, load_schema
+from dicompare.io.json import make_json_serializable
+from dicompare.schema import build_schema
+from dicompare.validation import check_acquisition_compliance
+from dicompare.validation.helpers import ComplianceStatus, create_compliance_record
+from dicompare.session import map_to_json_reference, interactive_mapping_to_json_reference, assign_acquisition_and_run_numbers
+
+# Set up logging
+logging.basicConfig(level=logging.INFO, format='%(levelname)s: %(message)s')
+logger = logging.getLogger(__name__)
+
+
+def build_command(args) -> None:
+    """Generate a JSON schema from a DICOM session."""
+    # Read DICOM session
+    session_data = load_dicom_session(
+        session_dir=args.dicoms,
+        show_progress=True
+    )
+
+    # Generate JSON schema
+    json_schema = build_schema(session_df=session_data)
+
+    # Write JSON to output file
+    serializable_schema = make_json_serializable(json_schema)
+    with open(args.schema, "w") as f:
+        json.dump(serializable_schema, f, indent=4)
+    logger.info(f"JSON schema saved to {args.schema}")
+
+
+def check_command(args) -> None:
+    """Check a DICOM session against a schema for compliance."""
+    # Load the schema
+    reference_fields, json_schema, validation_rules = load_schema(json_schema_path=args.schema)
+
+    # Load the input session
+    in_session = load_dicom_session(
+        session_dir=args.dicoms,
+    )
+
+    # Assign acquisition and series using canonical process
+    in_session = assign_acquisition_and_run_numbers(in_session)
+
+    # Map and perform compliance check
+    session_map = map_to_json_reference(in_session, json_schema)
+    if not args.auto_yes and sys.stdin.isatty():
+        session_map = interactive_mapping_to_json_reference(in_session, json_schema, initial_mapping=session_map)
+
+    # Check compliance for each acquisition
+    compliance_summary = []
+    for ref_acq_name, schema_acq in json_schema["acquisitions"].items():
+        if ref_acq_name not in session_map:
+            compliance_summary.append(create_compliance_record(
+                field="Acquisition Mapping",
+                message=f"Reference acquisition '{ref_acq_name}' is not mapped to any input acquisition.",
+                status=ComplianceStatus.ERROR,
+                expected=f"Acquisition '{ref_acq_name}' to be mapped"
+            ))
+            continue
+
+        input_acq_name = session_map[ref_acq_name]
+        acq_validation_rules = validation_rules.get(ref_acq_name) if validation_rules else None
+        results = check_acquisition_compliance(
+            in_session,
+            schema_acq,
+            acquisition_name=input_acq_name,
+            validation_rules=acq_validation_rules
+        )
+        compliance_summary.extend(results)
+    compliance_df = pd.DataFrame(compliance_summary)
+
+    # If compliance_df is empty, log message and exit
+    if compliance_df.empty:
+        logger.info("Session is fully compliant with the schema model.")
+        return
+
+    # Inline summary output
+    for entry in compliance_summary:
+        if entry.get('input acquisition'):
+            acq_text = f"Acquisition: {entry.get('input acquisition')}"
+            if entry.get('reference acquisition'):
+                acq_text += f" ({entry.get('reference acquisition')})"
+            logger.info(acq_text)
+        # Handle 'field' (single) or derive from 'expected' keys
+        if entry.get('field'):
+            logger.info(f"Field: {entry.get('field')}")
+        elif entry.get('expected') and isinstance(entry.get('expected'), dict):
+            logger.info(f"Fields: {list(entry.get('expected').keys())}")
+        if entry.get('series'): logger.info(f"Series: {entry.get('series')}")
+        if entry.get('expected') is not None: logger.info(f"Expected: {entry.get('expected')}")
+        if entry.get('value') is not None: logger.info(f"Value: {entry.get('value')}")
+        if entry.get('message'): logger.info(f"Message: {entry.get('message')}")
+        logger.info("-" * 40)
+
+    # Save compliance summary to JSON
+    if args.report:
+        with open(args.report, "w") as f:
+            json.dump(compliance_summary, f, indent=4)
+        logger.info(f"Compliance report saved to {args.report}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="DICOM compliance validation tool",
+        prog="dicompare"
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # Build subcommand
+    build_parser = subparsers.add_parser(
+        "build",
+        help="Build a JSON schema from a DICOM session"
+    )
+    build_parser.add_argument(
+        "dicoms",
+        nargs="?",
+        help="Directory containing DICOM files"
+    )
+    build_parser.add_argument(
+        "schema",
+        nargs="?",
+        help="Output path for the JSON schema"
+    )
+    build_parser.add_argument(
+        "--dicoms",
+        dest="dicoms_named",
+        metavar="PATH",
+        help="Directory containing DICOM files"
+    )
+    build_parser.add_argument(
+        "--schema",
+        dest="schema_named",
+        metavar="PATH",
+        help="Output path for the JSON schema"
+    )
+    build_parser.add_argument(
+        "--name-template",
+        default="{ProtocolName}",
+        help="Naming template for acquisitions (default: {ProtocolName})"
+    )
+
+    # Check subcommand
+    check_parser = subparsers.add_parser(
+        "check",
+        help="Check a DICOM session against a schema"
+    )
+    check_parser.add_argument(
+        "dicoms",
+        nargs="?",
+        help="Directory containing DICOM files to check"
+    )
+    check_parser.add_argument(
+        "schema",
+        nargs="?",
+        help="Path to the JSON schema file"
+    )
+    check_parser.add_argument(
+        "report",
+        nargs="?",
+        help="Output path for the compliance report"
+    )
+    check_parser.add_argument(
+        "--dicoms",
+        dest="dicoms_named",
+        metavar="PATH",
+        help="Directory containing DICOM files to check"
+    )
+    check_parser.add_argument(
+        "--schema",
+        dest="schema_named",
+        metavar="PATH",
+        help="Path to the JSON schema file"
+    )
+    check_parser.add_argument(
+        "--report",
+        dest="report_named",
+        metavar="PATH",
+        help="Output path for the compliance report"
+    )
+    check_parser.add_argument(
+        "--auto-yes", "-y",
+        action="store_true",
+        help="Automatically map acquisitions without prompting"
+    )
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    # Resolve positional vs named arguments
+    if args.command == "build":
+        args.dicoms = args.dicoms or args.dicoms_named
+        args.schema = args.schema or args.schema_named
+
+        if not args.dicoms or not args.schema:
+            build_parser.error("the following arguments are required: dicoms, schema")
+
+        build_command(args)
+
+    elif args.command == "check":
+        args.dicoms = args.dicoms or args.dicoms_named
+        args.schema = args.schema or args.schema_named
+        args.report = args.report or args.report_named
+
+        if not args.dicoms or not args.schema:
+            check_parser.error("the following arguments are required: dicoms, schema")
+
+        check_command(args)
+
+
+if __name__ == "__main__":
+    main()