Indicators¶
Overview¶
As described in What is ChildCount+?, ChildCount+ collects data, runs analysis on those data, then generates reports and alerts based on the results of the analysis. The indicators functionality takes care of the simple data analysis that goes on inside of ChildCount+.
The data analysis features are centered around the idea of “indicators.” An indicator is a function that takes two arguments: a data set and a time period and returns a numerical value. For example, an indicator called “Number of Households” would take a list of patients and a time period as arguments, and would return an integer – the number of households heads in the patient list at the given time period – as output.
The standard interface for indicators provides a few benefits to the programmer:
- We can transparently cache indicator values.
- Aggregation is simple: the same indicator function can generate per-patient, per-CHW, per-village, and per-site values, depending on the patient (or other) list you provide as input.
- It is easy to reuse reporting code across indicators.
The indicators code lives in two places. The
definition of the indicators interface is
in a library directory: lib/indicator/
while the ChildCount+ indicator definitions
live inside the ChildCount+ application
directory: apps/childcount/indicators/
.
Creating an Indicator¶
All of the ChildCount+ indicator code resides in the
apps/childcount/indicators/
directory.
For the most part, one indicator module (e.g.,
childcount.indicators.household
directly
corresponds to one ChildCount+ SMS form
(e.g., +V
or the
childcount.forms.HouseholdVisitForm
).
To create a new indicator, you must add a new class
to one of the files in apps/childcount/indicators/
.
Warning
Calculating indicator values can be very nuanced and tricky. Please make sure to extensively test your indicator code before you deploy it.
For example, you might want to create an indicator that
measures the number of households headed by people over
the age of 50 (at the end of the time period).
Since this indicator relates most directly to registration
(the +NEW
form), we would put it in the file
apps/childcount/indicators/registration.py
.
Warning
If your indicator returns a percentage value,
make sure that your indicator class inherits
from indicator.indicator.IndicatorPercentage
.
Using the percentage class will save you lots
of time and will make caching your life easier!
Adding a time period¶
Since all indicators take a time period as an argument,
ChildCount+ defines a standard set of time periods we
can use for indicator and report generation.
Every time period has a start and end datetime
object,
plus one or more sub-periods.
A time period might be “One Year” and the sub-periods might
be each of the months of the year.
These time periods are defined in
apps/reportgen/timeperiods/definitions/
.
To define a new time period, clone one of the files
in apps/reportgen/timeperiods/definitions/
,
edit it to do what you want,
and make sure to add it to the list of imports
in apps/reportgen/timeperiods/__init__.py
.