COVID-19 Regional Analytics — from administrative-region population to hotspot graphs

Workshop goal

By the time you finish this Workshop, you will have walked through one full cycle of the following flow inside D.Hub.

• Load a single scenario into portal so that one collection, 9 datasets (5 input + 4 intermediate), 4 code nodes, 4 pipelines, an ontology with 6 entities and 6 relations, and one agent are all registered together.
• Combine floating population and registered resident population across 3 administrative-region tiers (sido / sigungu / dong) using composite-key joins.
• Align the three infection signals — patient location, screening clinics, contact hotspots — at the dong level so a single neighborhood's patient cluster + available clinics fit on one screen.
• Expand the 5-hop patient → hotspot → dong → sigungu → sido path on the 6-entity, 6-relation regional ontology graph.
• (Optional) Run a natural-language query through the epidemic_assistant agent — patient clusters + hotspot distribution within a sigungu.

This is the integrated regional analysis scenario in the public-health domain. The spatial join pattern — aligning patient / clinic / hotspot data against the administrative-region hierarchy — is the core lesson. Recommended duration: 90 minutes.

Prerequisites

• An analyst or engineer account with access to D.Hub portal (Editor or higher)
• ~70 KB of download room for one scenario zip

1. Load the scenario (10 min)

Go to Collections → more (⋯) menu → Import (가져오기) and upload the zip.

Following manifest.json, the import creates the following in order:

1. One collection — covid19 (alias: COVID-19 Regional Analytics)
2. 9 datasets — Inputs 5 (floating_population, residents_population, region_dong_info, patient, clinics, hotspot_result), intermediates 3 (region_dong, sido_filter, sigungu_filter)
3. 4 codes (Python) — join_populations, sido_filter, sigungu_filter, build_covid_ontology
4. 4 pipelines — join_population, sido_filter, sigungu_filter, ontology_materialization
5. Ontology — 6 entities (patient, clinic, hotspot, sido, sigungu, dong), 6 relations
6. One agent — epidemic_assistant

2. Browse the population data (12 min)

The starting point is administrative-region × population across two sources.

floating_population — Weekly floating population per dong. Columns: sido_name, sigungu_name, dong_name, week_start_date, floating_count (weekly average floating count).

residents_population — Registered residential population per dong. Columns: sido_name, sigungu_name, dong_name, register_year, male_count, female_count, total_residents.

In each dataset's Schema tab, confirm the composite key (sido_name, sigungu_name, dong_name) is the same type (string) on both sides and that region names use consistent representation (e.g. Sejong Special Self-Governing City vs Sejong City). The §3 join depends on this composite key.

region_dong_info — Regional metadata. Per-dong area / coordinates / commercial-district info. Used downstream as an administrative-hierarchy lookup.

3. Population integration + administrative-hierarchy lookups (15 min)

In the covid19 collection's Pipelines section, run the three pipelines in order.

join_population — One node: join_populations outer-joins the two population sources on the composite key (sido_name, sigungu_name, dong_name) → region_dong. One row carries both floating and resident populations; rows present in only one source carry null on the other side.

sido_filter — Extracts unique sido names from region_dong → sido_filter. Columns: sido_id (= sido_name), sido_name.

sigungu_filter — Keeps unique sido + sigungu combinations from region_dong → sigungu_filter. Columns: sigungu_id ("sido|sigungu" format), sido_name, sigungu_name.

Press Run on each in sequence. When done, confirm that region_dong's row count equals the union of dongs across the two sources, and that sido_filter is 17 rows or fewer (the count of sido in Korea).

4. Patients · clinics · hotspots (10 min)

patient — Patient records. Columns: patient_id, age_group, gender, sido_name, sigungu_name, dong_name, infection_date. Location is normalized to the dong of residence (not a precise street address).

clinics — Screening clinics. Columns: clinic_id, clinic_name, clinic_type (screening / respiratory_dedicated), sample_available (boolean), address, latitude, longitude, sido_name, sigungu_name, dong_name.

hotspot_result — Contact-tracing hotspots. One row = one pair of patients who shared the same dong during overlapping time windows. Columns: hotspot_id, patient_a_id, patient_b_id, dong_name, cross_start_time, cross_end_time, location_description.

The three inputs all share the dong spatial unit. The next-step ontology connects all three to the same dong node via patient → dong, clinic → dong, hotspot → dong relations.

5. Regional ontology + graph exploration (15 min)

Run ontology_materialization. build_covid_ontology reads 5 inputs + 3 intermediates in batch mode and lands the 6 entities + 6 relations in upsert mode.

Relations × 6:

• belongs_to_sido (sigungu → sido) — Up the administrative hierarchy
• belongs_to (dong → sigungu) — Down the administrative hierarchy
• resides_in (patient → dong)
• located_in (clinic → dong)
• within (hotspot → dong)
• involved_in (patient → hotspot)

In the Graph explorer, surface a 5-hop location context for one patient.

MATCH (p:patient)-[:involved_in]->(h:hotspot)-[:within]->(d:dong)
       -[:belongs_to]->(sg:sigungu)-[:belongs_to_sido]->(s:sido)
RETURN p, h, d, sg, s
LIMIT 25

A single patient's location context — individual → hotspot → dong → sigungu → sido — appears on one screen. When a patient is linked to multiple hotspots or a dong carries a cluster of patients + a clinic, those visual patterns fall out immediately.

Next, surface the contact network within one dong.

MATCH (d:dong {dong_name: 'Myeong-dong'})<-[:within]-(h:hotspot)<-[:involved_in]-(p:patient)
RETURN d, h, p
LIMIT 50

The who-met-whom across time windows within one dong network spreads on one graph. Double-clicking nodes to expand neighboring hotspots extends the inferred transmission paths.

6. Per-dong analysis — patients × clinics × density (15 min)

This step is the operational angle for one dong. From the graph explorer, pick a dong with a visible patient cluster (the seed Yeoksam 1-dong, Gangnam-gu, Seoul is a good candidate). Collect four numbers on one screen.

1. total_residents and floating_count of that dong — From region_dong's preview filtered to one row. Floating ≫ resident indicates commuter-heavy business district.
2. Patient count for that dong — From patient preview filtered on dong_name. Roughly 2–8 on the seed.
3. Clinics within that dong — From clinics preview filtered on dong_name + sample_available = true. Roughly 0–3.
4. Hotspots within that dong — From hotspot_result preview filtered on dong_name. One hotspot pairs two patients.

These four numbers directly surface operational signals like clinic-deficient dong (5 patients + 0 clinics). The seed data intentionally embeds clinic distribution imbalance — some sigungu are clinic-starved relative to their patient counts.

7. Next steps and a retrospective (5 min)

By this point you've walked through five flows on a single public-health scenario:

• Two population sources composited via an outer join
• Administrative-hierarchy 3-tier lookup extraction
• Patient / clinic / hotspot triple-signal dong-level alignment
• 6-entity graph's 5-hop patient location context
• A single dong's 4-number operational summary

Pick the most appealing direction:

• Call the epidemic_assistant agent with a natural-language query like "What's the patient count and clinic distribution for Yeoksam 1-dong in Gangnam-gu?". The agent generates the dong-level graph query automatically.
• The Engineer Path Pipeline scheduling lesson — assume patient and hotspot data land hourly and register ontology_materialization accordingly.
• Map your own domain's hierarchy + location data (school districts, store catchments, infrastructure assets) to the same shape.

Verification checklist

• The covid19 collection holds 5 inputs + 3 intermediates.
• After join_population, one row of region_dong carries both floating and resident measures.
• After sido_filter, the row count is at or below the number of sido in Korea (≤ 17 on the seed).
• In the Graph explorer, starting from one patient you can expand the 5-hop path patient → hotspot → dong → sigungu → sido.
• You can collect the patient × clinic × hotspot × density 4-number summary for one dong on one screen (the §6 core result).