_main.Rmd

--- 
title: "Documentation for the discoveryengine"
site: bookdown::bookdown_site
output: bookdown::gitbook
documentclass: book
github-repo: cwolfsonseeley/discodocs
description: "Some documentation for the discoveryengine"
knit: "bookdown::render_book"
---
```{r}
knitr::opts_chunk$set(warning = FALSE, message = FALSE, fig.path = "images/")
```
# Welcome

![[Did I mention that I like to dance?](https://www.youtube.com/watch?v=uxi73RQlLB8)](images/disco.gif)

Welcome to the introduction to and extended documentation for the discoveryengine! The discoveryengine, also known as "Disco Engine" or just "Disco," is a tool enabling Prospect Development staff to do custom prospecting, written in the R programming language. For more information, see [What is the Disco Engine?](#what-is-disco)

If you are already familiar with the Disco Engine, and looking for some quick tips to refresh your memory, check out the [cheat sheet](#cheat-sheet).

Though the Disco Engine is written in R, you don't need to have any experience using R in order to get started. That said, if you're brand new to R and RStudio, check out our brief [introduction to R and RStudio](#r-intro).

Otherwise, feel free to read this document in order, or to jump around or just bookmark it and refer to it as needed. You may find the search feature helpful, you can access it by clicking on the little magnifying glass at the top of the screen. 

## Contribute to the Disco Engine

The Disco Engine is a tool made by and for Prospect Development. If you see something that doesn't work correctly, or documentation that could be made clearer, or a widget that would be useful that isn't implemented, or anything at all that could be improved in the Disco Engine, please submit an issue by clicking on the green "New Issue" button on the [Disco engine issues page](https://github.com/cwolfsonseeley/discoveryengine/issues).

## Contribute to this documentation

This site is a work in progress. One way you can help is to report any mistakes you find (typos, spelling mistakes, grammatical errors) or any areas that could be explained better (if something was not clear to you, there's a good chance it won't be clear to others either). This documentation site has its own [Disco-docs issues page](https://github.com/cwolfsonseeley/discodocs/issues) -- click on the green "New Issue" button and enter a short message explaining what's wrong. If you'd like to suggest edits directly, you can do so by clicking on the pen-and-paper icon at the top of any page on this site (guide coming soon). Thank you!

<!--chapter:end:index.Rmd-->


# (PART) Preliminaries {-}
# What is the Disco Engine? {#what-is-disco}

Placeholder


## Vocabulary and Grammar
## Facilitating discovery

<!--chapter:end:005-what-is-disco.Rmd-->

# Introduction to R and RStudio {#r-intro}

The discoveryengine works best when used with RStudio. Watch this video for a quick tour around RStudio:

<iframe width="560" height="315" src="https://www.youtube.com/watch?v=FIrsOBy5k58" frameborder="0" allowfullscreen></iframe>

<!--chapter:end:01-intro-r.Rmd-->


# Installation {#installation}

Placeholder


## Before you continue
## A disco test

<!--chapter:end:02-installation.Rmd-->


# (PART) Basics {-}
# An introductory example {#intro-example}

Placeholder


## Develop a strategy
## Create the definition {#intro-example-create-def}
## Send the definition to the CDW

<!--chapter:end:03-intro-example.Rmd-->


# Working with widgets {#working-with-widgets}

Placeholder


## Finding widgets {#working-with-finding-widgets}
## Leveraging autocomplete {#working-with-autocomplete}
## Codes and synonyms {#working-with-codes-synonyms}
## Synonym search {#synonym-search}
## Use the default cases {#use-defaults}
## The `not()` operator {#widget-not-operator}
## Detailed controls {#detailed-controls}

<!--chapter:end:04-working-with-widgets.Rmd-->


# Combining widgets {#combining-widgets}

Placeholder


## Example

<!--chapter:end:05-combining-widgets.Rmd-->


# (PART) Bots {-}
# The Brainstorm Bot {#brainstorm-bot}

Placeholder


## Search features

<!--chapter:end:30-brainstorm-bot.Rmd-->


# The Matrix Bot {#matrix-bot}

Placeholder


## Introduction
## What it is
## Example
## Botstrapping
## How does it work?

<!--chapter:end:31-matrix-bot.Rmd-->


# (PART) Advanced {-}
# Higher order widgets {#higher-order-widgets}

Placeholder


## Children of wealth

<!--chapter:end:40-higher-order.Rmd-->


# Non-entity widgets {#non-entity-widgets}

Placeholder


## Motivation
## Disco Definition Types {#non-entity-disco-definition-types}
## Searching fund text
## From funds to entities
## "Converters" {#non-entity-converters}

<!--chapter:end:45-non-entity-widgets.Rmd-->


# Optional arguments {#optional-arguments}

Placeholder


## Event invitees and attendees {#opt-events}
## Date ranges
## Graduate, undergraduate, attendee
## Workarounds: inactive only

<!--chapter:end:50-optional-arguments.Rmd-->


# (PART) Related tools {-}
# Add-on packages {#add-on-packages}

Placeholder


## `discoappend`
## `discovcr`
## `discoscape`

<!--chapter:end:70-add-on-packages.Rmd-->


# (PART) Examples {-}
# Political economy list {#ex-political-economy}

Placeholder



<!--chapter:end:80-example-01.Rmd-->


# LYBUNTs {#ex-lybunt}

Placeholder



<!--chapter:end:80-example-02.Rmd-->


# Recent Band Parents {#ex-recent-band-parents}

Placeholder


## Recent band members
## Find their parents
## Who live close enough
## How many?
## Householding

<!--chapter:end:80-example-03.Rmd-->


# Nearing Builder of Berkeley Status {#ex-near-builder}

Placeholder


## Defining close
## Householding

<!--chapter:end:80-example-04.Rmd-->

# Donors who aren't degreeholders {#ex-sim-donors}

```{r ex-sim-donors-loadlib, message = FALSE}
# i always begin by loading the disco engine if it isn't already loaded
library(discoveryengine)
```

We have what looks like an easy request:

> Find donors to the School of Information who are not SIM degree holders.

Having already looked up the codes, you immediately think: 

```{r eval = FALSE}
gave_to_area(SIM) %but_not% has_degree_from(LI)
```

Unfortunately, as you begin reviewing the results, you notice that you produced a list that includes spouses of degree holders who received credit for household gifts to SIM. 

To get around the issue, use the `married_to` widget (a [higher-order widget](#higher-order-widgets)). Note the use of parentheses to ensure the correct interpretation:

```{r}
alum = has_degree_from(LI)
non_alum_donor = 
    gave_to_area(SIM) %but_not%
    (alum %or% married_to(alum))
```

<!--chapter:end:80-example-05.Rmd-->


# Utilizing FEC disclosure data {#ex-fec}

Placeholder


## Basics
## Example: Engineering Prospects
## Example: Environmental Interest
## Bots

<!--chapter:end:80-example-06.Rmd-->


# Utilizing CA campaign finance data {#ex-ca-campaign}

Placeholder


## Example: State Senate and Assembly candidates
## Propositions

<!--chapter:end:80-example-07-ca-campaign.Rmd-->


# Alumni and current students {#ex-academic}

Placeholder



<!--chapter:end:80-example-07.Rmd-->


# Mining SEC filings {#ex-sec}

Placeholder


## Basics
## Looking for companies
## Specific roles

<!--chapter:end:80-example-08-sec.Rmd-->


# Finding dual-degree holders {#ex-mba-dual}

Placeholder


## Why not `%but_not%`?

<!--chapter:end:80-example-09-mba-dual.Rmd-->


# Moves Management {#ex-moves-management}

Placeholder


## Basics
## Example: Engineering qualifications
## Example: collaborative asks

<!--chapter:end:80-example-10-proposals.Rmd-->


# (APPENDIX) Appendix {-}
# Test your database set up {#test-cdw}

Placeholder


## Test your connection
## Opening RStudio
## Testing getcdw

<!--chapter:end:90-test-cdw.Rmd-->


# Cheat Sheet {#cheat-sheet}

Placeholder


## General
## Output
## Code lookup
## Text search
## Other

<!--chapter:end:93-cheat-sheet.Rmd-->


# How does it work? {#how-it-works}

Placeholder


## A Widget as a SQL template
## A template as a data structure
## Non-standard evaluation
## Combining simple definitions
### "Atomic" vs. "Complex" definitions
### Operations on definitions
## Re-visiting `to_sql`
## Seeing it all in action
## For further study

<!--chapter:end:99-how-does-it-work.Rmd-->