projects.mako.cc - protection-tools/blob - README

   1 Page Protection: Another Missing Dimension of Wikipedia Research
   2 -------------------------------------------------------------------------
   3
   4 | Author: Benjamin Mako Hill <mako@atdot.cc> and Aaron Shaw <aaron.d.shaw@gmail.com>
   5 | Homepage: http://communitydata.cc/wiki-protection/
   6 | Code: http://projects.mako.cc/source/?p=protection-tools
   7 | License: GNU GPLv3 or any later version
   8 | Description:
   9
  10     Tools to generate a protection spells dataset from "raw" MediaWiki
  11     XML dumps like those published by the Wikimedia foundation.
  12
  13 General Information
  14 ----------------------
  15
  16 page protection log data is very uneven and changed its format many
  17 times.  For several years before 2008-09, data on the specific rights
  18 were recorded in comment fields but this was subject to incorrect
  19 parsing because people sometimes added additional information (or
  20 tried to reproduce the format "by hand" as well).
  21
  22 This code is limited to extracting and parsing only the most reliable
  23 information which means only protection data from 2008-09 and the
  24 point of data collection.
  25
  26 There are two sources of page protection data:
  27
  28 - A log file that contains log events including protections, moves,
  29   deletions, blocks, etc.
  30
  31 - A snapshot from Wikipedia MySQL database of protected pages at the
  32   point that the database (and log) was exported.
  33
  34 As mentioned above, our log data begins only in 2008-09 which means we
  35 have data on protection spells that is both right censored (i.e.,
  36 ongoing protection events) and left censored (i.e., protect spells
  37 that were ongoing in 2008-09.  Because protection data was not
  38 recorded reliably over Wikipedia's history, we believe that avoiding
  39 censoring (either left or right) is not technically possible given the
  40 data sources the WMF has published.
  41
  42
  43   |---------|----------------|----->
  44 2004 <x>  2008     <y>     2015  <z>
  45             |--Our Dataset---|
  46
  47 Because we don't have a perfect data for the beginning of any window,
  48 it means that events that happened are invisible to us unless they are
  49 ongoing at the point of data collection.  When our dataset starts in
  50 2008 (as it does in the dataset we produce here where the log format
  51 stabilizes, this means that there are two conditions where data will
  52 be missing (refer to the timeline figure above):
  53
  54 a) If a page is protected in <x> and is deleted in <y> we wll have no
  55    indication that the page was protected at all and no page
  56    protection spells will be included in the database.
  57
  58 b) If a page is protected in <x> and its protection status is changed
  59    at any time <t> during period <y> (i.e., either by adjusting the
  60    rights, updating the expiration time, or unprotecting the page) we
  61    will know that the page was protected during the period from the
  62    beginning of <y> until <t> but will we not know the specific rights
  63    associated with the protection. We will have complete data on the
  64    protection status of that page from <t> onward.
  65
  66
  67 Running the Software
  68 -----------------------------
  69
  70 0. Install dependencies
  71 ===========================
  72
  73 - Python 3
  74 - GNU R
  75 - `data.table` R package available on CRAN
  76
  77 1. Download Dumps
  78 ==========================
  79
  80 First, download a dump of MediWiki log actions. WMF distributes these
  81 for English Wikipedia at http://dumps.wikimedia.org. For example, the
  82 latest version when we wrote this document was this file:
  83
  84 https://dumps.wikimedia.org/enwiki/20150112/enwiki-20150112-pages-logging.xml.gz
  85
  86 You will also need a page that includes the status of protected pages
  87 at the point that data was created in the database. WMF distributes
  88 these from http://dumps.wikimedia.org as well. For example, the latest
  89 version is here:
  90
  91 https://dumps.wikimedia.org/enwiki/20150112/enwiki-20150112-page_restrictions.sql.gz
  92
  93 Finally, because the table above maps only page ID numbers to
  94 restriction events, we'll need a mapping of page IDs to page titles
  95 which is contained in a table like this one (the latest at the time of
  96 writing):
  97
  98 https://dumps.wikimedia.org/enwiki/20150112/enwiki-20150112-page.sql.gz
  99
 100 2. Parse SQL Tables
 101 ============================
 102
 103 An important first step is parsing the two wQL dumps file into CSV
 104 format. We can use the `mysqldump_to_csv.py` to do this like:
 105
 106 $ zcat enwiki-20150112-page_restrictions.sql.gz | ./02-mysqldump_to_csv.py \
 107   > enwiki-20150112-page_restrictions.csv
 108
 109 $ zcat enwiki-20150112-page.sql.gz | ./02-mysqldump_to_csv.py \
 110   > enwiki-20150112-page.csv
 111
 112 The first file is small and should be very quick. The second file is
 113 larger but still should still take only several minutes.
 114
 115 The number is adapated from: https://github.com/jamesmishra/mysqldump-to-csv
 116
 117 3. Parse Log File
 118 =================================
 119
 120 The log file that contains changes over time is much larger and will
 121 take several hours to parse for English Wikipedia even on a very fast
 122 machine.  The page log can be parsed using the file like:
 123
 124 $ zcat enwiki-20150112-pages-logging.xml.gz | ./03-parse_mw_event_log.py
 125
 126 This will produce several TSV files of the log file in several different
 127 formats:
 128
 129   output-moves.tsv
 130   output-protection.tsv
 131   output-deletions.tsv
 132
 133 If you pass an XML filename to 03-parse_mw_event_log.py, these file
 134 will not be called output but something based on the root of the
 135 filename.
 136
 137 4. Import Data Into R
 138 =============================
 139
 140 Import all of the data that we've created into a series of RData
 141 files. You'll need to first edit the file `04-import_data.R` so that
 142 the input files (all defined at teh very top of the script) match the
 143 files that you've downloaded and created.
 144
 145 Once you've done that, you can run the R script which will load and
 146 process these:
 147
 148 $ R --no-save < 04-import_data.R
 149
 150 This will output an RData file called `processed_log_and_sql_data.RData`.
 151
 152 5. Generate Spells
 153 =============================
 154
 155 Finally, we run the command that reads in all the prepared dataset and
 156 generates the spells dataset:
 157
 158 $ R --no-save < 05-generate_spells.R
 159
 160 This will generate the final page protection dataset: `spells.RData`