session5/Session05_PlainTextCollation.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Session 5a - Collate with CollateX\n",
    "## Plain Text"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Finally, we will start using CollateX!\n",
    "\n",
    "In this exercise, follow the instructions here: \n",
    "- read the Markdown cells\n",
    "- execute the Code cells (the ones with `In [xx]:` on their left).\n",
    "\n",
    "If you don't remember how to execute cells in a Notebook, check the Jupyter Notebook tutorial of [session 1](https://github.com/automaticCollationLausanne2020/Materials/blob/master/session1/session1b_JupyterNotebooks.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Delete the outputs\n",
    "In this notebook, you may already have outputs - the results of the exercises. We want to start from scratch, let's delete the outputs!\n",
    "\n",
    "- Go to the menu 'Kernel'\n",
    "- click on 'Restart & Clear Outputs' and confirm when Jupyter asks for it\n",
    "- Wait a few seconds, a blue string appears telling 'Kernel ready' ('Noyau prêt'); 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."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Update Collatex\n",
    "\n",
    "We want to make sure that we are using the latest version of CollateX. You don't need to do it every time, but it is best to do it regularly - so we are running this at the beginning of the notebook:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install --upgrade collatex"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Importing CollateX\n",
    "Before we can use CollateX, we need to import it as a module:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from collatex import * # the * means we import everything"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Did it work? If you got an error, you may need to install the [python-levenshtein C library](https://pypi.org/project/python-Levenshtein/).\n",
    "\n",
    "Follow the instructions [here](https://github.com/automaticCollationLausanne2020/Materials/blob/master/installation.md#33-installing-the-python-levenshtein-library) to install python-levenshtein, then come back to this notebook and start from the beginning. \n",
    "\n",
    "You don't need to import python-levenshtein as a module, you only need to have it installed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Step 1 - Create a Collation Object\n",
    "\n",
    "We create a Collation object with this slightly hermetic line of code:\n",
    "\n",
    "`collation = Collation()`\n",
    "\n",
    "Here the lower case `collation` is the variable name, you can choose any name. We simply tell CollateX to create a new empty Collation \"instance\" by saying `Collation()`. Collation is a sort of special data type, that was created especially for CollateX.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "collation = Collation()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Step 2 - Add Witnesses\n",
    "The Collation object will contain the witnesses that we want to collate.\n",
    "\n",
    "Each witness gets:\n",
    "- a name (or sigil) to identify it. The name can be a single letter, number, or a longer name\n",
    "- a text that will be collated\n",
    "\n",
    "We need to use the function `add_plain_witness()`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "collation.add_plain_witness('A', 'Bladorthin, Dwarves, and Mr Baggins.')\n",
    "collation.add_plain_witness('B', 'Bladorthin, dwarves and Mr Baggins, [...]')\n",
    "collation.add_plain_witness('C', 'Gandalf, dwarves and Mr Baggins!')\n",
    "\n",
    "# we can check how many witnesses are in our Collation object\n",
    "len(collation.witnesses)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Step 3 - Collate\n",
    "\n",
    "We give our Collation object to the function `collate()`: it will collate all the witnesses that we just added. \n",
    "\n",
    "We save the result into a variable."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "result = collate(collation)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Step 4 - Visualize the Result\n",
    "Use the function `print()` -- and voilà! \n",
    "\n",
    "We have successfully collated our witnesses."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "We have just done the most basic collation possible. But the `collate()` function has more options, that will modify how the result looks like.\n",
    "\n",
    "We will see two of these options:\n",
    "- **layout**: it can be either 'horizontal' (by default), or 'vertical'\n",
    "- **segmentation**: it can be either `True` (by default), or `False`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "# layout changes the orientation of the table\n",
    "result2 = collate(collation, layout='vertical')\n",
    "print(result2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "# segmentation changes how the words are separated (or not) in the table\n",
    "result3 = collate(collation, layout='vertical', segmentation=False)\n",
    "print(result3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "source": [
    "## Recap and Exercise\n",
    "\n",
    "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.\n",
    "\n",
    "\n",
    "**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.\n",
    "\n",
    "**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.\n",
    "\n",
    "**Now** run the cell a first time and see the results.\n",
    "\n",
    "**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:\n",
    " 1. Change the text for each witness\n",
    " 1. Add a new witness\n",
    " 2. Set the segmentation option to True (you will see that it is the same as deleting it)\n",
    " 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'.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "from collatex import *\n",
    "collation = Collation()\n",
    "collation.add_plain_witness('A', 'Bladorthin, Dwarves, and Mr Baggins.')\n",
    "collation.add_plain_witness('B', 'Bladorthin, dwarves and Mr Baggins, [...]')\n",
    "collation.add_plain_witness('C', 'Gandalf, dwarves and Mr Baggins!')\n",
    "result = collate(collation, layout='vertical', segmentation=False)\n",
    "print(result)"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Diaporama",
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.7"
  },
  "rise": {
   "scroll": true,
   "theme": "solarized",
   "transition": "slide"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}