R/redist_flip_tidy.R
redist_flip.Rd
redist_flip
provides a tidy interface to the methods in
redist.flip
.
redist_flip( map, nsims, warmup = 0, init_plan, pop_tol, constraints = list(), nthin = 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 )
map  A 

nsims  The number of samples to draw, not including warmup. 
warmup  The number of warmup samples to discard. 
init_plan  A vector containing the congressional district labels
of each geographic unit. The default is 
pop_tol  The strength of the hard population
constraint. 
constraints  a list of constraints to implement. Can be created with

nthin  The amount by which to thin the Markov Chain. The
default is 
eprob  The probability of keeping an edge connected. The
default is 
lambda  lambda The parameter determining the number of swaps to attempt
each iteration of the algorithm. The number of swaps each iteration is
equal to Pois( 
temper  Whether to use simulated tempering algorithm. Default is FALSE. 
betaseq  Sequence of beta values for tempering. The default is

betaseqlength  Length of beta sequence desired for
tempering. The default is 
betaweights  betaweights Sequence of weights for different values of
beta. Allows the user to upweight certain values of beta over
others. The default is 
adapt_lambda  adapt_lambda Whether to adaptively tune the lambda parameter so that the MetropolisHastings acceptance probability falls between 20% and 40%. Default is FALSE. 
adapt_eprob  eprob Whether to adaptively tune the edgecut probability parameter so that the MetropolisHastings acceptance probability falls between 20% and 40%. Default is FALSE. 
exact_mh  Whether to use the approximate (FALSE) or exact (TRUE) MetropolisHastings ratio calculation for acceptreject rule. Default is FALSE. 
adjswaps  Flag to restrict swaps of beta so that only
values adjacent to current constraint are proposed. The default is

init_name  a name for the initial plan, or 
verbose  Whether to print initialization statement. Default is 
A redist_plans
object containing the simulated plans.
This function allows users to simulate redistricting plans using the Markov Chain Monte Carlo methods of Fifield et al. Several constraints corresponding to substantive requirements in the redistricting process are implemented, including population parity and geographic compactness. In addition, the function includes multipleswap and simulated tempering functionality to improve the mixing of the Markov Chain.
redist_flip
allows for Gibbs constraints to be supplied via a list object
passed to constraints
. This is a change from the original redist.flip
behavior to allow for a more straightforward function call when used within a pipe.
A key difference between redist_flip
and redist.flip
is that
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 noncompact 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 edgesremoved
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
. We recommend setting up the constraints for
redist_flip
with flip_constraints_helper
to ensure that
you are supplying the exact information needed. As a quick shorthand, if you
want to run a simulation with no constraints at all, you can use
flip_constraints_helper(map = map, constraint = NULL)
and pass this to
constraints
. The following describes the constraints available. The general
advice is to set weights in a way that gets between 20\
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 subtypes 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 edgesremoved
(the default),
polsbypopper
, fryerholden
, or logst
. Using Polsby Popper
is generally not recommended, as edgesremoved
is faster and highly correlated.
logst
can be used to match the target distribution of redist_smc
or
redist_mergesplit
.
areas  Only used with polsbypopper
 A vector of precinct areas.
borderlength_mat  Only used with polsbypopper
 A matrix of precinct
border lengths.
ssdmat  Only used with fryerholden
 A matrix of squared distances between
precinct centroids.
ssd_denom  Only used with fryerholden
 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.pcttarget.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 statusquo 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 proportionalrepresentation
or efficiencygap
.
segregation
This constraint attempts to minimize the degree of dissimilarity
between districts by group population.
weight  the coefficient to put on the Gibbs constraint
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.
data(iowa) iowa_map < redist_map(iowa, ndists = 4, existing_plan = cd_2010, total_pop = pop, pop_tol = 0.01) sims < redist_flip(map = iowa_map, nsims = 100)#> #> ==================== #> redist.flip(): Automated Redistricting Simulation Using #> Markov Chain Monte Carlo #> #> Preprocessing data. #> #> Starting swMH(). #> 10 percent done. #> Metropolis acceptance ratio: 0.777778 #> #> 20 percent done. #> Metropolis acceptance ratio: 0.842105 #> #> 30 percent done. #> Metropolis acceptance ratio: 0.758621 #> #> 40 percent done. #> Metropolis acceptance ratio: 0.769231 #> #> 50 percent done. #> Metropolis acceptance ratio: 0.734694 #> #> 60 percent done. #> Metropolis acceptance ratio: 0.644068 #> #> 70 percent done. #> Metropolis acceptance ratio: 0.57971 #> #> 80 percent done. #> Metropolis acceptance ratio: 0.544304 #> #> 90 percent done. #> Metropolis acceptance ratio: 0.52809 #> #> 100 percent done. #> Metropolis acceptance ratio: 0.525253 #>