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