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/RtmpgcD0tD/example/'
#> ✔ Setting active project to "/tmp/RtmpgcD0tD/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

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:

1. Automatically retrieve tweets using rtweet (or from the cached data file)
2. Save the data as a file with the same name as the analysis in the data/ directory
3. Perform the analysis in the _analysis.Rmd file
4. 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:

1. Set up a git repository and commit your files, including the docs/ directory
2. Create a new repository on GitHub, set this as a remote and push your files
3. 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.