Mosaic
What Mosaic does
Load a polygon shapefile, choose the district count, and set your scoring priorities. Mosaic searches for plans with lower weighted scores. Pause to inspect a plan, return to the best found, or export the map on screen.
Basic workflow
Load your data
Open a polygon shapefile and identify the population, precinct ID, county, election, and demographic columns that are available. See the shapefile guide for file requirements.
Set the basic limits
Choose the number of districts, the population tolerance, and the maximum number of iterations.
Choose your priorities
Enable the scores you want Mosaic to consider and set their weights. Only use priorities supported by the data you loaded.
Run and inspect
Start the search, watch the map and charts, and pause when you want a closer look.
Save the map you want
Export the assignment, district information, or a map image. Exports use the plan currently shown on the map.
Set up a run
Import Shapefile from File opens Shapefile Setup. Choose the required Population and Precinct ID columns; County, Elections, and Demographics are optional. + Add Election pairs DEM and GOP columns. Then choose Confirm and Load.
| Setting | What it changes | Practical guidance |
|---|---|---|
| Districts | The number of districts in the plan. | Use the size of the chamber or map you are drawing. |
| Population Tolerance | The largest allowed difference from the ideal district population. | Choose percent or people; both control the same limit. The people slider moves in rounded steps. Smaller tolerances make valid moves harder to find. |
| Iterations | The maximum number of search steps in the run. | More iterations give Mosaic more opportunities to improve the plan, but take longer. |
Settings are checked when the run starts
If Mosaic cannot start, read the status message first. It usually identifies a missing column, an invalid district count, a population constraint that cannot be met, or an incompatible starting map.
Choose what to optimize
A score tells Mosaic what kind of plan to favor. Enabling a score adds it to the search objective; its weight controls how strongly it competes with the other enabled scores.
Scores do not all use the same scale or direction. Some panels show ratings, some show penalties, and some show measurements in their natural units. Read the label on the score or chart rather than assuming that every high or low number means the same thing.
Geography and population
Compactness
Favors districts that are less stretched or irregular. Mosaic combines two complementary shape measures.
Polsby-Popper and Reock
Expose the two shape measures separately when you want direct control instead of the combined Compactness score.
Cut Edges
Counts neighboring precinct pairs placed in different districts. Fewer cut edges generally means simpler boundaries.
County Congruence
Favors plans that keep counties together and avoid severe county splits.
Classic Splitting
Provides a count-based alternative for limiting county splits and rewarding districts contained within one county.
Population Deviation
Favors district populations closer to the ideal, beyond the hard population limit used to reject invalid moves.
Alignment
Favors plans that preserve districts from a reference assignment. Load a reference plan before enabling it.
Election-based priorities
These options require Democratic and Republican vote columns.
Mean-Median, Efficiency Gap, Partisan Bias, and Partisan Gini
Measure different forms of partisan asymmetry. Directional controls are available where Mosaic can favor fairness or a selected party.
Proportionality
Compares the balance of seats with the balance of votes and accounts for the risk that the statewide vote winner loses control.
Competitiveness
Favors districts with less certain election outcomes.
Expected Dem Seats
Moves the expected Democratic seat count up or down, depending on the selected direction.
Chance of Majority
Favors a higher chance that the selected party wins a majority of districts.
Supermajority/Hinge
Favors a higher chance that the selected party reaches a seat threshold you choose.
Demographic priorities
These options require a demographic total and at least one compatible group-population column.
Electoral Opportunity
Uses selected demographic shares as a planning proxy for electoral opportunity.
Neighborhood Severance
Discourages boundaries that cut through areas where a demographic group is concentrated.
Community Dispersion
Discourages dividing concentrated communities among more districts than their population requires.
For exact definitions, scales, and formulas, see the score methodology.
Run and inspect
Run controls
| Start | Begins a new run using the current data and settings. |
| Pause / Resume | Stops after a clean iteration boundary. The same button changes to Resume so you can continue the existing run. |
| Revert to Best | Returns the map and run state to the best-scoring accepted plan found so far. History after that point is discarded. |
| Reset | Clears the current run while keeping the loaded shapefile and configuration. If Relight is active, Reset also clears it and restores the settings it replaced. |
Read the map
- Scroll over the map to zoom, drag to pan, and double-click to return to the full state.
- Resizing the window preserves the map’s center and zoom. Extra width expands the map; extra height goes to the scores area.
- Use the controls below the map to change the coloring and add county lines, precinct lines, or labels.
- Coloring modes replace one another. Line and label overlays can be placed on top.
- Map-image exports always show the full state, regardless of the current zoom.
Scores and Views are different
Scores
Controls which priorities appear in the score area and can influence the search. Hiding a score also turns it off; showing it again does not automatically re-enable it.
Views
Controls which charts and information panels are visible. Showing a view does not automatically add that metric to the objective.
Map fills, overlays, and status
The Fill menu offers None (District), election Results - Precinct and Results - District, Demographics - Precinct and Demographics - District, Compactness, and Population Deviation. Results use Democratic two-party share; Demographics use the largest selected group and its share. Compactness runs from less-compact red/orange toward more-compact green. Population Deviation uses blue below ideal and red above it. County, Precinct, Labels, and Splits are additive overlays; Splits highlights counties divided among districts.
Score is the current weighted total and Best is the lowest accepted total so far. Entropy in the status box is the run-wide share of higher-scoring proposals accepted; the Entropy chart shows the rolling rate. Accepted steps counts accepted proposals, while Flip rate is the current chance of trying a boundary flip. Iter/sec and Est. left report speed and estimated time remaining.
Temperature, Partisanship, Win Chance, Score Contributors, District Info, and Comet Plot
Temperature charts annealing temperature. Partisanship shows loaded two-party district results; Win Chance shows modeled Democratic win probabilities. Score Contributors shows each enabled metric's share of the current weighted total. District Info is a per-district table; Update every (iters) changes only its refresh rate.
Comet Plot traces two selected measures against each other. Smooth averages nearby plotted points, Fit all shows the full trail, and Fade makes older points less prominent. These controls change only the chart.
Score presets
Use Configuration → Save Preset... to save scoring choices as TOML. Apply Preset... or Apply Recent Preset restores them. The default folder is presets/ beside the launcher.
Presets include score switches, weights, score options, and county bias. They exclude the map, column selections, reference assignment, district count, population tolerance, and run controls. Applying a preset turns Hinge off because its seat threshold depends on the map.
Applying and editing presets
Disabled scores retain their saved weights. Scores requiring missing data stay off, and a message identifies the missing inputs. Review those choices after loading the required data. Safe Harbor is capped at the current population tolerance.
Known numeric settings must be finite, in range, and integral where required. Invalid settings reject the preset before controls change. Missing settings use startup defaults; unknown keys are ignored with a warning. TOML proportions use fractions, such as 0.05 for 5%.
Clear All Scores turns every score off and restores its startup control values. It does not restore the usual set of enabled scores or change row visibility. Presets are scoring recipes, not full run checkpoints.
Save and export
Exports use the plan currently shown on the map. If you want the best plan found during the run, choose Revert to Best before exporting.
Quick Save / Save Assignments
Writes an Assignments CSV with one row per source feature and its district number. Quick Save uses a timestamped name in the output folder; File → Save Assignments lets you choose a name and location.
Save Metrics / Save District Info
Writes a District Info CSV with one row per district and the available district-level measures. Save Metrics uses a timestamped name in the output folder.
Quick PNG / Save Map Image...
Saves the full map using the current fill, overlays, and labels. Save Map Image offers an optional title, PNG resolution, vector PDF, and Save As.
Open output directory... opens the automatic-save folder. New unloads the current shapefile; unlike Reset, it returns Mosaic to its no-file state. Saving assignments marks the current plan as saved; exporting metrics or a photo does not. Open Recent reuses the column choices remembered for that file. Check for updates... checks for a newer release.
District Info CSV fields and units
Population differences are signed relative to ideal: positive means overpopulated. The absolute-percent column removes the sign. District numbers start at 1; precinct counts count source features.
County fields count counties touched and counties wholly contained in each district. Election fields use the first configured DEM/GOP pair. Total votes means DEM + GOP; shares are percentages, and dem_margin is Democratic share minus 50 percentage points. A district with no two-party votes receives 50% for each share. win_prob is a modeled probability from 0 to 1.
Area and perimeter use the shapefile’s coordinate units, squared for area. Geographic coordinates therefore produce square degrees and degrees; Mosaic does not reproject them for export. Polsby–Popper and Reock are ratios. Holistic compactness is the clipped combined rating from 0 to 1.
Demographic totals and group shares use the selected demographic universe, which may differ from general population. Only selected groups are exported. Group opportunity is normalized election-opportunity credit from 0 to 1, not a probability. Fields requiring unavailable inputs are omitted. A calculation or write error fails the export and preserves any existing destination file.
Troubleshooting
Mosaic will not load my shapefile
Check the message in the application, then use the shapefile troubleshooting guide. Common problems include unsupported geometry, a missing population column, invalid values, or disconnected geography that Mosaic cannot repair automatically.
A score is unavailable
Election scores require election columns. Demographic scores require a demographic total and compatible group columns. Alignment requires a reference assignment. Reload the data and select the missing fields. A demographic score can also be not applicable when there is no qualifying community or opportunity to measure; that is a normal result.
The run will not start
Read the status message. Check the district count, population tolerance, enabled score requirements, and any loaded starting map. A very strict population tolerance can make a valid starting plan difficult or impossible to construct.
My map includes islands or disconnected pieces
Mosaic normally adds internal connections so the search can reach islands and exclaves. These connections do not alter the shapefile. If Mosaic still reports disconnected geometry, inspect the source data for invalid or degenerate shapes.
The first run is slow to begin
Some of Mosaic's fast numerical routines are compiled when first used. Later iterations and later runs are usually faster.
The interface feels slow during a run
In the Appearance menu, increase the Map Render Interval so the map redraws less often. Limit Plots can also reduce the amount of chart data drawn at one time.
Mosaic crashed
Look in the crashes folder for the newest log file. Keep that file with the shapefile and the steps that led to the crash; it contains the error and basic information about the run.
Advanced settings
Ensemble
Advanced → Ensemble... repeats runs with the loaded map and settings. It is available when the search is idle and Relight is off. Count sets the number of runs; Duration finishes the current run when time expires; Unlimited continues until stopped.
Each run saves its final map, or its lowest-scoring map with Keep best map enabled. Force Stop discards the unfinished run and keeps completed results.
Histograms, Scatterplot, and Roster compare completed runs; Map displays a selected plan. Open Folder opens the saved assignments, metrics, and settings.
Fast tree generation
Uses Mosaic's faster method for building the randomized trees behind most ReCom moves. It is on by default.
Turning it off uses the slower reference method. Both follow the same basic move procedure, but they randomize trees differently, so changing this setting changes the path of the search—even with the same seed.
n=3 ReCom Mix and Polish Flips
% of iterations sets the conditional chance of trying n=3 after no flip is selected. These moves take more work but can reach plans that ordinary two-district ReCom misses.
Enable single-precinct flips adds small, contiguous boundary adjustments. Flips are rare early and more common late. The 50% crossover (% of run) chooses when flips reach half of proposal attempts.
Enable simulated annealing, cooling, and Launch Watch
Enable simulated annealing lets Mosaic sometimes accept a worse-scoring plan so it can move out of local dead ends. Turning it off accepts every valid proposal.
Initial Temp Factor controls how permissive the run is at the start. Guided (recommended) calculates a schedule that reaches Target Temp at Guide Point. Static applies the selected Cooling Rate / iteration after each step.
Launch Watch can recalculate the Guided schedule once, using the score at that point instead of the original starting score. Re-anchor after iter chooses how long Mosaic waits before doing so.
Population Ratchet and Safe Harbor
Tolerance Ratchet can tighten the allowed population difference as the run progresses. Standard considers tightening when Mosaic finds a new best plan; Strict considers it at every eligible step. Neither mode loosens the limit or tightens beyond what the current map can satisfy.
Safe Harbor sets a band around the ideal population where the Population Deviation score adds no penalty. It does not replace the hard Population Tolerance.
County-Edge Bias
Changes which proposed boundaries Mosaic is more likely to try by favoring cuts along county borders. It is a move preference, not a weighted score. County Congruence instead evaluates the resulting plan.
Clipped and unclipped scorecards
Unclipped Compactness, Unclipped County Congruence, Unclipped Competitiveness, Unclipped Proportionality, and Unclipped Electoral Opportunity select alternate score shapes.
Clipped forms stop changing after a defined threshold. The default Unclipped forms keep giving the search useful distinctions beyond that threshold, although each does so differently. These settings change the optimizer penalty, not merely the chart. See the score methodology for the exact form.
Partisanship Settings
Win Prob at 55% vote share controls how confidently Mosaic treats a district with 55% of the two-party vote as won. Swing sigma (shared) controls the size of the statewide electoral swing shared across districts.
Efficiency Gap mode chooses between Robust (recommended) and Static. Use quadratic penalty, MM bound, EG bound, and Partisan Bias bound change how signed statistics become optimizer penalties; they do not change the raw charted statistics.
Electoral Opportunity settings
Smart Targets uses nearby precincts to build a geographic reference for each group. Turning it off uses a statewide group-share ranking that can combine distant places.
Midpoint is the group share assigned a 50% opportunity value. Steepness controls how gradually that value rises. Solid level is the reference share for full district credit.
The chart offers Overall penalty, per-group Rating, and modeled Opportunity count. Smart Targets is a heuristic reference, not proof that a valid district can be drawn. The technical description explains its limits.
Alignment Settings
Load reference plan... supplies the comparison assignment; it does not start the search from that plan. Focus chooses All residents, Republican, or Democratic as the overlap weight.
Only districts that party wins limits the comparison to reference districts above the selected District win threshold.
Random Seed
A nonzero seed is one requirement for replaying a run; it is not enough by itself. For the strongest repeatability, also turn off Fast tree generation, reuse the same Hot Start, and keep the data, settings, Mosaic version, and computing environment unchanged. Exact results are not guaranteed across machines or releases.
Load Hot Start, Clear Hot Start, and Relight
Load Hot Start... loads a saved Assignments CSV as the starting map. It needs matching Precinct ID and District columns, 1-based district numbers, and the same district count as the current Districts setting. Clear Hot Start returns to an automatically generated start.
Relight starts another run from the map currently on screen and temporarily applies a polishing preset. Clear Relight restores the settings it replaced.
Renumber districts after run and Renumber options
Renumber districts after run changes labels without changing boundaries, colors, or scores and is on by default. Renumber options... offers By proximity, Northwest to Southeast, North to South, None, or—when a reference plan is loaded—Infer from alignment.
Appearance and drawing speed
Map Render Interval controls how often the map redraws while a run is active. A longer interval can make the interface more responsive without changing the search.
Limit plots to last 10,000 iterations changes what is drawn, not what Mosaic calculates.
How Mosaic searches
Mosaic searches for plans that score well under the priorities you choose. Its main move joins neighboring districts, builds a randomized tree of connections within the combined area, and splits that tree into new contiguous districts that meet the population limit. Optional three-district moves and small boundary flips give the search other ways to change a plan.
With annealing enabled, Mosaic always accepts a plan that does not worsen the total score. Early in a run it may also accept a worse-scoring plan, which helps it move out of local dead ends. As the run cools, it becomes more selective. Mosaic records the best plan it finds during the run.
Mosaic's recombination approach belongs to the family of methods developed by the MGGG Redistricting Lab. Mosaic has its own implementation built for interactive optimization.