---
title: "rpredictit"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{rpredictit}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

# An R interface to the PredictIt API
The `rpredictit` package provides an interface to the PredictIt public API.

In addition to providing a wrapper to retrieve market data, this package includes visualization functions for plotting historical price data and exploring available markets. The package also comes with a demo shiny application for illustrating example use cases.

`rpredictit` is not affiliated with any predictive markets and is presented for informational purposes only. Always confirm with your own research before making an investment. 
**License to use data made available via the API is for non-commercial use and PredictIt is the sole source of such data.**

## Installation

Once released, you may install the stable version from CRAN, or the development version using *devtools*:
```{r setup, eval=FALSE}
# development version, via devtools
devtools::install_github('danielkovtun/rpredictit')
```

## Usage

#### Demo Shiny Application
To start off, try running a demo Shiny application included with the package by running:
```{r, eval=FALSE}
library(rpredictit)
rpredictit::runExample('demo')  
```


#### All Markets
Try `rpredictit::all_markets()` to return a tibble containing bid and ask data for all PredictIt markets:

```{r}
rpredictit::all_markets()
```

#### Interactive Table
Alternatively, to return an interactive htmlwidget (DT::datatable) table containing HTML formatted market data, pass the returned bid/ask data to `rpredictit::markets_table()`:

```{r}
data <- rpredictit::all_markets()
rpredictit::markets_table(data)
```

#### Interactive Plot
To plot historical prices, download a 'csv' file for a specific contract from PredictIt's website and pass the file path to `rpredictit::parse_historical_ohlcv()`.
Then, pass in the returned contract data object to `rpredictit::historical_plot()`:
```{r}
filename <- "What_will_be_the_balance_of_power_in_Congress_after_the_2020_election.csv"
csv_path <- system.file("extdata", filename, package = "rpredictit")
contract_data <- rpredictit::parse_historical_csv(csv_path)
rpredictit::historical_plot(contract_data)
```


#### Individual Market
To return data for a specific market, use `rpredictit::single_market(id)`, where `id` refers to the numerical code pertaining to the market of interest. 
You can find a market's numerical code by consulting its URL or by first calling the all markets API (`all_markets()`)
```{r, eval=FALSE}
markets <- rpredictit::all_markets()
id <- markets$id[1]
rpredictit::single_market(id)
```

See the full documentation at https://danielkovtun.github.io/rpredictit/.