library(giphyR, quietly = TRUE) test <- giphyR::search('giphy package', rating = 'g')
"This annual report is great, but it would be better with an animated image, taken from Shrek, where the donkey says something hilarious." - Anonymous CEO of a large international banking conglomerate
The increasing use of automated reporting using tools within scientific and administrative workflows, such as RMarkdown and Jupyter, has led users to require a greater range of tools to make their reports stand out. Significant steps within the R ecosystem have added custom table formatting using kable
, (OTHER PACKAGES) and SOMETHING ELSE. However, while animated GIFs have long been part of the common currency on Internet message boards and messaging applications such as Slack, for technical reasons animated GIFs have been absent from the peer reviewed literature and technical reports, even as journals move to online-only formats (e.g., Open Quaternary and Data Science Journal). The development of the giphyR
package allows researchers to place significant findings into context by linking them to simple animated images which serve to emphasize key points or distract from inconvenient results.
The giphyR
package binds to published endpoints of the giphy
Application Programming Interface (API) to connect to a library of animated images from Giphy, providing users with the ability to search, access and download images that can be used to adorn reports. The giphyR
package requires the use of the magick
R package, which itself is dependent on the software ImageMagick.
Instructions for installing ImageMagick and the magick
package are clearly described in the magick
package vignette.
giphyR
giphy
objectgiphyR
commands that return data objects from Giphy return an object of class giphy
. The object contains a number of parameters to support various image sizes, static and animated versions, and other image elements that provide image metadata. The object includes a large number of elements, some filled, some NA, depending on the Giphy response.
names(test)
The majority of these columns are either character
or integer
classes, however, images
and user
are both data.frame
s that contain more information about both the images and the users who uploaded the images. The images
element is itself a data.frame
of data.frame
s. There is a unique data.frame
for each image representation within the giphy
object. In general these include the original
and a downsized
table:
knitr::kable(head(test$images$original))
A giphy
print
ing a giphy
plot
ting a giphy
random
GIFsGiphy's random
endpoint provides a single random GIF that can be restriced to GIFs with a certain suitability rating, for example, 'g'
and 'pg'
. Leaving the rating
parameter unfilled results in an unrated GIF, and may cause issues for the user if the function is used in a workplace environment.
The giphyR
random()
function takes parameters tag
, which can help constrain search results, rating
, as discussed above, sticker
, which differentiates between larger sized GIFs without transparent backgrounds (sticker = FALSE
) and smaller GIFs with transparent backgrounds (sticker=TRUE
). This function is generally not recommended for users intent on auto-generating documents. As noted above, the results may include offensive or off-putting content. Stories have been told about a user who used random()
as part of a government document prepared for a G7 meeting and was promply fired by the Deputy Minister for Finance as a result of a GIF showing Scrooge McDuck swimming through a pile of money with the caption "Higher taxes feed the beast!".
The api_key
is used as part of Giphy's terms of use. Testing applications can use the default API key (the default for this package), but if a user intends to use this package as part of a production tool (for example, a Shiny app), then they should apply for their own API key.
random()
function:"If a picture is worth a thousand words, then an animated GIF is worth a thousand lols." - Sir John A. MacDonald, first Prime Minister of Canada
A user is generating techinical documentation for a new trans-continental passenger jet. To illustrate safety instructions they would like to illustrate calm and orderly de-planing in the event of a water landing. Following a block of text explaining the procedure they would like to embed a figure that would represent the textual description. Within the RMarkdown document, the user would encode:
/```r
deplaning <- giphyR::random(tag='safe deplaning', rating = 'g')
plot(deplaning)
/```
deplaning <- giphyR::random(tag='safe deplaning', rating = 'g') plot(deplaning)
trending
GIFsWithin social media it is important for companies to appear current and, in the parlance of the younger generation, 'hip with the jive'. Given this, it may be useful to include GIFs that are currently popular so that companies, consultants, or scientists working on projects that will have a public audience can seem 'hip to the jive'.
The trending()
function can return up to 100 trending results from the Giphy web service. These results cannot be limited by tag
, but can be restricted by rating (including rating = 'r'
, the restricted rating, which is the most permissive). As these GIFs will be embedded within documents for public consumption in most cases we recommed using a more restricted rating (as opposed to the 'r'
rating). In the following example, a researcher is looking for a recently popular GIF, and wants to return the 10^th^ result:
/```r
hip_gif <- giphyR::trending(rating = 'g')
plot(hip_gif, n = 10)
/```
hip_gif <- giphyR::trending(rating = 'g') plot(hip_gif, n = 10)
search
ing for GIFsWhen a researcher is preparing a document such as a grant proposal or a thesis document, the choice of an appropriate GIF may be critically important. It would be unfortunate if one's thesis committee were to open up the second chapter and find a GIF that, while it may be G rated, is inappropriate for the subject of the thesis. For this puspose one may use the search()
function to find a more appropriate GIF. If the thesis subject was, perhaps, the American chestnut (Castanea dentata), a tree once common in the northeastern United States, but currently in decline as the result of the Chestnut blight, a pathogenic fungus. To really highlight the importance of the work, the researcher chooses to include an animated GIF, but wishes to ensure the image is appropriate for the thesis:
/```r
chestnut_gif <- giphyR::search("chestnut tree", rating = "g")
plot(chestnut_gif, n = 10)
/```
chestnut_gif <- giphyR::search("chestnut tree", rating = "g") plot(chestnut_gif, n = 1)
translate
a word or phraseGiphy
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.