---
title: "Querying the Data"
author: "Jake Conway and Nils Gehlenborg"
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{Querying the Data}
  \usepackage[utf8]{inputenc}
---

<br>

For all examples the movies data set contained in the package will be used.
```{r, tidy=TRUE}
library(UpSetR)
movies <- read.csv( system.file("extdata", "movies.csv", package = "UpSetR"), header=T, sep=";" )
```

<br>

*queries* Parameter Breakdown
----------------------------------
Each list contained in the `queries` parameter takes 4 fields: `query`, `params`, `color`, and `active`.

- `query` specifies which query is going to be run

- `params` is a list of paramters for the query to work on

- `color` is the color that will represent the query on the plot. If no color is provided, a color will be selected from the _UpSetR_ default color palette.

- `active` determines how the query will be represented on the plot. If `active` is `TRUE`, the intersection size bar will be overlayed by a bar representing the query. If `active` is `FALSE`, a jitter point will be placed on the intersection size bar.

To learn how queries can be explored and visualized on an element level see the **Attribute Plots** vignette.

<br>

Example 1: Built-in Intersection Query
-------------
This example shows how to use the built in intersection query, `intersects`, to find or display elements in specific intersections. In this example the color selected for the active query is from the default color palette.
```{r, out.width="850px", fig.width=9, fig.height =5, tidy=TRUE, fig.align='center'}
upset(movies, queries = list(list(query = intersects, params = list("Drama", "Comedy", "Action"), color = "orange", active = T), list(query = intersects, params = list("Drama"), color = "red", active = F), list(query = intersects, params = list("Action", "Drama"), active = T)))
```

<br>

Example 2: Built-In Elements Query
-------------
This example shows how to use the built in element query, `elements`, to visualize how certain elements are distributed amongst the intersections.
```{r, out.width="850px", fig.width=9, fig.height =5, tidy=TRUE, fig.align='center'}
upset(movies, queries = list(list(query = elements, params = list("AvgRating", 3.5, 4.1), color = "blue", active = T), list(query = elements, params = list("ReleaseDate", 1980, 1990, 2000), color = "red", active = F)))
```

<br>

Example 3: Using Expression Parameter to Subset Intersection and Element Queries
-------------
This example shows how to use the `expression` parameter to subset the results of element and intersection queries.
```{r, out.width="850px", fig.width=9, fig.height =5, tidy=TRUE, fig.align='center'}
upset(movies, queries = list(list(query = intersects, params = list("Action", "Drama"), active = T), list(query = elements, params = list("ReleaseDate", 1980, 1990, 2000), color = "red", active = F)), expression = "AvgRating > 3 & Watches > 100")
```

<br>

Example 4: Creating Custom Queries on Set Elements and Attributes
-------------
Creating a custom query to operate on the rows of the data.
```{r, tidy=TRUE}
Myfunc <- function(row, release, rating){
    data <- (row["ReleaseDate"] %in% release) & (row["AvgRating"] > rating)
}
```

Applying the created query to the queries parameter.
```{r, out.width="850px", fig.width=9, fig.height =5, tidy=TRUE, fig.align='center'}
upset(movies, queries = list(list(query = Myfunc, params = list(c(1970,1980, 1990, 1999, 2000), 2.5), color = "blue", active =T)))
```

<br>

Example 5: Applying a query legend
--------------
To add a legend for the queries applied, the `query.legend` parameter can be used. The `query.legend` parameter takes the position where the legend should be displayed, either *top* or *bottom*. To apply a specific name to each query, the parameter `query.name` can be used when defining the query in the `queries` paramter. If no `query.name` is provided, a generic name will be used. The example below shows how to do this.
```{r, out.width="850px", fig.width=9, fig.height =5, tidy=TRUE, fig.align='center'}
upset(movies, query.legend = "top", queries = list(list(query = intersects, params = list("Drama", "Comedy", "Action"), color = "orange", active = T, query.name="Funny action"), list(query = intersects, params = list("Drama"), color = "red", active = F), list(query = intersects, params = list("Action", "Drama"), active = T, query.name="Emotional action")))
```

<br>

Example 6: Applying Everything at Once
--------------
Combining pieces from all previous examples into one awesome query!
```{r, out.width="850px", fig.width=9, fig.height =5, tidy=TRUE, fig.align='center'}
upset(movies, query.legend = "bottom", queries = list(list(query = Myfunc, params = list(c(1970,1980, 1990, 1999, 2000), 2.5), color = "orange", active =T), list(query = intersects, params = list("Action", "Drama"), active = F), list(query = elements, params = list("ReleaseDate", 1980, 1990, 2000), color = "red", active = F, query.name="Decades")), expression = "AvgRating > 3 & Watches > 100")
```