Package {brazilmaps}

Type: Package
Title: Brazilian Maps from Different Geographic Levels
Version: 1.0.0
Copyright: Package code (c) 2018-2026 Renato Prado Siqueira. See inst/COPYRIGHTS for bundled data attribution.
Description: Provides simplified Brazilian territorial meshes derived from official data published by the Brazilian Institute of Geography and Statistics (IBGE) https://www.ibge.gov.br/ as local spatial objects, with no download required at use time. Municipal meshes cover selected official editions from 2000 onwards whenever the number of municipalities changes, and current meshes are available for states, regions and other geographic levels. Convenience functions support filtering, joining and plotting the maps, as well as consulting Brazilian territorial codes.
Depends: R (≥ 4.1.0)
LazyData: true
LazyDataCompression: xz
License: GPL-3
Encoding: UTF-8
URL: https://github.com/rpradosiqueira/brazilmaps
BugReports: https://github.com/rpradosiqueira/brazilmaps/issues
Imports: dplyr, ggplot2 (≥ 3.5.0), rlang, sf
Suggests: knitr, rmarkdown, sp, testthat (≥ 3.0.0)
Config/testthat/edition: 3
VignetteBuilder: knitr
Config/roxygen2/version: 8.0.0
NeedsCompilation: no
Packaged: 2026-07-24 13:37:41 UTC; renat
Author: Renato Prado Siqueira [aut, cre]
Maintainer: Renato Prado Siqueira <rpradosiqueira@gmail.com>
Repository: CRAN
Date/Publication: 2026-08-04 10:20:03 UTC

List bundled municipal mesh editions

Description

Returns the inventory generated with the spatial files. The package bundles the latest official edition from each consecutive run with the same municipality count. All listed editions are installed and read locally by [get_brmap()].

Usage

brmap_editions()

brmap_years()

Value

A data frame with edition year, feature count, file size, checksum, source and processing metadata.

Examples

brmap_editions()

Municipal deaths in Brazil

Description

Example municipal mortality data.

Usage

deaths

Format

A data frame with 558 rows and 3 variables:

cod

IBGE microregion code.

micro

Microregion name.

ndeaths

Registered deaths.

Source

DATASUS.

Get a Brazilian territorial map

Description

Returns a simplified territorial mesh shipped with the package. No network connection is used. Municipal meshes can be selected by milestone edition year; other levels represent the current edition.

Usage

get_brmap(
  level = "country",
  filters = NULL,
  output = c("sf", "data.frame", "sp"),
  year = NULL,
  geo = NULL,
  geo_filter = NULL,
  as = NULL,
  geo.filter = NULL,
  class = NULL
)

Arguments

level

Geographic level in lower snake case. One of '"country"', '"region"', '"state"', '"state_hex"', '"state_region"', '"intermediate_region"', '"immediate_region"', '"mesoregion"', '"microregion"' or '"municipality"'.

filters

Optional named list of code filters. Level shorthands such as 'list(region = 5, state = 50)' are accepted and combined with logical AND.

output

Output type: '"sf"', '"data.frame"' or '"sp"'.

year

Bundled municipal mesh edition. 'NULL' selects the most recent edition. Historical years are available only for municipalities.

geo, geo_filter, as

Deprecated aliases for 'level', 'filters' and 'output'.

geo.filter, class

Older deprecated aliases for 'filters' and 'output'.

Value

An 'sf' object by default. '"data.frame"' removes the geometry; '"sp"' returns a legacy 'Spatial' object and requires package 'sp'.

See Also

[brmap_editions()], [join_brmap()], [plot_brmap()]

Examples

rio <- get_brmap("state", filters = list(state = 33))
municipalities_2010 <- get_brmap(
  "municipality", year = 2010, filters = list(region = 5)
)
plot_brmap(rio)

Query the Brazilian Territorial Division

Description

Looks up territorial identifiers and their hierarchy in the version of the Brazilian Territorial Division (DTB) shipped with the package.

Usage

get_dtb(code = NULL, name = NULL)

Arguments

code

Optional vector of IBGE territorial codes.

name

Optional vector of territory names. Matching ignores case and surrounding whitespace.

Value

A data frame. If both arguments are 'NULL', the complete table is returned. If both are supplied, rows matching either condition are returned.

References

https://www.ibge.gov.br/geociencias/organizacao-do-territorio/estrutura-territorial/23701-divisao-territorial-brasileira.html

See Also

[get_dtb_levels()]

Examples

get_dtb(code = c(50, 5002704, 1))
get_dtb(name = c("Campo Grande", "Recife"))

Deprecated DTB query

Description

'get_dtb_info()' is retained for compatibility. Use [get_dtb()] with argument 'code' and lower-snake-case output columns.

Usage

get_dtb_info(cod = NULL, name = NULL)

Arguments

cod

Optional vector of IBGE territorial codes.

name

Optional vector of territory names.

Value

A data frame using the legacy DTB column names.

Relate levels of the Brazilian Territorial Division

Description

Returns codes and names for one or more territorial levels using the hierarchy shipped with the package.

Usage

get_dtb_levels(
  levels = c("municipality", "state", "region", "immediate_region",
    "intermediate_region", "microregion", "mesoregion"),
  filters = NULL
)

Arguments

levels

Character vector containing any of '"municipality"', '"state"', '"region"', '"immediate_region"', '"intermediate_region"', '"microregion"' and '"mesoregion"'.

filters

Optional named list of codes used to filter the result. Conditions are combined with logical AND.

Value

A data frame with explicit code/name pairs for the requested levels.

References

https://www.ibge.gov.br/geociencias/organizacao-do-territorio/estrutura-territorial/23701-divisao-territorial-brasileira.html

See Also

[get_dtb()]

Examples

get_dtb_levels(c("municipality", "region"))
get_dtb_levels(c("state", "immediate_region"))

Deprecated DTB level relationship helper

Description

'get_dtb_lvl()' is retained for compatibility. Use [get_dtb_levels()].

Usage

get_dtb_lvl(
  geo = c("City", "State", "Region", "Immediate", "Intermediary", "MicroRegion",
    "MesoRegion"),
  geo_filter = NULL
)

Arguments

geo

Legacy geographic level names.

geo_filter

Optional named list of legacy filters.

Value

A data frame using the legacy DTB column names.

Municipal Gini index in 2015

Description

Example data containing the 2015 municipal Gini index.

Usage

gini2015

Format

A data frame with 27 rows and 3 variables:

cod

IBGE state code.

uf

State name.

gini

Gini index.

Source

Brazilian Institute of Geography and Statistics (IBGE).

Join tabular data to a Brazilian map

Description

A small type-preserving wrapper around [dplyr::left_join()].

Usage

join_brmap(map, data, by = NULL)

join_data(map, data, by = NULL)

Arguments

map

An 'sf', 'SpatialPolygonsDataFrame' or 'data.frame' object.

data

A data frame containing the columns to add.

by

Join specification accepted by [dplyr::left_join()].

Value

The same broad object type supplied in 'map'.

See Also

[get_brmap()]

Examples

data("pop2017")
municipalities <- get_brmap("municipality", year = 2023)
municipalities <- join_brmap(
  municipalities, pop2017, by = c("municipality_code" = "mun")
)

Plot a Brazilian map

Description

Creates a 'ggplot' using [ggplot2::geom_sf()]. The returned object can be extended with any regular ggplot2 layer, scale or label.

Usage

plot_brmap(
  map,
  data = NULL,
  by = NULL,
  fill_by = NULL,
  theme = theme_brmap(),
  border_colour = "grey30",
  border_linewidth = 0.15,
  fill = "white",
  data_to_join = NULL,
  join_by = NULL,
  var = NULL
)

Arguments

map

An 'sf' or legacy 'Spatial' polygon object.

data

Optional data frame to join before plotting.

by

Join specification accepted by [dplyr::left_join()].

fill_by

Optional single column name mapped to polygon fill.

theme

A complete or partial ggplot2 theme.

border_colour

Polygon border colour.

border_linewidth

Polygon border width.

fill

Constant fill used when 'fill_by' is 'NULL'.

data_to_join, join_by, var

Deprecated aliases for 'data', 'by' and 'fill_by'.

Value

A 'ggplot' object.

See Also

[get_brmap()], [join_brmap()]

Examples

data("pop2017")
south <- get_brmap(
  "municipality", year = 2023, filters = list(region = 4)
)
plot_brmap(
  south,
  data = pop2017,
  by = c("municipality_code" = "mun"),
  fill_by = "pop2017"
)

Municipal population estimates in 2017

Description

Example data containing 2017 municipal population estimates.

Usage

pop2017

Format

A data frame with 5,570 rows and 3 variables:

mun

IBGE municipality code.

nome_mun

Municipality name.

pop2017

Estimated 2017 population.

Source

Brazilian Institute of Geography and Statistics (IBGE).

Minimal theme for Brazilian maps

Description

Minimal theme for Brazilian maps

Usage

theme_brmap(base_size = 9, base_family = "")

theme_map(base_size = 9, base_family = "")

Arguments

base_size

Base font size.

base_family

Base font family.

Value

A ggplot2 theme.