Installing and testing CollateX

Quick start

If you have already installed CollateX, make sure that you have the most recent version by running:

pip install --upgrade collatex

If not, here are the installation instructions in a nutshell:

Install Python 3 (Anaconda distribution)
pip install collatex
pip install python-levenshtein (but see the note below for Windows)
Install Graphviz, either through a package manager such as apt-get (Ubuntu) or Homebrew or MacPorts (Mac OS), or go to http://www.graphviz.org/Download.php and accept the license
pip install graphviz

If you are not sure what all that means, read on!

Installation

To run CollateX, you need to install first Python 3 and then the CollateX module, along with some other programs, packages, and modules upon which CollateX depends. Here’s how to do that in Mac OS X, Ubuntu Linux, and Windows. This tutorial assumes that you are running Mac OS X 10.11 (El Capitan) or later; Windows 7, 8, or 10; or Ubuntu Linux 14.04 LTS or later. In all of the steps below, if you are prompted to enter your password, you should do so.

Install CollateX

Install CollateX from the command line by typing:

pip install collatex

Install the Python Levenshtein library

CollateX relies on this library to do near (inexact) matching of words. If you don’t plan to do near matching, you don’t need to install it.

For Mac OS X and Linux

Type the following at the command line:

pip install python-levenshtein

Mac OS users: You may get a popup window telling you that you require the command-line developer tools. If you get this window, choose “Install”. When the installation is finished, run the command again.

Once this is done, you can check that everything worked by opening a terminal, typing the following command, and hitting the Enter key:

python -c "import Levenshtein; print('This works.')"

For Windows

Windows users with an installed and configured C++ compiler can try:

pip install python-levenshtein

This will succeed only if you have a C++ compiler configured (most Windows users do not).

If you don’t have a C++ compiler configured, run one of the following command to install a precompiled package, according to your version of Windows (32 bit or 64 bit; if you aren’t sure which one you have, see How To tell if you Have Windows 64-bit or 32-bit):

32-bit:

pip install https://github.com/Pittsburgh-NEH-Institute/Institute-Materials-2017/blob/master/schedule/week_2/whl/python_Levenshtein-0.12.0-cp36-cp36m-win32.whl

64-bit:

pip install https://github.com/Pittsburgh-NEH-Institute/Institute-Materials-2017/blob/master/schedule/week_2/whl/python_Levenshtein-0.12.0-cp36-cp36m-win_amd64.whl

These files are mirrored from http://www.lfd.uci.edu/~gohlke/pythonlibs/#python-levenshtein. At the time we are writing this tutorial, we’re linking to the Levenshtein files for Python 3.6 (that’s what the “cp36” means in the filenames), which is the current Anaconda version.

Once you have installed the package, you can check whether everything works with the following command:

python -c "import Levenshtein; print('This works.')"

Install Graphviz

Graphviz is a program for creating graphic representations, including the variant graphs sometimes used in CollateX (see the examples at http://stemmaweb.net/stemmaweb/relation/help/Latin). Graphviz is required by CollateX only for viewing variant graphs. We recommend installing it for the Institute, but you can perform collation without it. Note that in addition to installing Graphviz, all users need to install Python bindings for Graphviz, which is a separate step, described below.

For Mac OS X

The easiest way to install Graphviz is to download the appropriate installer from the Graphviz download page (you will need to accept the license.) On Mac, this will be the mountainlion current stable release. The Graphiz page is often inaccessible; should this happen you can use the Internet Archive Wayback Machine.

If the installer refuses to run when you double-click it, then you can do the following:

Navigate to the installer in your Downloads folder.
Right-click (or Ctrl-click) to bring up the context menu.
Choose “Open”.
When the warning dialog appears, choose “Open” again.

This is a useful trick to remember for installing any software that you know you want, but that your Mac doesn’t trust.

For Ubuntu Linux

Graphviz can be installed from the Terminal on Ubuntu with:

sudo apt-get install graphviz

For Windows

The easiest way to install Graphviz on Windows is to download the appropriate installer from the Graphviz download page (you will need to accept the license.) The Graphiz page is often inaccessible; should this happen you can use the Internet Archive Wayback Machine. On Windows, use the .msi file if you can. When the installer shows the screen in the image on the right, copy the full and exact folder name somewhere. When the installer is done, you will need to add this information to your execution path.

From the Control Panel, choose System and Security → System → Advanced settings, and then click the Environment variables button near the bottom of the window.
Select the entry in the list that says PATH and choose Edit.
Scroll all the way to the end of whatever is already there, and add a “;” character (without the quotes), then the exact folder name you copied, and then “\bin” (also without the quotes). In the example above, you would append “;C:\Program Files (x86)\Graphviz2.38\bin” (without the quotes, but with the leading semicolon) to the end of your original path, as in the image below.
To confirm that the path has been set correctly, close any open Powershell or bash window you have, open a new one, and run the command
```
where.exe dot
```
Do not leave off the “.exe”! The output should look something like:
```
 PS C:\Users\Tara L Andrews> where.exe dot
 C:\Program Files (x86)\Graphviz2.38\bin\dot.exe
```

Installing the Python Graphviz bindings

In addition to Graphviz itself, all users on all operating systems also need to install Python bindings (support) for Graphviz, which you can do at the command line by typing:

pip install graphviz

Note that the preceding line does not install Graphviz; what it installs is just the Python bindings for Graphviz. You also need to install Graphviz itself, as described above.