edc-reportable

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,
)

Normal data

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.

Grading data

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.

Attempting to grade a value without grading data

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

Limiting what is “gradeable” for your project

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.

Declaring minor exceptions

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]}
...

Exporting the reference tables

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')

Check a normal value

Check an abnormal value

Check if a value is “reportable”

Metadata

Release files for edc-reportable 2.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for edc-reportable 2.0.2
File	Size	Uploaded
edc_reportable-2.0.2.tar.gz	60.2 kB	Jul 16, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for edc-reportable 2.0.2
File	Interpreter	ABI	Platform	Reset
edc_reportable-2.0.2-py3-none-any.whl 77.9 kB Jul 16, 2025	Python 3	none	any	Details

Total release size: 138.1 kB

Release files / edc_reportable-2.0.2.tar.gz

Download URL	edc_reportable-2.0.2.tar.gz
Size	60.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`a7ca71ebf37efa7637af45b501cea4d5b17b49359c92cbc6b8197ff14465c0bb`
BLAKE2b-256 checksum How to use checksums	`744d67dd196ad9af4afa2c67db3ca15e8ea88d09c231d8d68b9ce3335b0ecbbe`
Upload date	Jul 16, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.12.11`

Release files / edc_reportable-2.0.2-py3-none-any.whl

Download URL	edc_reportable-2.0.2-py3-none-any.whl
Size	77.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`788725d9659e19a70b052c59e942711cac0627474cba937577821bc7813760a3`
BLAKE2b-256 checksum How to use checksums	`567be2d257e7bf7fe2a53816df735497fe7ce0571d0027f825e225aed40dbaa6`
Upload date	Jul 16, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.12.11`