add section for non-entity widgets

Author: tarakc02

02-installation.Rmd

@@ -25,7 +25,7 @@ devtools::install_github("tarakc02/discoveryengine")
 
 In order to make sure everything is working properly, we'll run a quick disco test:
 
-```{r disco_test}
+```{r disco_test, cache = TRUE}
 # you'll always load the discoveryengine package before doing anythying else
 library(discoveryengine)
 

03-intro-example.Rmd

@@ -19,7 +19,7 @@ You might already be thinking of what sorts of prospects we should look for. Tha
 
 Note that we now have a pretty clear idea of who to look for, but we need more precision. For instance, what constitutes a "demonstrated interest in technology?" What does it mean to be "in/near San Francisco?" In day-to-day conversations, we don't necessarily need that level of precision to understand one another, but since we'll need to translate this request into language a computer can understand, the more precision the better. I'll define a "demonstrated interest in technology" as having either an interest code or a philanthropic affinity related to technology, and "in/near San Francisco" as anywhere that falls into the San Francisco Metropolitan Statistical Area (MSA).
 
-## Create the definition
+## Create the definition {#intro-example-create-def}
 
 So now that we have a precise idea of who we want to find, we can create a definition that the computer will understand. This is important, since our computer is the only link we have to the CADS Data Warehouse. We can give it a precise definition in a language that it understands, and it will then relay our request to the CADS Data Warehouse. The CADS data warehouse can then search for people who meet our definition, and send them back to the computer, which will then display the list to us. 
 

04-working-with-widgets.Rmd

@@ -1,12 +1,12 @@
-# Working with widgets {#working_with_widgets}
+# Working with widgets {#working-with-widgets}
 
 So far, we've used widgets in some simple examples. In this section, we'll explore widgets in some more detail. As always, we'll begin by loading the `discoveryengine`:
 
 ```{r working-with-load}
 library(discoveryengine)
 ```
 
-## Finding widgets
+## Finding widgets {#working-with-finding-widgets}
 
 There are two main ways to find widgets. The first is to use the `show_widgets` function. The function takes no arguments. When you run it, an interactive list of widgets, with short descriptions of each, will appear in your viewer window:
 

40-higher-order.Rmd

@@ -1,6 +1,6 @@
 # (PART) Advanced {-}
 
-# Higher order widgets
+# Higher order widgets {#higher-order-widgets}
 
 You may have noticed when we ran the `show_widgets()` function in  [working with widgets](#working-with-show_widgets) that there is a mysterious "Order" column that categorizes widgets as either "first-order" or "second-order". What's that all about? In order to answer that, let's take a look at another example.
 

45-non-entity-widgets.Rmd

@@ -0,0 +1,52 @@
+# Non-entity widgets {#non-entity-widgets}
+
+## Motivation
+
+In CADSmart, there is a report called the Fundfinder, which allows you to search for allocations that contain specific words or phrases in the name, fund terms, or fund biography. A natural application is to use the report to find some allocations, and then turn around and get a list of entities who have given to those funds. So far, we haven't seen how to do that in the disco engine, but that's about to change. Before reading this section, make sure you understand [higher order widgets](#higher-order-widgets).
+
+## Disco Definition Types {#non-entity-disco-definition-types}
+
+Let's take a closer look at a widget we've already used a lot, the `has_capacity` widget. In particular, let's look at the [definition](#intro-example-create-def) that gets created when we use `has_capacity`:
+
+```{r non-entity-has-cap-ex}
+has_capacity(1)
+```
+
+See in parentheses in the first line where it says `type: entity_id`? So `entity_id` is the "type" of the definition we've created. And as you may have guessed by now, we can also create other types of definition!
+
+## Searching fund text
+
+The Fundfinder report does not give you a list of entities, it gives you a list of allocations. You are then expected to use a different report to find donors to those allocations. We'll follow a similar (but hopefully more convenient) strategy with the disco engine. We start by using `fund_text_contains` to do a text search of fund terms/biographies/names (for more info, check the help file by typing `?fund_text_contains`). `fund_text_contains`, like all text-searching tools in the discoveryengine, allows you to enter as many search terms as you like, and to use wildcards (*):
+
+```{r non-entity-fund-text-contains}
+# let's look for funds that support diversity/underrepresented students
+diversity_funds = fund_text_contains("divers*", "underrepresented")
+```
+
+The definition looks pretty complex, but notice that first line -- this time around, instead of entity_id, we have `type: allocation_code`:
+
+```{r non-entity-fund-text-contains-view}
+diversity_funds
+```
+
+And in fact, if we run `display`, we'll see a list of allocation codes instead of the entity IDs that we've seen in previous examples:
+
+```{r non-entity-fund-text-contains-display, cache = TRUE}
+display(diversity_funds)
+```
+
+## From funds to entities
+
+If all you needed to do was get a list of allocation codes for your own research, then congrats, you're done! But what if you want to take the next step, and find donors to those funds? You use one of the [tools to find widgets](#working-with-finding-widgets) to discover the `gave_to_fund` widget (read more at `?gave_to_fund`). Though it looks on the surface pretty similar to `gave_to_area` and `gave_to_department`, it is in fact one of those [second-order widgets](#higher-order-widgets)! 
+
+```{r non-entity-gave-to-fund, cache = TRUE}
+# gave_to_fund has the same interface/options 
+# as gave_to_area and gave_to_department. 
+diversity_donors = gave_to_fund(diversity_funds, at_least = 10000,
+                                from = 20150101, to = 20151231)
+display(diversity_donors)
+```
+
+## "Converters" {#non-entity-converters}
+
+Examples like this one show how higher-order widgets can act as "converters," converting one type of definition (like `allocation_code`) to another (like `entity_id`). This is a handy idea to have in the back of your mind. If you find yourself with an ID list definition that has the wrong type of ID, see if you can find a second-order widget that will "convert" it to the right type. 

docs/higher-order-widgets.html

@@ -25,7 +25,7 @@
 
 <meta name="author" content="Tarak Shah">
 
-<meta name="date" content="2016-08-26">
+<meta name="date" content="2016-08-31">
 
 
   <meta name="viewport" content="width=device-width, initial-scale=1">
@@ -34,7 +34,7 @@
 
 
 <link rel="prev" href="the-brainstorm-bot.html">
-<link rel="next" href="test-cdw.html">
+<link rel="next" href="non-entity-widgets.html">
 
 <script src="libs/jquery-2.2.3/jquery.min.js"></script>
 <link href="libs/gitbook-2.6.7/css/style.css" rel="stylesheet" />
@@ -121,11 +121,11 @@
 <li class="part"><span><b>Basics</b></span></li>
 <li class="chapter" data-level="4" data-path="intro-example.html"><a href="intro-example.html"><i class="fa fa-check"></i><b>4</b> An introductory example</a><ul>
 <li class="chapter" data-level="4.1" data-path="intro-example.html"><a href="intro-example.html#develop-a-strategy"><i class="fa fa-check"></i><b>4.1</b> Develop a strategy</a></li>
-<li class="chapter" data-level="4.2" data-path="intro-example.html"><a href="intro-example.html#create-the-definition"><i class="fa fa-check"></i><b>4.2</b> Create the definition</a></li>
+<li class="chapter" data-level="4.2" data-path="intro-example.html"><a href="intro-example.html#intro-example-create-def"><i class="fa fa-check"></i><b>4.2</b> Create the definition</a></li>
 <li class="chapter" data-level="4.3" data-path="intro-example.html"><a href="intro-example.html#send-the-definition-to-the-cdw"><i class="fa fa-check"></i><b>4.3</b> Send the definition to the CDW</a></li>
 </ul></li>
 <li class="chapter" data-level="5" data-path="working-with-widgets.html"><a href="working-with-widgets.html"><i class="fa fa-check"></i><b>5</b> Working with widgets</a><ul>
-<li class="chapter" data-level="5.1" data-path="working-with-widgets.html"><a href="working-with-widgets.html#finding-widgets"><i class="fa fa-check"></i><b>5.1</b> Finding widgets</a></li>
+<li class="chapter" data-level="5.1" data-path="working-with-widgets.html"><a href="working-with-widgets.html#working-with-finding-widgets"><i class="fa fa-check"></i><b>5.1</b> Finding widgets</a></li>
 <li class="chapter" data-level="5.2" data-path="working-with-widgets.html"><a href="working-with-widgets.html#codes-and-synonyms"><i class="fa fa-check"></i><b>5.2</b> Codes and synonyms</a></li>
 <li class="chapter" data-level="5.3" data-path="working-with-widgets.html"><a href="working-with-widgets.html#synonym-search"><i class="fa fa-check"></i><b>5.3</b> Synonym search</a></li>
 <li class="chapter" data-level="5.4" data-path="working-with-widgets.html"><a href="working-with-widgets.html#use-the-default-cases"><i class="fa fa-check"></i><b>5.4</b> Use the default cases</a></li>
@@ -142,6 +142,13 @@
 <li class="chapter" data-level="7" data-path="higher-order-widgets.html"><a href="higher-order-widgets.html"><i class="fa fa-check"></i><b>7</b> Higher order widgets</a><ul>
 <li class="chapter" data-level="7.1" data-path="higher-order-widgets.html"><a href="higher-order-widgets.html#children-of-wealth"><i class="fa fa-check"></i><b>7.1</b> Children of wealth</a></li>
 </ul></li>
+<li class="chapter" data-level="8" data-path="non-entity-widgets.html"><a href="non-entity-widgets.html"><i class="fa fa-check"></i><b>8</b> Non-entity widgets</a><ul>
+<li class="chapter" data-level="8.1" data-path="non-entity-widgets.html"><a href="non-entity-widgets.html#motivation"><i class="fa fa-check"></i><b>8.1</b> Motivation</a></li>
+<li class="chapter" data-level="8.2" data-path="non-entity-widgets.html"><a href="non-entity-widgets.html#non-entity-disco-definition-types"><i class="fa fa-check"></i><b>8.2</b> Disco Definition Types</a></li>
+<li class="chapter" data-level="8.3" data-path="non-entity-widgets.html"><a href="non-entity-widgets.html#searching-fund-text"><i class="fa fa-check"></i><b>8.3</b> Searching fund text</a></li>
+<li class="chapter" data-level="8.4" data-path="non-entity-widgets.html"><a href="non-entity-widgets.html#from-funds-to-entities"><i class="fa fa-check"></i><b>8.4</b> From funds to entities</a></li>
+<li class="chapter" data-level="8.5" data-path="non-entity-widgets.html"><a href="non-entity-widgets.html#non-entity-converters"><i class="fa fa-check"></i><b>8.5</b> “Converters”</a></li>
+</ul></li>
 <li class="appendix"><span><b>Appendix</b></span></li>
 <li class="chapter" data-level="A" data-path="test-cdw.html"><a href="test-cdw.html"><i class="fa fa-check"></i><b>A</b> Test your database set up</a><ul>
 <li class="chapter" data-level="A.1" data-path="test-cdw.html"><a href="test-cdw.html#test-your-connection"><i class="fa fa-check"></i><b>A.1</b> Test your connection</a></li>
@@ -235,16 +242,13 @@ <h2><span class="header-section-number">7.1</span> Children of wealth</h2>
 
 </div>
 </div>
-
-
-
             </section>
 
           </div>
         </div>
       </div>
 <a href="the-brainstorm-bot.html" class="navigation navigation-prev " aria-label="Previous page"><i class="fa fa-angle-left"></i></a>
-<a href="test-cdw.html" class="navigation navigation-next " aria-label="Next page""><i class="fa fa-angle-right"></i></a>
+<a href="non-entity-widgets.html" class="navigation navigation-next " aria-label="Next page""><i class="fa fa-angle-right"></i></a>
 
 <script src="libs/gitbook-2.6.7/js/app.min.js"></script>
 <script src="libs/gitbook-2.6.7/js/lunr.js"></script>

docs/index.html

@@ -25,7 +25,7 @@
 
 <meta name="author" content="Tarak Shah">
 
-<meta name="date" content="2016-08-26">
+<meta name="date" content="2016-08-31">
 
 
   <meta name="viewport" content="width=device-width, initial-scale=1">
@@ -121,11 +121,11 @@
 <li class="part"><span><b>Basics</b></span></li>
 <li class="chapter" data-level="4" data-path="intro-example.html"><a href="intro-example.html"><i class="fa fa-check"></i><b>4</b> An introductory example</a><ul>
 <li class="chapter" data-level="4.1" data-path="intro-example.html"><a href="intro-example.html#develop-a-strategy"><i class="fa fa-check"></i><b>4.1</b> Develop a strategy</a></li>
-<li class="chapter" data-level="4.2" data-path="intro-example.html"><a href="intro-example.html#create-the-definition"><i class="fa fa-check"></i><b>4.2</b> Create the definition</a></li>
+<li class="chapter" data-level="4.2" data-path="intro-example.html"><a href="intro-example.html#intro-example-create-def"><i class="fa fa-check"></i><b>4.2</b> Create the definition</a></li>
 <li class="chapter" data-level="4.3" data-path="intro-example.html"><a href="intro-example.html#send-the-definition-to-the-cdw"><i class="fa fa-check"></i><b>4.3</b> Send the definition to the CDW</a></li>
 </ul></li>
 <li class="chapter" data-level="5" data-path="working-with-widgets.html"><a href="working-with-widgets.html"><i class="fa fa-check"></i><b>5</b> Working with widgets</a><ul>
-<li class="chapter" data-level="5.1" data-path="working-with-widgets.html"><a href="working-with-widgets.html#finding-widgets"><i class="fa fa-check"></i><b>5.1</b> Finding widgets</a></li>
+<li class="chapter" data-level="5.1" data-path="working-with-widgets.html"><a href="working-with-widgets.html#working-with-finding-widgets"><i class="fa fa-check"></i><b>5.1</b> Finding widgets</a></li>
 <li class="chapter" data-level="5.2" data-path="working-with-widgets.html"><a href="working-with-widgets.html#codes-and-synonyms"><i class="fa fa-check"></i><b>5.2</b> Codes and synonyms</a></li>
 <li class="chapter" data-level="5.3" data-path="working-with-widgets.html"><a href="working-with-widgets.html#synonym-search"><i class="fa fa-check"></i><b>5.3</b> Synonym search</a></li>
 <li class="chapter" data-level="5.4" data-path="working-with-widgets.html"><a href="working-with-widgets.html#use-the-default-cases"><i class="fa fa-check"></i><b>5.4</b> Use the default cases</a></li>
@@ -142,6 +142,13 @@
 <li class="chapter" data-level="7" data-path="higher-order-widgets.html"><a href="higher-order-widgets.html"><i class="fa fa-check"></i><b>7</b> Higher order widgets</a><ul>
 <li class="chapter" data-level="7.1" data-path="higher-order-widgets.html"><a href="higher-order-widgets.html#children-of-wealth"><i class="fa fa-check"></i><b>7.1</b> Children of wealth</a></li>
 </ul></li>
+<li class="chapter" data-level="8" data-path="non-entity-widgets.html"><a href="non-entity-widgets.html"><i class="fa fa-check"></i><b>8</b> Non-entity widgets</a><ul>
+<li class="chapter" data-level="8.1" data-path="non-entity-widgets.html"><a href="non-entity-widgets.html#motivation"><i class="fa fa-check"></i><b>8.1</b> Motivation</a></li>
+<li class="chapter" data-level="8.2" data-path="non-entity-widgets.html"><a href="non-entity-widgets.html#non-entity-disco-definition-types"><i class="fa fa-check"></i><b>8.2</b> Disco Definition Types</a></li>
+<li class="chapter" data-level="8.3" data-path="non-entity-widgets.html"><a href="non-entity-widgets.html#searching-fund-text"><i class="fa fa-check"></i><b>8.3</b> Searching fund text</a></li>
+<li class="chapter" data-level="8.4" data-path="non-entity-widgets.html"><a href="non-entity-widgets.html#from-funds-to-entities"><i class="fa fa-check"></i><b>8.4</b> From funds to entities</a></li>
+<li class="chapter" data-level="8.5" data-path="non-entity-widgets.html"><a href="non-entity-widgets.html#non-entity-converters"><i class="fa fa-check"></i><b>8.5</b> “Converters”</a></li>
+</ul></li>
 <li class="appendix"><span><b>Appendix</b></span></li>
 <li class="chapter" data-level="A" data-path="test-cdw.html"><a href="test-cdw.html"><i class="fa fa-check"></i><b>A</b> Test your database set up</a><ul>
 <li class="chapter" data-level="A.1" data-path="test-cdw.html"><a href="test-cdw.html#test-your-connection"><i class="fa fa-check"></i><b>A.1</b> Test your connection</a></li>
@@ -172,7 +179,7 @@ <h1>
 <div id="header">
 <h1 class="title">Documentation for discoveryengine</h1>
 <h4 class="author"><em>Tarak Shah</em></h4>
-<h4 class="date"><em>2016-08-26</em></h4>
+<h4 class="date"><em>2016-08-31</em></h4>
 </div>
 <div id="disco" class="section level1">
 <h1><span class="header-section-number">1</span> Disco</h1>