Add configuration for DESPIAD project

README.md

@@ -147,6 +147,13 @@ The configuration file defines:
 
 - Project name: the `<project-slug>` name of the Project
 - The DICOM dataset modalities to retain (e.g. `["DX", "CR"]` for X-Ray studies)
+- The minimum number of instances required by a series (defaults to 1). May be set higher than 1 to filter out
+  series with a single screenshot containing patient identifiable data
+- A list of series description filters (e.g. `['loc', 'pos']`). Series with descriptions matching any of these
+  filters will be skipped
+- A list of allowed manufacturers. By default, no manufacturers are allowed. For each manufacturer:
+  - A regex to identify the allowed manufacturer (e.g. `^philips`)
+  - A list of series numbers to exclude for the given manufacturer (e.g. `[3, 4]`)
 - The [anonymisation operations](/pixl_dcmd/README.md#tag-scheme-anonymisation) to be applied to the DICOM tags,
   by providing a file path to one or multiple YAML files.
   We currently allow two types of files:

cli/src/pixl_cli/_config.py

@@ -35,7 +35,7 @@
         "password": config("PIXL_DB_PASSWORD"),
         "database": config("PIXL_DB_NAME"),
     },
-}  # type: dict
+}
 
 
 class APIConfig:

orthanc/orthanc-anon/plugin/pixl.py

@@ -45,6 +45,7 @@
 from pixl_dcmd.dicom_helpers import get_study_info
 from pixl_dcmd.main import (
     anonymise_dicom_and_update_db,
+    get_series_to_skip,
     parse_validation_results,
     write_dataset_to_bytes,
 )
@@ -331,6 +332,7 @@ def _anonymise_study_instances(
     Return a list of the bytes of anonymised instances, and the anonymised StudyInstanceUID.
     """
     config = load_project_config(project_name)
+    series_to_skip = get_series_to_skip(zipped_study, config.min_instances_per_series)
     anonymised_instances_bytes = []
     skipped_instance_counts = defaultdict(int)
     dicom_validation_errors = {}
@@ -339,6 +341,17 @@ def _anonymise_study_instances(
         with zipped_study.open(file_info) as file:
             logger.debug("Reading file {}", file)
             dataset = dcmread(file)
+
+            if dataset.SeriesInstanceUID in series_to_skip:
+                logger.debug(
+                    "Skipping series {} for study {} due to too few instances",
+                    dataset.SeriesInstanceUID,
+                    study_info,
+                )
+                key = "DICOM instance discarded as series has too few instances"
+                skipped_instance_counts[key] += 1
+                continue
+
             try:
                 anonymised_instance, instance_validation_errors = _anonymise_dicom_instance(
                     dataset, config

pixl_core/src/core/project_config/pixl_config_model.py

@@ -16,6 +16,7 @@
 
 from __future__ import annotations
 
+import re
 from enum import Enum
 from pathlib import Path
 from typing import Any, Optional
@@ -61,6 +62,16 @@
     modalities: list[str]
 
 
+class Manufacturer(BaseModel):
+    """
+    An allowed manufacturer for a project.
+    Also defines which series numbers to exclude for this manufacturer.
+    """
+
+    regex: str = "no manufacturers allowed ^"
+    exclude_series_numbers: list[str] = []
+
+
 class TagOperationFiles(BaseModel):
     """Tag operations files for a project. At least a base file is required."""
 
@@ -133,20 +144,66 @@
     """Project-specific configuration for Pixl."""
 
     project: _Project
-    series_filters: Optional[list[str]] = None
+    min_instances_per_series: Optional[int] = 1
+    series_filters: Optional[list[str]] = []  # pydantic makes a deep copy of the empty default list
+    allowed_manufacturers: list[Manufacturer] = [Manufacturer()]
     tag_operation_files: TagOperationFiles
     destination: _Destination
 
-    def is_series_excluded(self, series_description: str) -> bool:
+    def is_series_description_excluded(self, series_description: str | None) -> bool:
         """
-        Return whether this config excludes the series with the given description
+        Return whether this config excludes the series with the given description.
+
+        Do a simple case-insensitive substring check - this data is ultimately typed by a human, and
+        different image sources may have different conventions for case conversion.
+
         :param series_description: the series description to test
         :returns: True if it should be excluded, False if not
         """
-        if self.series_filters is None or series_description is None:
+        if not self.series_filters or series_description is None:
             return False
-        # Do a simple case-insensitive substring check - this data is ultimately typed by a human,
-        # and different image sources may have different conventions for case conversion.
+
         return any(
             series_description.upper().find(filt.upper()) != -1 for filt in self.series_filters
         )
+
+    def is_series_number_excluded(self, manufacturer: str, series_number: str | None) -> bool:
+        """
+        Return whether this config excludes the series with the given number for the given
+        manufacturer.
+
+        :param manufacturer: the manufacturer to test
+        :param series_number: the series number to test
+        :returns: True if it should be excluded, False if not
+        """
+        if not self.is_manufacturer_allowed(manufacturer) or series_number is None:
+            return False
+
+        exclude_series_numbers = self._get_manufacturer(manufacturer).exclude_series_numbers
+        return any(series_number.find(filt) != -1 for filt in exclude_series_numbers)
+
+    def is_manufacturer_allowed(self, manufacturer: str) -> bool:
+        """
+        Check whether the manufacturer is in the allow-list.
+
+        :param manufacturer: name of the manufacturer
+        :returns: True is the manufacturer is allowed, False if not
+        """
+        for manufacturer_config in self.allowed_manufacturers:
+            if re.search(rf"{manufacturer_config.regex}", manufacturer, flags=re.IGNORECASE):
+                return True
+        return False
+
+    def _get_manufacturer(self, manufacturer: str) -> Manufacturer:
+        """
+        Get the manufacturer configuration for the given manufacturer.
+
+        :param manufacturer: name of the manufacturer
+        :returns: Manufacturer configuration
+        :raises: ValueError: if the manufacturer is not allowed
+        """
+        for manufacturer_config in self.allowed_manufacturers:
+            if re.search(rf"{manufacturer_config.regex}", manufacturer, flags=re.IGNORECASE):
+                return manufacturer_config
+        msg = f"Manufacturer {manufacturer} is not allowed by project {self.project.name}"
+        raise ValueError(msg)

pixl_core/tests/project_config/test_project_config.py

@@ -181,4 +181,4 @@ def test_series_filtering(base_yaml_data, series_filters, test_series_desc, expe
     if series_filters is not None:
         base_yaml_data["series_filters"] = series_filters
     cfg = PixlConfig.model_validate(base_yaml_data)
-    assert cfg.is_series_excluded(test_series_desc) == expect_exclude
+    assert cfg.is_series_description_excluded(test_series_desc) == expect_exclude

pixl_dcmd/src/pixl_dcmd/main.py

@@ -16,6 +16,7 @@
 import typing
 from functools import lru_cache
 from io import BytesIO
+from zipfile import ZipFile
 
 import requests
 from core.exceptions import PixlSkipInstanceError
@@ -26,7 +27,7 @@
     anonymize_dataset,
 )
 from loguru import logger
-from pydicom import DataElement, Dataset, dcmwrite
+from pydicom import DataElement, Dataset, dcmread, dcmwrite
 
 from core.project_config.pixl_config_model import PixlConfig
 from pixl_dcmd._database import (
@@ -56,14 +57,71 @@
         return buffer.read()
 
 
+def get_series_to_skip(zipped_study: ZipFile, min_instances: int) -> set[str]:
+    """
+    Determine which series to skip based on the number of instances in the series.
+
+    If a series has fewer instances than `min_instances`, add it to a set of series to skip.
+
+    Args:
+        zipped_study: ZipFile containing the study
+        min_instances: Minimum number of instances required to include a series
+
+    """
+    if min_instances <= 1:
+        return set()
+
+    series_instances = {}
+    for file_info in zipped_study.infolist():
+        with zipped_study.open(file_info) as file:
+            logger.debug("Reading file {}", file)
+            dataset = dcmread(file)
+            if dataset.SeriesInstanceUID not in series_instances:
+                series_instances[dataset.SeriesInstanceUID] = 1
+                continue
+            series_instances[dataset.SeriesInstanceUID] += 1
+
+    return {
+        series for series, count in series_instances.items() if count < min_instances
+    }
+
+
 def _should_exclude_series(dataset: Dataset, cfg: PixlConfig) -> bool:
+    """
+    Check whether the dataset series should be exlucded based on its description
+    and number.
+    """
     series_description = dataset.get("SeriesDescription")
-    if cfg.is_series_excluded(series_description):
+    if cfg.is_series_description_excluded(series_description):
         logger.debug("FILTERING OUT series description: {}", series_description)
         return True
+
+    manufacturer = dataset.get("Manufacturer")
+    series_number = dataset.get("SeriesNumber")
+    if cfg.is_series_number_excluded(
+        manufacturer=manufacturer, series_number=series_number
+    ):
+        logger.debug(
+            "FILTERING OUT series number: {} for manufacturer: {}",
+            series_number,
+            manufacturer,
+        )
+        return True
+
     return False
 
 
+def _should_exclude_manufacturer(dataset: Dataset, cfg: PixlConfig) -> bool:
+    manufacturer = dataset.get("Manufacturer")
+    if manufacturer is None:
+        logger.debug("FILTERING out as manufacturer tag is missing")
+
+    should_exclude = not cfg.is_manufacturer_allowed(manufacturer=manufacturer)
+    if should_exclude:
+        logger.debug("FILTERING out manufacturer: {}", manufacturer)
+    return should_exclude
+
+
 def anonymise_dicom_and_update_db(
     dataset: Dataset,
     *,
@@ -125,9 +183,12 @@
     )
 
     # Do before anonymisation in case someone decides to delete the
-    # Series Description tag as part of anonymisation.
+    # Series Description or Manufacturer tags as part of anonymisation.
+    if _should_exclude_manufacturer(dataset, config):
+        msg = "DICOM instance discarded due to its manufacturer"
+        raise PixlSkipInstanceError(msg)
     if _should_exclude_series(dataset, config):
-        msg = "DICOM instance discarded due to its series description"
+        msg = "DICOM instance discarded due to its series description or number"
         raise PixlSkipInstanceError(msg)
     if dataset.Modality not in config.project.modalities:
         msg = f"Dropping DICOM Modality: {dataset.Modality}"

pixl_dcmd/tests/test_main.py

@@ -194,7 +194,9 @@ def ids_for_parameterised_test(val: pathlib.Path) -> str:
 
 
 @pytest.mark.parametrize(
-    ("yaml_file"), PROJECT_CONFIGS_DIR.glob("*.yaml"), ids=ids_for_parameterised_test
+    ("yaml_file"),
+    PROJECT_CONFIGS_DIR.glob("*.yaml"),
+    ids=ids_for_parameterised_test,
 )
 def test_anonymise_and_validate_dicom(caplog, request, yaml_file) -> None:
     """

projects/configs/despiad.yaml

@@ -0,0 +1,39 @@
+#  Copyright (c) 2024 University College London Hospitals NHS Foundation Trust
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+project:
+    name: "despiad"
+    modalities:
+      - "CT"
+      - "PT"
+
+tag_operation_files:
+    base:
+        - "base.yaml"
+        - "ct.yaml"
+        - "pet.yaml"
+        - "despiad.yaml"
+    manufacturer_overrides: []
+
+allowed_manufacturers:
+  - regex: ".*"
+    exclude_series_numbers: []
+
+min_instances_per_series: 1
+
+series_filters: []
+
+destination:
+    dicom: "xnat"
+    parquet: "none"

projects/configs/ms-pinpoint.yaml

@@ -23,6 +23,12 @@ tag_operation_files:
         - "ms-pinpoint.yaml"
     manufacturer_overrides: ["mri.yaml"]
 
+allowed_manufacturers:
+  - regex: ".*"
+    exclude_series_numbers: []
+
+min_instances_per_series: 1
+
 series_filters:
     - "localizer"
     - "localiser"

projects/configs/prognosis-ai.yaml

@@ -23,6 +23,12 @@ tag_operation_files:
         - "ion-neuro-db.yaml"
     manufacturer_overrides: ["mri.yaml"]
 
+allowed_manufacturers:
+  - regex: ".*"
+    exclude_series_numbers: []
+
+min_instances_per_series: 1
+
 series_filters:
     - "localizer"
     - "localiser"