One-step IDW interpolation from source points to census tracts

General-purpose wrapper that combines travel-time computation (optional), alpha optimization, and interpolation into a single call. Accepts R objects (sf data frames) directly. If no travel time matrix is provided, OSM road network data is automatically downloaded and travel times are computed via r5r.

Usage

interpolate_election(
  tracts_sf,
  electoral_sf,
  calib_tracts,
  calib_sources,
  interp_sources = NULL,
  tract_id = "id",
  point_id = "id",
  time_matrix = NULL,
  weights = NULL,
  optim = optim_control(),
  routing = routing_control(),
  min_tract_pop = 1,
  offset = 1,
  keep = NULL,
  verbose = TRUE,
  ...
)

Arguments

tracts_sf

An sf polygon object. Target census tracts.

electoral_sf

An sf point object. Source points (e.g., voting locations).

calib_tracts

Character vector. Column names in tracts_sf to use as the calibration population matrix. Must match calib_sources in length.

calib_sources

Character vector. Column names in electoral_sf to use as the source calibration matrix. Must match calib_tracts in length.

interp_sources

Character vector or NULL. Column names in electoral_sf to interpolate. Default NULL means all numeric columns not in calib_sources.

tract_id

Character. Name of the ID column in tracts_sf. Default: "id".

point_id

Character. Name of the ID column in electoral_sf. Default: "id".

time_matrix

Numeric matrix [n x m] or NULL. Pre-computed travel times. If provided, skips all travel time computation.

weights

Numeric matrix or NULL. Pre-computed weight matrix [n x m]. When provided, optimization is skipped and these weights are used directly. Useful for reinterpolate() fast path.

optim

An optim_control() object with optimization parameters. Default: optim_control().

routing

A routing_control() object with routing parameters. Default: routing_control().

min_tract_pop

Numeric. Minimum total population in calib_tracts for a census tract to be included. Default: 1.

offset

Numeric. Travel time offset (power kernel only; ignored when kernel = "exponential" in optim). Default: 1.

keep

Character vector or NULL. Names of extra intermediate objects to include in the result. weights, time_matrix, electoral_sf, and rep_points are always kept. Options: "pop_raster", "osm_roads".

verbose

Logical. Print progress. Default: TRUE.

...

Advanced arguments. network_path (character) for pre-downloaded OSM data, elevation_path (character) for elevation GeoTIFF.

Value

A list of class "interpElections_result" with components:

interpolated

Numeric matrix [n x p]. Interpolated values.

alpha

Decay parameters used.

tracts_sf

sf object with interpolated columns joined.

sources

Data frame (no geometry) of source point data.

optimization

interpElections_optim object.

offset

Numeric. Offset value used.

call

The matched call.

tract_id, point_id

ID column names.

interp_cols

Character vector. Interpolated column names.

calib_cols

List with $tracts and $sources.

weights

Weight matrix. Always kept.

time_matrix

Travel time matrix. Always kept.

electoral_sf

sf point object. Always kept.

rep_points

Representative points sf object. Always kept.

kernel

Character. Kernel type used ("power" or "stretched_exp").

row_targets

Numeric vector. Row target proportions for Sinkhorn.

pop_raster

Population raster or NULL (opt-in via keep).

osm_roads

OSM road network sf object or NULL (opt-in via keep).

Details

For Brazilian elections, use interpolate_election_br() which auto-downloads all required data.

See also

optim_control(), routing_control(), optimize_alpha(), compute_weight_matrix(), interpolate_election_br() for the Brazilian-specific wrapper.

Other wrappers: interpolate_election_br()

Examples

if (FALSE) { # \dontrun{
# Minimal: sf objects + column names (auto-downloads OSM)
result <- interpolate_election(
  tracts_sf    = census_tracts,
  electoral_sf = voting_stations,
  calib_tracts  = c("pop_18_24", "pop_25_34"),
  calib_sources = c("voters_18_24", "voters_25_34")
)

# With pre-computed travel times (skip r5r)
result <- interpolate_election(
  tracts_sf    = census_tracts,
  electoral_sf = voting_stations,
  calib_tracts  = c("pop_young", "pop_old"),
  calib_sources = c("voters_young", "voters_old"),
  time_matrix  = my_tt_matrix
)

# GPU optimization with custom routing
result <- interpolate_election(
  tracts_sf    = census_tracts,
  electoral_sf = voting_stations,
  calib_tracts  = c("pop_young", "pop_old"),
  calib_sources = c("voters_young", "voters_old"),
  optim   = optim_control(use_gpu = TRUE),
  routing = routing_control(mode = c("WALK", "TRANSIT"))
)
} # }