Package 'redist'

Description

This function facilitates comparing an existing (i.e., non-simulated) redistricting plan to a set of simulated plans.

Usage

add_reference(plans, ref_plan, name = NULL)

Arguments

Value

a modified redist_plans object containing the reference plan

Description

Deprecated in favor of proj_avg(). Takes a column of a redist_plans object and averages it across a set of draws for each precinct.

Usage

avg_by_prec(plans, x, draws = NA)

Arguments

Value

a vector of length matching the number of precincts, containing the average.

Description

Applies hierarchical clustering to a distance matrix computed from a set of plans and takes the first k splits.

Usage

classify_plans(dist_mat, k = 8, method = "complete")

Arguments

Value

An object of class redist_classified, which is a list with two elements:

Use plot.redist_classified() for a visual summary.

Description

This function provides one way to identify the structural differences between two sets of redistricting plans. It operates by computing the precinct co-occurrence matrix (a symmetric matrix where the i,j-th entry is the fraction of plans where precinct i and j are in the same district) for each set, and then computing the first eigenvalue of the difference in these two matrices (in each direction). These eigenvalues identify the important parts of the map.

Usage

compare_plans(
  plans,
  set1,
  set2,
  shp = NULL,
  plot = "fill",
  thresh = 0.1,
  labs = c("Set 1", "Set 2"),
  ncores = 1
)

Arguments

Details

The co-occurrence matrices are regularized with a $Beta(1/ndists, 1-1/ndists)$ prior, which is useful for when either set1 or set2 is small.

Value

If possible, makes a comparison plot according to plot. Otherwise returns the following list:

Examples

data(iowa)
iowa_map <- redist_map(iowa, ndists = 4, pop_tol = 0.05)
plans1 <- redist_smc(iowa_map, 100, silent = TRUE)
plans2 <- redist_mergesplit(iowa_map, 200, warmup = 100, silent = TRUE)
compare_plans(plans1, plans2, shp = iowa_map)
compare_plans(plans2, as.integer(draw) <= 20,
    as.integer(draw) > 20, shp = iowa_map, plot = "line")

Description

Currently only implements the competitiveness function in equation (5) of Cho & Liu 2016.

Usage

competitiveness(map, rvote, dvote, .data = cur_plans())

redist.competitiveness(plans, rvote, dvote, alpha = 1, beta = 1)

Arguments

Value

Numeric vector with competitiveness scores

Examples

data(fl25)
data(fl25_enum)

plans_05 <- fl25_enum$plans[, fl25_enum$pop_dev <= 0.05]
# old: comp <- redist.competitiveness(plans_05, fl25$mccain, fl25$obama)
comp <- compet_talisman(plans_05, fl25, mccain, obama)

Description

The redist_smc() and redist_mergesplit() algorithms in this package allow for additional constraints on the redistricting process to be encoded in the target distribution for sampling. These functions are provided to specify these constraints. All arguments are quoted and evaluated in the context of the data frame provided to redist_constr().

Usage

add_constr_status_quo(constr, strength, current)

add_constr_grp_pow(
  constr,
  strength,
  group_pop,
  total_pop = NULL,
  tgt_group = 0.5,
  tgt_other = 0.5,
  pow = 1
)

add_constr_grp_hinge(
  constr,
  strength,
  group_pop,
  total_pop = NULL,
  tgts_group = c(0.55)
)

add_constr_grp_inv_hinge(
  constr,
  strength,
  group_pop,
  total_pop = NULL,
  tgts_group = c(0.55)
)

add_constr_compet(constr, strength, dvote, rvote, pow = 0.5)

add_constr_incumbency(constr, strength, incumbents)

add_constr_splits(constr, strength, admin)

add_constr_multisplits(constr, strength, admin)

add_constr_total_splits(constr, strength, admin)

add_constr_pop_dev(constr, strength)

add_constr_segregation(constr, strength, group_pop, total_pop = NULL)

add_constr_polsby(constr, strength, perim_df = NULL)

add_constr_fry_hold(
  constr,
  strength,
  total_pop = NULL,
  ssdmat = NULL,
  denominator = 1
)

add_constr_log_st(constr, strength, admin = NULL)

add_constr_edges_rem(constr, strength)

add_constr_custom(constr, strength, fn)

Arguments

Details

All constraints are fed into a Gibbs measure, with coefficients on each constraint set by the corresponding strength parameter. The strength can be any real number, with zero corresponding to no constraint. Higher and higher strength values will eventually cause the algorithm's accuracy and efficiency to suffer. Whenever you use constraints, be sure to check all sampling diagnostics.

The status_quo constraint adds a term measuring the variation of information distance between the plan and the reference, rescaled to [0, 1].

The grp_hinge constraint takes a list of target group percentages. It matches each district to its nearest target percentage, and then applies a penalty of the form $\sqrt{max(0, tgt - grouppct)}$, summing across districts. This penalizes districts which are below their target percentage. Use plot.redist_constr() to visualize the effect of this constraint and calibrate strength appropriately.

The grp_inv_hinge constraint takes a list of target group percentages. It matches each district to its nearest target percentage, and then applies a penalty of the form $\sqrt{max(0, grouppct - tgt)}$, summing across districts. This penalizes districts which are above their target percentage. Use plot.redist_constr() to visualize the effect of this constraint and calibrate strength appropriately.

The grp_pow constraint (for expert use) adds a term of the form $(|tgtgroup-grouppct||tgtother-grouppct|)^{pow})$, which encourages districts to have group shares near either tgt_group or tgt_other. Values of strength depend heavily on the values of these parameters and especially the pow parameter. Use plot.redist_constr() to visualize the effect of this constraint and calibrate strength appropriately.

The compet constraint encourages competitiveness by applying the grp_pow constraint with target percentages set to 50%. For convenience, it is specified with Democratic and Republican vote shares.

The incumbency constraint adds a term counting the number of districts containing paired-up incumbents. Values of strength should generally be small, given that the underlying values are counts.

The splits constraint adds a term counting the number of counties which are split once or more. Values of strength should generally be small, given that the underlying values are counts.

The multisplits constraint adds a term counting the number of counties which are split twice or more. Values of strength should generally be small, given that the underlying values are counts.

The total_splits constraint adds a term counting the total number of times each county is split, summed across counties (i.e., counting the number of excess district-county pairs). Values of strength should generally be small, given that the underlying values are counts.

The edges_rem constraint adds a term counting the number of edges removed from the adjacency graph. This is only usable with redist_flip(), as other algorithms implicitly use this via the compactness parameter. Values of strength should generally be small, given that the underlying values are counts.

The log_st constraint constraint adds a term counting the log number of spanning trees. This is only usable with redist_flip(), as other algorithms implicitly use this via the compactness parameter.

The polsby constraint adds a term encouraging compactness as defined by the Polsby Popper metric. Values of strength may be of moderate size.

The fry_hold constraint adds a term encouraging compactness as defined by the Fryer Holden metric. Values of strength should be extremely small, as the underlying values are massive when the true minimum Fryer Holden denominator is not known.

The segregation constraint adds a term encouraging segregation among minority groups, as measured by the dissimilarity index.

The pop_dev constraint adds a term encouraging plans to have smaller population deviations from the target population.

The custom constraint allows the user to specify their own constraint using a function which evaluates districts one at a time. The provided function fn should take two arguments: a vector describing the current plan assignment for each unit as its first argument, and an integer describing the district which to evaluate in the second argument. ⁠which([plans == distr])⁠ would give the indices of the units that are assigned to a district distr in any iteration. The function must return a single scalar for each plan - district combination, where a value of 0 indicates no penalty is applied. If users want to penalize an entire plan, they can have the penalty function return a scalar that does not depend on the district. It is important that fn not use information from precincts not included in distr, since in the case of SMC these precincts may not be assigned any district at all (plan will take the value of 0 for these precincts). The flexibility of this constraint comes with an additional computational cost, since the other constraints are written in C++ and so are more performant.

Examples

data(iowa)
iowa_map <- redist_map(iowa, existing_plan = cd_2010, pop_tol = 0.05)
constr <- redist_constr(iowa_map)
constr <- add_constr_splits(constr, strength = 1.5, admin = name)
constr <- add_constr_grp_hinge(constr, strength = 100,
    dem_08, tot_08, tgts_group = c(0.5, 0.6))
# encourage districts to have the same number of counties
constr <- add_constr_custom(constr, strength = 1000, fn = function(plan, distr) {
    # notice that we only use information on precincts in `distr`
    abs(sum(plan == distr) - 99/4)
})
print(constr)

Description

Count County Splits

Usage

county_splits(map, counties, .data = cur_plans())

redist.splits(plans, counties)

Arguments

Value

integer vector with one number for each map

Description

redist.compactness is used to compute different compactness statistics for a shapefile. It currently computes the Polsby-Popper, Schwartzberg score, Length-Width Ratio, Convex Hull score, Reock score, Boyce Clark Index, Fryer Holden score, Edges Removed number, and the log of the Spanning Trees.

Usage

distr_compactness(map, measure = "FracKept", .data = cur_plans(), ...)

redist.compactness(
  shp = NULL,
  plans,
  measure = c("PolsbyPopper"),
  total_pop = NULL,
  adj = NULL,
  draw = 1,
  ncores = 1,
  counties = NULL,
  planarize = 3857,
  ppRcpp,
  perim_path,
  perim_df
)

Arguments

Details

This function computes specified compactness scores for a map. If there is more than one shape specified for a single district, it combines them, if necessary, and computes one score for each district.

Polsby-Popper is computed as

$\frac{4*\pi*A(d)}{P(d)^2}$

where A is the area function, the district is d, and P is the perimeter function. All values are between 0 and 1, where larger values are more compact.

Schwartzberg is computed as

$\frac{P(d)}{2*\pi*\sqrt{\frac{A(d)}{\pi}}}$

where A is the area function, the district is d, and P is the perimeter function. All values are between 0 and 1, where larger values are more compact.

The Length Width ratio is computed as

$\frac{length}{width}$

where length is the shorter of the maximum x distance and the maximum y distance. Width is the longer of the two values. All values are between 0 and 1, where larger values are more compact.

The Convex Hull score is computed as

$\frac{A(d)}{A(CVH)}$

where A is the area function, d is the district, and CVH is the convex hull of the district. All values are between 0 and 1, where larger values are more compact.

The Reock score is computed as

$\frac{A(d)}{A(MBC)}$

where A is the area function, d is the district, and MBC is the minimum bounding circle of the district. All values are between 0 and 1, where larger values are more compact.

The Boyce Clark Index is computed as

$1 - \sum_{1}^{16}\{\frac{|\frac{r_i}{\sum_ir_i}*100-6.25 |\}}{200}$

. The $r_i$ are the distances of the 16 radii computed from the geometric centroid of the shape to the most outward point of the shape that intersects the radii, if the centroid is contained within the shape. If the centroid lies outside of the shape, a point on the surface is used, which will naturally incur a penalty to the score. All values are between 0 and 1, where larger values are more compact.

The Fryer Holden score for each district is computed with

$Pop\odot D(precinct)^2$

, where $Pop$ is the population product matrix. Each element is the product of the i-th and j-th precinct's populations. D represents the distance, where the matrix is the distance between each precinct. To fully compute this index, for any map, the sum of these values should be used as the numerator. The denominator can be calculated from the full enumeration of districts as the smallest calculated numerator. This produces very large numbers, where smaller values are more compact.

The log spanning tree measure is the logarithm of the product of the number of spanning trees which can be drawn on each district.

The edges removed measure is number of edges removed from the underlying adjacency graph. A smaller number of edges removed is more compact.

The fraction kept measure is the fraction of edges that were not removed from the underlying adjacency graph. This takes values 0 - 1, where 1 is more compact.

Value

A tibble with a column that specifies the district, a column for each specified measure, and a column that specifies the map number.

References

Boyce, R., & Clark, W. 1964. The Concept of Shape in Geography. Geographical Review, 54(4), 561-572.

Cox, E. 1927. A Method of Assigning Numerical and Percentage Values to the Degree of Roundness of Sand Grains. Journal of Paleontology, 1(3), 179-183.

Fryer R, Holden R. 2011. Measuring the Compactness of Political Districting Plans. Journal of Law and Economics.

Harris, Curtis C. 1964. “A scientific method of districting”. Behavioral Science 3(9), 219–225.

Maceachren, A. 1985. Compactness of Geographic Shape: Comparison and Evaluation of Measures. Geografiska Annaler. Series B, Human Geography, 67(1), 53-67.

Polsby, Daniel D., and Robert D. Popper. 1991. “The Third Criterion: Compactness as a procedural safeguard against partisan gerrymandering.” Yale Law & Policy Review 9 (2): 301–353.

Reock, E. 1961. A Note: Measuring Compactness as a Requirement of Legislative Apportionment. Midwest Journal of Political Science, 5(1), 70-74.

Schwartzberg, Joseph E. 1966. Reapportionment, Gerrymanders, and the Notion of Compactness. Minnesota Law Review. 1701.

Examples

data(fl25)
data(fl25_enum)

plans_05 <- fl25_enum$plans[, fl25_enum$pop_dev <= 0.05]

# old redist.compactness(
#     shp = fl25, plans = plans_05[, 1:3],
#     measure = c("PolsbyPopper", "EdgesRemoved")
# )
comp_polsby(plans_05[, 1:3], fl25)
comp_edges_rem(plans_05[, 1:3], fl25, fl25$adj)

Description

This data contains NAD83 (HARN) EPSG codes for every U.S. state. Since redist uses projected geometries, it is often a good idea to use projections tailored to a particular state, rather than, for example, a Mercator projection. Use these codes along with sf::st_transform() to project your shapefiles nicely.

Usage

data("EPSG")

Format

named list containing EPSG codes for each U.S. state. Codes are indexed by state abbreviations.

Examples

data(EPSG)
EPSG$WA # 2855

Description

This data set contains the 25-precinct shapefile and related data for each precinct. All possible partitions of the 25 precincts into three contiguous congressional districts are stored in fl25_enum, and the corresponding adjacency graph is stored in fl25_adj. This is generally useful for demonstrating basic algorithms locally.

Usage

data("fl25")

Format

sf data.frame containing columns for useful data related to the redistricting process, subsetted from real data in Florida, and sf geometry column.

geoid

Contains unique identifier for each precinct which can be matched to the full Florida dataset.

pop

Contains the population of each precinct.

vap

Contains the voting age population of each precinct.

obama

Contains the 2012 presidential vote for Obama.

mccain

Contains the 2012 presidential vote for McCain.

TotPop

Contains the population of each precinct. Identical to pop.

BlackPop

Contains the black population of each precinct.

HispPop

Contains the Hispanic population of each precinct.

VAP

Contains the voting age population of each precinct. Identical to vap.

BlackVAP

Contains the voting age population of black constituents of each precinct.

HispVAP

Contains the voting age population of hispanic constituents of each precinct.

geometry

Contains sf geometry of each precinct.

References

Fifield, Benjamin, Michael Higgins, Kosuke Imai and Alexander Tarr. (2016) "A New Automated Redistricting Simulator Using Markov Chain Monte Carlo." Working Paper. Available at http://imai.princeton.edu/research/files/redist.pdf.

Examples

data(fl25)

Description

This data set contains the 25-precinct shapefile and related data for each precinct. All possible partitions of the 25 precincts into three contiguous congressional districts are stored in fl25_enum, and the corresponding adjacency graph is stored in fl25_adj.

Format

A list storing the adjacency graph for the 25-precinct subset of Florida.

References

Fifield, Benjamin, Michael Higgins, Kosuke Imai and Alexander Tarr. (2016) "A New Automated Redistricting Simulator Using Markov Chain Monte Carlo." Working Paper. Available at http://imai.princeton.edu/research/files/redist.pdf.

Examples

data(fl25_adj)

Description

This data set contains demographic and geographic information about 25 contiguous precincts in the state of Florida. The data lists all possible partitions of the 25 precincts into three contiguous congressional districts. The 25-precinct shapefile may be found in fl25

Usage

data("fl25_enum")

Format

A list with two entries:

plans

A matrix containing every partition of the 25 precincts into three contiguous congressional districts, with no population constraint.

pop_dev

A vector containing the maximum population deviation across the three districts for each plan.

References

Fifield, Benjamin, Michael Higgins, Kosuke Imai and Alexander Tarr. (2016) "A New Automated Redistricting Simulator Using Markov Chain Monte Carlo." Working Paper. Available at http://imai.princeton.edu/research/files/redist.pdf.

Massey, Douglas and Nancy Denton. (1987) "The Dimensions of Social Segregation". Social Forces.

Examples

data(fl25_enum)

Description

This data set contains the 250 Precinct shapefile and related data for each precinct.

Usage

data("fl250")

Format

sf data.frame containing columns for useful data related to the redistricting process, subsetted from real data in Florida, and sf geometry column.

geoid

Contains unique identifier for each precinct which can be matched to the full Florida dataset.

pop

Contains the population of each precinct.

vap

Contains the voting age population of each precinct.

obama

Contains the 2012 presidential vote for Obama.

mccain

Contains the 2012 presidential vote for McCain.

TotPop

Contains the population of each precinct. Identical to pop.

BlackPop

Contains the black population of each precinct.

HispPop

Contains the Hispanic population of each precinct.

VAP

Contains the voting age population of each precinct. Identical to vap.

BlackVAP

Contains the voting age population of black constituents of each precinct.

HispVAP

Contains the voting age population of hispanic constituents of each precinct.

geometry

Contains sf geometry of each precinct.

Details

It is a random 70 precinct connected subset from Florida's precincts. This was introduced by doi:10.1080/2330443X.2020.1791773

References

Benjamin Fifield, Kosuke Imai, Jun Kawahara & Christopher T. Kenny (2020) The Essential Role of Empirical Validation in Legislative Redistricting Simulation, Statistics and Public Policy, 7:1, 52-68, doi:10.1080/2330443X.2020.1791773

Examples

data(fl250)

Description

This data set contains the 70 Precinct shapefile and related data for each precinct.

Usage

data("fl70")

Format

sf data.frame containing columns for useful data related to the redistricting process, subsetted from real data in Florida, and sf geometry column.

geoid

Contains unique identifier for each precinct which can be matched to the full Florida dataset.

pop

Contains the population of each precinct.

vap

Contains the voting age population of each precinct.

obama

Contains the 2012 presidential vote for Obama.

mccain

Contains the 2012 presidential vote for McCain.

TotPop

Contains the population of each precinct. Identical to pop.

BlackPop

Contains the black population of each precinct.

HispPop

Contains the Hispanic population of each precinct.

VAP

Contains the voting age population of each precinct. Identical to vap.

BlackVAP

Contains the voting age population of black constituents of each precinct.

HispVAP

Contains the voting age population of hispanic constituents of each precinct.

geometry

Contains sf geometry of each precinct.

Details

It is a random 70 precinct connected subset from Florida's precincts. This was introduced by doi:10.1080/2330443X.2020.1791773

References

Benjamin Fifield, Kosuke Imai, Jun Kawahara & Christopher T. Kenny (2020) The Essential Role of Empirical Validation in Legislative Redistricting Simulation, Statistics and Public Policy, 7:1, 52-68, doi:10.1080/2330443X.2020.1791773

Examples

data(fl70)

Description

Freeze Parts of a Map

Usage

freeze(freeze_row, plan, .data = cur_map())

redist.freeze(adj, freeze_row, plan = rep(1, length(adj)))

Arguments

Value

integer vector to group by

Examples

library(redist)
library(dplyr)
data(fl25)
data(fl25_enum)
data(fl25_adj)
plan <- fl25_enum$plans[, 5118]
freeze_id <- redist.freeze(adj = fl25_adj, freeze_row = (plan == 2),
    plan = plan)

data(iowa)
map <- redist_map(iowa, existing_plan = cd_2010, pop_tol = 0.02)
map <- map %>% merge_by(freeze(cd_2010 == 1, .data = .))

Description

Get and set the adjacency graph from a redist_map object

Usage

get_adj(x)

set_adj(x, adj)

Arguments

Value

a zero-indexed adjacency list (get_adj)

the modified redist_map object (set_adj)

Description

Extract the existing district assignment from a redist_map object

Usage

get_existing(x)

Arguments

Value

an integer vector of district numbers

Description

Extract the Metropolis Hastings Acceptance Rate

Usage

get_mh_acceptance_rate(plans)

Arguments

Value

a numeric acceptance rate

Description

Extract the matrix of district assignments from a redistricting simulation

Usage

get_plans_matrix(x)

## S3 method for class 'redist_plans'
as.matrix(x, ...)

Arguments

Value

matrix

matrix

Description

May be NULL if no weights exist (MCMC or optimization methods).

Usage

get_plans_weights(plans)

## S3 method for class 'redist_plans'
weights(object, ...)

Arguments

Value

A numeric vector of weights, with an additional attribute resampled indicating whether the plans have been resampled according to these weights. If weights have been resampled, this returns the weights before resampling (i.e., they do not correspond to the resampled plans).

numeric vector

Description

Get and set the population tolerance from a redist_map object

Usage

get_pop_tol(map)

set_pop_tol(map, pop_tol)

Arguments

Value

For get_pop_tol, a single numeric value, the population tolerance

For seet_pop_tol, an updated redist_map object

Description

Extract the sampling information from a redistricting simulation

Usage

get_sampling_info(plans)

Arguments

Value

a list of parameters and information about the sampling problem.

Description

Extract the target district population from a redist_map object

Usage

get_target(x)

Arguments

Value

a single numeric value, the target population

Description

redist.group.percent computes the proportion that a group makes up in each district across a matrix of maps.

Usage

group_frac(
  map,
  group_pop,
  total_pop = map[[attr(map, "pop_col")]],
  .data = pl()
)

redist.group.percent(plans, group_pop, total_pop, ncores = 1)

Arguments

Value

matrix with percent for each district

Examples

data(fl25)
data(fl25_enum)

cd <- fl25_enum$plans[, fl25_enum$pop_dev <= 0.05]
fl25_map = redist_map(fl25, ndists=3, pop_tol=0.1)
fl25_plans = redist_plans(cd, fl25_map, algorithm="enumpart")

group_frac(fl25_map, BlackPop, TotPop, fl25_plans)

Description

This data contains geographic and demographic information on the 99 counties of the state of Iowa.

Usage

data("iowa")

Format

sf tibble containing columns for useful data related to the redistricting process

fips

The FIPS code for the county.

cd_2010

The 2010 congressional district assignments.

pop

The total population of the precinct, according to the 2010 Census.

white

The non-Hispanic white population of the precinct.

black

The non-Hispanic Black population of the precinct.

hisp

The Hispanic population (of any race) of the precinct.

vap

The voting-age population of the precinct.

wvap

The white voting-age population of the precinct.

bvap

The Black voting-age population of the precinct.

hvap

The Hispanic voting-age population of the precinct.

tot_08

Number of total votes for president in the county in 2008.

dem_08

Number of votes for Barack Obama in 2008.

rep_08

Number of votes for John McCain in 2008.

region

The 28E agency regions for counties.

geometry

The sf geometry column containing the geographic information.

Examples

data(iowa)
print(iowa)

Description

Check that a redist_map object is contiguous

Usage

is_contiguous(x)

Arguments

Value

TRUE if contiguous.

Description

Identify which counties are split by a plan

Usage

is_county_split(plan, counties)

Arguments

Value

A logical vector which is TRUE for precincts belonging to counties which are split

Description

Extract the last plan from a set of plans

Usage

last_plan(plans)

Arguments

Value

An integer vector containing the final plan assignment.

Description

Creates a grouping ID to unite geographies and perform analysis on a smaller set of precincts. It identifies all precincts more than boundary edges of a district district boundary. Each contiguous group of precincts more than boundary steps away from another district gets it own group. Some districts may have multiple, disconnected components that make up the core, but each of these is assigned a separate grouping id so that a call to sf::st_union() would produce only connected pieces.

Usage

make_cores(.data = cur_map(), boundary = 1, focus = NULL)

redist.identify.cores(adj, plan, boundary = 1, focus = NULL, simplify = TRUE)

Arguments

Details

This is a loose interpretation of the NCSL's summary of redistricting criteria to preserve the cores of prior districts. Using the adjacency graph for a given plan, it will locate the precincts on the boundary of the district, within boundary steps of the edge. Each of these is given their own group. Each remaining entry that is not near the boundary of the district is given an id that can be used to group the remainder of the district by connected component. This portion is deemed the core of the district.

Value

integer vector (if simplify is false). Otherwise it returns a tibble with the grouping variable as group_id and additional information on connected components.

See Also

redist.plot.cores() for a plotting function

Examples

data(fl250)
fl250_map <- redist_map(fl250, ndists = 4, pop_tol = 0.01)
plan <- as.matrix(redist_smc(fl250_map, 20, silent = TRUE))
core <- redist.identify.cores(adj = fl250_map$adj, plan = plan)
redist.plot.cores(shp = fl250, plan = plan, core = core)

Description

District numbers in simulated plans are by and large random. This function attempts to renumber the districts across all simulated plans to match the numbers in a provided plan, using the Hungarian algorithm.

Usage

match_numbers(
  data,
  plan,
  total_pop = attr(data, "prec_pop"),
  col = "pop_overlap"
)

Arguments

Value

a modified redist_plans object. New district numbers will be stored as an ordered factor variable in the district column. The district numbers in the plan matrix will match the levels of this factor.

Examples

data(iowa)

iowa_map <- redist_map(iowa, existing_plan = cd_2010, pop_tol = 0.05)
plans <- redist_smc(iowa_map, 100, silent = TRUE)
match_numbers(plans, "cd_2010")

Description

In performing a county-level or cores-based analysis it is often necessary to merge several units together into a larger unit. This function performs this operation, modifying the adjacency graph as needed and attempting to properly aggregate other data columns.

Usage

merge_by(.data, ..., by_existing = TRUE, drop_geom = TRUE, collapse_chr = TRUE)

Arguments

Value

A merged redist_map object

Description

This function computes a minimal set of population moves (e.g., 5 people from district 1 to district 3) to maximally balance the population between districts. The moves are only allowed between districts that share the territory of a county, so that any boundary adjustments are guaranteed to preserve all unbroken county boundaries.

Usage

min_move_parity(map, plan, counties = NULL, penalty = 0.2)

Arguments

Value

a list with components:

moves

A tibble describing the population moves

pop_old

The current district populations

pop_new

The district populations after the moves

Examples

data(iowa)
iowa_map <- redist_map(iowa, existing_plan = cd_2010, pop_tol = 0.01)
min_move_parity(iowa_map, cd_2010)

Description

Counts the total number of municpalities that are split. Municipalities in this interpretation do not need to cover the entire state, which differs from counties.

Usage

muni_splits(map, munis, .data = cur_plans())

redist.muni.splits(plans, munis)

Arguments

Value

integer vector of length ndist by ncol(plans)

Examples

data(iowa)
ia <- redist_map(iowa, existing_plan = cd_2010, total_pop = pop, pop_tol = 0.01)
plans <- redist_smc(ia, 50, silent = TRUE)
ia$region[1:10] <- NA
#old redist.muni.splits(plans, ia$region)
splits_sub_admin(plans, ia, region)

Description

District numbers in simulated plans are by and large random. This function will renumber the districts across all simulated plans in order of a provided quantity of interest.

Usage

number_by(data, x, desc = FALSE)

Arguments

Value

a modified redist_plans object. New district numbers will be stored as an ordered factor variable in the district column. The district numbers in the plan matrix will match the levels of this factor.

Description

redist.metrics is used to compute different gerrymandering metrics for a set of maps.

Usage

partisan_metrics(map, measure, rvote, dvote, ..., .data = cur_plans())

redist.metrics(
  plans,
  measure = "DSeats",
  rvote,
  dvote,
  tau = 1,
  biasV = 0.5,
  respV = 0.5,
  bandwidth = 0.01,
  draw = 1
)

Arguments

Details

This function computes specified compactness scores for a map. If there is more than one precinct specified for a map, it aggregates to the district level and computes one score.

• DSeats is computed as the expected number of Democratic seats with no change in votes.

• DVS is the Democratic Vote Share, which is the two party vote share with Democratic votes as the numerator.

• EffGap is the Efficiency Gap, calculated with votes directly.

• EffGapEqPop is the Efficiency Gap under an Equal Population assumption, calculated with the DVS.

• TauGap is the Tau Gap, computed with the Equal Population assumption.

• MeanMedian is the Mean Median difference.

• Bias is the Partisan Bias computed at 0.5.

• BiasV is the Partisan Bias computed at value V.

• Declination is the value of declination at 0.5.

• Responsiveness is the responsiveness at the user-supplied value with the user-supplied bandwidth.

• LopsidedWins computed the Lopsided Outcomes value, but does not produce a test statistic.

• RankedMarginal computes the Ranked Marginal Deviation (0-1, smaller is better). This is also known as the "Gerrymandering Index" and is sometimes presented as this value divided by 10000.

• SmoothedSeat computes the Smoothed Seat Count Deviation (0-1, smaller is R Bias, bigger is D Bias).

Value

A tibble with a column for each specified measure and a column that specifies the map number.

References

Jonathan N. Katz, Gary King, and Elizabeth Rosenblatt. 2020. Theoretical Foundations and Empirical Evaluations of Partisan Fairness in District-Based Democracies. American Political Science Review, 114, 1, Pp. 164-178.

Gregory S. Warrington. 2018. "Quantifying Gerrymandering Using the Vote Distribution." Election Law Journal: Rules, Politics, and Policy. Pp. 39-57.http://doi.org/10.1089/elj.2017.0447

Samuel S.-H. Wang. 2016. "Three Tests for Practical Evaluation of Partisan Gerrymandering." Stanford Law Review, 68, Pp. 1263 - 1321.

Gregory Herschlag, Han Sung Kang, Justin Luo, Christy Vaughn Graves, Sachet Bangia, Robert Ravier & Jonathan C. Mattingly (2020) Quantifying Gerrymandering in North Carolina, Statistics and Public Policy, 7:1, 30-38, DOI: 10.1080/2330443X.2020.1796400

Examples

data(fl25)
data(fl25_enum)
plans_05 <- fl25_enum$plans[, fl25_enum$pop_dev <= 0.05]
# old: redist.metrics(plans_05, measure = "DSeats", rvote = fl25$mccain, dvote = fl25$obama)
part_dseats(plans_05, fl25, mccain, obama)

Description

Useful inside piped expressions and dplyr functions.

Usage

pl()

Value

A redist_plans object, or NULL if not called from inside a dplyr function.

Examples

pl()

Description

Compute Distance between Partitions

Usage

plan_distances(plans, measure = "variation of information", ncores = 1)

redist.distances(plans, measure = "Hamming", ncores = 1, total_pop = NULL)

Arguments

Details

Hamming distance measures the number of different precinct assignments between plans. Manhattan and Euclidean distances are the 1- and 2-norms for the assignment vectors. All three of the Hamming, Manhattan, and Euclidean distances implemented here are not invariant to permutations of the district labels; permuting will cause large changes in measured distance, and maps which are identical up to a permutation may be computed to be maximally distant.

Variation of Information is a metric on population partitions (i.e., districtings) which is invariant to permutations of the district labels, and arises out of information theory. It is calculated as

$VI(\xi, \xi') = -\sum_{i=1}^n\sum_{j=1}^n pop(\xi_i \cap \xi'_j)/P (2log(pop(\xi_i \cap \xi'_j)) - log(pop(\xi_i)) - log(pop(\xi'_j)))$

where $\xi,\xi'$ are the partitions, $\xi_i,\xi_j$ the individual districts, $pop(\cdot)$ is the population, and $P$ the total population of the state. VI is also expressible as the difference between the joint entropy and the mutual information (see references).

Value

distance_matrix returns a numeric distance matrix for the chosen metric.

a named list of distance matrices, one for each distance measure selected.

References

Cover, T. M. and Thomas, J. A. (2006). Elements of information theory. John Wiley & Sons, 2 edition.

Examples

data(fl25)
data(fl25_enum)

plans_05 <- fl25_enum$plans[, fl25_enum$pop_dev <= 0.05]
distances <- redist.distances(plans_05)
distances$Hamming[1:5, 1:5]

Description

Returns the off-diagonal elements of the variation of information distance matrix for a sample of plans, which can be used as a diagnostic measure to assess the diversity of a set of plans. While the exact scale varies depending on the number of precincts and districts, generally diversity is good if most of the values are greater than 0.5. Conversely, if there are many values close to zero, then the sample has many similar plans and may not be a good approximation to the target distribution.

Usage

plans_diversity(
  plans,
  chains = 1,
  n_max = 100,
  ncores = 1,
  total_pop = attr(plans, "prec_pop")
)

Arguments

Value

A numeric vector of off-diagonal variation of information distances.

Examples

data(iowa)
ia <- redist_map(iowa, existing_plan = cd_2010, pop_tol = 0.01)
plans <- redist_smc(ia, 100, silent = TRUE)
hist(plans_diversity(plans))

Description

Plot a plan classification

Usage

## S3 method for class 'redist_classified'
plot(x, plans, shp, type = "fill", which = NULL, ...)

Arguments

Value

ggplot comparison plot

Description

Plots the constraint strength versus some running variable. Currently supports visualizing the grp_hinge, grp_inv_hinge, and grp_pow constraints.

Usage

## S3 method for class 'redist_constr'
plot(x, y, type = "group", xlim = c(0, 1), ...)

Arguments

Value

A ggplot object

Examples

data(iowa)
iowa_map <- redist_map(iowa, existing_plan = cd_2010, pop_tol = 0.05)
constr <- redist_constr(iowa_map)
constr <- add_constr_grp_hinge(constr, strength = 30,
                               dem_08, tot_08, tgts_group = 0.5)
constr <- add_constr_grp_hinge(constr, strength = -20,
                               dem_08, tot_08, tgts_group = 0.3)
plot(constr)

Description

Plot a redist_map

Usage

## S3 method for class 'redist_map'
plot(x, fill = NULL, by_distr = FALSE, adj = FALSE, ...)

Arguments

Value

ggplot2 object

Examples

data(fl25)
d <- redist_map(fl25, ndists = 3, pop_tol = 0.05)
plot(d)
plot(d, BlackPop/pop)

data(fl25_enum)
fl25$dist <- fl25_enum$plans[, 5118]
d <- redist_map(fl25, existing_plan = dist)
plot(d)

Description

If no arguments are passed, defaults to plotting the sampling weights for the redist_plans object. If no weights exist, plots district populations.

Usage

## S3 method for class 'redist_plans'
plot(x, ..., type = "distr_qtys")

Arguments

Description

Extract the district assignments for a precinct across all simulated plans

Usage

prec_assignment(prec, .data = pl())

Arguments

Value

integer vector, a row from a plans matrix

Description

For a map with n precincts Returns an n-by-n matrix, where each entry measures the fraction of the plans in which the row and column precincts were in the same district.

Usage

prec_cooccurrence(plans, which = NULL, sampled_only = TRUE, ncores = 1)

Arguments

Value

a symmetric matrix the size of the number of precincts.

Description

Print redist_classified objects

Usage

## S3 method for class 'redist_classified'
print(x, ...)

Arguments

Value

prints to console

Description

Generic to print redist_constr

Usage

## S3 method for class 'redist_constr'
print(x, header = TRUE, details = TRUE, ...)

Arguments

Value

Prints to console and returns input redist_constr

Description

Generic to print redist_map

Usage

## S3 method for class 'redist_map'
print(x, ...)

Arguments

Value

Prints to console and returns input redist_map

Description

Print method for redist_plans

Usage

## S3 method for class 'redist_plans'
print(x, ...)

Arguments

Value

The original object, invisibly.

Description

The projective distribution of a district-level summary statistic (McCartan 2024) is the distribution of values of that statistic across a set of plans for the district each precinct belongs to. The projective average of a statistic is the average value of the projective distribution in each precinct. A projective contrast is the difference between the projective average for a single plan and the projective average for an ensemble of sampled plans.

It is very important to properly account for variation in the projective distribution when looking at projective contrasts. The pfdr argument to proj_contr() will calculate q-values for each precinct that can be used to control the positive false discovery rate (pFDR) to avoid being misled by this variation. See redist.plot.contr_pfdr() for a way to automatically plot projective contrasts with this false discovery rate control.

Usage

proj_distr(plans, x, draws = NA)

proj_avg(plans, x, draws = NA)

proj_contr(plans, x, compare = NA, draws = NA, norm = FALSE, pfdr = FALSE)

Arguments

Value

proj_distr: A matrix with a row for each precinct (row in the map object) and a column for every draw described by draws.

proj_avg: A numeric vector of length matching the number of precincts.

proj_contr: A numeric vector of length matching the number of precincts, optionally with a "q" attribute containing q-values.

References

McCartan, C. (2024). Projective Averages for Summarizing Redistricting Ensembles. arXiv preprint. Available at https://arxiv.org/abs/.

Examples

data(iowa)
map <- redist_map(iowa, existing_plan = cd_2010, pop_tol = 0.01)
plans <- redist_smc(map, 50, silent = TRUE)
plans$dem <- group_frac(map, dem_08, tot_08, plans)

proj_distr(plans, dem) # a 99-by-50 matrix
plot(map, proj_avg(plans, dem))
plot(map, proj_contr(plans, dem))
plot(map, proj_contr(plans, dem, comp="cd_2010"))

Description

Merging map units through merge_by or summarize changes the indexing of each unit. Use this function to take a set of redistricting plans from a redist algorithm and re-index them to be compatible with the original set of units.

Usage

pullback(plans, map = NULL)

Arguments

Value

a new, re-indexed, redist_plans object

Description

Only works when all the sets are compatible—generated from the same map, with the same number of districts. Sets of plans will be indexed by the chain column.

Usage

## S3 method for class 'redist_plans'
rbind(..., deparse.level = 1)

Arguments

Value

A new redist_plans object.

Description

Builds a confidence interval for a quantity of interest. If multiple runs are available, uses the between-run variation to estimate the standard error. If only one run is available, uses information on the SMC particle/plan genealogy to estimate the standard error, using a variant of the method of Olson & Douc (2019). The multiple-run estimator is more reliable, especially for situations with many districts, and should be used when parallelism is available. All reference plans are ignored.

Usage

redist_ci(plans, x, district = 1L, conf = 0.9, by_chain = FALSE)

redist_smc_ci(plans, x, district = 1L, conf = 0.9, by_chain = FALSE)

redist_mcmc_ci(plans, x, district = 1L, conf = 0.9, by_chain = FALSE)

Arguments

Value

A tibble with three columns: X, X_lower, and X_upper, where X is the name of the vector of interest, containing the mean and confidence interval. When used inside summarize() this will create three columns in the output data.

Functions

• redist_smc_ci(): Compute confidence intervals for SMC output.

• redist_mcmc_ci(): Compute confidence intervals for MCMC output.

References

Lee, A., & Whiteley, N. (2018). Variance estimation in the particle filter. Biometrika, 105(3), 609-625.

Olsson, J., & Douc, R. (2019). Numerically stable online estimation of variance in particle filters. Bernoulli, 25(2), 1504-1535.

H. P. Chan and T. L. Lai. A general theory of particle filters in hidden Markov models and some applications. Ann. Statist., 41(6):2877–2904, 2013.

Examples

library(dplyr)
data(iowa)

iowa_map <- redist_map(iowa, existing_plan = cd_2010, pop_tol = 0.05)
plans <- redist_mergesplit_parallel(iowa_map, nsims = 200, chains = 2, silent = TRUE) %>%
    mutate(dem = group_frac(iowa_map, dem_08, dem_08 + rep_08)) %>%
    number_by(dem)
redist_smc_ci(plans, dem)

Description

redist_constr objects are used to specify constraints when sampling redistricting plans with redist_smc() and redist_mergesplit(). Each constraint is specified as a function which scores a given plan. Higher scores are penalized and sampled less frequently.

Usage

redist_constr(map = tibble())

Arguments

Details

The redist_constr object keeps track of sampling constraints in a nested list. You can view the exact structure of this list by calling str(). Constraints may be added by using one of the following functions:

• add_constr_compet()

• add_constr_custom()

• add_constr_edges_rem()

• add_constr_fry_hold()

• add_constr_grp_hinge()

• add_constr_grp_inv_hinge()

• add_constr_grp_pow()

• add_constr_incumbency()

• add_constr_log_st()

• add_constr_multisplits()

• add_constr_polsby()

• add_constr_pop_dev()

• add_constr_segregation()

• add_constr_splits()

• add_constr_status_quo()

• add_constr_total_splits()

More information about each constraint can be found on the relevant constraint page.

Value

a redist_constr object, which is just a list with a certain nested structure.

Examples

data(iowa)
map_ia <- redist_map(iowa, existing_plan = cd_2010, pop_tol = 0.01)
constr <- redist_constr(map_ia)
constr <- add_constr_splits(constr, strength = 1.5, admin = region)
print(constr)

Description

This function allows users to simulate redistricting plans using a Markov Chain Monte Carlo algorithm (Fifield, Higgins, Imai, and Tarr 2020). Several constraints corresponding to substantive requirements in the redistricting process are implemented, including population parity and geographic compactness. In addition, the function includes multiple-swap and simulated tempering functionality to improve the mixing of the Markov Chain.

Usage

redist_flip(
  map,
  nsims,
  warmup = 0,
  init_plan,
  constraints = add_constr_edges_rem(redist_constr(map), 0.4),
  thin = 1,
  eprob = 0.05,
  lambda = 0,
  temper = FALSE,
  betaseq = "powerlaw",
  betaseqlength = 10,
  betaweights = NULL,
  adapt_lambda = FALSE,
  adapt_eprob = FALSE,
  exact_mh = FALSE,
  adjswaps = TRUE,
  init_name = NULL,
  verbose = TRUE,
  nthin
)

Arguments

Details

redist_flip allows for Gibbs constraints to be supplied via a list object passed to constraints. redist_flip uses a small compactness constraint by default, as this improves the realism of the maps greatly and also leads to large speed improvements. (One of the most time consuming aspects of the flip MCMC backend is checking for district shattering, which is slowed down even further by non-compact districts. As such, it is recommended that all flip simulations use at least a minimal compactness constraint, even if you weaken it from the default settings.) The default is a compact constraint using the edges-removed metric with a weight of 0.6. For very small maps (< 100 precincts), you will likely want to weaken (lower) this constraint, while for very large maps (> 5000 precincts), you will likely want to strengthen (increase) this constraint. Otherwise, for most maps, the default constraint should be a good starting place.

redist_flip samples from a known target distribution which can be described using the constraints. The following describes the constraints available. The general advice is to set weights in a way that gets between 20% and 40% acceptance on average, though more tuning advice is available in the vignette on using MCMC methods.Having too small of an acceptance rate indicates that the weights within constraints are too large and will impact sampling efficiency. If the Metropolis Hastings acceptance rate is too large, this may impact the target distribution, but may be fine for general exploration of possible maps.

There are currently 9 implemented constraint types, though 'compact and partisan have sub-types which are specified via a character metric within their respective list objects. The constraints are as follows:

• compact - biases the algorithm towards drawing more compact districts.

• weight - the coefficient to put on the Gibbs constraint

• metric - which metric to use. Must be one of edges-removed (the default), polsby-popper, fryer-holden, or log-st. Using Polsby Popper is generally not recommended, as edges-removed is faster and highly correlated. log-st can be used to match the target distribution of redist_smc or redist_mergesplit.

• areas - Only used with polsby-popper - A vector of precinct areas.

• borderlength_mat - Only used with polsby-popper - A matrix of precinct border lengths.

• ssdmat - Only used with fryer-holden - A matrix of squared distances between precinct centroids.

• ssd_denom - Only used with fryer-holden - a positive integer to use as the normalizing constant for the Relative Proximity Index.

• population - A Gibbs constraint to complement the hard population constraint set by pop_tol. This penalizes moves which move away from smaller population parity deviations. It is very useful when an init_plan sits outside of the desired pop_tol but there are substantive reasons to use that plan. This constraint uses the input to total_pop.

• weight - the coefficient to put on the Gibbs constraint

• countysplit This is a Gibbs constraint to minimize county splits. Unlike SMC's county constraint, this allows for more than ndists - 1 splits and does not require that counties are contiguous.

• weight - the coefficient to put on the Gibbs constraint

• hinge This uses the proportion of a group in a district and matches to the nearest target proportion, and then creates a penalty of $\sqrt{max(0, nearest.target - group.pct)}$.

• weight - the coefficient to put on the Gibbs constraint

• minorityprop - A numeric vector of minority proportions (between 0 and 1) which districts should aim to have

• vra This takes two target proportions of the presence of a minority group within a district. $(|target.min - group.pct||target.other - group.pct|)^{1.5})$

• weight - the coefficient to put on the Gibbs constraint

• target_min - the target minority percentage. Often, this is set to 0.55 to encourage minority majority districts.

• target_other - the target minority percentage for non majority minority districts.

• minority This constraint sorts the districts by the proportion of a group in a district and compares the highest districts to the entries of minorityprop. This takes the form $\sum_{i=1}^{n} \sqrt{|group.pct(i) - minorityprop(i)| }$ where n is the length of minorityprop input.

• weight - the coefficient to put on the Gibbs constraint

• minorityprop - A numeric vector of minority proportions (between 0 and 1) which districts should aim to have

• similarity This is a status-quo constraint which penalizes plans which are very different from the starting place. It is useful for local exploration.

• weight - the coefficient to put on the Gibbs constraint

• partisan This is a constraint which minimizes partisan bias, either as measured as the difference from proportional representation or as the magnitude of the efficiency gap.

• weight - the coefficient to put on the Gibbs constraint

• rvote - An integer vector of votes for Republicans or other party

• dvote - An integer vector of votes for Democrats or other party

• metric - which metric to use. Must be one of proportional-representation or efficiency-gap.

• segregation This constraint attempts to minimize the degree of dissimilarity between districts by group population.

• weight - the coefficient to put on the Gibbs constraint

Value

A redist_plans object containing the simulated plans.

References

Fifield, B., Higgins, M., Imai, K., & Tarr, A. (2020). Automated redistricting simulation using Markov chain Monte Carlo. Journal of Computational and Graphical Statistics, 29(4), 715-728.

Examples

data(iowa)
iowa_map <- redist_map(iowa, ndists = 4, existing_plan = cd_2010, total_pop = pop,
    pop_tol = 0.05)
sims <- redist_flip(map = iowa_map, nsims = 100)

Description

redist_flip_anneal simulates congressional redistricting plans using Markov chain Monte Carlo methods coupled with simulated annealing.

Usage

redist_flip_anneal(
  map,
  nsims,
  warmup = 0,
  init_plan = NULL,
  constraints = redist_constr(),
  num_hot_steps = 40000,
  num_annealing_steps = 60000,
  num_cold_steps = 20000,
  eprob = 0.05,
  lambda = 0,
  adapt_lambda = FALSE,
  adapt_eprob = FALSE,
  exact_mh = FALSE,
  maxiterrsg = 5000,
  verbose = TRUE
)

Arguments

Value

redist_plans

Description

Sets up a redistricting problem.

Usage

redist_map(
  ...,
  existing_plan = NULL,
  pop_tol = NULL,
  total_pop = c("pop", "population", "total_pop", "POP100"),
  ndists = NULL,
  pop_bounds = NULL,
  adj = NULL,
  adj_col = "adj",
  planarize = 3857
)

as_redist_map(x)

Arguments

Details

A redist_map object is a tibble which contains an adjacency list and additional information about the number of districts and population bounds. It supports all of the dplyr generics, and will adjust the adjacency list and attributes according to these functions; i.e., if we filter to a subset of units, the graph will change to subset to these units, and the population bounds will adjust accordingly. If an existing map is also attached to the object, the number of districts will also adjust. Subsetting with `[` and `[[` does not recompute graphs or attributes.

Other useful methods for redist_map objects:

• merge_by

• get_adj

• plot.redist_map

Value

A redist_map object

Examples

data(fl25)
d <- redist_map(fl25, ndists = 3, pop_tol = 0.05, total_pop = pop)
dplyr::filter(d, pop >= 10e3)

Description

redist_mergesplit uses a Markov Chain Monte Carlo algorithm (Carter et al. 2019; based on DeFord et. al 2019) to generate congressional or legislative redistricting plans according to contiguity, population, compactness, and administrative boundary constraints. The MCMC proposal is the same as is used in the SMC sampler (McCartan and Imai 2023); it is similar but not identical to those used in the references. 1-level hierarchical Merge-split is supported through the counties parameter; unlike in the SMC algorithm, this does not guarantee a maximum number of county splits.

Usage

redist_mergesplit(
  map,
  nsims,
  warmup = if (is.null(init_plan)) 10 else max(100, nsims%/%5),
  thin = 1L,
  init_plan = NULL,
  counties = NULL,
  compactness = 1,
  constraints = list(),
  constraint_fn = function(m) rep(0, ncol(m)),
  adapt_k_thresh = 0.99,
  k = NULL,
  init_name = NULL,
  silly_adj_fix = FALSE,
  verbose = FALSE,
  silent = FALSE
)

Arguments

Details

This function draws samples from a specific target measure, controlled by the map, compactness, and constraints parameters.

Key to ensuring good performance is monitoring the acceptance rate, which is reported at the sample level in the output. Users should also check diagnostics of the sample by running summary.redist_plans().

Higher values of compactness sample more compact districts; setting this parameter to 1 is computationally efficient and generates nicely compact districts.

Value

redist_mergesplit returns an object of class redist_plans containing the simulated plans.

References

Carter, D., Herschlag, G., Hunter, Z., and Mattingly, J. (2019). A merge-split proposal for reversible Monte Carlo Markov chain sampling of redistricting plans. arXiv preprint arXiv:1911.01503.

McCartan, C., & Imai, K. (2023). Sequential Monte Carlo for Sampling Balanced and Compact Redistricting Plans. Annals of Applied Statistics 17(4). Available at doi:10.1214/23-AOAS1763.

DeFord, D., Duchin, M., and Solomon, J. (2019). Recombination: A family of Markov chains for redistricting. arXiv preprint arXiv:1911.05725.

Examples

data(fl25)

fl_map <- redist_map(fl25, ndists = 3, pop_tol = 0.1)

sampled_basic <- redist_mergesplit(fl_map, 10000)

sampled_constr <- redist_mergesplit(fl_map, 10000, constraints = list(
    incumbency = list(strength = 1000, incumbents = c(3, 6, 25))
))

Description

redist_mergesplit_parallel() runs redist_mergesplit() on several chains in parallel.

Usage

redist_mergesplit_parallel(
  map,
  nsims,
  chains = 1,
  warmup = if (is.null(init_plan)) 10 else max(100, nsims%/%5),
  thin = 1L,
  init_plan = NULL,
  counties = NULL,
  compactness = 1,
  constraints = list(),
  constraint_fn = function(m) rep(0, ncol(m)),
  adapt_k_thresh = 0.99,
  k = NULL,
  ncores = NULL,
  cl_type = "PSOCK",
  return_all = TRUE,
  init_name = NULL,
  silly_adj_fix = FALSE,
  verbose = FALSE,
  silent = FALSE
)

Arguments

Details

This function draws samples from a specific target measure, controlled by the map, compactness, and constraints parameters.

Key to ensuring good performance is monitoring the acceptance rate, which is reported at the sample level in the output. Users should also check diagnostics of the sample by running summary.redist_plans().

Higher values of compactness sample more compact districts; setting this parameter to 1 is computationally efficient and generates nicely compact districts.

Value

A redist_plans object with all of the simulated plans, and an additional chain column indicating the chain the plan was drawn from.

References

Carter, D., Herschlag, G., Hunter, Z., and Mattingly, J. (2019). A merge-split proposal for reversible Monte Carlo Markov chain sampling of redistricting plans. arXiv preprint arXiv:1911.01503.

McCartan, C., & Imai, K. (2023). Sequential Monte Carlo for Sampling Balanced and Compact Redistricting Plans. Annals of Applied Statistics 17(4). Available at doi:10.1214/23-AOAS1763.

DeFord, D., Duchin, M., and Solomon, J. (2019). Recombination: A family of Markov chains for redistricting. arXiv preprint arXiv:1911.05725.

Examples

## Not run: 
data(fl25)
fl_map <- redist_map(fl25, ndists = 3, pop_tol = 0.1)
sampled <- redist_mergesplit_parallel(fl_map, nsims = 100, chains = 100)

## End(Not run)

Description

A redist_plans object is essentially a data frame of summary information on each district and each plan, along with the matrix of district assignments and information about the simulation process used to generate the plans.

Usage

redist_plans(plans, map, algorithm, wgt = NULL, ...)

Arguments

Details

The first two columns of the data frame will be draw, a factor indexing the simulation draw, and district, an integer indexing the districts within a plan. The data frame will therefore have n_sims*ndists rows. As a data frame, the usual dplyr methods will work.

Other useful methods for redist_plans objects:

• summary.redist_plans

• add_reference

• subset_sampled

• subset_ref

• pullback

• number_by

• match_numbers

• is_county_split

• prec_assignment

• plan_distances

• get_plans_matrix

• get_plans_weights

• get_sampling_info

• as.matrix.redist_plans

• plot.redist_plans

Value

a new redist_plans object.

Examples

data(iowa)

iowa <- redist_map(iowa, existing_plan = cd_2010, pop_tol = 0.05, total_pop = pop)
rsg_plan <- redist.rsg(iowa$adj, iowa$pop, ndists = 4, pop_tol = 0.05)$plan
redist_plans(rsg_plan, iowa, "rsg")

Description

Defined as pmin(x, quantile(x, 1 - length(x)^(-0.5)))

Usage

redist_quantile_trunc(x)

Arguments

Value

numeric vector

Examples

redist_quantile_trunc(c(1, 2, 3, 4))

Description

This function uses redist_mergesplit() or redist_flip() to optimize a redistrict plan according to a user-provided criteria. It does so by running the Markov chain for "short bursts" of usually 10 iterations, and then starting the chain anew from the best plan in the burst, according to the criteria. This implements the ideas in the below-referenced paper, "Voting Rights, Markov Chains, and Optimization by Short Bursts."

Usage

redist_shortburst(
  map,
  score_fn = NULL,
  stop_at = NULL,
  burst_size = ifelse(backend == "mergesplit", 10L, 50L),
  max_bursts = 500L,
  maximize = TRUE,
  init_plan = NULL,
  counties = NULL,
  constraints = redist_constr(map),
  compactness = 1,
  adapt_k_thresh = 0.95,
  reversible = TRUE,
  fixed_k = NULL,
  return_all = TRUE,
  thin = 1L,
  backend = "mergesplit",
  flip_lambda = 0,
  flip_eprob = 0.05,
  verbose = TRUE
)

Arguments

Value

a redist_plans object containing the final best plan (or the best plans after each burst, if return_all=TRUE.

References

Cannon, S., Goldbloom-Helzner, A., Gupta, V., Matthews, J. N., & Suwal, B. (2020). Voting Rights, Markov Chains, and Optimization by Short Bursts. arXiv preprint arXiv:2011.02288.

Examples

data(iowa)

iowa_map <- redist_map(iowa, existing_plan = cd_2010, pop_tol = 0.01)
redist_shortburst(iowa_map, scorer_frac_kept(iowa_map), max_bursts = 50)
redist_shortburst(iowa_map, ~ 1 - scorer_frac_kept(iowa_map)(.), max_bursts = 50)

Description

redist_smc uses a Sequential Monte Carlo algorithm (McCartan and Imai 2023) to generate representative samples of congressional or legislative redistricting plans according to contiguity, population, compactness, and administrative boundary constraints.

Usage

redist_smc(
  map,
  nsims,
  counties = NULL,
  compactness = 1,
  constraints = list(),
  resample = TRUE,
  runs = 1L,
  ncores = 0L,
  init_particles = NULL,
  n_steps = NULL,
  adapt_k_thresh = 0.99,
  seq_alpha = 0.5,
  truncate = (compactness != 1),
  trunc_fn = redist_quantile_trunc,
  pop_temper = 0,
  final_infl = 1,
  ref_name = NULL,
  verbose = FALSE,
  silent = FALSE
)

Arguments

Details

This function draws samples from a specific target measure controlled by the map, compactness, and constraints parameters.

Key to ensuring good performance is monitoring the efficiency of the resampling process at each SMC stage. Unless silent=FALSE, this function will print out the effective sample size of each resampling step to allow the user to monitor the efficiency. If verbose=TRUE the function will also print out information on the $k_i$ values automatically chosen and the acceptance rate (based on the population constraint) at each step. Users should also check diagnostics of the sample by running summary.redist_plans().

Higher values of compactness sample more compact districts; setting this parameter to 1 is computationally efficient and generates nicely compact districts. Values of other than 1 may lead to highly variable importance sampling weights. In these cases, these weights are by default truncated using redist_quantile_trunc() to stabilize the resulting estimates, but if truncation is used, a specific truncation function should probably be chosen by the user.

Value

redist_smc returns a redist_plans object containing the simulated plans.

References

McCartan, C., & Imai, K. (2023). Sequential Monte Carlo for Sampling Balanced and Compact Redistricting Plans. Annals of Applied Statistics 17(4). Available at doi:10.1214/23-AOAS1763.

Examples

data(fl25)

fl_map <- redist_map(fl25, ndists = 3, pop_tol = 0.1)

sampled_basic <- redist_smc(fl_map, 5000)

constr <- redist_constr(fl_map)
constr <- add_constr_incumbency(constr, strength = 100, incumbents = c(3, 6, 25))
sampled_constr <- redist_smc(fl_map, 5000, constraints = constr)

# Multiple parallel independent runs
redist_smc(fl_map, 1000, runs = 2)

# One run with multiple cores
redist_smc(fl_map, 1000, ncores = 2)

Description

Creates an adjacency list that is zero indexed with no skips

Usage

redist.adjacency(shp, plan)

Arguments

Value

Adjacency list

Description

Calculate Frontier Size

Usage

redist.calc.frontier.size(ordered_path)

Arguments

Value

List, four objects

• max numeric, maximum frontier size

• average numeric, average frontier size

• average_sq numeric, average((frontier size)^2)

• sequence numeric vector, lists out all sizes for every frontier

Examples

## Not run: 
data(fl25)
adj <- redist.adjacency(fl25)
redist.prep.enumpart(adj, "unordered", "ordered")
redist.calc.frontier.size("ordered")

## End(Not run)

Description

Coarsen Adjacency List

Usage

redist.coarsen.adjacency(adj, groups)

Arguments

Value

adjacency list coarsened

Description

redist.combine.mpi is used to combine successive runs of redist.mcmc.mpi into a single data object

Usage

redist.combine.mpi(savename, nloop, nthin, tempadj)

Arguments

Details

This function allows users to combine multiple successive runs of redist.mcmc.mpi into a single redist object for analysis.

Value

redist.combine.mpi returns an object of class "redist". The object redist is a list that contains the following components (the inclusion of some components is dependent on whether tempering techniques are used):

References

Fifield, Benjamin, Michael Higgins, Kosuke Imai and Alexander Tarr. (2016) "A New Automated Redistricting Simulator Using Markov Chain Monte Carlo." Working Paper. Available at http://imai.princeton.edu/research/files/redist.pdf.

Examples

## Not run: 
# Cannot run on machines without Rmpi
data(fl25)
data(fl25_enum)
data(fl25_adj)

## Code to run the simulations in Figure 4 in Fifield, Higgins, Imai and
## Tarr (2015)

## Get an initial partition
init_plan <- fl25_enum$plans[, 5118]

## Run the algorithm
redist.mcmc.mpi(adj = fl25_adj, total_pop = fl25$pop,
    init_plan = init_plan, nsims = 10000, nloops = 2, savename = "test")
out <- redist.combine.mpi(savename = "test", nloop = 2,
    nthin = 10, tempadj = tempAdjMat)

## End(Not run)

Description

Create Constraints for SMC

Usage

redist.constraint.helper(
  constraints = "vra",
  tgt_min = 0.55,
  group_pop,
  total_pop,
  ndists,
  nmmd,
  strength_vra = 2500,
  pow_vra = 1.5
)

Arguments

Value

list of lists for each constraint selected

Description

Create County IDs

Usage

redist.county.id(counties)

Arguments

Value

A vector with an ID that corresponds from 1:n counties

Examples

set.seed(2)
counties <- sample(c(rep("a", 20), rep("b", 5)))
redist.county.id(counties)

Description

Relabel Discontinuous Counties

Usage

redist.county.relabel(adj, counties, simplify = TRUE)

Arguments

Value

character vector of county names

Examples

set.seed(2)
data(fl25)
data(fl25_adj)
counties <- sample(c(rep("a", 20), rep("b", 5)))
redist.county.relabel(fl25_adj, counties)

Description

redist.crsg generates redistricting plans using a random seed a grow algorithm. This is the compact districting algorithm described in Chen and Rodden (2013).

Usage

redist.crsg(
  adj,
  total_pop,
  shp,
  ndists,
  pop_tol,
  verbose = TRUE,
  maxiter = 5000
)

Arguments

Value

list, containing three objects containing the completed redistricting plan.

• plan: A vector of length N, indicating the district membership of each precinct.

• district_list A list of length Ndistrict. Each list contains a vector of the precincts in the respective district.

• district_pop A vector of length Ndistrict, containing the population totals of the respective districts.

References

Jowei Chen and Jonathan Rodden (2013) “Unintentional Gerrymandering: Political Geography and Electoral Bias in Legislatures.” Quarterly Journal of Political Science. 8(3): 239-269.

Examples

data("fl25")
adj <- redist.adjacency(fl25)
redist.crsg(adj = adj, total_pop = fl25$pop, shp = fl25, ndists = 2, pop_tol = .1)

Description

redist.diagplot generates several common MCMC diagnostic plots.

Usage

redist.diagplot(sumstat,
plot = c("trace", "autocorr", "densplot", "mean", "gelmanrubin"),
logit = FALSE, savename = NULL)

Arguments

Details

This function allows users to generate several standard diagnostic plots from the MCMC literature, as implemented by Plummer et. al (2006). Diagnostic plots implemented include trace plots, autocorrelation plots, density plots, running means, and Gelman-Rubin convergence diagnostics (Gelman & Rubin 1992).

Value

Returns a plot of file type .pdf.

References

Fifield, Benjamin, Michael Higgins, Kosuke Imai and Alexander Tarr. (2016) "A New Automated Redistricting Simulator Using Markov Chain Monte Carlo." Working Paper. Available at http://imai.princeton.edu/research/files/redist.pdf.

Gelman, Andrew and Donald Rubin. (1992) "Inference from iterative simulations using multiple sequences (with discussion)." Statistical Science.

Plummer, Martin, Nicky Best, Kate Cowles and Karen Vines. (2006) "CODA: Convergence Diagnosis and Output Analysis for MCMC." R News.

Examples

data(fl25)
data(fl25_enum)
data(fl25_adj)

## Get an initial partition
init_plan <- fl25_enum$plans[, 5118]
fl25$init_plan <- init_plan

## 25 precinct, three districts - no pop constraint ##
fl_map <- redist_map(fl25, existing_plan = 'init_plan', adj = fl25_adj)
alg_253 <- redist_flip(fl_map, nsims = 10000)

## Get Republican Dissimilarity Index from simulations
rep_dmi_253 <- redistmetrics::seg_dissim(alg_253, fl25, mccain, pop) |>
    redistmetrics::by_plan(ndists = 3)

## Generate diagnostic plots
redist.diagplot(rep_dmi_253, plot = "trace")
redist.diagplot(rep_dmi_253, plot = "autocorr")
redist.diagplot(rep_dmi_253, plot = "densplot")
redist.diagplot(rep_dmi_253, plot = "mean")

## Gelman Rubin needs two chains, so we run a second
alg_253_2 <- redist_flip(fl_map, nsims = 10000)

rep_dmi_253_2 <- redistmetrics::seg_dissim(alg_253_2, fl25, mccain, pop) |>
    redistmetrics::by_plan(ndists = 3)

## Make a list out of the objects:
rep_dmi_253_list <- list(rep_dmi_253, rep_dmi_253_2)

## Generate Gelman Rubin diagnostic plot
redist.diagplot(sumstat = rep_dmi_253_list, plot = "gelmanrubin")

Description

This implements Crespin's 2005 measure of district continuity, as applied to the geographies represented by a plan, typically precincts or voting districts. This implementation assumes none of the precincts in plan_old or plan_new are split.

Usage

redist.dist.pop.overlap(plan_old, plan_new, total_pop, normalize_rows = TRUE)

Arguments

Value

matrix with length(unique(plan_old)) rows and length(unique(plan_new)) columns

References

"Using Geographic Information Systems to Measure District Change, 2000-02", Michael Crespin, Political Analysis (2005) 13(3): 253-260

Examples

set.seed(5)
data(iowa)
iowa_map <- redist_map(iowa, total_pop = pop, pop_tol = 0.01, ndists = 4)
plans <- redist_smc(iowa_map, 2)
plans_mat <- get_plans_matrix(plans)
ov <- redist.dist.pop.overlap(plans_mat[, 1], plans_mat[, 2], iowa_map)
round(ov, 2)

ov_col <- redist.dist.pop.overlap(plans_mat[, 1], plans_mat[, 2], iowa_map, normalize_rows = FALSE)
round(ov_col, 2)

ov_un_norm <- redist.dist.pop.overlap(plans_mat[, 1], plans_mat[, 2],
    iowa_map, normalize_rows = NULL)
round(ov_un_norm, 2)

iowa_map_5 <- iowa_map <- redist_map(iowa, total_pop = pop, pop_tol = 0.01, ndists = 5)
plan_5 <- get_plans_matrix(redist_smc(iowa_map_5, 1))
ov4_5 <- redist.dist.pop.overlap(plans_mat[, 1], plan_5, iowa_map)
round(ov4_5, 2)

Description

Counts the total number of counties that are found within a district. This does not subtract out the number of counties that are found completely within a district.

Usage

redist.district.splits(plans, counties)

Arguments

Value

integer matrix where each district is a

Examples

data(iowa)
ia <- redist_map(iowa, existing_plan = cd_2010, total_pop = pop, pop_tol = 0.01)
plans <- redist_smc(ia, 50, silent = TRUE)
#old redist.district.splits(plans, ia$region)
splits_count(plans, ia, region)

Description

Single function for standard enumeration analysis, using ZDD methodology (Fifield, Imai, Kawahara, and Kenny 2020).

Usage

redist.enumpart(
  adj,
  unordered_path,
  ordered_path,
  out_path,
  ndists = 2,
  all = TRUE,
  n = NULL,
  weight_path = NULL,
  lower = NULL,
  upper = NULL,
  init = FALSE,
  read = TRUE,
  total_pop = NULL
)

Arguments

Value

List with entries district_membership and parity.

References

Fifield, B., Imai, K., Kawahara, J., & Kenny, C. T. (2020). The essential role of empirical validation in legislative redistricting simulation. Statistics and Public Policy, 7(1), 52-68.

Description

Given a percent goal for majority minority districts, this computes the average value of minority in non-majority minority districts. This value is "tgt_other" in redist_flip and redist_smc.

Usage

redist.find.target(tgt_min, group_pop, total_pop, ndists, nmmd)

Arguments

Value

numeric value to target

Description

redist.findparams is used to find optimal parameter values of redist_flip for a given map.

Usage

redist.findparams(
  map,
  nsims,
  init_plan = NULL,
  adapt_lambda = FALSE,
  adapt_eprob = FALSE,
  params,
  ssdmat = NULL,
  group_pop = NULL,
  counties = NULL,
  nstartval_store = 1,
  maxdist_startval = 100,
  maxiterrsg = 5000,
  report_all = TRUE,
  parallel = FALSE,
  ncores = NULL,
  log = FALSE,
  verbose = TRUE
)

Arguments

Details

This function allows users to test multiple parameter settings of redist_flip in preparation for a longer run for analysis.

Value

redist.findparams returns a print-out of summary statistics about each parameter setting.

References

Fifield, Benjamin, Michael Higgins, Kosuke Imai and Alexander Tarr. (2016) "A New Automated Redistricting Simulator Using Markov Chain Monte Carlo." Working Paper. Available at http://imai.princeton.edu/research/files/redist.pdf.

Examples

data(fl25)
data(fl25_enum)
data(fl25_adj)

## Get an initial partition
init_plan <- fl25_enum$plans[, 5118]

params <- expand.grid(eprob = c(.01, .05, .1))

# Make map
map_fl <- redist_map(fl25, ndists = 3, pop_tol = 0.2)
## Run the algorithm
redist.findparams(map_fl,
    init_plan = init_plan, nsims = 10000, params = params)