examples/monolingual.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "# Monolingual sentence comparison\n",
    "\n",
    "Although this library was created with the intention of comparing syntactic structures between languages, it can also\n",
    " be used to compare two sentences in the same language. This is for instance useful when comparing different\n",
    " translations of the same text, comparing a post-edited or revised version with the original, or compare a machine\n",
    " translation with a reference translation.\n",
    "\n",
    "In this case, we do not necessarily need Universal Dependencies\n",
    " to be able to compare languages. So instead of using stanza, which used the UD annotation schema, we can use any other\n",
    " parser as well. This library provides built-in support for stanza and spaCy, so in this example we will make use of\n",
    " spaCy."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "!pip install astred[spacy]"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "from astred import AlignedSentences, Sentence\n",
    "from astred.utils import load_parser\n",
    "\n",
    "# Just for this notebook, we do not want to be bothered with spaCy's UserWarnings\n",
    "import warnings\n",
    "warnings.simplefilter(\"ignore\", UserWarning)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "The default English spaCy models do not make use of Universal Dependencies, but since we are comparing two sentences in\n",
    " the same language, parsed with the same parser, that is not an issue: the tags and labels are comparable.\n",
    "\n",
    "When using spaCy, models must be downloaded manually, though. When you use stanza in `astred` you can simply provide\n",
    " the language code and the required models will be downloaded behind the scenes. That is not possible with spaCy.\n"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "# Download a default, English spaCy models\n",
    "!python -m spacy download en_core_web_sm"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "The only thing that is different from what is shown in the other examples, is that here we explicitly pass an\n",
    " initialized spaCy parser to `.from_text()` instead of a language code. We could have written\n",
    " `.from_text(\"<text>\", \"en\")` but that means that for both these sentences the parser will be loaded. That is quite\n",
    " some overhead! If you need to parse multiple sentences with the same parser (language), it is best to first create the\n",
    " parser and pass that parser to `.from_text()`, as we do in this example.\n",
    "\n",
    "The spaCy parser can be created with `spacy.load()`, but as an example we will use the method `load_parser()`, which\n",
    " can also be used to initialize a stanza parser."
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "nlp = load_parser(\"en_core_web_sm\", \"spacy\")\n",
    "src_sent = Sentence.from_text(\"I saw the director hiding a lot of documents at night !\", nlp)\n",
    "tgt_sent = Sentence.from_text(\"Last night , the director was hiding a lot of our papers .\", nlp)\n",
    "aligns = \"2-3 3-4 4-5 4-6 5-7 6-8 7-9 8-10 8-11 9-0 9-1 10-0 10-1 11-12\"\n",
    "\n",
    "aligned = AlignedSentences(src_sent, tgt_sent, word_aligns=aligns)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "You'll notice that not all words can be aligned, perhaps because different translators to show a different perspective.\n",
    " Particularly, \"I saw\" is not aligned on the source side. If a word is not aligned, it is implicitly connected to a\n",
    " NULL word. after creating the `AlignedSentences` object, the source and target sentence receive a NULL element at the\n",
    " front to which \"unaligned words\" are then connected. For a given word you can check whether it is aligned with\n",
    " `is_aligned` and if it is, you can easily get its aligned words. To iterate the words of a sentence without including\n",
    " the NULL word, we can use `Sentence.no_null_words`.\n",
    "\n",
    "In this example we will display for each source word its aligned target words."
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "for src_word in src_sent.no_null_words:\n",
    "\tif not src_word.is_aligned:\n",
    "\t\tcontinue\n",
    "\tprint(src_word.text, \" \".join([tgt_word.text for tgt_word in src_word.aligned]))"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "You can also easily find whether any of a word's tags have changed compared to its aligned words:"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "for src_word in src_sent.no_null_words:\n",
    "\tif not src_word.is_aligned:\n",
    "\t\tcontinue\n",
    "\n",
    "\tprint(\"DEPENDENCIES\")\n",
    "\tfor tgt_id, change in src_word.changes(\"deprel\").items():\n",
    "\t\ttgt_word = tgt_sent[tgt_id]\n",
    "\t\tprint(\"CHANGE:\" if change else \"SAME:\", f\"{src_word.text} ({src_word.deprel})\", f\"{tgt_word.text} ({tgt_word.deprel})\")\n",
    "\n",
    "\tprint(\"PART-OF-SPEECH\")\n",
    "\tfor tgt_id, change in src_word.changes(\"xpos\").items():\n",
    "\t\ttgt_word = tgt_sent[tgt_id]\n",
    "\t\tprint(\"CHANGE:\" if change else \"SAME:\", f\"{src_word.text} ({src_word.xpos})\", f\"{tgt_word.text} ({tgt_word.xpos})\")\n",
    "\tprint(\"---\")\n"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "Sentences can be represented as linguistic \"trees\". Here, we make use of dependency trees to formalize the structure of\n",
    " the sentences. As such, it is interesting to find differences between these structures. This is typically done with\n",
    " tree edit distance, but in our paper we suggest ASTrED (aligned syntactic tree edit distance), which also takes word\n",
    " alignment information into account during the tree edit distance calculation.\n",
    "\n",
    "We can also check which structural changes need to happen to convert the source dependency tree to the target tree\n",
    " quite easily. In `aligned.ted_ops` the operations are saved that are necessary to make the conversion. This is in\n",
    " fact a list of tuples of a source and target sub `Tree`s. The comments in the cell below explain this further.\n",
    " Note again that this is not calculated based on regular tree edit distance, but with ASTrED. For the argumentation\n",
    " behind ASTrED, see our paper but the main goal is to ensure that only aligned elements can match each other to avoid\n",
    " \"accidental\" structural overlap to bias the outcome."
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "print(\"Edit distance:\", aligned.ted)\n",
    "for operation in aligned.ted_ops:\n",
    "\tsrc_node, tgt_node = operation\n",
    "\tsrc_text = src_node.node.text if src_node else None\n",
    "\ttgt_text = tgt_node.node.text if tgt_node else None\n",
    "\n",
    "\t# If both a source and target element are present in this operation...\n",
    "\tif src_text and tgt_text:\n",
    "\t\t# ... that can mean they match, or ...\n",
    "\t\tif src_text == tgt_text:\n",
    "\t\t\tprint(\"MATCH\", src_text, \"===\", tgt_text)\n",
    "\t\t# ... that a source element has been replaced by a target element\n",
    "\t\telse:\n",
    "\t\t\tprint(\"SUBSTITUTION\", src_text, \"-->\", tgt_text)\n",
    "\t# If only a source element is present, and no target, then that means the source element was deleted\n",
    "\telif src_text:\n",
    "\t\tprint(\"DELETION:\", f\"{src_text} (src)\")\n",
    "\t# If only a target element is present, and no source, then that means the target element was inserted\n",
    "\telif tgt_text:\n",
    "\t\tprint(\"INSERTION:\", f\"{tgt_text} (tgt)\")"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "Because we have access to the underlying sentence Spans and Tokens that spaCy produced, we can now also do some pretty\n",
    " neat stuff, like calculating the semantic similarity between a source sentence and its translation. Not only that, it\n",
    " is also easy to compare a source word with its aligned translation(s)! In this case, we can see that the sentences are\n",
    " relatively similar and that particularly a reasonable similarity exists between \"documents\" and \"papers\".\n",
    "\n",
    "Note that this functionality is only available in spaCy and that this is not comparable between different models! So\n",
    " if you would parse one sentence with an English model and another with French, you cannot use this effectively!"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "# The original, parsed sentences are stored in Sentence._sentence, so we can use the spaCy functionality\n",
    "# that is present there to calculate similarity\n",
    "print(\"Sentence similarity:\", src_sent._sentence.similarity(tgt_sent._sentence))\n",
    "print()\n",
    "\n",
    "# Loop over the source words as before\n",
    "for src_word in src_sent.no_null_words:\n",
    "\t# Skip words that are not aligned\n",
    "\tif not src_word.is_aligned:\n",
    "\t\tcontinue\n",
    "\n",
    "\t# The original, parsed tokens are stored in Word._word\n",
    "\tfor tgt_word in src_word.aligned:\n",
    "\t\tprint(src_word.text, tgt_word.text, src_word._word.similarity(tgt_word._word))"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}