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,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%",
  message = FALSE
)
```

# tidytags <a href='https://docs.ropensci.org/tidytags/'><img src='man/figures/logo.png' align="right" height="138" /></a>

##### *Importing and Analyzing 'Twitter' Data Collected with 'Twitter Archiving Google Sheets'*

<!-- badges: start -->

<!-- For additional badges for CRAN, see https://docs.ropensci.org/drake/ -->

<table class="table">

<thead>
<tr class="header">

<th align="left">
Usage
</th>

<th align="left">
Release
</th>

<th align="left">
Development
</th>

<th align="left">
Checks
</th>

</tr>
</thead>

<tbody>

<tr class="odd">

<td align="left">
<a href="https://choosealicense.com/licenses/mit/"><img src="https://img.shields.io/badge/licence-MIT-9cf.svg" alt="Licence"></a>
</td>

<td align="left">
<a href="https://github.com/ropensci/software-review/issues/382"><img src="https://badges.ropensci.org/382_status.svg" alt="rOpenSci Peer Review"></a>
</td>

<td align="left">
<a href="https://www.repostatus.org/#active/"><img src="https://www.repostatus.org/badges/latest/active.svg" alt="Status"></a>
</td>

<td align="left">
<a href="https://github.com/ropensci/tidytags/actions/"><img src="https://github.com/ropensci/tidytags/workflows/R-CMD-check/badge.svg" alt="Check"></a>
</td>

</tr>

<tr class="even">

<td align="left">
<a href="https://cran.r-project.org/"><img src="https://img.shields.io/badge/R%3E%3D-4.2.0-blue.svg" alt="Minimal R Version"></a>
</td>

<td align="left">
<a href="https://cran.r-project.org/package=tidytags"><img src="https://www.r-pkg.org/badges/version/tidytags" alt="CRAN"></a>
</td>

<td align="left">
<a href="https://lifecycle.r-lib.org/articles/stages.html#stable"><img src="https://lifecycle.r-lib.org/articles/figures/lifecycle-stable.svg" alt='Lifecycle'></a>
</td>

<td align="left">
<a href="https://app.codecov.io/gh/ropensci/tidytags?branch=main"><img src="https://codecov.io/gh/ropensci/tidytags/coverage.svg?branch=main" alt="Codecov"></a>
</td>

</tr>

<tr class="odd">

<td align="left">
</td>

<td align="left">
</td>

<td align="left">
<a href="https://github.com/ropensci/tidytags/commits/main"><img src="https://img.shields.io/github/last-commit/ropensci/tidytags.svg" alt="Last Commit"></a>
</td>

<td align="left">
</td>

</tr>

</tbody>

</table>

<!-- badges: end -->
---

## Overview

The purpose of **tidytags** is to make the collection of Twitter data more accessible and robust. **tidytags** retrieves tweet data collected by a [Twitter Archiving Google Sheet (TAGS)](https://tags.hawksey.info/), gets additional metadata from Twitter via the **[rtweet](https://docs.ropensci.org/rtweet/)** R package, and provides additional functions to facilitate a systematic yet flexible analyses of data from Twitter. TAGS is based on Google spreadsheets. A TAGS tracker continuously collects tweets from Twitter, based on predefined search criteria and collection frequency.

In short, **tidytags** first uses TAGS to easily collect tweet ID numbers and then uses the R package **rtweet** to re-query the Twitter API to collect additional metadata. **tidytags** also introduces functions developed to facilitate systematic yet flexible analyses of data from Twitter.

Two vignettes illustrate the setup and use of the package:

- [Getting started with tidytags](https://docs.ropensci.org/tidytags/articles/setup.html) (`vignette("setup", package = "tidytags")`)
- [Using tidytags with a conference hashtag](https://docs.ropensci.org/tidytags/articles/tidytags-with-conf-hashtags.html) (`vignette("tidytags-with-conf-hashtags", package = "tidytags")`)

---

## Installation

To get the current released version of **tidytags** from CRAN:

```{r, eval=FALSE}
install.packages("tidytags")
```

Or you can install the development version of **tidytags** from GitHub:

```{r, eval=FALSE}
install.packages("tidytags", repos = "https://ropensci.r-universe.dev")
```

Once installed, use the `library()` function load **tidytags**:

```{r}
library(tidytags)
```

---

## Setup

For help with initial **tidytags** setup, see the [Getting started with tidytags](https://docs.ropensci.org/tidytags/articles/setup.html) vignette (`vignette("setup", package = "tidytags")`). Specifically, this guide offers help for two key tasks:

1. Making sure your TAGS tracker can be accessed
2. Getting and storing Twitter API tokens

---

## Usage

To test the **tidytags** package, you can use an openly shared TAGS tracker that has been collecting tweets associated with the AECT 2019 since September 30, 2019. This is the same TAGS tracker used in the [Using tidytags with a conference hashtag vignette](https://docs.ropensci.org/tidytags/articles/tidytags-with-conf-hashtags.html) (`vignette("tidytags-with-conf-hashtags", package = "tidytags")`).

---

## Core Functions

### read_tags()

At its most basic level, **tidytags** allows you to import data from a [Twitter Archiving Google Sheet](https://tags.hawksey.info/) (TAGS) into R. This is done with the **[googlesheets4](https://CRAN.R-project.org/package=googlesheets4)** R package. One requirement for using the **googlesheets4** package is that your TAGS tracker has been "published to the web." See the  [Getting started with tidytags](https://docs.ropensci.org/tidytags/articles/setup.html) vignette (`vignette("setup", package = "tidytags")`), **Key Task #1**, if you need help with this.

Once a TAGS tracker has been published to the web, you can import the TAGS archive into R using `read_tags()`.

```{r}
example_tags <- "18clYlQeJOc6W5QRuSlJ6_v3snqKJImFhU42bRkM_OX8"
tags_data <- read_tags(example_tags)
head(tags_data)
```

### pull_tweet_data()

With a TAGS archive imported into R, **tidytags** allows you to gather quite a bit more information related to the collected tweets with the `pull_tweet_data()` function. This function uses the **[rtweet package](https://docs.ropensci.org/rtweet/)** (via `rtweet::lookup_tweets()`) to query the Twitter API. 

This process requires Twitter API keys associated with an approved Twitter developer account. See the  [Getting started with tidytags](https://docs.ropensci.org/tidytags/articles/setup.html) vignette (`vignette("setup", package = "tidytags")`), **Key Task #2**, if you need help with this.

```{r}
app <- rtweet::rtweet_app(bearer_token = Sys.getenv("TWITTER_BEARER_TOKEN"))
rtweet::auth_as(app)

expanded_metadata <- pull_tweet_data(tags_data, n = 10)
expanded_metadata
```

---

## Workflow

The following diagram represents how the functions included in the **tidytags** package may work together. These are presented in the figure below.

<p align="center"><img src="man/figures/tidytags-workflow.jpg" alt="tidytags workflow" width="600"></p>

---

## Learning More About **tidytags**

For a walkthrough of numerous additional **tidytags** functions, see the [Using tidytags with a conference hashtag](https://docs.ropensci.org/tidytags/articles/tidytags-with-conf-hashtags.html) vignette (`vignette("tidytags-with-conf-hashtags", package = "tidytags")`).

---

## Getting Help

```{r, child='./man/fragments/getting-help.Rmd'} 
```

---

## Considerations Related to Ethics, Data Privacy, and Human Subjects Research 

```{r, child='./man/fragments/ethics.Rmd'} 
```

---

## Contributing

If you encounter an obvious bug for which there is not already an [active issue](https://github.com/ropensci/tidytags/issues/), please [create a new issue](https://github.com/ropensci/tidytags/issues/new/) with all code used (preferably a reproducible example) on GitHub.

If you would like to become a more involved contributor, please read the [Contributing Guide](https://github.com/ropensci/tidytags/blob/master/CONTRIBUTING.md/).

### Contributor Code of Conduct

Please note that this package is released with a [Contributor Code of Conduct](https://ropensci.org/code-of-conduct/). By contributing to this project, you agree to abide by its terms.

---

## How to Cite This Package in Publications

You can cite this package like this: "we collected, processed, and analyzed Twitter data  using the tidytags R package (Staudt Willet & Rosenberg, 2022)". Here is the full bibliographic reference to include in your reference list:

> Staudt Willet, K. B., & Rosenberg, J. M. (2022). tidytags: Importing and analyzing Twitter data collected with Twitter Archiving Google Sheets. https://github.com/ropensci/tidytags

---

## License [![license](https://img.shields.io/badge/licence-MIT-9cf.svg)](https://choosealicense.com/licenses/mit/)

The **tidytags** package is licensed under the [*MIT License*](https://choosealicense.com/licenses/mit/). For background on why we chose this license, read this chapter on [R package licensing](https://r-pkgs.org/license.html).