clinicedc 2.0.1__py3-none-any.whl → 2.0.3__py3-none-any.whl

edc_egfr/calculators/base_egrfr.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from edc_constants.constants import FEMALE, MALE
+from edc_reportable import MICROMOLES_PER_LITER, MILLIGRAMS_PER_DECILITER
+from edc_reportable.utils import convert_units
+
+
+class EgfrCalculatorError(Exception):
+    pass
+
+
+class BaseEgfr:
+    def __init__(
+        self,
+        gender: str | None = None,
+        age_in_years: int | float | None = None,
+        creatinine_value: float | int | None = None,
+        creatinine_units: str | None = None,
+        **kwargs,  # noqa
+    ):
+        """Expects creatinine (scr) in umols/L.
+
+        Converts to creatinine to mg/dL for the calculation.
+        """
+        self.scr = {}
+        if not gender or gender not in [MALE, FEMALE]:
+            raise EgfrCalculatorError(
+                f"Invalid gender. Expected one of {MALE}, {FEMALE}. Got {gender}."
+            )
+        self.gender = gender
+        if not (18 <= (age_in_years or 0) < 120):
+            raise EgfrCalculatorError(
+                f"Invalid age. See {self.__class__.__name__}. Got {age_in_years}"
+            )
+        self.age_in_years = float(age_in_years) if age_in_years else None
+        if creatinine_value and creatinine_units:
+            self.scr.update(
+                {
+                    MILLIGRAMS_PER_DECILITER: convert_units(
+                        label="creatinine",
+                        value=float(creatinine_value),
+                        units_from=creatinine_units,
+                        units_to=MILLIGRAMS_PER_DECILITER,
+                    )
+                }
+            )
+            self.scr.update(
+                {
+                    MICROMOLES_PER_LITER: convert_units(
+                        label="creatinine",
+                        value=float(creatinine_value),
+                        units_from=creatinine_units,
+                        units_to=MICROMOLES_PER_LITER,
+                    )
+                }
+            )

edc_egfr/calculators/egfr_ckd_epi.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from edc_constants.constants import BLACK, FEMALE
+from edc_reportable import MILLIGRAMS_PER_DECILITER
+
+from .base_egrfr import BaseEgfr, EgfrCalculatorError
+
+# TODO: https://www.rcpa.edu.au/Manuals/RCPA-Manual/
+#  Pathology-Tests/C/Creatinine-clearance-Cockcroft-and-Gault
+
+
+class EgfrCkdEpi(BaseEgfr):
+    """Reference https://nephron.com/epi_equation
+
+    CKD-EPI Creatinine equation (2009)
+
+    Levey AS, Stevens LA, et al. A New Equation to Estimate Glomerular
+    Filtration Rate. Ann Intern Med. 2009; 150:604-612.
+    """
+
+    def __init__(self, ethnicity: str = None, **kwargs):
+        self.ethnicity = ethnicity
+        super().__init__(**kwargs)
+
+    @property
+    def value(self) -> float | None:
+        if (
+            self.gender
+            and self.age_in_years
+            and self.ethnicity
+            and self.scr.get(MILLIGRAMS_PER_DECILITER)
+        ):
+            scr = self.scr.get(MILLIGRAMS_PER_DECILITER)
+            return float(
+                141.000
+                * (min(scr / self.kappa, 1.000) ** self.alpha)
+                * (max(scr / self.kappa, 1.000) ** -1.209)
+                * self.age_factor
+                * self.gender_factor
+                * self.ethnicity_factor
+            )
+        opts = dict(
+            gender=self.gender,
+            age_in_years=self.age_in_years,
+            ethnicity=self.ethnicity,
+            scr=self.scr.get(MILLIGRAMS_PER_DECILITER),
+        )
+        raise EgfrCalculatorError(f"Unable to calculate. Insufficient information. Got {opts}")
+
+    @property
+    def alpha(self) -> float:
+        return float(-0.329 if self.gender == FEMALE else -0.411)
+
+    @property
+    def kappa(self) -> float:
+        return float(0.7 if self.gender == FEMALE else 0.9)
+
+    @property
+    def ethnicity_factor(self) -> float:
+        return float(1.159 if self.ethnicity == BLACK else 1.000)
+
+    @property
+    def gender_factor(self) -> float:
+        return float(1.018 if self.gender == FEMALE else 1.000)
+
+    @property
+    def age_factor(self) -> float:
+        return float(0.993**self.age_in_years)

edc_egfr/calculators/egfr_cockcroft_gault.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from decimal import Decimal
+
+from edc_constants.constants import FEMALE
+from edc_reportable import MICROMOLES_PER_LITER
+
+from .base_egrfr import BaseEgfr, EgfrCalculatorError
+
+
+class EgfrCockcroftGault(BaseEgfr):
+    """Reference https://www.mdcalc.com/creatinine-clearance-cockcroft-gault-equation
+
+    Cockcroft-Gault
+
+    eGFR (mL/min) = { (140 – age (years)) x weight (kg) x constant*} /
+    serum creatinine (μmol/L)
+    *constant = 1.23 for males and 1.05 for females
+
+    Cockcroft-Gault CrCl, mL/min =
+        (140 – age) × (weight, kg) × (0.85 if female) / (72 × SCr(mg/dL))
+
+    or:
+
+    https://www.ncbi.nlm.nih.gov/pmc/articles/PMC2763564/
+
+    GFR = 141 × min(Scr/κ, 1)α × max(Scr/κ, 1)-1.209 × 0.993Age
+    """
+
+    def __init__(self, weight: int | float | Decimal = None, **kwargs):
+        self.weight = float(weight) if weight else None
+        super().__init__(**kwargs)
+
+    @property
+    def value(self) -> float:
+        """Returns the eGFR value or raises.
+
+        eGFR (mL/min) = { (140 – age (years)) x weight (kg) x constant*} /
+        serum creatinine (μmol/L)
+
+        *constant = 1.23 for males and 1.05 for females
+        """
+        if (
+            self.gender
+            and self.age_in_years
+            and self.weight
+            and self.scr.get(MICROMOLES_PER_LITER)
+        ):
+            gender_factor = 1.05 if self.gender == FEMALE else 1.23
+            adjusted_age = 140.00 - self.age_in_years
+            value = (adjusted_age * self.weight * gender_factor) / float(
+                self.scr.get(MICROMOLES_PER_LITER)
+            )
+            return value
+        opts = dict(
+            gender=self.gender,
+            age_in_years=self.age_in_years,
+            weight=self.weight,
+            scr=self.scr.get(MICROMOLES_PER_LITER),
+        )
+        raise EgfrCalculatorError(
+            f"Unable to calculate egfr_value. Insufficient information. Got {opts}."
+        )

edc_egfr/calculators/percent_change.py

@@ -0,0 +1,7 @@
+def egfr_percent_change(egfr_value: float, baseline_egfr_value: float) -> float:
+    """Returns the percent change from baseline"""
+    if egfr_value and baseline_egfr_value:
+        return 100 * (
+            (float(baseline_egfr_value) - float(egfr_value)) / float(baseline_egfr_value)
+        )
+    return 0.0

edc_egfr/constants.py

@@ -0,0 +1 @@
+EGFR_DROP_NOTIFICATION_ACTION = "egfr_notification_action"

edc_egfr/egfr.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+from datetime import date, datetime
+from decimal import Decimal
+from typing import TYPE_CHECKING, Any, Optional
+from zoneinfo import ZoneInfo
+
+from dateutil.relativedelta import relativedelta
+from django.core.exceptions import ObjectDoesNotExist
+from django.db import transaction
+
+from edc_constants.constants import NEW
+from edc_reportable.models import ReferenceRangeCollection
+from edc_reportable.units import EGFR_UNITS, PERCENT
+from edc_reportable.utils import get_grade_for_value
+from edc_utils import age, get_utcnow
+
+from .calculators import EgfrCkdEpi, EgfrCockcroftGault, egfr_percent_change
+from .get_drop_notification_model import get_egfr_drop_notification_model_cls
+
+if TYPE_CHECKING:
+    from edc_visit_tracking.typing_stubs import RelatedVisitProtocol
+
+
+class EgfrError(Exception):
+    pass
+
+
+class Egfr:
+    calculators: dict = {"ckd-epi": EgfrCkdEpi, "cockcroft-gault": EgfrCockcroftGault}
+
+    def __init__(
+        self,
+        baseline_egfr_value: Decimal | float | None = None,
+        gender: str | None = None,
+        ethnicity: str | None = None,
+        age_in_years: int | None = None,
+        dob: date | None = None,
+        weight_in_kgs: Decimal | float | None = None,
+        report_datetime: datetime | None = None,
+        creatinine_value: Decimal | float | None = None,
+        creatinine_units: str | None = None,
+        formula_name: str | None = None,
+        value_threshold: Decimal | float | None = None,
+        percent_drop_threshold: Decimal | float | None = None,
+        reference_range_collection: ReferenceRangeCollection | None = None,
+        reference_range_collection_name: str | None = None,
+        calling_crf: Any | None = None,
+        related_visit: RelatedVisitProtocol | None = None,
+        assay_datetime: datetime | None = None,
+        egfr_drop_notification_model: str | None = None,
+    ):
+        self._egfr_value: Decimal | None = None
+        self._egfr_grade = None
+        self._egfr_drop_value: Decimal | None = None
+        self._egfr_drop_grade = None
+        self.assay_date: date | None = None
+        self.related_visit = None
+
+        self.baseline_egfr_value = baseline_egfr_value
+        if formula_name not in self.calculators:
+            raise EgfrError(
+                f"Invalid formula_name. Expected one of {list(self.calculators.keys())}. "
+                f"Got {formula_name}."
+            )
+        else:
+            self.calculator_cls = self.calculators.get(formula_name)
+        self.age_in_years = age_in_years
+        self.dob = dob
+        self.weight_in_kgs = weight_in_kgs
+        self.egfr_drop_notification_model = egfr_drop_notification_model
+        self.egfr_drop_units = PERCENT
+        self.egfr_units = EGFR_UNITS
+        self.ethnicity = ethnicity
+        self.gender = gender
+        if not reference_range_collection:
+            try:
+                self.reference_range_collection = ReferenceRangeCollection.objects.get(
+                    name=reference_range_collection_name
+                )
+            except ObjectDoesNotExist as e:
+                raise ObjectDoesNotExist(f"{e} Got {reference_range_collection_name}")
+        else:
+            self.reference_range_collection = reference_range_collection
+        self.report_datetime = report_datetime
+        self.value_threshold = value_threshold
+        self.percent_drop_threshold = percent_drop_threshold
+
+        if self.dob:
+            self.age_in_years = age(
+                born=self.dob,
+                reference_dt=self.report_datetime.astimezone(ZoneInfo("UTC")),
+            ).years
+        elif not self.dob and self.age_in_years:
+            self.dob = (
+                self.report_datetime.astimezone(ZoneInfo("UTC"))
+                - relativedelta(years=self.age_in_years)
+            ).date()
+        else:
+            raise EgfrError("Expected `age_in_years` or `dob`. Got None for both.")
+
+        if calling_crf:
+            self.creatinine_units = calling_crf.creatinine_units
+            self.creatinine_value = calling_crf.creatinine_value
+            self.percent_drop_threshold = calling_crf.percent_drop_threshold
+            self.related_visit = calling_crf.related_visit
+            self.report_datetime = calling_crf.report_datetime
+            self.assay_date = calling_crf.assay_datetime.astimezone(ZoneInfo("UTC")).date()
+        else:
+            self.creatinine_units = creatinine_units
+            self.creatinine_value = creatinine_value
+            self.percent_drop_threshold = percent_drop_threshold
+            self.related_visit = related_visit
+            self.report_datetime = report_datetime
+            if assay_datetime:
+                self.assay_date = assay_datetime.astimezone(ZoneInfo("UTC")).date()
+
+        if self.percent_drop_threshold is not None and self.percent_drop_threshold < 1.0:
+            raise EgfrError(
+                "Attr `percent_drop_threshold` should be a percentage. "
+                f"Got {self.percent_drop_threshold}"
+            )
+
+        self.on_value_threshold_reached()
+
+        self.on_percent_drop_threshold_reached()
+
+    def on_value_threshold_reached(self) -> None:
+        """A hook to respond if egfr value is at or beyond the value
+        threshold.
+        """
+        pass
+
+    def on_percent_drop_threshold_reached(self) -> None:
+        """A hook to respond if egfr percent drop from baseline
+        is at or beyond the percent drop threshold.
+        """
+        if self.egfr_drop_value and self.percent_drop_threshold is not None:
+            if self.egfr_drop_value >= self.percent_drop_threshold:
+                self.create_or_update_egfr_drop_notification()
+
+    @property
+    def egfr_value(self) -> float:
+        if self._egfr_value is None:
+            self._egfr_value = self.calculator_cls(
+                gender=self.gender,
+                ethnicity=self.ethnicity,
+                age_in_years=self.age_in_years,
+                creatinine_value=self.creatinine_value,
+                creatinine_units=self.creatinine_units,
+                weight=self.get_weight_in_kgs(),
+            ).value
+        return self._egfr_value
+
+    @property
+    def egfr_grade(self) -> Optional[int]:
+        if self._egfr_grade is None:
+            grading_data, _ = get_grade_for_value(
+                self.reference_range_collection,
+                value=self.egfr_value,
+                label="egfr",
+                gender=self.gender,
+                dob=self.dob,
+                report_datetime=self.report_datetime,
+                units=self.egfr_units,
+                age_units="years",
+            )
+            if grading_data:
+                self._egfr_grade = grading_data.grade
+        return self._egfr_grade
+
+    @property
+    def egfr_drop_value(self) -> float:
+        if self._egfr_drop_value is None:
+            if self.baseline_egfr_value:
+                egfr_drop_value = egfr_percent_change(
+                    float(self.egfr_value), float(self.baseline_egfr_value)
+                )
+            else:
+                egfr_drop_value = 0.0000
+            self._egfr_drop_value = 0.0000 if egfr_drop_value < 0.0000 else egfr_drop_value
+        return self._egfr_drop_value
+
+    @property
+    def egfr_drop_grade(self) -> Optional[int]:
+        if self._egfr_drop_grade is None:
+            grading_data, _ = get_grade_for_value(
+                self.reference_range_collection,
+                value=self.egfr_drop_value,
+                label="egfr_drop",
+                gender=self.gender,
+                dob=self.dob,
+                report_datetime=self.report_datetime,
+                units=self.egfr_drop_units,
+                age_units="years",
+            )
+            if grading_data:
+                self._egfr_drop_grade = grading_data.grade
+        return self._egfr_drop_grade
+
+    def get_weight_in_kgs(self) -> Optional[float]:
+        return self.weight_in_kgs
+
+    def create_or_update_egfr_drop_notification(self):
+        """Creates or updates the `eGFR notification model`"""
+        with transaction.atomic():
+            try:
+                obj = self.egfr_drop_notification_model_cls.objects.get(
+                    subject_visit__id=self.related_visit.id
+                )
+            except ObjectDoesNotExist:
+                obj = self.egfr_drop_notification_model_cls.objects.create(
+                    subject_visit_id=self.related_visit.id,
+                    report_datetime=self.report_datetime,
+                    egfr_value=self.egfr_value,
+                    creatinine_date=self.assay_date,
+                    creatinine_value=self.creatinine_value,
+                    creatinine_units=self.creatinine_units,
+                    weight=self.get_weight_in_kgs(),
+                    egfr_percent_change=self.egfr_drop_value,
+                    report_status=NEW,
+                    site_id=self.related_visit.site.id,
+                )
+            else:
+                obj.egfr_value = self.egfr_value
+                obj.creatinine_value = self.creatinine_value
+                obj.weight = self.get_weight_in_kgs()
+                obj.egfr_percent_change = self.egfr_drop_value
+                obj.creatinine_date = self.assay_date
+                obj.modified = get_utcnow()
+                obj.save()
+        obj.refresh_from_db()
+        return obj
+
+    @property
+    def egfr_drop_notification_model_cls(self):
+        return get_egfr_drop_notification_model_cls()

edc_egfr/form_validator_mixins/__init__.py

@@ -0,0 +1,4 @@
+from .egfr_form_validator_mixins import (
+    EgfrCkdEpiFormValidatorMixin,
+    EgfrCockcroftGaultFormValidatorMixin,
+)

edc_egfr/form_validator_mixins/egfr_form_validator_mixins.py

@@ -0,0 +1,55 @@
+from django import forms
+
+from edc_form_validators import INVALID_ERROR
+from edc_reportable import ConversionNotHandled
+from edc_vitals.calculators import CalculatorError
+
+from ..calculators import EgfrCalculatorError, EgfrCkdEpi, EgfrCockcroftGault
+
+
+class EgfrCkdEpiFormValidatorMixin:
+    def validate_egfr(
+        self,
+        gender: str = None,
+        age_in_years: int = None,
+        weight_in_kgs: float = None,
+        ethnicity: str = None,
+        baseline_egfr_value: float | None = None,
+    ):
+        opts = dict(
+            gender=gender,
+            age_in_years=age_in_years,
+            weight=weight_in_kgs,
+            ethnicity=ethnicity,
+            creatinine_value=self.cleaned_data.get("creatinine_value"),
+            creatinine_units=self.cleaned_data.get("creatinine_units"),
+            baseline_egfr_value=baseline_egfr_value,
+        )
+        try:
+            value = EgfrCkdEpi(**opts).value
+        except (EgfrCalculatorError, CalculatorError, ConversionNotHandled) as e:
+            raise forms.ValidationError(e)
+        return value
+
+
+class EgfrCockcroftGaultFormValidatorMixin:
+    def validate_egfr(
+        self,
+        gender: str = None,
+        age_in_years: int = None,
+        weight_in_kgs: float = None,
+        ethnicity: str = None,
+    ):
+        opts = dict(
+            gender=gender,
+            age_in_years=age_in_years,
+            weight=weight_in_kgs,
+            ethnicity=ethnicity,
+            creatinine_value=self.cleaned_data.get("creatinine_value"),
+            creatinine_units=self.cleaned_data.get("creatinine_units"),
+        )
+        try:
+            value = EgfrCockcroftGault(**opts).value
+        except (EgfrCalculatorError, CalculatorError, ConversionNotHandled) as e:
+            self.raise_validation_error({"__all__": str(e)}, INVALID_ERROR)
+        return value

edc_egfr/get_drop_notification_model.py

@@ -0,0 +1,10 @@
+from django.apps import apps as django_apps
+from django.conf import settings
+
+
+def get_egfr_drop_notification_model():
+    return getattr(settings, "EDC_EGFR_DROP_NOTIFICATION_MODEL")
+
+
+def get_egfr_drop_notification_model_cls():
+    return django_apps.get_model(get_egfr_drop_notification_model())

edc_egfr/get_egfr_for_subject.py

@@ -0,0 +1,31 @@
+from datetime import date, datetime
+
+from .egfr import Egfr
+
+
+def get_egfr_for_subject(
+    creatinine_value: float = None,
+    creatinine_units: str = None,
+    assay_datetime: datetime = None,
+    dob: date = None,
+    gender: str = None,
+    ethnicity: str = None,
+    report_datetime: datetime = None,
+    baseline_egfr_value: float | None = None,
+    value_threshold: float | None = None,
+    percent_drop_threshold: float | None = None,
+):
+    return Egfr(
+        percent_drop_threshold=percent_drop_threshold or 20.0000,
+        dob=dob,
+        gender=gender,
+        ethnicity=ethnicity,
+        value_threshold=value_threshold or 45.0000,
+        report_datetime=report_datetime,
+        baseline_egfr_value=baseline_egfr_value,
+        formula_name="ckd-epi",
+        reference_range_collection_name="meta",
+        creatinine_units=creatinine_units,
+        creatinine_value=creatinine_value,
+        assay_datetime=assay_datetime,
+    )

edc_egfr/model_mixins/__init__.py

@@ -0,0 +1,2 @@
+from .egfr_drop_notification_model_mixin import EgfrDropNotificationModelMixin
+from .egfr_model_mixin import EgfrModelMixin

edc_egfr/model_mixins/egfr_drop_notification_model_mixin.py

@@ -0,0 +1,63 @@
+from django.db import models
+
+from edc_constants.constants import COMPLETE, INCOMPLETE, NEW, OPEN
+from edc_lab.choices import SERUM_CREATININE_UNITS
+from edc_lab_results.model_mixin_factories import reportable_result_model_mixin_factory
+from edc_model import REPORT_STATUS
+from edc_reportable.units import EGFR_UNITS, MICROMOLES_PER_LITER
+from edc_vitals.models import WeightField
+
+
+class EgfrDropNotificationModelMixin(
+    reportable_result_model_mixin_factory(
+        utest_id="egfr",
+        verbose_name="eGFR",
+        decimal_places=4,
+        default_units=EGFR_UNITS,
+        max_digits=8,
+        units_choices=((EGFR_UNITS, EGFR_UNITS),),
+        exclude_attrs_for_reportable=True,
+    ),
+    reportable_result_model_mixin_factory(
+        utest_id="creatinine",
+        verbose_name="Serum creatinine",
+        decimal_places=2,
+        default_units=MICROMOLES_PER_LITER,
+        max_digits=8,
+        units_choices=((SERUM_CREATININE_UNITS, SERUM_CREATININE_UNITS),),
+        exclude_attrs_for_reportable=True,
+    ),
+    models.Model,
+):
+    creatinine_date = models.DateField(verbose_name="Serum creatinine date")
+
+    weight = WeightField(null=True, blank=True)
+
+    egfr_percent_change = models.DecimalField(
+        verbose_name="Percent change from baseline",
+        max_digits=10,
+        decimal_places=2,
+        null=True,
+        blank=True,
+        help_text="Copied from RFT result eGFR section.",
+    )
+
+    narrative = models.TextField(
+        verbose_name="Narrative",
+        null=True,
+        blank=True,
+    )
+
+    report_status = models.CharField(max_length=15, choices=REPORT_STATUS, default=NEW)
+
+    def save(self, *args, **kwargs):
+        if self.report_status == OPEN:
+            self.crf_status = INCOMPLETE
+        else:
+            self.crf_status = COMPLETE
+        super().save(*args, **kwargs)
+
+    class Meta:
+        verbose_name = "eGFR Drop Notification"
+        verbose_name_plural = "eGFR Drop Notifications"
+        abstract = True