adapter Module#

Convert DHIS2 API responses to Episia datasets.

This module provides the DHIS2Adapter class for converting raw DHIS2 API responses into Episia’s SurveillanceDataset format.

Class#

class episia.dhis2.adapter.DHIS2Adapter[source]#

Bases: object

Converts raw DHIS2 analytics API responses to SurveillanceDataset.

This class is used internally by DHIS2Client but can also be used standalone to convert data you have already fetched.

Example:

adapter = DHIS2Adapter()
ds = adapter.from_analytics_response(raw_json)

from_analytics_response(response, cases_element=None, deaths_element=None)[source]#

Convert a DHIS2 /api/analytics JSON response to SurveillanceDataset.

The analytics API returns rows like:: [dx, pe, ou, value]

where dx=data element UID, pe=period, ou=org unit UID.

Parameters:

response (Dict[str, Any]) – Raw JSON dict from DHIS2 analytics endpoint.
cases_element (str | None) – UID of the cases data element (filters rows).
deaths_element (str | None) – UID of the deaths data element (optional).

Returns:

SurveillanceDataset with date_col=’period’, cases_col=’cases’.

Return type:

SurveillanceDataset

from_data_value_sets(response)[source]#

Convert a DHIS2 /api/dataValueSets response to a flat DataFrame.

Parameters:: response (Dict[str, Any]) – Raw JSON from dataValueSets endpoint.
Returns:: period, org_unit, data_element, value.
Return type:: pandas DataFrame with columns

Examples#

Using the adapter standalone:

from episia.dhis2 import DHIS2Adapter
import json

# Load previously fetched DHIS2 data
with open("dhis2_response.json") as f:
    response = json.load(f)

adapter = DHIS2Adapter()

# Convert to SurveillanceDataset
ds = adapter.from_analytics_response(
    response,
    cases_element="FTRrcoaog83",
    deaths_element="cYeuwXTCPkU"
)

print(ds)

Working with dataValueSets:

# Convert dataValueSets response to DataFrame
with open("data_values.json") as f:
    data_values = json.load(f)

df = adapter.from_data_value_sets(data_values)
print(df.head())

Period parsing:

# The adapter handles various DHIS2 period formats
from episia.dhis2.adapter import DHIS2Adapter
import pandas as pd

adapter = DHIS2Adapter()

series = pd.Series(["2024W01", "202401", "2024Q1", "2024"])
parsed = adapter._parse_dhis2_period(series)
print(parsed)
# Output: Timestamps for week 1 of 2024, Jan 2024, Jan 2024, Jan 2024