Humanitarian Logistics

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

calculate_service_area

Calculate the reachable road-network area around one or more facilities (warehouse, clinic, distribution point) within a given travel distance or time -- e.g. 'what area can this warehouse serve within 30km by road'. Produces, per facility, both the reachable road network and an approximate coverage polygon (convex hull around it). Requires a real line layer representing the road network -- for simple straight-line/as-the-crow-flies coverage, use buffer_analysis instead. Without speed_field, every road segment is treated as one flat default_speed regardless of surface or condition, which overstates reachability on unpaved/damaged roads -- when the network layer has a per-segment speed or condition field (e.g. from OSM highway/surface tags), pass it as speed_field with strategy='fastest' for a more realistic area. direction_field makes one-way roads one-way instead of assuming every segment is traversable both directions. Pass travel_cost as a LIST (e.g. [15, 30, 60]) instead of a single number for a real isochrone/access-band map: builds one combined polygon layer per facility with a travel_cost_band field, one ring per value, auto-styled with a graduated renderer -- a single call instead of one per band plus manual styling.

Parameter	Type	Required	Description
facility_layer	string	yes	Point layer with the facility/facilities to calculate service areas for.
road_network_layer	string	yes	Line layer representing the road/path network.
travel_cost	any	yes	Maximum travel distance in METRES (real-world, measured on the ellipsoid whatever the layers' CRS is) or time in HOURS if strategy='fastest'. Pass a single number for one service area, or a list of ascending values (e.g. [15, 30, 60]) for a multi-band isochrone/access map -- one combined, auto-styled polygon layer per facility instead of separate calls.
strategy	string	no	'shortest' (distance-based, default) or 'fastest' (time-based).
default_speed	number	no	Default travel speed in km/h for any segment with no speed_field value, used only when strategy='fastest'. Defaults to 50.
speed_field	string	no	Optional numeric field on road_network_layer giving per-segment speed in km/h (e.g. derived from OSM highway/surface tags). Only affects routing when strategy='fastest'.
direction_field	string	no	Optional field on road_network_layer marking one-way segments (e.g. OSM's 'oneway' tag). Segments with no matching value still route both ways.
style_by_cost	boolean	no	Default true: also add a road layer graded by travel cost (near = dark, far = warm, labelled bands) and hide the plain reached-roads line layer, which stays in the project for analysis. Set false to keep only the plain lines.
value_forward	string	no	direction_field value meaning forward-only travel. Defaults to 'yes' (OSM convention).
value_backward	string	no	direction_field value meaning backward-only travel. Defaults to '-1' (OSM convention).
value_both	string	no	direction_field value meaning both directions. Defaults to 'no' (OSM convention).

classify_facilities_by_access

Answer 'which facilities are within / beyond N hours (or N metres) of this origin' FAST. Runs ONE service area from origin_layer (seconds, the same engine as calculate_service_area) and labels every facility in facility_layer 'within' when it lies on or within snap_distance_m of a road reached inside travel_cost, else 'beyond'. Use THIS instead of travel_time_matrix for any 'beyond/within X of the origin' question over many facilities: travel_time_matrix ties every destination into the road graph and took ~44 minutes for 3,369 facilities. Adds a copy of the facility layer with access_class and dist_to_reach_m fields, plus the service-area layers. For a DISTANCE budget (strategy 'shortest') over up to 200 facilities each facility is routed and 'within' means road distance PLUS the straight leg from the road to the facility is inside the budget; the result says method 'routed' and snap_distance_m is not used. For a time budget, or more facilities, it is an APPROXIMATION to state in the answer: it ignores the access leg from the road to the facility (up to snap_distance_m) and is not a per-facility routed cost; pass a small snap_distance_m (for example 50) so a facility far from the road is not counted as reached.

Parameter	Type	Required	Description
origin_layer	string	yes	Point layer holding the origin(s) the travel cost is measured from.
facility_layer	string	yes	Point layer of the facilities to classify.
road_network_layer	string	yes	Line layer of the road/path network.
travel_cost	number	yes	Max travel distance in METRES (strategy='shortest') or time in HOURS (strategy='fastest').
strategy	string	no	'shortest' (distance, default) or 'fastest' (time).
default_speed	number	no	Default speed in km/h, used only when strategy='fastest'. Defaults to 50.
speed_field	string	no	Optional per-segment speed field (km/h); ignored with a note if mostly empty.
direction_field	string	no	Optional one-way field on the road layer.
snap_distance_m	number	no	A facility counts as reached when it is within this many metres of a reached road. Defaults to 500.

estimate_road_speeds

Write an 'assumed_speed_kmh' field onto a road network layer's features, filled in from a fixed table of typical speeds per road class (motorway/primary/residential/track/etc, common routing-profile values -- see ASSUMED_SPEED_BY_ROAD_CLASS_KMH), read from the layer's 'fclass' (Geofabrik OSM extracts) or 'highway' (OSM/Overpass ingests) field. Use this when a road network has little or no real maxspeed data (very common: a real Jordan extract had maxspeed on only 0.9% of roads) and calculate_service_area/travel_time_matrix/optimize_delivery_route with strategy='fastest' would otherwise fall back to one flat default speed for nearly every road. IMPORTANT: this is an ASSUMPTION, not measured data for this specific road network -- tell the user the travel times that follow from it are estimates based on typical road-class speeds, not this network's real posted limits, especially if they ask for a precise duration. Never call this automatically as part of another tool's workflow; only when the user has actual maxspeed data will speed_field give a materially better answer. Pass country (an ISO 3166-1 alpha-2 code, e.g. 'JO', 'DE', 'US') to scale the table to that country's real legal urban/rural/motorway speed limits (see COUNTRY_SPEED_TIERS_KMH) instead of the generic global defaults -- covers a curated set of countries; falls back to the generic table for any other code or when omitted. Destructive action requiring UI confirmation -- in-place attribute mutation on the live layer, same class of operation as calculate_area/field_calculator.

Parameter	Type	Required	Description
road_network_layer	string	yes	Line layer of the road network, with an 'fclass' or 'highway' field.
default_speed_kmh	number	no	Speed assumed for a road class not in the table (default 30).
overwrite	boolean	no	If assumed_speed_kmh already exists, overwrite it. Default false: existing values are left alone, only missing/null ones are filled in.
country	string	no	Optional ISO 3166-1 alpha-2 country code (e.g. 'JO', 'DE', 'US') to scale the speed table to that country's real legal urban/rural/motorway limits instead of generic global defaults. Unrecognized or omitted falls back to the generic table.

location_allocation

Choose the best COMBINATION of num_facilities locations (out of a larger candidate list) to collectively minimize distance to all demand points -- e.g. 'which 3 of these 10 possible warehouse sites should we actually build, together, to best cover all these villages'. Different from optimal_hub_siting, which ranks candidates independently and doesn't account for overlap between them (two candidates both close to the same villages don't both get credit for covering them here). Uses a standard greedy approximation, not a guaranteed globally-optimal solution -- exact optimization is computationally infeasible beyond a handful of candidates anyway.

Parameter	Type	Required	Description
candidate_layer	string	yes	Point layer of possible facility locations.
demand_layer	string	yes	Point layer of locations needing service.
num_facilities	integer	yes	How many facilities to select.
weight_field	string	no	Optional numeric field on demand_layer to weight points by (e.g. population). Defaults to equal weight.

optimal_hub_siting

Rank candidate hub/warehouse/facility locations by how well they serve a set of demand points (e.g. villages, distribution sites) -- for each candidate, computes the average straight-line distance to all demand points and (if max_distance is given) how many fall within it. Returns candidates ranked best (lowest average distance) first. Use this instead of eyeballing a map when choosing between several possible hub locations. Uses straight-line distance, not road network distance -- for network-based reachability use calculate_service_area instead.

Parameter	Type	Required	Description
candidate_layer	string	yes	Point layer of possible hub/facility locations to evaluate.
demand_layer	string	yes	Point layer of locations needing service (villages, distribution sites).
max_distance	number	no	Distance (in the layers' CRS units, usually meters) within which a demand point counts as 'served'. Omit to rank on average distance alone.

optimize_delivery_route

Find a good visiting order for a set of delivery/distribution stops -- e.g. 'what order should the truck visit these 8 distribution points'. Uses a standard nearest-neighbor + 2-opt heuristic to pick the order (not a guaranteed globally-optimal order). Without road_network_layer, ordering uses straight-line distance and the result is a stop order only -- do NOT draw a straight line between the stops and present it as a route on an operational map; it is not a routable path. Pass road_network_layer to make the ordering itself road-network-aware (real road distance between every pair of stops, not straight-line) and to build an actual road-snapped route line, added to the project and safe to render as a real route. speed_field/direction_field (same meaning as calculate_service_area's) only affect ordering when road_network_layer is given. Not a substitute for a full commercial VRP solver with vehicle capacity/time-window constraints. If the start (a hub, depot) and the stops are in DIFFERENT point layers, name the others in additional_stops_layers -- do not write a script to merge them first.

Parameter	Type	Required	Description
stops_layer	string	yes	Point layer of stops to visit.
additional_stops_layers	array[string]	no	Optional other point layers whose features are added to the stops (for example the depot layer when the stops are in another one). They are reprojected into stops_layer's CRS, and start_stop_name can name a stop from any of them.
start_stop_name	string	no	Optional name (from the layer's first attribute field) of the stop to start from. Defaults to the first feature.
road_network_layer	string	no	Optional line layer representing the road/path network. When given, visiting order uses real road-network distance (not straight-line) and a road-snapped route line is built and added to the project -- required before the output may be rendered as a route on a map.
speed_field	string	no	Optional numeric field on road_network_layer giving per-segment speed in km/h. Only affects ordering when road_network_layer is given.
direction_field	string	no	Optional field on road_network_layer marking one-way segments (e.g. OSM's 'oneway' tag). Only affects ordering when road_network_layer is given.
value_forward	string	no	direction_field value meaning forward-only travel. Defaults to 'yes' (OSM convention).
value_backward	string	no	direction_field value meaning backward-only travel. Defaults to '-1' (OSM convention).
value_both	string	no	direction_field value meaning both directions. Defaults to 'no' (OSM convention).
strategy	string	no	'shortest' (distance-based, default) or 'fastest' (travel time). Use 'fastest' when the user asks for the fastest route or a travel time; it needs road_network_layer. The time is an ESTIMATE from speed_field (km/h per segment) or default_speed, not measured traffic.
default_speed	number	no	Speed in km/h for road segments with no speed_field value. Only used with strategy='fastest'. Defaults to 50.

population_access_gap

Compute how many people, and what percentage of a population base, are BEYOND a given travel distance/time from the nearest facility -- e.g. 'X people / Y% of the population are more than 30 minutes from a functioning health facility', the standard access-to-services statistic in humanitarian gap analysis and cluster reporting. A thin composite over calculate_service_area (network-based reach per facility) and estimate_population_exposure (population sum within a polygon) rather than reimplementing either -- area_layer defines the population base to check coverage for (e.g. an admin-boundary or catchment polygon) and must already have a population raster available (see fetch_worldpop_population). As a side effect of calling calculate_service_area internally, per-facility service-area polygons are also added to the project, plus the combined reachable-area layers this tool builds from them. It reports THREE labelled figures (reach_figures): a concave hull of the reached roads (the headline, the method used in published hospital-access work), the reached roads buffered by reach_buffer_m (a tight lower figure) and the convex hull (an UPPER BOUND that fills the land between roads). Always give the user the range (reachable_population_range), not only the headline. Returns a MODELED estimate -- network-based reachability against a gridded population raster, not a verified count of people confirmed to lack access -- report it as 'an estimated N people/percent are beyond X', not as a confirmed access-gap figure.

Parameter	Type	Required	Description
facility_layer	string	yes	Point layer of facilities (health centers, warehouses, etc.).
road_network_layer	string	yes	Line layer of the road/path network.
population_raster_layer	string	yes	Population-per-pixel raster (e.g. from fetch_worldpop_population).
area_layer	string	yes	Polygon layer defining the population base to check coverage for.
travel_cost	number	yes	Max travel distance in METRES (real-world, whatever the layers' CRS is) or time in HOURS if strategy='fastest'.
strategy	string	no	'shortest' (distance-based, default) or 'fastest' (time-based).
default_speed	number	no	Default travel speed in km/h, used only when strategy='fastest'. Defaults to 50.
reach_geometry	string	no	Which figure is the headline: 'concave_hull' (default), 'road_buffer' (people within reach_buffer_m of a reached road) or 'convex_hull' (an UPPER BOUND). All three are always reported in reach_figures.
reach_buffer_m	number	no	Buffer distance in metres around the reached roads for the road-buffer figure. Defaults to 500.
speed_field	string	no	Optional numeric field on road_network_layer giving per-segment speed in km/h, same meaning as in calculate_service_area. Pass it when the request names one (for example the speed_blocked field written by apply_network_barriers): without it, blocked or slowed roads are ignored and the people-beyond figure is wrong. Only affects routing when strategy='fastest'.
direction_field	string	no	Optional one-way field on road_network_layer, same meaning as in calculate_service_area.

score_route_incident_risk

Score a planned route (or any line layer) against how close it passes to recent security/safety incidents -- 'does this route go near any recent incidents'. Reuses buffer_analysis's exact processing call to build a buffer around the route, then counts/lists incident_layer points falling within it, each with its own distance to the route. Optionally restrict to recent incidents only (date_field + days_back) and/or weight by a numeric field (e.g. a severity score) for a weighted risk total instead of a flat count. The buffer layer it creates is auto-styled as a translucent orange risk corridor (not QGIS's default random single-symbol color) so it reads as risk on the map without a separate styling call. Does NOT re-route or exclude anything automatically -- this scores a route for a human to act on; for a genuine hard-exclude of a security-restricted area from routing itself, use difference_layers to remove that area from the road network layer before calling calculate_service_area/travel_time_matrix, see docs/archive/ROUTE_RISK_AND_NOGO_ZONES_SPEC.md.

Parameter	Type	Required	Description
route_layer	string	yes	Line layer of the planned route (any line layer -- a hand-drawn route, a road-network subset, etc.).
incident_layer	string	yes	Point layer of incidents to check proximity against, e.g. the shared 'Incidents' layer from add_incident_point.
buffer_distance	number	yes	How close counts as 'near' the route, in the layers' CRS units (usually meters).
date_field	string	no	Optional date field on incident_layer, required if days_back is set.
days_back	integer	no	Optional: only count incidents from the last N days. Requires date_field.
weight_field	string	no	Optional numeric field on incident_layer (e.g. a severity score) to compute a weighted risk total instead of a flat count.

travel_time_matrix

Calculate road-network distance or travel time from each origin point to each destination point -- e.g. delivery distance from each warehouse to each distribution site. Returns a matrix of costs (metres for strategy='shortest' -- real-world distance whatever the layers' CRS is -- or hours for strategy='fastest') keyed by origin then destination. Requires a line layer representing the road network, not straight-line distance. Without speed_field, every segment is treated as one flat default_speed regardless of surface or condition -- when the network layer has a per-segment speed or condition field, pass it as speed_field with strategy='fastest' for a more realistic matrix. direction_field makes one-way roads one-way instead of assuming every segment is traversable both directions. The costs are along the road only: the result also gives access_leg_m (straight distance from each destination to its nearest road); ADD it when the question is total travel within a budget. SLOW for many destinations (every destination is tied into the road graph, which QGIS does by brute force; ~44 minutes for 3,369): for 'which facilities are within/beyond N of this origin' use classify_facilities_by_access instead; destination layers over 200 features use a single shortest-path tree per origin (fast; each destination is charged the cost to its projected point on the nearest road segment) when the QGIS network classes are available.

Parameter	Type	Required	Description
origins_layer	string	yes	Point layer of origin locations (e.g. warehouses).
destinations_layer	string	yes	Point layer of destination locations (e.g. distribution sites).
road_network_layer	string	yes	Line layer representing the road/path network.
strategy	string	no	'shortest' (distance-based, default) or 'fastest' (time-based).
default_speed	number	no	Default travel speed in km/h for any segment with no speed_field value, used only when strategy='fastest'. Defaults to 50.
speed_field	string	no	Optional numeric field on road_network_layer giving per-segment speed in km/h. Only affects the matrix when strategy='fastest'.
direction_field	string	no	Optional field on road_network_layer marking one-way segments (e.g. OSM's 'oneway' tag). Segments with no matching value still route both ways.
value_forward	string	no	direction_field value meaning forward-only travel. Defaults to 'yes' (OSM convention).
value_backward	string	no	direction_field value meaning backward-only travel. Defaults to '-1' (OSM convention).
value_both	string	no	direction_field value meaning both directions. Defaults to 'no' (OSM convention).
allow_large	boolean	no	Only needed if the fast single-tree method is unavailable: set true to run a matrix over more than 200 destinations the slow way.