endoreg-db 0.8.9.32__py3-none-any.whl

endoreg_db/models/medical/patient/patient_finding.py

@@ -0,0 +1,416 @@
+from typing import TYPE_CHECKING
+
+from django.core.exceptions import ValidationError
+from django.db import models
+from django.utils import timezone
+
+if TYPE_CHECKING:
+    from endoreg_db.models import (
+        Finding,
+        LabelVideoSegment,
+        PatientExamination,
+        PatientFindingClassification,
+        PatientFindingIntervention,
+    )
+    from endoreg_db.utils.links.requirement_link import RequirementLinks
+
+
+class PatientFinding(models.Model):
+    patient_examination = models.ForeignKey(
+        "PatientExamination", on_delete=models.CASCADE, related_name="patient_findings"
+    )
+    finding = models.ForeignKey(
+        "Finding", on_delete=models.CASCADE, related_name="finding_patient_findings"
+    )
+
+    # Audit-Felder für medizinische Nachverfolgung
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+    created_by = models.ForeignKey(
+        "auth.User",
+        on_delete=models.PROTECT,
+        related_name="created_findings",
+        null=True,
+        blank=True,
+    )
+    updated_by = models.ForeignKey(
+        "auth.User",
+        on_delete=models.PROTECT,
+        related_name="updated_findings",
+        null=True,
+        blank=True,
+    )
+
+    # Soft Delete für historische Daten
+    is_active = models.BooleanField(
+        default=True, help_text="Deaktiviert statt gelöscht für Audit-Trail"
+    )
+    deactivated_at = models.DateTimeField(null=True, blank=True)
+    deactivated_by = models.ForeignKey(
+        "auth.User",
+        on_delete=models.PROTECT,
+        related_name="deactivated_findings",
+        null=True,
+        blank=True,
+    )
+
+    if TYPE_CHECKING:
+        patient_examination: models.ForeignKey["PatientExamination"]
+        finding: models.ForeignKey["Finding"]
+
+        @property
+        def video_segments(
+            self,
+        ) -> models.manager.RelatedManager["LabelVideoSegment"]: ...
+
+        @property
+        def interventions(
+            self,
+        ) -> models.manager.RelatedManager["PatientFindingIntervention"]: ...
+
+        @property
+        def classifications(
+            self,
+        ) -> models.manager.RelatedManager["PatientFindingClassification"]: ...
+
+    class Meta:
+        verbose_name = "Patient Finding"
+        verbose_name_plural = "Patient Findings"
+        ordering = ["patient_examination", "finding"]
+
+        # Wichtige Constraints für Datenintegrität
+        constraints = [
+            models.UniqueConstraint(
+                fields=["patient_examination", "finding"],
+                condition=models.Q(is_active=True),
+                name="unique_active_finding_per_examination",
+            ),
+            models.CheckConstraint(
+                condition=models.Q(  # called .check in future?
+                    deactivated_at__isnull=True, deactivated_by__isnull=True
+                )
+                | models.Q(
+                    deactivated_at__isnull=False,
+                    deactivated_by__isnull=False,
+                    is_active=False,
+                ),
+                name="deactivation_fields_consistency",
+            ),
+        ]
+
+        # Performance-optimierte Indizes
+        indexes = [
+            models.Index(fields=["patient_examination", "finding"]),
+            models.Index(fields=["patient_examination", "is_active"]),
+            models.Index(fields=["created_at"]),
+            models.Index(fields=["finding", "is_active"]),
+        ]
+
+    @property
+    def patient(self):
+        """Returns the patient associated with this patient finding."""
+        return self.patient_examination.patient
+
+    def __str__(self):
+        status = " (deaktiviert)" if not self.is_active else ""
+        return f"{self.patient_examination} - {self.finding}{status}"
+
+    def clean(self):
+        """
+        Validates the patient finding against business rules before saving.
+
+        Ensures that the selected finding is allowed for the associated examination and that all required findings are present. Raises a ValidationError if the finding is not permitted or required findings are missing.
+        """
+        super().clean()
+
+        # Prüfe ob Finding für diese Examination erlaubt ist
+        if self.finding and self.patient_examination:
+            available_findings = (
+                self.patient_examination.examination_safe.get_available_findings()
+            )
+            if self.finding not in available_findings:
+                raise ValidationError(
+                    {
+                        "finding": f'Finding "{self.finding.name}" ist nicht für Examination "{self.patient_examination.examination_safe.name}" erlaubt.'
+                    }
+                )
+
+        # Prüfe Required Findings Logic
+        if self.finding and self.patient_examination:
+            self._validate_required_findings()
+
+    # This avoids validation errors on partial updates
+    def save(self, *args, **kwargs):
+        """
+        Validates the model instance before saving, unless performing a partial update.
+
+        Performs full model validation with `full_clean()` before saving, except when `update_fields` is specified for a partial update.
+        """
+        if not kwargs.get("update_fields"):
+            self.full_clean()
+        super().save(*args, **kwargs)
+
+    def _validate_required_findings(self):
+        """Validiert Required vs Optional Finding Constraints"""
+        examination = self.patient_examination.examination
+
+        # Hole Required Findings für diese Examination
+        required_findings = getattr(examination, "required_findings", None)
+        if required_findings and required_findings.exists():
+            # Prüfe ob alle Required Findings vorhanden sind
+            existing_findings = self.patient_examination.patient_findings.filter(
+                is_active=True
+            ).values_list("finding", flat=True)
+
+            missing_required = required_findings.exclude(id__in=existing_findings)
+            if (
+                missing_required.exists()
+                and self.finding not in required_findings.all()
+            ):
+                missing_names = ", ".join([f.name for f in missing_required])
+                raise ValidationError(f"Erforderliche Findings fehlen: {missing_names}")
+
+    def deactivate(self, user=None, reason=None):
+        """Soft Delete mit Audit-Trail"""
+        self.is_active = False
+        self.deactivated_at = timezone.now()
+        self.deactivated_by = user
+        self.save(update_fields=["is_active", "deactivated_at", "deactivated_by"])
+
+        # Deaktiviere auch abhängige Objekte
+        self.locations.update(is_active=False, deactivated_at=timezone.now())
+        self.morphologies.update(is_active=False, deactivated_at=timezone.now())
+        self.interventions.update(is_active=False, deactivated_at=timezone.now())
+
+    def reactivate(self, user=None):
+        """
+        Reactivates a previously deactivated patient finding after validating its state.
+
+        If validation passes, sets the finding as active, clears deactivation fields, updates the user, and saves changes. Raises a ValidationError if reactivation is not allowed.
+        """
+        if not self.is_active:
+            # Prüfe ob Reaktivierung erlaubt ist
+            try:
+                self.clean()
+                self.is_active = True
+                self.deactivated_at = None
+                self.deactivated_by = None
+                self.updated_by = user
+                self.save(
+                    update_fields=[
+                        "is_active",
+                        "deactivated_at",
+                        "deactivated_by",
+                        "updated_by",
+                    ]
+                )
+            except ValidationError as e:
+                raise ValidationError(f"Reaktivierung nicht möglich: {e}")
+
+    def get_interventions(self):
+        """
+        Retrieve all active interventions associated with this patient finding.
+
+        Returns:
+            QuerySet: Active related interventions with intervention details prefetched.
+        """
+        return self.interventions.filter(is_active=True).select_related("intervention")
+
+    def add_classification(
+        self,
+        classification_id,
+        classification_choice_id,
+        user=None,
+    ) -> "PatientFindingClassification":
+        """
+        Add a classification choice to this patient finding after validating its association.
+
+        Parameters:
+            classification_id: The ID of the classification to add.
+            classification_choice_id: The ID of the classification choice to associate.
+            user: Optional user performing the action.
+
+        Returns:
+            PatientFindingClassification: The created or existing active classification association.
+
+        Raises:
+            ValidationError: If the classification does not exist or the choice is not valid for the classification.
+        """
+        from ..finding import FindingClassification, FindingClassificationChoice
+        from .patient_finding_classification import PatientFindingClassification
+
+        try:
+            classification = FindingClassification.objects.get(id=classification_id)
+            classification_choice = FindingClassificationChoice.objects.filter(
+                id=classification_choice_id
+            ).first()
+
+            if not classification.choices.filter(id=classification_choice_id).exists():
+                raise ValidationError(
+                    f"Classification Choice {classification_choice_id} gehört nicht zu Classification {classification_id}"
+                )
+
+            existing = self.classifications.filter(
+                classification=classification,
+                classification_choice=classification_choice,
+                is_active=True,
+            ).first()
+
+            if existing:
+                return existing
+
+            patient_finding_classification = (
+                PatientFindingClassification.objects.create(
+                    finding=self,
+                    classification_id=classification_id,
+                    classification_choice_id=classification_choice_id,
+                )
+            )
+
+            return patient_finding_classification
+
+        except FindingClassification.DoesNotExist:
+            raise ValidationError(f"Classification {classification_id} nicht gefunden")
+
+    def add_intervention(self, intervention_id, state="pending", date=None, user=None):
+        """
+        Add an intervention to the patient finding after validating its existence.
+
+        Parameters:
+            intervention_id (int): The ID of the intervention to add.
+            state (str, optional): The state of the intervention. Defaults to "pending".
+            date (datetime, optional): The date of the intervention. Defaults to the current time if not provided.
+            user (User, optional): The user creating the intervention.
+
+        Returns:
+            PatientFindingIntervention: The created intervention instance.
+
+        Raises:
+            ValidationError: If the specified intervention does not exist.
+        """
+        from ..finding import FindingIntervention
+        from .patient_finding_intervention import PatientFindingIntervention
+
+        try:
+            intervention = FindingIntervention.objects.get(id=intervention_id)
+
+            patient_finding_intervention = PatientFindingIntervention.objects.create(
+                patient_finding=self,
+                intervention=intervention,
+                state=state,
+                date=date or timezone.now(),
+                created_by=user,
+            )
+
+            return patient_finding_intervention
+
+        except FindingIntervention.DoesNotExist:
+            raise ValidationError(f"Intervention {intervention_id} nicht gefunden")
+
+    def add_video_segment(self, video_segment):
+        """
+        Associates a video segment with this patient finding.
+
+        Parameters:
+                video_segment: The video segment instance to add.
+
+        Returns:
+                The added video segment instance.
+        """
+        self.video_segments.add(video_segment)  # TODO
+        return video_segment
+
+    # Manager für active/inactive Objekte
+    @property
+    def active_classifications(self):
+        """
+        Return all active classifications associated with this patient finding.
+
+        Returns:
+                QuerySet: Active related classifications where `is_active` is True.
+        """
+        return self.classifications.filter(is_active=True)
+
+    @property
+    def locations(self):
+        """
+        Return all classifications of this patient finding that are of type "location".
+
+        Returns:
+                QuerySet: Classifications related to this finding filtered by the "location" classification type.
+        """
+        classifications = self.classifications.filter(
+            classification__classification_types__name__iexact="location"
+        )
+        return classifications
+
+    @property
+    def morphologies(self):
+        """
+        Return all classifications of this patient finding that are of type "morphology".
+
+        Returns:
+                QuerySet: Classifications related to this finding filtered by the "morphology" classification type.
+        """
+        classifications = self.classifications.filter(
+            classification__classification_types__name__iexact="morphology"
+        )
+        return classifications
+
+    @property
+    def active_interventions(self):
+        return self.interventions.filter(is_active=True)
+
+    @property
+    def links(self) -> "RequirementLinks":
+        """
+        Aggregates and returns all related model instances relevant for requirement evaluation
+        as a RequirementLinks object.
+
+        This property provides access to:
+        - The finding associated with this patient finding
+        - All active finding classifications and their choices
+        - All active finding interventions
+        - The patient examination and patient
+        """
+        from typing import List, cast
+
+        from endoreg_db.utils.links.requirement_link import RequirementLinks
+
+        # Get the base finding
+        findings_list = [self.finding] if self.finding else []
+
+        # Get all active finding classifications and their choices
+        finding_classifications_list = []
+        finding_classification_choices_list = []
+
+        for pf_classification in self.active_classifications:
+            if pf_classification.classification:
+                finding_classifications_list.append(pf_classification.classification)
+            if pf_classification.classification_choice:
+                finding_classification_choices_list.append(
+                    pf_classification.classification_choice
+                )
+
+        # Get all active finding interventions
+        finding_interventions_list = []
+        for pf_intervention in self.active_interventions:
+            if pf_intervention.intervention:
+                finding_interventions_list.append(pf_intervention.intervention)
+
+        # Include patient examination and patient for context
+        patient_examinations_list = (
+            [self.patient_examination] if self.patient_examination else []
+        )
+        patient_findings_list = cast(
+            "List[PatientFinding]", [self]
+        )  # Include self for direct patient finding evaluations
+
+        return RequirementLinks(
+            findings=findings_list,
+            finding_classifications=finding_classifications_list,
+            finding_classification_choices=finding_classification_choices_list,
+            finding_interventions=finding_interventions_list,
+            patient_examinations=patient_examinations_list,
+            patient_findings=patient_findings_list,
+        )

endoreg_db/models/medical/patient/patient_finding_classification.py

@@ -0,0 +1,231 @@
+import random
+from typing import TYPE_CHECKING, Dict
+
+import numpy as np
+from django.db import models
+
+# Corrected imports for type hints
+if TYPE_CHECKING:
+    from ..finding import (
+        FindingClassification,
+        FindingClassificationChoice,
+    )
+    from .patient_finding import PatientFinding
+
+
+class PatientFindingClassification(models.Model):
+    """Represents basic classifications for specific findings in a patient context.
+    Links a PatientFinding to a specific classification and choice, with optional subcategory values.
+    """
+
+    finding = models.ForeignKey(
+        "PatientFinding", on_delete=models.CASCADE, related_name="classifications"
+    )
+    classification = models.ForeignKey(
+        "FindingClassification",
+        on_delete=models.CASCADE,
+        related_name="patient_finding_classifications",
+    )
+    classification_choice = models.ForeignKey(
+        "FindingClassificationChoice",
+        on_delete=models.CASCADE,
+        related_name="patient_finding_classifications",
+    )
+
+    is_active = models.BooleanField(
+        default=True, help_text="Indicates if the classification is currently active."
+    )
+    subcategories = models.JSONField(blank=True, null=True)
+    numerical_descriptors = models.JSONField(blank=True, null=True)
+
+    if TYPE_CHECKING:
+        finding: models.ForeignKey["PatientFinding"]
+        classification: models.ForeignKey["FindingClassification"]
+        classification_choice: models.ForeignKey["FindingClassificationChoice"]
+
+    class Meta:
+        verbose_name = "Patient Finding Classification"
+        verbose_name_plural = "Patient Finding Classifications"
+        ordering = ["finding", "classification", "classification_choice"]
+
+    def __str__(self):
+        """
+        Return a string representation combining the finding, classification, and classification choice.
+        """
+        return f"{self.finding} - {self.classification} - {self.classification_choice}"
+
+    def save(self, *args, **kwargs):
+        """
+        Saves the model instance after validating and initializing classification-related fields.
+
+        Ensures that the selected classification choice is valid for the associated classification. If subcategories or numerical descriptors are unset, initializes them from the classification choice before saving.
+        """
+        if self.classification_choice not in self.classification.choices.all():
+            raise ValueError("classification_choice must be in classification.choices")
+
+        if not self.subcategories:
+            self.subcategories = self.classification_choice.subcategories
+
+        if not self.numerical_descriptors:
+            self.numerical_descriptors = (
+                self.classification_choice.numerical_descriptors
+            )
+
+        super().save(*args, **kwargs)
+
+    def initialize_and_get_subcategories(self):
+        """
+        Ensure the subcategories field is initialized and return its dictionary.
+
+        Returns:
+            dict: The subcategories associated with this classification.
+        """
+        if not self.subcategories:
+            self.save()
+        return self.subcategories
+
+    def initialize_and_get_descriptors(self):
+        """
+        Return the numerical descriptors dictionary, initializing it if necessary.
+
+        If the `numerical_descriptors` field is empty or uninitialized, the method triggers model initialization and returns the resulting dictionary.
+        """
+        if not self.numerical_descriptors:
+            self.save()
+        return self.numerical_descriptors
+
+    def set_subcategory(
+        self, subcategory_name: str, subcategory_value: Dict[str, dict]
+    ):
+        """
+        Update the value of a specified subcategory and save the classification.
+
+        Parameters:
+            subcategory_name (str): The name of the subcategory to update.
+            subcategory_value (dict): The value to assign to the subcategory.
+
+        Returns:
+            dict: The updated subcategory dictionary.
+        """
+        assert self.subcategories, "Subcategories must be initialized."
+        assert subcategory_name in self.subcategories, (
+            "Subcategory must be in subcategories."
+        )
+        self.subcategories[subcategory_name]["value"] = subcategory_value
+        self.save()
+
+        return self.subcategories[subcategory_name]
+
+    def set_random_subcategories(self):
+        """
+        Assign random values to all required subcategories that do not already have a value.
+
+        For each required subcategory without a value, selects a random option from its available choices, updates the subcategory, saves the model, and returns the updated subcategories dictionary.
+
+        Returns:
+            dict: The updated subcategories with random values assigned where needed.
+        """
+
+        if not self.subcategories or not self.numerical_descriptors:
+            self.save()
+
+        self.refresh_from_db()
+        assert self.subcategories is not None, "Subcategories must be initialized."
+
+        for subcategory_name, subcategory_dict in self.subcategories.items():
+            if subcategory_dict["required"] and not subcategory_dict.get("value", None):
+                subcategory_choice = random.choice(subcategory_dict["choices"])
+                self.subcategories[subcategory_name]["value"] = subcategory_choice
+
+        self.save()
+
+        return self.subcategories
+
+    def get_random_value_for_numerical_descriptor(self, descriptor_name):
+        """
+        Generate a random value for the specified numerical descriptor using its defined distribution parameters.
+
+        Parameters:
+            descriptor_name (str): The name of the numerical descriptor to generate a value for.
+
+        Returns:
+            float: A randomly generated value based on the descriptor's distribution, clipped to its min and max range.
+
+        Raises:
+            ValueError: If the descriptor's distribution type is not supported.
+        """
+        assert self.numerical_descriptors is not None, (
+            "Numerical descriptors must be initialized."
+        )
+        assert descriptor_name in self.numerical_descriptors, (
+            "Descriptor must be in numerical descriptors."
+        )
+        descriptor = self.numerical_descriptors[descriptor_name]
+        min_val = descriptor.get("min", 0)
+        max_val = descriptor.get("max", 1)
+        distribution = descriptor.get("distribution", "normal")
+        if distribution == "normal":
+            mean = descriptor.get("mean", 0.5)
+            std = descriptor.get("std", 0.1)
+            value = np.random.normal(mean, std)
+            # clip value to min and max
+            value = np.clip(value, min_val, max_val)
+        elif distribution == "uniform":
+            value = np.random.uniform(min_val, max_val)
+        else:
+            raise ValueError("Distribution not supported")
+
+        return value
+
+    def set_random_numerical_descriptor(self, descriptor_name, save=True):
+        """
+        Assigns a random value to the specified numerical descriptor and optionally saves the model.
+
+        Parameters:
+            descriptor_name (str): The name of the numerical descriptor to update.
+            save (bool): If True, saves the model after updating the descriptor. Defaults to True.
+
+        Returns:
+            dict: The updated numerical descriptor dictionary with the new random value.
+
+        Raises:
+            ValueError: If the descriptor name is not present in the numerical descriptors.
+        """
+        if descriptor_name not in self.numerical_descriptors:
+            raise ValueError("Descriptor name must be in numerical descriptors.")
+
+        value = self.get_random_value_for_numerical_descriptor(descriptor_name)
+        assert self.numerical_descriptors is not None, (
+            "Numerical descriptors must be initialized."
+        )
+        self.numerical_descriptors[descriptor_name]["value"] = value
+        if save:
+            self.save()
+
+        return self.numerical_descriptors[descriptor_name]
+
+    def set_random_numerical_descriptors(self):
+        """
+        Assigns random values to all numerical descriptors and saves the model.
+
+        Returns:
+            dict: The updated numerical_descriptors dictionary with assigned random values.
+        """
+        if not self.subcategories or not self.numerical_descriptors:
+            self.save()
+
+        assert self.numerical_descriptors is not None, (
+            "Numerical descriptors must be initialized."
+        )
+
+        numerical_descriptors = self.numerical_descriptors
+
+        for (
+            numerical_descriptor_name,
+            _numerical_descriptor_dict,
+        ) in numerical_descriptors.items():
+            self.set_random_numerical_descriptor(numerical_descriptor_name, save=False)
+
+        self.save()
+
+        return self.numerical_descriptors

endoreg_db/models/medical/patient/patient_finding_intervention.py

@@ -0,0 +1,37 @@
+from typing import TYPE_CHECKING
+
+from django.db import models
+
+if TYPE_CHECKING:
+    from ..finding import FindingIntervention
+    from .patient_finding import PatientFinding
+
+
+class PatientFindingIntervention(models.Model):
+    finding = models.ForeignKey(
+        "PatientFinding", on_delete=models.CASCADE, related_name="interventions"
+    )
+    intervention = models.ForeignKey(
+        "FindingIntervention",
+        on_delete=models.CASCADE,
+        related_name="patient_finding_interventions",
+    )
+    is_active = models.BooleanField(
+        default=True, help_text="Indicates if the intervention is currently active."
+    )
+    state = models.CharField(max_length=100, blank=True, null=True)
+    time_start = models.DateTimeField(blank=True, null=True)
+    time_end = models.DateTimeField(blank=True, null=True)
+    date = models.DateField(blank=True, null=True)
+
+    if TYPE_CHECKING:
+        finding: models.ForeignKey["PatientFinding"]
+        intervention: models.ForeignKey["FindingIntervention"]
+
+    def __str__(self):
+        return self.intervention.name
+
+    def natural_key(self):
+        return (self.intervention.name,)
+
+    objects = models.Manager()