Market Access and Site Planning

Purpose

Market Access and Site Planning evaluates market accessibility, trade area definition, site suitability for retail/commercial facilities, and competitive positioning. Supports site selection and market penetration strategy.

Typical Questions This Tool Helps Answer

• Which candidate site gives the strongest coverage gain with acceptable competitive overlap?
• Are we under-served, balanced, or saturated in each target area?
• How do candidate rankings change under peak-hour impedance and routing restrictions?

Background

Network planning workflows use graph-theoretic representations of roads, routes, or linear assets, where node-edge topology and impedance attribution directly control results. Missing restrictions, incorrect turn logic, or stale demand assumptions can dominate outcome quality.

These tools are best interpreted as constrained optimization and diagnostics frameworks. Decisions should be based on trade-offs across service, resilience, and cost objectives rather than any single metric.

Market-access intelligence merges catchment logic, travel impedance, and competitive overlap to rank candidate sites. Decision confidence improves when sensitivity to demand assumptions is explicitly reviewed.

Methodological Considerations

• Topology validation should precede optimization or scenario simulation.
• Explicitly represent operational constraints (time windows, restrictions, capacities, closures) before comparing objective outcomes.
• Test outcomes under stress scenarios so selected plans remain stable under realistic disruptions.

Practical Interpretation Pitfalls

Single-metric improvements can hide degraded resilience or equity; compare candidate plans across multiple KPIs and scenario conditions.

Inputs

Role Split (Important)

• sites_existing: your incumbent baseline sites used for existing coverage and coverage-gain calculations.
• competition_sites: optional separate competitor layer used for overlap pressure.
• If competition_sites is not provided, overlap is computed against sites_existing.
• For most business scenarios, place your current sites in sites_existing and other providers in competition_sites.

Parameters

• ring_costs (required): JSON array of positive numeric thresholds, for example [5.0, 10.0, 15.0].
• The model uses max(ring_costs) as the catchment threshold.
• Units follow your network impedance units.

Candidate Generation and Selection

• candidate_mode (optional): user_supplied (default) or generated.
• num_sites_to_select (optional, default 1): number of top sites to flag as selected.
• selection_strategy (optional, default single_best): single_best or top_k_greedy.
• min_new_site_separation (optional): minimum separation distance between selected sites.
• max_generated_candidates (optional, default 250): max generated seed candidates when candidate_mode="generated".

Optional Routing Cost Parameters

Forwarded routing parameters:

• cost_method
• edge_cost_field
• one_way_field (accepts FT/TF/B codes and legacy boolean values)
• mode_field
• default_mode_speed
• mode_speed_overrides
• allowed_modes
• temporal_cost_profile
• temporal_edge_id_field
• departure_time
• temporal_mode
• temporal_fallback
• turn_penalty
• u_turn_penalty
• forbid_u_turns
• forbid_left_turns
• forbid_right_turns
• turn_restrictions_csv
• node_cost_points
• node_cost_field
• node_cost_snap_distance

How Ranking Works

Per candidate site:

• Demand coverage percent: share of demand points within threshold.
• Average distance to demand: mean network cost to demand points.
• Competitive overlap percent: share of competitor points within threshold.
• Accessibility score: normalized inverse average-distance score on a 0-100 scale.
• Composite rank score: 0.50 * demand_coverage_pct + 0.25 * accessibility_score + 0.25 * (100 - competitive_overlap_pct).

Opportunity band definitions:

• expand_now: composite >= 80, coverage gain > 5, overlap < 40
• pilot: composite >= 65 and coverage gain > 0
• saturated: overlap >= 60
• monitor: everything else

Outputs

Map interpretation note:

• catchments_output stores one polygon per candidate site; these are candidate trade-area polygons, not separate ring-band isochrone polygons.
• Catchments are built as convex hulls of covered demand points plus each candidate point.
• When a hull cannot be formed (insufficient valid geometry), a small fallback square polygon is written.
• overlap_analysis_output is a point layer. If you see squares there, it is typically point marker symbology.

Runtime output keys (returned in ToolRunResult.outputs):

catchments_output fields

• SITE_ID, COV_PCT, ACC_SCORE, OVR_PCT, RANK

overlap_analysis_output fields

• SITE_ID, OVR_PCT, GAIN_PCT, OPP_BAND, CMP_SCORE, TOT_COMP

candidate_rank_csv columns

rank,site_id,x,y,demand_coverage_pct,coverage_gain_pct,unmet_demand_count,avg_distance_to_demand,competitive_overlap_pct,accessibility_score,composite_rank_score,opportunity_band,selected_in_top_k

market_action_queue_csv columns (optional)

rank,site_id,opportunity_band,coverage_gain_pct,composite_rank_score,recommended_action

executive_summary_json keys

• analysis_timestamp, schema_version, total_candidates_evaluated, total_demand_points
• market_metrics, top_ranked_candidates, decision_rationale, recommendation, decision_gate

Decision gate rule:

• decision_gate=true when average candidate coverage is above 70% and average overlap is below 50%.

Example

import whitebox_workflows as wbw

env = wbw.WbEnvironment()
env.market_access_and_site_intelligence_workflow(
  network="street_network.gpkg",
  sites_existing="existing_sites.gpkg",
  sites_candidates="candidate_sites.gpkg",
  demand_surface="demand_points.gpkg",
  competition_sites="competitors.gpkg",
  ring_costs=[5.0, 10.0, 15.0],
  catchments_output="outputs/candidate_catchments.gpkg",
  overlap_analysis_output="outputs/competitive_overlap.gpkg",
  candidate_rank_csv="outputs/candidate_ranking.csv",
  executive_summary_json="outputs/market_summary.json",
  market_action_queue_csv="outputs/market_action_queue.csv",
  html_report="outputs/market_access_report.html"
)

Generated-candidate mode with temporal and turn-aware routing:

env.market_access_and_site_intelligence_workflow(
  network="street_network.gpkg",
  sites_existing="existing_sites.gpkg",
  demand_surface="demand_points.gpkg",
  competition_sites="competitors.gpkg",
  ring_costs=[5.0, 10.0, 15.0],
  candidate_mode="generated",
  selection_strategy="top_k_greedy",
  num_sites_to_select=5,
  min_new_site_separation=1000.0,
  max_generated_candidates=250,
  edge_cost_field="MINUTES",
  one_way_field="ONEWAY",
  node_cost_points="intersection_delay_points.shp",
  node_cost_field="DELAY_MIN",
  node_cost_snap_distance=25.0,
  turn_penalty=0.3,
  u_turn_penalty=2.0,
  forbid_u_turns=True,
  temporal_cost_profile="am_peak_profiles.csv",
  temporal_edge_id_field="EDGE_ID",
  departure_time="2024-06-15T08:00:00Z",
  temporal_mode="multiplier",
  temporal_fallback="static_cost",
  catchments_output="outputs/candidate_catchments_peak.gpkg",
  overlap_analysis_output="outputs/competitive_overlap_peak.gpkg",
  candidate_rank_csv="outputs/candidate_ranking_peak.csv",
  executive_summary_json="outputs/market_summary_peak.json",
  market_action_queue_csv="outputs/market_action_queue_peak.csv",
  html_report="outputs/market_access_report_peak.html"
)

References

• Huff, D. L. (1963). "A Probabilistic Analysis of Shopping Center Trade Areas." Land Economics 39(1), 81–90.

Parameter Interaction Notes

ring_costs selection is the highest-impact control:

• Lower thresholds produce tighter catchments and usually lower overlap.
• Higher thresholds increase coverage and often increase overlap in dense markets.
• Always interpret scores in context of demand-point quality and completeness.

QA and Acceptance Criteria

Use a staged acceptance approach for Market Access and Site Planning:

1. Validate projected CRS and non-empty network/candidate/demand point inputs.
2. Confirm all required output paths are set and writable.
3. Verify candidate ranking aligns with known market context.
4. Re-run with same inputs to confirm deterministic outputs.

Recommended acceptance checks:

• Candidate count in CSV matches evaluated candidate points.
• Output layers contain expected attribute fields.
• Executive summary includes valid top candidates and decision gate.

Advanced Operational Guidance

For production deployment of Market Access and Site Planning:

• Keep demand and competitor snapshots date-stamped for consistent comparisons.
• Use the action queue as a planning filter, then run standard site due diligence before commitment.

Implementation Patterns

Common implementation patterns with Market Access and Site Planning:

• Baseline run with current market snapshot.
• Sensitivity run with alternate ring_costs arrays.
• Governance run with archived summary JSON and ranking CSV.

Related Tools

Use Market Access and Site Planning together with upstream conditioning and downstream validation tools in the same bundle to ensure end-to-end consistency and stronger decision confidence.

When To Use This Workflow

Market Access and Site Planning is most valuable when teams need measurable service-level improvements (coverage, response time, cost-to-serve) with governance-ready transparency.

What this workflow helps you achieve:

• Translates network complexity into decision-ready options.
• Supports defensible operational planning with explicit constraints.
• Creates repeatable workflows for quarterly and annual optimization cycles.

Results Delivery Checklist

Before sharing results with stakeholders:

1. Validate network topology and impedance attributes for all served areas.
2. Confirm objective function matches business KPI priorities.
3. Document constraints (capacity, time windows, exclusions) in deliverable notes.
4. Provide baseline-vs-optimized comparison metrics.
5. Include at least one scenario stress test (demand spike, outage, or route closure).

Common Questions

Q: Why does a high-coverage candidate sometimes rank lower?
A: Ranking also penalizes high competition overlap and poor relative accessibility.

Q: What does decision_gate=false mean?
A: Average candidate coverage did not exceed 70% and/or average overlap was not below 50%.

Q: Are catchments true isochrone polygons?
A: Current implementation outputs hull-based catchment polygons from covered demand points.

Q: Can polygon demand data be used directly?
A: Convert polygon demand to centroid points first for reliable scoring.