Calculate Z-Score within app workflow form

[abbyad]

From https://github.com/medic/medic-projects/issues/810, emphasis mine:

As a CHW I need to see accurate weight-for-age, height-for-age, and weight-for-height z-scores so that I can properly diagnose chronic and acute malnutrition in children.

During every nutrition visit, CHWs collect the height and weight of the child. Each time this action is performed, the mobile app should take the recent height and weight measurements as well as the child's sex and age to display three z-scores on the results screen: weight-for-age (WFA), height-for-age (HFA), and weight-for-height (WFH).

If you take a look at one of the weight-for-age charts attached below, you will see age in days in the first column along with a series of SD weight values for each age. According to the Boys WFA Chart, an average 3-day-old boy weighs 3.363 kgs (SD0). If a 3-day-old boy weighs 2.895 kg, then his weight is 1 SD below the mean and his z-score is -1. If instead the boy weighs 3.129 kg, then his z-score would be -0.5, as this is halfway between SD0 and SD1neg (we can assume that z-scores increase/decrease linearly between neighboring SD values).

Using WFA as an example, the CHW would need a function accessible from an Enketo form that takes weight, age, sex, and calculation type as inputs and returns the z-score value of a decimal (to the nearest tenth) between -5 and 5. This z-score value should be saved as a field within the xls form so that it can be validated, displayed in the results screen, and passed on as an input for the next task.

This folder contains the code that CiC is currently using for their tablet, along with comments and instructions: GradeCalculator.zip

The z-score tables for this first project are based on WHO tables, but these may change between projects and also over time.

[garethbowen]

Prioritising as this should be included in 2.9

[garethbowen]

PRs:

• Add Enketo zscore widget and service. Issue: #2915 #2929
• Allow replication of zscore charts doc. Issue: medic/medic-webapp#2915 medic-api#104

[garethbowen]

To get this to work...

Charts doc

Add a doc to the couchdb which stores the raw data. Here's one I generated for the WHO data provided above: doc.zip

Update the form

Example:

<?xml version="1.0"?>
<h:html xmlns="http://www.w3.org/2002/xforms" xmlns:ev="http://www.w3.org/2001/xml-events" xmlns:h="http://www.w3.org/1999/xhtml" xmlns:jr="http://openrosa.org/javarosa" xmlns:orx="http://openrosa.org/xforms/" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <h:head>
    <h:title>PNC Visit Report</h:title>
    <model>
      <instance>
        <data id="PNCV" version="2015-06-05">
          <contact>
            <_id />
          </contact>
          <zscore>
            <sex />
            <weight />
            <height />
            <age />
            <wfa />
            <hfa />
            <wfh />
          </zscore>
        </data>
      </instance>
      <bind nodeset="/data/contact/_id" type="db:person" />
      <bind nodeset="/data/zscore/weight" type="decimal" />
      <bind nodeset="/data/zscore/height" type="decimal" />
      <bind nodeset="/data/zscore/age" type="integer" />
      <bind nodeset="/data/zscore/sex" type="string" />
      <bind nodeset="/data/zscore/wfa" type="decimal" />
      <bind nodeset="/data/zscore/hfa" type="decimal" />
      <bind nodeset="/data/zscore/wfh" type="decimal" />
    </model>
  </h:head>
  <h:body>
    <input appearance="db-object" ref="/data/contact/_id">
      <label>Who is the patient?</label>
      <hint>Select a person from list</hint>
    </input>
    <group appearance="zscore" ref="/data/zscore">
      <select1 ref="sex" appearance="zscore-sex">
        <label>Sex</label>
        <item>
          <label>Female</label>
          <value>female</value>
        </item>
        <item>
          <label>Male</label>
          <value>male</value>
        </item>
      </select1>
      <input ref="weight" appearance="zscore-weight">
        <label>Weight (kg)</label>
      </input>
      <input ref="height" appearance="zscore-height">
        <label>Height (cm)</label>
      </input>
      <input ref="age" appearance="zscore-age">
        <label>Age (days)</label>
      </input>
      <input ref="wfa" appearance="zscore-weight-for-age">
        <label>Weight for age z-score</label>
      </input>
      <input ref="hfa" appearance="zscore-height-for-age">
        <label>Height for age z-score</label>
      </input>
      <input ref="wfh" appearance="zscore-weight-for-height">
        <label>Weight for height z-score</label>
      </input>
    </group>
  </h:body>
</h:html>

The appearance attributes are the key - everything else can be changed.

[SCdF]

LGTM, merging.

[guptasanchay]

I did some acceptance testing for this issue on the alpha instance that @abbyad shared with me: https://v2-alpha.app.medicmobile.org/

I randomly tested ~50 cases from a dataset of 1400 measurements that CiC's promotoras collected this month.

The calculator is working really well for the most part. I did notice that it produces a z-score of -4 for any combination of gender, weight, height, and age that should give a result of -3.x. This is the only issue we've been able to identify.

As an example, a boy with a weight of 11.704545 kg, a height of 83 cm, and an age of 1072 days should have a HFA of -3.4. The calculator returns -4. See case 1003 or 1008 in the dataset above for more examples.

[garethbowen]

@guptasanchay You're absolutely right. There was a bug where any zscore between -3.0 and -3.9 was returning as -4. This is now patched and I've added that CIC case as a unit test.

@abbyad Can you please deploy on the right instance so testing can resume?

[abbyad]

Updated to 2.9.0-alpha.4509, testing can resume with this fix.

[abbyad]

It may be a good idea to rename chart to table in the code to avoid confusion later on, especially that there are feature requests to display growth charts in the future.

The chart is typically the visual graph, whereas table refers to the list of values used to generate the chart.

On the WHO site they split these up

Chart

Table

Week	L	M	S	SD3neg	SD2neg	SD1neg	SD0	SD1	SD2	SD3
0	0.3809	3.2322	0.14171	2.0	2.4	2.8	3.2	3.7	4.2	4.8
1	0.2671	3.3388	0.14600	2.1	2.5	2.9	3.3	3.9	4.4	5.1
2	0.2304	3.5693	0.14339	2.3	2.7	3.1	3.6	4.1	4.7	5.4
3	0.2024	3.8352	0.14060	2.5	2.9	3.3	3.8	4.4	5.0	5.7
4	0.1789	4.0987	0.13805	2.7	3.1	3.6	4.1	4.7	5.4	6.1
5	0.1582	4.3476	0.13583	2.9	3.3	3.8	4.3	5.0	5.7	6.5
6	0.1395	4.5793	0.13392	3.0	3.5	4.0	4.6	5.2	6.0	6.8
7	0.1224	4.7950	0.13228	3.2	3.7	4.2	4.8	5.5	6.2	7.1
8	0.1065	4.9959	0.13087	3.3	3.8	4.4	5.0	5.7	6.5	7.3
9	0.0918	5.1842	0.12966	3.5	4.0	4.6	5.2	5.9	6.7	7.6
10	0.0779	5.3618	0.12861	3.6	4.1	4.7	5.4	6.1	6.9	7.8
11	0.0648	5.5295	0.12770	3.8	4.3	4.9	5.5	6.3	7.1	8.1
12	0.0525	5.6883	0.12691	3.9	4.4	5.0	5.7	6.5	7.3	8.3
13	0.0407	5.8393	0.12622	4.0	4.5	5.1	5.8	6.6	7.5	8.5

[guptasanchay]

Okay, retested and everything looks great! Thanks all

@abbayad, next steps before we can get this onto the CiC instance?

[abbyad]

@guptasanchay I think you are all set, so moving to Ready.

[derickl]

@garethbowen is there an existing XLS Form for the above example?

[sglangevin]

@derickl check the CIC Guatemala project in medic-projects

[guptasanchay]

@sglangevin, Derick and I were looking at the xml that Gareth shared and thought it would be easier to implement for cic-guatemala if we could view it as an xls form.

[sglangevin]

Should be pretty straightforward to translate from XML to XLS. Looks like all you have to do is make sure to list the correct appearance for the fields you're using to calculate z-score and that you contain those fields within a group with appearance of zscore.

[guptasanchay]

@sglangevin that's what we tried. We have a group in the malnutrition_visit_test.xls form with appearance of zscore containing the sex, age in days, weight, height, wfa, hfa, and wfh fields (with the same types and appearances as outlined above). The calculations aren't happening.

What are we missing from Gareth's XML form? Is there something that needs to be added to the input or contact group? Our zscore group is lower down in the form embedded within the assessment.

[guptasanchay]

@garethbowen, @ranjuts was going over designs for a similar project in Indonesia and an interesting question came up: there are other partners who might be using variations on the z-score reference tables we used for this feature.

I imagine it wouldn't be too challenging for you to implement the same feature with a different set of tables, but is there a better way for us to support future variations without creating a new request every time?

[garethbowen]

@guptasanchay What's different in the variation - is the format or the values or... something else?

[sglangevin]

@guptasanchay I recommend starting simple. Instead of adding to a complex form, try to get the simplest case working, then add.

[guptasanchay]

@garethbowen, the difference would just be in the values I believe. Format would stay the same.

Also, @derickl and I tried implementing this feature in an assessment form and in a separate form with only the calculator and everything else removed. We're not having any luck. Could you take a look at our xls and see what we're doing wrong? The form is titled "malnutrition_zscore_calculator" and you can find it in the cic-guatemala folder (cc @garethbowen @abbyad).

Really running on crunch time now

[abbyad]

Moving this conversation to private channel since the feature is tested and complete. We can open new issues if there are any problems with this feature, although we have yet to identify any.

[garethbowen]

@guptasanchay The values are stored in a doc in the database (id: zscore-charts) so they can change if necessary. We have a script to help convert the WHO tables to the JSON format we use. It's reasonably configurable so you should be able to make the required changes.

[erwagasore]

Hey @abbyad . I am trying to implement z-score feature on IMC-Kenya. We are hopping to use calculated fields for age and sex. Unfortunately it is not working with calculated fields, it only working with text, integer and other. Is there a way around this?

We tried to do an integer field with a calculation(the calculated value was visible and pre-filled) but didn't work either.

We have the form uploaded the form admit-to-otp on imc-kenya.app instance if you need to experience it :)

[abbyad]

I just tested this and managed to get it to work. See https://github.com/medic/medic-projects/commit/7919c945c13f9846b06be121fa9911b461ea0304.

Any further config issues should be opened in medic-projects.

[garethbowen]

Documentation