Collating for real with CollateX. Plain texts

In this exercise, follow the instructions here: read the Markdown cells and execute the Code cells (the ones with In + a number on their left).

Not sure how to execute cells in a Notebook? Check the Jupyter Notebook tutorial.

Delete the outputs

In this notebook, you might have already the code and the outputs, that is the results. We want to create the results afresh, so let's clear all the outputs. Go to the menu 'Kernel' and choose 'Restart & Clear Output' and confirm it when Jupyter asks for it. Wait some seconds, a blue string appears telling 'Kernel ready'; if you don't see it, don't worry, it is so quick that you might have lost it. But the Notebook is ready again.

Please note that we are clearing the results only because we want to run everything in the exercise. But if in the future you come back here, you don't need to delete the results before starting.

Update CollateX

CollateX is already installed, but we want to make sure to have the latest version of CollateX. You don't need to do this every time, but make sure you do it regularly.

That's why we do in the Jupyter Notebook:


In [1]:
!pip install --upgrade collatex


Requirement already up-to-date: collatex in /home/espadini/anaconda3/lib/python3.6/site-packages (2.2)
Requirement already satisfied, skipping upgrade: prettytable in /home/espadini/anaconda3/lib/python3.6/site-packages (from collatex) (0.7.2)
Requirement already satisfied, skipping upgrade: networkx in /home/espadini/anaconda3/lib/python3.6/site-packages (from collatex) (1.11)
Requirement already satisfied, skipping upgrade: decorator>=3.4.0 in /home/espadini/anaconda3/lib/python3.6/site-packages (from networkx->collatex) (4.1.2)
You are using pip version 19.0.3, however version 19.1 is available.
You should consider upgrading via the 'pip install --upgrade pip' command.

Or directly in the commandline: pip install --upgrade collatex (without the exclamation mark at the beginning of the line).

Run CollateX

Finally, we can use CollateX.

We need to tell Python that we will be needing the CollateX package. A package or library is a program, a set of code files that together form a program. In Pythong, before using the library, you need to ask for it. Here is how you do it:


In [2]:
from collatex import *

Now we're ready to make a collation object. We do this with the slightly hermetic line of code:

collation = Collation()

Here the lower case collation is the arbitrary named variable that refers to a copy (officially it is called an instance) of the CollateX collation engine. We simply tell the collation library to create a new instance by saying Collation().


In [3]:
collation = Collation()

Now we add some witnesses. Each witness gets a letter or name that will identify them, and for each we add the literal text of the witness to the collation object.


In [4]:
collation.add_plain_witness( "A", "The quick brown fox jumped over the lazy dog.")
collation.add_plain_witness( "B", "The brown fox jumped over the dog." )
collation.add_plain_witness( "C", "The bad fox jumped over the lazy dog." )

And now we can let CollateX do its work of collating these witnesses and sit back for about 0.001 seconds. The result will be an alignment table, so we'll refer to the result with a variable named alignment_table.


In [5]:
alignment_table = collate(collation, layout='vertical', segmentation=False )

Well, that worked nicely it seems. But there's no printout, no visualization. That's okay, we can come up with a printout of the alignment table too:


In [6]:
print( alignment_table )


+--------+--------+--------+
|   A    |   B    |   C    |
+--------+--------+--------+
|  The   |  The   |  The   |
+--------+--------+--------+
| quick  |   -    |  bad   |
+--------+--------+--------+
| brown  | brown  |   -    |
+--------+--------+--------+
|  fox   |  fox   |  fox   |
+--------+--------+--------+
| jumped | jumped | jumped |
+--------+--------+--------+
|  over  |  over  |  over  |
+--------+--------+--------+
|  the   |  the   |  the   |
+--------+--------+--------+
|  lazy  |   -    |  lazy  |
+--------+--------+--------+
|  dog   |  dog   |  dog   |
+--------+--------+--------+
|   .    |   .    |   .    |
+--------+--------+--------+

CollateX can also collect the segments that run parallel and display them together. To do that, just delete the option segmentation=False as in the line below. We can now collate and print the output again.


In [7]:
alignment_table = collate(collation, layout='vertical' )
print( alignment_table )


+---------------------+---------------------+---------------------+
|          A          |          B          |          C          |
+---------------------+---------------------+---------------------+
|         The         |         The         |         The         |
+---------------------+---------------------+---------------------+
|        quick        |          -          |         bad         |
+---------------------+---------------------+---------------------+
|        brown        |        brown        |          -          |
+---------------------+---------------------+---------------------+
| fox jumped over the | fox jumped over the | fox jumped over the |
+---------------------+---------------------+---------------------+
|         lazy        |          -          |         lazy        |
+---------------------+---------------------+---------------------+
|         dog.        |         dog.        |         dog.        |
+---------------------+---------------------+---------------------+

Jupyter Notebook cells order

You may have noticed that if you run the cells in the Notebook in order, they know about one another. For this reason, in the end of this tutorial we could produce different outputs using the information typed into the previous cells. When you open a notebook, remember to run the cells in order or to "run all cells" (from the menu Cell), otherwise you may get an error message.

Recap and exercise

Before moving forward and see how to collate texts stored in files and discover the various outputs that CollateX provide, let's recap what we've done and exercise a bit.

We are using

  1. First, create a new Markdown cell at the end of this Notebook (you could also create a new Notebook, but we'll save time by working in this one). Write in the new cell something like My CollateX test, so you know that this is your tests from that cell onwards. You can use the Markdown cells to document what is happening around them.

  2. Then, create a Code cell and copy the code here below: this is all CollateX needs to collate some texts, the same instructions we gave it before but all together.

  3. Now run the cell a first time and see the results.

  4. Make changes and see how the output changes when you run the cell again. Change one thing at a time: this way, if you get an error message, it will be easier to debug the code. Try the following changes:

    1. Change the text for each witness
    2. Set the segmentation option to True (you will see that it is the same as deleting it)
    3. Add a new witness
    4. It is also possible to change the sigil for each witness. The sigil is the abbreviation used for refering to a witness, here 'A', 'B', 'C'.

In [6]:
from collatex import *
collation = Collation()
collation.add_plain_witness( "W1", "Some texts here")
collation.add_plain_witness( "W2", "Some text here as well" )
collation.add_plain_witness( "W3", "Some texts in the third witness as well" )
collation.add_plain_witness( "W4", "Some texts here")
alignment_table = collate(collation, layout='vertical')
print( alignment_table )


+-------+---------+----------------------+-------+
|   W1  |    W2   |          W3          |   W4  |
+-------+---------+----------------------+-------+
|  Some |   Some  |         Some         |  Some |
+-------+---------+----------------------+-------+
| texts |   text  |        texts         | texts |
+-------+---------+----------------------+-------+
|  here |   here  | in the third witness |  here |
+-------+---------+----------------------+-------+
|   -   | as well |       as well        |   -   |
+-------+---------+----------------------+-------+