Learn R Programming

imguR Package

imguR enables intuitive uploading of plots created in R to the free image hosting service Imgur simply, quickly, and intuitively via the Imgur v3 API. The package is a complete client library for the Imgur API, meaning that one can also delete, favorite, and comment on images, as well as organize them in albums and galleries, among other operations.

By default, all images are loaded to Imgur anonymously. Optionally, using an OAuth2.0 login (see examples below), users can also gain full access to their own Imgur user account.

The Imgur Graphics Device

The two workhorse functions for anonymously uploading images to Imgur are imgur and imgur_off, the latter of which wraps dev.off and completes the image upload.

library('imguR')
i <- imgur('pdf') # first argument to `imgur` is any graphics device function
plot(x=1:10, y=-1:-10, col=1:10, pch=19, main="oh hai dere")
imgur_off(i)
# [1] "http://imgur.com/nsDOm"

To upload images to a user account, first complete an OAuth login (see next section) and then pass the OAuth2.0 token object to imgur, e.g.:

tkn <- imgur_login()
i <- imgur(token = tkn)
hist(rnorm(100))
imgur_off(i)

OAuth2.0 Support

By default, all operations in imguR are performed anonymously using an API key attached to the imguR package and registered by the package maintainer. To use the package in a non-anonymous fashion (and to obtain higher API rate limits), operations needs to include an token argument, which must contain an OAuth2.0 token object. Note: Some operations cannot be performed anonymously and must be performed with the token argument; these operations produce an error if no token is supplied.

Generating an OAuth2.0 token is easy in an interactive session using imgur_login() (and completing a user account login in your web browser on a screen that looks like this), the response of which is a Reference Class object that can be passed to all package functions. For example:

# login
tkn <- imgur_login()

# upload a simple plot
i <- imgur(token = tkn)
hist(rnorm(100))
imgur_off(i)

# check account details
account(token = tkn)
account_image_count(token = tkn)
account_album_count(token = tkn)

The OAuth2.0 token is moderately long lived. You can see when it expires by looking at, e.g., tkn$credentials$expiration. If a token expires, it can be refreshed using the refresh() method, e.g., tkn$refresh().

The ability to refresh the OAuth2.0 token also means that it is possible to use the token non-interactively. First, generate a token and save it locally (with the default cache = TRUE argument to imgur_login):

# generate a token interactively
tkn <- imgur_login()

Then, reload (using httr's built-in OAuth caching mechanism) and optionally refresh the token in the non-interactive session before performing any operations:

tkn <- imgur_login()
# tkn$refresh() # refresh token, if expired
i <- imgur(token = tkn)
hist(rnorm(100))
imgur_off(i)

Note: imgur_login uses OAuth credentials registered to the package maintainer. If you intend to make a very large number of API requests, it may be appropriate to register your own application. You can check user- and package-level rate limits with rate_limit.

Managing Images

If operations (e.g., upload_image) are performed with a token argument, they can subsequently be modified (e.g., update_image) by passing the relevant identifiers:

i <- imgur(token = tkn)
hist(rnorm(100))
u <- imgur_off(i)

# pass the `imgur_image` object to `update_image`:
update_image(u, title = 'My graph', description = 'A simple graph', token = tkn)

# or, pass just the image id:
update_image(u$id, title = 'My graph', description = 'A simple graph', token = tkn)

If you tried to perform the update_image operation without passing a token argument, the operation would fail. Similarly, if an image is uploaded anonymously, it is not possibly to anonymously modify it. Instead, the imgur_image response object (a simple list) will include a deletehash element, which is essentially a private key for the image. This can be used to modify the image:

i <- imgur()
hist(rnorm(100))
u <- imgur_off(i)

# pass just the image deletehash:
update_image(u$deletehash, title = 'My graph', description = 'A simple graph')

This procedure can also be used for other API operations, such as modifying albums. Not all operations can be performed anonymously, however.

Requirements and Installation

The current stable version imguR can be installed from CRAN using:

install.packages('imguR')

The development version can be installed directly from GitHub using ghit:

if(!require('ghit')) {
    install.packages('ghit')
}
ghit::install_github('leeper/imguR')

Copy Link

Version

Install

install.packages('imguR')

Monthly Downloads

1,170

Version

1.0.3

License

GPL-3

Issues

Pull Requests

Stars

Forks

Last Published

March 29th, 2016

Functions in imguR (1.0.3)

get_reddit_image

Get reddit image
delete_image

Delete image
create_message

Create a comments
report_comment

Report a comment
get_random_images

Get random images
imguR-package

Imgur API Client Package for R
get_replies

Get replies
report_gallery_image

Report a gallery image
get_conversations

Get conversations
get_gallery_image

Get gallery image
account_settings

Retrieve and modify account settings
get_comment

Get a comment
imgur_login

Login to Imgur
memes

Memes
get_gallery_album

Get gallery album
mark_notification

Mark notification read
account_gallery

User gallery profile
Authentication

Imgur API Authentication
rate_limit

API rate limits
account_favorites

Retrieve user favorites
get_notifications

Get notifications
search_gallery

Search gallery
account_images

Retrieve user images
imgur

Initiate an Imgur-enabled Graphics Device
http

Workhorse HTTP functions
remove_gallery_image

Remove gallery image
account_albums

Retrieve user albums
favorite_image

Favorite image
get_gallery

Get gallery
get_reddit_gallery

Get gallery
delete_comment

Delete a comment
update_image

Update image
plot

Plot Imgur image
imgur_off

Close an Imgur-linked plotting device and upload image
add_album_images

Manage album images
add_gallery_images

Add gallery images
create_album

Create album
create_comment

Create a comments
upload_image

Upload an image file to Imgur
get_image

Get image
vote_comment

Vote on a comment
block_sender

Block a user
update_album

Update album
account_comments

Retrieve user albums
get_album

Get album
account

Retrieve user account details
delete_album

Delete album
favorite_album

Favorite album
delete_conversation

Delete conversation
report_sender

Report a user