projects.mako.cc - redirect-tools/blob - README.rst

   1 MediaWiki Redirect Tools
   2 =======================================================================
   3
   4   | **Author:** `Benjamin Mako Hill`__ <mako@atdot.cc>
   5   | **Homepage:** http://networkcollectiv.es/wiki-redirects/
   6   | **License:** `GNU GPLv3 or any later version`__ (see COPYING)
   7   | **Description:** Tools to to generate a redirect spells dataset from "raw" MediaWiki XML dumps like those published by the Wikimedia foundation.
   8
   9 __ http://mako.cc/
  10 __ http://www.gnu.org/copyleft/gpl.html
  11
  12 If you use this software for research, please **cite the following
  13 paper** in any resulting publication:
  14
  15   *Hill, Benjamin Mako and Aaron Shaw. "Consider the Redirect:  A Missing
  16   Dimension of Wikipedia Research." In Proceedings of the 10th International
  17   Symposium on Open Collaboration (OpenSym 2014). ACM Press, 2014.*
  18
  19 **Overview:**
  20
  21 To use these tools, you will need need to start with a MediaWiki dump
  22 file. For Wikimedia Foundation projects, you can download them all from:
  23 http://dumps.wikimedia.org/
  24
  25 Wikis from Wikia.com and other Wikimedia projects all use the same XML format
  26 for their projects.
  27
  28 In the examples in this README, I will use a dump of `Simple English
  29 Wikipedia`__ that I downloaded with the following command::
  30
  31   wget http://dumps.wikimedia.org/simplewiki/20140410/simplewiki-20140410-pages-meta-history.xml.7z
  32
  33 __ https://simple.wikipedia.org/
  34
  35 Before you start, you may also want to change the default directories for writing intermediate output files.  The default directories for writing and reading files are at the top of the file `redirect_tools.R` and can be changed by editing that file. By default, all files will be written to the subdirectory "./output" in the local directory. If you want to use the default directories, you will still need to create them with a command like this::
  36
  37   mkdir output; output/redir; output/spells
  38
  39 Step 2: Find Redirects in Revisions
  40 =======================================================================
  41
  42 Dependencies:
  43
  44 - Python 2.7
  45 - Wikimedia Utilities (https://bitbucket.org/halfak/wikimedia-utilities)
  46
  47 Input:
  48
  49 - Wikimedia XML Dump files (compressed in some form)
  50
  51 Output:
  52
  53 - bzip2 compressed TSV files (one line per revision)
  54
  55 You will run the `01-extract_redirects.py` script to build a dataset of revisions or edits that marks every revisions as either containinig a revision, or not.
  56
  57 Then, the script `01-extract_redirects.py` will take a MediaWiki dump file on STDIN and output a TSV file on STDOUT of the following form.
  58
  59 +---------+-------------+--------------------------------+------------+---------+----------+--------------------+
  60 | page.id | revision.id | page.title                     | timestamp  | deleted | redirect | target             |
  61 +=========+=============+================================+============+=========+==========+====================+
  62 | 1935456 | 17563584    | Mikhail Alekseevich Lavrentiev | 1116962833 | FALSE   | FALSE    | NA                 |
  63 | 1935456 | 22034930    | Mikhail Alekseevich Lavrentiev | 1125245577 | FALSE   | TRUE     | Mikhail Lavrentyev |
  64 +---------+-------------+--------------------------------+------------+---------+----------+--------------------+
  65
  66
  67 In this (example) case, the first revision of the article "Mikhail Alekseevich Lavrentiev" was not a redirect but the second is a redirect to "Mikhail Lavrentyev."
  68
  69 If you are using the Simple English dump (which is a single file) you would run the following command to send the output to the default destination::
  70
  71   7za x -so simplewiki-20140410-pages-meta-history.xml.7z |
  72   python2.7 01-extract_redirects.py | bzip2 -c - > output/redir/simple_redirs.tsz.bz2
  73
  74 Because our dumpfile is 7z compressed, I used 7za to uncompress it. If I had used a gzip or bzip compressed file, I would use `zcat` or `bzcat` instead. I'm also catting the output to `bzip2 -c` which will bzip the TSV output to conserve space. The next step assumes a bzip2 compressed file. If you don't want to use bzip2 to compress, you'll need to modify the code.
  75
  76
  77 Step 2: Generate spells
  78 =======================================================================
  79
  80 Dependencies:
  81
  82 - GNU R
  83 - data.table (http://cran.r-project.org/web/packages/data.table/)
  84 - foriegn (http://cran.r-project.org/web/packages/foreign/)
  85
  86 Input:
  87
  88 - bzip compressed TSV files
  89
  90 Output:
  91
  92 - RData files containing a data.frame of redirect spells named `redirect.spell`
  93   (one file per input file)
  94 - Stata DTA file (same data)
  95 - TSV file (same data)
  96
  97 The file `redirect_tools.R` contains an R function `generate.spells()` that
  98 takes a data frame of edit data as created in step 1 and a list of page titles
  99 in order to create a list of redirect spells for those pages. It also
 100 contains a function `filename.to.spells()` which takes the filename of a bzip
 101 compressed file of the form created in step 1 and outputs a full list of
 102 redirect spells.
 103
 104 You can run the command with::
 105
 106   R --no-save < 02-generate_spells.R
 107
 108 By default, output will be saved into `output/spells`.
 109
 110 The
 111
 112 Running Code in Parallel
 113 =======================================================================
 114
 115 Because the full history dumps from the WMF foundation are split into many
 116 files, it is can be appropriate to parse these dumps in parallel. Although the
 117 specific ways you choose to do this will vary by the queuing system you use,
 118 we've included examples of the scripts we used with Condor on the Harvard/MIT
 119 Data Center (HMDC) in the "examples/" directory. They will not work without
 120 modification for your computing environment because they have our environment
 121 hardcoded in but they will give you an idea of where you might want to start.
 122
 123 Additionally, there is a third step `03-assemble_redirect_spells.R` that
 124 contains R code that will read in all of the separate RData files, assmebles
 125 the many smaller dataframes into a single data.frame, and then saves that
 126 unified data.frame into a single RData file.
 127