]> code.communitydata.science - social-media-chapter.git/blob - README.md
a554433ee011ffc76b3f3a9b0b76610210c3e28b
[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 > **Authors:** [Jeremy Foote](http://jeremydfoote.com/), [Aaron Shaw](http://aaronshaw.org/), [Benjamin Mako Hill](https://mako.cc/academic/)<br />
7 > **Archival copies of code and data:** <https://dx.doi.org/10.7910/DVN/W31PH5><br />
8 > **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 for code; paper is released as [CC BY-NC-SA](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode).
9
10 <figure style="float:right">
11 <img src="./hairball.png"/>
12 <figcaption>Network "hairball" of social media papers published from 2004-2016</figcaption>
13 </figure>
14
15 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.
16
17 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.
18
19 This document is meant to be read alongside our chapter. You can find the chapter here:
20
21 > 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)]
22
23 The rest of this document describes how to download our code and data and how to reproduce the analyses in the paper on your own computer.
24
25 ### Requirements and Expectations
26
27 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:
28
29 * 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, 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 paper to build.
30 * 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/)
31 * 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.
32 * 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`.
33 * You will also need the following Python libraries:
34
35 > * [Requests](http://docs.python-requests.org/en/master/)
36 > * [numpy](http://www.numpy.org/)
37 > * [pandas](https://pandas.pydata.org/)
38 > * [igraph](http://igraph.org/)
39 > * [sklearn](http://scikit-learn.org/stable/)
40 > * [scipy](https://www.scipy.org/)
41 > * [rpy2](https://rpy2.bitbucket.io/)
42 > * [matplotlib](https://matplotlib.org/)
43
44 > If you use Debian or Ubuntu, you install them with the following command run as root in your shell: 
45
46             apt install python3-requests  python3-numpy python3-pandas python3-igraph python3-sklearn python3-rpy2 python3-matplotlib
47                         
48 > Another way to install them is using `pip3` (or just `pip`) with the following command in your shell: 
49
50             pip3 install requests numpy pandas python-igraph sklearn scipy rpy2 matplotlib
51
52 * You will also need to install the following *R* libraries:
53
54 > * [ggplot2](http://ggplot2.org/)
55 > * [data.table](https://r-datatable.com/)
56 > * [reshape2](https://github.com/hadley/reshape)
57 > * [glmnet](https://cran.r-project.org/web/packages/glmnet/)
58 > * [txtplot](https://cran.r-project.org/web/packages/txtplot/)
59 > * [Matrix](https://cran.r-project.org/web/packages/Matrix/)
60 > * [xtable](https://cran.r-project.org/web/packages/xtable/)
61 > * [dplyr](http://dplyr.tidyverse.org/)
62 > * [knitr](https://yihui.name/knitr/)
63
64 > One way to install them is by running the command *from within a running copy of R*: 
65
66             install.packages(c("ggplot2", "data.table", "reshape2", "glmnet", "txtplot", "Matrix", "xtable", "dplyr", "knitr"))
67
68 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.
69
70 ### 1. Setting up Your Environment
71
72 You'll want to start by creating a new directory. Download and extract following file from the [the Harvard Dataverse repository for the paper](https://dx.doi.org/10.7910/DVN/W31PH5):
73
74 * [`code_and_paper.tar.gz`](https://dataverse.harvard.edu/file.xhtml?fileId=3107305) (this file is publicly accessible)
75
76 If this is successful, you should have two subdirectories: `code` and `paper`.
77
78 ### 2. Getting the Scopus Data
79
80 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 paper, you have two options for getting this metadata.
81
82 #### 2.1. Option 1: Downloading Collected Data from Harvard Dataverse
83
84 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.
85
86 Scopus won't let us make that dataset publicly accessible on the web so you'll need to request access to it through [the Harvard Dataverse](https://dataverse.harvard.edu/) and we'll ask that you only use the data for the purpose of reproducing this paper.
87
88 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`.
89
90 #### 2.2. Option 2: Getting the Data Yourself
91
92 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.
93
94 In order to do this:
95
96 1. You must belong to an institution that has access to [Scopus](https://www.scopus.com/). 
97 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.
98
99 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.
100
101 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)). I noticed that I had to be logged into our university VPN (even if I was on campus) in order to have all of the permissions needed to carry this out.
102
103 Getting the data is a three-step process:
104
105 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:
106
107         mkdir raw_data
108         python3 code/data_collection/00_get_search_results.py -q 'title-abs-key("social media")' -o raw_data/search_results.json
109
110 > 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.
111
112 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:
113
114         python3 code/data_collection/01_get_abstracts.py -i raw_data/search_results.json -o raw_data/abstracts_and_citations.json
115
116 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):
117
118         python3 code/data_collection/02_get_cited_by.py -i raw_data/search_results.json -o raw_data/cited_by.json
119
120 ### 3. Cleaning the Data
121
122 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`.
123
124 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 won't use in this analysis. They are also in JSON format which is not the best format for bringing data into most of the tools we'll be using for our analysis. As a result, we will clean them up to make them easier to work with in the tools that we'll be using.
125
126 All of the following commands should be run from the directory where you downloaded the material.
127
128 1. First, create a `processed_data` directory in the root directory with `raw_data`, `code`, etc., to store all of these processed data files:
129
130         mkdir processed_data
131
132 2. We'll start by changing the abstracts file into a tab-separated value (TSV) table:
133
134         python3 code/data_processing/00_abstracts_to_tsv.py -i raw_data/abstracts_and_citations.json -o processed_data/abstracts.tsv
135
136 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:
137
138         python3 code/data_processing/01_cited_by_to_edgelist.py -i raw_data/cited_by.json -o processed_data/citation_edgelist.txt
139
140 4. And a filtered version of this file which only lists the papers which include "social media" in their abstract, title, or keywords:
141
142         python3 code/data_processing/02_filter_edgelist.py -i processed_data/citation_edgelist.txt -o processed_data/social_media_edgelist.txt
143
144 5. Finally, we make a few tables that are easy to import into R:
145
146         python3 code/data_processing/03_make_paper_aff_table.py -i raw_data/abstracts_and_citations.json -o processed_data/paper_aff_table.tsv
147         python3 code/data_processing/04_make_paper_subject_table.py -i raw_data/abstracts_and_citations.json -o processed_data/paper_subject_table.tsv 
148
149 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 paper to create figures and tables.
150
151 Doing this will require two final steps:
152
153 6. First, you'll need to create the directory:
154
155         mkdir paper/data
156
157 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 paper in order to report descriptive statistics:
158
159         Rscript code/data_processing/05_save_descriptives.R
160
161 ### 4. Bibliometric Analysis
162
163 #### 4.1 Cluster Analysis and Network Statistics
164
165 The code used for our bibliometric analysis is contained within the `code/bibliometrics/` subdirectory.
166
167 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 [Juypter](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).
168
169 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:
170
171             mkdir output_dir
172         git clone git@github.com:mapequation/infomap.git
173         cd infomap
174         make
175
176 Once you have Infomap installed, running our bibliometric analysis all done with a single Python command run from the root directory:
177
178         python3 code/bibliometrics/00_citation_network_analysis.py
179
180 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.
181
182 #### 4.2 Network Visualizations
183
184 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/). Figure 2 in the paper is 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/).
185
186 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. 
187
188 We created the the big network "hairball" in Figure 2 by starting in the following way:
189
190 1. Opening the file `code/bibliometrics/g_sm.graphml`
191 2. On the top part of the left sidebar, clicking on: *Appearance*, *Node*, the color palette icon, *Partition*, selecting "cluster" from the drop-down, and then *▶Apply*.
192 3. In the *Layout* tab, Selecting "Fruchterman Reingold" and then clicking *Run*. (This will take a really long time!)
193
194 To create the small network cluster in Figure 3 we began in the following way:
195
196 1. Opening the file `code/bibliometrics/cluster.graphml`
197 2. In the *Layout* tab, selecting "Fruchterman Reingold" and then clicking *Run*. 
198 3. Clicking on: *Appearance*, *Node*, the color palette icon, *Partition*, selecting "name" from the drop-down, and then clicking *▶Apply*.
199 4. Clicking on: *Appearance*, *Node*, the size icon concentric circles, *Ranking*, selecting "papers" from the drop-down, fiddling with the min and max sizes, and then clicking *▶Apply*.
200
201 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.
202
203
204 ### 5. Topic Modeling Analysis
205
206 The topic in the `code/topic_modeling` directory applies [latent Dirichlet allocation](https://en.wikipedia.org/wiki/Latent_Dirichlet_allocation) topic modeling to the social media abstracts.
207
208 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.
209
210 Our topic modeling analysis includes the following steps:
211
212 1. Running the following Python script that extracts our topics:
213
214         python3 code/topic_modeling/00_topics_extraction.py
215
216 > Note that this will take some time —5-10 minutes on a decent laptop.
217
218 2. Running 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:
219
220         python3 code/topic_modeling/01_make_paper_files.py
221
222 Topic modeling is a stochastic process, and you may notice differences—potentially large differences—between the results in our paper 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.
223
224 ### 6. Prediction Analysis
225
226
227 For the prediction analysis, we use features of the papers to predict whether or not a paper gets cited. 
228
229 These commands require a computer with a large amount of memory (i.e., RAM). We had trouble running this step on our laptops which did not have enough. 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.
230
231 We ran the following steps:
232
233 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` python file: 
234
235         python3 code/prediction/00_ngram_extraction.py
236
237 > This will create an `ngram_table.csv` file in the `processed_data` directory.
238
239 2. Next, we build control variables:
240
241         Rscript code/prediction/01-build_control_variables.R 
242         
243 > This will build a set of descriptive variables, saved to `paper/data/prediction_descriptives.RData`
244
245 3. Then, we create textual features using the ngram table we created:
246
247         Rscript code/prediction/02-build_textual_features.R
248
249 > 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`.
250
251 4. Finally, the data that we've collected is put into models, and statistics are collected:
252
253         Rscript code/prediction/03-prediction_analysis.R
254
255 >This step will save the output of the models to `paper/data/prediction.RData`. 
256
257 Each of these final two steps will take a long time to run.
258
259 ### 7. Building the Paper
260
261
262 Now we should have all of the data that we need sitting in the `paper/data` directory. We use a really neat package called [knitr](https://yihui.name/knitr/) to load and manipulate data directly in the document. Nearly all of the tables and figures in the document are created using code that is in the document, and knitr is the magic behind the scenes that makes that possible.
263
264 To build the paper, 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 ### Errors, Improvements, and Updates
275
276 Although we have tried to make this document as clear as possible and although we have tested it carefully 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.
277
278 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:
279
280 * [Jeremy Foote](http://jeremydfoote.com/) <<jdfoote1@gmail.com>>
281 * [Aaron Shaw](http://aaronshaw.org/) <<aaron.d.shaw@gmail.com>>
282 * [Benjamin Mako Hill](https://mako.cc/academic/) <<makohill@uw.edu>>
283
284 If you can fix issues you run into, find ways to clarify our instructions, or make fixes to our code, please tell us!
285
286 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>
287 Even the page you are reading is included in our repository. If you notice any typos or errors, please fix it and send us your fix!
288
289 Please feel to follow the [instructions we have posted](https://code.communitydata.cc/) for sending updated versions of our code or documentation so that others trying to replicate and learn from our work can benefit from your work and improvements!

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