-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy path04-working-with-widgets.Rmd
104 lines (64 loc) · 7.03 KB
/
04-working-with-widgets.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
# 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 {#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:
You can browse the entire listing, or use the search bar at the top right to search for specific widgets.
The second way to search for widgets is to use the `widget_for` function. This function takes as an argument a search term, and finds all widgets that are related to that search term. For example:
```{r working_with_widget_for}
widget_for("giving")
```
Once you've found the widget you're looking for, you can get additional information using R's built-in help system. Just type a question mark followed by the name of the widget, e.g. `?gave_to_area`.
## Leveraging autocomplete {#working-with-autocomplete}
As the previous section illustrates, there are a bewildering number of widgets available in the Discovery Engine. To make them a little easier to navigate, we've attached standard prefixes to the names of groups of widgets with related functionality. Since RStudio's autocomplete pops up suggestions along with documnetation as you type, typing a known prefix is a good way to quickly find and access a widget.
Here are some of the groups of related widgets that use common prefixes in their names:
- Giving-related widgets: To find donors to the College of Natural Resources, you'd use `gave_to_area`. To find donors to scholarships, use `gave_to_purpose`. Type `gave_to` and wait for a second to see the full list of giving widgets.
- Political contribution widgets (federal): Widgets for [political contributions in federal elections](#ex-fec) all begin with the prefix `fec_`.
- Political contribution widgets (statewide): Widgets for [political contributions in California elections](#ex-ca-campaign) all begin with the prefix `ca_`.
In addition to entity widgets, [other types of widgets](#non-entity-widgets) are also helpfully grouped together.
- Every widget that pulls allocation codes instead of entity IDs begins with `fund_` (for example, `fund_type` or `fund_department`).
- Contact report widgets all begin with `contact_` (for example `contact_text_contains` or `contact_date`).
- Proposal-based widgets all begin with `proposal_` (for example, `proposal_actual_ask` or `proposal_qualified`).
Finally, `bot_brainstorm` and `bot_matrix` are aliases for the [`brainstorm_bot`](#brainstorm-bot) and the [`matrix_bot`](#matrix-bot), and in general, typing `bot_` and waiting for a second will show a full list of the disco engine's bots.
## Codes and synonyms {#working-with-codes-synonyms}
You may have noticed in previous examples that widgets work with exact codes, such as `in_unit_portfolio(BU)` or with *synonyms*, such as `in_unit_portfolio(business)`. Synonyms will always be in lower-case, and may include any letter of the alphabet or the underscore "_" character, and nothing else.
Use whichever feels more comfortable -- there is no advantage to using codes vs. synonyms, though I personally find the synonyms easier to read and understand later on.
## Synonym search {#synonym-search}
If you're not sure of the code or synonym to use, try out the synonym search feature that works with most widgets. Instead of entering a code (`in_unit_portfolio(BU)`) or synonym (`in_unit_portfolio(business)`), enter a question mark followed by a search string:
```{r working_with_synsearch1}
in_unit_portfolio(?business)
```
You can enter partial terms:
```{r working_with_synsearch2}
in_unit_portfolio(?sci)
```
And even multiple search terms:
```{r working_with_synsearch3}
in_unit_portfolio(?bus, ?chem, ?public)
```
Widgets can always accept multiple codes/synonyms as arguments, and even combinations of the two:
- `gave_to_area(business)` would find anyone who has given to the school of Business
- `gave_to_area(business, chemistry)` would find anyone who has given to Business or to Chemistry
- `gave_to_area(HSB, COC)` is the same as above
- `gave_to_area(business, COC)` once again, the same thing
## Use the default cases {#use-defaults}
So by now you can probably figure out that `partcipated_in(uc_jazz_ensembles)` gets you alumni who participated in the UC Jazz Ensembles. But what if you're actually looking for people who particpated in any student activity at all? Would you have to type out all (hundreds!) of them?
Luckily, no! In fact, all you have to do is type `participated_in()`:
```{r participated-in-anything, cache = TRUE}
did_anything = participated_in()
display(did_anything)
```
That seems a bit magical, doesn't it? The reason that works is because every widget has a defined behavior for when no codes/synonyms are entered. These default behaviors aim to be sensible so that you can use them in an intuitive way. You can always find out exactly what is included in the default by using the help. For instance, by typing `?has_capacity` I find out that entering `has_capacity()` without any specific ratings will find anyone with a researched capacity rating between 1 and 14 (so 99's are excluded, and those with no capacity ratings are excluded).
## The `not()` operator {#widget-not-operator}
Within a widget, you can use `not` to modify what you're looking for. For example, you can type `gave_to_fund_type(not(endowment))` to find donors who gave to any kind of fund **other than** endowment funds. For an example of when this can be useful, see [the MBA dual-degree holder example](#ex-mba-dual).
## Detailed controls {#detailed-controls}
We saw above that `gave_to_area(business)` will find people who have given to the Haas School of Business. By default, this will find anyone who has ever given any amount, at any time. But `gave_to_area`, like many widgets, has a number of optional arguments that allow more fine-grained control. For example:
- `gave_to_area(business, at_least = 10000)`: finds anyone who has given at least $10,000 lifetime to the school of Business.
- `gave_to_area(business, at_least = 10000, from = 20160101)`: finds anyone who has given at least $10,000 to Business since the beginning of 2016.
- `gave_to_area(business, at_least = 10000, from = 20150101, to = 20151231)`: finds anyone who gave at least $10,000 to Business between January 1, 2015 and December 31, 2015.
- `gave_to_area(business, from = 20150101, to = 20151231)`: finds anyone who gave anything at all to the school of Business between January 1, 2015 and December 31, 2015
As you can see, you can pick and choose which optional arguments you want to use. To find out all of the possible controls for a widget, use the built in help. For example, type `?gave_to_area`.