imguR v1.0.3

0

Monthly downloads

0th

Percentile

An Imgur.com API Client Package

A complete API client for the image hosting service Imgur.com, including the an imgur graphics device, enabling the easy upload and sharing of plots.

Readme

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

CRAN Version Downloads Travis-CI Build Status codecov.io

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')

Functions in imguR

Name Description
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
No Results!

Last month downloads

Details

Type Package
Date 2016-03-29
License GPL-3
URL https://github.com/leeper/imguR
BugReports https://github.com/leeper/imguR/issues
NeedsCompilation no
Packaged 2016-03-29 09:32:21 UTC; THOMAS
Repository CRAN
Date/Publication 2016-03-29 11:55:23

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/imguR)](http://www.rdocumentation.org/packages/imguR)