Add EIC-first deterministic matching before Duke fuzzy matching

[MaykThewessen]

Summary

Implements the architecture proposed in #287: deterministic matching on EIC (Energy Identification Code) runs before Duke fuzzy matching in compare_two_datasets(). Plants sharing an EIC code are matched with certainty and removed from the Duke input, so the fuzzy matcher only handles the residual.

Before:
  All sources ──→ Duke fuzzy match ──→ reduce

After:
  All sources ──→ Deterministic EIC join ──→ matched set 1 (high confidence)
                  │
                  └→ EIC-unmatched residual ──→ Duke fuzzy match ──→ matched set 2

                  matched set 1 + matched set 2 ──→ reduce

Motivation

EIC codes are unique European plant identifiers already loaded from ENTSOE, OPSD, and GEM — but previously unused in the matching decision. This change uses them as a first-pass exact match, providing a robustness guarantee against co-located plant confusion.

Example: Eemshaven harbour, Netherlands

Source	Plant	Fuel	Capacity	EIC
OPSD	Eemscentrale Ec	Natural Gas	1929 MW	6 shared codes
ENTSOE	Eems	Natural Gas	1931 MW	same 6 codes
ENTSOE	Eemshaven	Hard Coal	1580 MW	49W000000000066Q
ENTSOE	Eemshaven	Natural Gas (Magnum)	1410 MW	49W000000000119V

EIC matching deterministically pairs the gas plants via their shared codes, preventing any possibility of Duke merging them with the nearby coal plant based on name/geo similarity (~0.86 JaroWinkler, ~400m apart).

Example: Borssele, Netherlands

Borssele nuclear (OPSD: 492 MW, ENTSOE: 485 MW) is locked to its correct cross-source pair via EIC 49W000000000054X, independent of fuzzy name matching against nearby Borssele wind/coal/solar entries.

Integration test results

• 431 deterministic EIC matches between OPSD and ENTSOE (28% of ENTSOE resolved without fuzzy matching)
• Reduces Duke's workload for those pairs to zero
• Gracefully falls back to Duke-only when EIC data is unavailable (GEM, GEO, GPD have no EIC codes)

Implementation

• New _match_by_eic() function in matching.py — builds {eic_code → row_index} dicts, finds shared codes via set intersection, greedy 1-to-1 pairing
• Modified compare_two_datasets() — calls EIC matching first, drops matched rows, then Duke on residual
• 7 unit tests covering: basic matching, missing EIC columns, empty sets, NaN-in-set filtering, 1-to-1 enforcement, non-set values

Test plan

• pytest test/test_matching.py — 7 tests pass
• Integration test with real OPSD + ENTSOE data — 431 matches, correct plant pairings verified
• Full pipeline run with powerplants(update=True) to verify end-to-end output

Closes #287

🤖 Generated with Claude Code