basedosdados / mais

⚙️ Código de manutenção do datalake (metadados e pacotes de acesso) | 📖 Docs: https://basedosdados.github.io/mais/

Universalizando o acesso a dados de qualidade no Brasil.

A Base dos Dados Mais (BD+) é um datalake público no Google BigQuery com os principais conjuntos de dados abertos do Brasil. Na BD+ você encontra tabelas tratadas e prontas para uso de forma gratuita. Disponibilizamos e mantemos neste projeto pacotes de acesso à BD+ em diferentes linguagens.

O projeto faz parte da Base dos Dados, uma organização sem fins lucrativos com a missão de universalizar o acesso a dados de qualidade para todes.

Versões atuais

R	Python	Stata
install.packages("basedosdados")	pip install basedosdados	-

Encontre aqui

• 📝 Como citar o projeto
• 🐍 Usando em Python
• Usando em R
• Análises e tutoriais:
  • Códigos de análises publicadas nas redes, workshops e artigos ↗
  • Youtube ↗
  • Medium ↗
• ⚙️ Desenvolvimento
• 👥 Como contribuir ↗
• 💚 Apoie o projeto! ↗

Como citar o projeto

O projeto (software) está sob licenca MIT - logo, pode ser utilizado e modificado sem restrições desde que sejam remetidos os direitos autorais originais - veja o texto de referência aqui.

Caso queira citar o projeto numa publicação, artigo ou na web, utilize o modelo no menu ao lado conforme a imagem.

💡 Quer divulgar seu projeto nas nossas redes? Envie para [email protected]

Usando em Python

Instale

pip install basedosdados

Acesse uma tabela

import basedosdados as bd

df = bd.read_table('br_ibge_pib', 'municipio', billing_project_id="<YOUR-PROJECT>")

Caso esteja acessando da primeira vez, vão aparecer alguns passos na tela para autenticar seu projeto - basta segui-los!

É necessário criar um projeto para que você possa fazer as queries no nosso repositório. Ter um projeto é de graça e basta ter uma conta Google (seu gmail por exemplo). Veja aqui como criar um projeto no Google Cloud.

Se possível, armazene suas credenciais em um arquivo dotenv: "billing_project_id=<suas_credenciais_do_projeto>" >> .env

Faça uma consulta

import basedosdados as bd

# Bens dos candidatos de Tocantins em 2020
query = """
SELECT *
FROM `basedosdados.br_tse_eleicoes.bens_candidato` 
WHERE ano = 2020
AND sigla_uf = 'TO'
"""

df = bd.read_sql(query, billing_project_id="<YOUR-PROJECT>")

Caso esteja acessando da primeira vez, vão aparecer alguns passos na tela para autenticar seu projeto - basta segui-los!

Veja todos os datasets disponíveis

import basedosdados as bd 

bd.list_datasets()

Defina paramêtros utilizando as configurações do pacote

import basedosdados as bd

# seta o billing_project_id global
bd.config.billing_project_id =  '<billing-project-id>'

query = """
SELECT 
    * 
FROM `basedosdados.br_bd_diretorios_brasil.municipio`
"""

df = bd.read_sql(query=query)

Para saber mais, veja os exemplos ou a documentação da API

Criando múltiplas configurações

Caso você precise ter uma configuração adicional, com uma service account diferente, você pode criar uma configuração e utilizá-la em conjunto com a default, apenas alterando um atributo. Você deverá fazer o processo abaixo usando o terminal, mas esta forma só funcionará no Python.

Para isso, siga os seguintes passos:

1. Renomeie a pasta com o comando abaixo (pode ser o nome que quiser)

   mv ~/.basedosdados ~/.basedosdados_default

2. Neste momento, o pacote não terá a configuração padrão. Assim, ao rodar o comando

     basedosdados config init

   ele irá criar uma nova configuração padrão, que será salva na pasta ~/.basedosdados (que será recriada). Lembre-se de, no passo em que é oferecido um link do Google Cloud Platform (GCP) para criar a nova service account, observar que seu navegador esteja logado com a conta que você deseja utilizar.
3. Faça todo o processo como anteriormete, passando os parâmetros que deseja utilizar com esta nova conta, como o path dos metadados, o nome do bucket do Google Cloud Storage, etc.
4. Ao salvar as novas service accounts (prod e staging), certifique-se de salvar na pasta .basedosdados criada no passo 1. Na verdade, esta é apenas a repetição do processo de criação de uma nova configuração.
5. Renomeie a pasta criada no passo 1 para o nome que desejar, como ~/.bd_minha_nova_conta.
6. Caso você queira que a primeira configuração seja a padrão, retorne o nome da pasta modificada anterioremnte (.basedosdados_default) para o valor utilizado como padrão pelo pacote basedosdados, usando o comando mv ~/.basedosdados_default ~/.basedosdados.
7. A partir de agora, você poderá usar a nova conta (no Python), bastando utilizar o seguinte processo:

   import basedosdados as bd
   bd.config.project_config_path = f"{home}/.bd_minha_nova_conta"

   e, se quiser voltar para a configuração padrão, basta utilizar o comando

   bd.config.project_config_path = f"{home}/.basedosdados"

   Importante observar que, ao alterar o path de configuração do Python ele valerá para a sessão. Então é recomendável que ele seja usado com cuidado, evitanto trocas numa mesma sessão - especialmente quando estiver usando Jupyter Notebook onde é comum a reutilização de células anteriores, sem redefinição de variáveis e atributos anteriormente setados.

Usando em R

Instalação

install.packages("basedosdados")

# ou a versão de desenvolvimento

devtools::install_github("basedosdados/mais", subdir = "r-package")

Consultas

read_sql executa queries no banco e as devolve em dataframes (sempre na classe tibble), download escreve o resultado da query em um arquivo .csv no disco.

library(basedosdados)

set_billing_id("id do seu projeto aqui") # autenticação para acesso aos dados

pib_per_capita <- " 
SELECT 
    pib.id_municipio ,
    pop.ano, 
    pib.PIB / pop.populacao as pib_per_capita
FROM `basedosdados.br_ibge_pib.municipio` as pib
  INNER JOIN `basedosdados.br_ibge_populacao.municipio` as pop
  ON pib.id_municipio = pop.id_municipio AND pib.ano = pop.ano"

(data <- read_sql(pib_per_capita)) # leia os dados em memória
download(pib_per_capita, "pib_per_capita.csv") # salve os dados em disco

Ou use o nosso backend para o dplyr e faça queries com código, sem SQL.

  query <- basedosdados::bdplyr("br_inep_ideb.municipio") %>% 
    dplyr::select(ano, id_municipio, sigla_uf, ideb) %>% 
    dplyr::filter(sigla_uf == "AC", ano < 2021) %>% 
    dplyr::group_by(ano) %>% 
    dplyr::summarise(ideb_medio = mean(ideb, na.rm = TRUE)) 

  basedosdados::bd_collect(query) # retorne como um tibble
  basedosdados::bd_write_csv(query, "ideb_medio.csv") 
  basedosdados::bd_write_rds(query, "ideb_medio.rds") 

bd_write é uma extensão para formatos customizados.

  basedosdados::bd_write(query, .write_fn = writexl::write_xlsx, "ideb_medio.xlsx")
  basedosdados::bd_write(query, .write_fn = jsonlite::write_json, "ideb_medio.json")
  basedosdados::bd_write(query, .write_fn = haven::write_dta, "ideb_medio.dta")

O argumento .write_fn espera uma função que receba como argumento um tibble e um endereço de escrita, compatível com a interface convencional da língua para escrever arquivos em disco. A princípio, toda função write_* disponível no CRAN deve funcionar.

Caso encontre algum problema no pacote e queira ajudar, basta documentar o problema em um exemplo mínimo reprodutível e abrir uma issue.

Metadados e buscas

Você pode fazer buscas por tabelas usando palavras-chave ou buscar descrições de conjuntos e tabelas:

dataset_search("educação")
get_dataset_description("br_sp_alesp")
get_table_description("br_sp_alesp", "deputado")

Atenção

Caso esteja acessando da primeira vez, vão aparecer alguns passos na tela para autenticar seu projeto com sua conta google e possivelmente na Tidyverse API - basta segui-los! As credenciais ficam armazenadas no computador então usuários com mais de uma máquina talvez precisem autenticar mais de uma vez. É necessário criar um projeto para que você possa fazer as queries no nosso repositório. Ter um projeto é de graça e basta ter uma conta Google (seu gmail por exemplo). Veja aqui como criar um projeto no Google Cloud. Se possível, armazene suas credenciais em um arquivo dotenv, em bash o comando é "billing_project_id=<suas_credenciais_do_projeto>" >> .env. Veja aqui como criar um arquivo dotenv.

Desenvolvimento

Roadmap

• Primeiro semestre 2022

Documentação

Para rodar a documentação localmente:

python -m venv .mais # cria ambiente virtual (só rodar da primeira vez)
. .mais/bin/activate # ativa ambiente virtual
pip install --upgrade  -r python-package/requirements-dev.txt # instala dependências
python python-package/setup.py develop # instala pacote local
mkdocs serve # cria documentacao em: http://localhost:8000/

Atualize os docs adicionando ou editando os arquivos .md em docs/.

Para adicionar seu arquivo no sumário da documentação, adicione-o em mkdocs.yml sob a chave nav:

nav:
  - Home:
    - Aprenda sobre a BD: index.md
    - BigQuery: access_data_bq.md
    - Pacotes: access_data_packages.md
    - Contribua: colab.md
    - [Seu novo título]: <seu_arquivo>.md

mais's Issues

Compatibilizar grupos para a busca da Base dos Dados.

Improve CLI help strings

Add some examples on how to use it

change staging database name order

Adicionar a opção de deletar o folder todo para dataset/table/storage

Add new functionalities to CLI

Staging name in table

reestructure columns and schema

Add tests to table class

Improve auto casting in publish.sql

Leitura do CSV pode indicar se é STRING ou NUMERIC

[infra] Ter uma tabela de instituições para preenchimento de configs.

Ideia seria cada instituição ter um ID, e incluirmos informações sobre (nome, website, email, etc). Na hora de criar tabelas, não precisaríamos repetir o preenchimento toda vez.

Será útil para instituições grandes, como IBGE, Ipea, TSE, etc.

Criar padrão para nomeação de variáveis.

Exemplos:

• Variáveis de porcentagem/proporção.
  prefixo: prop_
  valor máximo: 100

• Variáveis de log/ln.
  prefixo: ln_

Analisar casos de diferentes schema modes no update da tabela

Comandos de download do CLI não devem exigir arquivo de config

finish description template

Accept partitions in Storage and Table

Erro com download em Python

Rodei:

import basedosdados as bd

bd.download(savepath="~/Downloads/test.csv",dataset_id='br_suporte',table_id='diretorio_municipios')

e deu

---------------------------------------------------------------------------
OSError                                   Traceback (most recent call last)
<ipython-input-1-c0f5299e96d1> in <module>
      1 import basedosdados as bd
      2 
----> 3 bd.download(savepath="~/Downloads/test.csv",dataset_id='br_suporte',table_id='diretorio_municipios')

/Library/Frameworks/Python.framework/Versions/3.8/lib/python3.8/site-packages/basedosdados/download.py in download(savepath, query, dataset_id, table_id, project_id, limit, **pandas_kwargs)
     58 
     59     if (dataset_id is not None) and (table_id is not None):
---> 60         table = read_table(dataset_id, table_id, limit=limit)
     61     elif query is not None:
     62         if limit is not None:

/Library/Frameworks/Python.framework/Versions/3.8/lib/python3.8/site-packages/basedosdados/download.py in read_table(dataset_id, table_id, project_id, limit)
    124         raise Exception("Both table_id and dataset_id should be filled.")
    125 
--> 126     return read_sql(query)

/Library/Frameworks/Python.framework/Versions/3.8/lib/python3.8/site-packages/basedosdados/download.py in read_sql(query)
     88         Query result
     89     """
---> 90     client = bigquery.Client()
     91     return client.query(query).to_dataframe()
     92 

/Library/Frameworks/Python.framework/Versions/3.8/lib/python3.8/site-packages/google/cloud/bigquery/client.py in __init__(self, project, credentials, _http, location, default_query_job_config, client_info, client_options)
    178         client_options=None,
    179     ):
--> 180         super(Client, self).__init__(
    181             project=project,
    182             credentials=credentials,

/Library/Frameworks/Python.framework/Versions/3.8/lib/python3.8/site-packages/google/cloud/client.py in __init__(self, project, credentials, client_options, _http)
    247 
    248     def __init__(self, project=None, credentials=None, client_options=None, _http=None):
--> 249         _ClientProjectMixin.__init__(self, project=project)
    250         Client.__init__(self, credentials=credentials, client_options=client_options, _http=_http)

/Library/Frameworks/Python.framework/Versions/3.8/lib/python3.8/site-packages/google/cloud/client.py in __init__(self, project)
    201         project = self._determine_default(project)
    202         if project is None:
--> 203             raise EnvironmentError(
    204                 "Project was not passed and could not be "
    205                 "determined from the environment."

OSError: Project was not passed and could not be determined from the environment.

Download pelo CLI ter opção de limite de linhas.

Add Storage class

Should support

• init : initialize new bucket and folders
• create : to create folders given dataset_id and table_id
• delete : delete folders given dataset_id and table_id

Criar padrão de nomeação para tables.

Precisamos de um padrão para tabelas que se repetem entre níveis de observação.

Sugestão: <nível>_<descrição>

Exemplo: dados de PIB do IBGE para municípios, estados e país. Dentro do dataset br_economia_IBGE, as tables poderiam ser municipio_PIB, estado_PIB, pais_PIB?

Download pelo CLI permitir especificar só a pasta.

Nesse exemplo:

basedosdados download --dataset_id br_suporte --table_id diretorio_municipios ~/Downloads/

ele dá erro que Downloads é uma pasta. Ele podia baixar direto a table com o nome do BQ (nesse caso 'diretorio_municipios.csv'.

Adicionar CLI comando `basedosdados download tabela 'tablename'`

Talvez seja melhor

basedosdados table download DATABASE_ID TABLE_ID

para manter a consistência com as outras chamadas.

Where to put overall config?

1. CLI deve rodar de qlqr lugar do computador
2. secrets deve estar nessa pasta

lugar do config: ~/.basedosdados

config.yaml

metadata_path: 
bucket_name:
templates_path:

user:
   name:
   email:
   website:
   photo:

Templates folder not found

Download pelo CLI ter index=False como padrão.

subir o cli pro pip

Investigar se temos log de queries q involvam nossas tabelas

Aparentemente conseguimos saber o número de consultas por tabela. O logger não retorna a query para consultas externas.

Add tests to Storage class

Criar comandos rápidos no CLI

Adicionar tabelas simples:

basedosdados quick add_table DATASET_ID TABLE_ID FILEPATH[FOLDERPATH] --publish

Adicionar novo dado no storage e atualizar tabela

basedosdados quick add_table_data DATASET_ID TABLE_ID FILEPATH

Split files Table, Dataset, Base, Storage, api

Adicionar cache dos clientes do gbq para diminuir tempo de resposta do CLI

[infra] Padrão da função download ser não ter index.

Agora está baixando coisas com uma primeira coluna sem nome e com valores 0, 1, 2, 3, 4, 5...

Add if_exists=replace_all to Table

Sometimes you just want to replace everything

Pasta /code sendo criada na branch master quando rodamos o table create ou publish em outra branch.

Reparei que quando crio uma nova branch a partir do master e faço o pipeline create-publish nessa branch, é criada uma pasta /code dentro da branch master.

Por exemplo, o CLI criou a pasta br_economia_IBGE/code dentro de master mesmo comigo editando tudo de dentro da branch add_municipio_PIB.

Mudar Storage init para outro nome menos confuso (?)

[infra] Implementar uso de `labels` no BigQuery

Criei o diretorio_municipios com um label 'diretorio' mas não apareceu no BQ.

Melhorar campo 'data_update_frequency' no table_config.yaml

• Mudar os exemplos para letra minúscula: hora, dia, semana, etc.
• Agora não está contemplando bases que mudam de forma 'recorrente', ou só quando acontece alguma mudança relevante. Ou seja, frequências irregulares e reativas a eventos.

Auto fill last updated date to template

production table as view

Melhorar docstrings para `mode` e adicionar default no CLI

[infra] Arquivos config.yaml já virem com informações pré-registradas do usuário.

Já vir com nome, email, site, etc.

Adicionar mudança de tipos no publish.sql

To Storage, add if_exists=append option

Arquivos csv de download vindo com casas decimais pra números inteiros.

Exemplo: baixei o br_populacao_IBGE.populacao_municipios e a coluna populacao vem com valores como 31981.0, 83684.0, etc.

* bater o martelo toml vs yaml

Aparentemente é só usar o ruamel que os comentários e estrutura são preservados.

https://stackoverflow.com/questions/40235554/python-use-pyyaml-and-keep-format

https://stackoverflow.com/questions/60107078/dynamically-modify-yaml-and-preserve-all-formatting-and-comments-python

Criar projeto para staging e adaptar CLI

Create auto-pull after publishing data

Eleições - Detalhes Votação: Por que % votos válidos está >100 para senadores?

Linhas aparecendo sem like break na descrição.

Email deveria aparecer na linha seguinte.

To Storage, add mode='all' option

[infra] Setup Github Actions to lint and run tests