---
title: "clamour"
subtitle: "An introduction to the _clamour_ package"
date: "Last updated: 2019-07-07"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{clamour}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

# 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.

```{r library}
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][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.

```{r setup}
path <- fs::path(tempdir(), "example")
clamour_setup(path)
```

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_][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][rtweet].

# 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][pages] 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][example].

[pages]: https://pages.github.com/ "GitHub pages"
[rtweet]: https://rtweet.info/ "rtweet"
[example]: https://lazappi.github.io/clamour-example "clamour example"