1. Acessando o CEPESPData
O cepespR é um pacote criado para auxiliar o acesso dos usuários a API do CEPESPData. Por meio dessa ferramenta, é possível realizar requisições de maneira mais rápida e estruturada aos dados eleitorais presentes no nosso repositório. Por enquanto, o CEPESPData possui bancos referentes às eleições ocorridas no Brasil entre os anos de 1998 e 2016.
Pensando nisto, este tutorial tem como objetivo principal demonstrar algumas funcionalidades básicas do cepespR, assim como alguns exemplos de requisições e análises que podem ser feitas em poucos minutos no R. Seguindo a rotina de códigos abaixo, o usuário, ao final deste tutorial, poderá ter as consultas salvas com sucesso em formato compatível com o Excel(.csv).
1. Instalando o CepespR
Para instalar o pacote CepespR é preciso rodar o código abaixo apenas uma vez (apenas em caso de troca de computador é preciso instalar novamente o pacote):
if (!require("devtools")) install.packages("devtools")
devtools::install_github("Cepesp-Fgv/cepesp-r")
Uma vez instalado o CepespR, o pacote é ativado mediante a função library. Lembre-se que é preciso executar essa função toda vez que iniciar o R, senão as funções do cepespR não irão funcionar.
library(cepespR)
2. Explorando as funções do CepespR
Uma vez carregado o pacote do CepespR, o usuário poderá fazer uso de 4 tipos de funções: get_candidates, get_coalitions, get_votes e get_elections. Cada função devolve ao usuário diferentes partes dos dados do TSE, retornando sempre ao final da consulta uma tabela com os detalhes das eleições. Veja abaixo o que cada função faz:
2.1. Perfil dos candidatos (get_candidates)
A função get_candidates retorna uma tabela com informações sobre características individuais dos candidatos. Com ela, é possível obter, por exemplo, informações sobre partido, cor/raça, idade, gênero, ou outra informação que diga respeito ao candidato.
Para utilizá-la, você deve informar um ano e uma posição. De modo geral, ela terá a seguinte estrutura:
base_de_dados <- get_candidates(year = <Ano escolhido>, position = <cargo escolhido>).
No exemplo abaixo, faremos uma consulta para os candidatos à presidência durante as eleições de 2014. Repare que a função get_candidates salva a tabela no objeto candpres_14. Esse passo é importante uma vez que, caso seja de interesse utilizar essa tabela depois, faremos referência ao nome candpres_14.
candpres_14 <- get_candidates(year = 2014, position = "Presidente")
Para visualizar os dados da tabela criada, usamos a função View e dentro dos parênteses colocamos o nome da nossa tabela. No caso, utilizamos candpres_14.
View(candpres_14)
Uma das vantagem de se utilizar o R é que podemos criar tabelas de frequência com uma certa facilidade. Caso você queira, por exemplo, ver a distribuição de gênero (DESCRICAO_SEXO) ou de cor/raça(DESCRICAO_COR_RACA) entre todos os candidatos, podemos utilizar a função table da seguinte maneira:
table(candpres_14$DESCRICAO_COR_RACA)
table(candpres_14$DESCRICAO_SEXO)
Outra função que pode ser executada para análises rápidas é a summary. Com ela, podemos obter a média, o desvio padrão e outros estatísticas descritivas de uma variável quantitativa. No exemplo abaixo, temos a média de idade (IDADE_DATA_ELEICAO) dos candidatos.
summary(candpres_14$IDADE_DATA_ELEICAO)
2.1.1. Utilizando códigos ao invés de nomes
Ao invés de escrever os nomes das posições desejadas, uma alternativa é fornecer o código do cargo. Essa solução pode se demonstrar mais rápida com o tempo, uma vez que escrever os nomes é relativamente mais demorado e, caso digitado errado, levará a um erro durante a execução da função.
Os códigos estão disponíveis na nossa página do GitHub.
Vamos ver um exemplo. Suponhamos que estamos interessados nas eleições para prefeito ocorridas em 2012. O código do cargo para prefeito é 11. Sabendo disso, basta fornecer os valores desejados para a função e executá-la.
candpref_12 <- get_candidates(year = 2012, position = 11)
View(candpref_12)
2.2. Coligações (get_coalitions)
Caso o interesse seja pelas coligações realizadas por diferentes partidos, podemos utilizar a função get_coalitions.
É importante ter em mente que o banco da dados sobre coligações fornecido pelo TSE apresenta diversas inconsistências. Por exemplo, estão presentes no banco tanto coligações que concorreram quanto aquelas que por algum motivo não puderam concorrer. Sabendo disso, indicamos que essas informações sejam utilizadas com cuidado. De modo geral, caso deseje obter informações sobre coligações, talvez seja mais interessante utilizar a função get_elections, como iremos demonstrar mais para frente.
O funcionamento de get_coalitions é similar ao de get_candidates. Basta fornecer uma posição e um ano para acessar as informações desejadas.
base_de_dados <- get_coalitions(year = <Ano escolhido>, position = <cargo escolhido>).
Por exemplo, caso seja de interesse as coligações realizadas para prefeitura durante as eleições de 2016, basta informar esses parâmetros e executar a função.
colpres_14 <- get_coalitions(year = 2016, position = "Prefeito")
Novamente, para ter uma visão geral da tabela devolvida pela função, podemos utilizar a função View.
View(colpres_14)
Suponhamos que agora estamos interessados nas coligações da eleição para presidente em 2002. Neste caso, a função será escrita assim:
colpres_02 <- get_coalitions(year = 2002, position = "Presidente")
View(colpres_02)
2.3. Votos por eleição (get_votes)
Para obter detalhes a respeito do número de votos de cada candidato em uma eleição específica, a função get_votos é a indicada. Diferente das funções anteriores, essa função precisa de uma agregação regional. Nesse sentido, você precisa definir o nível de agregação dos votos (municípios, estados, nacional, etc). Caso essa opção não seja definida, get_votes retornará por padrão os votos agregados por municípios. Os diferentes níveis de agregação disponíveis podem ser consultados em: https://github.com/Cepesp-Fgv/cepesp-r
No exemplo abaixo, podemos ver uma requisição para os votos para presidente, em 2014, com agregação regional configurada para municípios.
vtpres_14_mun <- get_votes(year = 2014, position = "Presidente", regional_aggregation = "Municipio")
View(vtpres_14_mun)
E se estivéssemos interessados em ver a agregação por Estado (unidade da federação)?
vtpres_14_estad <- get_votes(year = 2014, position = "Presidente", regional_aggregation = "Estado")
View(vtpres_14_estad)
2.4. Resultado de eleições por cargo (get_elections)
Além das consultas disponíveis no TSE, é possível fazer uma consulta integrada as eleições. Esta consulta agrega informações de candidato, coligações e votos. Trata-se de um dos diferenciais do CEPESPData frente a outras fontes. A consulta ainda está em fase BETA e podem haver pontos de melhoria. Para obter detalhes a respeito de uma eleição especificando-se o cargo, use a função get_elections:
elpres_14 <- get_elections(year = 2014, position = "Presidente", regional_aggregation = "Municipio", political_aggregation = "Candidato")
View(elpres_14)
Esta função permite também consultar o resultado por diferentes agregações políticas: candidato, partido, coligação e consolidado da eleição. Cada uma delas agrega os votos e outras informações. Por exemplo, caso seja feita um requisição para agregação política partido, será retornado os votos obtidos e a coligação da qual o partido fez parte, além de outras informações.
A agregação política consolidado da eleição possui informações um tanto quanto diferente das outras. Ela não retorna os votos de um candidato, partido ou coligação. Nela, você pode encontrar dados de comparecimento, votos válidos e _votos brancos e nulos._ Veja:
elpres_14_2 <- get_elections(year = 2014, position = "Presidente", regional_aggregation = "Estado", political_aggregation = "Consolidado")
View(elpres_14_2)
3. Filtrando resultados
Por padrão as funções do cepespR retornam todas colunas disponíveis como também todos os partidos, candidatos e Estados. A fim de reduzir o tamanho da tabela, é possível selecionar valores específicos para essas consultas e, assim, obter resultados menores e mais fáceis de se trabalhar.
3.1. Selecionando partidos, candidatos e Estados
Para limitar os resultados a valores específicos (um estado, um partido ou a um candidato, por exemplo), basta acrescentar os parâmetros state, party ou candidate_number e alterá-los de acordo com o interesse.
| Variável | Parâmetro |
|---|---|
| Estado | state |
| Partido | party |
| Número do Candidato | candidate_number |
Para mostrar apenas os resultados do Rio Grande do Sul (RS), por exemplo, acrescente o parâmetro state.
elpres_14_RS <- get_elections(year=2014, position="Presidente", regional_aggregation="Estado", political_aggregation="Partido", state="RS")
View(elpres_14_RS)
Para mostrar apenas os resultados referentes ao PT (13), por exemplo, acrescente o parâmetro party.
elpres_14_PT <- get_elections(year=2014, position="Presidente", regional_aggregation="Estado", political_aggregation="Partido", party="13")
View(elpres_14_PT)
Para mostrar apenas os resultados referentes ao candidato 2511, por exemplo, acrescente o parâmetro candidate_number Vamos escrever os parâmetros usando os códigos. Para o cargo de deputado federal o código é 6, para a agregação por UF. O código é 2 e para a agregação por candidato o código é 2
eldepfed_2511 <- get_elections(year=2014, position=6, regional_aggregation=2, political_aggregation=2, candidate_number=2511)
View(eldepfed_2511)
3.2. Selecionando colunas
Por padrão, as funções do CepespR retornam todas as colunas disponíveis, mas é possível limitar o tamanho das tabelas para apenas a quantidade de variáveis desejadas.
- PASSO 1: Primeiro visualizamos quais são as colunas padrões através da função
names.
Existem duas maneiras de realizar esse procedimento. Em primeiro lugar, você pode acessar a nossa página do GitHub e selecionar a consulta desejada. Lá você poderá ver quais colunas são retornadas para cada requisição e escolher as pretendidas. Em segunda lugar, é possível realizar esse procedimento dentro do R, mediante a função names.
Na função get_candidates, por exemplo, as colunas padrões são:
names(get_candidates(year = 2014, position = "Presidente"))
Note que uma lista de 46 colunas apareceu no seu console. E para as outras funções?
#Lista as colunas da função get_coalition
names(get_coalitions(year = 2014, position = "Presidente"))
#Lista as colunas da função get_votes
names(get_votes(year = 2014, position = "Presidente"))
#Lista as colunas da função get_elections
names(get_elections(year = 2014, position = "Presidente"))
- PASSO 2: Em segundo, criamos uma lista com o nome das colunas que desejamos:
Se queremos analisar os dados referentes aos votos, por exemplo, poderíamos reduzir nosso data frame a seguintes colunas:
colunas <- list("NUMERO_CANDIDATO", "UF", "QTDE_VOTOS", "COD_MUN_IBGE")
- PASSO 3: Acrescentamos o parâmetro
columns_lista nossa função e indicamos a lista criada com o nome das colunas:
vtpres_14_new <- get_votes(year = "2014", position = "Presidente", regional_aggregation = "Municipio", columns_list = colunas)
View(vtpres_14_new)
Repare que, em primeiro lugar, criamos um objeto chamado colunas, contendo os nomes das variáveis de nosso interesse. Após, nós passamos esse objeto colunas para o parâmetro columns_list dentro da função get_votes.
Outra maneira de selecionar as colunas de interesse é através da função subset. Para isto, basta:
elpres_14_ <- subset(elpres_14_2,select= c("ANO_ELEICAO", "QT_VOTOS_BRANCOS", "QT_VOTOS_NULOS"))
View(elpres_14_)
Note que a função foi escrita na seguinte ordem: nome do novo data frame+subset+nome do antigo data frame+nome das colunas de interesse
5. Analisando os resultados
É possível fazer análises descritivas das variáveis contidas nos data frames. Por exemplo:
Para variáveis qualitativas (categóricas), podemos usar a função TABLE. Esta função retorna a distribuição de frequência absoluta das categorias. Veja:
Suponhamos que estamos interessados na quantidade de candidatas do sexo feminino para as eleições a prefeito de 2016. A função abaixo retorna a frequência absoluta de homens e mulheres:
elpref_16 <- get_elections(year=2016, position="Prefeito", regional_aggregation="Municipio", political_aggregation="Candidato")
table(elpref_16$DESCRICAO_SEXO)
Note que a função foi escrita assim: table(nome do data frame$variável do data frame em que estou interessado). E para as eleições a deputado federal em 2014? Quantas mulheres se candidataram neste ano? Veja:
eldepfed_14 <- get_elections(year=2014, position="Deputado Federal", regional_aggregation="Estado", political_aggregation="Candidato")
table(eldepfed_14$DESCRICAO_SEXO)
Para variáveis quantitativas (contínuas), podemos usar a função SUMMARY. Esta função retorna média, mediana, mínimo e máximo das variáveis. Veja:
Suponhamos que estamos interessados na média das idades dos candidatos nas eleições a presidente de 2014. Veja:
summary(elpres_14$IDADE_DATA_ELEICAO)
Note que a função summary funciona de maneira similar a table: summary (nome do data frame$variável do data frame em que estou interessado).
6. Salvando os resultados
Para salvar os data frames gerados neste script em formato .csv, basta usar a função abaixo:
A função está organizada da seguinte maneira: write.csv2(nome do data frame que quero exportar, nome que quero dar ao meu arquivo .csv)
write.csv2(elpres_14, "eleicoes_presidente_2014.csv")