2021/exercises/Additional_Exercises_Solutions_Frequency_Distribution.ipynb

{
  "nbformat": 4,
  "nbformat_minor": 0,
  "metadata": {
    "colab": {
      "name": "Additional Exercises: Frequency Distribution (Solution)",
      "provenance": [],
      "collapsed_sections": []
    },
    "kernelspec": {
      "name": "python3",
      "display_name": "Python 3"
    },
    "language_info": {
      "name": "python"
    }
  },
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "M8LHZw5jxwmW"
      },
      "source": [
        "# Additional Exercises - Frequency Distribution\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "WFTxNWfN8Vua"
      },
      "source": [
        "In this notebook (set of exercises) we will create a tool that, given a corpus of text files and a search term, is able to provide us with information about the frequency distribution of the term across the files in the corpus.\n",
        "\n",
        "The solution we will implement is not perfect and very much influenced by educational decisions. After finishing the exercise, you will be invited to think about ways of optimizing the solution."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "gHvM1cmJ8qd7"
      },
      "source": [
        "## Setup\n",
        "\n",
        "This is a little bit of setup. First, we import necessary libraries. Of course, feel free to add libraries as needed! After, we clone the workshop repository and use the provided helper script to download a series of Sherlock Holmes short stories."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "CTSVAtts8RdO"
      },
      "source": [
        "# Regular Expressions\n",
        "import re\n",
        "\n",
        "# Pathlib\n",
        "from pathlib import Path\n",
        "\n",
        "# Counter for getting frequencies\n",
        "from collections import Counter\n",
        "\n",
        "# DataFrames\n",
        "import pandas as pd\n",
        "\n",
        "# Visualization\n",
        "import seaborn as sns\n",
        "import matplotlib.pyplot as plt"
      ],
      "execution_count": 1,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "jCqH7MeyxzRa"
      },
      "source": [
        "%%capture\n",
        "!git clone https://github.com/IngoKl/python-programming-for-linguists\n",
        "!cd python-programming-for-linguists/2021/data && sh download_sherlockholmes.sh"
      ],
      "execution_count": 2,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "l-txyxOP9G5s"
      },
      "source": [
        "## Step 1: Preparing the Data\n",
        "\n",
        "After running the `download_sherlockholmes.sh` script above, you will have 12 short stories (*The Adventures of Sherlock Holmes*) in the `python-programming-for-linguists/2021/data/corpora/holmes` folder.\n",
        "\n",
        "The goal of this first step is to read and prepare the data. Your goal will be to create the data structure below. \n",
        "\n",
        "Please note that there are other, better and more efficient, data structures to achieve the same goals. However, we are building a solution that mirrors practices in corpus linguistics without being too conscious of memory of computation limitations."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "5nlXgAZq9GYH",
        "outputId": "c1aca188-1e0e-4a75-f18c-913f76c711dc"
      },
      "source": [
        "corpus = [\n",
        "          {\n",
        "           'filename': 'bery.txt', \n",
        "           'text': '...', \n",
        "           'story_title': 'THE ADVENTURE OF THE BERYL CORONET', \n",
        "           'length': None, \n",
        "           'frequencies': {}\n",
        "          },\n",
        "]\n",
        "\n",
        "corpus"
      ],
      "execution_count": 3,
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "[{'filename': 'bery.txt',\n",
              "  'frequencies': {},\n",
              "  'length': None,\n",
              "  'story_title': 'THE ADVENTURE OF THE BERYL CORONET',\n",
              "  'text': '...'}]"
            ]
          },
          "metadata": {
            "tags": []
          },
          "execution_count": 3
        }
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "bPGW5NIW-nGN"
      },
      "source": [
        "Obviously, your solution will create a list with more than one item. The `frequencies` dictionary as well as `length` can be empty for now. We will populate it in the next step. `text` is supposed to contain the actual text.\n",
        "\n",
        "If you want to, you can preprocess the text before adding it to `corpus`.\n",
        "\n",
        "The trickiest bit is getting the `story_title` from the file. Have a look at one of the actual text files and remember what you've learned about regular expressions."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "Vx13B3qyAD3q"
      },
      "source": [
        "def get_story_title(text):\n",
        "  title = re.search(\" *([A-Z '-]+)\\n\", text).group(1)\n",
        "  return title\n",
        "\n",
        "def preprocess_text(text):\n",
        "  text = text.lower()\n",
        "  text = re.sub('\\n+', ' ', text)\n",
        "  text = re.sub(' +', ' ', text)\n",
        "\n",
        "  return text"
      ],
      "execution_count": 4,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "y_17lprz_MFg"
      },
      "source": [
        "corpus = []\n",
        "files = Path('python-programming-for-linguists/2021/data/corpora/holmes').glob('*.txt')\n",
        "\n",
        "for f in files:\n",
        "  filename = f.name\n",
        "  text = preprocess_text(f.read_text())\n",
        "  story_title = get_story_title(f.read_text())\n",
        "\n",
        "  corpus.append({'filename': filename, \n",
        "                 'text': text, \n",
        "                 'story_title': story_title, \n",
        "                 'length': None, \n",
        "                 'frequencies': {}\n",
        "                 })"
      ],
      "execution_count": 5,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "_qizNQCTDTSt"
      },
      "source": [
        "## Step 2: Getting the Frequencies\n",
        "\n",
        "You will need to generate frequency tables and add them to `corpus`. At the same time, you should populate `length` with the number of tokens in the document.\n",
        "\n",
        "This also means that you will have to tokenize the stories first. Remember that you can use `dict()` to turn a `Counter` object into a dictionary.\n",
        "\n",
        "Ultimately, `frequency`, for each story, should contain a structure like below:"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "gnZ_FDT8Dn4P"
      },
      "source": [
        "frequencies = {\n",
        "    'word_a': 42,\n",
        "    'word_b': 12,\n",
        "}"
      ],
      "execution_count": 6,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "i5VrpJaVDufW"
      },
      "source": [
        "def tokenize(text):\n",
        "  return re.findall('\\w+', text)"
      ],
      "execution_count": 7,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "5ObMUj8gDy5f"
      },
      "source": [
        "for story in corpus:\n",
        "  tokenized_story = tokenize(story['text'])\n",
        "  frequencies = dict(Counter(tokenized_story))\n",
        "\n",
        "  story['length'] = len(tokenized_story)\n",
        "  story['frequencies'] = frequencies"
      ],
      "execution_count": 8,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "dhScros9GJeW"
      },
      "source": [
        "## Step 3: Frequencies and Frequency Distribution\n",
        "\n",
        "Now you will need to write a function that takes a `corpus` as well as `search_term`. You will also need to account for both the absolute as well as the relative (per 1,000 tokens) frequencies.\n",
        "\n",
        "If you need to check whether something is in a dictionary, you can do the following: `if x in y`\n",
        "\n",
        "You will generate a frequency table for the search term that looks as follows:"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "wclpClooGXZr"
      },
      "source": [
        "frequency_table = {\n",
        "    # Filename: (abs_frequency, rel_frequency_per_1000)\n",
        "    'story_title_a': (1, 2),\n",
        "    'story_title_b': (1, 2)\n",
        "}"
      ],
      "execution_count": 9,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "7ZZufRoQG_S1"
      },
      "source": [
        "def get_frequencies(corpus, search_term):\n",
        "\n",
        "  frequency_table = {}\n",
        "\n",
        "  for story in corpus:\n",
        "\n",
        "    # Absolute Frequency\n",
        "    if search_term in story['frequencies']:\n",
        "      abs_frequency = story['frequencies'][search_term]\n",
        "    else:\n",
        "      abs_frequency = 0\n",
        "\n",
        "    rel_frequency = (abs_frequency / story['length']) * 1000\n",
        "\n",
        "    # Relative Frequency (per 1,000 tokens)\n",
        "    frequency_table[story['story_title']] = (abs_frequency, rel_frequency)\n",
        "\n",
        "  return frequency_table\n"
      ],
      "execution_count": 10,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "fzoGahWOHF5-"
      },
      "source": [
        "The following code is **provided for you**. You don't have to change anything here. Just need to make sure that you `get_frequencies` function works well with it. \n",
        "\n",
        "* We will nicely print the results\n",
        "* We will calculate a very basic dispersion statistic (Range_2)\n",
        "* We will plot the results using `seaborn`"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "B77mZcOA8H_4"
      },
      "source": [
        "def plot_frequency_table(frequency_table, search_term):\n",
        "\n",
        "  df = pd.DataFrame(frequency_table).transpose()\n",
        "  df.columns = ['abs_frequency', 'rel_frequency']\n",
        "  df = df.sort_values('rel_frequency', ascending=False)\n",
        "\n",
        "  ax = sns.barplot(y=df.index, x='rel_frequency', data=df, color='#EF2D56')\n",
        "  ax.set_title(f'Frequency Distribution of {search_term} (per 1,000 Tokens')"
      ],
      "execution_count": 11,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 590
        },
        "id": "aEOGDIi-HNTR",
        "outputId": "24f14ec3-eb32-4f0f-e3fe-dd35dda3058f"
      },
      "source": [
        "search_term = 'watson'\n",
        "\n",
        "parts_with_st = 0\n",
        "frequency_table = get_frequencies(corpus, search_term)\n",
        "\n",
        "print(f'Distribution of \"{search_term}\":\\n')\n",
        "for s in frequency_table:\n",
        "  \n",
        "  if frequency_table[s][0] > 0:\n",
        "    parts_with_st += 1\n",
        "\n",
        "  print(f'- {frequency_table[s][0]} ({round(frequency_table[s][1], 2)} per 1,000 tokens) in {s}')\n",
        "\n",
        "# Range_2\n",
        "range_2 = ( parts_with_st / len(frequency_table.keys()) ) * 100\n",
        "\n",
        "print(f'\\nThe Range_2 is: {round(range_2, 2)}%\\n')\n",
        "\n",
        "plot_frequency_table(frequency_table, search_term)"
      ],
      "execution_count": 12,
      "outputs": [
        {
          "output_type": "stream",
          "text": [
            "Distribution of \"watson\":\n",
            "\n",
            "- 16 (1.69 per 1,000 tokens) in THE MAN WITH THE TWISTED LIP\n",
            "- 10 (1.07 per 1,000 tokens) in HEADED LEAGUE\n",
            "- 7 (0.84 per 1,000 tokens) in THE ADVENTURE OF THE NOBLE BACHELOR\n",
            "- 7 (0.69 per 1,000 tokens) in THE ADVENTURE OF THE COPPER BEECHES\n",
            "- 4 (0.53 per 1,000 tokens) in THE FIVE ORANGE PIPS\n",
            "- 4 (0.56 per 1,000 tokens) in A CASE OF IDENTITY\n",
            "- 4 (0.41 per 1,000 tokens) in THE BOSCOMBE VALLEY MYSTERY\n",
            "- 2 (0.2 per 1,000 tokens) in THE ADVENTURE OF THE BERYL CORONET\n",
            "- 9 (1.12 per 1,000 tokens) in THE ADVENTURE OF THE BLUE CARBUNCLE\n",
            "- 0 (0.0 per 1,000 tokens) in THE ADVENTURE OF THE ENGINEER'S THUMB\n",
            "- 6 (0.69 per 1,000 tokens) in A SCANDAL IN BOHEMIA\n",
            "- 12 (1.2 per 1,000 tokens) in THE ADVENTURE OF THE SPECKLED BAND\n",
            "\n",
            "The Range_2 is: 91.67%\n",
            "\n"
          ],
          "name": "stdout"
        },
        {
          "output_type": "display_data",
          "data": {
            "image/png": "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\n",
            "text/plain": [
              "<Figure size 432x288 with 1 Axes>"
            ]
          },
          "metadata": {
            "tags": [],
            "needs_background": "light"
          }
        }
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "C2kHzQ0wHDqd"
      },
      "source": [
        "## Making it Better\n",
        "\n",
        "Now we have a working solution that does what we set out to do. However, it is definitely not the most efficient or most elegant solution.\n",
        "\n",
        "Can you think of some ways of making this program better?"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "kqDDyWvwHElg"
      },
      "source": [
        "*   If we combined steps one and two, we would not have to store the actual `text` in our corpus object. This would save a lot of memory!\n",
        "*   In step one, we are reading each file twice. Once to get the text and again to get the `story_title`. This isn't necessarily a problem for 10 or 20 files, but it becomes important very quickly. That said, often there are memory vs. speed trade-offs.\n",
        "* Storing individual frequency tables for each document is wasteful in terms of memory as we are storing each word in the vocabulary multiple times.\n",
        "* Since we are storing individual frequency tables, we need to mitigate differences between the vocabularies of each document. For example, we need to mitigage if a `search_term` does not appear in a document. An alternative would be a vocabulary, across all documents, approach. Here we would first create a vocabulary of all words in all documents. Then we would get frequencies for each document and each word."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "fUYJNonuttUw"
      },
      "source": [
        "These are just some suggestions. Ultimately, there are many ways of achieving the same result - each with its own pros and cons. When developing solutions, you should also be mindful of what you are doing why."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "fAn_uzYJIVh8"
      },
      "source": [
        "## Bonus: Dispersion Statistics\n",
        "\n",
        "If you are interested in playing with dispersion statistics, have a look at this function:"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "OFmjmCfdIVA4"
      },
      "source": [
        "import numpy as np\n",
        "\n",
        "def dispersion_statistics(frequency_table):\n",
        "    document_lengths = {}\n",
        "    for d in corpus:\n",
        "        document_lengths[d['story_title']] = d['length']\n",
        "        \n",
        "    # The percentage the term makes up of each document\n",
        "    p = [f[0] / document_lengths[t] for t, f in frequency_table.items()]\n",
        "    \n",
        "    frequencies = [f[0] for f in frequency_table.values()]\n",
        "    \n",
        "    n = len(frequencies)\n",
        "    range_1 = len([f for f in frequencies if f > 0])\n",
        "    range_2 = round((range_1 / n) * 100, 2)\n",
        "    \n",
        "    mean = np.mean(frequencies)\n",
        "    mean_p = np.mean(p)\n",
        "    \n",
        "    std = np.std(frequencies)\n",
        "    std_p = np.std(p)\n",
        "    \n",
        "    cv = std / mean\n",
        "    cv_p = std_p / mean_p\n",
        "    \n",
        "    D = 1 - (cv / np.sqrt(n - 1))\n",
        "    D_p = 1 - (cv_p / np.sqrt(n - 1))\n",
        "\n",
        "    stats = {'n': n, \n",
        "             'mean': mean, 'mean_p': mean_p, \n",
        "             'range_2': range_2, \n",
        "             'std': std, 'std_p': std_p, \n",
        "             'cv': cv, 'cv_p': cv_p, \n",
        "             'D': D, 'D_p': D_p\n",
        "    }\n",
        "\n",
        "\n",
        "    return stats"
      ],
      "execution_count": 19,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "i6yUaB-gIYDG",
        "outputId": "07c43234-2b82-45ec-be57-58d75815bb7c"
      },
      "source": [
        "frequency_table = get_frequencies(corpus, 'watson')\n",
        "dispersion_statistics(frequency_table)"
      ],
      "execution_count": 20,
      "outputs": [
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "{'D': 0.8086329244383665,\n",
              " 'D_p': 0.819914027984733,\n",
              " 'cv': 0.6346927868655285,\n",
              " 'cv_p': 0.5972775991810831,\n",
              " 'mean': 6.75,\n",
              " 'mean_p': 0.0007495326821571226,\n",
              " 'n': 12,\n",
              " 'range_2': 91.67,\n",
              " 'std': 4.284176311342318,\n",
              " 'std_p': 0.00044767908090656404}"
            ]
          },
          "metadata": {
            "tags": []
          },
          "execution_count": 20
        }
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "WhPh-FyFIkda"
      },
      "source": [
        "For a detailled discussion of these statistics as well as the '_p' versions, have a look at: \n",
        "\n",
        "Gries, Stefan Th. 2020. “Analyzing Dispersion.” In A Practical Handbook of Corpus Linguistics, edited by Magali Paquot and Stefan T. Gries, 99–118. Cham: Springer Nature Switzerland."
      ]
    }
  ]
}