edc-reportable

Reportable clinic events, reference ranges, grading

from dateutil.relativedelta import relativedelta
from edc_utils import get_utcnow
from edc_constants.constants import MALE, FEMALE
from edc_reportable import ValueReferenceGroup, NormalReference, GradeReference
from edc_reportable import site_reportables
from edc_reportable.tests.reportables import normal_data, grading_data

Create a group for each test:

neutrophils = ValueReferenceGroup(name='neutrophils')

A normal reference is declared like this:

ref = NormalReference(
    name='neutrophils',
    lower=2.5,
    upper=7.5,
    units='10e9/L',
    age_lower=18,
    age_upper=99,
    age_units='years',
    gender=[MALE, FEMALE])

>>> ref
NormalReference(neutrophils, 2.5<x<7.5 10e9/L MF, 18<AGE<99 years)

And added to a group like this:

neutrophils.add_normal(ref)

Add as many normal references in a group 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.

A grading reference is declared like this:

g3 = GradeReference(
    name='neutrophils',
    grade=3,
    lower=0.4,
    lower_inclusive=True,
    upper=0.59,
    upper_inclusive=True,
    units='10e9/L',
    age_lower=18,
    age_upper=99,
    age_units='years',
    gender=[MALE, FEMALE])

>>> g3
GradeReference(neutrophils, 0.4<=x<=0.59 in 10e9/L GRADE 3, MF, 18<AGE<99 in years) GRADE 3)

or using lower / upper limits of normal:

g3 = GradeReference(
    name="amylase",
    grade=1,
    lower="3.0*ULN",
    upper="5.0*ULN",
    lower_inclusive=True,
    upper_inclusive=False,
    units=IU_LITER,
    gender=MALE,
    normal_references={MALE: [normal_reference]},
    **adult_age_options)

>>> g3
GradeReference(amylase, 375.0<=x<625.0 IU/L GRADE 3) GRADE 3)

And added to the group like this:

neutrophils.add_grading(g3)

Declare and add a GradeReference for each reportable grade of the test.

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.

Declaring with parse

You may find using parse somewhat simplifies the declaration where lower, lower_inclusive, upper and upper_inclusive can be written as a phrase, like 13.5<=x<=17.5. For example:

age_opts = dict(
    age_lower=18,
    age_upper=120,
    age_units='years',
    age_lower_inclusive=True,
    age_upper_inclusive=True)

normal_data = {
    'haemoglobin': [
        p('13.5<=x<=17.5', units=GRAMS_PER_DECILITER,
          gender=[MALE], **age_opts),
        p('12.0<=x<=15.5', units=GRAMS_PER_DECILITER, gender=[FEMALE], **age_opts)],
     ...
}

Registering with site_reportables

Once you have declared all your references, register them

site_reportables.register(
    name='my_project',
    normal_data=normal_data,
    grading_data=grading_data)

Important:

Writing out references is prone to error. It is better to declare a dictionary of normal references and grading references. Use the parse function so that you can use a phrase like 13.5<=x<=17.5 instead of a listing attributes. There are examples of complete normal_data and grading_data in the tests. See``edc_reportable.tests.reportables``.

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:

site_reportables.register(
    name='my_project',
    normal_data=normal_data,
    grading_data=grading_data,
    reportable_grades=[GRADE3, GRADE4],
)

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:

site_reportables.register(
    name='my_project',
    normal_data=normal_data,
    grading_data=grading_data,
    reportable_grades=[GRADE3, GRADE4],
    reportable_grades_exceptions={"amylase": [GRADE2, GRADE3, GRADE4]}
)

Exporting the reference tables

You can export your declared references to CSV for further inspection

>>> site_reportables.to_csv(name='my_project', path='~/')

('/Users/erikvw/my_project_normal_ranges.csv',
'/Users/erikvw/my_project_grading.csv')

Using your reportables

In your code, get the references by collection name:

my_project_reportables = site_reportables.get('my_project')

neutrophil = my_project_reportables.get('neutrophil')

report_datetime = get_utcnow()
dob = (report_datetime - relativedelta(years=25)).date()

Check a normal value

If a value is normal, get_normal returns the NormalReference instance that matched with the value.

# evaluate a normal value
normal = neutrophil.get_normal(
    value=3.5, units='10^9/L',
    gender=MALE, dob=dob, report_datetime=report_datetime)

# returns a normal object with information about the range selected
>>> normal.description
'2.5<=3.5<=7.5 10^9/L MF, 18<=AGE years'

Check an abnormal value

If a value is abnormal, get_normal returns None.

# evaluate an abnormal value
opts = dict(
    units='10^9/L',
    gender=MALE, dob=dob,
    report_datetime=report_datetime)
normal = neutrophil.get_normal(value=0.3, **opts)

# returns None
>>> if not normal:
        print('abnormal')
'abnormal'

To show which ranges the value was evaluated against

# use same options for units, gender, dob, report_datetime
>>> neutrophil.get_normal_description(**opts)
['2.5<=x<=7.5 10^9/L MF, 18<=AGE years']

Check if a value is "reportable"

grade = neutrophil.get_grade(
    value=0.43, units='10^9/L',
    gender=MALE, dob=dob, report_datetime=report_datetime)

>>> grade.grade
3

>>> grade.description
'0.4<=0.43<=0.59 10^9/L GRADE 3'

grade = neutrophil.get_grade(
    value=0.3, units='10^9/L',
    gender=MALE, dob=dob, report_datetime=report_datetime)

>>> grade.grade
4

>>> grade.description
'0.3<0.4 10^9/L GRADE 4'

If the value is not evaluated against any reportable ranges, a NotEvaluated exception is raised

# call with the wrong units

>>> grade = neutrophil.get_grade(
        value=0.3, units='mmol/L',
        gender=MALE, dob=dob, report_datetime=report_datetime)

    NotEvaluated: neutrophil value not graded. No reference range found ...