HW_02_202602

[jeanpool1415]

Integrative Project: Geospatial Analysis, Accessibility Metrics, and Data Storytelling

Total value: 20 points

This integrative project consists of one end-to-end challenge built in five connected phases, designed to apply knowledge of Python, open data acquisition, data cleaning and validation, geospatial analysis, network routing, metric construction, interactive dashboards with Streamlit, and technical writing in LaTeX.

Each phase one consumes the output of the previous one. A broken phase blocks everything downstream, so incremental delivery and checkpointing are part of the evaluation.

The project will be presented through a single video.

Innovation: Points earned for innovation are additional to the 20 points of the project. These points may be accumulated for the next assignment or used as participation points.

---

General Information

Deadline: September 9, 2026

Repository submission:
https://docs.google.com/spreadsheets/d/1CdYa-YDoPvhCm1MvD1j7ISDLRvByqbQLgn1I42dLTyY/edit?usp=sharing

Each student must register their corresponding GitHub repository in the document.

---

The Problem — "Golden Hour"

In emergency medicine, the golden hour is the window in which a severe trauma or obstetric emergency must reach a facility capable of resolving it. In Peru, a health post (category I-1) can stabilize a patient but cannot perform surgery or a caesarean section. Only facilities from category II-1 upward have that resolutive capacity.

The question this project must answer is:

How long does it actually take, by road, for the population of a given region to reach a health facility with resolutive capacity — and where are the worst gaps?

"Actually" is the hard word. A straight line on a map is not a road. A facility that appears in the registry may be closed. A coordinate in the registry may be in the wrong hemisphere. Your analysis is only as good as your treatment of those problems, and defending that treatment is a large part of your grade.

---

Mandatory Scope

To keep the workload realistic, the analysis is not national.

Each student must analyze exactly three departments, selected so that the set contains:

• One coastal department (e.g. Lambayeque, Ica, La Libertad, Piura)
• One Andean department (e.g. Cusco, Puno, Ayacucho, Huancavelica, Cajamarca)
• One Amazonian department (e.g. Loreto, Ucayali, Amazonas, Madre de Dios, San Martín)

The three departments must be declared in config.md and must be changeable without touching the code. The contrast between geographies is the analytical point of the exercise: a coastal department and an Amazonian department should not behave the same way, and your report must explain why.

Students who wish to run the pipeline nationally may do so as an innovation extension, but the three-department result must exist and must be reproducible.

---

Phase 1 — Data Acquisition and Validation

Value: 3.0 points

Objective

Build a clean, validated, documented geospatial dataset of demand points (where people are) and supply points (where resolutive care is).

Required sources

Supply — health facilities (RENIPRESS, SUSALUD):
https://www.datosabiertos.gob.pe/dataset/registro-nacional-de-entidades-prestadoras-de-servicios-de-salud-renipress

Demand — populated centres with coordinates (MINEDU / SIGMED spatial download):
https://sigmed.minedu.gob.pe/descargas/

Road network (OpenStreetMap, Peru extract):
https://download.geofabrik.de/south-america/peru-latest.osm.pbf

Administrative boundaries (district / province / department polygons): any official source, declared and cited in the report.

Definitions you must implement

A facility counts as resolutive if and only if:

• Its operating status is active, and
• Its category is II-1, II-2, II-E, III-1, III-2 or III-E.

Everything else (I-1 through I-4) is non-resolutive and must be kept in the dataset but excluded from the nearest-facility computation. Category strings in RENIPRESS are not clean — normalizing them is your job, and the normalization rules must be visible in the code.

Required validation layer

The registry contains real errors. Your pipeline must detect and log, at minimum:

1. Records with missing, null, or zero coordinates.
2. Coordinates outside Peru's bounding box (approx. lon −81.4 to −68.6, lat −18.4 to −0.04).
3. Coordinates where latitude and longitude have been swapped.
4. Points that fall outside the district polygon their own record declares.
5. Duplicated facility codes.
6. Encoding problems in text fields (UTF-8 vs. latin-1).

For each rule, the pipeline must produce a data quality report stating how many records were flagged, what was done with them (corrected, dropped, kept with a warning), and why.

Silently dropping bad rows is a failing approach. Dropping them with a logged, justified rule is a passing approach. Correcting the recoverable ones and documenting the recovery rate is an excellent approach.

Technical Considerations

• Raw downloaded files go to data/raw/ and are never modified in place.
• Processed outputs go to data/processed/ in GeoParquet or GeoPackage.
• Every path, department code, category whitelist, and threshold lives in config.md.
• The download step must be re-runnable and must not re-download what already exists.
• If a source portal is down on the day you run it, cache the file in the repository and document the download date.

---

Phase 2 — Routing and Travel-Time Computation

Value: 3.0 points

Objective

For every demand point, compute the road travel time and distance to the nearest resolutive facility — by car — and, for urban demand points, the walking time to the nearest facility of any category.

Required approach

You must use a real road network. A Haversine distance is not a travel time.

Choose one primary routing engine:

Option	Setup	When it fits
OSRM in Docker (recommended)	Build once from peru-latest.osm.pbf (~220 MB); serves unlimited local queries	Best option — no rate limits, full control, fast matrix queries
OSMnx + NetworkX	Downloads and builds a graph per area	Fine for smaller/urban areas; heavy and slow at department scale
OpenRouteService API	Free API key, rate-limited	Acceptable fallback only, with mandatory caching and throttling

Whichever you choose, the following are required:

1. Snapping. Demand and supply points must be snapped to the network. Report how many points failed to snap and how far the average snap moved a point.
2. Caching. Every routing result is written to disk (Parquet). A second run of the pipeline must not recompute what it already has. This is not optional — it is what makes your dashboard demo possible.
3. A full origin × facility matrix for the resolutive set, not just the nearest one. You will need it in Phase 4.
4. A documented fallback. If a demand point is unroutable (island, unmapped road, disconnected component), it must be flagged as such, not silently assigned a straight-line distance. If you use a straight-line estimate with a detour factor, that factor must be justified empirically against your own routed data.
5. Throttling and error handling if you use a remote API. The process must survive a failed request without losing the work already done.

The comparisons you must make

Walking vs. driving. For each demand point, compute the nearest resolutive facility under the foot profile and under the car profile. Report how often the nearest facility differs between the two modes, and how the travel times compare. A facility that is 25 minutes away by car may be 6 hours on foot — or unreachable entirely if the pedestrian network is disconnected.
Cross-mode comparison. For the same set of demand points, compare the travel time to the nearest resolutive facility across all three profiles (car, bike, foot). This is where the analysis gets interesting: the ratio of walking time to driving time is not constant — it depends on terrain, road type, and network connectivity.

These disagreements are not bugs in your pipeline. They are findings your report must discuss. Think about where in Peru you would expect the car-vs-foot ratio to be largest, and check whether the data agrees with you.

Technical Considerations

• Cap the analysis at 5,000 demand points. If your three departments exceed that, apply a documented sampling strategy (population-weighted or stratified by district) and state the sampling error implication in the report.
• Log elapsed time and request counts. The routing step must print progress; a silent 40-minute run is not acceptable.
• The routing module must be importable and testable independently of the pipeline.

---

Phase 3 — Metric Construction and Analysis

Value: 2.0 points

Objective

Turn travel times into decision-grade indicators.

Required metrics

1. Access time t_min(i) — minutes by car from demand point i to the nearest resolutive facility.
2. Coverage bands — share of population within 30 / 60 / 120 minutes, and beyond 120 minutes.
3. Population-weighted mean access time, aggregated at district, province, and department level.
4. Critical gap list — the districts with the worst population-weighted access, ranked.
5. An inequality measure of access — a Gini coefficient or Lorenz curve of population-weighted access time. Justify your choice.
6. Urban vs. rural contrast, using a defensible classification rule that you state explicitly.

Required cross-analysis

At least one metric must combine access with a second dimension — poverty rate, rurality, population under 5, altitude, or similar — and the report must state whether the relationship you find is causal, correlational, or neither.

Technical Considerations

• Aggregation must be population-weighted. An unweighted district average treats a hamlet of 12 people the same as a town of 12,000, and the evaluation will look for this specifically.
• Every metric is produced by a function that takes a DataFrame and returns a DataFrame. No metric logic inside the dashboard code.
• All metric outputs are exported to data/outputs/ as CSV and as the exact tables used in the LaTeX report.

---

Phase 4 — Streamlit Dashboard

Value: 2.5 points

Objective

Deliver an interactive application that lets a non-technical user — a regional health director, say — explore the result and reach their own conclusions.

Minimum required views

1. KPI header — population covered, population beyond 60 minutes, worst district, median access time. Updates with filters.
2. Choropleth map — districts coloured by population-weighted access time, with a working legend and tooltips.
3. Facility layer — resolutive and non-resolutive facilities as points, toggleable, filterable by category and institution (MINSA, EsSalud, private).
4. Distribution view — histogram or ECDF of access time, split by department or by urban/rural.
5. Ranked table — worst districts, sortable, with download-to-CSV.
6. Scenario simulator — the user selects one or more existing I-3/I-4 facilities to "upgrade" to resolutive status, and the dashboard recomputes coverage using the precomputed matrix from Phase 2. Show the marginal gain in population covered.
7. Data quality panel — surfacing the Phase 1 validation counts, so the user can see what the analysis is standing on.

Technical Considerations

• The dashboard reads precomputed files. It must not call a routing API or rebuild a graph at load time. If your app takes more than a few seconds to load, the architecture is wrong.
• Use @st.cache_data for data loading.
• Sidebar filters: department, province, category, institution, time threshold.
• The app must run with a single streamlit run app.py on a clean machine after pip install -r requirements.txt.
• Handle the empty-selection case without crashing.

The scenario simulator is where the matrix from Phase 2 earns its keep. If you only stored nearest-facility distances, you cannot build it — which is the point of asking for the full matrix.

---

Phase 5 — LaTeX Report

Value: 1.5 points

Objective

Write a technical report that states a finding and defends it.

Required structure

1. Abstract — the finding, in numbers, in under 150 words.
2. Introduction and problem statement.
3. Data sources — with access dates, licences, and known limitations of each.
4. Methodology — resolutive-capacity definition, validation rules, routing engine and parameters, metric definitions. Written so that a reader could reproduce your numbers.
5. Results — with at least 3 figures and 3 tables generated by your pipeline, not screenshotted from the dashboard.
6. Discussion — including the straight-line vs. network comparison from Phase 2.
7. Limitations — mandatory and graded. Registry error rates, OSM coverage bias in rural areas, the assumption that a listed facility is actually staffed and operating, the absence of ambulance availability, sampling if you sampled.
8. Conclusions and recommendations.
9. References.

Technical Considerations

• Length: 8 to 12 pages.
• The .tex source and the compiled PDF must both be in the repository. A report that cannot be recompiled from source does not count.
• Figures must be exported from the pipeline as vector PDF or high-resolution PNG. Tables should be generated programmatically (e.g. df.to_latex() with booktabs), not typed by hand.
• Overleaf is acceptable; commit the source either way.

The limitations section is where the difference between a student and an analyst becomes visible. Everyone can produce a number. Knowing what your number cannot support is the harder skill.

---

Presentation

Value: 8.0 points

You must submit a single video of up to 12 minutes.

The presentation carries the largest single weight in this project. A correct analysis that you cannot explain is worth very little, because in practice you will always have to defend your method to someone who did not build it.

Your video must cover:

1. The problem — what question you asked and why it matters.
2. The data — where it came from, what was wrong with it, and what you did about it. Show the data quality report.
3. The method — which routing engine, why, and what the key parameters were.
4. The technical decisions — at least three decisions where you chose between alternatives, and your reasoning.
5. The obstacles — what broke, and how you diagnosed and fixed it.
6. A live demonstration of the dashboard, including the scenario simulator.
7. The findings — the actual numbers, and what you would recommend on the basis of them.
8. The limitations — what your analysis does not prove.

Evaluation of the presentation

Criterion	Points
Problem framing and data pipeline clearly explained	2.0
Live demonstration of the working dashboard	2.5
Defence of methodology and technical decisions	2.0
Presentation of findings, limitations, and recommendations	1.5
Total	8.0

Reading slides aloud will not score well. Expect to be evaluated on whether you understand what you built.

---

Deliverables

• Own GitHub repository, clearly organized, with the structure below.
• README.md with setup instructions, data download steps, and run commands.
• config.md containing all parameters — departments, thresholds, category whitelist, paths, routing engine selection.
• requirements.txt
• Python modules for each phase, with reusable functions.
• data/processed/ and data/outputs/ committed (or a documented script that regenerates them).
• Precomputed routing matrix committed, so the dashboard runs without a routing engine.
• Execution logs, including the data quality report.
• Streamlit application (app.py), runnable locally.
• LaTeX report: .tex source plus compiled PDF.
• A single video of up to 12 minutes.

Suggested repository structure

├── config.md
├── requirements.txt
├── README.md
├── src/
│   ├── acquisition.py      # Phase 1 — download
│   ├── validation.py       # Phase 1 — quality rules
│   ├── routing.py          # Phase 2 — engine + cache
│   ├── metrics.py          # Phase 3
│   └── export.py           # tables and figures for the report
├── data/
│   ├── raw/
│   ├── processed/
│   └── outputs/
├── app.py                  # Phase 4 — Streamlit
├── report/
│   ├── main.tex
│   └── figures/
└── logs/

---

Feasibility and Checkpoints

This project is deliberately demanding, but it is scoped to be finishable. The failure mode is not difficulty — it is leaving the routing step until the last day.

Suggested schedule

Day	Checkpoint
1	Repository created, sources downloaded, RENIPRESS and populated centres loaded and mapped
2	Validation rules implemented, data quality report produced
3	Routing engine running, matrix computed for one department
4	Full matrix for all three departments, cached to disk
5	Metrics computed and exported
6	Streamlit dashboard working end to end
7	LaTeX report drafted, figures exported
8	Video recorded, repository cleaned, README finished

Risk controls

• Start the routing build on Day 1, even before the data is clean. Building the OSRM graph from the Peru extract takes time and disk space, and discovering that on Day 6 is fatal.
• Cache everything. If your pipeline recomputes routes on every run, you will lose hours.
• Commit the matrix. Your dashboard demo must work on the day of the presentation, regardless of whether a routing service is up.
• One department first. Get the entire pipeline working end to end on the smallest department before scaling to three. A complete pipeline over one department beats three half-finished ones.
• If a data source is unreachable, document it, use a cached or alternative source, and explain the substitution in the report. This is a legitimate finding about the state of Peruvian open data, not a failure.

---

Evaluation Criteria

Phase	Criterion	Points
1	Data acquisition, validation rules, and quality report	3.0
2	Routing implementation, caching, matrix, and snapping analysis	3.0
3	Metric construction, population weighting, and cross-analysis	2.0
4	Streamlit dashboard, including scenario simulator	2.5
5	LaTeX report, with limitations section	1.5
—	Technical presentation (video)	8.0
—	Innovation	+extra
	Total	20.0

Repository and code quality

Code organization, documentation, absence of hardcoded values, and reproducibility are assessed within each phase's score rather than separately. A phase that produces the right answer through an unreadable, unreproducible script will not receive full marks for that phase.

---

Innovation

Innovation is evaluated as an additional bonus and is not part of the 20 base points. It must represent a meaningful improvement beyond the minimum requirements.

Examples that would qualify:

• Two-Step Floating Catchment Area (2SFCA) analysis, modelling facility capacity against demand rather than treating every facility as infinitely available.
• Facility siting optimization — solving a maximal-covering location problem to answer "where should the next resolutive facility go?" rather than only "where are the gaps?".
• Uncertainty quantification — bootstrapping the coverage estimate over the coordinate error rate found in Phase 1, and reporting a confidence band rather than a point estimate.
• National-scale run with a documented strategy for handling the computational load.
• Isochrone rendering — reachability polygons around facilities rather than point-to-point times.
• Temporal comparison — using an older RENIPRESS release to show how coverage changed over time.
• Automated report generation — a pipeline step that recompiles the LaTeX PDF with fresh numbers whenever the data changes.