amazonasdatahub 0.2.4__tar.gz

amazonasdatahub-0.2.4/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026, Nelson Geraldo Aquino de Carvalho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

amazonasdatahub-0.2.4/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: amazonasdatahub
+Version: 0.2.4
+Summary: The goal of amazonasdatahub is to gather various data sets from the state of Amazonas (AM), Brazil, to which Deep Learning can be applied.
+License: MIT
+License-File: LICENSE
+Author: Nelson Geraldo Aquino de Carvalho
+Requires-Python: >=3.12,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: pandas (>=3.0.2,<4.0.0)
+Requires-Dist: pyarrow (>=24.0.0,<25.0.0)
+Requires-Dist: python-frontmatter (>=1.1.0,<2.0.0)
+Requires-Dist: requests (>=2.33.1,<3.0.0)
+Description-Content-Type: text/markdown
+
+# amazonasdatahub
+
+![amazonasdatahub logo](assets/figures/logo_amazonasdatahub_small.png)
+<!-- badges: start -->
+
+<!-- badges: end -->
+
+The goal of `amazonasdatahub` is to aggregate databases from the State
+of Amazonas (AM), Brazil, for conducting studies and preparing
+educational materials, as well as to facilitate access to organized and
+processed data, thereby supporting research and teaching and enabling
+the application of statistical methods.
+
+Full documentation of both Python and R versions is available in the
+following languages/Documentação das versões em Python e R estão
+disponíveis nos seguintes idiomas:
+
+- [English
+  documentation](https://onelsoncarvalho.github.io/amazonasdatahubsite/en/)
+- [🇧🇷 Documentação em Português
+  (BR)](https://onelsoncarvalho.github.io/amazonasdatahubsite/)
+
+Python only documentation:
+
+- [English documentation for Python
+  version](https://onelsoncarvalho.github.io/amazonasdatahubpy/en/)
+- [🇧🇷 Documentação em Português (BR) para versão do
+  Python](https://onelsoncarvalho.github.io/amazonasdatahubpy/br/)
+
+## Overview
+
+This `amazonasdatahub` package provides databases from various types and
+sources, all of which concern the State of Amazonas.
+
+List of available datasets:
+
+| Dataset | Area | Source |
+|:---|:--:|:---|
+| agriculture_amazonas | Agriculture and Livestock | Institute of Agricultural and Sustainable Forestry Development of the State of Amazonas - 2024 |
+| aids_amazonas | Health | Department of HIV, AIDS, Tuberculosis, Viral Hepatitis, and Sexually Transmitted Infections, 2024 |
+| gdp_amazonas | Economy | Scientific Journal of Applied Social and Clinical Science - TIME SERIES ANALYSIS FOR THE QUARTERLY GROSS DOMESTIC PRODUCT OF AMAZONAS |
+| humidity_manaus | Climate | NASCIMENTO, Leonardo Brandão Freitas; LIMA, Max Sousa; DUCZMAL, Luiz H. P-min-stable regression models for time series with extreme values of limited range. Environmetrics, Issue 2, v. 36, 2025. |
+| malaria_amazonas | Health | Lais Baroni, M. P. (2020). An Integrated Dataset of Malaria Notifications in the Legal Amazon (Dataset). Synapse. <https://doi.org/10.7303/SYN21552203> |
+| prf_amazonas | Road Safety | Brasil. Polícia Rodoviária Federal (PRF). Dados Abertos da PRF: Acidentes de Trânsito |
+| rionegro_amazonas | Environment | Porto de Manaus. Nível do Rio Negro |
+| srl_muni | Education | ALMEIDA, Thiago da Cruz de. Physical Literacy e desempenho em leitura de escolares amazônicos: um estudo de associação. 2024. 104 f. Dissertação (Mestrado em Educação) - Universidade Federal do Amazonas, Manaus, 2024. |
+
+## Installation
+
+To install `amazonasdatahub`, you need the following tools installed on your computer or development environment:
+
+- Python 3.14.3
+- `pip` (package manager)
+- Git
+
+You can install the development version of `amazonasdatahub` using `git clone` to clone the remote repository into your local environment and `pip` to install it:
+``` 
+# cloning
+git clone https://github.com/onelsoncarvalho/amazonasdatahubpy amazonasdatahub
+cd amazonasdatahub
+
+# installing
+pip install amazonasdatahub
+```
+
+## Usage and Examples
+
+### Loading `amazonasdatahub`
+
+Use `import` and `from` to require the functions from `datasets` module of `amazonasdatahub`:
+
+``` python
+from amazonasdatahub.datasets import get_dataset
+```
+
+The dataset name should be provided as argument of `get_dataset(dataset: str)` function.
+
+```python
+agriculture_amazonas = get_dataset('agriculture_amazonas')
+aids_amazonas = get_dataset('aids_amazonas')
+gdp_amazonas = get_dataset('gdp_amazonas')
+```
+
+### Get dataset documentation
+
+Each dataset has its own documentation to provide the user information about the dataset variables.
+
+Use `import` and `from` to require the functions from `docs` module:
+
+```python
+from amazonasdatahub.docs import get_doc
+```
+
+The dataset name should be provided as argument of `get_docs(dataset: str)` function.
+
+```python
+get_doc('agriculture_amazonas')
+get_doc('aids_amazonas')
+get_doc('gdp_amazonas')
+```
+
+<!-- ### Examples
+
+#### Disease occurrence
+
+The dataset `aids_amazonas` contains data of the AIDS occurrences in
+each municipality from Amazonas.
+
+One of the analysis that can be made is: visualize the time series of
+counts filtered by municipality, where each case is grouped by the
+sex/gender of each observation. To do this, we will use the dplyr
+package to structure the data and the ggplot2 package to create and
+customize the chart.
+
+``` r
+# Loading dplyr and ggplot to structure the data
+require(dplyr)
+require(ggplot2)
+```
+
+``` r
+# Filtering by municipality and plotting case count by gender
+aids_amazonas %>%
+  filter(name_muni == "Manaus") %>%
+  group_by(gender) %>%
+  ggplot(aes(x = year, y = cases, group = gender, color = gender)) +
+  geom_line() +
+  scale_color_manual(values = c("blue", "red")) +
+  theme_minimal() +
+  labs(
+    title = "AIDS occurrences in Manaus (2011-2023)",
+    x = "Year",
+    y = "Case count",
+    color = "Gender"
+  )
+```
+
+<img src="man/figures/README-unnamed-chunk-6-1.png" alt="" width="100%" />
+
+#### Time Series
+
+The `humidity_manaus` consists of the minimum relative humidity observed
+in the city of Manaus from January 2009 to December 2020. We can
+visualize the time series of the relative humidity during this time
+interval.
+
+Using `dplyr`, it is possible to create a date column, which will be
+composed of the month and year. Using`ggplot2`, the time series chart
+can be plotted.
+
+``` r
+# Loading dplyr and ggplot to structure the data
+require(dplyr)
+require(ggplot2)
+
+# Creating date column and plotting the time series
+humidity_manaus %>%
+  mutate(date = as.Date(paste0(year, "-", month, "-","01"))) %>%
+  ggplot(aes(x = date, y = rh)) +
+  geom_line() +
+  theme_minimal() +
+  labs(
+    title = "Relative Humidity of Amazonas (2009-2020)",
+    x = "Date",
+    y = "Relative Humidity"
+  )
+```
+
+<img src="man/figures/README-unnamed-chunk-7-1.png" alt="" width="100%" /> -->
+
+
+## Contributing
+
+Interested in contributing? Check out the contributing guidelines. Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.
+
+## License
+
+`amazonasdatahub` was created by Nelson Geraldo Aquino de Carvalho. It is licensed under the terms of the MIT license.
+
+<!-- ## Credits
+
+`amazonasdatahub` was created with [`cookiecutter`](https://cookiecutter.readthedocs.io/en/latest/) and the `py-pkgs-cookiecutter` [template](https://github.com/py-pkgs/py-pkgs-cookiecutter). -->
+
+## Citation
+
+- CARVALHO, Nelson Geraldo Aquino de; NASCIMENTO, Leonardo Brandão
+  Freitas do. **amazonasdatahub**. 2026.
+  <https://onelsoncarvalho.github.io/amazonasdatahubpy>.
+
+

amazonasdatahub-0.2.4/README.md

@@ -0,0 +1,189 @@
+# amazonasdatahub
+
+![amazonasdatahub logo](assets/figures/logo_amazonasdatahub_small.png)
+<!-- badges: start -->
+
+<!-- badges: end -->
+
+The goal of `amazonasdatahub` is to aggregate databases from the State
+of Amazonas (AM), Brazil, for conducting studies and preparing
+educational materials, as well as to facilitate access to organized and
+processed data, thereby supporting research and teaching and enabling
+the application of statistical methods.
+
+Full documentation of both Python and R versions is available in the
+following languages/Documentação das versões em Python e R estão
+disponíveis nos seguintes idiomas:
+
+- [English
+  documentation](https://onelsoncarvalho.github.io/amazonasdatahubsite/en/)
+- [🇧🇷 Documentação em Português
+  (BR)](https://onelsoncarvalho.github.io/amazonasdatahubsite/)
+
+Python only documentation:
+
+- [English documentation for Python
+  version](https://onelsoncarvalho.github.io/amazonasdatahubpy/en/)
+- [🇧🇷 Documentação em Português (BR) para versão do
+  Python](https://onelsoncarvalho.github.io/amazonasdatahubpy/br/)
+
+## Overview
+
+This `amazonasdatahub` package provides databases from various types and
+sources, all of which concern the State of Amazonas.
+
+List of available datasets:
+
+| Dataset | Area | Source |
+|:---|:--:|:---|
+| agriculture_amazonas | Agriculture and Livestock | Institute of Agricultural and Sustainable Forestry Development of the State of Amazonas - 2024 |
+| aids_amazonas | Health | Department of HIV, AIDS, Tuberculosis, Viral Hepatitis, and Sexually Transmitted Infections, 2024 |
+| gdp_amazonas | Economy | Scientific Journal of Applied Social and Clinical Science - TIME SERIES ANALYSIS FOR THE QUARTERLY GROSS DOMESTIC PRODUCT OF AMAZONAS |
+| humidity_manaus | Climate | NASCIMENTO, Leonardo Brandão Freitas; LIMA, Max Sousa; DUCZMAL, Luiz H. P-min-stable regression models for time series with extreme values of limited range. Environmetrics, Issue 2, v. 36, 2025. |
+| malaria_amazonas | Health | Lais Baroni, M. P. (2020). An Integrated Dataset of Malaria Notifications in the Legal Amazon (Dataset). Synapse. <https://doi.org/10.7303/SYN21552203> |
+| prf_amazonas | Road Safety | Brasil. Polícia Rodoviária Federal (PRF). Dados Abertos da PRF: Acidentes de Trânsito |
+| rionegro_amazonas | Environment | Porto de Manaus. Nível do Rio Negro |
+| srl_muni | Education | ALMEIDA, Thiago da Cruz de. Physical Literacy e desempenho em leitura de escolares amazônicos: um estudo de associação. 2024. 104 f. Dissertação (Mestrado em Educação) - Universidade Federal do Amazonas, Manaus, 2024. |
+
+## Installation
+
+To install `amazonasdatahub`, you need the following tools installed on your computer or development environment:
+
+- Python 3.14.3
+- `pip` (package manager)
+- Git
+
+You can install the development version of `amazonasdatahub` using `git clone` to clone the remote repository into your local environment and `pip` to install it:
+``` 
+# cloning
+git clone https://github.com/onelsoncarvalho/amazonasdatahubpy amazonasdatahub
+cd amazonasdatahub
+
+# installing
+pip install amazonasdatahub
+```
+
+## Usage and Examples
+
+### Loading `amazonasdatahub`
+
+Use `import` and `from` to require the functions from `datasets` module of `amazonasdatahub`:
+
+``` python
+from amazonasdatahub.datasets import get_dataset
+```
+
+The dataset name should be provided as argument of `get_dataset(dataset: str)` function.
+
+```python
+agriculture_amazonas = get_dataset('agriculture_amazonas')
+aids_amazonas = get_dataset('aids_amazonas')
+gdp_amazonas = get_dataset('gdp_amazonas')
+```
+
+### Get dataset documentation
+
+Each dataset has its own documentation to provide the user information about the dataset variables.
+
+Use `import` and `from` to require the functions from `docs` module:
+
+```python
+from amazonasdatahub.docs import get_doc
+```
+
+The dataset name should be provided as argument of `get_docs(dataset: str)` function.
+
+```python
+get_doc('agriculture_amazonas')
+get_doc('aids_amazonas')
+get_doc('gdp_amazonas')
+```
+
+<!-- ### Examples
+
+#### Disease occurrence
+
+The dataset `aids_amazonas` contains data of the AIDS occurrences in
+each municipality from Amazonas.
+
+One of the analysis that can be made is: visualize the time series of
+counts filtered by municipality, where each case is grouped by the
+sex/gender of each observation. To do this, we will use the dplyr
+package to structure the data and the ggplot2 package to create and
+customize the chart.
+
+``` r
+# Loading dplyr and ggplot to structure the data
+require(dplyr)
+require(ggplot2)
+```
+
+``` r
+# Filtering by municipality and plotting case count by gender
+aids_amazonas %>%
+  filter(name_muni == "Manaus") %>%
+  group_by(gender) %>%
+  ggplot(aes(x = year, y = cases, group = gender, color = gender)) +
+  geom_line() +
+  scale_color_manual(values = c("blue", "red")) +
+  theme_minimal() +
+  labs(
+    title = "AIDS occurrences in Manaus (2011-2023)",
+    x = "Year",
+    y = "Case count",
+    color = "Gender"
+  )
+```
+
+<img src="man/figures/README-unnamed-chunk-6-1.png" alt="" width="100%" />
+
+#### Time Series
+
+The `humidity_manaus` consists of the minimum relative humidity observed
+in the city of Manaus from January 2009 to December 2020. We can
+visualize the time series of the relative humidity during this time
+interval.
+
+Using `dplyr`, it is possible to create a date column, which will be
+composed of the month and year. Using`ggplot2`, the time series chart
+can be plotted.
+
+``` r
+# Loading dplyr and ggplot to structure the data
+require(dplyr)
+require(ggplot2)
+
+# Creating date column and plotting the time series
+humidity_manaus %>%
+  mutate(date = as.Date(paste0(year, "-", month, "-","01"))) %>%
+  ggplot(aes(x = date, y = rh)) +
+  geom_line() +
+  theme_minimal() +
+  labs(
+    title = "Relative Humidity of Amazonas (2009-2020)",
+    x = "Date",
+    y = "Relative Humidity"
+  )
+```
+
+<img src="man/figures/README-unnamed-chunk-7-1.png" alt="" width="100%" /> -->
+
+
+## Contributing
+
+Interested in contributing? Check out the contributing guidelines. Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.
+
+## License
+
+`amazonasdatahub` was created by Nelson Geraldo Aquino de Carvalho. It is licensed under the terms of the MIT license.
+
+<!-- ## Credits
+
+`amazonasdatahub` was created with [`cookiecutter`](https://cookiecutter.readthedocs.io/en/latest/) and the `py-pkgs-cookiecutter` [template](https://github.com/py-pkgs/py-pkgs-cookiecutter). -->
+
+## Citation
+
+- CARVALHO, Nelson Geraldo Aquino de; NASCIMENTO, Leonardo Brandão
+  Freitas do. **amazonasdatahub**. 2026.
+  <https://onelsoncarvalho.github.io/amazonasdatahubpy>.
+

amazonasdatahub-0.2.4/pyproject.toml

@@ -0,0 +1,31 @@
+[tool.poetry]
+name = "amazonasdatahub"
+version = "0.2.4"
+description = "The goal of amazonasdatahub is to gather various data sets from the state of Amazonas (AM), Brazil, to which Deep Learning can be applied."
+authors = ["Nelson Geraldo Aquino de Carvalho"]
+license = "MIT"
+readme = "README.md"
+packages = [{ include = "amazonasdatahub", from = "src" }]
+
+[tool.poetry.dependencies]
+python = "^3.12"
+pandas = "^3.0.2"
+python-frontmatter = "^1.1.0"
+requests = "^2.33.1"
+pyarrow = "^24.0.0"
+
+[tool.poetry.group.dev.dependencies]
+myst-nb = ">=1.3.0,<1.4.0"
+sphinx-autoapi = ">=3.8.1,<4.0.0"
+shibuya = ">=2026.7.12,<2027.0.0"
+matplotlib = "^3.11.2"
+deepl = ">=1.32.0,<2.0.0"
+polib = ">=1.2.0,<2.0.0"
+sphinx-intl = ">=2.4.0,<3.0.0"
+sphinx-autobuild = ">=2025.8.25,<2026.0.0"
+pytest = ">=9.2.0,<10.0.0"
+pytest-cov = ">=7.1.0,<8.0.0"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"

amazonasdatahub-0.2.4/src/amazonasdatahub/__init__.py

@@ -0,0 +1,3 @@
+# read version from installed package
+from importlib.metadata import version
+__version__ = version("amazonasdatahub")

amazonasdatahub-0.2.4/src/amazonasdatahub/datasets.py

@@ -0,0 +1,36 @@
+import pandas as pd
+import requests
+from pathlib import Path
+
+CACHE_DIR = Path.home() / ".cache" / "amazonasdatahub"
+CACHE_DIR.mkdir(parents = True, exist_ok=True)
+
+def get_dataset(dataset_name, force=False):
+    """
+    Gather an specific dataset.
+    :param dataset_name: Dataset name (example: agriculture_amazonas)
+    :param force: If True, ignores the cache and downloads the dataset again
+    """
+
+    file_name = f"{dataset_name}.parquet"
+    local_path = CACHE_DIR / file_name 
+    url = f"https://github.com/onelsoncarvalho/amazonasdatahubpy/raw/refs/heads/main/raw_data/{file_name}"
+
+    if force or not local_path.exists():
+        print(f"Gathering updated data from {url}...")
+        try:
+            response = requests.get(url)
+            response.raise_for_status()
+
+            with open(local_path, "wb") as f:
+                f.write(response.content)
+            print(f"Saved in: {local_path}")
+
+        except Exception as e:
+            if not local_path.exists():
+                raise Exception(f"Error while downloading and there is no cache available: {e}")
+            print(f"Warning: Download error, using old cache version. Error: {e}")
+
+    return pd.read_parquet(local_path)
+
+

amazonasdatahub-0.2.4/src/amazonasdatahub/docs.py

@@ -0,0 +1,33 @@
+import frontmatter
+from importlib import resources
+
+
+def get_doc(dataset_name):
+    """
+    Shows the documentation of a dataset
+    """
+
+    try:
+        md_path = resources.files("amazonasdatahub.documentations").joinpath(f"{dataset_name}.md")
+        if not md_path.exists():
+            print(f"Docs for {dataset_name} not found")
+            return
+
+        md_content = md_path.read_text(encoding = "utf-8")
+
+        loaded_md = frontmatter.loads(md_content)
+
+        title = loaded_md.get('title', dataset_name.upper())
+        body = loaded_md.content
+
+        print(f"\n{'='*60}")
+        print(f"Documentation from: {title}")
+        print(f"{'='*60}")
+
+        try :
+            from IPython.display import display, Markdown
+            display(Markdown(body))
+        except ImportError:
+            print(body)
+    except Exception as e:
+        print(f"Error while processing docs: {e}")

amazonasdatahub-0.2.4/src/amazonasdatahub/documentations/agriculture_amazonas.md

@@ -0,0 +1,109 @@
+---
+title: "agriculture_amazonas"
+---
+
+# agriculture_amazonas
+
+Plant production data from the Institute of Sustainable Agricultural and Forestry Development of Amazonas - IDAM (2023).
+
+### Description
+
+This database, which is the consolidation of data from IDAM's activity reports, provides crop production data for crops that this institute considers a priority.
+
+### Usage
+
+```python
+agriculture_amazonas = get_dataset("agriculture_amazonas")
+```
+
+### Format
+
+‘agriculture_amazonas’ A data frame with 1072 rows and 13 columns:
+
+#### municipality
+
+Municipality
+
+#### local_unit
+
+Local Unit of the Institute
+
+#### n_beneficiary
+
+Number of assisted beneficiaries
+
+#### planted
+
+Planted area in hectares (ha)
+
+#### harvested
+
+Harvested area in hectares (ha)
+
+#### production
+
+Production (in the unit of measurement - measure)
+
+#### estimated_n_beneficiary
+
+Estimate of the number of beneficiaries
+
+#### estimated_planted
+
+Estimate of the planted area (ha)
+
+#### estimated_harvested
+
+Estimate of the harvested area (ha)
+
+#### estimated_production
+
+Estimate of production (in the unit of measurement - measure)
+
+#### measure
+
+Unit of Measurement of production
+
+
+#### cultivation
+
+Cultivation
+
+#### year
+
+Year of cultivation
+
+### Source
+
+https://www.idam.am.gov.br/biblioteca/relatorio-de-atividades-rat-23-2/
+
+
+### Example
+
+```python
+import matplotlib.pyplot as plt
+from amazonasdatahub.datasets import get_dataset
+
+# Loading data
+agriculture_amazonas = get_dataset("agriculture_amazonas")
+
+# Filtering data
+mandioca_prod = agriculture_amazonas[
+  agriculture_amazonas["cultivation"] == "Mandioca"
+]
+
+# Scatterplot
+plt.figure(figsize=(8,6))
+plt.scatter(
+  mandioca_prod["planted"],
+  mandioca_prod["harvested"],
+  alpha=0.7,
+  edgecolors="none"
+)
+plt.xlabel("Planted area (hectare)")
+plt.ylabel("Harvested area (hectare)")
+plt.title("Cassava production in Amazonas")
+plt.grid(True, linestyle="--", alpha=0.5)
+plt.tight_layout()
+plt.show()
+```