workshop.Rmd

---
title: "Guia CEPESP"
author: "Rafael Coelho"
date: "August 9, 2018"
output:
  pdf_document: default
  html_document: default
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE,
                      eval = FALSE)
```

O __CepespR__ é um pacote criado para auxiliar o acesso dos usuários a API do CepespData. Por meio deste pacote é possível ter um acesso mais rápido e organizado aos dados do TSE a respeito das eleições ocorridas no Brasil entres os anos de 1998 e 2016. Pensando nisto, este script tem como seu objetivo principal mostrar exemplos de como o pacote CepespR funciona e, assim, facilitar a vida dos usuários na hora de utilizar o R. Seguindo a rotina de cógidos abaixo, o usuário ao final deste script terá as consultas realizadas 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):

```{r}
if (!require("devtools")) install.packages("devtools")
devtools::install_github("Cepesp-Fgv/cepesp-r") 
```

Uma vez instalado o CepespR, é preciso "ativar" a library toda vez. Por isso SEMPRE que for utilizar o CepespData, é necessário rodar o código abaixo:

```{r}
library(cepespR)
```

## 2. Explorando as funções do CepespR

Uma vez carregado o pacote do CepespR, o usuário poderá fazer uso de 7 tipos de funções: `get_candidates`, `get_coalitions`, `get_votes`,  `get_elections`, `get_assets`, `get_secretaries` e `get_filiates`. Cada função mostra 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. Consultar perfil dos candidatos (get_candidates)

Para obter detalhes a respeito das características individuais dos candidatos que concorreram em uma eleição específica, a função get_candidates é a indicada: A função funciona assim: base_de_dados<-get_candidates(year= "Ano escolhido", position = "cargo escolhido"). Como no exemplo abaixo:

```{r}
candpres_14 <- get_candidates(year=2014, position="Presidente")
```

Para visualizar os dados do data frame criado usamos a função VIEW

```{r}
View(candpres_14)
```


A ordem da função é sempre esta: nome do data frame onde você quer salvar estas informações + nome da função + variáveis de interesse. Também é possível realizar as consultas indicando os códigos dos cargos. Para visualizar quais códigos representam cada cargo, por favor, acesse: https://github.com/Cepesp-Fgv/cepesp-rest/blob/master/EleicoesPorCargo_BETA.md

Vamos fazer uma consulta usando o código do cargo:

Suponhamos que estamos interessados nas eleições para prefeito ocorridas em 2012. Neste caso, é preciso mudar apenas os valores dos parâmetros da função. Veja:

```{r}
candpref_12 <- get_candidates(year=2012, position=11)
```

Você também poderia ter escrito "Prefeito" no lugar do código 11, que o resultado seria o mesmo. Note que apenas o ano e o nome(código) do cargo foram alterados

```{r}
View(candpref_12)
```

### 2.2. Consultar Coligações

Para obter detalhes a respeito dos partidos que compuseram as coligacões em uma eleição específica, a função get_coalitions é a indicada:

Ela funciona de forma similar a get_candidates:

```{r}
colpres_14 <- get_coalitions(year=2014, position="Presidente")

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:

```{r}
colpres_02 <- get_coalitions(year=2002, position="Presidente")

View(colpres_02)
```

### 2.3. Consultar votos por eleição

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:

```{r}
vtpres_14_mun <- get_votes(year=2014, position="Presidente", regional_aggregation="Municipio")

View(vtpres_14_mun)
```


Diferente das funções anteriores, essa função precisa de uma AGREGAÇÃO REGIONAL. Ou seja, você pode escolher a que nível de detalhe você quer ver os dados, se é por seção, municipio, nacional, etc. Os diferentes níveis de agregação disponíveis podem ser consultados em: https://github.com/Cepesp-Fgv/cepesp-r

E se estivéssemos interessados em ver a agregação por Estado (unidade da federação)?

```{r}
vtpres_14_estad <- get_votes(year=2014, position="Presidente", regional_aggregation="Estado")
View(vtpres_14_estad)
```

### 2.4. Consultar resultado de eleições por cargo

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. 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:

```{r}
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: 

- Candidato.

- Partido.

- Coligação.

- Consolidado.

Em resultado consolidado da eleição você pode encontrar dados de comparecimento, votos válidos e votos brancos e nulos. Veja:

```{r}
elpres_14_2 <- get_elections(year=2014, position="Presidente", regional_aggregation="Estado", political_aggregation="Consolidado")

View(elpres_14_2)
```

Caso você queira restringir sua busca, é possível filtrar na consulta valores específicos. 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.

Para mostrar apenas os resultados do Rio Grande do Sul, por exemplo, acrescente o parâmetro STATE

```{r}
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, por exemplo, acrescente o parâmetro PARTY

```{r}
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

```{r}
eldepfed_2511 <- get_elections(year=2014, position=6, regional_aggregation=2, political_aggregation=2, candidate_number=2511)

View(eldepfed_2511)
```

### 2.5. Consultar bens de candidatos

Para obter detalhes a respeito dos bens declarados pelos candidatos em uma eleição específica, a função get_assets é a indicada:
```{r}
bens_14 <- get_assets(year=2014)
View(bens_14)
```

Nesta função, o único parâmetro obrigatório é YEAR, mas também é possível fazer uso de outros dois parâmetros opcionais, STATE e COLUMNS_LIST:

```{r}
bens_10_AC <- get_assets(year = 2010, state = "AC", columns_list = list('CODIGO_CARGO','NOME_CANDIDATO','CPF_CANDIDATO','VALOR_BEM'))
View(bens_10_AC)
```

### 2.6. Consultar a lista de secretários estaduais

Para obter detalhes sobre as características individuais dos secretrários estaduais entre 1995 e 2010, a função get_secretaries é a indicada:

```{r}
secret_SP <- get_secretaries(state = "SP", name = "João")
View(secret_SP)
```


### 2.7. Consultar a lista de filiados

Para obter informações sobre os filiados de um determinado partido, a função get_filiates é a indicada:

```{r}
fili_MG_PT <- get_filiates(state = "MG", party = "PT")
View(fili_MG_PT)
```


## 3. Selecionando colunas

As funções do CepespR retornam todas as colunas disponíveis, mas é possivel limitar o tamanho dos resultados selecionando apenas as colunas de interesse. Veja:

- PASSO 1: Primeiro visualizamos quais são as colunas padrões através da função NAMES. Veja:

Na função get_candidates,por exemplo, as colunas padrões são:

```{r}
names(get_candidates(year = 2014, position = "Presidente"))
```

Note que uma lista de 46 colunas apareceu no seu console. E para as outras funções?

```{r}
#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:

```{r}
colunas <- list("NUMERO_CANDIDATO", "UF", "QTDE_VOTOS", "COD_MUN_IBGE")
```

- PASSO 3: Acrescentamos o parâmetro columns_list a nossa função e indicamos a lista criada com o nome das colunas:

```{r}
vtpres_14_new <- get_votes(year="2014", position="Presidente", regional_aggregation="Municipio", columns_list=colunas)

View(vtpres_14_new)
```

Outra maneira de selecionar as colunas de interesse é através da função SUBSET. Para isto, basta:

```{r}
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


## 4. 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:

```{r}
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:

```{r}
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:

```{r}
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).

## 5. 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)

```{r}
write.csv2(elpres_14, "eleicoes_presidente_2014.csv")
```