dicompare 0.1.8__py3-none-any.whl

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/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/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/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}")

dicompare/compliance.py

@@ -0,0 +1,343 @@
+"""
+This module provides functions for validating a DICOM sessions.
+
+The module supports compliance checks for JSON-based reference sessions and Python module-based validation models.
+
+"""
+
+from typing import List, Dict, Any, Tuple
+from dicompare.validation import BaseValidationModel
+import pandas as pd
+
+def check_session_compliance_with_json_reference(
+    in_session: pd.DataFrame,
+    ref_session: Dict[str, Any],
+    session_map: Dict[Tuple[str, str], Tuple[str, str]]
+) -> List[Dict[str, Any]]:
+    """
+    Validate a DICOM session against a JSON reference session.
+
+    Args:
+        in_session (pd.DataFrame): Input session DataFrame containing DICOM metadata.
+        ref_session (Dict[str, Any]): Reference session data loaded from a JSON file.
+        session_map (Dict[Tuple[str, str], Tuple[str, str]]): Mapping of input acquisitions/series 
+            to reference acquisitions/series.
+
+    Returns:
+        List[Dict[str, Any]]: A list of compliance issues, where each issue is represented as a dictionary.
+    """
+    compliance_summary = []
+
+    # Iterate over the session mapping
+    for (in_acq_name, in_series_name), (ref_acq_name, ref_series_name) in session_map.items():
+        # Filter the input session for the current acquisition and series
+        in_acq_series = in_session[
+            (in_session["Acquisition"] == in_acq_name) & 
+            (in_session["Series"] == in_series_name)
+        ]
+
+        if in_acq_series.empty:
+            compliance_summary.append({
+                "reference acquisition": (ref_acq_name, ref_series_name),
+                "input acquisition": (in_acq_name, in_series_name),
+                "field": "Acquisition-Level Error",
+                "value": None,
+                "rule": "Input acquisition and series must be present.",
+                "message": "Input acquisition or series not found.",
+                "passed": "❌"
+            })
+            continue
+
+        # Filter the reference session for the current acquisition and series
+        ref_acq = ref_session["acquisitions"].get(ref_acq_name, {})
+        ref_series = next(
+            (series for series in ref_acq.get("series", []) if series["name"] == ref_series_name),
+            None
+        )
+
+        if not ref_series:
+            compliance_summary.append({
+                "reference acquisition": (ref_acq_name, ref_series_name),
+                "input acquisition": (in_acq_name, in_series_name),
+                "field": "Reference-Level Error",
+                "value": None,
+                "rule": "Reference acquisition and series must be present.",
+                "message": "Reference acquisition or series not found.",
+                "passed": "❌"
+            })
+            continue
+
+        # Iterate through the reference fields and check compliance
+        for ref_field in ref_series.get("fields", []):
+            field_name = ref_field["field"]
+            expected_value = ref_field.get("value")
+            tolerance = ref_field.get("tolerance")
+            contains = ref_field.get("contains")
+
+            # Check the corresponding field in the input session DataFrame
+            if field_name not in in_acq_series.columns:
+                compliance_summary.append({
+                    "reference acquisition": (ref_acq_name, ref_series_name),
+                    "input acquisition": (in_acq_name, in_series_name),
+                    "field": field_name,
+                    "value": None,
+                    "rule": "Field must be present.",
+                    "message": "Field not found in input session.",
+                    "passed": "❌"
+                })
+                continue
+
+            actual_value = in_acq_series[field_name].iloc[0]
+
+            # Contains check
+            if contains is not None:
+                if not isinstance(actual_value, list) or contains not in actual_value:
+                    compliance_summary.append({
+                        "reference acquisition": (ref_acq_name, ref_series_name),
+                        "input acquisition": (in_acq_name, in_series_name),
+                        "field": field_name,
+                        "value": actual_value,
+                        "rule": "Field must contain value.",
+                        "message": f"Expected to contain {contains}, got {actual_value}.",
+                        "passed": "❌"
+                    })
+
+            # Tolerance check
+            elif tolerance is not None and isinstance(actual_value, (int, float)):
+                if not (expected_value - tolerance <= actual_value <= expected_value + tolerance):
+                    compliance_summary.append({
+                        "reference acquisition": (ref_acq_name, ref_series_name),
+                        "input acquisition": (in_acq_name, in_series_name),
+                        "field": field_name,
+                        "value": actual_value,
+                        "rule": "Field must be within tolerance.",
+                        "message": f"Expected {expected_value} ± {tolerance}, got {actual_value}.",
+                        "passed": "❌"
+                    })
+
+            # Exact match check
+            elif expected_value is not None and actual_value != expected_value:
+                compliance_summary.append({
+                    "reference acquisition": (ref_acq_name, ref_series_name),
+                    "input acquisition": (in_acq_name, in_series_name),
+                    "field": field_name,
+                    "value": actual_value,
+                    "rule": "Field must match expected value.",
+                    "message": f"Expected {expected_value}, got {actual_value}.",
+                    "passed": "❌"
+                })
+
+    return compliance_summary
+
+def check_session_compliance_with_python_module(
+    in_session: pd.DataFrame,
+    ref_models: Dict[str, BaseValidationModel],
+    session_map: Dict[str, str],
+    raise_errors: bool = False
+) -> List[Dict[str, Any]]:
+    """
+    Validate a DICOM session against Python module-based validation models.
+
+    Args:
+        in_session (pd.DataFrame): Input session DataFrame containing DICOM metadata.
+        ref_models (Dict[str, BaseValidationModel]): Dictionary mapping acquisition names to 
+            validation models.
+        session_map (Dict[str, str]): Mapping of reference acquisitions to input acquisitions.
+        raise_errors (bool): Whether to raise exceptions for validation failures. Defaults to False.
+
+    Returns:
+        List[Dict[str, Any]]: A list of compliance issues, where each issue is represented as a dictionary.
+    
+    Raises:
+        ValueError: If `raise_errors` is True and validation fails for any acquisition.
+    """
+    compliance_summary = []
+
+    for ref_acq_name, in_acq_name in session_map.items():
+        # Filter the input session for the current acquisition
+        in_acq = in_session[in_session["Acquisition"] == in_acq_name]
+
+        if in_acq.empty:
+            compliance_summary.append({
+                "reference acquisition": ref_acq_name,
+                "input acquisition": in_acq_name,
+                "field": "Acquisition-Level Error",
+                "value": None,
+                "rule": "Input acquisition must be present.",
+                "message": f"Input acquisition '{in_acq_name}' not found.",
+                "passed": "❌"
+            })
+            continue
+
+        # Retrieve reference model
+        ref_model_cls = ref_models.get(ref_acq_name)
+        if not ref_model_cls:
+            compliance_summary.append({
+                "reference acquisition": ref_acq_name,
+                "input acquisition": in_acq_name,
+                "field": "Model Error",
+                "value": None,
+                "rule": "Reference model must exist.",
+                "message": f"No model found for reference acquisition '{ref_acq_name}'.",
+                "passed": "❌"
+            })
+            continue
+        ref_model = ref_model_cls()
+
+        # Prepare acquisition data as a single DataFrame
+        acquisition_df = in_acq.copy()
+
+        # Validate using the reference model
+        success, errors, passes = ref_model.validate(data=acquisition_df)
+
+        # Record errors
+        for error in errors:
+            compliance_summary.append({
+                "reference acquisition": ref_acq_name,
+                "reference series": None,
+                "input acquisition": in_acq_name,
+                "input series": None,
+                "field": error['field'],
+                "value": error['value'],
+                "rule": error['rule'],
+                "message": error['message'],
+                "passed": "❌"
+            })
+
+        # Record passes
+        for passed_test in passes:
+            compliance_summary.append({
+                "reference acquisition": ref_acq_name,
+                "reference series": None,
+                "input acquisition": in_acq_name,
+                "input series": None,
+                "field": passed_test['field'],
+                "value": passed_test['value'],
+                "rule": passed_test['rule'],
+                "message": passed_test['message'],
+                "passed": "✅"
+            })
+
+        # Raise an error if validation fails and `raise_errors` is True
+        if raise_errors and not success:
+            raise ValueError(f"Validation failed for acquisition '{in_acq_name}'.")
+
+    return compliance_summary
+
+def check_dicom_compliance(
+    reference_fields: List[Dict[str, Any]],
+    dicom_values: Dict[str, Any]
+) -> List[Dict[str, Any]]:
+    """
+    Validate individual DICOM values against reference fields.
+
+    Args:
+        reference_fields (List[Dict[str, Any]]): A list of dictionaries defining the expected values 
+            and rules for validation (e.g., tolerance, contains).
+        dicom_values (Dict[str, Any]): Dictionary of DICOM metadata values to be validated.
+
+    Returns:
+        List[Dict[str, Any]]: A list of compliance issues, where each issue is represented as a dictionary.
+    """
+    compliance_summary = []
+
+    for ref_field in reference_fields:
+        field_name = ref_field["field"]
+        expected_value = ref_field.get("value")
+        tolerance = ref_field.get("tolerance")
+        contains = ref_field.get("contains")
+        actual_value = dicom_values.get(field_name, "N/A")
+
+        # Convert lists to tuples for comparison
+        if expected_value is not None and isinstance(expected_value, list):
+            expected_value = tuple(expected_value)
+        if actual_value is not None and isinstance(actual_value, list):
+            actual_value = tuple(actual_value)
+
+        # Check for missing field
+        if actual_value == "N/A":
+            compliance_summary.append({
+                "field": field_name,
+                "value": actual_value,
+                "rule": "Field must be present.",
+                "message": "Field not found.",
+                "passed": "❌",
+            })
+            continue
+
+        # Contains check
+        if contains is not None:
+            if not isinstance(actual_value, list) or contains not in actual_value:
+                compliance_summary.append({
+                    "field": field_name,
+                    "value": actual_value,
+                    "rule": "Field must contain value.",
+                    "message": f"Expected to contain {contains}, got {actual_value}.",
+                    "passed": "❌",
+                })
+
+        # Tolerance check
+        elif tolerance is not None and isinstance(actual_value, (int, float)):
+            if not (expected_value - tolerance <= actual_value <= expected_value + tolerance):
+                compliance_summary.append({
+                    "field": field_name,
+                    "value": actual_value,
+                    "rule": "Field must be within tolerance.",
+                    "message": f"Expected {expected_value} ± {tolerance}, got {actual_value}.",
+                    "passed": "❌",
+                })
+
+        # Exact match check
+        elif expected_value is not None and actual_value != expected_value:
+            compliance_summary.append({
+                "field": field_name,
+                "value": actual_value,
+                "rule": "Field must match expected value.",
+                "message": f"Expected {expected_value}, got {actual_value}.",
+                "passed": "❌",
+            })
+
+    return compliance_summary
+
+def is_session_compliant(
+        in_session: Dict[str, Dict[str, Any]],
+        ref_session: Dict[str, Dict[str, Any]],
+        session_map: Dict[Tuple[str, str], Tuple[str, str]]
+) -> bool:
+    """
+    Check if the entire DICOM session complies with the reference session.
+
+    Args:
+        in_session (Dict): Input session data containing DICOM metadata.
+        ref_session (Dict): Reference session data containing expected metadata and rules.
+        session_map (Dict): Mapping of input acquisitions/series to reference acquisitions/series.
+
+    Returns:
+        bool: True if the session is fully compliant, False otherwise.
+    """
+
+    compliance_issues = check_session_compliance_with_json_reference(in_session, ref_session, session_map)
+    return len(compliance_issues) == 0
+
+def is_dicom_compliant(
+        reference_model: BaseValidationModel,
+        dicom_values: Dict[str, Any]
+) -> bool:
+    """
+    Check if a DICOM file's metadata complies with a validation model.
+
+    Args:
+        reference_model (BaseValidationModel): The validation model defining expected metadata.
+        dicom_values (Dict[str, Any]): Dictionary of DICOM metadata values to be validated.
+
+    Returns:
+        bool: True if the DICOM metadata is compliant, False otherwise.
+    """
+
+    compliance_issues = check_dicom_compliance(
+        reference_model.fields,
+        dicom_values
+    )
+
+    return len(compliance_issues) == 0
+