Spatial expectation + density — the same engine, two zoom levels
There is one instinct hiding at two different scales in this system, and it is worth naming before you run into it twice and think you're looking at two different things.
The instinct is: modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' what you'd expect, then treat the deviation as signal.
At the value level, the question is: "how surprised am I that these two records agree?" At the regional level, the question is: "how surprised am I that there is — or isn't — a facility here?" The math is different, the zoom level is different, but the engine is the same. And that's not a coincidence you should let pass without noting, because understanding the connection tells you what we're building toward and why the geocoder's population-ranking isn't a separate concern from the coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. product.
Scale one: value-level distinctiveness
The Fellegi-Sunter modelFellegi-SunterA probabilistic record linkage model that computes match probability from agreement-level log-likelihood ratios: log₂(m/u) where m is the probability of agreement given a true match and u is the probability of agreement by chance. Mailwoman learns m and u label-free via expectation-maximization. underlying the matcher assigns each field agreement a weightparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values.: log₂(m / u), where m is how often a true match agrees on that field and u is how often a non-match agrees by coincidence. The u term is the one to fix your eye on. For any given field, u is roughly how common that value is.
Two records that agree on the value "Smith" are barely evidence of anything. Agreement on "Smith" happens all the time among non-matches, because "Smith" is everywhere. Two records that agree on "Vijayan" are strong evidence — that agreement is unlikely to be coincidental. The math is the same in both cases; what differs is the value's frequency.
This is the Winkler extension to Fellegi-SunterFellegi-SunterA probabilistic record linkage model that computes match probability from agreement-level log-likelihood ratios: log₂(m/u) where m is the probability of agreement given a true match and u is the probability of agreement by chance. Mailwoman learns m and u label-free via expectation-maximization.: replace the level's average u with the agreeing value's actual frequency, and you get a per-value adjustment that makes rare agreements count more and common ones count less (Winkler, 1988; "Frequency-based matching in the Fellegi-Sunter modelFellegi-SunterA probabilistic record linkage model that computes match probability from agreement-level log-likelihood ratios: log₂(m/u) where m is the probability of agreement given a true match and u is the probability of agreement by chance. Mailwoman learns m and u label-free via expectation-maximization.," Journal of Applied Statistics 49:11, 2022). The implementation in match/tf.ts (withTermFrequency) does exactly this — it computes the adjustment on-the-fly from the input column itself, so there's no external lookup or pre-trained prior required:
// match/tf.ts
// The agreeing value's own frequency replaces the level's average u.
// log2(u_level / frequency(v)) → large positive for rare values, negative for common ones.
const frequency = Math.max(tf.frequency(value), tf.minimumFrequency ?? 1e-4)
w += Math.log2(level.u / frequency) * (tf.weight ?? 1)
The pattern is inverse-frequency weighting — the same math as TF-IDF. A clinic building shared by fifty providers has a near-zero address weightparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values.: "123 Medical Center Drive" is effectively a common value in this dataset, so agreement on it is barely evidence that two records are the same entity. A sole practitioner's home-office address is rare; agreement on it is strong evidence. The matcher already has this mechanism (withTermFrequency over the address comparison), and the term-frequency table is built from the dataset itself at match time.
Scale two: regional expected density
Zoom out from a pair of records to a regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality., and the question changes from "should these agree?" to "how many facilities of this type should be here, given the population?"
This question has a long quantitative history.
Central Place Theory (Christaller, 1933) formalized the observation that service centers arrange themselves in a hierarchy: small settlements offer basic services, larger ones add specialized ones, and you need a minimum population — a "threshold" — to support each tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous.. Healthcare facilities follow this pattern. Primary care is a low-order service (it should be dispersed, close to where people are); specialized surgery is a high-order service (it concentrates in fewer, larger centers). A rural county with 4,000 residents that has no primary care practice is a deviation from the expected hierarchy. That same county having no neurosurgery center is not. (Christaller, 1933; Openshaw and Veneris, 2003 on medical facility hierarchies.)
Gravity and spatial interaction modelsneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' (Wilson, 1970s) quantified how population generates demand for facilities: locations with greater services and greater population pull harder, in proportion. The basic gravity formulation is Iᵢⱼ ∝ Pᵢ × Sⱼ / dᵢⱼ², where Pᵢ is the population at demand point i, Sⱼ is supply at facility j, and d is distance.
Two-step floating catchment areatwo-step floating catchment area (2SFCA). A spatial-accessibility metric that measures provider supply against population demand within a distance threshold, with distance decay (the E2SFCA variant). Appears in Mailwoman's spatial-demand analysis of geocoded points. (2SFCAtwo-step floating catchment area (2SFCA). A spatial-accessibility metric that measures provider supply against population demand within a distance threshold, with distance decay (the E2SFCA variant). Appears in Mailwoman's spatial-demand analysis of geocoded points.) turns that gravity intuition into a measurable accessibility index (Radke & Mu, 2000; widely cited):
- For each facility location, calculate the supply-demand ratio within a threshold travel distance: how many providers per thousand residents in the catchment?
- For each residential area, sum the supply-demand ratios of all facilities within its threshold travel distance.
The result is an accessibility score per location — a local estimate of "provider supply per unitunitA subdivision of a building — apartment, suite, floor — that refines a street address. Mailwoman's unit component; a designator plus identifier forms a subpremise. of population demand." The enhanced version (E2SFCA) adds a distance-decay function so closer facilities count more than distant ones. Both variants quantify the gap between what the population generates as demand and what the supply side delivers.
HRSA's HPSAHPSA (Health Professional Shortage Area). A US federal designation identifying areas short of health providers relative to population and need, scored 0–25. An example downstream use of geocoded address data. and MUAMUA (Medically Underserved Area). A US federal designation for inadequate primary-care access, scored using the Index of Medical Underservice. Another downstream consumer of accurate geocoding. designations are the federal government's operationalization of this exact idea, and they matter to our work directly because the datasets we're correlating (NPPES providers, FCC Rural Health Care filings) are themselves organized around HRSA-designated areas.
A Health Professional Shortage Area (HPSAHPSA (Health Professional Shortage Area). A US federal designation identifying areas short of health providers relative to population and need, scored 0–25. An example downstream use of geocoded address data.) designation for primary care requires a population-to-provider ratio of at least 3,500:1 (or 3,000:1 in areas with documented high need). That ratio is an expected-vs-observed modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.': the threshold encodes what a population should minimally be able to support in provider density. HRSA then scores the severity of the shortage on a 0–25 scale for primary care and mental health (0–26 for dental), weighted by:
- Population-to-FTE provider ratio (largest weightparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values., ~28.7 points at max): the core supply-demand gap
- Percentage of population at or below 100% of the federal poverty level (~25.1 points at max): an equity adjustment
- Travel distance / time to the nearest accessible care outside the HPSAHPSA (Health Professional Shortage Area). A US federal designation identifying areas short of health providers relative to population and need, scored 0–25. An example downstream use of geocoded address data. (~20.2 points at max): a spatial isolation correction
- Percentage of population age 65 and over: a needs-intensity adjustment
A Medically Underserved Area (MUAMUA (Medically Underserved Area). A US federal designation for inadequate primary-care access, scored using the Index of Medical Underservice. Another downstream consumer of accurate geocoding.) designation uses a composite Index of Medical Underservice (IMUIMU (Index of Medical Underservice). The composite score — provider-to-population ratio, poverty rate, infant mortality, and elderly-population share — behind the Medically Underserved Area designation.) that combines the provider-to-population ratio, the poverty rate, the infant mortality rate, and the elderly population percentage into a single score. An IMUIMU (Index of Medical Underservice). The composite score — provider-to-population ratio, poverty rate, infant mortality, and elderly-population share — behind the Medically Underserved Area designation. of 62.0 or below qualifies for designation. (HRSA Bureau of Health Workforce, "Scoring Shortage Designations," 2024; Healthcare shortage area, Wikipedia.)
The IMUIMU (Index of Medical Underservice). The composite score — provider-to-population ratio, poverty rate, infant mortality, and elderly-population share — behind the Medically Underserved Area designation. and HPSAHPSA (Health Professional Shortage Area). A US federal designation identifying areas short of health providers relative to population and need, scored 0–25. An example downstream use of geocoded address data. score are, in the terminology of this system, expected-density modelsneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' with equity weighting. They estimate where facilities "should" be given population and need, measure the shortfall, and quantify the severity. The HRSA designation appears in the FCC Rural Health Care program — providers apply for funding under RHC specifically on the basis of being in or serving HPSAHPSA (Health Professional Shortage Area). A US federal designation identifying areas short of health providers relative to population and need, scored 0–25. An example downstream use of geocoded address data./MUAMUA (Medically Underserved Area). A US federal designation for inadequate primary-care access, scored using the Index of Medical Underservice. Another downstream consumer of accurate geocoding. areas. So the designation is itself a column in the data we're correlating, not only background.
How they connect — and why the geocoder already knew
This is the part worth reading carefully.
The geocoder's resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. already implements a "where is something likely to be given the population?" prior. When two candidate localities have the same name and the parser can't resolve the ambiguity, the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. ranks by population (primary) and centroid distance (tiebreak):
// core/resolver/resolve.ts
const ranked = [...candidates].sort((a, b) => b.population - a.population || a.distanceKm - b.distanceKm)
The coarse-placercoarse-placerA lightweight int8 country classifier (~0.79 MB) that predicts which of a set of target countries an address belongs to, feeding a soft prior into resolver disambiguation. (#244) extends this to the countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. level: a tiny linear classifier infers the probable countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. from the address text and injects that as a soft anchorPosterior into the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon.'s re-ranking (core/coarse-placer/coarse-placer.ts, core/pipeline/runtime-pipeline.ts). Population data lives in place_population (built from WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. wof:population / gn:population during scripts/build-unified-wof.ts). The resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon.'s populationBoost: 4.0 is a calibrated prior that says: the more people live there, the more likely an address is actually there.
That is already a spatial expectation modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.'. It is already live.
What changes at the matcher scale is that "spatial expectation" operates not on individual place candidates but on facility counts across a regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.. Instead of "which Berlin is the right one?" you're asking "how many primary care practices should serve a county with 40,000 residents and a median income below the federal poverty level?" The data is coarser; the question is about a distribution, not a point.
The connection between the two scales is that both are the same Bayesian move applied at different granularities:
- The resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. asks: given a population, which candidate is the most probable referent of this address?
- The coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. analysis asks: given a population and its demographics, what is the expected number of facilities of this type, and how far does the observed count deviate from it?
Population is already in the system. The admin hierarchy is already in the system. Census data is available at $MAILWOMAN_DATA_ROOT/census/ (including the 2024 ZIP Code Tabulation Area gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. at 2024_Gaz_zcta_national.txt). The spatial machinery needed to answer "how surprised should I be that there are no providers here?" is substantially the same machinery that already answers "how surprised should I be that these two records agree?"
Where this lands in the open work
#621 — coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. reconciliation (eligibility ↔ enrollment anti-join) is where the regional expected-density modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' becomes a concrete deliverable. The anti-join — "eligible, not enrolled" — surfaces every provider or facility that should appear in the FCC RHC enrollment data but doesn't. That is already a deviation from expectation. The density modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' adds a second, coarser layerlayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6.: not just "which individual entity is missing?" but "which geographic areas have fewer enrolled providers than their population would predict?" The HRSA HPSAHPSA (Health Professional Shortage Area). A US federal designation identifying areas short of health providers relative to population and need, scored 0–25. An example downstream use of geocoded address data./MUAMUA (Medically Underserved Area). A US federal designation for inadequate primary-care access, scored using the Index of Medical Underservice. Another downstream consumer of accurate geocoding. designations are exactly this precomputed — a column in the data (the FCC forms explicitly reference HPSAHPSA (Health Professional Shortage Area). A US federal designation identifying areas short of health providers relative to population and need, scored 0–25. An example downstream use of geocoded address data. status). Using them means we don't have to recompute the expected density ourselves; we inherit it from the federal designation system.
#618 — multi-source cross-dataset correlation is where inverse-address-frequency weighting does its heaviest work. The NPPES registry alone has 4.8 GB of provider records, many at shared institutional addresses (hospitals, clinics, care systemsexpectation-maximizationAn iterative algorithm that estimates model parameters when some variables are unobserved. In Mailwoman's matcher, EM learns the Fellegi-Sunter m and u parameters from unlabeled data — no training labels needed.). A shared address among many records is a high-frequency value and should contribute near-zero evidence to a match decision. The withTermFrequency mechanism in match/tf.ts and match/fellegi-sunter.ts handles this automatically — the term-frequency table is built from the dataset at match time, so a shared-building address automatically gets its weightparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values. suppressed without any hand-tuning.
#602 / #603 — config auto-tuning and selective modelsneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' are where a regionally-aware density weightparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values. might eventually live. A population-weighted distance threshold — the "50 m same-building" bucket that's right downtown but too tight in a rural county — is one concrete lever. The geocoder already knows the density context (WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. hierarchy + population data); the matcher can condition its distance comparisons on that context. This is a tunable config surface, not a new modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.': it's the kind of adjustment that AutoER's sampling-based tuner (AutoER, IEEE Access 2025, ~100 trials to recover >95% of exhaustive search) can find automatically once the surface is exposed.
#615 — real-data validation (epic) is the gate the density modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' must pass through. The NPPES NPI dedup benchmark gives us a measurable ground truthground truthThe correct answer for an example, used as the standard a prediction is graded against. Mailwoman's ground truth is the hand-labeled golden set; its quality caps achievable accuracy.; the coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. reconciliation (#621) gives us the product output. The density expectation modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' is most useful after the basic matcher is graded — it is a signal to layerlayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. on top of a working resolution pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-gate → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package., not a prerequisite for it.
What to build, and in what order
The density modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' is not on the critical path. The critical path is: get the classical Fellegi-SunterFellegi-SunterA probabilistic record linkage model that computes match probability from agreement-level log-likelihood ratios: log₂(m/u) where m is the probability of agreement given a true match and u is the probability of agreement by chance. Mailwoman learns m and u label-free via expectation-maximization. core working, grade it on the NPI benchmark (#615), and produce the eligibility ↔ enrollment anti-join (#621). Those are the deliverables.
Two specific piecesECE (Expected Calibration Error). A metric that measures how well a model's confidence scores align with its actual accuracy. Lower is better. Mailwoman's held-out ECE drops from 0.067 (raw) to 0.0035 (calibrated). are worth building early because they're essential to the anti-join's interpretability, not just analytical color:
-
Attach HRSA HPSAHPSA (Health Professional Shortage Area). A US federal designation identifying areas short of health providers relative to population and need, scored 0–25. An example downstream use of geocoded address data./MUAMUA (Medically Underserved Area). A US federal designation for inadequate primary-care access, scored using the Index of Medical Underservice. Another downstream consumer of accurate geocoding. designation to each resolved entity. The FCC RHC forms already reference whether the HCP is in a designated shortage area. Cross-referencing the resolved entity cluster against the HRSA designation data (available via
data.hrsa.gov) gives the anti-join output a "designated shortage area" column — a standard federal signal the data consumer can use to prioritize. This is a join, not a modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.'. -
Surface address frequency in the match score attribution. The per-pair contribution breakdown in
match/fellegi-sunter.ts(PairScore.contributions) already attributes every match-weightparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values. to a field. When the term-frequency adjustment suppresses an address match because the building is shared, that suppression should be visible in the output:address: weight=0.2 (shared-building penalty). This is reporting infrastructure, not new math — thecontributionsarray is already there.
The 2SFCAtwo-step floating catchment area (2SFCA). A spatial-accessibility metric that measures provider supply against population demand within a distance threshold, with distance decay (the E2SFCA variant). Appears in Mailwoman's spatial-demand analysis of geocoded points. accessibility index and a full Central Place Theory-based expected-facility modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' are downstream: useful for characterizing coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. gaps once the entity resolutionrecord matchingThe process of determining whether two database records refer to the same real-world entity. Mailwoman's matcher uses a geocode-first approach (match the resolved place, not the address string) with Fellegi-Sunter probabilistic scoring. is working, but not needed to ship the anti-join.
The line between what we measure and what it means
Every number this system produces — the accessibility index, the anti-join membership, the deviation from expected facility density — is a measurement. What a coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. gap means, what causes it, or what should be done about it is the data consumer's domain, not ours. We surface candidate links and reconciled entity sets; the analyst decides what the deviation implies.
That line reflects the correct division of labor for a system that resolves fragmented public data into an analyzable shape. The coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. product (#621) is worth building precisely because it makes that analysis tractable — not because it answers the question for the analyst, but because it asks the question precisely.
The spatial expectation modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.', at both scales, is how we keep that line exact: given what we know about the population and the data sources, here is what we'd expect to see, and here is how much the observed data departs from it. Interpreting that departure is the analyst's job, not ours.
See also
- Geocode-first record matching — the full matcher strategy, including the Fellegi-SunterFellegi-SunterA probabilistic record linkage model that computes match probability from agreement-level log-likelihood ratios: log₂(m/u) where m is the probability of agreement given a true match and u is the probability of agreement by chance. Mailwoman learns m and u label-free via expectation-maximization. core and the geocode-firstgeocode-firstThe matcher's core design principle: resolve addresses to geographic coordinates first, then compare the resolved places — not the raw address strings. Two records at the same coordinates match even if one says '123 Main St' and the other says '123 MAIN STREET.' blockingblockingThe first stage of entity resolution: generate candidate record pairs using cheap, high-recall keys (geo cell, canonical address, phone) instead of comparing every record to every other (O(n²)). The matcher only scores pairs that survive blocking. bet
- Importance vs population — the two signals the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. uses, and why population dominates the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous.
- Confidence calibration — how "calibrated" becomes a precise claim about probabilities rather than a general reassurance