1_examples_of_working_with_textacy.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Working with textacy and spaCy\n",
    "\n",
    "In this notebook we'll be working with textacy, spaCy, and a bit of `TODO?`.\n",
    "\n",
    "## Useful links:\n",
    "Keep these handy, the corpus we'll work with (should) fit(s) in memory, and `spacy` and `textacy` contain a lot of convenient methods for extracting meaningful representations. \n",
    "\n",
    "1. [spaCy's Doc API reference](https://spacy.io/api/doc): our `textacy.Corpus` consists of `spacy.Doc` instances.\n",
    "   \n",
    "1. [textacy's corpus API reference](https://chartbeat-labs.github.io/textacy/api_reference/lang_doc_corpus.html#textacy.corpus.Corpus)\n",
    "\n",
    "1. [textacy's document analysis quickstart](https://chartbeat-labs.github.io/textacy/getting_started/quickstart.html#analyze-a-doc): `textacy` adds a bunch of methods on top of the `spacy.Doc` methods, e.g., keyword extraction, readability scores, etc.\n",
    "\n",
    "1. [textacy's corpus analysis quickstart](https://chartbeat-labs.github.io/textacy/getting_started/quickstart.html#analyze-a-corpus): On top of that, `textacy` provides a bunch of methods for doing corpus-level operations, e.g., topic modeling, computing doc_term matrices, etc.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import textacy"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Load the Wikinews corpus\n",
    "\n",
    "We prepared a `textacy.datasets.wikimedia.Wikinews`-corpus in the `get_wikinews_data.ipynb`-notebook. \n",
    "\n",
    "Note that when loading the `textacy.Corpus`, we need to have a spaCy `en` model, either the medium (`en_core_web_md`) or large (`en_core_web_lg`) model, if we want to use word vectors (I think we do). Download a model with, e.g.:\n",
    "\n",
    "```bash\n",
    "python -m spacy download en_core_web_md\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "corpus = textacy.Corpus.load(\"en_core_web_md\", \"./data/enwikinews/textacy_corpus.bin.gz\")\n",
    "print(corpus)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Document in the corpus can be directly accesssed through their indices, e.g.:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "doc = corpus[5786]  # Take one sample document\n",
    "doc  # Holds the article content\n",
    "doc._.meta  # Wikinews metadata is accessible through `._.meta`. Yeah (._.)\n",
    "doc.has_vector"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Document Representations\n",
    "\n",
    "We can extract meaningful representations and additional metadata, by using [spaCy's Doc methods](https://spacy.io/api/doc) and [`textacy`-specific additional Doc methods](https://chartbeat-labs.github.io/textacy/getting_started/quickstart.html#analyze-a-doc), e.g.:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "entities = doc.ents  # spaCy.Doc.ents\n",
    "sentiment_score = doc.sentiment  # spaCy.Doc.sentiment\n",
    "word_embeddings = doc.vector"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import textacy.ke  # textacy's keyword extraction module\n",
    "\n",
    "keywords = textacy.ke.textrank(doc, normalize=\"lemma\", topn=10)\n",
    "print(\"keywords: {}\\n\".format(\", \".join([k for k, s in keywords])))\n",
    "\n",
    "doc_stats = textacy.TextStats(doc)\n",
    "f_k_grade_level = doc_stats.flesch_kincaid_grade_level\n",
    "print(\"Flesch-Kincaid Grade Level: {}\".format(f_k_grade_level))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Corpus-level operations\n",
    "\n",
    "Finally, `textacy` allows us to conveniently process corpus-level statistics, create similarity matrices, etc.\n",
    "* See [textacy's quickstart](https://chartbeat-labs.github.io/textacy/getting_started/quickstart.html#analyze-a-corpus) for reference"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import textacy.vsm  # vector space models\n",
    "\n",
    "vectorizer = textacy.vsm.Vectorizer(tf_type=\"linear\", apply_idf=True, idf_type=\"smooth\", norm=\"l2\", \n",
    "                                    min_df=2, max_df=0.95)\n",
    "doc_term_matrix = vectorizer.fit_transform((doc._.to_terms_list(ngrams=1, entities=True, \n",
    "                                                                as_strings=True) for doc in corpus))\n",
    "print(doc_term_matrix.shape)  # n_docs * n_vocab"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import textacy.tm  # topic models\n",
    "\n",
    "model = textacy.tm.TopicModel(\"nmf\", n_topics=10)\n",
    "model.fit(doc_term_matrix)\n",
    "doc_topic_matrix = model.transform(doc_term_matrix)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for topic_idx, top_terms in model.top_topic_terms(vectorizer.id_to_term, top_n=10):\n",
    "    print(\"topic\", topic_idx+1, \":\", \", \".join(top_terms))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Other ways to manipulate corpus\n",
    "===\n",
    "`textacy.Corpus.vectors` exposes the articles' underlying word embedding vectors, which allow for quick similarity computations;"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from scipy.spatial.distance import pdist, squareform\n",
    "\n",
    "distances = squareform(pdist(corpus.vectors, 'cosine'))  # Compute all pair-wise cosine similarities"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"Most similar to:\\n   {}\\n\".format(doc._.meta['title']))\n",
    "\n",
    "for rank, idx in enumerate(distances[5786].argsort()[1:11]):\n",
    "    title = corpus[idx]._.meta['title']\n",
    "    similarity = 1-distances[5786][idx]\n",
    "    print(\"{}. {} ({})\".format(rank+1, title, similarity))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "These are just a few examples, but it's good to think a bit about how to model similarity in different ways, using different representations or metadata, for the next steps..."
   ]
  }
 ],
 "metadata": {
  "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.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}