README.Rmd

---
title: rfigshare tutorial
author: Carl Boettiger
---


<!--
%\VignetteEngine{knitr::knitr}
%\VignetteIndexEntry{An Introduction to the rfigshare package}
-->

[![Build Status](https://api.travis-ci.org/ropensci/rfigshare.png)](https://travis-ci.org/ropensci/rfigshare)




rfigshare
==========

*An R interface to [FigShare](http://figshare.com)*

* Maintainer: Carl Boettiger, [cboettig](https://github.com/cboettig)
* License: [CC0](http://creativecommons.org/publicdomain/zero/1.0/)
* Contact: Report bugs, questions, or feature requests on the [Issues Tracker](https://github.com/ropensci/rfigshare/issues), or get in touch with us at [info@ropensci.org](mailto:info@ropensci.org)


Getting Started
---------------
Figshare is an online digital repository where researchers can preserve and share their research outputs, including figures, datasets, images, and videos. It is free to upload content and free to access, in adherence to the principle of open data.

Key Features:
- Showcase your institution's research with a customizable portal of all public research outputs using the reporting and statistics feature.
- Have full control of your institution's research outputs with private storage, public storage and collaborative spaces with the data management feature.
- Filter your institution's research by department, category or file type, and rank content by most viewed, downloaded or shared with the data dissemination feauture. 
- Manage the curation of files to be made public, control quotas, and administer rights with the user group administration feature. 





# Using rfigshare


```{r}
library("rfigshare")
```


```{r include = FALSE}
# This loads the rOpenSci figshare sandbox credentials, so that the example 
# can run automatically during check and install.  Unlike normal figshare accounts,
# data loaded to this testing sandbox is periodically purged.  
fs_auth(token = "xdBjcKOiunwjiovwkfTF2QjGhROeLMw0y0nSCSgvg3YQxdBjcKOiunwjiovwkfTF2Q", token_secret = "4mdM3pfekNGO16X4hsvZdg")
```

The first time you use an `rfigshare` function, it will ask you to authenticate online. Just log in and click okay to authenticate rfigshare.  R will allow you to cache your login credentials so that you won't be asked to authenticate again (even between R sessions), as long as you are using the same working directory in future.  

Try a search for an author:


```{r}
fs_author_search("Boettiger")
```



Try creating your own content:


```{r}
id <- fs_create("Test title", "description of test")
```


This creates an article with the essential metadata information. We can now upload the dataset to this newly created figshare object using `fs_upload`.  For the purposes of this example, we'll just upload one of R's built-in datasets:


```{r}
data(mtcars)
write.csv(mtcars, "mtcars.csv")
fs_upload(id, "mtcars.csv")
```


Note that we must pass the id number of our the newly created figshare object as the first argument.  Similar functions let us add additional authors, tags, categories, and links, e.g.


```{r}
fs_add_tags(id, "demo")
```



Minimal metadata includes title, description, type, and at least one tag and one category.  We can add categories using either the category id or the name of the category, but it must be one of the preset categories available.  We can ask the API for a list of all the categories:


```{r}
fs_category_list()
```


And we can add the category or categories we like,


```{r}
fs_add_categories(id, c("Education", "Software Engineering"))
```



The file we have created remains saved as a draft until we publish it, either publicly or privately.  Note that once a file is declared public, it cannot be made private or deleted.  Let's release this dataset privately:


```{r}
fs_make_private(id)
```


We can now share the dataset with collaborators by way of the private url.  

### The quick and easy way

The `rfigshare` package will let you create a new figshare article with additional authors, tags, categories, etc in a single command usnig the `fs_new_article` function.  The essential metadata `title`, `description` and `type` are required, but any other information we omit at this stage can be added later.  If we set `visibility` to private or public, the article is published on figshare immediately.  


```{r}
data(mtcars)
write.csv(mtcars,"mtcars.csv")
id <- fs_new_article(title="A Test of rfigshare", 
                     description="This is a test", 
                     type="dataset", 
                     authors=c("Karthik Ram", "Scott Chamberlain"), 
                     tags=c("ecology", "openscience"), 
                     categories="Ecology", 
                     links="http://ropensci.org", 
                     files="mtcars.csv",
                     visibility="private")
unlink("mtcars.csv") # clean up
```


# Examining Data on Figshare

We can view all available metadata of a figshare object. 


```{r}
fs_details(id)
```

You can see all of the files you have (Currently only up to 10):


```{r}
mine <- fs_browse()
mine[1:2]
```

Note that we can easily grab the ids with the wrapper function `fs_ids`:



```{r}
fs_ids(mine)
```


We can delete unwanted files that are not public with `fs_delete`:  


```{r}
fs_delete(id)
```

To cite package `rfigshare` in publications use:


```{r}
citation("rfigshare")
```


[![ropensci.org logo](http://ropensci.org/public_images/github_footer.png)](http://ropensci.org)\