Reportable clinic events, reference ranges, grading
Project description
|pypi| |travis| |coverage|
edc-reportable
--------------
Reportable clinic events, reference ranges, grading
.. code-block:: python
from dateutil.relativedelta import relativedelta
from edc_base.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:
.. code-block:: python
neutrophils = ValueReferenceGroup(name='neutrophils')
A normal reference is declared like this:
.. code-block:: python
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:
.. code-block:: python
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:
.. code-block:: python
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)
And added to the group like this:
.. code-block:: python
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:
.. code-block:: python
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
.. code-block:: python
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``.
You can export your declared references to CSV for further inspection
.. code-block:: python
>>> 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:
.. code-block:: python
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.
.. code-block:: python
# 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``.
.. code-block:: python
# 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
.. code-block:: python
# 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"
================================
.. code-block:: python
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
.. code-block:: python
# 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 ...
.. |pypi| image:: https://img.shields.io/pypi/v/edc-reportable.svg
:target: https://pypi.python.org/pypi/edc-reportable
.. |travis| image:: https://travis-ci.org/clinicedc/edc-reportable.svg?branch=develop
:target: https://travis-ci.org/clinicedc/edc-reportable
.. |coverage| image:: https://coveralls.io/repos/github/clinicedc/edc-reportable/badge.svg?branch=develop
:target: https://coveralls.io/github/clinicedc/edc-reportable?branch=develop
edc-reportable
--------------
Reportable clinic events, reference ranges, grading
.. code-block:: python
from dateutil.relativedelta import relativedelta
from edc_base.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:
.. code-block:: python
neutrophils = ValueReferenceGroup(name='neutrophils')
A normal reference is declared like this:
.. code-block:: python
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:
.. code-block:: python
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:
.. code-block:: python
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)
And added to the group like this:
.. code-block:: python
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:
.. code-block:: python
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
.. code-block:: python
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``.
You can export your declared references to CSV for further inspection
.. code-block:: python
>>> 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:
.. code-block:: python
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.
.. code-block:: python
# 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``.
.. code-block:: python
# 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
.. code-block:: python
# 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"
================================
.. code-block:: python
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
.. code-block:: python
# 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 ...
.. |pypi| image:: https://img.shields.io/pypi/v/edc-reportable.svg
:target: https://pypi.python.org/pypi/edc-reportable
.. |travis| image:: https://travis-ci.org/clinicedc/edc-reportable.svg?branch=develop
:target: https://travis-ci.org/clinicedc/edc-reportable
.. |coverage| image:: https://coveralls.io/repos/github/clinicedc/edc-reportable/badge.svg?branch=develop
:target: https://coveralls.io/github/clinicedc/edc-reportable?branch=develop
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Close
Hashes for edc-reportable-0.1.3.macosx-10.13-x86_64.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8b9423105f50862f3a14dd5a3cffb7822a53e0723505392b75239c239bdb11ff |
|
MD5 | 507f88b6901b4e941e32b273011babd5 |
|
BLAKE2b-256 | 6dd519f64561bd311b1307a944b6770bf573c210d14ca7e18e9f80dd76556607 |
Close
Hashes for edc_reportable-0.1.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3b9991d0125e15bddd3560faad6c2b1ff1f92f1aeed9a4cd7ad2eec8a7ac11ce |
|
MD5 | 4a93e0648e71ba61dc4dafde3d8a1a79 |
|
BLAKE2b-256 | 64bf1d472aedb7b54d34b5ec92d27867caefe913f819ad3883e418d527eb1445 |