README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  cache = FALSE,
  comment = "",
  prompt = TRUE,
  fig.path = "man/figures/README-",
  out.width = "100%"
)
if (dir.exists(".tmp")) unlink(".tmp", recursive = TRUE)
dir.create(".tmp/rstats", recursive = TRUE, showWarnings = FALSE)
knitr::opts_knit$set(root.dir = ".tmp/rstats")
```

[rtweet]: https://rtweet.info
[cron]: https://en.wikipedia.org/wiki/Cron

<h1 style="font-weight: normal;">gathe<strong>rtweet</strong></h1>

The goal of gathertweet is to provide a simple command line utility that wraps key functions from [rtweet].

The magic of **gathertweet** is that it grants you the power to **quickly set up twitter monitoring and tweet gathering** while saving you from the pain of **writing a bunch of boilerplate code** to 

- save new tweets without losing previously collected tweets, 
- join multiple searches, 
- update tweet stats, 
- simplify stored tweets,
- schedule easily with [cron],
- and more...

gathe**rtweet** is a thin wrapper around [rtweet], the excellent R interface to Twitter written by [Mike Kearney](https://mikewk.com/).
If you use gathertweet, please ensure that you [cite rtweet directly](https://rtweet.info/authors.html).

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

## Installation

This is a work in progress and may not work well for you yet.
But you are welcome to install **gathertweet** and try it out.

```r
# install.packages("remotes")
remotes::install_github("gadenbuie/gathertweet")
```

Once you've installed the package, you need to run

```r
gathertweet::install_gathertweet()
```

which adds `gathertweet` to `/usr/local/bin` as a symlink (you can adjust where this link is created in `install_gathertweet()`).
If you need admin rights to install, try 
```
sudo Rscript -e "gathertweet::install_gathertweet()"
``` 
from the command line.


## Example

### Use gathertweet from the command line

Create a directory to store tweets

```bash
mkdir rstats
cd rstats
```

```{r include=FALSE}
knitr::opts_knit$set(root.dir = ".tmp/rstats")
```

Get 100 #rstats tweets

```{bash}
gathertweet search --n 100 --quiet "#rstats"
```

Get more tweets, automatically starting from end of the last search

```{r include=FALSE}
Sys.sleep(60)
```

```{bash}
gathertweet search --n 100 --quiet "#rstats"
```

Update the stored data about those #rstats tweets

```{bash}
gathertweet update
```

```{bash}
ls -lh
```

Gather user timelines

```{bash}
gathertweet timeline hadleywickham jennybryan dataandme
```

### Schedule tweet gathering using cron

The primary use case of gathertweet is to make it easy to set up [cron] to periodically gather tweets.
Here's a simple example to download all tweets matching the search term `rstats OR tidyverse` every night at midnight.
The tweets are stored, by default, in `tweets.rds` in `~/rstats-tweets`.

```bash
crontab -e

# m h dom mon dow   command
0 0 * * * (cd ~/rstats-tweets && ~/bin/gathertweet search --polite 'rstats OR tidyverse' >>gathertweet.log)
```

## Documentation

```bash
> gathertweet --help
```

```{bash gathertweet_help, echo=FALSE}
../../inst/gathertweet.R --help
```