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.
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 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.
The majority of these columns are either
integer classes, however,
user are both
data.frames that contain more information about both the images and the users who uploaded the images. The
images element is itself a
data.frames. There is a unique
data.frame for each image representation within the
giphy object. In general these include the
original and a
random endpoint provides a single random GIF that can be restriced to GIFs with a certain suitability rating, for example,
'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.
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!".
"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)
Within 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'.
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)
searching for GIFs
When 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)
translatea word or phrase
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.