# Perceptual Dialectology in Potato: Draw-a-Map Tasks and Overlap Heat Maps

Source: https://www.potatoannotator.com/docs/guides/perceptual-dialectology

**[Perceptual dialectology](https://en.wikipedia.org/wiki/Perceptual_dialectology) studies where non-linguists believe dialect areas are, and what they call them. Its best-known method is Dennis Preston's draw-a-map task, in which participants outline the areas where they think people speak differently on a blank map and name each one. Potato 2.12.0 runs the task online with the `geo_annotation` scheme and aggregates many participants' drawings into heat maps with the `geo_overlap` export.**

Overlaying the maps shows which areas participants agree on and what they call them. Potato's implementation is its own: the draw-a-map tools found online carry no licence, so it shares no code with them.

## Try the example study

`examples/advanced/dialect-map/` is a complete study on a fictional country, Arventa, whose ten province outlines are synthetic and resemble no real borders. It asks three questions on one page:

1. **Draw the areas where people speak differently** (`task: draw`): freehand or polygon outlines, a label for how different the speech sounds, and a required name for each area.
2. **Where did you grow up?** (`task: pin`): one pin.
3. **How does the speech of each province sound to you?** (`task: classify_region`): each province gets *Sounds like home*, *Sounds different* or *Don't know*.

```bash
python potato/flask_server.py start examples/advanced/dialect-map/config.yaml -p 8000
```

The map needs no network connection, and nothing is fetched from a tile server.

## Choose an outline map

Use an outline the participants will recognise, without the dialect labels or regional names you are trying to elicit, because a labelled map leads the answers. Boundaries of states, provinces or counties are the usual choice.

- Put the file under the project directory and name it in `basemap.geojson`. It is embedded in the page, so simplify it first, with mapshaper, QGIS or similar, to a few hundred kilobytes or less.
- Check the licence of the boundary data before you put it in the project. Many national statistics offices publish boundary files under open licences, and some commercial boundary sets cannot be redistributed.
- If the file writes latitude first, set `coordinate_order: latlon`.
- Region names in the outline (`region_name_property`) are drawn on the map. If they would lead the participants, leave the property out of the file.

## Configure the draw question

```yaml
- annotation_type: geo_annotation
  name: dialect_areas
  description: "Draw the areas where people speak differently"
  task: draw
  tools: [freehand, polygon]
  labels:
    - "A little different"
    - "Very different"
    - "Hard to understand"
  feature_text:
    prompt: "What do you call how people talk there?"
    required: true
  basemap:
    geojson: maps/regions.geojson
  label_requirement:
    required: true
```

- `tools: [freehand]` alone is closest to drawing with a pen on a paper map. Freehand outlines may cross themselves, and the aggregate fills them by the even-odd rule, so a figure-eight counts as its two loops.
- One label is enough if you want only the areas and their names. More labels let participants rate each area as they draw it, for how different, how pleasant or how easy to understand the speech is.
- `feature_text.required` makes every area need a name before Next, and `min_features` and `max_features` bound how many areas a participant draws.

`task: pin` with one label per question records places such as birthplace or current residence, which you will usually want for grouping the drawings. `task: classify_region` asks for one judgement per region and gives a choropleth instead of free outlines. [Maps](/docs/annotation-types/geo-annotation) has every option.

## Overlap heat maps

```bash
python -m potato.export --config config.yaml --format geo_overlap --output out/
```

For each item and draw scheme, the export lays a regular longitude/latitude grid over the outline map, or over the drawings if there is no outline. For every label, a cell's **share** is the fraction of respondents with at least one polygon of that label whose outline contains the cell's centre. Respondents are the participants who drew at least one polygon in that scheme on that item, and a participant counts once per cell however many of their polygons overlap there.

| File | Content |
|---|---|
| `geo_overlap/<item>__<schema>__<group>.geojson` | One square polygon per covered cell, with `count`, `respondents`, `share`, `row`, `col`, and the item, scheme and group |
| `geo_overlap/<item>__<schema>__<group>.png` | A preview, with covered cells shaded from light (few respondents) to dark (all of them) and the outline in grey |
| `geo_overlap_summary.csv` | One row per heat map: respondents, polygons, cells covered, largest share, grid size and extent |
| `geo_names.csv` | Every drawn feature: participant, item, label, the name as typed, a normalised form, geometry type, area in km² and a label point |
| `geo_name_counts.csv` | Per scheme, label and normalised name, how many participants used it |
| `geo_regions.csv` | For `classify_region` schemes, per region and label, how many participants chose it and the share |

| Option | Default | Meaning |
|---|---|---|
| `group_by` | `label` | `label`, `text` (the normalised name) or `label_text` (both) |
| `cells` | `100` | Cells along the longer side of the extent |
| `cell_size` | none | Cell size in degrees, which overrides `cells` |
| `extent` | outline bounds | `min_lon,min_lat,max_lon,max_lat` |
| `schema` | all | Exports one scheme |

Cells are equal in degrees, not in area. Over one country the difference is small, and the GeoJSON cells carry their corner coordinates, so a GIS can reproject them. The PNG preview is plate carrée, so it looks wider than the Web Mercator map on the page.

Grouping by name puts two areas together only when their normalised names match, after case-folding and collapsing whitespace. `geo_name_counts.csv` shows the spellings participants used. To merge variants such as "Southern", "the south" and "southern drawl", recode `geo_names.csv` and aggregate the polygons yourself, or ask participants to choose from labels instead. Points and lines are not aggregated, and a heat map with share 1.0 everywhere it is shaded means only one participant drew that label.

The `geojson` export writes every drawing with its participant and item, for analysis in QGIS, R (`sf`) or Python (`geopandas`).

## Further Reading

- [Maps](/docs/annotation-types/geo-annotation) - Every `geo_annotation` option, basemap and control
- [Linguistic Fieldwork](/docs/guides/linguistic-fieldwork) - Interlinear glossing, FLEx and Toolbox
- [Online Behavioral Experiments](/docs/guides/online-behavioral-experiments) - Recruiting and screening participants

For implementation details, see the [source documentation](https://github.com/davidjurgens/potato/blob/master/docs/guides/perceptual-dialectology.md).