Convert SF Object to Power BI-Compatible TopoJSON

Converts an sf spatial dataframe to TopoJSON format optimized for Microsoft Power BI Shape Map visualizations. Automatically handles CRS transformation to WGS84 and validates geometry types.

sf_to_powerbi_topojson(
  sf_data,
  file = "output_powerbi.json",
  object_name = "features",
  id_col = NULL,
  name_col = NULL,
  keep_cols = NULL,
  simplify = FALSE,
  tolerance = 0.01,
  verbose = TRUE
)

Arguments

sf_data

sf object. Spatial data to convert. Must contain POLYGON or MULTIPOLYGON geometries. Required.

file

Character string. Output file path. Must end with .json extension (Power BI requirement). Default is "output_powerbi.json".

object_name

Character string. Name for the TopoJSON object layer. This name will be used by Power BI to identify the geographic layer. Default is "features".

id_col

Character string or NULL. Optional column name to use as the feature ID in the TopoJSON properties. If specified, this field should uniquely identify each feature. Default is NULL (no specific ID field).

name_col

Character string or NULL. Optional column name to use as the feature name in the TopoJSON properties. Useful for labeling features in Power BI. Default is NULL (no specific name field).

keep_cols

Character vector or NULL. Column names to keep in the output properties (excluding geometry). If NULL (default), all attribute columns are kept. Geometry column is always retained.

simplify

Logical. If TRUE, simplify geometries using rmapshaper to reduce file size while preserving topology. Requires rmapshaper package. Default is FALSE.

tolerance

Numeric. Simplification tolerance parameter for rmapshaper::ms_simplify (0-1). Higher values = more simplification. This is the "keep" parameter: proportion of points to retain. Only used if simplify = TRUE. Default is 0.01 (keep 1% of points).

verbose

Logical. If TRUE (default), print progress messages including CRS transformations, simplification results, and file creation.

Value

Invisibly returns the output file path. The function is called primarily for its side effect of creating the TopoJSON file.

Details

Power BI Requirements: Power BI Shape Map visual has specific requirements for custom map files:

  • CRS: Must use WGS84 (EPSG:4326) coordinate system

  • Geometry: Only POLYGON and MULTIPOLYGON supported (no lines/points)

  • File Extension: Must be .json (not .topojson)

  • Properties: Need feature properties for data binding

This function automatically handles all these requirements:

  1. Validates that geometries are polygon types

  2. Transforms to WGS84 if needed

  3. Ensures .json file extension

  4. Preserves attribute columns for data binding

Column Filtering: You can control which attribute columns are included using keep_cols, id_col, and name_col:

  • If keep_cols is NULL: all columns are kept

  • If keep_cols is specified: only those columns (plus geometry)

  • If id_col or name_col are specified and not in keep_cols, they are automatically added

Simplification: Setting simplify = TRUE can dramatically reduce file size for complex geometries (e.g., detailed municipality boundaries). The tolerance parameter controls how much simplification occurs:

  • 0.01 = keep 1% of points (aggressive simplification)

  • 0.1 = keep 10% of points (moderate simplification)

  • 0.5 = keep 50% of points (gentle simplification)

Simplification uses topology-preserving algorithms that maintain shared boundaries between adjacent polygons.

Using in Power BI: Once you have created the .json file:

  1. Open Power BI Desktop

  2. Insert > Shape Map visual

  3. Click on the visual

  4. Format visual > Shape > Map settings

  5. Click "+ Add map" and select your .json file

  6. Drag your data fields to the visual:

    • Location: field matching id_col or other identifier

    • Color saturation: your metric field

    • Tooltips: additional fields to display

Export Method: The function uses geojsonio::topojson_write() with high quantization (1e5) to create Power BI-compatible TopoJSON files with optimal topology preservation and precision. Optional geometry simplification is available via rmapshaper::ms_simplify() when simplify = TRUE.

Examples

if (FALSE) { # \dontrun{
# Basic usage with default settings
library(sf)
italy_regions <- st_read("regions.shp")
sf_to_powerbi_topojson(italy_regions, file = "italy_regions.json")

# Specify ID and name columns for Power BI matching
sf_to_powerbi_topojson(
  sf_data = italy_regions,
  file = "italy_regions.json",
  id_col = "COD_REG",
  name_col = "DEN_REG",
  object_name = "regioni"
)

# Keep only specific columns and simplify geometries
sf_to_powerbi_topojson(
  sf_data = italy_municipalities,
  file = "italy_comuni_simple.json",
  keep_cols = c("PRO_COM", "COMUNE", "COD_REG"),
  simplify = TRUE,
  tolerance = 0.01  # Keep 1 percent of points
)

# With aggressive simplification for large datasets
sf_to_powerbi_topojson(
  sf_data = detailed_boundaries,
  file = "boundaries_simplified.json",
  simplify = TRUE,
  tolerance = 0.005,  # Very aggressive
  verbose = TRUE  # See size reduction
)

# Use with situas package data
library(situas)
files <- prepare_territorial_maps(territorial_level = "province")
province_sf <- readRDS(files$rds)

# Convert to custom Power BI format with specific columns
sf_to_powerbi_topojson(
  sf_data = province_sf,
  file = "data/province_custom.json",
  id_col = "COD_UTS",
  name_col = "DEN_UTS",
  keep_cols = c("COD_UTS", "DEN_UTS", "COD_REG"),
  object_name = "province"
)
} # }