Feed another dashboard

A common use of the API is to show AI4M risk beside your own indicators in a system you already run, such as a DHIS2 instance, a Power BI report or a shared spreadsheet.

Those systems all want the same shape: one row for each area and month, with a period, a stable area identifier and a value. This guide produces that.

The shape to aim for

period,kind,state_code,lga_code,lga,score,score_low,score_high,level
202607,estimated,KN,NGA.20.26_1,Kunchi,0.549,0.308,0.79,very_high
202607,estimated,KN,NGA.20.33_1,Rimin Gado,0.541,0.3,0.782,very_high
202608,forecast,KN,NGA.20.26_1,Kunchi,0.543,0.273,0.787,very_high

Column	Why it is there
`period`	The month. DHIS2 writes monthly periods as `YYYYMM`; most other tools accept that or `YYYY-MM`
`kind`	Lets the dashboard draw forecasts differently from estimates
`lga_code`	The identifier to join on. Names repeat across states and are spelled differently between sources
`score`, `score_low`, `score_high`	The value and its likely range
`level`	For colouring

Export it

Create a key with the Risk scores and Forecasts scopes, for this job only. See Authentication.

Fetch and write the rows. This script writes this month’s estimate and the forecasts for the states you name:

import csv, os, sys
from ai4m_sdk import AI4MClient

client = AI4MClient(api_key=os.environ["AI4M_API_KEY"])
writer = csv.writer(sys.stdout)
writer.writerow(["period", "kind", "state_code", "lga_code", "lga",
                 "score", "score_low", "score_high", "level"])

for state in sys.argv[1:] or ["KN"]:
    for report in [client.get_lga_risk(state), *client.get_lga_forecasts(state)]:
        for lga in report.lgas:
            writer.writerow([
                report.period.replace("-", ""), report.kind, report.state_code,
                lga.lga_code, lga.lga, lga.score, lga.score_low, lga.score_high, lga.level,
            ])

python export.py KN JI > ai4m_risk.csv

The SDK ships this script as examples/export_for_dashboard.py.

Map AI4M’s LGAs to your system’s areas, once. Build a small lookup table from lga_code to your system’s own identifier (in DHIS2, the organisation unit’s UID). Check the six LGA names that repeat across states, and any LGA whose boundary differs between GADM and your source.
Import the file with your system’s own tool: DHIS2’s Import/Export app or its data value API, Power BI’s Get data, or a spreadsheet import.
Run it once a month. The data changes about monthly. Check updated_at from Periods and skip the run if it has not changed.

In DHIS2

Create a data element for the score (a number between 0 and 1), and if you want them, two more for the low and high ends of the range. Use monthly periods and LGA-level organisation units.

Keep estimates and forecasts apart, either as separate data elements or with a category option, so a forecast is never mistaken for an estimate. When a forecast month later becomes an estimate, the new value should replace the old one.

Showing it accurately

Show the range, not only the score, wherever there is room.
Mark forecast months so they look different from estimated months.
Say where the figure comes from and link to Limitations.