Reporting and Document Analysis

This page is generated from the repository on every merge to main; changes made here are overwritten.

aggregate_data (network-only)

Group rows of data by a field and compute sum/count/mean/min/max of another field per group -- e.g. 'total incidents by district' or 'average funding by cluster'. Takes structured rows such as the output of extract_pdf_tables/extract_word_tables (their 'rows' list), or any other list of flat {field: value} objects you've already gathered.

Parameter	Type	Required	Description
rows	array[object]	yes	List of flat row objects to aggregate.
group_by_field	string	yes
value_field	string	no	Numeric field to aggregate. Not needed when agg is 'count'.
agg	string	no	'sum' (default), 'count', 'mean', 'min', or 'max'.

extract_pdf_tables (network-only)

Extract structured tables from a PDF file -- e.g. a situation report's 'IDPs by district' table -- as rows of column values, not just plain text. Use this instead of reading PDF text when the data you need is in a table (funding breakdowns, incident lists, needs-assessment figures). Returns one entry per detected table, each with its own columns/rows.

Parameter	Type	Required	Description
file_path	string	yes	Absolute path to the PDF file.
page	integer	no	1-based page number to limit extraction to. Omit to scan every page.

extract_word_tables (network-only)

Extract structured tables from a Word (.docx) document as rows of column values, instead of flattened text. Use this when the data you need is in a table (e.g. a needs-assessment matrix) rather than prose.

Parameter	Type	Required	Description
file_path	string	yes	Absolute path to the .docx file.

generate_chart (network-only)

Generate a bar, pie, or line chart image from labeled numeric data -- for statistical comparisons a map can't show (funding by cluster, incidents over time, casualties by district). Not for spatial/geographic visualization -- use the styling tools (apply_categorized_style, apply_graduated_style, etc.) for that. Returns the PNG file path.

Parameter	Type	Required	Description
chart_type	string	yes	'bar', 'pie', or 'line'.
title	string	yes
labels	array[string]	yes	Category names (bar/pie) or x-axis points (line).
values	array[number]	yes	One numeric value per label.
x_label	string	no	X-axis label. Ignored for pie charts.
y_label	string	no	Y-axis label. Ignored for pie charts.
output_path	string	no	Where to save the PNG. Defaults to a temp file.
color_palette	array[string]	no	Optional list of hex colors (e.g. ['#0072B2', '#E69F00']) to use instead of the default colorblind-safe palette -- cycled if there are more categories than colors.
dpi	integer	no	Export resolution in DPI. Defaults to 300 (print quality).

generate_sector_coverage_report

Generate the standard humanitarian 'beneficiaries reached vs. target' coverage table and bar chart in one call, grouped by sector/cluster (or any other categorical field, e.g. admin unit) -- instead of chaining aggregate_data + generate_chart by hand. Sums reached_field (and target_field, if given) per group_by_field value, computes a coverage percentage per group when a target is given, and renders a bar chart. Returns the underlying table alongside the chart path so both the numbers and the visual are available. When a target is given, the table is sorted worst-coverage-first (groups with no target on record sort alongside the worst performers, not silently last, since missing target data is itself worth flagging in a gap analysis) -- otherwise sorted by reached, highest first.

Parameter	Type	Required	Description
rows	array[object]	yes	List of flat row objects, e.g. one per activity/beneficiary record.
group_by_field	string	yes	Field to group by -- typically sector/cluster, but any categorical field works (e.g. admin unit).
reached_field	string	yes	Numeric field holding beneficiaries reached per row.
target_field	string	no	Optional numeric field holding the target per row -- enables a coverage percentage.
title	string	no	Chart title. Defaults to 'Coverage by {group_by_field}'.
output_path	string	no	Where to save the chart PNG. Defaults to a temp file.

load_3w_data

Read a 3W/4W ('who does what where/when') CSV or Excel file -- the standard humanitarian operational-presence dataset, one row per activity with an organization, admin unit, and usually a sector/cluster -- and aggregate it into organizational presence per admin unit: how many distinct organizations are active there, which ones, and (if a sector field is given) which sectors are covered. Use this for 'which organizations work in X' / 'how many actors cover district Y' questions. This is a plain tabular read, not a QGIS layer load -- pair with calculate_presence_gap to cross-reference presence against a severity/needs index.

Parameter	Type	Required	Description
file_path	string	yes	Absolute path to the .csv/.xlsx/.xls 3W/4W file.
admin_field	string	yes	Column holding the admin unit name/P-code each activity row belongs to.
org_field	string	yes	Column holding the organization name/acronym running each activity.
sector_field	string	no	Optional column holding the sector/cluster (e.g. WASH, Health) -- adds sector coverage per unit.
sheet_name	string	no	Sheet name for Excel files with multiple sheets. Defaults to the first sheet.
delimiter	string	no	CSV field delimiter. Defaults to ','.