tunned-geobr 0.1.0__py3-none-any.whl

tunned_geobr/read_immediate_region.py

@@ -0,0 +1,81 @@
+from cursed_geobr.utils import select_metadata, download_gpkg, change_type_list, test_options
+
+
+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 cursed_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'")

tunned_geobr/read_indigenous_land.py

@@ -0,0 +1,44 @@
+from cursed_geobr.utils import select_metadata, download_gpkg
+
+
+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 cursed_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

tunned_geobr/read_intermediate_region.py

@@ -0,0 +1,61 @@
+from cursed_geobr.utils import select_metadata, download_gpkg
+
+
+def read_intermediate_region(
+    code_intermadiate="all", year=2019, simplified=True, verbose=False
+):
+    r"""Download spatial data of Brazil's Intermediate Geographic Areas
+
+    The intermediate Geographic Areas are part of the geographic division of
+    Brazil created in 2017 by IBGE. These regions were created to replace the
+    "Meso Regions" division. Data at scale 1:250,000, using Geodetic reference
+    system "SIRGAS2000" and CRS(4674)
+
+       Parameters
+       ----------
+       code_intermadiate: str or int, by default "all"
+            4-digit code of an intermediate 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 intermediate regions of that
+            state. If `code_intermediate="all"` (Default), all intermediate regions of
+            the country are loaded.
+       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 cursed_geobr import read_intermediate_region
+
+       # Read specific state at a given year
+       >>> df = read_intermediate_region(year=2019)
+    """
+
+    metadata = select_metadata("intermediate_regions", year=year, simplified=simplified)
+
+    gdf = download_gpkg(metadata)
+
+    if code_intermadiate == "all":
+        return gdf
+
+    for col in ["abbrev_state", "code_state", "code_intermediate"]:
+        if code_intermadiate in gdf[col].unique():
+            return gdf[gdf[col] == code_intermadiate]
+    else:
+        raise ValueError(
+            f"Invalid value to argumet `code_intermadiate`: {code_intermadiate}"
+        )

tunned_geobr/read_meso_region.py

@@ -0,0 +1,78 @@
+from cursed_geobr.utils import select_metadata, download_gpkg
+
+
+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 cursed_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_abbrev"]].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_abbrev"]),  # 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.")

tunned_geobr/read_metro_area.py

@@ -0,0 +1,44 @@
+from cursed_geobr.utils import select_metadata, download_gpkg
+
+
+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 cursed_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

tunned_geobr/read_micro_region.py

@@ -0,0 +1,78 @@
+from cursed_geobr.utils import select_metadata, download_gpkg
+
+
+def read_micro_region(code_micro="all", year=2010, simplified=True, verbose=False):
+    """Download shape files of micro region as sf objects
+
+     Data at scale 1:250,000, using Geodetic reference system "SIRGAS2000" and CRS(4674)
+
+    Parameters
+    ----------
+    code_micro:
+        5-digit code of a micro 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 micro regions of that state.
+        If code_micro="all", all micro 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 cursed_geobr import read_micro_region
+
+    # Read specific meso region at a given year
+    >>> df = read_micro_region(code_micro=11008, year=2018)
+
+    # Read all meso regions of a state at a given year
+    >>> df = read_micro_region(code_micro=12, year=2017)
+    >>> df = read_micro_region(code_micro="AM", year=2000)
+
+    # Read all meso regions of the country at a given year
+    >>> df = read_micro_region(code_micro="all", year=2010)
+    """
+
+    metadata = select_metadata("micro_region", year=year, simplified=simplified)
+
+    if code_micro == "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_abbrev"]].apply(
+            lambda x: str(code_micro)[:2] in str(x["code"])
+            or str(code_micro)[:2]  # if number e.g. 12
+            in str(x["code_abbrev"]),  # if UF e.g. RO
+            1,
+        )
+    ]
+
+    if not len(metadata):
+        raise Exception("Invalid Value to argument code_micro.")
+
+    gdf = download_gpkg(metadata)
+
+    if len(str(code_micro)) == 2:
+        return gdf
+
+    elif code_micro in gdf["code_micro"].tolist():
+        return gdf.query(f"code_micro == {code_micro}")
+
+    else:
+        raise Exception("Invalid Value to argument code_micro.")

tunned_geobr/read_mining_processes.py

@@ -0,0 +1,76 @@
+import geopandas as gpd
+import tempfile
+import os
+import requests
+from zipfile import ZipFile
+from io import BytesIO
+
+def read_mining_processes(simplified=False):
+    """Download official mining process data from ANM (National Mining Agency).
+    
+    This function downloads and processes mining permit data from Brazil's National Mining Agency (ANM).
+    The data includes all mining processes such as research permits, mining concessions, etc.
+    Original source: SIGMINE/ANM
+    
+    Parameters
+    ----------
+    simplified : boolean, by default True
+        If True, returns a simplified version of the dataset with fewer columns
+        
+    Returns
+    -------
+    gpd.GeoDataFrame
+        Geodataframe with mining process data
+        
+    Example
+    -------
+    >>> from cursed_geobr import read_mining_processes
+    
+    # Read mining processes data
+    >>> mining = read_mining_processes()
+    """
+    
+    url = "https://app.anm.gov.br/dadosabertos/SIGMINE/PROCESSOS_MINERARIOS/BRASIL.zip"
+    
+    try:
+        # Download the zip file with SSL verification disabled (use with caution)
+        response = requests.get(url, verify=False)
+        if response.status_code != 200:
+            raise Exception("Failed to download data from ANM")
+        
+        # Suppress SSL verification warnings
+        import warnings
+        warnings.filterwarnings('ignore', message='Unverified HTTPS request')
+            
+        # Create a temporary directory
+        with tempfile.TemporaryDirectory() as temp_dir:
+            # Extract zip content
+            with ZipFile(BytesIO(response.content)) as zip_ref:
+                zip_ref.extractall(temp_dir)
+                
+            # Find the shapefile
+            shp_files = [f for f in os.listdir(temp_dir) if f.endswith('.shp')]
+            if not shp_files:
+                raise Exception("No shapefile found in the downloaded data")
+                
+            # Read the shapefile
+            gdf = gpd.read_file(os.path.join(temp_dir, shp_files[0]))
+            
+            if simplified:
+                # Keep only the most relevant columns
+                columns_to_keep = [
+                    'geometry',
+                    'PROCESSO',
+                    'FASE',
+                    'NOME',
+                    'SUBS',
+                    'USO',
+                    'UF',
+                    'AREA_HA'
+                ]
+                gdf = gdf[columns_to_keep]
+    
+    except Exception as e:
+        raise Exception(f"Error downloading mining processes data: {str(e)}")
+        
+    return gdf

tunned_geobr/read_municipal_seat.py

@@ -0,0 +1,41 @@
+from cursed_geobr.utils import select_metadata, download_gpkg
+
+
+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 cursed_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

tunned_geobr/read_municipality.py

@@ -0,0 +1,83 @@
+from cursed_geobr.utils import select_metadata, download_gpkg
+
+
+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 cursed_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_abbrev"]].apply(
+            lambda x: str(code_muni)[:2] in str(x["code"])
+            or str(code_muni)[:2]  # if number e.g. 12
+            in str(x["code_abbrev"]),  # 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

tunned_geobr/read_neighborhood.py

@@ -0,0 +1,39 @@
+from cursed_geobr.utils import select_metadata, download_gpkg
+
+
+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 cursed_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