{"id":17258556,"url":"https://github.com/turicas/eleicoes-brasil","last_synced_at":"2025-04-04T16:11:34.595Z","repository":{"id":33672171,"uuid":"156513383","full_name":"turicas/eleicoes-brasil","owner":"turicas","description":"Scripts para capturar dados do Repositório de Dados Eleitorais do TSE, limpá-los, normalizá-los e agrupá-los","archived":false,"fork":false,"pushed_at":"2024-12-12T02:03:43.000Z","size":361,"stargazers_count":152,"open_issues_count":12,"forks_count":33,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-03-27T07:02:33.297Z","etag":null,"topics":["brazil","dados","elections","eleicoes2020","hacktoberfest","opendata","tse"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/turicas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":"https://apoia.se/brasilio"}},"created_at":"2018-11-07T08:22:24.000Z","updated_at":"2025-03-23T06:26:27.000Z","dependencies_parsed_at":"2023-01-15T01:59:38.553Z","dependency_job_id":"826f891a-0fbb-4a5f-99f3-a928f0e4ff93","html_url":"https://github.com/turicas/eleicoes-brasil","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turicas%2Feleicoes-brasil","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turicas%2Feleicoes-brasil/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turicas%2Feleicoes-brasil/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turicas%2Feleicoes-brasil/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/turicas","download_url":"https://codeload.github.com/turicas/eleicoes-brasil/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247208142,"owners_count":20901570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["brazil","dados","elections","eleicoes2020","hacktoberfest","opendata","tse"],"created_at":"2024-10-15T07:21:05.676Z","updated_at":"2025-04-04T16:11:34.564Z","avatar_url":"https://github.com/turicas.png","language":"Python","funding_links":["https://apoia.se/brasilio"],"categories":[],"sub_categories":[],"readme":"# Eleições Brasil\n\nEsse repositório de código contém programas que baixam dados do Tribunal\nSuperior Eleitoral, normalizam, agrupam e limpam. Atualmente as bases de dados\ndisponíveis são:\n\n- Candidaturas (1996 a 2020)\n- Bens declarados (2006 a 2020)\n- Votação por zona eleitoral (1996 a 2020)\n- Prestação de contas (2002 a 2020)\n\n## Metodologia\n\nA fonte primária é o [Repositório de Dados Eleitorais do\nTSE](http://www.tse.jus.br/eleicoes/estatisticas/repositorio-de-dados-eleitorais-1).\nO processo é o seguinte:\n\n- Baixar arquivos ZIP\n- Para cada ZIP, extrair (em memória) os arquivos internos\n- Para cada arquivo interno, processá-lo (identificar cabeçalho, limpar)\n- Juntar todos os resultados em um arquivo\n\n\n## Normalização\n\nAlgumas etapas de normalização são necessárias para facilitar análises e\nconversões dos dados, como:\n\n- Retirar todos os acentos: alguns nomes aparecem com acentos em um ano e sem\n  em outros, dificultando muito os agrupamentos;\n- Retirar strings inúteis: valores como `#NULO#`, `#NULO`, `#NE` e `#NE#` são\n  retirados, deixando as células em branco;\n- Normalização dos códigos de cargo: os códigos de cargo variam para alguns\n  anos, tornando difícil o agrupamento entre anos e, para facilitar as\n  análises, normalizamos todos os anos;\n- Renomear colunas: nem todas as colunas possuem nomes intuitivos e foram\n  nomeadas (exemplo: `COD_SIT_TOT_TURNO` foi renomeado para\n  `codigo_totalizacao_turno`). Para saber mais detalhes sobre as colunas que\n  foram renomeadas, olhe os arquivos no diretório `headers/` (caso você altere\n  algum desses arquivos, gere novamente os cabeçalhos finais com\n  `python tse.py headers`).\n\n\u003e Nota: nem todos os códigos/descrição foram normalizados (alguns apresentam\n\u003e inconsistências ainda não resolvidas e serão feitos em breve).\n\n\n### Privacidade\n\nPara garantir a privacidade e evitar SPAM, o script limpa algumas colunas com\ninformações sensíveis. Essa é a forma padrão de funcionamento para não\nfacilitar a exposição desses dados. Os dados censurados são:\n\n- Na tabela `candidatura`:\n  - A coluna `email` terá seu conteúdo totalmente limpo\n  - A coluna `cpf` terá os 3 primerios dígitos trocados por `*`\n\nCaso queira rodar o script sem o modo censura, altere o script `run.sh` e\nadicione a opção `--no-censorship` para o script `tse.py`.\n\n\n## Instalando\n\nOs programas requerem Python 3.7+. Instale as dependências executando:\n\n```bash\npip install -r requirements.txt\n```\n\n\n## Rodando\n\nO script `tse.py` baixa, trata e extrai os dados. Basta rodá-lo, passando que\ntipo de dado quer baixar/tratar/extrair:\n\n```bash\npython tse.py candidatura\npython tse.py bem_declarado\npython tse.py votacao_zona\npython tse.py receita\npython tse.py despesa\n```\n\nOs dados ficarão disponíveis em:\n\n- `data/download/`: arquivos originais baixados, por ano\n- `data/output/`: arquivos extraídos (agrupados por tipo)\n\nCaso queira converter os arquivos `.csv.gz` gerados em um banco de dados\nSQLite (facilita as análises), execute:\n\n```bash\n./csv2sqlite.sh\n```\n\nEsse script irá rodar o comando `rows csv-to-sqlite` em todos os arquivos\ngerados em `data/output` e criará o arquivo `data/eleicoes-brasil.sqlite`.\n\n### Opções\n\nAs opções listadas abaixo podem ser utilizadas em conjunto.\n\n#### Anos\n\nVocê pode especificar para quais anos deseja a extração (separados por\nvírgulas), como em:\n\n```bash\npython tse.py candidatura --years=2014,2018\n```\n\n#### Alterar fonte dos dados\n\nComo os servidores do TSE podem estar lentos em épocas de eleição, você pode\nbaixar os dados de algum servidor mais rápido que hospede uma cópia deles\n(chamamos de *mirror*). No Brasil.IO mantemos um *mirror* de alguns arquivos do\nRepositório de Dados Eleitorais do TSE, **porém** note que ainda não temos uma\npolítica de atualização frequente desses dados e, por isso, eles podem estar\ndesatualizados (estamos trabalhando para que sejam atualizados com mais\nfrequência e que a data de cópia dos dados fique explícita em uma página).\n\nPara que o script colete os daos usando nosso *mirror*, execute-o com a opção\n`--use-mirror`:\n\n```bash\npython tse.py candidatura --use-mirror\n```\n\nVocê pode especificar também a URL base do *mirror*, que por padrão é do\n[Brasil.IO](https://brasil.io/):\n\n```bash\npython tse.py candidatura --use-mirror --mirror-url=https://data.brasil.io/mirror/eleicoes-brasil/\n```\n\n\n#### Apenas baixar\n\nCaso queira apenas baixar os arquivos, utilize a opção `--download-only`.\n\n#### Forçar download\n\nPor padrão, caso os arquivos necessários para uma extração já existam em\n`data/download/`, eles não serão baixados novamente. Você pode utilizar a opção\n`--force-redownload` para que eles sejam deletados e baixados novamente.\n\n#### Arquivo de saída\n\nVocê pode especificar o arquivo de saída (que será sempre um CSV, mas pode\nestar compactado):\n\n```bash\npython tse.py candidatura --output=candidatura.csv.gz\n```\n\n#### Observações\n\nEm alguns casos o TSE libera arquivos compactados no formato RAR (mesmo com a\nextensão \".zip\"). Para extrair os dados desses arquivos você precisa instalar\nem seu sistema o bsdtar ou unrar (em sistemas Debian e derivados):\n`apt install libarchive-tools` ou `apt install unrar` - o último não é software\nlivre).\n\n\n## Desenvolvendo/contribuindo\n\nInstale as dependências de desenvolvimento:\n\n```bash\npip install -r dev-requirements.txt\n```\n\nRode os testes:\n\n```bash\npytest tests.py\n```\n\nAo alterar os arquivos, rode o comando `black .` para normalizá-los com relação\nà [PEP-0008](https://www.python.org/dev/peps/pep-0008/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fturicas%2Feleicoes-brasil","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fturicas%2Feleicoes-brasil","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fturicas%2Feleicoes-brasil/lists"}