endoreg-db 0.6.3__py3-none-any.whl → 0.6.4__py3-none-any.whl

endoreg_db/models/laboratory/lab_value.py

@@ -3,40 +3,59 @@ import warnings
 
 LANG = "de"
 
+
 class LabValueManager(models.Manager):
     def get_by_natural_key(self, name):
+        """
+        Retrieves a model instance by its natural key.
+        
+        This method returns the instance whose unique name matches the provided natural key.
+          
+        Args:
+            name: The unique identifier corresponding to the model's "name" field.
+          
+        Returns:
+            The model instance with a matching name.
+        """
         return self.get(name=name)
 
+
 class LabValue(models.Model):
     name = models.CharField(max_length=255, unique=True)
     name_de = models.CharField(max_length=255, blank=True, null=True)
     name_en = models.CharField(max_length=255, blank=True, null=True)
     abbreviation = models.CharField(max_length=10, blank=True, null=True)
-    default_unit = models.ForeignKey('Unit', on_delete=models.CASCADE, blank=True, null=True)
+    default_unit = models.ForeignKey(
+        "Unit", on_delete=models.CASCADE, blank=True, null=True
+    )
     numeric_precision = models.IntegerField(default=3)
     default_single_categorical_value_distribution = models.ForeignKey(
-        'SingleCategoricalValueDistribution',
+        "SingleCategoricalValueDistribution",
         on_delete=models.CASCADE,
-        blank=True, null=True,
-        related_name='default_single_categorical_value_distribution'
+        blank=True,
+        null=True,
+        related_name="default_single_categorical_value_distribution",
     )
     default_numerical_value_distribution = models.ForeignKey(
-        'NumericValueDistribution',
+        "NumericValueDistribution",
         on_delete=models.CASCADE,
-        blank=True, null=True,
-        related_name='default_numerical_value_distribution'
+        blank=True,
+        null=True,
+        related_name="default_numerical_value_distribution",
     )
     default_multiple_categorical_value_distribution = models.ForeignKey(
-        'MultipleCategoricalValueDistribution',
+        "MultipleCategoricalValueDistribution",
         on_delete=models.CASCADE,
-        blank=True, null=True,
-        related_name='default_multiple_categorical_value_distribution'
+        blank=True,
+        null=True,
+        related_name="default_multiple_categorical_value_distribution",
     )
     default_date_value_distribution = models.ForeignKey(
-        'DateValueDistribution',
+        "DateValueDistribution",
         on_delete=models.CASCADE,
-        blank=True, null=True,
-        related_name='default_date_value_distribution'
+        blank=True,
+        null=True,
+        related_name="default_date_value_distribution",
     )
     default_normal_range = models.JSONField(blank=True, null=True)
     normal_range_age_dependent = models.BooleanField(default=False)
@@ -45,12 +64,32 @@ class LabValue(models.Model):
     objects = LabValueManager()
 
     def natural_key(self):
+        """
+        Return a tuple representing the natural key for this instance.
+        
+        Returns:
+            tuple: A single-element tuple containing the instance's unique name.
+        """
         return (self.name,)
 
     def __str__(self):
-        return self.name
-    
+        """
+        Return the lab value name as a string.
+        
+        Converts the lab value's `name` attribute into its string representation for
+        display purposes.
+        """
+        return str(self.name)
+
     def get_default_default_distribution(self):
+        """
+        Returns the first available default distribution for the lab value.
+        
+        Checks the default distribution fields in the following order:
+        default_single_categorical_value_distribution, default_numerical_value_distribution,
+        default_multiple_categorical_value_distribution, and default_date_value_distribution.
+        If none are set, a warning is issued and None is returned.
+        """
         if self.default_single_categorical_value_distribution:
             return self.default_single_categorical_value_distribution
         elif self.default_numerical_value_distribution:
@@ -62,9 +101,24 @@ class LabValue(models.Model):
         else:
             warnings.warn("No default distribution set for lab value")
             return None
-    
-    def get_normal_range(self, age:int=None, gender=None):
+
+    def get_normal_range(self, age: int = None, gender=None):
+        """
+        Retrieve the normal range for the lab value based on optional age and gender.
+        
+        This method returns the default normal range when the lab value is not age-, gender-, or special-case dependent.
+        For gender-dependent ranges, it uses a gender-specific default range and, if no gender is provided, selects one at random with a warning.
+        Note that age-dependent and special-case normal ranges are not implemented and will issue warnings when invoked.
+        
+        Args:
+            age (int, optional): The age in years used for age-dependent range computation.
+            gender (Gender, optional): The gender instance used for gender-dependent range computation.
+        
+        Returns:
+            dict: A dictionary with 'min' and 'max' keys indicating the lower and upper bounds of the normal range.
+        """
         from endoreg_db.models import Gender
+
         assert isinstance(age, int) or age is None
         assert isinstance(gender, Gender) or gender is None
 
@@ -75,37 +129,34 @@ class LabValue(models.Model):
         min_value = None
         max_value = None
 
-        if not age_dependent and \
-        not gender_dependent and \
-        not special_case:
-            min_value = self.default_normal_range.get('min', None)
-            max_value = self.default_normal_range.get('max', None)
+        if not age_dependent and not gender_dependent and not special_case:
+            min_value = self.default_normal_range.get("min", None)
+            max_value = self.default_normal_range.get("max", None)
 
-        if age_dependent: 
+        if age_dependent:
             # get normal range for age)
             warnings.warn("Age dependent normal range not implemented yet")
             pass
-        
+
         if gender_dependent:
             if not gender:
-                warnings.warn("Calling get_normal_range with gender_dependent=True requires gender to be set, choosing by random")
+                warnings.warn(
+                    "Calling get_normal_range with gender_dependent=True requires gender to be set, choosing by random"
+                )
                 # set gender to either "male" or "female"
                 from random import choice
+
                 choices = ["male", "female"]
                 gender = choice(choices)
 
             default_range_dict = self.default_normal_range.get(gender.name, {})
-            min_value = default_range_dict.get('min', None)
-            max_value = default_range_dict.get('max', None)
+            min_value = default_range_dict.get("min", None)
+            max_value = default_range_dict.get("max", None)
 
         if special_case:
             # get normal range for special case
             warnings.warn("Special case normal range not implemented yet")
 
-        normal_range_dict = {
-            "min": min_value,
-            "max": max_value
-        }
+        normal_range_dict = {"min": min_value, "max": max_value}
 
         return normal_range_dict
-

endoreg_db/models/requirement/__init__.py

@@ -0,0 +1,11 @@
+from .requirement import Requirement, RequirementType
+from .requirement_operator import RequirementOperator
+from .requirement_set import RequirementSet, RequirementSetType
+
+__all__ = [
+    "Requirement",
+    "RequirementType",
+    "RequirementOperator",
+    "RequirementSet",
+    "RequirementSetType",
+]

endoreg_db/models/requirement/requirement.py

@@ -0,0 +1,325 @@
+from django.db import models
+from typing import TYPE_CHECKING, Optional
+
+from pydantic import BaseModel
+
+QuerySet = models.QuerySet
+
+if TYPE_CHECKING:
+    from endoreg_db.models import (
+        RequirementOperator,
+        RequirementSet,
+        Examination,
+        ExaminationIndication,
+        LabValue,
+        Disease,
+        DiseaseClassificationChoice,
+        Event,
+        Finding,
+        FindingMorphologyClassificationChoice,
+        FindingLocationClassificationChoice,
+        FindingIntervention,
+    )
+
+
+class RequirementsModelDict(BaseModel):
+    """
+    A class representing a dictionary of models related to a requirement.
+
+    Attributes:
+        requirement_types (QuerySet[RequirementType]): A queryset of requirement types.
+        operators (QuerySet[RequirementOperator]): A queryset of operators.
+        requirement_sets (QuerySet[RequirementSet]): A queryset of requirement sets.
+        examinations (QuerySet[Examination]): A queryset of examinations.
+        examination_indications (QuerySet[ExaminationIndication]): A queryset of examination indications.
+        lab_values (QuerySet[LabValue]): A queryset of lab values.
+        diseases (QuerySet[Disease]): A queryset of diseases.
+        disease_classification_choices (QuerySet[DiseaseClassificationChoice]): A queryset of disease classification choices.
+        events (QuerySet[Event]): A queryset of events.
+        findings (QuerySet[Finding]): A queryset of findings.
+        finding_morphology_classification_choices (QuerySet[FindingMorphologyClassificationChoice]): A queryset of finding morphology classification choices.
+        finding_location_classification_choices (QuerySet[FindingLocationClassificationChoice]): A queryset of finding location classification choices.
+        finding_interventions (QuerySet[FindingIntervention]): A queryset of finding interventions.
+    """
+
+    model_config = {"arbitrary_types_allowed": True}
+    requirement_types: Optional[QuerySet["RequirementType"]] = None
+    operators: Optional[QuerySet["RequirementOperator"]] = None
+    requirement_sets: Optional[QuerySet["RequirementSet"]] = None
+    examinations: Optional[QuerySet["Examination"]] = None
+    examination_indications: Optional[QuerySet["ExaminationIndication"]] = None
+    lab_values: Optional[QuerySet["LabValue"]] = None
+    diseases: Optional[QuerySet["Disease"]] = None
+    disease_classification_choices: Optional[
+        QuerySet["DiseaseClassificationChoice"]
+    ] = None
+    events: Optional[QuerySet["Event"]] = None
+    findings: Optional[QuerySet["Finding"]] = None
+    finding_morphology_classification_choices: Optional[
+        QuerySet["FindingMorphologyClassificationChoice"]
+    ] = None
+    finding_location_classification_choices: Optional[
+        QuerySet["FindingLocationClassificationChoice"]
+    ] = None
+    finding_interventions: Optional[QuerySet["FindingIntervention"]] = None
+
+
+class RequirementTypeManager(models.Manager):
+    def get_by_natural_key(self, name):
+        """
+        Retrieve a model instance using its natural key.
+
+        Queries the database for an instance with a matching name, serving as the natural key.
+
+        Args:
+            name: The natural key identifying the model instance.
+
+        Returns:
+            The model instance matching the provided natural key.
+        """
+        return self.get(name=name)
+
+
+class RequirementType(models.Model):
+    """
+    A class representing a type of requirement.
+
+    Attributes:
+        name (str): The name of the requirement type.
+        name_de (str): The German name of the requirement type.
+        name_en (str): The English name of the requirement type.
+    """
+
+    name = models.CharField(max_length=100, unique=True)
+    name_de = models.CharField(max_length=100, blank=True, null=True)
+    name_en = models.CharField(max_length=100, blank=True, null=True)
+    description = models.TextField(blank=True, null=True)
+
+    objects = RequirementTypeManager()
+
+    def natural_key(self):
+        """
+        Return the natural key for the instance as a tuple containing its name.
+
+        This tuple enables the use of natural key lookups for serialization and deserialization.
+        """
+        return (self.name,)
+
+    def __str__(self):
+        """Return the string representation of the requirement type's name.
+
+        Returns:
+            str: The name of the requirement type.
+        """
+        return str(self.name)
+
+
+class RequirementManager(models.Manager):
+    def get_by_natural_key(self, name):
+        """
+        Retrieve an instance using its natural key.
+
+        Args:
+            name: The natural key used to look up the instance.
+
+        Returns:
+            The object whose 'name' field matches the given key.
+        """
+        return self.get(name=name)
+
+
+class Requirement(models.Model):
+    """
+    A class representing a requirement.
+
+    Attributes:
+        name (str): The name of the requirement.
+        name_de (str): The German name of the requirement.
+        name_en (str): The English name of the requirement.
+        description (str): A description of the requirement.
+    """
+
+    name = models.CharField(max_length=100, unique=True)
+    name_de = models.CharField(max_length=100, blank=True, null=True)
+    name_en = models.CharField(max_length=100, blank=True, null=True)
+    description = models.TextField(blank=True, null=True)
+    numeric_value = models.FloatField(
+        blank=True,
+        null=True,
+        help_text="Numeric value for the requirement. If not set, the requirement is not used in calculations.",
+    )
+
+    numeric_value_min = models.FloatField(
+        blank=True,
+        null=True,
+        help_text="Minimum numeric value for the requirement. If not set, the requirement is not used in calculations.",
+    )
+    numeric_value_max = models.FloatField(
+        blank=True,
+        null=True,
+        help_text="Maximum numeric value for the requirement. If not set, the requirement is not used in calculations.",
+    )
+
+    string_value = models.CharField(
+        max_length=100,
+        blank=True,
+        null=True,
+        help_text="String value for the requirement. If not set, the requirement is not used in calculations.",
+    )
+
+    string_values = models.TextField(
+        blank=True,
+        null=True,
+        help_text=" ','-separated list of string values for the requirement.If not set, the requirement is not used in calculations.",
+    )
+
+    objects = RequirementManager()
+
+    requirement_types = models.ManyToManyField(
+        "RequirementType",
+        blank=True,
+        related_name="linked_requirements",
+    )
+
+    operators = models.ManyToManyField(
+        "RequirementOperator",
+        blank=True,
+        related_name="required_in",
+    )
+
+    unit = models.ForeignKey(
+        "Unit",
+        on_delete=models.CASCADE,
+        related_name="required_in",
+        blank=True,
+        null=True,
+    )
+
+    examinations = models.ManyToManyField(
+        "Examination",
+        blank=True,
+        related_name="required_in",
+    )
+
+    examination_indications = models.ManyToManyField(
+        "ExaminationIndication",
+        blank=True,
+        related_name="required_in",
+    )
+
+    diseases = models.ManyToManyField(
+        "Disease",
+        blank=True,
+        related_name="required_in",
+    )
+
+    disease_classification_choices = models.ManyToManyField(
+        "DiseaseClassificationChoice",
+        blank=True,
+        related_name="required_in",
+    )
+
+    events = models.ManyToManyField(
+        "Event",
+        blank=True,
+        related_name="required_in",
+    )
+
+    lab_values = models.ManyToManyField(
+        "LabValue",
+        blank=True,
+        related_name="required_in",
+    )
+
+    findings = models.ManyToManyField(
+        "Finding",
+        blank=True,
+        related_name="required_in",
+    )
+
+    finding_morphology_classification_choices = models.ManyToManyField(
+        "FindingMorphologyClassificationChoice",
+        blank=True,
+        related_name="required_in",
+    )
+
+    finding_location_classification_choices = models.ManyToManyField(
+        "FindingLocationClassificationChoice",
+        blank=True,
+        related_name="required_in",
+    )
+
+    finding_interventions = models.ManyToManyField(
+        "FindingIntervention",
+        blank=True,
+        related_name="required_in",
+    )
+
+    if TYPE_CHECKING:
+        requirement_types: models.QuerySet[RequirementType]
+        operators: models.QuerySet[RequirementOperator]
+        requirement_sets: models.QuerySet[RequirementSet]
+        examinations: models.QuerySet[Examination]
+        examination_indications: models.QuerySet[ExaminationIndication]
+        lab_values: models.QuerySet[LabValue]
+        diseases: models.QuerySet[Disease]
+        disease_classification_choices: models.QuerySet[DiseaseClassificationChoice]
+        events: models.QuerySet[Event]
+        findings: models.QuerySet[Finding]
+        finding_morphology_classification_choices: models.QuerySet[
+            FindingMorphologyClassificationChoice
+        ]
+        finding_location_classification_choices: models.QuerySet[
+            FindingLocationClassificationChoice
+        ]
+        finding_interventions: models.QuerySet[FindingIntervention]
+
+    def natural_key(self):
+        """
+        Return a tuple containing the natural key of the instance.
+
+        The tuple, comprised solely of the instance's name, serves as an alternative unique identifier for serialization.
+        """
+        return (self.name,)
+
+    def __str__(self):
+        """Return the string representation of the requirement's name.
+
+        Returns:
+            str: The name of the requirement.
+        """
+        return str(self.name)
+
+    def get_models_dict(self) -> RequirementsModelDict:
+        """
+        Returns a RequirementsModelDict with querysets of all associated models.
+
+        This method aggregates related models by invoking .all() on each
+        many-to-many field of the requirement. The resulting RequirementsModelDict
+        includes querysets for requirement types, operators, requirement sets,
+        examinations, examination indications, lab values, diseases, disease
+        classification choices, events, findings, finding morphology classification
+        choices, finding location classification choices, and finding interventions.
+        """
+        models_dict = RequirementsModelDict(
+            requirement_types=self.requirement_types.all(),
+            operators=self.operators.all(),
+            requirement_sets=self.requirement_sets.all(),
+            examinations=self.examinations.all(),
+            examination_indications=self.examination_indications.all(),
+            lab_values=self.lab_values.all(),
+            diseases=self.diseases.all(),
+            disease_classification_choices=self.disease_classification_choices.all(),
+            events=self.events.all(),
+            findings=self.findings.all(),
+            finding_morphology_classification_choices=self.finding_morphology_classification_choices.all(),
+            finding_location_classification_choices=self.finding_location_classification_choices.all(),
+            finding_interventions=self.finding_interventions.all(),
+        )
+        return models_dict
+    
+    def evaluate(self, **kwargs):
+        #TODO refactor after prototyping
+        # from .requirement_evaluation.requirement_type_parser import get_input_data
+
+        return_value = True

endoreg_db/models/requirement/requirement_evaluation/__init__.py

@@ -0,0 +1,134 @@
+from typing import Optional
+from endoreg_db.models import (
+    Patient,
+    PatientExamination,
+    Finding,
+    FindingIntervention,
+    FindingLocationClassification,
+    Requirement,
+)
+
+
+def get_kwargs_by_req_type_and_operator(requirement, **kwargs):
+    """
+    Extract keyword arguments based on the requirement's type and operator.
+    
+    This function inspects the provided requirement to determine which keyword arguments are relevant
+    for its evaluation. It constructs and returns a dictionary of arguments suitable for processing the
+    requirement with its associated operator.
+    
+    Args:
+        requirement: The requirement instance used to identify the applicable parameters.
+        **kwargs: Additional keyword arguments that may include values required for evaluation.
+    
+    Returns:
+        A dictionary mapping relevant parameter names to their corresponding values.
+    """
+    pass
+
+
+def models_match_all(requirement: Requirement, **kwargs):
+    """
+    Match all models for a given requirement.
+    
+    Retrieves the models dictionary from the requirement by calling its get_models_dict() method.
+    Additional keyword arguments are accepted for future extensions. Note that this function
+    currently only extracts the models without performing any matching logic.
+    """
+    models_dict = requirement.get_models_dict()
+
+
+SUPPORTED_REQUIREMENT_TYPES = ["patient_examination", "patient"]
+SUPPORTED_OPERATORS = {
+    "models_match_all": models_match_all,
+}
+
+
+def get_operator_function(operator_name):
+    """
+    Retrieves the operator function for the given operator name.
+    
+    This function looks up the operator name in the supported operators mapping
+    and returns the corresponding operator function used for evaluating requirements.
+    If the operator name is not recognized, the behavior is undefined.
+     
+    Args:
+        operator_name: The name of the operator to retrieve.
+    
+    Returns:
+        The operator function associated with the operator name.
+    """
+    pass
+
+
+def get_values_from_kwargs(
+    requirement: Requirement,
+    patient: Optional[Patient] = None,
+    patient_examination: Optional[PatientExamination] = None,
+    **kwargs,
+) -> dict:
+    """
+    Extracts and validates values for requirement evaluation.
+    
+    This function aggregates values from keyword arguments along with
+    the 'patient' and 'patient_examination' inputs based on the requirement's types.
+    It verifies that all requirement types are supported—currently, only types like
+    'patient_examination' and 'patient' are allowed—and ensures that the corresponding
+    parameters are provided when required. A ValueError is raised if an unsupported
+    requirement type is encountered or if a required parameter is missing.
+    
+    Args:
+        requirement (Requirement): The evaluation criterion containing requirement types.
+        patient (Optional[Patient]): Patient details, required if the requirement includes 'patient'.
+        patient_examination (Optional[PatientExamination]): Examination details, required if the requirement includes 'patient_examination'.
+        **kwargs: Additional keyword arguments for the evaluation.
+    
+    Raises:
+        ValueError: If a requirement type is unsupported or a necessary parameter is missing.
+    
+    Returns:
+        dict: A dictionary combining 'patient', 'patient_examination', and additional keyword arguments.
+    """
+    requirement_types = [_.name for _ in requirement.requirement_types]
+    # operators = [_.name for _ in requirement.operators]  # Uncomment when needed
+
+    for requirement_type in requirement_types:
+        if requirement_type not in SUPPORTED_REQUIREMENT_TYPES:
+            raise ValueError(f"Unsupported requirement type: {requirement_type}")
+
+    if "patient_examination" in requirement_types:
+        if patient_examination is None:
+            raise ValueError(
+                "patient_examination is required for this requirement type"
+            )
+
+    if "patient" in requirement_types:
+        if patient is None:
+            raise ValueError("patient is required for this requirement type")
+
+    # Prepare and return the extracted values
+    return {"patient": patient, "patient_examination": patient_examination, **kwargs}
+
+
+def evaluate_requirement(
+    requirement: Requirement,
+    **kwargs,
+):
+    """
+    Evaluates the given requirement against provided parameters.
+    
+    This function determines if the requirement is met based on its type and
+    the additional evaluation inputs supplied via keyword arguments. Evaluation
+    may depend on context-specific data, such as patient or examination details,
+    as required by the requirement.
+    
+    Args:
+        requirement (Requirement): The requirement to evaluate.
+        **kwargs: Additional parameters that support the evaluation process.
+    
+    Returns:
+        bool: True if the requirement is met, False otherwise.
+    """
+    # Implement the logic to evaluate the requirement based on its type
+    # and the provided keyword arguments.
+    pass