Geospatial history extraction and review¶

Module release: 13 November 2026. This opt-in module finds location candidates in records, preserves their provenance, and creates a geocoding queue only after explicit human review. It does not establish residence, geocode addresses, create a map or estimate exposure.

The existing pipeline and public dashboards are unchanged. run_all.py does not run this module. The new extractor has focused synthetic tests; the broader Registry Forge workflows have not been revalidated on a new clinical cohort by this update.

Run the optional module¶

First use the invented example from the downloaded package:

python pipeline/geospatial_extraction.py extract \
  --bundle templates/synthetic_geospatial_bundle.json \
  --out-dir practice_run/restricted/geospatial

For authorized real records, substitute the existing dashboard_data.json from an approved Registry Forge run. The module reads notes[].narrative_text and documents[].plain_text using the same reader as note extraction. C-CDA sections are not searched again through the parent document. It writes geospatial_candidates.json and .csv, always marked restricted.

Make a protected working copy for review. Read the full source record, confirm the subject and purpose of the location, and edit only the review fields. Then regenerate the candidates from the same current input while validating the review:

python pipeline/geospatial_extraction.py queue \
  --bundle templates/synthetic_geospatial_bundle.json \
  --review practice_run/restricted/geospatial/reviewed_candidates.json \
  --out-dir practice_run/restricted/approved_geospatial

The result is geocoding_queue.json and .csv, not a completed geographic data set. No network connection or geocoder is used. A nonzero exit means validation failed; do not use older outputs left by a previous successful run as though they were current. Retain the original candidates, reviewed file and resulting queue in the approved audit record.

What is extracted¶

The seed rule recognizes conservative US-style numbered street addresses, including a limited set of street suffixes and optional city/state/ZIP text. It will miss many real locations, including rural routes, most town-only histories, informal place descriptions and international formats. A match does not establish that the address exists or is in the United States. False positives are possible. Measure performance on locally reviewed records before use.

Each candidate retains a stable content-derived ID, registry patient ID, source identifier, source date, source-content SHA-256, exact matched text and character offsets. Context hints flag a possible patient, relative, facility or ambiguous subject; home, work, school or care context; negation; uncertainty; and historical/current/transition wording. These are sorting aids, not clinical facts. A facility address in a letterhead and a relative's home must not silently become the patient's residence.

Source-document date and a date expression near an address are separate from residence start/end. Neither automatically populates an interval. Unknown dates remain unknown. A move destination is not assumed to remain current indefinitely. Repeated mentions remain separate when their provenance differs; a reviewer can reconcile them without deleting the original evidence.

Explicit review contract¶

Field	Required decision
`review_status`	Exactly `needs_review`, `rejected` or `approved_patient_place`; other values fail validation
`reviewed_subject` and `source_verified`	`patient` and `yes` for a queued place, with a nonempty registry ID
`reviewed_place_type`	Residence, work, school, care, community or other, using the documented lowercase values
`reviewed_location` and `reviewed_country`	Human-verified location string and `US`; this release's queue is limited to US places
`context_resolved` and `review_reason`	`yes` plus the basis for resolving subject, negation, uncertainty, facility and temporal context
`reviewer_id` and `reviewed_at`	Authorized reviewer and ISO timestamp including timezone, such as `2026-11-13T14:00:00-05:00`
`start_date`, `end_date` and precision	Optional `YYYY`, `YYYY-MM` or `YYYY-MM-DD` paired with year/month/day precision; absent dates require `unknown`
Coordinates	Optional previously reviewed latitude/longitude pair with source and precision; never generated by this module

Do not alter the immutable source fields. The queue step rejects changed snapshots, stale source hashes, unknown candidate IDs, duplicate review rows, invalid statuses, reversed intervals and invalid coordinates. A source correction requires fresh extraction and review. Human approval remains an attestation, not independent proof that the reviewer is correct; use institutional reviewer access controls and quality assurance.

Optional structured FHIR addresses¶

The current core patient master does not retain Patient.address. This optional direct path reads one original FHIR Patient or a Bundle containing exactly one Patient, after the institution verifies its mapping to a registry ID:

python pipeline/geospatial_extraction.py extract \
  --fhir-bundle approved_input/patient_bundle.json \
  --patient-id REGISTRY_ID \
  --out-dir approved_run/restricted/geospatial

Use the same arguments again with queue and --review. Multiple Patient resources are rejected because the module cannot resolve their identity mapping. Address use/type/text and recorded periods are preserved in context, with an exact JSON pointer. A recorded contact or billing address is not assumed to be a residence; meta.lastUpdated is a source-record timestamp, not a move date. No patient demographic fields are added to public dashboards.

Restricted handling and later GIS work¶

All outputs can identify people. The destination must contain a restricted directory and cannot be inside docs, assets, public, site, dist, www or reports. Symlink destinations are refused. The module requests directory mode 0700 and file mode 0600; these do not replace institutional access controls, encryption, platform-specific permissions or a security review. CSV formula-like text is escaped; JSON retains exact source values. Do not upload outputs to a repository or serve them through this site.

Only an approved downstream service may geocode the vetted queue. Record provider/version, processing date, match precision, corrections and any coordinate uncertainty. Do not assign a rooftop point to a ZIP-only location, substitute modern environmental measurements for unsupported historical periods, or interpret proximity as personal dose. Care locations and workplaces remain distinguishable from residences. Review geographic outputs for disclosure risk before any sharing.

Focused validation¶

python -m unittest discover -s tests -p test_geospatial.py -v

Tests cover provenance, source dates, facility and relative addresses, negation, uncertain dates, moves, empty text, structured FHIR, changed-source approvals, malicious statuses, coordinate validation, CSV handling and restricted destinations. These are software checks with fictional records, not estimates of clinical extraction accuracy.