Mosaic
Prepare a shapefile
Mosaic can use any polygon shapefile that has a population count and a stable ID for each map unit. Election, county, and demographic data are optional.
Start with the complete file
A shapefile is a group of files, not only the file ending in
.shp. Keep its matching .shp, .shx,
.dbf, and .prj files together with the same base
name. Select the .shp file in Mosaic.
Mosaic-ready files
The Mosaic shapefile collection contains prepared state files and documents each file's fields, data choices, and license. Mosaic also includes a small North Carolina sample for trying the program.
Files from anywhere else are fine. Mosaic cares about their geometry and columns, not who published them.
Geometry
Each row must contain one polygon or multipolygon representing a map unit, usually a precinct. Points, lines, empty shapes, and zero-area shapes cannot be used to build districts.
Choose columns in Shapefile Setup
Mosaic will suggest columns when their names are recognizable. Check the selections before choosing Confirm and Load; the meaning of the data matters more than the column name.
| Selection | What it needs | What it enables |
|---|---|---|
| Population | A numeric count with no blanks or negative values. | Required for every run. |
| Precinct ID | A stable, unique value for every row. | Required for assignments and saved plans. |
| County | A county name or code shared by units in the same county. | County scoring, County-Edge Bias, and the county overlay. |
| Elections | Matching Democratic and Republican vote totals from the same election. | Partisan scores and election displays. |
| Demographics | A total plus at least one matching Black, Latino, or Asian count. White is optional. | Demographic scores and map fills. White is used only in the map fill. |
Leave optional selections blank when your file does not contain the right data. Mosaic will leave the related scores and displays unavailable.
Use an appropriate coordinate system
Mosaic reads the coordinate system stored in the shapefile. A latitude and longitude file can be displayed, but its area, distance, and compactness calculations are distorted. Use an appropriate projected, preferably equal-area, coordinate system when those measurements matter.
The bundled North Carolina sample uses latitude and longitude. It is useful for learning the interface, but its compactness values should not be treated as authoritative.
When a file will not load
Mosaic reports the first blocking problem in Shapefile Setup. These are the common fixes.
Missing, empty, or wrong geometry
Errors mentioning null or empty geometry, not Polygon / MultiPolygon, or zero area identify rows Mosaic cannot use. Repair or remove those shapes in a GIS program, then reload the file.
Population or vote column errors
The selected columns must be numeric, nonnegative, and free of missing values. Confirm that you selected counts rather than a label, percentage, or ID column.
Demographic selection errors
“A Total column is required” means a group was selected without its matching denominator. “Select at least one scored group” means only Total or White was selected.
A warning that a group is larger than its total usually means the columns use different population bases or the wrong total was selected. Fix that before relying on demographic results.
Disconnected geography
Islands and exclaves are normal, and Mosaic usually connects them in its working map automatically. If it still reports disconnected components, inspect the named rows for empty, damaged, or unusable geometry.
The cache folder
Mosaic saves the connections between map units after the first load so the
same file opens faster later. It rebuilds that information when the source
data changes. The cache folder can be deleted safely; Mosaic
creates it again when needed.