---
title: "Basemaps for Data Visualization"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Basemaps for Data Visualization}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)
```

*Note: Code examples are not evaluated in this vignette. Copy and run them in your R console to see the interactive maps.*

## Introduction

When overlaying data on maps, busy basemaps can distract from your visualization. This vignette shows how to create minimal, muted basemaps that let your data stand out.

## Ultra-Minimal: Land and Water Only

Strip everything except land and water boundaries using `pmMinimal()`:

```{r}
library(leaflet)
library(protomapr)

# Using the convenience function - just two lines!
leaflet() %>%
  setView(lng = -122.4, lat = 37.8, zoom = 10) %>%
  addProtomaps(url = protomaps_url(), style = pmMinimal())

# Custom colors
leaflet() %>%
  setView(lng = -122.4, lat = 37.8, zoom = 10) %>%
  addProtomaps(
    url = protomaps_url(),
    style = pmMinimal(land = "#f5f5f0", water = "#c8dce8")
  )
```

## Subtle Context: Faint Roads

Keep roads barely visible for orientation without distraction:

```{r}
leaflet() %>%
  setView(lng = -73.98, lat = 40.75, zoom = 12) %>%
  addProtomaps(
    url = protomaps_url(),
    colors = pmColors(
      background = "#ffffff",
      earth = "#fafafa",
      water = "#f0f4f8",
      # Muted land use
      park = "#f5f7f5",
      wood = "#f5f7f5",
      scrub_a = "#fafafa",
      scrub_b = "#fafafa",
      glacier = "#fafafa",
      sand = "#fafafa",
      beach = "#fafafa",
      hospital = "#fafafa",
      school = "#fafafa",
      industrial = "#fafafa",
      pedestrian = "#fafafa",
      zoo = "#fafafa",
      military = "#fafafa",
      aerodrome = "#fafafa",
      # Faint roads - just slightly darker than background
      highway = "#e8e8e8",
      major = "#efefef",
      medium = "#f5f5f5",
      minor = "#fafafa",
      link = "#fafafa",
      other = "#fafafa",
      railway = "#f0f0f0",
      pier = "#fafafa",
      boundary = "#fafafa",
      buildings = "#fafafa"
    ),
    labelRules = list()
  )
```

## Dark Mode for Bright Data

Dark basemaps make colorful data points pop. Use the `minimal-dark` preset:

```{r}
leaflet() %>%
  setView(lng = -122.4, lat = 37.8, zoom = 11) %>%
  addProtomaps(url = protomaps_url(), style = pmStyle("minimal-dark"))
```

## Muted with Major Labels Only

Sometimes you need city names for context but nothing else. Use `pmMinimal()` with `labels = TRUE`:

```{r}
leaflet() %>%
  setView(lng = -100, lat = 40, zoom = 4) %>%
  addProtomaps(
    url = protomaps_url(),
    style = pmMinimal(land = "#f5f5f0", water = "#d4e4ed", labels = TRUE)
  )

# Or use the "muted" preset which includes subtle roads and labels
leaflet() %>%
  setView(lng = -100, lat = 40, zoom = 4) %>%
  addProtomaps(url = protomaps_url(), style = pmStyle("muted"))
```

## Choropleth-Friendly: No Fill Competition

For choropleth maps, you want boundaries visible but no competing fill colors:

```{r}
leaflet() %>%
  setView(lng = -98, lat = 38, zoom = 4) %>%
  addProtomaps(
    url = protomaps_url(),
    colors = pmColors(
      background = "#ffffff",
      earth = "#ffffff",
      water = "#ffffff",
      # Hide all land use
      park = "#ffffff",
      wood = "#ffffff",
      scrub_a = "#ffffff",
      scrub_b = "#ffffff",
      glacier = "#ffffff",
      sand = "#ffffff",
      beach = "#ffffff",
      hospital = "#ffffff",
      school = "#ffffff",
      industrial = "#ffffff",
      pedestrian = "#ffffff",
      zoo = "#ffffff",
      military = "#ffffff",
      aerodrome = "#ffffff",
      # Hide roads
      highway = "#ffffff",
      major = "#ffffff",
      medium = "#ffffff",
      minor = "#ffffff",
      link = "#ffffff",
      other = "#ffffff",
      railway = "#ffffff",
      pier = "#ffffff",
      buildings = "#ffffff",
      # Keep boundaries visible
      boundary = "#cccccc"
    ),
    labelRules = list(
      pmLabelRule("places", pmCenteredTextSymbolizer(
        font = "600 11px sans-serif",
        fill = "#333333",
        stroke = "#ffffff",
        width = 2
      ), filter = "feature.props.kind === 'region'")
    )
  )
```

## Watercolor Style

Soft, hand-drawn aesthetic using the `watercolor` preset:

```{r}
leaflet() %>%
  setView(lng = -122.4, lat = 37.8, zoom = 12) %>%
  addProtomaps(url = protomaps_url(), style = pmStyle("watercolor"))
```

## Tips for Data Visualization Basemaps

1. **Match your data colors**: If your data uses warm colors, use cool-toned basemaps (and vice versa)

2. **Consider accessibility**: Ensure sufficient contrast between your data and basemap

3. **Remove labels when zoomed in**: Dense point data doesn't need city labels competing for attention

4. **Use transparency**: Leaflet markers and shapes can use alpha values to blend with basemaps

5. **Test at all zoom levels**: A basemap that works at zoom 10 may be too busy at zoom 15