Introduction

clamour is a package to help with building a website to display the results of analysis of Twitter hashtags, usually associated with an event such as an academic conference. The package provides some basic infrastructure and examples to help you get set up.

library(clamour)

This vignette will take you through the basics of setting up a clamour project, analysis of an example dataset and how to host the results on a website using GitHub pages.

Setting up

To start a clamour project we can use the clamour_setup function. This will create a basic directory structure with some template files. We just need to provide the function with a path to the new project directory. For this vignette we use a temporary directory.

path <- fs::path(tempdir(), "example")
clamour_setup(path)
#> ✔ Creating '/tmp/Rtmp2EP8XH/example/'
#> ✔ Setting active project to '/tmp/Rtmp2EP8XH/example'
#> ✔ Creating 'analysis/'
#> ✔ Creating 'analysis/figures/'
#> ✔ Adding '^analysis/figures$' to '.Rbuildignore'
#> ✔ Writing 'analysis/_site.yml'
#> ✔ Writing 'analysis/index.Rmd'
#> ✔ Writing 'analysis/about.Rmd'
#> ✔ Writing 'analysis/_analysis.Rmd'
#> ✔ Writing 'analysis/EXAMPLE.Rmd'
#> ✔ Creating 'R/'
#> ✔ Writing 'R/libraries.R'
#> ✔ Writing 'R/knitr-options.R'
#> ✔ Creating 'docs/'
#> ✔ Creating 'data/'
#> ✔ Copying 'data/EXAMPLE.Rds'
#> ✔ Writing 'README.md'
#> ● Run the following code to make sure rtweet is authorised:
#> `rt <- rtweet::search_tweets('#rstats', n = 1000)`
#> ✔ Setting active project to '<no active project>'

The result is the following directory structure:

analysis/ - Analysis files for each hashtag
- _site.yml - Website configuration file
- index.Rmd - Index page
- about.Rmd - About page
- EXAMPLE.Rmd - An example hashtag analysis file
- _analysis.Rmd - Analysis template that is applied to each hashtag
data/ - Data files containing tweets
- EXAMPLE.Rds - The example tweet dataset
docs/ - Rendered website files will go here

Authorising rtweet

The rtweet package is used to download tweets from Twitter but to do so it must first be authorised. The setup function will prompt you to run some code that should do this but if that is unsuccessful please refer to the information on the rtweet website.

Starting an analysis

When you want to add an analysis for a new hashtag or event you should run the clamour_new function. This function will create a new R Markdown document based on the arguments you have provided. See the EXAMPLE.Rmd file for an example of what this looks like. Parameters for this analysis are provided in the YAML section at the start of the file (see ?clamour_new for more description of these). After loading the tweet data there is an introduction where you can describe the analysis in more detail. Most of the analysis is performed by the chunk labelled analysis which knits the _analysis.Rmd file. By having the analysis code in a separate file it is easy to update it in one place and apply those changes to every analysis on your website.

To make sure that your new analysis will be accessible our your website remember to render the index.html file. The template for this file contains a call to clamour_list() which should automatically add a link to your new analysis.

Running an analysis

Individual analysis files can be rendered by using rmarkdown::render() or pressing the “Knit” button in RStudio. Doing this should:

Automatically retrieve tweets using rtweet (or from the cached data file)
Save the data as a file with the same name as the analysis in the data/ directory
Perform the analysis in the _analysis.Rmd file
Save the output HTML file to the docs/ directory

Serving your website

The clamour template assumes that you will be serving your website using GitHub pages but it should also be possible use other similar services (with minor modifications). Details on setting up GitHub pages are available here but briefly the steps are:

Set up a git repository and commit your files, including the docs/ directory
Create a new repository on GitHub, set this as a remote and push your files
Change the settings on GitHub to serve the files in the docs/ directory

By default your website will be available at a URL like https://GITHUB-USER.github.io/REPOSITORY. You can see what the example website looks like here.

clamour