Reportable clinic events, reference ranges, grading

Normal data is kept in model NormalData and grading data in GradingData.

The two tables are populated by the post_migrate signal post_migrate_load_reference_ranges.

The post-migrate signal goes through all apps looking for reportables.py and loads according to the attributes in the module.

A reportables.py might look like this:

from edc_reportable.data import africa, daids_july_2017

collection_name = "meta"

normal_data = africa.normal_data

grading_data = {}
grading_data.update(**daids_july_2017.dummies)
grading_data.update(**daids_july_2017.chemistries)
grading_data.update(**daids_july_2017.hematology)
reportable_grades = [3, 4]
reportable_grades_exceptions = {}

These attributes in reportables.py are required:

• collection_name
• normal_data
• grading_data
• reportable_grades
• reportable_grades_exceptions

When the post-migrate signal finds a module it calls load_reference_ranges:

load_reference_ranges(
    reportables_module.collection_name,
    normal_data=reportables_module.normal_data,
    grading_data=reportables_module.grading_data,
    reportable_grades=reportables_module.reportable_grades,
    reportable_grades_exceptions=reportables_module.reportable_grades_exceptions,
)

A normal reference is declared like this:

normal_data = {
    "albumin": [
        Formula(
            "3.5<=x<=5.0",
            units=GRAMS_PER_DECILITER,
            gender=[MALE, FEMALE],
            **adult_age_options,
        ),
    ],
    ...
}

Add as many normal references in the dictionary as you like, just ensure the lower and upper boundaries don't overlap.

Note: If the lower and upper values of a normal reference overlap with another normal reference in the same group, a BoundaryOverlap exception will be raised when the value is evaluated. Catch this in your tests.

See edc_reportable.data.normal_data for a complete example.

A grading reference is declared like this:

from edc_constants.constants import FEMALE, MALE
from ...adult_age_options import adult_age_options
from ...constants import HIGH_VALUE
from ...units import IU_LITER

grading_data = {
    amylase=[
        Formula(
            "1.1*ULN<=x<1.5*ULN",
            grade=1,
            units=IU_LITER,
            gender=[MALE, FEMALE],
            **adult_age_options,
        ),
        Formula(
            "1.5*ULN<=x<3.0*ULN",
            grade=2,
            units=IU_LITER,
            gender=[MALE, FEMALE],
            **adult_age_options,
        ),
        Formula(
            "3.0*ULN<=x<5.0*ULN",
            grade=3,
            units=IU_LITER,
            gender=[MALE, FEMALE],
            **adult_age_options,
        ),
        Formula(
            f"5.0*ULN<=x<{HIGH_VALUE}*ULN",
            grade=4,
            units=IU_LITER,
            gender=[MALE, FEMALE],
            **adult_age_options,
        ),
    ],
    ...
}

Some references are not relative to LLN or ULN and are declared like this:

grading_data = {
    ldl=[
        Formula(
            "4.90<=x",
            grade=3,
            units=MILLIMOLES_PER_LITER,
            gender=[MALE, FEMALE],
            **adult_age_options,
            fasting=True,
        ),
    ],
    ...
}

See edc_reportable.data.grading_data for a complete example.

Note: If the lower and upper values of a grade reference overlap with another grade reference in the same group, a BoundaryOverlap exception will be raised when the value is evaluated. Catch this in your tests.

Important:

Writing out references is prone to error. It is better to declare a dictionary of normal references and grading references as shown above. Use the Formula class so that you can use a phrase like 13.5<=x<=17.5 instead of a listing attributes.

If a value is pased to the evaluator and no grading data exists in the reference lists for that test, an exception is raised.

The default tables have grading data for grades 1-4. The evaluator will grade any value if there is grading data. You can prevent the evaluator from considering grades by passing reportable_grades when you register the normal and grading data.

For example, in your reportables.py:

...
reportable_grades = [3, 4]
...

In the above, by explicitly passing a list of grades, the evaluator will only raise an exception for grades 3 and 4. If a value meets the criteria for grade 1 or 2, it will be ignored.

Minor exceptions can be specified using the parameter reportable_grades_exceptions. For example, you wish to report grades 2,3,4 for Serum Amylase but grades 3,4 for everything else. You would register as follows:

...
reportable_grades_exceptions={"amylase": [GRADE2, GRADE3, GRADE4]}
...

You can export your declared references to CSV for further inspection using the management command

python manage.py export_reportables

('/Users/erikvw/my_project_normal_data.csv',
'/Users/erikvw/my_project_grading_data.csv')