testing permissions
[social-media-chapter.git] / README.md
1 ---
2 title: Software and data for "A Computational Analysis of Social Media Scholarship"
3 output: html_document
4 --- 
5
6 <link rel='stylesheet' href='./simple.css'>
7
8 > **Authors:** [Jeremy Foote](http://jeremydfoote.com/), [Aaron Shaw](http://aaronshaw.org/), [Benjamin Mako Hill](https://mako.cc/academic/)<br />
9 > **Archival copies of code and data:** <https://dx.doi.org/10.7910/DVN/W31PH5><br />
10 > **License:** see [COPYING file](COPYING): code is released under [GNU GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html) or any later version; chapter is released as [CC BY-NC-SA](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode).
11
12 <figure style="float:right">
13 <img src="./hairball.png"/>
14 <figcaption>Network "hairball" of social media papers published from 2004-2016</figcaption>
15 </figure>
16
17 Dramatic increases in large-scale data generated through social media, combined with increased computational power, have enabled the growth of computational approaches to social media research, and social science in general. While many of these approaches require statistical or computational training, they have the great benefit of being inherently transparent—allowing for research that others can reproduce and learn from.
18
19 To that end, we wrote a book chapter in the [Sage Handbook of Social Media](https://us.sagepub.com/en-us/nam/the-sage-handbook-of-social-media/book245739) in which we obtain a large-scale dataset of metadata about social media research papers which we analyze using a few commonly-used computational methods. This document is designed to tell you exactly how we did that and to walk you through how to reproduce our results and our paper by running the code we wrote.
20
21 This document is meant to be read alongside our chapter. The rest of this document describes how to download our code and data and how to reproduce the analyses in the chapter on your own computer. You can find and cite the chapter at the following: </br>
22
23 > Foote, Jeremy D., Aaron Shaw,  and Benjamin Mako Hill. 2017. “A Computational Analysis of Social Media Scholarship.”  In The SAGE Handbook of Social Media, edited by Jean Burgess, Alice Marwick, and Thomas Poell, 111–34. London, UK: SAGE. [[Official Link](https://uk.sagepub.com/en-gb/eur/the-sage-handbook-of-social-media/book245739)] [[Preprint PDF](http://mako.cc/academic/foote_shaw_hill-computational_analysis_of_social_media.pdf)]
24
25
26 ### Requirements and Expectations
27
28 We will be as explicit as possible in this document, and try to make it accessible to less-technical readers. However, we do make a few assumptions:
29
30 * You have access to and basic familiarity with [a POSIX command line interface](https://en.wikipedia.org/wiki/POSIX). The instructions here are written for and tested using [Debian](https://www.debian.org/) and [Ubuntu](https://www.ubuntu.com/) GNU/Linux. That said, these instructions should work without modification on most Linux systems.  Although MacOS users may need to [tweak a few things](MacInstallNotes), they should work there, too. Microsoft Windows users will likely need to tweak more things. This is particularly true for the last step—building the paper itself. If you can get a simple example like [this one](https://github.com/yihui/knitr-examples/blob/master/005-latex.Rtex) working, then there's a decent chance you can get the chapter to build.
31 * You have [Python 3.x](https://www.python.org/downloads/) installed. For many users, you will already have it installed. Debian and Ubuntu users can install it with `apt install python3`. Others can download it from [the Python download page](https://www.python.org/downloads/)
32 * You have [GNU R 3.x](https://www.r-project.org/) installed. Debian and Ubuntu users can install it with `apt install r-base`. Others can install it from [the R homepage](https://www.r-project.org/). In our testing we used versions GNU R versions 3.3.2 and 3.4.1.
33 * To conduct the bibliometric network analysis, you'll need the [igraph library](http://igraph.org/). To install it on Debian or Ubuntu you can run `apt install libigraph0v5`.
34 * You will also need the following Python libraries:
35
36 > * [Requests](http://docs.python-requests.org/en/master/)
37 > * [numpy](http://www.numpy.org/)
38 > * [pandas](https://pandas.pydata.org/)
39 > * [igraph](http://igraph.org/)
40 > * [sklearn](http://scikit-learn.org/stable/)
41 > * [scipy](https://www.scipy.org/)
42 > * [rpy2](https://rpy2.bitbucket.io/)
43 > * [matplotlib](https://matplotlib.org/)
44
45 > If you use Debian or Ubuntu, you install them with the following command run as root in your shell: 
46
47             apt install python3-requests  python3-numpy python3-pandas python3-igraph python3-sklearn python3-rpy2 python3-matplotlib
48                         
49 > Another way to install them is using `pip3` (or just `pip`) with the following command in your shell: 
50
51             pip3 install requests numpy pandas python-igraph sklearn scipy rpy2 matplotlib
52
53 * You will also need to install the following *R* libraries:
54
55 > * [ggplot2](http://ggplot2.org/)
56 > * [data.table](https://r-datatable.com/)
57 > * [reshape2](https://github.com/hadley/reshape)
58 > * [glmnet](https://cran.r-project.org/web/packages/glmnet/)
59 > * [txtplot](https://cran.r-project.org/web/packages/txtplot/)
60 > * [Matrix](https://cran.r-project.org/web/packages/Matrix/)
61 > * [xtable](https://cran.r-project.org/web/packages/xtable/)
62 > * [dplyr](http://dplyr.tidyverse.org/)
63 > * [knitr](https://yihui.name/knitr/)
64
65 > One way to install them is by running the command *from within a running copy of R*: 
66
67             install.packages(c("ggplot2", "data.table", "reshape2", "glmnet", "txtplot", "Matrix", "xtable", "dplyr", "knitr"))
68
69 We have ensured that every piece of software used in this analysis is [free/open source software](https://www.gnu.org/philosophy/free-sw.en.html) which means it is both available at no cost and, like our analysis code, is transparent and inspectable.
70
71 ### 1. Set up Your Environment
72
73 You'll want to start by creating a new directory. Then, download and extract the following file from the [the Harvard Dataverse repository for the paper](https://dx.doi.org/10.7910/DVN/W31PH5):
74
75 * [`code_and_paper.tar.gz`](https://dataverse.harvard.edu/file.xhtml?fileId=3107305) (this file is publicly accessible)
76
77 If this is successful, you should have two subdirectories: `code` and `paper`.
78
79 ### 2. Get the Scopus Data
80
81 The data for this project came from the [Scopus API](https://dev.elsevier.com/). An API ([Application Programming Interface](https://en.wikipedia.org/wiki/Application_programming_interface)) is basically a way for computers to talk to each other directly. In our case, we asked the Scopus API to give us metadata about a set of research papers. In order to replicate the analysis from the chapter, you have two options for getting this metadata.
82
83 #### 2.1. Option 1: Download the Data We Collected from Harvard Dataverse
84
85 As part of writing this paper, we did the work of downloading the metadata from Scopus and it is available in the [`raw_data.tar.gz`](https://dataverse.harvard.edu/file.xhtml?fileId=3106986) file on the Dataverse page. This dataset includes metadata about all of the papers that include the term "*social media*" in their title, abstract, or keywords, as well as all of the papers which cite these papers, as of February 2017.
86
87 Scopus won't let us make that dataset publicly accessible on the web, but we can grant you access to it through [the Harvard Dataverse](https://dataverse.harvard.edu/). Just request it through Dataverse. We ask that you only use the data for the purpose of reproducing this chapter.
88
89 Once you have downloaded the data, unpack it in the same directory that you unpacked the `code_and_data.tar.gz` file. Now you should have a third subdirectory: `raw_data`.
90
91 #### 2.2. Option 2: Get the Data from Scopus Yourself
92
93 If you want to download the data yourself instead of using the `raw_data.tar.gz` file we have prepared, follow the instructions in this section.  There are several reasons you might want to do this. For example, you might want to retrieve a new version of the dataset with details of more recent papers. Or you might want to do a similar analysis with a different search term.
94
95 In order to do this:
96
97 1. You must belong to an institution that has access to [Scopus](https://www.scopus.com/) and/or buy your own (absurdly expensive) subscription. 
98 2. You will need to be patient. Scopus has a weekly limit on requests to their API, and it may take multiple weeks to download all of the results.
99
100 You will also need to get an API key from <https://dev.elsevier.com/index.html>. In the `code/data_collection` directory, edit the `scopus_api.py` file so that it has your key. The file should look something like `key = 'XXXXXXXXXXXXXXXXX'` where your key replaces the Xs.
101
102 The Scopus API is a little odd, in that you are authenticated based on your key, but your permissions change based on your IP ([authentication documentation](https://dev.elsevier.com/tecdoc_api_authentication.html)). Jeremy noticed that he had to be logged into our Northwestern University VPN (even if he was on campus) in order to have all of the permissions needed to carry this out.
103
104 Getting the data is a three-step process:
105
106 1. First, we retrieve data about the papers which include the term "*social media*" in their title, abstract, or keywords. To do this, run the following command from the directory where you downloaded and unpacked our code archives:
107
108         mkdir raw_data
109         python3 code/data_collection/00_get_search_results.py -q 'title-abs-key("social media")' -o raw_data/search_results.json
110
111 > If you want to change the date range that is considered, then edit the `years` variable in the `code/data_collection/00_get_search_results.py` file.
112
113 2. Next, we take each of those results and query the API to get more detailed information about them (e.g., abstracts). To do that, run:
114
115         python3 code/data_collection/01_get_abstracts.py -i raw_data/search_results.json -o raw_data/abstracts_and_citations.json
116
117 3. Finally, the search results are then used as input to get a some basic metadata about all of the papers that cite them (we use these data for the network analysis):
118
119         python3 code/data_collection/02_get_cited_by.py -i raw_data/search_results.json -o raw_data/cited_by.json
120
121 ### 3. Clean the Data
122
123 Whichever option you used above, you should now have a `raw_data` subdirectory which contains the files `search_results.json`, `abstracts_and_citations.json`, and `cited_by.json`.
124
125 These raw data files are "raw" in the sense that they contain lots of data we are looking for as well as lots of things we didn't use in this analysis. They are also in JSON format which is not the best format for most of the tools we'll use for our analysis. As a result, we will clean them up to make them easier to work with.
126
127 All of the following commands should be run from the directory where you downloaded the material.
128
129 1. First, create a `processed_data` directory in the root directory with `raw_data`, `code`, etc., to store all of these processed data files:
130
131         mkdir processed_data
132
133 2. We'll start by changing the abstracts file into a tab-separated value (TSV) table:
134
135         python3 code/data_processing/00_abstracts_to_tsv.py -i raw_data/abstracts_and_citations.json -o processed_data/abstracts.tsv
136
137 3. We'll also make a few additional tables to make it easier to work with the data. A social network "edgelist" file which lists which papers cite each other:
138
139         python3 code/data_processing/01_cited_by_to_edgelist.py -i raw_data/cited_by.json -o processed_data/citation_edgelist.txt
140
141 4. And a filtered version of this file which only lists the papers which include "social media" in their abstract, title, or keywords:
142
143         python3 code/data_processing/02_filter_edgelist.py -i processed_data/citation_edgelist.txt -o processed_data/social_media_edgelist.txt
144
145 5. Finally, we make a few tables that are easy to import into R:
146
147         python3 code/data_processing/03_make_paper_aff_table.py -i raw_data/abstracts_and_citations.json -o processed_data/paper_aff_table.tsv
148         python3 code/data_processing/04_make_paper_subject_table.py -i raw_data/abstracts_and_citations.json -o processed_data/paper_subject_table.tsv 
149
150 Once we have all the data cleaned and prepared, we are ready to proceed to our analysis. Our general workflow for analysis will be to run our analysis code and then save the output to an RData file in the `paper/data/` subdirectory. We will then import these RData files into the chapter to create figures and tables.
151
152 Doing this will require two final steps:
153
154 6. First, you'll need to create the directory:
155
156         mkdir paper/data
157
158 7. Before we get to the analysis, though, we'll save some portions of the processed datasets to the `paper/data` subdirectory by running the following command, which will help us access the processed data directly from our chapter in order to report descriptive statistics:
159
160         Rscript code/data_processing/05_save_descriptives.R
161
162 ### 4. Bibliometric Analysis
163
164 #### 4.1 Cluster Analysis and Network Statistics
165
166 The code used for our bibliometric analysis is contained within the `code/bibliometrics/` subdirectory.
167
168 We've included two copies of our Python code for our bibliometric analysis in the files `00_citation_network_analysis.py` and `00_citation_network_analysis.ipynb`. We will describe using the former in this section. If you have [Jupyter](https://jupyter.org/) installed you can open the file in a a notebook format used by many scientists by running `jupyter-notebook citation_network_analysis.ipynb`. If you want to try Jupyter, Debian and Ubuntu users can install it with `apt install jupyter-notebook` and other users can download it [here](https://jupyter.org/install.html).
169
170 Our bibliometric analysis code does require one additional piece of software called [Infomap](http://www.mapequation.org/) which we use to identify clusters in our citation network. There are some [instructions online](https://github.com/mapequation/infomap) but you can download and install it with the following commands run from the `code/bibliometrics` subdirectory:
171
172             mkdir output_dir
173         git clone git@github.com:mapequation/infomap.git
174         cd infomap
175         make
176
177 Once you have Infomap installed, running our bibliometric analysis all done with a single Python command run from the root directory:
178
179         python3 code/bibliometrics/00_citation_network_analysis.py
180
181 This will save the output to `paper/data/network_data.RData`. This data is used in the bibliometric section, for example, to create Table 4 and Figure 3.
182
183 #### 4.2 Network Visualizations
184
185 If you want to create our two network diagrams, you'll need one additional piece of software: [Gephi, the Open Graph Viz Platform](https://gephi.org/). We used it to generate Figure 2 in the chapter, a "hairball" network graph of the citation network in our dataset.  Like all the software used here, it is free/open source software and available for [download](https://gephi.org/users/download/).
186
187 Gephi is a graphical and interactive tool so, unlike the rest of our analysis, it will take some clicking around to reproduce our graph exactly. 
188
189 We created Figure 2 in the following way:
190
191 1. Open the file `code/bibliometrics/g_sm.graphml`
192 2. On the top part of the left sidebar, click on: *Appearance*, *Node*, the color palette icon, *Partition*, select "cluster" from the drop-down, and then *▶Apply*.
193 3. In the *Layout* tab, Select "Fruchterman Reingold" and then click *Run*. (This will take a really long time!)
194
195 To create the small network cluster in Figure 3:
196
197 1. Open the file `code/bibliometrics/cluster.graphml`
198 2. In the *Layout* tab, select "Fruchterman Reingold" and then click *Run*. 
199 3. Click on: *Appearance*, *Node*, the color palette icon, *Partition*, select "name" from the drop-down, and then click *▶Apply*.
200 4. Click on: *Appearance*, *Node*, the size icon concentric circles, *Ranking*, select "papers" from the drop-down, fiddle with the min and max sizes, and then click *▶Apply*.
201
202 Getting things just right will take some fiddling! We've included our Gephi files (`code/bibliometrics/clusters.gephi` and `code/bibliometrics/g_sm.gephi`) which are finished or mostly finished versions that you can open up and use if you'd like.
203
204
205 ### 5. Topic Modeling Analysis
206
207 The `code/topic_modeling` directory applies [latent Dirichlet allocation](https://en.wikipedia.org/wiki/Latent_Dirichlet_allocation)(LDA) topic modeling to the social media abstracts.
208
209 LDA takes in a set of documents and produces a set of topics and a distribution of topics for each document. The first file takes in the abstract file, and creates two outputs: The abstracts together with their topic distribution and a set of topics and the top words associated with each.
210
211 Our topic modeling analysis includes the following steps:
212
213 1. Run the following Python script that extracts our topics:
214
215         python3 code/topic_modeling/00_topics_extraction.py
216
217 > Note that this will take some time —5-10 minutes on a decent laptop.
218
219 2. Run a second file which (a) makes a couple of tables of the top words for each topic and (b) generates some summary statistics for how the topics change over time. These statistics are used, e.g., to create Figure 4. You can run this with:
220
221         python3 code/topic_modeling/01_make_paper_files.py
222
223 Topic modeling is a stochastic process, and you may notice differences—potentially large differences—between the results in our chapter and the results when you run it. If the order of topics has changed (or if you think other labels would be appropriate for some topics), then you can adjust the topic names by editing the `topic_names` list in the `01_make_papers.py` file.
224
225 ### 6. Prediction Analysis
226
227
228 For the prediction analysis, we use features of the papers to predict whether or not a paper gets cited. 
229
230 These commands require a computer with a large amount of memory (i.e., RAM). We had trouble running these steps on our laptops which did not have enough memory. If you don't have access to such a computer, then you can change the `n_features` variable in the `00_ngram_extraction.py` file from `100000` to something like `3000`. This will change how many terms are included in the prediction analysis, but shouldn't make an important difference in the results.
231
232 We ran the following steps:
233
234 1. Because one of the features we use is the text of the abstracts, we start by getting uni-, bi-, and tri-grams from the abstracts. This is done with the `00_ngram_extraction.py` python file: 
235
236         python3 code/prediction/00_ngram_extraction.py
237
238 > This will create an `ngram_table.csv` file in the `processed_data` directory.
239
240 2. Next, we build control variables:
241
242         Rscript code/prediction/01-build_control_variables.R 
243         
244 > This will build a set of descriptive variables, saved to `paper/data/prediction_descriptives.RData`
245
246 3. Then, we create textual features using the ngram table we created:
247
248         Rscript code/prediction/02-build_textual_features.R
249
250 > This step filters the ngrams to those which occur across 30 subject areas and saves them as a matrix at `processed_data/top.ngram.matrix.RData`.
251
252 4. Finally, the data that we've collected is put into models, and statistics are collected:
253
254         Rscript code/prediction/03-prediction_analysis.R
255
256 >This step will save the output of the models to `paper/data/prediction.RData`. 
257
258 Each of these final two steps will take a long time to run.
259
260 ### 7. Build the Chapter
261
262 Now we should have all of the data that we need sitting in the `paper/data` directory. We use a package called [knitr](https://yihui.name/knitr/) to load and manipulate data directly in the chapter. With the exception of the Gephi graphs, all of the tables and figures in the chapter are created using code that is in the same file where we write the text of the chapter. The knitr package is the magic behind the scenes that makes that possible.
263
264 To build the chapter, we will be using a [Makefile](https://www.gnu.org/software/make/manual/make.html) which requires a set of utilities to run. This is the part that might get a little tricky for Windows users.
265
266 You can install the packages you'll need from Debian or Ubuntu with the following command: 
267
268             apt install rubber latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-extra texlive-fonts-recommended texlive-bibtex-extra moreutils gawk
269
270 After this, you should change to the `paper` directory and simply run the command `make`.
271
272 This will produce a quickly scrolling output to standard out, and if everything has worked, then in the end it will produce a bunch of files in the `paper` directory, one of which will be the final PDF file!
273
274 An alternative approach that does not involve installing software is to upload the entire paper subdirectory (including the paper/data subdirectory) as a paper repository to the service [ShareLaTeX](https://www.sharelatex.com/). In order to make it work, you'll also need to rename the file ending with `.Rnw` to `.Rtex`. We spent some of the time writing our paper using ShareLaTeX so this should work.
275
276 ### Help us Find Errors, Improvements, and Updates
277
278 Although we have tried to make this document as clear as possible and although we have tested it ourselves, there are many ways it might fail. You might have a different software environment or the software dependencies we have used might have [bit rot](https://en.wikipedia.org/wiki/Software_rot) over time in a way that leads to things breaking.
279
280 You are welcome to get in touch with us if you have questions and we have provided our webpages and emails here for that purpose:
281
282 * [Jeremy Foote](http://jeremydfoote.com/) <<jdfoote1@gmail.com>>
283 * [Aaron Shaw](http://aaronshaw.org/) <<aaronshaw@northwestern.edu>>
284 * [Benjamin Mako Hill](https://mako.cc/academic/) <<makohill@uw.edu>>
285
286 If you can fix issues you run into, find ways to clarify our instructions, or make fixes to our code, please tell us! We'd love to add helpful improvements to these materials.
287
288 In addition to the [archival version in the Dataverse](https://dx.doi.org/10.7910/DVN/W31PH5), we have hosted our code in a [git revision control management](https://git-scm.com/) repository here: <https://code.communitydata.cc/social-media-chapter.git> Even the page you are reading is included in our repository. If you notice any typos or errors, please send us your fix! To do so, you can follow the [instructions we have posted](https://code.communitydata.cc/) for sending updated versions of our code or documentation. Your work and improvements can help others trying to replicate and learn from this project.

Community Data Science Collective || Want to submit a patch?