---
title: "Using the Squiggle API"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using the Squiggle API}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
not_cran <- identical(Sys.getenv("NOT_CRAN"), "true")
online <- !is.null(curl::nslookup("r-project.org", error = FALSE))
eval_param <- not_cran & online

knitr::opts_chunk$set(
  eval = eval_param,
  message = FALSE,
  warning = FALSE,
  collapse = TRUE,
  comment = "#>"
)
```

```{r }
library(fitzRoy)
library(dplyr)
```

# Squiggle Data
You can access data from the [Squiggle API](https://api.squiggle.com.au) directly with the `fetch_squiggle_data`. This allows direct access to the Squiggle API. 

Note that we also provide some helper functions that map more closely to our `fetch_` functions such as `fetch_ladder_squiggle`. 

## Queries
Full instructions for constructing queries can be found at [Squiggle API](https://api.squiggle.com.au). One of the following must be provided to the `query` argument. 

* `teams` - Info about teams (e.g. Richmond, Geelong, West Coast)
* `games` - Info about games (e.g. Round 1, 2019 Richmond v Carlton)
* `sources` - Info about models (e.g. Matter of Stats, GRAFT, Swinburne)
* `tips` - Info about tips and predictions made by models
* `standings` - Info about team standings (i.e. the ladder)
* `ladder` - Info about predicted ladders generated by models
* `virtual` - Info about Virtually Season 2020
* `pav` - Info about Player Approximate Value from HPN Footy

## Optional Arguments
Optional arguments can then be supplied based on the query. 

For example, `games` takes the following optional arguments.
* `year` - Year
* `round` - Round
* `game` - Game ID
* `complete` - Percent of game complete

These can be supplied as named arguments after the query. For example, to return games from just 2020, we would use the following.

```{r, squiggle_games, include=TRUE,eval=FALSE}
fetch_squiggle_data(query = "games", year = 2020)
```
```{r, squiggle_game_included, echo=FALSE, eval=eval_param}
fitzRoy:::squiggle_games %>% filter(year == 2020)
```

# Examples
## Teams
Fetch info about one or more AFL teams. 

```{r squiggle_teams, include=TRUE, eval=FALSE}
fetch_squiggle_data("teams")
```
```{r squiggle_teams_included, echo=FALSE, eval=eval_param}
fitzRoy:::squiggle_teams
```

## Games
Fetch info about one or more games. 
```{r squiggle_games2, include=TRUE,eval=FALSE}
fetch_squiggle_data(query = "games", year = 2020)
```
```{r squiggle_game2_included, echo=FALSE, eval=eval_param}
fitzRoy:::squiggle_games %>% filter(year == 2020)
```

## Sources
Fetch info about one or more computer models. 
```{r squiggle_sources1, include=TRUE, eval=FALSE}
# You can get the sources
fetch_squiggle_data("sources")
```
```{r squiggle_sources1_included, echo=FALSE, eval=eval_param}
fitzRoy:::squiggle_sources
```

## Tips
Fetch info about one or more tips made by computer models. 

```{r squiggle_tips1,  include=TRUE, eval=FALSE}
# Get all tips
fetch_squiggle_data("tips")
```
```{r squiggle_tips2, echo=FALSE, eval=eval_param}
fitzRoy:::squiggle_tips
```

We can just look at one particular round. 
```{r squiggle_round1, include=TRUE, eval=FALSE}
# Get` just tips from round 1, 2018
fetch_squiggle_data("tips", round = 1, year = 2018)
```
```{r squiggle_round2, echo=FALSE, eval=eval_param}
fitzRoy:::squiggle_tips %>% filter(year == 2018 & round == 1)
```

## Standings

Fetch info about team standings at a point in time, i.e. the ladder. 

```{r squiggle_standings,  include=TRUE, eval=FALSE}
fetch_squiggle_data("standings", year = 2020, round = 1)
```
```{r squiggle_standings2, echo=FALSE, eval=eval_param}
fitzRoy:::squiggle_standings
```


## Ladder

Fetch info about one or more projected ladders generated by computer models. For the actual ladder, see standings instead. 

```{r squiggle_ladder,  include=TRUE, eval=FALSE}
fetch_squiggle_data("ladder", year = 2019, round = 15, source = 1)
```
```{r squiggle_ladder_included, echo=FALSE, eval=eval_param}
fitzRoy:::squiggle_ladder
```


## PAV

Fetch info about players using HPN Footy's Player Approximate Value. 

```{r squiggle_pav,  include=TRUE, eval=FALSE}
fetch_squiggle_data("pav",
  firstname = "Dustin",
  surname = "Martin",
  year = 2017
)
```
```{r squiggle_pav_included, echo=FALSE, eval=eval_param}
fitzRoy:::squiggle_pav
```