Package 'brazilmaps'

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 one row per installed edition and columns 'year', 'n_features', 'file_bytes', 'md5', 'crs', 'simplification' and 'source'. 'source' contains the exact official IBGE archive URL or URLs used by the maintenance pipeline.

Examples

brmap_editions()

---

Microregional deaths in Brazil

Description

Example mortality data for the discontinued IBGE microregions.

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 bundled snapshot. Parsed maps are cached only in memory for the duration of the R session.

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'.

Details

The meshes are intended for thematic mapping, exploratory analysis and joins. They are not suitable for cadastral work, legal boundary decisions or precise area and perimeter measurement. Historical municipal geometries receive current immediate, intermediate, microregion and mesoregion attributes when their municipality codes can be matched to the bundled current DTB.

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 bundled snapshot is returned. If both are supplied, rows matching either condition are returned. A query with no matches returns zero rows while preserving the complete column schema.

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.

---

State Gini index in 2015

Description

Example data containing the 2015 Gini index by state.

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.

---