Package: edc-reportable
edc-reportableReportable clinic events, reference ranges, gradingfromdateutil.relativedeltaimportrelativedeltafromedc_utilsimportget_utcnowfromedc_constants.constantsimportMALE,FEMALEfromedc_reportableimportValueReferenceGroup,NormalReference,GradeReferencefromedc_reportableimportsite_reportablesfromedc_reportable.tests.reportablesimportnormal_data,grading_dataCreate 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])>>>refNormalReference(neutrophils,2.5<x<7.510e9/LMF,18<AGE<99years)And added to a group like this:neutrophils.add_normal(ref)Add as many normal references in a group as you like, just ensure thelowerandupperboundaries don’t overlap.Note: If the lower and upper values of a normal reference overlap
with another normal reference in the same group, aBoundaryOverlapexception 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])>>>g3GradeReference(neutrophils,0.4<=x<=0.59in10e9/LGRADE3,MF,18<AGE<99inyears)GRADE3)orusinglower/upperlimitsofnormal: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)>>>g3GradeReference(amylase,375.0<=x<625.0IU/LGRADE3)GRADE3)And added to the group like this:neutrophils.add_grading(g3)Declare and add aGradeReferencefor 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, aBoundaryOverlapexception will be raised when the value is evaluated.
Catch this in your tests.Declaring withparseYou may find usingparsesomewhat simplifies the declaration wherelower,lower_inclusive,upperandupper_inclusivecan be written as a phrase, like13.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 withsite_reportablesOnce you have declared all your references, register themsite_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 theparsefunction
so that you can use a phrase like13.5<=x<=17.5instead of a listing attributes.
There are examples of completenormal_dataandgrading_datain the tests.
See``edc_reportable.tests.reportables``.Attempting to grade a value without grading dataIf 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 projectThe 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 passingreportable_gradeswhen 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 exceptionsMinor exceptions can be specified using the parameterreportable_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 tablesYou 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 reportablesIn 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 valueIf a value is normal,get_normalreturns theNormalReferenceinstance that matched with the value.# evaluate a normal valuenormal=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 valueIf a value is abnormal,get_normalreturnsNone.# evaluate an abnormal valueopts=dict(units='10^9/L',gender=MALE,dob=dob,report_datetime=report_datetime)normal=neutrophil.get_normal(value=0.3,**opts)# returns None>>>ifnotnormal: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.grade3>>>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.grade4>>>grade.description'0.3<0.4 10^9/L GRADE 4'If the value is not evaluated against any reportable ranges, aNotEvaluatedexception 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:neutrophilvaluenotgraded.Noreferencerangefound...