def read_health_region(year=2013, macro=False, simplified=True, verbose=False):
"""Download official data of Brazilian health regions as an sf object.
Health regions are used to guide the the regional and state planning of health services.
Macro health regions, in particular, are used to guide the planning of high complexity
health services. These services involve larger economics of scale and are concentrated in
few municipalities because they are generally more technology intensive, costly and face
shortages of specialized professionals. A macro region comprises one or more health regions.
Parameters
----------
year : int, optional
Year of the data, by default 2013
macro: If `False` (default), the function downloads health regions data.
If `True`, the function downloads macro regions data.
simplified: boolean, by default True
Data 'type', indicating whether the function returns the 'original' dataset
with high resolution or a dataset with 'simplified' borders (Default)
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import read_health_region
# Read specific state at a given year
>>> df = read_health_region(year=2013)
"""
if macro:
metadata = select_metadata("health_region_macro",
year=year,
simplified=simplified)
else:
metadata = select_metadata("health_region",
year=year,
simplified=simplified)
gdf = download_gpkg(metadata)
return gdf
def read_health_region(year=2013, simplified=True, verbose=False):
""" Download official data of Brazilian health regions as an sf object.
@param year Year of the data (defaults to 2013, latest available)
@param simplified Logic FALSE or TRUE, indicating whether the function returns the
data set with 'original' resolution or a data set with 'simplified' borders (Defaults to TRUE).
For spatial analysis and statistics users should set simplified = FALSE. Borders have been
simplified by removing vertices of borders using st_simplify{sf} preserving topology with a dTolerance of 100.
@param showProgress Logical. Defaults to (TRUE) display progress bar
@param tp Argument deprecated. Please use argument 'simplified
Parameters
----------
year : int, optional
Year of the data, by default 2013
simplified: boolean, by default True
Data 'type', indicating whether the function returns the 'original' dataset
with high resolution or a dataset with 'simplified' borders (Default)
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import read_health_region
# Read specific state at a given year
>>> df = read_health_region(year=2013)
"""
metadata = select_metadata("health_region",
year=year,
simplified=simplified)
gdf = download_gpkg(metadata)
return gdf
def read_disaster_risk_area(year=2010, simplified=True, verbose=False):
""" Download official data of disaster risk areas as an sf object.
This function reads the the official data of disaster risk areas in Brazil. It specifically focuses
on geodynamic and hydro-meteorological disasters capable of triggering landslides and floods. The
data set covers the whole country. Each risk area polygon (known as 'BATER') has unique code id (column 'geo_bater').
The data set brings information on the extent to which the risk area polygons overlap with census
tracts and block faces (column "acuracia") and number of ris areas within each risk area (column 'num').
Orignal data were generated by IBGE and CEMADEN. For more information about the methodology, see deails
at https://www.ibge.gov.br/geociencias/organizacao-do-territorio/tipologias-do-territorio/21538-populacao-em-areas-de-risco-no-brasil.html
Parameters
----------
year : int, optional
Year of the data, by default 2010
simplified: boolean, by default True
Data 'type', indicating whether the function returns the 'original' dataset
with high resolution or a dataset with 'simplified' borders (Default)
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import read_disaster_risk_area
# Read specific state at a given year
>>> df = read_disaster_risk_area(year=2010)
"""
metadata = select_metadata("disaster_risk_area",
year=year,
simplified=simplified)
gdf = download_gpkg(metadata)
return gdf
def read_urban_concentrations(year=2015, simplified=True, verbose=False):
r""" Download urban concentration areas in Brazil
@description
This function reads the official data on the urban concentration areas (Areas
de Concentracao de Populacao) of Brazil. Original data were generated by the
Institute of Geography and Statistics (IBGE) For more information about the
methodology, see details at \url{https://www.ibge.gov.br/apps/arranjos_populacionais/2015/pdf/publicacao.pdf}
Parameters
----------
year : int, optional
Year of the data, by default 2015
simplified: boolean, by default True
Data 'type', indicating whether the function returns the 'original' dataset
with high resolution or a dataset with 'simplified' borders (Default)
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import read_urban_concentrations
# Read specific state at a given year
>>> df = read_urban_concentrations(year=2015)
"""
metadata = select_metadata('urban_concentrations',
year=year,
simplified=simplified)
gdf = download_gpkg(metadata)
return gdf
def read_health_facilities(verbose=False):
""" Download geolocated data of health facilities as an sf object.
Data comes from the National Registry of Healthcare facilities (Cadastro Nacional de Estabelecimentos de Saude - CNES),
originally collected by the Brazilian Ministry of Health. The date of the last data update is
registered in the database in the columns 'date_update' and 'year_update'. These data uses Geodetic reference
system "SIRGAS2000" and CRS(4674). The coordinates of each facility was obtained by CNES
and validated by means of space operations. These operations verify if the point is in the
municipality, considering a radius of 5,000 meters. When the coordinate is not correct,
further searches are done in other systems of the Ministry of Health and in web services
like Google Maps . Finally, if the coordinates have been correctly obtained in this process,
the coordinates of the municipal head office are used. The final source used is registered
in the database in a specific column 'data_source'. Periodically the coordinates are revised
with the objective of improving the quality of the data. More information
available at http://dados.gov.br/dataset/cnes
Parameters
----------
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import read_health_facilities
# Read specific state at a given year
>>> df = read_health_facilities()
"""
metadata = select_metadata('health_facilities')
gdf = download_gpkg(metadata)
return gdf
def read_indigenous_land(date=201907, simplified=True, verbose=False):
""" Download official data of indigenous lands as an sf object.
The data set covers the whole of Brazil and it includes indigenous lands from all ethnicities and
in different stages of demarcation. The original data comes from the National Indian Foundation (FUNAI)
and can be found at http://www.funai.gov.br/index.php/shape. Although original data is updated monthly,
the geobr package will only keep the data for a few months per year.
Parameters
----------
date : int, optional
A date numer in YYYYMM format, by default 201907
simplified: boolean, by default True
Data 'type', indicating whether the function returns the 'original' dataset
with high resolution or a dataset with 'simplified' borders (Default)
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import read_indigenous_land
# Read specific state at a given year
>>> df = read_indigenous_land(date=201907)
"""
metadata = select_metadata("indigenous_land",
year=date,
simplified=simplified)
gdf = download_gpkg(metadata)
return gdf
def read_metro_area(year=2018, simplified=True, verbose=False):
""" Download shape files of official metropolitan areas in Brazil as an sf object.
The function returns the shapes of municipalities grouped by their respective metro areas.
Metropolitan areas are created by each state in Brazil. The data set includes the municipalities that belong to
all metropolitan areas in the country according to state legislation in each year. Orignal data were generated
by Institute of Geography. Data at scale 1:250,000, using Geodetic reference system "SIRGAS2000" and CRS(4674).
Parameters
----------
year : int, optional
Year of the data, by default 2018
simplified: boolean, by default True
Data 'type', indicating whether the function returns the 'original' dataset
with high resolution or a dataset with 'simplified' borders (Default)
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import read_metro_area
# Read specific state at a given year
>>> df = read_metro_area(year=2018)
"""
metadata = select_metadata("metropolitan_area",
year=year,
simplified=simplified)
gdf = download_gpkg(metadata)
return gdf
def read_conservation_units(date=201909, simplified=True, verbose=False):
""" Download official data of Brazilian conservation untis as an sf object.
This data set covers the whole of Brazil and it includes the polygons of all conservation untis present in Brazilian
territory. The last update of the data was 09-2019. The original
data comes from MMA and can be found at http://mapas.mma.gov.br/i3geo/datadownload.htm .
Parameters
----------
date : int, optional
A date number in YYYYMM format, by default 201909
simplified: boolean, by default True
Data 'type', indicating whether the function returns the 'original' dataset
with high resolution or a dataset with 'simplified' borders (Default)
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import read_conservation_units
# Read specific state at a given year
>>> df = read_conservation_units(date=201909)
"""
metadata = select_metadata("conservation_units",
year=date,
simplified=simplified)
gdf = download_gpkg(metadata)
return gdf
def read_amazon(year=2012, simplified=True, verbose=False):
""" Download official data of Brazil's Legal Amazon as an sf object.
This data set covers the whole of Brazil's Legal Amazon as defined in the federal law n. 12.651/2012). The original
data comes from the Brazilian Ministry of Environment (MMA) and can be found at http://mapas.mma.gov.br/i3geo/datadownload.htm .
Parameters
----------
year : int, optional
Year of the data, by default 2012
simplified: boolean, by default True
Data 'type', indicating whether the function returns the 'original' dataset
with high resolution or a dataset with 'simplified' borders (Default)
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import read_amazon
# Read specific state at a given year
>>> df = read_amazon(year=2012)
"""
metadata = select_metadata('amazonia_legal',
year=year,
simplified=simplified)
gdf = download_gpkg(metadata)
return gdf
def read_schools(year=2020, verbose=False):
r"""Download geolocated data of schools
Data comes from the School Census collected by INEP, the National Institute
for Educational Studies and Research Anisio Teixeira. The date of the last
data update is registered in the database in the column 'date_update'. These
data uses Geodetic reference system "SIRGAS2000" and CRS(4674). The coordinates
of each school if collected by INEP. Periodically the coordinates are revised
with the objective of improving the quality of the data. More information
available at \url{https://www.gov.br/inep/pt-br/acesso-a-informacao/dados-abertos/inep-data/catalogo-de-escolas/}
Parameters
----------
year : int, optional
Year of the data, by default 2020
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import read_schools
# Read specific state at a given year
>>> df = read_schools(year=2020)
"""
metadata = select_metadata("schools", year=year, simplified=False)
gdf = download_gpkg(metadata)
return gdf
def read_urban_area(year=2015, simplified=True, verbose=False):
""" Download official data of urbanized areas in Brazil as an sf object.
This function reads the official data on the urban footprint of Brazilian cities
in the years 2005 and 2015. Orignal data were generated by Institute of Geography
and Statistics (IBGE) For more information about the methodology, see deails at
https://biblioteca.ibge.gov.br/visualizacao/livros/liv100639.pdf
Parameters
----------
year : int, optional
Year of the data, by default 2015
simplified: boolean, by default True
Data 'type', indicating whether the function returns the 'original' dataset
with high resolution or a dataset with 'simplified' borders (Default)
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import read_urban_area
# Read specific state at a given year
>>> df = read_urban_area(year=2015)
"""
metadata = select_metadata('urban_area', year=year, simplified=simplified)
gdf = download_gpkg(metadata)
return gdf
def read_biomes(year=2019, simplified=True, verbose=False):
""" Download official data of Brazilian biomes as an sf object.
This data set includes polygons of all biomes present in Brazilian territory and coastal area.
The latest data set dates to 2019 and it is available at scale 1:250.000. The 2004 data set is at
the scale 1:5.000.000. The original data comes from IBGE. More information at https://www.ibge.gov.br/apps/biomas/
Parameters
----------
year : int, optional
Year of the data, by default 2019
simplified: boolean, by default True
Data 'type', indicating whether the function returns the 'original' dataset
with high resolution or a dataset with 'simplified' borders (Default)
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import read_biomes
# Read specific state at a given year
>>> df = read_biomes(year=2019)
"""
metadata = select_metadata('biomes', year=year, simplified=simplified)
gdf = download_gpkg(metadata)
return gdf
def read_country(year=2010, simplified=True, verbose=False):
""" Download shape file of Brazil as sf objects. Data at scale 1:250,000, using Geodetic reference system "SIRGAS2000" and CRS(4674)
@param year Year of the data (defaults to 2010)
@param simplifiedWhether the function returns the 'original' dataset with high resolution or a dataset with 'simplified' borders (Default)
@param showProgress Logical. Defaults to (TRUE) display progress bar
Parameters
----------
year : int, optional
Year of the data, by default 2010
simplified: boolean, by default True
Data 'type', indicating whether the function returns the 'original' dataset
with high resolution or a dataset with 'simplified' borders (Default)
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import read_country
# Read specific state at a given year
>>> df = read_country(year=2010)
"""
metadata = select_metadata("country", year=year, simplified=simplified)
gdf = download_gpkg(metadata)
return gdf
def read_semiarid(year=2017, simplified=True, verbose=False):
""" Download official data of Brazilian Semiarid as an sf object.
This data set covers the whole of Brazilian Semiarid as defined in the resolution in 23/11/2017). The original
data comes from the Brazilian Institute of Geography and Statistics (IBGE) and can be found at https://www.ibge.gov.br/geociencias/cartas-e-mapas/mapas-regionais/15974-semiarido-brasileiro.html?=&t=downloads
Parameters
----------
year : int, optional
Year of the data, by default 2017
simplified: boolean, by default True
Data 'type', indicating whether the function returns the 'original' dataset
with high resolution or a dataset with 'simplified' borders (Default)
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import read_semiarid
# Read specific state at a given year
>>> df = read_semiarid(year=2017)
"""
metadata = select_metadata('semiarid', year=year, simplified=simplified)
gdf = download_gpkg(metadata)
return gdf
def read_municipal_seat(year=2010, verbose=False):
""" Download official data of municipal seats (sede dos municipios) in Brazil as an sf object.
This function reads the official data on the municipal seats (sede dos municipios) of Brazil.
The data brings the spatial coordinates (lat lon) of of municipal seats for various years
between 1872 and 2010. Orignal data were generated by Brazilian Institute of Geography
and Statistics (IBGE).
Parameters
----------
year : int, optional
Year of the data, by default 2010
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import read_municipal_seat
# Read specific state at a given year
>>> df = read_municipal_seat(year=2010)
"""
metadata = select_metadata("municipal_seat", year=year)
gdf = download_gpkg(metadata)
return gdf
def read_neighborhood(year=2010, simplified=True, verbose=False):
""" Download neighborhood limits of Brazilian municipalities as a geopandas geodataframe object
Parameters
----------
year : int, optional
Year of the data, by default 2010
simplified: boolean, by default True
Data 'type', indicating whether the function returns the 'original' dataset
with high resolution or a dataset with 'simplified' borders (Default)
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import read_neighborhood
# Read specific neighborhoods at a given year
>>> df = read_neighborhood(year=2010)
"""
metadata = select_metadata('neighborhood', year=year, simplified=simplified)
gdf = download_gpkg(metadata)
return gdf
def read_state(code_state='all', year=2010, simplified=True, verbose=False):
"""Download shapefiles of Brazilian states as geopandas objects.
Data at scale 1:250,000, using Geodetic reference system "SIRGAS2000" and CRS(4674)
Parameters
----------
code_state : str, optional
The two-digit code of a state or a two-letter uppercase abbreviation
(e.g. 33 or "RJ"). If code_state="all", all states will be loaded (Default).
year : int, optional
Year of the data, by default 2010
simplified: boolean, by default True
Data 'type', indicating whether the function returns the 'original' dataset
with high resolution or a dataset with 'simplified' borders (Default)
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import read_state
# Read specific state at a given year
>>> uf = read_state(code_state=12, year=2017)
# Read specific state at a given year with normal geopackages
>>> uf = read_state(code_state="SC", year=2000, tp='normal')
# Read all states at a given year
>>> ufs = read_state(code_state="all", year=2010)
"""
metadata = select_metadata('state', year=year, simplified=simplified)
if code_state is None:
raise Exception("Value to argument 'code_state' cannot be None")
# From 1872 to 1991 and all
if (year < 1992) or (code_state == "all"):
if verbose:
print("Loading data for the whole country\n")
return download_gpkg(metadata)
# From 2000 onwards
else:
if (str(code_state)[0:2] not in metadata['code'].unique() and
str(code_state)[0:2] not in metadata['code_abrev'].unique()):
raise Exception("Error: Invalid Value to argument code_state.")
else:
if isinstance(code_state, int):
metadata = metadata.query(f'code == "{str(code_state)[0:2]}"')
if isinstance(code_state, str):
metadata = metadata.query(f'code_abrev == "{code_state[0:2]}"')
gdf = download_gpkg(metadata)
if len(str(code_state)) == 2:
return gdf
elif code_state in list(gdf['code_state']):
return gdf.query('code_state == "code_state"')
else:
raise Exception("Error: Invalid Value to argument code_state.")
def read_immediate_region(code_immediate="all",
year=2017,
simplified=True,
verbose=False):
""" Download shape files of Brazil's Immediate Geographic Areas as sf objects
The Immediate Geographic Areas are part of the geographic division of
Brazil created in 2017 by IBGE to replace the "Micro Regions" division.
Data at scale 1:250,000, using Geodetic reference system "SIRGAS2000"
and CRS(4674)
Parameters
----------
code_immediate:
6-digit code of an immediate region. If the two-digit code or a
two-letter uppercase abbreviation of a state is passed, (e.g. 33 or
"RJ") the function will load all immediate regions of that state. If
code_immediate="all", all immediate regions of the country are loaded
(defaults to "all").
year : int, optional
Year of the data, by default 2017
simplify: boolean, by default True
Data 'type', indicating whether the function returns the 'original' dataset
with high resolution or a dataset with 'simplify' borders (Default)
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import read_immediate_region
# Read specific state at a given year
>>> df = read_immediate_region(year=2017)
"""
test_options(code_immediate, "code_immediate", not_allowed=[None])
metadata = select_metadata("immediate_regions",
year=year,
simplified=simplified)
gdf = download_gpkg(metadata)
# ensure type
code_immediate = str(code_immediate)
if code_immediate == "all":
if verbose:
print("Loading data for the whole country. "
"This might take a few minutes.\n")
return gdf
elif code_immediate in gdf["abbrev_state"].tolist():
return gdf.query(f'abbrev_state == "{code_immediate}"')
elif code_immediate in change_type_list(gdf["code_state"].tolist()):
return gdf.query(f'code_state == "{code_immediate}"')
elif code_immediate in change_type_list(gdf["code_immediate"].tolist()):
return gdf.query(f'code_immediate == "{code_immediate}"')
else:
raise Exception("Invalid Value to argument 'code_immediate'")
def test_select_metadata():
assert isinstance(select_metadata("state", "simplified", 2010),
pd.core.frame.DataFrame)
assert isinstance(select_metadata("state", "simplified", None),
pd.core.frame.DataFrame)
assert isinstance(select_metadata("state", "normal", None),
pd.core.frame.DataFrame)
# checks if None conditions are being applied
assert len(select_metadata("state", "normal", None)) < len(
select_metadata("state", False, False))
assert len(select_metadata("state", "simplified", None)) < len(
select_metadata("state", False, False))
with pytest.raises(Exception):
select_metadata(123, 123, 123)
select_metadata("state", 123, 123)
select_metadata("state", "simplified", 12334)
def read_municipality(code_muni='all',
year=2010,
simplified=True,
verbose=False):
""" Download shape files of Brazilian municipalities as sf objects.
Data at scale 1:250,000, using Geodetic reference system "SIRGAS2000" and CRS(4674)
Parameters
----------
code_muni:
The 7-digit code of a municipality. If the two-digit code or a two-letter uppercase abbreviation of
a state is passed, (e.g. 33 or "RJ") the function will load all municipalities of that state.
If code_muni="all", all municipalities of the country will be loaded.
year : int, optional
Year of the data, by default 2010
simplified: boolean, by default True
Data 'type', indicating whether the function returns the 'original' dataset
with high resolution or a dataset with 'simplified' borders (Default)
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import read_municipality
# Read specific meso region at a given year
>>> df = read_municipality(code_muni=1200179, year=2018)
# Read all meso regions of a state at a given year
>>> df = read_municipality(code_muni=12, year=2017)
>>> df = read_municipality(code_muni="AM", year=2000)
# Read all meso regions of the country at a given year
>>> df = read_municipality(code_muni="all", year=2010)
"""
metadata = select_metadata('municipality',
year=year,
simplified=simplified)
if year < 1992:
return download_gpkg(metadata)
if code_muni == 'all':
if verbose:
print(
'Loading data for the whole country. This might take a few minutes.'
)
return download_gpkg(metadata)
metadata = metadata[metadata[['code', 'code_abrev']].apply(
lambda x: str(code_muni)[:2] in str(x['code']) or # if number e.g. 12
str(code_muni)[:2] in str(x['code_abrev']) # if UF e.g. RO
,
1)]
if not len(metadata):
raise Exception('Invalid Value to argument code_muni.')
gdf = download_gpkg(metadata)
if len(str(code_muni)) == 2:
return gdf
elif code_muni in gdf['code_muni'].tolist():
return gdf.query(f'code_muni == {code_muni}')
else:
raise Exception('Invalid Value to argument code_muni.')
return gdf
def read_comparable_areas(start_year=1970,
end_year=2010,
simplified=True,
verbose=False):
r"""Download spatial data of historically comparable municipalities
This function downloads the shape file of minimum comparable area of
municipalities, known in Portuguese as 'Areas minimas comparaveis (AMCs)'.
The data is available for any combination of census years between 1872-2010.
These data sets are generated based on the Stata code originally developed by
\doi{10.1590/0101-416147182phe}{Philipp Ehrl}, and translated
into `R` by the `geobr` team.
Years available:
1872,1900,1911,1920,1933,1940,1950,1960,1970,1980,1991,2000,2010
Parameters
----------
year : int, optional
Year of the data, by default
simplified: boolean, by default True
Data 'type', indicating whether the function returns the 'original' dataset
with high resolution or a dataset with 'simplified' borders (Default)
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import read_comparable_areas
# Read specific state at a given year
>>> df = read_comparable_areas(year=)
"""
years_available = [
1872,
1900,
1911,
1920,
1933,
1940,
1950,
1960,
1970,
1980,
1991,
2000,
2010,
]
if (start_year not in years_available) or (end_year
not in years_available):
raise ValueError("Invalid `start_year` or `end_year`."
f"It must be one of the following: {years_available}")
metadata = select_metadata("amc", year=start_year, simplified=simplified)
metadata = metadata.query(
f'download_path.str.contains("{start_year}_{end_year}")')
gdf = download_gpkg(metadata)
return gdf
Year of the data, by default {{ default_year }}
simplified: boolean, by default True
Data 'type', indicating whether the function returns the 'original' dataset
with high resolution or a dataset with 'simplified' borders (Default)
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import {{ name }}
# Read specific state at a given year
>>> df = {{ name }}(year={{ default_year }})
"""
metadata = select_metadata('{{ metadata_key }}', year=year, simplified=simplified)
gdf = download_gpkg(metadata)
return gdf
def read_weighting_area(code_weighting='all',
year=2010,
simplified=True,
verbose=False):
""" Download shape files of Census Weighting Areas (area de ponderacao) of the Brazilian Population Census.
Only 2010 data is currently available.
Parameters
----------
code_weighting:
The 7-digit code of a Municipality. If the two-digit code or a two-letter uppercase abbreviation of
a state is passed, (e.g. 33 or "RJ") the function will load all weighting areas of that state.
If code_weighting="all", all weighting areas of the country are loaded.
year : int, optional
Year of the data, by default 2010
simplified: boolean, by default True
Data 'type', indicating whether the function returns the 'original' dataset
with high resolution or a dataset with 'simplified' borders (Default)
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import read_weighting_area
# Read specific state at a given year
>>> df = read_weighting_area(year=2010)
"""
metadata = select_metadata('weighting_area',
year=year,
simplified=simplified)
if code_weighting == 'all':
if verbose:
print(
'Loading data for the whole country. This might take a few minutes.'
)
return download_gpkg(metadata)
metadata = metadata[metadata[['code', 'code_abrev']].apply(
lambda x: str(code_weighting)[:2] in str(x['code'])
or # if number e.g. 12
str(code_weighting)[:2] in str(x['code_abrev']) # if UF e.g. RO
,
1)]
if not len(metadata):
raise Exception('Invalid Value to argument code_weighting.')
gdf = download_gpkg(metadata)
if len(str(code_weighting)) == 2:
return gdf
elif code_weighting in gdf['code_muni'].tolist():
return gdf.query(f'code_muni == {code_weighting}')
elif code_weighting in gdf['code_weighting'].tolist():
return gdf.query(f'code_weighting == {code_weighting}')
return gdf
def read_census_tract(
code_tract, year=2010, zone="urban", simplified=True, verbose=False
):
""" Download shape files of census tracts of the Brazilian Population Census (Only years 2000 and 2010 are currently available).
Parameters
----------
code_tract: int
The 7-digit code of a Municipality. If the two-digit code or a two-letter uppercase abbreviation of
a state is passed, (e.g. 33 or "RJ") the function will load all census tracts of that state. If code_tract="all",
all census tracts of the country are loaded.
year : int, optional
Year of the data, by default 2010
zone: string, optional
"urban" or "rural" census tracts come in separate files in the year 2000, by default urban
simplified: boolean, by default True
Data 'type', indicating whether the function returns the 'original' dataset
with high resolution or a dataset with 'simplified' borders (Default)
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import read_census_tract
# Read rural census tracts for years before 2007
>>> df = read_census_tract(code_tract=5201108, year=2000, zone='rural')
# Read all census tracts of a state at a given year
>>> df = read_census_tract(code_tract=53, year=2010) # or
>>> df = read_census_tract(code_tract="DF", year=2010)
# Read all census tracts of a municipality at a given year
>>> df = read_census_tract(code_tract=5201108, year=2010)
# Read all census tracts of the country at a given year
>>> df = read_census_tract(code_tract="all", year=2010)
"""
test_options(zone, "zone", allowed=["urban", "rural"])
test_options(code_tract, "code_tract", not_allowed=[None])
metadata = select_metadata("census_tract", year=year, simplified=simplified)
# For year <= 2007, the code, eg. U11, comes with a trailing letter U for urban and
# R for rural. So, this code checks if the trailing code letter is the same as
# the argument zone.
if year <= 2007:
metadata = metadata[
metadata["code"].apply(lambda x: x[0].lower() == zone[0].lower())
]
# [R]12 == [r]ural
if code_tract == "all":
if verbose:
print("Loading data for the whole country. This might take a few minutes.")
return download_gpkg(metadata)
else:
metadata = metadata[
metadata[["code", "code_abrev"]].apply(
lambda x: str(code_tract)[:2] in str(x["code"])
or str(code_tract)[:2] # if number e.g. 12
in str(x["code_abrev"]), # if UF e.g. RO
1,
)
]
gdf = download_gpkg(metadata)
if len(str(code_tract)) == 2:
return gdf
elif code_tract in gdf["code_muni"].tolist():
return gdf.query(f"code_muni == {code_tract}")
else:
raise Exception("Invalid Value to argument code_tract.")
def read_meso_region(code_meso="all", year=2010, simplified=True, verbose=False):
""" Download shape files of meso region as sf objects. Data at scale 1:250,000, using Geodetic reference system "SIRGAS2000" and CRS(4674)
Data at scale 1:250,000, using Geodetic reference system "SIRGAS2000" and CRS(4674)
Parameters
----------
code_meso: int or string, by default 'all'
The 4-digit code of a meso region. If the two-digit code or a two-letter uppercase abbreviation of
a state is passed, (e.g. 33 or "RJ") the function will load all meso regions of that state.
If code_meso="all", all meso regions of the country are loaded.
year : int, optional
Year of the data, by default 2010
simplified: boolean, by default True
Data 'type', indicating whether the function returns the 'original' dataset
with high resolution or a dataset with 'simplified' borders (Default)
verbose : bool, optional
by default False
Returns
-------
gpd.GeoDataFrame
Metadata and geopackage of selected states
Raises
------
Exception
If parameters are not found or not well defined
Example
-------
>>> from geobr import read_meso_region
# Read specific meso region at a given year
>>> df = read_meso_region(code_meso=3301, year=2018)
# Read all meso regions of a state at a given year
>>> df = read_meso_region(code_meso=12, year=2017)
>>> df = read_meso_region(code_meso="AM", year=2000)
# Read all meso regions of the country at a given year
>>> df = read_meso_region(code_meso="all", year=2010)
"""
metadata = select_metadata("meso_region", year=year, simplified=simplified)
if code_meso == "all":
if verbose:
print("Loading data for the whole country. This might take a few minutes.")
return download_gpkg(metadata)
metadata = metadata[
metadata[["code", "code_abrev"]].apply(
lambda x: str(code_meso)[:2] in str(x["code"])
or str(code_meso)[:2] # if number e.g. 12
in str(x["code_abrev"]), # if UF e.g. RO
1,
)
]
if not len(metadata):
raise Exception("Invalid Value to argument code_meso.")
gdf = download_gpkg(metadata)
if len(str(code_meso)) == 2:
return gdf
elif code_meso in gdf["code_meso"].tolist():
return gdf.query(f"code_meso == {code_meso}")
else:
raise Exception("Invalid Value to argument code_meso.")
def lookup_muni(name_muni=None, code_muni=None, verbose=False):
"""Lookup municipality codes and names.
By default, it looks for all municipalities. You can also use 'all' to in
`name_muni` or `code_muni` to get all municipalities.
Input a municipality NAME or CODE and get the names and codes of
the municipality's corresponding state, meso, micro, intermediate, and
immediate regions. You should not select both code_muni and name_muni
Parameters
----------
name_muni : str, optional
The municipality name to be looked up
code_muni: str, optional
The municipality code to be looked up
verbose : bool, optional
by default False
Returns
-------
pd.DataFram
13 columns identifying the geographies information of that municipality
Details Only available from 2010 Census data so far
Raise
-------
Exception if code_muni or name_muni cannot be found
Example
-------
>>> import geobr
# Lookup table for municipality of Rio de Janeiro
>>> mun = lookup_muni('Rio de Janeiro)
or
>>> mun = lookup_muni(3304557)
# lookup table for all municipalities
>>> mun_all = lookup_muni()
"""
# Get metadata with data url addresses
temp_meta = utils.select_metadata(geo="lookup_muni", year=2010)
# Read DataFrame available at provided url
lookup_table = utils.download_metadata(
temp_meta.loc[:, "download_path"].to_list()[0])
lookup_table["name_muni_format"] = lookup_table[
"name_muni_format"].str.lower()
# Search by inputs
if (code_muni == "all" or name_muni == "all"
or (code_muni is None and name_muni is None)):
if verbose:
print(f"Returning results for all municipalities")
return lookup_table.iloc[:, :-1]
elif code_muni is not None:
if name_muni is not None:
if verbose:
print("Ignoring argument name_muni")
try:
output = lookup_table[lookup_table["code_muni"] == int(
code_muni)].iloc[:, :-1]
if verbose:
print(
"Returning results for municipality ",
f'{output.loc[:, "name_muni"].to_list()[0]}',
)
return output
except KeyError:
raise Exception(
f"The `code_muni` argument {code_muni}",
"was not found in the database.",
)
elif name_muni is not None:
# Cleaning from accents and turning into lower cases without spaces
name_muni = utils.strip_accents(str(name_muni).lower().strip())
output = lookup_table[lookup_table["name_muni_format"] == name_muni]
if len(output) == 0:
if verbose:
print("Please insert a valid municipality name")
raise Exception(
f"The `name_muni` argument {name_muni} ",
"was not found in the database.",
)
else:
if verbose:
print("Returning results for municipality"
f'{output.loc[:, "name_muni"].to_list()[0]}')
return output.iloc[:, :-1]
elif code_muni == "all" and name_muni == "all":
if verbose:
print("Please insert either a municipality ",
"name or a municipality code")
