dicompare 0.1.8__tar.gz

dicompare-0.1.8/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.8/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.1
+Name: dicompare
+Version: 0.1.8
+Summary: A tool for checking DICOM compliance against a reference model using Pydantic
+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.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydicom==3.0.1
+Requires-Dist: pandas
+Requires-Dist: tabulate
+Requires-Dist: scipy
+Provides-Extra: interactive
+Requires-Dist: curses; extra == "interactive"
+
+# dicompare
+
+[![](img/button.png)](https://astewartau.github.io/dicompare/)
+
+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, leveraging WebAssembly (WASM), Pyodide, and the underlying pip package [`dicompare`](#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:
+
+- **Session schemas**: JSON schema files that can be generated based on a reference session;
+- **[UNDER CONSTRUCTION] 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;
+- **[UNDER CONSTRUCTION] domain guidelines**: Flexible guidelines for domains such as [QSM](https://doi.org/10.1002/mrm.30006).
+
+# Command-line interface (CLI) and application programming interface (API)
+
+While you can run [dicompare](https://astewartau.github.io/dicompare/) 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 the following CLI entry points:
+
+- `dcm-gen-session`: Generate JSON schemas for DICOM validation.
+- `dcm-check-session`: Validate DICOM sessions against predefined schemas.
+
+1. Generate a JSON Reference Schema
+
+```bash
+dcm-gen-session \
+    --in_session_dir /path/to/dicom/session \
+    --out_json_ref schema.json \
+    --acquisition_fields ProtocolName SeriesDescription \
+    --reference_fields EchoTime RepetitionTime
+```
+
+This will create a JSON schema describing the session based on the specified fields.
+
+2. Validate a DICOM Session
+
+```bash
+dicompare-session \
+    --in_session /path/to/dicom/session \
+    --json_ref schema.json \
+    --out_json compliance_report.json
+```
+
+The tool will output a compliance summary, indicating deviations from the reference schema.
+
+## Python API
+
+The `dicompare` package provides a Python API for programmatic schema generation and validation.
+
+**Generate a schema:**
+
+```python
+from dicompare.io import read_dicom_session
+
+reference_fields = ["EchoTime", "RepetitionTime"]
+acquisition_fields = ["ProtocolName", "SeriesDescription"]
+
+session_data = read_dicom_session(
+    session_dir="/path/to/dicom/session",
+    acquisition_fields=acquisition_fields,
+    reference_fields=reference_fields
+)
+
+# Save the schema as JSON
+import json
+with open("schema.json", "w") as f:
+    json.dump(session_data, f, indent=4)
+```
+
+**Validate a session:**
+
+```python
+from dicompare.io import read_json_session, read_dicom_session
+from dicompare.compliance import check_session_compliance
+
+# Load the schema
+acquisition_fields, reference_fields, ref_session = read_json_session(json_ref="schema.json")
+
+# Read the input session
+in_session = read_dicom_session(
+    session_dir="/path/to/dicom/session",
+    acquisition_fields=acquisition_fields,
+    reference_fields=reference_fields
+)
+
+# Perform compliance check
+compliance_summary = check_session_compliance(
+    in_session=in_session,
+    ref_session=ref_session,
+    series_map=None  # Optional: map series if needed
+)
+
+# Print compliance summary
+for entry in compliance_summary:
+    print(entry)
+```
+

dicompare-0.1.8/README.md

@@ -0,0 +1,102 @@
+# dicompare
+
+[![](img/button.png)](https://astewartau.github.io/dicompare/)
+
+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, leveraging WebAssembly (WASM), Pyodide, and the underlying pip package [`dicompare`](#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:
+
+- **Session schemas**: JSON schema files that can be generated based on a reference session;
+- **[UNDER CONSTRUCTION] 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;
+- **[UNDER CONSTRUCTION] domain guidelines**: Flexible guidelines for domains such as [QSM](https://doi.org/10.1002/mrm.30006).
+
+# Command-line interface (CLI) and application programming interface (API)
+
+While you can run [dicompare](https://astewartau.github.io/dicompare/) 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 the following CLI entry points:
+
+- `dcm-gen-session`: Generate JSON schemas for DICOM validation.
+- `dcm-check-session`: Validate DICOM sessions against predefined schemas.
+
+1. Generate a JSON Reference Schema
+
+```bash
+dcm-gen-session \
+    --in_session_dir /path/to/dicom/session \
+    --out_json_ref schema.json \
+    --acquisition_fields ProtocolName SeriesDescription \
+    --reference_fields EchoTime RepetitionTime
+```
+
+This will create a JSON schema describing the session based on the specified fields.
+
+2. Validate a DICOM Session
+
+```bash
+dicompare-session \
+    --in_session /path/to/dicom/session \
+    --json_ref schema.json \
+    --out_json compliance_report.json
+```
+
+The tool will output a compliance summary, indicating deviations from the reference schema.
+
+## Python API
+
+The `dicompare` package provides a Python API for programmatic schema generation and validation.
+
+**Generate a schema:**
+
+```python
+from dicompare.io import read_dicom_session
+
+reference_fields = ["EchoTime", "RepetitionTime"]
+acquisition_fields = ["ProtocolName", "SeriesDescription"]
+
+session_data = read_dicom_session(
+    session_dir="/path/to/dicom/session",
+    acquisition_fields=acquisition_fields,
+    reference_fields=reference_fields
+)
+
+# Save the schema as JSON
+import json
+with open("schema.json", "w") as f:
+    json.dump(session_data, f, indent=4)
+```
+
+**Validate a session:**
+
+```python
+from dicompare.io import read_json_session, read_dicom_session
+from dicompare.compliance import check_session_compliance
+
+# Load the schema
+acquisition_fields, reference_fields, ref_session = read_json_session(json_ref="schema.json")
+
+# Read the input session
+in_session = read_dicom_session(
+    session_dir="/path/to/dicom/session",
+    acquisition_fields=acquisition_fields,
+    reference_fields=reference_fields
+)
+
+# Perform compliance check
+compliance_summary = check_session_compliance(
+    in_session=in_session,
+    ref_session=ref_session,
+    series_map=None  # Optional: map series if needed
+)
+
+# Print compliance summary
+for entry in compliance_summary:
+    print(entry)
+```
+

dicompare-0.1.8/dicompare/__init__.py

@@ -0,0 +1,7 @@
+__version__ = "0.1.8"
+
+# Import core functionalities
+from .io import get_dicom_values, load_dicom, load_json_session, load_dicom_session, load_python_session
+from .compliance import check_session_compliance_with_json_reference, check_session_compliance_with_python_module, check_dicom_compliance, is_session_compliant, is_dicom_compliant
+from .mapping import map_to_json_reference, interactive_mapping_to_json_reference, interactive_mapping_to_python_reference
+from .validation import BaseValidationModel, ValidationError, validator

dicompare-0.1.8/dicompare/cli/check_session.py

@@ -0,0 +1,93 @@
+import sys
+import json
+import argparse
+import pandas as pd
+
+from dicompare.io import load_json_session, load_python_session, load_dicom_session
+from dicompare.compliance import check_session_compliance_with_json_reference, check_session_compliance_with_python_module
+from dicompare.mapping import map_to_json_reference, interactive_mapping_to_json_reference, interactive_mapping_to_python_reference
+
+def main():
+    parser = argparse.ArgumentParser(description="Generate compliance summaries for a DICOM session.")
+    parser.add_argument("--json_ref", help="Path to the JSON reference file.")
+    parser.add_argument("--python_ref", help="Path to the Python module containing validation models.")
+    parser.add_argument("--in_session", required=True, help="Directory path for the DICOM session.")
+    parser.add_argument("--out_json", default="compliance_report.json", help="Path to save the JSON compliance summary report.")
+    parser.add_argument("--auto_yes", action="store_true", help="Automatically map acquisitions to series.")
+    args = parser.parse_args()
+
+    if not (args.json_ref or args.python_ref):
+        raise ValueError("You must provide either --json_ref or --python_ref.")
+
+    # Load the reference models and fields
+    if args.json_ref:
+        acquisition_fields, reference_fields, ref_session = load_json_session(json_ref=args.json_ref)
+    elif args.python_ref:
+        ref_models = load_python_session(module_path=args.python_ref)
+        acquisition_fields = ["ProtocolName"]
+
+    # Load the input session
+    in_session = load_dicom_session(
+        session_dir=args.in_session,
+        acquisition_fields=acquisition_fields,
+    )
+
+    if args.json_ref:
+        # Group by all existing unique combinations of reference fields
+        in_session = (
+            in_session.groupby(reference_fields)
+            .apply(lambda x: x.reset_index(drop=True))
+            .reset_index(drop=True)  # Reset the index to avoid index/column ambiguity
+        )
+
+        # Assign unique group numbers for each combination of reference fields
+        in_session["Series"] = (
+            in_session.groupby(reference_fields, dropna=False).ngroup().add(1).apply(lambda x: f"Series {x}")
+        )
+
+    if args.json_ref:
+        session_map = map_to_json_reference(in_session, ref_session)
+        if not args.auto_yes and sys.stdin.isatty():
+            session_map = interactive_mapping_to_json_reference(in_session, ref_session, initial_mapping=session_map)
+    else:
+        session_map = interactive_mapping_to_python_reference(in_session, ref_models)
+    
+
+    # Perform compliance check
+    if args.json_ref:
+        compliance_summary = check_session_compliance_with_json_reference(
+            in_session=in_session,
+            ref_session=ref_session,
+            session_map=session_map
+        )
+    else:
+        compliance_summary = check_session_compliance_with_python_module(
+            in_session=in_session,
+            ref_models=ref_models,
+            session_map=session_map
+        )
+    compliance_df = pd.DataFrame(compliance_summary)
+
+    # If compliance_df is empty, print message and exit
+    if compliance_df.empty:
+        print("Session is fully compliant with the reference model.")
+        return
+
+    # Inline summary output
+    for entry in compliance_summary:
+        if entry.get('acquisition'): print(f"Acquisition: {entry.get('acquisition')}")
+        if entry.get('field'): print(f"Field: {entry.get('field')}")
+        if entry.get('value'): print(f"Value: {entry.get('value')}")
+        if entry.get('rule'): print(f"Rule: {entry.get('rule')}")
+        if entry.get('message'): print(f"Message: {entry.get('message')}")
+        if entry.get('passed'): print(f"Passed: {entry.get('passed')}")
+        print("-" * 40)
+
+    # Save compliance summary to JSON
+    if args.out_json:
+        with open(args.out_json, "w") as f:
+            json.dump(compliance_summary, f)
+
+if __name__ == "__main__":
+    main()
+

dicompare-0.1.8/dicompare/cli/gen_session.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python
+
+import argparse
+import json
+import pandas as pd
+from dicompare.io import load_dicom_session
+from dicompare.utils import clean_string
+
+def make_hashable(value):
+    """
+    Convert a value into a hashable format.
+    Handles lists, dictionaries, and other non-hashable types.
+    """
+    if isinstance(value, list):
+        return tuple(value)
+    elif isinstance(value, dict):
+        return tuple((k, make_hashable(v)) for k, v in value.items())
+    elif isinstance(value, set):
+        return tuple(sorted(make_hashable(v) for v in value))
+    return value
+
+
+def create_json_reference(session_df, acquisition_fields, reference_fields, name_template="{ProtocolName}"):
+    """
+    Create a JSON reference from the session DataFrame.
+
+    Args:
+        session_df (pd.DataFrame): DataFrame of the DICOM session.
+        acquisition_fields (List[str]): Fields to uniquely identify each acquisition.
+        reference_fields (List[str]): Fields to include in JSON reference.
+        name_template (str): Naming template for acquisitions/series.
+
+    Returns:
+        dict: JSON structure representing the reference.
+    """
+    # Ensure all values in the DataFrame are hashable
+    for col in session_df.columns:
+        session_df[col] = session_df[col].apply(make_hashable)
+
+    json_reference = {"acquisitions": {}}
+
+    # Group by acquisition
+    for acquisition_name, group in session_df.groupby("Acquisition"):
+        acquisition_entry = {"fields": [], "series": []}
+
+        # Add acquisition-level fields
+        for field in acquisition_fields:
+            unique_values = group[field].dropna().unique()
+            if len(unique_values) == 1:
+                acquisition_entry["fields"].append({"field": field, "value": unique_values[0]})
+
+        # Group by series within each acquisition
+        series_fields = list(set(reference_fields) - set(acquisition_fields))
+        if series_fields:
+            series_groups = group.groupby(series_fields, dropna=False)
+
+            for i, (series_key, series_group) in enumerate(series_groups, start=1):
+                series_entry = {
+                    "name": f"Series {i}",
+                    "fields": [{"field": field, "value": series_key[j]} for j, field in enumerate(series_fields)]
+                }
+                acquisition_entry["series"].append(series_entry)
+
+        # Exclude reference fields from acquisition-level fields if they appear in series
+        acquisition_entry["fields"] = [
+            field for field in acquisition_entry["fields"] if field["field"] not in reference_fields
+        ]
+
+        # Add to JSON reference
+        json_reference["acquisitions"][clean_string(acquisition_name)] = acquisition_entry
+
+    return json_reference
+
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Generate a JSON reference for DICOM compliance.")
+    parser.add_argument("--in_session_dir", required=True, help="Directory containing DICOM files for the session.")
+    parser.add_argument("--out_json_ref", required=True, help="Path to save the generated JSON reference.")
+    parser.add_argument("--acquisition_fields", nargs="+", required=True, help="Fields to uniquely identify each acquisition.")
+    parser.add_argument("--reference_fields", nargs="+", required=True, help="Fields to include in JSON reference with their values.")
+    parser.add_argument("--name_template", default="{ProtocolName}", help="Naming template for each acquisition series.")
+    args = parser.parse_args()
+
+    # Read DICOM session
+    session_data = load_dicom_session(
+        session_dir=args.in_session_dir,
+        acquisition_fields=args.acquisition_fields,
+    )
+
+    # Filter fields in DataFrame
+    relevant_fields = set(args.acquisition_fields + args.reference_fields)
+    session_data = session_data[list(relevant_fields.intersection(session_data.columns)) + ["Acquisition"]]
+
+    # Generate JSON reference
+    json_reference = create_json_reference(
+        session_df=session_data,
+        acquisition_fields=args.acquisition_fields,
+        reference_fields=args.reference_fields,
+        name_template=args.name_template,
+    )
+
+    # Write JSON to output file
+    with open(args.out_json_ref, "w") as f:
+        json.dump(json_reference, f, indent=4)
+    print(f"JSON reference saved to {args.out_json_ref}")
+
+
+if __name__ == "__main__":
+    main()

dicompare-0.1.8/dicompare/cli/start_web.py

@@ -0,0 +1,18 @@
+import os
+import webbrowser
+from importlib.resources import files
+
+def main():
+    # Get the package base directory using `importlib.resources`
+    package_dir = files("dicompare").joinpath("docs", "index.html")
+
+    # Convert the resource path to an absolute file path
+    docs_path = str(package_dir)
+
+    # Check if the file exists
+    if not os.path.exists(docs_path):
+        print(f"Error: Documentation not found at {docs_path}.")
+        return
+
+    # Open the documentation in the default web browser
+    webbrowser.open(f"file://{docs_path}")