6 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:
library(discoveryengine)6.1 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:
Searching for widgets related to employment data
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:
widget_for("giving")## fund_area:
## Find funds with a particular area of giving code (type: allocation_code)
## fund_department:
## Find funds with a particular department code (type: allocation_code)
## fund_miner:
## Entities who gave to funds that match a keyword search (type: entity_id)
## fund_purpose:
## Find funds with a particular fund purpose (type: allocation_code)
## fund_text_contains:
## Funds with notes/biographies that contain the specified search string(s) (type: allocation_code)
## fund_type:
## Find funds with a particular fund type code (type: allocation_code)
## gave_to_area:
## Lists entities who gave to specific areas with minimum giving and specific date range (type: entity_id)
## gave_to_department:
## Lists entities who gave to specific departments with minimum giving and specific date range (type: entity_id)
## gave_to_fund:
## Entities who have given to specified funds (type: entity_id)
## gave_to_fund_type:
## Entities who have given to specific types of funds (type: entity_id)
## gave_to_purpose:
## Find donors to funds with a particular purpose (type: entity_id)
## has_philanthropic_affinity:
## Lists entities with philanthropic affinity(ies) (type: entity_id)
## has_philanthropic_interest:
## Lists entities with philanthropic interest(s) (type: entity_id)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.
6.2 Leveraging 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.
Autocomplete pop up for giving widgets
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, usegave_to_purpose. Typegave_toand wait for a second to see the full list of giving widgets. - Political contribution widgets (federal): Widgets for political contributions in federal elections all begin with the prefix
fec_. - Political contribution widgets (statewide): Widgets for political contributions in California elections all begin with the prefix
ca_.
In addition to entity widgets, other types of widgets are also helpfully grouped together.
- Every widget that pulls allocation codes instead of entity IDs begins with
fund_(for example,fund_typeorfund_department). - Contact report widgets all begin with
contact_(for examplecontact_text_containsorcontact_date). - Proposal-based widgets all begin with
proposal_(for example,proposal_actual_askorproposal_qualified).
Finally, bot_brainstorm and bot_matrix are aliases for the brainstorm_bot and the matrix_bot, and in general, typing bot_ and waiting for a second will show a full list of the disco engine’s bots.
6.3 Codes and 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.
6.4 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:
in_unit_portfolio(?business)## Regular codes and synonyms:
## synonym code
## business BUYou can enter partial terms:
in_unit_portfolio(?sci)## Regular codes and synonyms:
## synonym code
## greater_good_science_center GG
## qb3_quantitative_biosciences QB
## letters_science LS
## lawrence_hall_of_science LH
## neuroscience_institute NS
## letters_and_science LS
## neuroscience NS
## quantitative_bioscience QB
## quantitative_biosciences QBAnd even multiple search terms:
in_unit_portfolio(?bus, ?chem, ?public)## Regular codes and synonyms:
## synonym code
## business BU
## chemistry CH
## public_health PH
## public_policy PP
## communications_public_affairs PAWidgets 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 Businessgave_to_area(business, chemistry)would find anyone who has given to Business or to Chemistrygave_to_area(HSB, COC)is the same as abovegave_to_area(business, COC)once again, the same thing
6.5 Use the default cases
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():
did_anything = participated_in()
display(did_anything)## # A tibble: 256,802 x 1
## entity_id
## <dbl>
## 1 3
## 2 4
## 3 5
## 4 7
## 5 9
## 6 15
## 7 16
## 8 18
## 9 22
## 10 28
## # … with 256,792 more rowsThat 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).
6.6 The 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.
6.7 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.