Tools catalogue

This page mirrors docs/HUMANITARIAN_TOOLS_CATALOGUE.md from the repository and is regenerated on every merge to main. To correct it, edit that file; changes made here are overwritten.

Every tool Cartogen AI offers for humanitarian work, organised by the six workflows in the "Humanitarian Mapping Workflows" document (field operations first, then strategic orchestration), with what each tool produces on the map and how to get better results from it. Companion to the generated parameter reference TOOLS_REFERENCE.md (exact arguments) and the gap analysis HUMANITARIAN_WORKFLOW_GAP_ANALYSIS_2026-10-04.md (what is still missing).

Honesty notes. This is a static description written from the code and tool descriptions, dated 2026-10-04. "Map output" says what the tool draws; a tool marked no automatic style leaves QGIS's default look and you can ask for apply_graduated_style / apply_categorized_style afterwards. Nothing here was hand-tested in a live QGIS session; the QGIS-side behaviour is covered by CI tests on QGIS 4.2.2 where the tool's entry says so. Tools that produce estimates say so, and you should repeat that wording in reports. The tools do not choose thresholds, weights or survey designs for you: where a number is a judgement (trigger threshold, criteria weights, design effect, minimum cell size) the tool asks for it.

How to prompt well, in general. Name the layers exactly as they appear in the project. Say the unit you mean (minutes or hours of travel, metres, people or households). Give weights, thresholds and dates yourself rather than asking for "reasonable" ones. Say which end of a scale is worse. Ask for the assumptions to be listed in the answer. For anything that is a count of people, ask for the wording "estimated".

---

Phase I -- Operational and field mapping

Workflow 1. Rapid crisis and base mapping

The workflow. Build or refresh the base geography of an affected area (boundaries, roads, buildings, facilities), assess damage, and organise remote mappers. Outputs. Base map layers, damage and change layers, a mapping-task grid. Supporting data sources. HDX / OCHA COD-AB, geoBoundaries, OpenStreetMap (Overpass, Geofabrik extracts), Microsoft building footprints, Sentinel-2 via STAC.

search_hdx_datasets

Search the Humanitarian Data Exchange by keyword. Map output: none (a list of datasets). Better results: search with the place and the theme ("Yemen health facilities", "Sudan flood extent"), then ask for the specific dataset to be downloaded or loaded; check the dataset's date and licence yourself.

fetch_hdx_admin_boundaries

Downloads OCHA COD-AB administrative boundaries with real P-codes. Map output: light grey fill with thin white borders between areas, name labels when there are few enough areas, ordered under points and lines. Better results: use this rather than fetch_geoboundaries whenever you will join data by P-code; pass the reported pcode_field to the severity and presence-gap tools. A large file asks for confirmation before download.

fetch_geoboundaries

Administrative boundaries from geoBoundaries (broader coverage, no P-codes). Map output: same backdrop styling as above. Better results: use as a fallback when COD-AB does not exist for the country; join by name only with care (spelling variants break joins).

fetch_osm_features / ingest_osm_features

Overpass queries for OSM features (key, value, bounding box or centre and radius); ingest_osm_features adds the result as a layer. Map output: roads are graded by highway class (major / secondary / local / tracks, thick and dark to thin and pale) with an "Other" class; areas get a pale fill, other layers a neutral look. Better results: give a tight bounding box; combine values with | (hospital|clinic|doctors); ask for roads separately from facilities; for a road network to route on, request highways and then run estimate_road_speeds.

fetch_building_footprints

Microsoft Global ML Building Footprints for an area. Map output: a quiet translucent grey reference layer so an analysis on top stays readable. Better results: use a small bounding box; remember the dataset can lag real conditions by months, so it is a baseline, not a damage assessment.

search_stac_satellite_imagery

Finds Sentinel-2 scenes (Earth Search STAC) by bounding box and dates. Map output: none (scene list). Better results: give a before and an after date range and a low-cloud requirement; the tool lists scenes, it does not judge usability.

calculate_raster_change_detection

Pixel-wise after-minus-before difference of two rasters. Map output: a diverging ramp symmetric about zero -- blue = decrease, red = increase, no change transparent -- drawn under the vector layers. Better results: use two rasters of the same sensor, band, resolution and CRS; co-registration and clouds are your responsibility.

calculate_damage_exposure_severity

Per-admin-unit damage score combining the change raster, building counts and an optional hazard-intensity raster; reports buildings in the high-severity units. Map output: values on the admin layer (output_field); the layer keeps its colours until you ask -- the result carries a map_look hint for apply_humanitarian_look (severity classes). Better results: supply the before/after pair, the footprints layer and the admin layer with a P-code or name field; state it is a rapid indicative assessment, not a field-verified count.

extract_features_from_imagery

Segments object outlines from a raster you loaded (FastSAM, local, offline once the model is downloaded). Map output: polygons in three model-confidence bands (below 0.6, 0.6 to < 0.8, 0.8 or more), translucent. The bands are the model's score, not a probability that the object is real. Better results: use a clear, high-resolution image; the tool finds outlines, never identities -- do not call a polygon "a building" unless you know it is.

add_incident_point / add_point_layer

Plot one incident, or a list of named points, from real verified coordinates. Map output: incidents: red marker with a red label on a shared Incidents layer; named point layers: consistent point look with labels. Better results: give coordinates and dates you have verified; set severity / event_type (ACLED-style) so a later categorized style can tell incidents apart; use add_point_layer for more than one point.

generate_mapping_task_grid -- new (H2)

Splits an area into square mapping tasks for remote or crowd mapping, clipped to the area, optionally ranked High / Medium / Low by a point count (damage reports, buildings) or a population raster; can write GeoJSON. Map output: task polygons coloured by priority (dark red High, orange Medium, pale Low, grey for unranked) with task ids as labels on small grids; an unranked grid is a neutral outline. Better results: choose a cell size that one mapper can finish (500-2000 m for dense areas); pass a damage or building layer as the priority basis so the worst-hit cells are mapped first; check the GeoJSON against your Tasking Manager's import rules (not verified here).

---

Workflow 2. Multi-sectoral needs assessment (MSNA) and field data collection

The workflow. Design a statistically defensible sample, collect household data, and turn it into figures per area. Outputs. Sample sizes and draws, population baselines, weighted indicators per area. Supporting data sources. KoboToolbox / ODK exports (as CSV/XLSX), WorldPop, REACH/IMPACT datasets via HDX.

design_sampling_frame -- new (H3)

Per-stratum sample sizes for a single proportion (confidence, margin of error, expected proportion, design effect, finite-population correction, non-response) and a reproducible draw from a candidate-units layer or as random points per stratum. Map output: sample points, one colour per stratum. Better results: give the survey designer's design effect for cluster samples (the default of 1 is only valid for simple random sampling); supply a layer of dwellings or settlements so points are real units, not random locations; keep the returned seed with your methodology note; use plan_only first to see the sample sizes.

fetch_worldpop_population

WorldPop gridded population (about 100 m) clipped to your area. Map output: a heavy-tailed warm ramp with zero cells transparent, placed under the vector layers. Better results: always pass an extent_layer or bbox; whole-country downloads are refused unless you confirm; the figures are modelled estimates -- say "estimated".

estimate_population_exposure

Sums a population raster inside each polygon (one total per zone, on a detached copy: the polygon layer is not modified; overlapping zones are summed separately and the overlap is reported). Map output: values in the result; pass output_layer_name to also get a NEW polygon layer (field pop_estimate) in exposure classes. The polygon layer you pass is never changed or restyled. Better results: build the exposure polygon first (buffer, flood extent, service area) and say "estimated population within".

load_tabular_data_as_layer

Loads a CSV/XLSX in full as a layer, with coordinate or WKT columns where present. Map output: points get one consistent look and name labels on small layers. Better results: name the X/Y columns if the file's headings are unusual; check the reported CRS.

extract_pdf_tables / extract_word_tables / aggregate_data

Pull tables out of reports and group-summarise rows. Map output: none. Better results: give the page for PDFs; check the extracted columns before aggregating.

aggregate_survey_indicator -- new (H6)

Weighted share of "yes" answers or weighted mean per area, with confidence intervals; groups below a minimum number of respondents are suppressed. Map output: a results table (optional); join it to admin polygons with join_by_attribute to map it. Better results: pass the survey's own weight field; say which answers count as "yes" (positive_values); supply the design effect for cluster surveys (intervals otherwise ignore clustering); set min_n from your data-protection policy (30 is only a rule of thumb); never infer a suppressed group from totals.

---

Workflow 3. Logistics, route planning and catchment analysis

The workflow. Put the physical constraints into a road network and measure who can reach what. Outputs. Reach polygons, travel-time layers, access classes, route layers, siting rankings. Supporting data sources. OSM roads, HDX road status layers, Logistics Cluster layers (not fetched automatically).

estimate_road_speeds

Writes an assumed speed per road class. Map output: a field, no style. Better results: use only when the network has little real speed data; state that it is an assumption.

build_composite_impedance_field

Blends road class, surface, optional passability and optional slope into one km/h field. Map output: a field. Better results: run it before routing and pass its output as speed_field with strategy='fastest'; supply a 0-1 damage/passability field if you have a road assessment.

apply_network_barriers -- new (H1)

Blocks or slows road segments near destroyed bridges, checkpoints or flood extents (points, lines or polygons) and writes a speed field. Map output: the affected segments are drawn as a separate layer <roads>_barrier_affected, thick red when blocked, orange when slowed; your road layer is not restyled. Better results: pass speed_field from build_composite_impedance_field so unaffected roads keep realistic speeds; "block" writes a negative (closed) speed, and calculate_service_area, travel_time_matrix and optimize_delivery_route then route on the network without those segments, for either strategy; "penalise" only matters with strategy='fastest'; pick buffer_m to match the barrier's real footprint.

calculate_service_area

Reachable road network and approximate coverage polygon within a distance or time. Map output: roads graded in five cost bands (dark near, warm far) and a reach polygon, with the plain network hidden. Better results: use a real line layer with a speed field; ask for strategy='fastest' for time; read the polygon as an approximation (a hull around the reached roads).

classify_facilities_by_access

Labels each facility within or beyond a travel cost of an origin, using one service area (fast). Map output: points coloured within/beyond, "beyond" drawn larger and on top, labelled when the layer is small. Better results: use it instead of travel_time_matrix for any "within / beyond N hours" question over many facilities; state its snapping approximation.

travel_time_matrix

Road distance or time from each origin to each destination. Map output: none (a matrix). Better results: keep origins and destinations few; large sets are slow.

population_access_gap

People and percentage beyond a travel distance or time of the nearest facility. Map output: three reach figures with distinct translucent fills in one group; the headline figure visible, the others hidden. Better results: supply an area layer, a population raster and a speed field; quote the figure as an estimate and say which reach figure it used.

optimal_hub_siting / location_allocation

Rank candidate hubs, or choose the best combination of N sites, by distance to demand points (ellipsoidal distances). Map output: rankings in the result; no automatic style. Better results: give demand weights (weight_field) such as population; remember these are straight-line distances -- use the service-area tools for road reach.

optimize_delivery_route

Visiting order for stops, and a road-snapped route line when a network is given. Map output: route line in the route-line style. Better results: always pass the road network; do not present a straight line as a route.

score_route_incident_risk

Counts and distances of incidents near a route, optionally recent or severity-weighted. Map output: a translucent orange risk corridor. Better results: pass dates and a recency window; weight by severity if you have it; it counts nearby incidents, it does not predict risk.

---

Phase II -- Strategic decision-making and donor orchestration

Workflow 4. Intersectoral severity mapping (JIAF-style)

The workflow. Overlay vulnerabilities per admin unit into a composite severity score and class. Outputs. A severity layer, hotspot surfaces, coverage-gap lists. Supporting data sources. IPC, ACLED and 3W/4W tables (loaded as files; no automatic IPC or ACLED download).

apply_humanitarian_look -- new (HX1)

Gives a result field written by one of the analysis tools above its humanitarian map look: severity (0-1 score, five equal classes, the same classes the tool reports), people_in_need and exposure (counts in quantile classes, zero kept as its own class), presence_gap (gap / covered / unmatched) and rank (top_k emphasised). Map output: changes only the layer's renderer; nothing is written to the data; units with no value are not drawn. Better results: use it when you want the result shown on the map; the analysis tools return a map_look hint with the exact arguments.

calculate_severity_index

Min-max normalised, weighted composite score and a 1-5 class per unit. Map output: an optional score field; the layer keeps its colours until you ask -- apply_humanitarian_look (look severity) draws the five classes the tool reports, yellow to dark red. Better results: state the weights and which indicators are "higher is better" (invert_indicators); report excluded units. It is JIAF-style exploratory analysis (a weighted min-max index), not the JIAF method, and must not be called JIAF-compliant; a JIAF 2 analysis-support module is planned separately.

calculate_presence_gap / load_3w_data

Cross-reference high-severity units with 3W/4W presence. Map output: an optional status field (gap / covered / unmatched); apply_humanitarian_look (look presence_gap) colours it. Better results: join by P-code, not name; look at the "unmatched" list before concluding a gap.

calculate_population_in_need

Population in the high-severity classes using a population raster. Map output: an optional field; apply_humanitarian_look (look people_in_need) draws quantile classes. Better results: quote as an estimate and give the severity classes counted.

hotspot_analysis

Kernel density surface of a point layer. Map output: warm density ramp, transparent where empty. Better results: choose the radius to match the question; weight by severity if relevant.

analyze_incident_trend / forecast_trend

Is incident density rising or falling per zone; linear projection of a numeric field. Map output: none. Better results: supply at least three periods; present results as projections with the stated fit.

---

Workflow 5. Donor resource allocation and prioritisation

The workflow. Combine severity with funding and access to find where need is critical and support is thin. Outputs. Ranked priorities, coverage tables, funding snapshots. Supporting data sources. FTS, INFORM (as files).

import_humanitarian_table -- new (HX3b)

Reads an IPC, INFORM Risk or UNOSAT damage-point table from a CSV/Excel file you supply (for example from HDX) and validates it: IPC phase must be 1-5, INFORM scores 0-10, populations non-negative, coordinates in range, damage class from a fixed vocabulary. Map output: none by itself; for ipc and inform, giving an admin layer and its P-code field reports the join and, after confirmation, writes ipc_phase, ipc_pop, ipc_p3plus or inf_risk, inf_haz, inf_vuln, inf_coping to it (then apply_humanitarian_look can draw them). UNOSAT points are loaded with load_tabular_data_as_layer using the detected latitude/longitude columns. Better results: check the mapping_used in the result against your file -- the column names it recognises are unverified against real HDX files; pass an explicit mapping when a column is missing or ambiguous. Nothing is repaired: invalid values are listed and left empty (a missing IPC phase is not phase 1), duplicate or unmatched keys are never guessed, and the source to quote is your file and its date.

calculate_allocation_envelope -- new (H8)

Splits a budget you give across areas in proportion to need (optionally times population), with an optional ceiling per area, a floor, rounding and a need threshold below which an area gets nothing. Map output: an optional amount field; apply_humanitarian_look (look allocation, green quantile classes) draws it. Better results: it is an advisory calculation of an envelope, not a recommendation of who should receive what: state the budget, the need field, the exponent and the ceiling with the result. Areas with a missing or negative value are listed, never imputed; if ceilings stop the whole budget being spent the rest is reported as unallocated. It never supplies a cost per person or any coefficient.

calculate_mcda_ranking -- new (H5)

Weighted multi-criteria ranking of areas, each criterion with a weight and a priority direction, plus a test of how much the ranking depends on the weights. Map output: optional <prefix>_score, _rank, _rank_min, _rank_max fields; apply_humanitarian_look (look rank, with top_k) emphasises the top-ranked units. Better results: give the weights yourself; say for each criterion whether a high or low value gets priority; use top_k to see which areas stay in the top group; treat areas whose best and worst rank differ widely as weight-dependent, not firm.

fetch_fts_funding_data

Plan-level requirements, funding received and gap from FTS. Map output: none; it is not geographic. Better results: name the plan year; quote it as a snapshot.

generate_sector_coverage_report

"Reached versus target" table and bar chart by sector or admin unit. Map output: a chart image. Better results: include a target column; missing targets sort with the worst performers deliberately.

weighted_overlay_analysis

Weighted sum of already-normalised rasters (suitability or risk surface). Map output: an opaque low-to-high surface ramp, placed under the vector layers. Better results: normalise inputs to a common scale first; share CRS and extent.

---

Workflow 6. Anticipatory action and forecast-based financing

The workflow. Compare forecasts with pre-agreed triggers and watch live hazards. Outputs. Which areas meet a trigger, hazard layers, dashboards, scheduled change summaries. Supporting data sources. GDACS, NASA EONET, NASA FIRMS (needs a free key), your own forecast tables (GloFAS and rainfall are not fetched automatically).

evaluate_forecast_trigger -- new (H4)

Applies your threshold, lead window and probability cut-off to forecast rows already in a layer or table and reports activated areas. Map output: none (a table and the rule in words). Better results: give the threshold, comparison, lead days and probability from your trigger protocol -- the tool has no defaults; include a date and a unit field; check rows_skipped.

fetch_gdacs_disaster_alerts / fetch_nasa_eonet_events / fetch_nasa_active_fires

Live hazard layers. Map output: GDACS points coloured Red / Orange / Green (with a grey "other"); EONET points coloured by event category; fires as small orange dots. Styled when the layer is first created, so a refresh keeps any restyling you did. Better results: pass a bounding box as [min_lon, min_lat, max_lon, max_lat]; GDACS alerts "may require further validation" -- do not act on one without confirmation.

generate_situation_dashboard

Fetches the three hazard feeds for a box and writes one HTML dashboard. Map output: an interactive web map (needs internet to view). Better results: give a tight box and a title.

run_monitoring_workflow / schedule_recurring_workflow / stop_recurring_workflow / list_scheduled_workflows

Re-run a saved set of read-only analyses and report what changed; schedule it while QGIS is open. Map output: change summaries in chat. Better results: save the preset first; remember schedules stop when QGIS closes.

create_print_layout with template='sitrep' -- new (HX1c)

A one-page situation report: map, legend, scale bar and a structured text panel with SITUATION (your body_text), KEY FIGURES, HOW TO READ THIS MAP (when access layers are visible), SOURCES and HANDLING. Map output: a print layout, exportable to PDF or PNG. Better results: pass the headline figures as key_figures copied from tool results (label, value, source; at most 8) and the data sources as sources; the handling note (estimates, no exact locations of people or sensitive sites) and the preparation date are always added. With nothing supplied the report holds only the handling note and the reply says so. A long summary is shortened to fit the panel; the sources and the handling note never are.

---

Cross-cutting tools

Data quality and governance

check_pcode_uniqueness, check_pcode_hierarchy, validate_schema / list_schema_contracts, get_dataset_status / set_dataset_status / advance_dataset_status, get_provenance_record / write_provenance_sidecar, set_layer_sensitivity / get_layer_sensitivity, generate_map_product_qa_checklist. Map output: none. Better results: run the P-code checks before any join; advance a layer's status only after the checks pass; tag sensitive layers before exporting or using a cloud model.

Reporting and products

generate_chart, generate_html_dashboard, generate_temporal_dashboard, generate_spatial_report, generate_report. Map output: charts, interactive HTML maps, Word and Markdown reports. Better results: use the HTML dashboard for non-GIS audiences; pass source_layers to reports so provenance is included.

Engineering hydrology

parse_dms_location, assess_watershed_hydrology_request, calculate_rational_watershed_peak_flow. Map output: none. Better results: supply measured basin area, flow length, elevations and a cited local rainfall intensity; the tools refuse to invent them.

---

Map styling review

What each tool's map output looked like before this review, and now. "Default" means QGIS's raw random single-colour or unstretched look.

Tool	Layer it creates	Before the review	Now
generate_mapping_task_grid	task polygons	default colour	priority colours, task-id labels
apply_network_barriers	speed field only	nothing visible	separate red / orange layer of affected segments
design_sampling_frame	sample points	default colour	one colour per stratum
fetch_gdacs_disaster_alerts	alert points	default colour	Red / Orange / Green plus "other"
fetch_nasa_eonet_events	event points	default colour	colour per category plus "other"
fetch_nasa_active_fires	fire points	default colour	small orange dots
calculate_raster_change_detection	difference raster	unstretched grey	diverging blue-white-red, zero transparent
calculate_service_area, classify_facilities_by_access, population_access_gap, score_route_incident_risk, optimize_delivery_route	routing layers	already styled (cost bands, within/beyond, reach figures, risk corridor, route line)	unchanged
fetch_worldpop_population, hotspot_analysis	rasters	already styled	unchanged
fetch_hdx_admin_boundaries, fetch_geoboundaries	boundaries	already a pale backdrop with labels	unchanged
add_incident_point, add_point_layer, load_tabular_data_as_layer	points	already styled	unchanged

Still not automatically styled (a deliberate or open gap).

• calculate_severity_index, calculate_presence_gap, calculate_population_in_need, calculate_damage_exposure_severity, calculate_mcda_ranking write fields onto your layer; they do not restyle it, because that layer is yours. Ask for apply_graduated_style (scores, ranks) or apply_categorized_style (gap status) as the next step.
• fetch_osm_features / ingest_osm_features, fetch_building_footprints, extract_features_from_imagery, weighted_overlay_analysis: default look; open gap, listed in the implementation tracker.
• evaluate_forecast_trigger and aggregate_survey_indicator produce tables, not map layers; join their results to admin polygons to map them.

Verification. The pure parts (palettes, ordering) are unit tested offline. The QGIS styling code has live tests (tests/test_humanitarian_style_live.py) that were written without a local QGIS; their first execution is CI, and none of the looks has been seen on a real canvas.

analyze_critical_links -- new (HX3c)

Screens a road network for bottlenecks: how much origin-to-destination demand has its shortest path through each road segment. Map output: a new line layer critical_links drawn in five load classes, light to heavy orange-red with increasing width; segments no route uses are not drawn. Better results: give origins (hubs) and destinations (sites) and, if you have them, weight fields (population, caseload) -- without weights the load counts OD pairs. It is a screening of dependence, not a closure simulation and not a traffic forecast: one shortest path per pair, no congestion, convoy size or security. Origins are capped (default 50, max 200) and a time budget labels a partial run; for national road data clip the network to the area first. Closed roads (negative speed) are removed; destinations beyond max_snap_m of the road are left out and counted.

import_jiaf_inputs, record_jiaf_setup, get_jiaf_setup -- new (HX5 stage 2)

Support for people running the JIAF 2 process; not the JIAF method and not endorsed by OCHA or the IASC, and no joint PiN, flag or severity is computed yet (stage 3). import_jiaf_inputs reads and validates the sector inputs from the OCHA Workspace 3A/3B worksheet, an HXL-tagged published table (such as the Yemen HNO files) or the manual's per-sector template; it reports units, sectors found, per-sector totals and every problem (severity must be a phase 1-5, with 0 reported as not-applicable; PiN a non-negative number; duplicates and missing values listed, never filled) and returns stored Preliminary/Final columns only as stored. Optionally joins to an admin layer by P-code and, after confirmation, writes jp_<sector> (PiN) and js_<sector> (severity) fields. record_jiaf_setup stores the country, cycle, unit of analysis, manual edition, scope and each sector's alignment self-assessment in the project; get_jiaf_setup reads it back. Map output: none yet. Better results: pass the edition you follow; give an explanation wherever a sector is not aligned.

compute_jiaf_preliminary -- new (HX5 stage 3)

Computes the preliminary JIAF 2 figures from sector inputs (support for the JIAF 2 process; not the JIAF method, not endorsed by OCHA or the IASC). Per unit: the preliminary joint PiN (the highest of the eight main sectors' PiN -- the Mosaic Method; never an average, never a sum across sectors; the AoRs are excluded), the PiN flags 1-6 of Reference Table 3A, the preliminary intersectoral severity from the overlap of sectoral severities, and the severity flags 1-4 of Table 3B1. The national figure is the sum over units. It is not the Final PiN or the final severity: those are group decisions for flagged units. There is no national severity and no PiN per severity phase. Map output: none automatic; optionally writes jf_pre_pin, jf_pre_sev, jf_npinfl, jf_nsevfl to an admin layer after confirmation, and a per-unit CSV. Better results: use OCHA's Worksheet 3A/3B itself (its Thresholds named cells, sub-population list and historical table are read from the file); give the analysts' outcome-indicator phases for severity flags 2-3. Flag rules: the default profile ocha_worksheet_2026 implements the flag formulas read from the cells of OCHA's official Worksheet 3A/3B example and template workbooks (distinct-value ranks, a tie for the highest switches flags 2 and 3 off, flag 1 counts blank and zero sectors at zero_pin_thresh, flag 6 is two parts, and the worksheet's Preliminary PiN is the highest PiN only where the severity is above 2). Every cached flag, severity and preliminary-PiN value of the example workbook's 6 units is reproduced; thresholds come from the workbook, else the template defaults, and each result says which (threshold_sources). The older manual_reading profile (this tool's earlier interpretation of the manual) is kept for comparison only. Items still unconfirmed are listed in every result as readings_to_confirm.

record_jiaf_decisions, get_jiaf_decisions, finalize_jiaf_results, compute_jiaf_patterns -- new (HX5 stage 4)

Support for people running the JIAF 2 process; not the JIAF method and not endorsed by OCHA or the IASC. record_jiaf_decisions records what the multi-partner group decided for flagged units -- which main sector's PiN becomes the Final PiN (the manual offers the highest or second highest; any main sector is accepted and its rank reported; a rationale is required) and the agreed intersectoral severity phase 1-5 with its evidence basis and evidence -- in the QGIS project; it decides nothing. finalize_jiaf_results applies them: an unflagged unit keeps the preliminary figures, a flagged unit uses its decision, and a flagged unit with no decision is pending (its Final PiN is shown at the highest sectoral PiN as a provisional figure, totalled separately, and its final severity is left empty). bulk_accepted_flags closes units whose only fired PiN flags are the ones the team agreed to close together. The Final PiN total is a sum over units; there is no national severity and no PiN per severity phase. compute_jiaf_patterns produces the lists and counts of the ten Workspace 3C questions with country-level thresholds (the manual's defaults where it gives one; the others are the module's and are echoed). Map output: optional jf_fin_pin, jf_fin_sev, jf_pin_rk and jf_nsec40, jf_nsev45 fields after confirmation (then apply_humanitarian_look can draw the PiN field); a per-unit CSV with the Evidence & Comments. Better results: record a rationale for every PiN decision; do not close a flag in bulk that the team has not agreed to close.

Coverage rule (added to the JIAF tools above). Incomplete sector coverage is never turned into phase 1. The sectors in scope (sectors_in_scope, default all eight main sectors; narrow it only to the sectors the HCT activated) that have no phase are missing; if they could change the preliminary severity the unit has no preliminary severity, with status incomplete_coverage and a lower and upper bound, and it needs a recorded severity decision. A severity of 0 is not applicable by default (as in the Yemen worksheet's CCCM column) or missing with zero_severity_as='missing'. A unit with a missing sector PiN keeps the highest of the reporting sectors and is marked as a lower bound. The preliminary result, the review status, the final result and the justification (with who decided and when) are separate columns in the CSV and separate results, and jf_pin_st / jf_sev_st carry the review status on the layer.

Validation blockers for the JIAF tools (neither is marked complete). (1) Flag formulas -- compared, awaiting the owner's closure. The flags are now OCHA's worksheet formulas and reproduce the official example workbook and the stored preliminary PiN and severity of Yemen's 333 units. Not yet verified: flag 6 on real output (the example's historical table is empty), flag 3 when the 3rd highest PiN is exactly 0 (formula text and Excel's text-versus-number rule only), severity flag 4 (the worksheet's formula and its header disagree; the formula is implemented), a real country's threshold values, and the flag decisions Yemen's analysis team actually took (its workbook holds values only; how many units were flagged or pending needs the team's records). Closing flags in bulk needs a recorded rationale (bulk_rationale). (2) Annex 4 reader -- open; an unsupported optional format. It was implemented from the manual's screenshots, is never detected automatically (only input_format='sector_template' reads it), and its compatibility with real files is unverified; neither the Yemen worksheet nor OCHA's Worksheet 3A/3B can validate it. Do not describe the JIAF tools as a faithful or complete JIAF implementation until the owner has closed both (see docs/JIAF2_ANALYSIS_SUPPORT_PLAN_2026-10-04.md, sections 11 and 11.2).

Sectors counted, published values, and not-assessable checks (JIAF tools). The eight main sectors are the only ones counted in the joint PiN, the flags and the severity; the four Protection AoRs are shown as separate evidence (aor_evidence) and never counted as additional sectors. Flag 1's threshold is the team's choice: results show how many units it would flag at each threshold, counting missing and zero PiN together or each alone (flag_1_sensitivity). Published final PiN and severity are imported beside the calculated figures and never overwrite them; where a published final PiN differs from the preliminary one and no decision is recorded here it is listed as undocumented. Stored values that disagree with the recomputed ones are preserved and listed (source_discrepancies). Blank outcome-indicator evidence makes severity flags 2 and 3 not assessable, not passed. Each result names the import adapter used and what it was validated against: OCHA's official example workbook, the Yemen worksheet and the published Yemen datasets are validated; the Annex 4 template reader is an unsupported optional format. The worksheet is read through its Excel tables (tblPiNAnalysis, tblSeverityAnalysis, tblPiNHistorical) with columns matched by header text, and a unit's identity is the worksheet's own (population group + pocket of need + Admin 3/2/1 P-code), so a pocket of need in the same Admin 2 is a separate unit. Where the worksheet's severity-above-2 rule gives a unit a Preliminary PiN of 0, the calculated and stored values agree and nothing is reported as a discrepancy (earlier versions wrongly listed Yemen's YE1920 and YE1928 as source discrepancies).