tutorial-and-cookbook.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tutorial and cookbook\n",
    "\n",
    "By [Allison Parrish](http://www.decontextualize.com/)\n",
    "\n",
    "Draft version!\n",
    "\n",
    "This notebook shows you how to use [Pincelate](https://pincelate.readthedocs.io/) and how to do some interesting things with it.\n",
    "\n",
    "Pincelate is a Python library that provides a simple interface for a machine learning model that can sound out English words and spell English words based on how they sound. \"Sounding out\" here means converting letters (\"orthography\") to sounds (\"phonemes\"), and \"spelling\" means converting sounds to letters (phonemes to orthography). The model is trained on the [CMU Pronouncing Dictionary](http://www.speech.cs.cmu.edu/cgi-bin/cmudict), which means it generally sounds words out as though speaking \"standard\" North American English, and spells words according to \"standard\" North American English rules (at least as far as the model itself is accurate).\n",
    "\n",
    "## Preliminaries\n",
    "\n",
    "Loading various required modules, plus the language model and Pincelate. To run these experiments, you'll need to install Pincelate. Type the following at a command prompt:\n",
    "\n",
    "    pip install tensorflow  # or tensorflow-gpu\n",
    "    pip install pincelate\n",
    "    \n",
    "(Installing Pincelate will also install Pronouncing, which we'll use at various points in the experiments below.)\n",
    "\n",
    "Other libraries you'll need for this notebook: `numpy` and `scipy`. If you're using Anaconda, you already have these libraries. If not, install them like so:\n",
    "\n",
    "    pip install numpy scipy\n",
    "    \n",
    "Importing numpy and Pronouncing:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import pronouncing as pr"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now import Pincelate and instantiate a Pincelate object. (This will load the pre-trained model provided with the package.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Using TensorFlow backend.\n"
     ]
    }
   ],
   "source": [
    "from pincelate import Pincelate"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "pin = Pincelate()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Later in the notebook, I'm going to use some of Jupyter Notebook's interactive features, so I'll import the libraries here:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ipywidgets as widgets\n",
    "from IPython.display import display\n",
    "from ipywidgets import interact, interactive_output, Layout, HBox, VBox"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Sounding out and spelling\n",
    "\n",
    "The CMU Pronouncing Dictionary provides a database of tens of thousands of English words along with their pronunciations. I made a Python library called [Pronouncing](https://github.com/aparrish/pronouncingpy) to make it easier to look up words in dictionary. Here's how it works. To get the pronunciation of a word:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'AE1 L F AH0 B EH2 T'"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pr.phones_for_word(\"alphabet\")[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The CMU Pronouncing Dictionary provides pronunciations as a list of phonemes in a phonetic transcription scheme called [Arpabet](https://en.wikipedia.org/wiki/ARPABET), in which each unique sound in English is given a different symbol.\n",
    "\n",
    "If you want to find words that have a particular pronunciation, you can look them up in the CMU Pronouncing Dictionary like so:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['flour', 'flower']"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pr.search(\"^F L AW1 ER0$\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "That all seems pretty straightforward! The problem arises when you want to spell a word that *isn't* in the CMU Pronouncing Dictionary. You'll get an error:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "ename": "IndexError",
     "evalue": "list index out of range",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mIndexError\u001b[0m                                Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-7-4aa47dd2de94>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0mpr\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mphones_for_word\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m\"mimsy\"\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0;36m0\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;31mIndexError\u001b[0m: list index out of range"
     ]
    }
   ],
   "source": [
    "pr.phones_for_word(\"mimsy\")[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Likewise, if you've just invented a new word and have a pronunciation in mind, the CMU Pronouncing Dictionary won't be able to help you spell it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[]"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pr.search(\"^B L AH1 R F$\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is where Pincelate comes in handy. Pincelate's machine learning model can provide phonemes for words that aren't in the CMU Pronouncing Dictionary, and produce plausible spellings of arbitrary sequences of phonemes. To sound out a word, use the `.soundout()` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['M', 'IH1', 'M', 'S', 'IY0']"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pin.soundout(\"mimsy\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "... and to produce a plausible spelling for a word whose sounds you just made up, use the `.spell()` method, passing it a list of Arpabet phonemes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'blurf'"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pin.spell(['B', 'L', 'AH1', 'R', 'F'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It's important to note that Pincelate's `.soundout()` method will *only* work with letters that appear the CMU Pronouncing Dictionary's vocabulary. (You need to use lowercase letters only.) So the following will throw an error:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "ename": "KeyError",
     "evalue": "'é'",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mKeyError\u001b[0m                                  Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-11-0edf2522d617>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0mpin\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mspell\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m\"étui\"\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;32m~/Dropbox/projects/pincelate/pincelate/__init__.py\u001b[0m in \u001b[0;36mspell\u001b[0;34m(self, phones, temperature)\u001b[0m\n\u001b[1;32m    130\u001b[0m                 \u001b[0mthis_feat\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mphone_feature_map\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0mitem\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m-\u001b[0m\u001b[0;36m1\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    131\u001b[0m             \u001b[0;32melse\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m--> 132\u001b[0;31m                 \u001b[0mthis_feat\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mphone_feature_map\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0mitem\u001b[0m\u001b[0;34m]\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m    133\u001b[0m             \u001b[0mfeats\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mappend\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mthis_feat\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    134\u001b[0m         state_val = self.phon2orth.infer(\n",
      "\u001b[0;31mKeyError\u001b[0m: 'é'"
     ]
    }
   ],
   "source": [
    "pin.spell(\"étui\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example: phoneme frequency analysis\n",
    "\n",
    "Using Pincelate's model, we can do phonetic analysis on texts, even texts that contain words that aren't in the CMU Pronouncing Dictionary. For example, let's find out what the most common phonemes are in Lewis Carroll's \"Jabberwocky.\" Here's the full text:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "text = \"\"\"\n",
    "'Twas brillig, and the slithy toves\n",
    "      Did gyre and gimble in the wabe:\n",
    "All mimsy were the borogoves,\n",
    "      And the mome raths outgrabe.\n",
    "\n",
    "\"Beware the Jabberwock, my son!\n",
    "      The jaws that bite, the claws that catch!\n",
    "Beware the Jubjub bird, and shun\n",
    "      The frumious Bandersnatch!\"\n",
    "\n",
    "He took his vorpal sword in hand;\n",
    "      Long time the manxome foe he sought---\n",
    "So rested he by the Tumtum tree\n",
    "      And stood awhile in thought.\n",
    "\n",
    "And, as in uffish thought he stood,\n",
    "      The Jabberwock, with eyes of flame,\n",
    "Came whiffling through the tulgey wood,\n",
    "      And burbled as it came!\n",
    "\n",
    "One, two! One, two! And through and through\n",
    "      The vorpal blade went snicker-snack!\n",
    "He left it dead, and with its head\n",
    "      He went galumphing back.\n",
    "\n",
    "\"And hast thou slain the Jabberwock?\n",
    "      Come to my arms, my beamish boy!\n",
    "O frabjous day! Callooh! Callay!\"\n",
    "      He chortled in his joy.\n",
    "\n",
    "'Twas brillig, and the slithy toves\n",
    "      Did gyre and gimble in the wabe:\n",
    "All mimsy were the borogoves,\n",
    "      And the mome raths outgrabe.\n",
    "\"\"\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First, parse the text into words and convert them to lower case:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "import re\n",
    "words = [item.lower() for item in re.findall(r\"\\b(\\w+)\\b\", text)]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here's a random sample of the words just to ensure that we've got what we wanted:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['flame',\n",
       " 'son',\n",
       " 'slithy',\n",
       " 'left',\n",
       " 'he',\n",
       " 'the',\n",
       " 'beamish',\n",
       " 'wabe',\n",
       " 'and',\n",
       " 'manxome']"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import random\n",
    "random.sample(words, 10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we'll use `.soundout()` to get a list of phonemes for each item, and feed them to a `Counter()` object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "from collections import Counter\n",
    "phoneme_count = Counter()\n",
    "for word in words:\n",
    "    phoneme_count.update(pin.soundout(word))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And now print out the most common phonemes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('AE1', 34),\n",
       " ('D', 34),\n",
       " ('T', 32),\n",
       " ('N', 32),\n",
       " ('B', 28),\n",
       " ('IY1', 28),\n",
       " ('IH1', 27),\n",
       " ('M', 26),\n",
       " ('R', 25),\n",
       " ('L', 24),\n",
       " ('DH', 22),\n",
       " ('S', 22)]"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "phoneme_count.most_common(12)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For reference, the following cell calculates the most common phonemes in all of the CMU Pronouncing Dictionary:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('AH0', 63131),\n",
       " ('N', 61231),\n",
       " ('S', 50431),\n",
       " ('L', 49960),\n",
       " ('T', 49073),\n",
       " ('R', 46467),\n",
       " ('K', 43075),\n",
       " ('D', 32558),\n",
       " ('IH0', 30196),\n",
       " ('M', 29741),\n",
       " ('Z', 28217),\n",
       " ('ER0', 23954)]"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cmu_phoneme_count = Counter()\n",
    "for word, phones in pr.pronunciations:\n",
    "    cmu_phoneme_count.update(phones.split())\n",
    "cmu_phoneme_count.most_common(12)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We could do a more formal analysis and make claims about how Lewis Carroll's *Jabberwocky* differs significantly from typical English from a phonetic standpoint, but just from a quick look we can see that \"Jabberwocky\" is heavy on the `AE1`s (i.e., the vowel sound in \"hand\") and `B`s."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example: Spelling words from random phonemes\n",
    "\n",
    "Having just counted up all of the phonemes in the CMU Pronouncing Dictionary, we can now invent somewhat plausible neologisms by drawing phonemes at random according to their frequency and gluing them together. (\"Neologism\" is a fancy word for \"made-up word.\") The following code normalizes the phoneme frequencies so we can use them in numpy's `np.random.choice` function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [],
   "source": [
    "all_phonemes = list(cmu_phoneme_count.keys())\n",
    "phoneme_frequencies = np.array(list(cmu_phoneme_count.values()), dtype=np.float32)\n",
    "phoneme_frequencies /= phoneme_frequencies.sum()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And then this function will return a random neologism, created from phonemes drawn at random based on their frequency in English words:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "def neologism_phonemes():\n",
    "    return [np.random.choice(all_phonemes, p=phoneme_frequencies)\n",
    "            for item in range(random.randrange(3,10))]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here's a handful, just to get a taste:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['SH', 'Z', 'B', 'B']\n",
      "['AH0', 'AE1', 'K']\n",
      "['L', 'V', 'S', 'L', 'ER0', 'V', 'IH1']\n",
      "['D', 'R', 'AH0']\n",
      "['AH0', 'D', 'N', 'Y', 'Z', 'IH0', 'S', 'F']\n"
     ]
    }
   ],
   "source": [
    "for i in range(5):\n",
    "    print(neologism_phonemes())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "That's all well and good! Try sounding out some of these on your own (consult the [Arpabet](https://en.wikipedia.org/wiki/ARPABET) table to find the English sound corresponding to each symbol).\n",
    "\n",
    "But how do you *spell* these neologisms? Why, with Pincelate's `.spell()` method of course:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'ebege'"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pin.spell(neologism_phonemes())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here's a for loop that generates neologisms and prints them along with their spellings:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "lalamar ['L', 'AH0', 'L', 'AE1', 'AE1', 'M', 'R']\n",
      "sciachua ['S', 'IH0', 'UW0', 'CH', 'OW1', 'AH0']\n",
      "ahenurnd ['AE1', 'IY0', 'N', 'ER0', 'NG', 'D']\n",
      "smiem ['S', 'M', 'S', 'IY0', 'AE2', 'M']\n",
      "lmang ['L', 'S', 'M']\n",
      "itemstida ['IH1', 'T', 'EH1', 'M', 'S', 'D', 'AH0', 'T', 'AA1']\n",
      "ppnubf ['P', 'S', 'N', 'B', 'F']\n",
      "chiours ['SH', 'IH0', 'OW1', 'ER1', 'Z']\n",
      "eich's ['AY2', 'CH', 'S']\n",
      "ahavi ['AH0', 'HH', 'AH0', 'V', 'IY1']\n",
      "moehl ['M', 'P', 'OW1', 'AH0', 'L']\n",
      "zerbianor ['Z', 'ER0', 'B', 'IY1', 'AE1', 'OY1', 'N', 'ER0']\n"
     ]
    }
   ],
   "source": [
    "for i in range(12):\n",
    "    phonemes = neologism_phonemes()\n",
    "    print(pin.spell(phonemes), phonemes)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Phoneme features\n",
    "\n",
    "The examples above use the phoneme as the basic unit of English phonetics. But each phoneme itself has characteristics, and many phonemes have characteristics in common. For example, the phoneme `/B/` has the following characteristics:\n",
    "\n",
    "* *bilabial*: you put your lips together when you say it\n",
    "* *stop*: airflow from the lungs is completely obstructed\n",
    "* *voiced*: your vocal cords are vibrating while you say it\n",
    "\n",
    "The phoneme `/P/` shares two out of three of these characteristics (it's *bilabial* and a *stop*, but is not voiced). The phoneme `/AE/`, on the other hand, shares *none* of these characteristics. Instead, it has these characteristics:\n",
    "\n",
    "* *vowel*: your mouth doesn't stop or occlude airflow when making this sound\n",
    "* *low*: your tongue is low in the mouth\n",
    "* *front*: your tongue is advanced forward in the mouth\n",
    "* *unrounded*: your lips are not rounded\n",
    "\n",
    "These characteristics of phonemes are traditionally called \"features.\" You can look up the features for particular phonemes using the `phone_feature_map` variable in Pincelate's `featurephone` module:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pincelate.featurephone import phone_feature_map"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example, to get the features for the vowel `/UW/` (vowel sound in \"toot\"):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('hgh', 'bck', 'rnd', 'vwl')"
      ]
     },
     "execution_count": 34,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "phone_feature_map['UW']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The features are referred to here with short three-letter abbreviations. Here's a full list:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* `alv`: alveolar\n",
    "* `apr`: approximant\n",
    "* `bck`: back\n",
    "* `blb`: bilabial\n",
    "* `cnt`: central\n",
    "* `dnt`: dental\n",
    "* `fnt`: front\n",
    "* `frc`: fricative\n",
    "* `glt`: glottal\n",
    "* `hgh`: high\n",
    "* `lat`: lateral\n",
    "* `lbd`: labiodental\n",
    "* `lbv`: labiovelar\n",
    "* `lmd`: low-mid\n",
    "* `low`: low\n",
    "* `mid`: mid\n",
    "* `nas`: nasal\n",
    "* `pal`: palatal\n",
    "* `pla`: palato-alveolar\n",
    "* `rnd`: rounded\n",
    "* `rzd`: rhoticized\n",
    "* `smh`: semi-high\n",
    "* `stp`: stop\n",
    "* `umd`: upper-mid\n",
    "* `unr`: unrounded\n",
    "* `vcd`: voiced\n",
    "* `vel`: velar\n",
    "* `vls`: voiceless\n",
    "* `vwl`: vowel\n",
    "\n",
    "Additionally, there are two special phoneme features:\n",
    "\n",
    "* `beg`: beginning of word\n",
    "* `end`: end of word\n",
    "\n",
    "... which are found and the beginnings and endings of words."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Internally, Pincelate's model operates on these *phoneme features*, instead of directly on whole phonemes. This allows the model to capture and predict underlying similarities between phonemes.\n",
    "\n",
    "Pincelate's `.phonemefeatures()` method works a lot like `.spell()`, except instead of returning a list of phonemes, it returns a [numpy](https://numpy.org/) array of *phoneme feature probabilities*. This array has one row for each predicted phoneme, and one column for the probability (between 0 and 1) of a phoneme feature being a component of each phoneme. To illustrate, here I get the feature array for the word `cat`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {},
   "outputs": [],
   "source": [
    "cat_feats = pin.phonemefeatures(\"cat\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This array has the following shape:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(5, 32)"
      ]
     },
     "execution_count": 42,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cat_feats.shape"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "... which tells us that there are five predicted phonemes. (The `32` is the total number of possible features.) The word `cat`, of course, has only three phonemes (`/K AE T/`)—the extra two are the special \"beginning of the word\" and \"end of the word\" phonemes at the beginning and end, respectively.\n",
    "\n",
    "### Examining predicted phoneme features\n",
    "\n",
    "Let's look at the feature probabilities for the first phoneme (after the special \"beginning of the word\" token at index 0):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 56,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([6.42707571e-04, 2.13692928e-07, 6.62605757e-08, 5.43442347e-10,\n",
       "       5.47038814e-09, 7.04440527e-06, 1.58982238e-09, 1.66211791e-08,\n",
       "       3.81101599e-05, 8.24350354e-05, 1.62252746e-07, 5.46323768e-08,\n",
       "       1.41502560e-10, 5.33169420e-09, 7.31331828e-10, 2.70081146e-05,\n",
       "       1.83614669e-04, 1.62359720e-05, 2.74244065e-11, 1.44446346e-07,\n",
       "       3.33543511e-07, 1.91042790e-08, 3.52445828e-09, 4.54965146e-07,\n",
       "       9.99929667e-01, 7.26780854e-05, 8.35576885e-10, 2.66875286e-04,\n",
       "       1.75827936e-05, 9.99930263e-01, 9.99974251e-01, 1.87013138e-04])"
      ]
     },
     "execution_count": 56,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cat_feats[1]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can look up the index in this array associated with a particular phoneme feature using Pincelate's `.featureidx()` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 74,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.9999302625656128"
      ]
     },
     "execution_count": 74,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cat_feats[1][pin.featureidx('vel')]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This tells us that the `vel` (velar) feature for this phoneme is predicted with almost 100% probability—which makes sense, since the phoneme we'd anticipate—`/K/` is a voiceless velar stop."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following bit of code steps through each row in this array and prints out the phoneme features with the highest probability in that row, using numpy's `argsort` function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 77,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "phoneme 0\n",
      "beg 1.0\n",
      "vwl 0.0\n",
      "vls 0.0\n",
      "apr 0.0\n",
      "bck 0.0\n",
      "\n",
      "phoneme 1\n",
      "vls 0.999974250793457\n",
      "vel 0.9999302625656128\n",
      "stp 0.999929666519165\n",
      "alv 0.000642707571387291\n",
      "unr 0.00026687528588809073\n",
      "\n",
      "phoneme 2\n",
      "unr 0.9997866749763489\n",
      "vwl 0.9990422129631042\n",
      "str 0.9986899495124817\n",
      "fnt 0.9959463477134705\n",
      "low 0.9807271957397461\n",
      "\n",
      "phoneme 3\n",
      "vls 0.9993033409118652\n",
      "alv 0.9990631937980652\n",
      "stp 0.9904974102973938\n",
      "frc 0.0036416002549231052\n",
      "end 0.0013078120537102222\n",
      "\n",
      "phoneme 4\n",
      "end 0.9997904896736145\n",
      "fnt 0.0006787743768654764\n",
      "vwl 0.000589678471442312\n",
      "unr 0.0005248847301118076\n",
      "str 0.0003406509349588305\n",
      "\n"
     ]
    }
   ],
   "source": [
    "def idxfeature(pin, idx):\n",
    "    return pin.orth2phon.target_vocab[idx]\n",
    "for i, phon in enumerate(cat_feats):\n",
    "    print(\"phoneme\", i)\n",
    "    for idx in np.argsort(phon)[::-1][:5]:\n",
    "        print(idxfeature(pin, idx), phon[idx])\n",
    "    print()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example: Distinctive phoneme features in lines of poetry\n",
    "\n",
    "Poems are often organized into lines. In the following example, I look at our example poem (\"Jabberwocky\", included this notebook above) and try to figure out what makes each line of the poem *phonetically distinct* from the other lines.\n",
    "\n",
    "To do this, we need a baseline of phoneme feature frequency in the entire text. As a measure of this, I'm just going to calculate phoneme feature probabilities for every word in the poem (using the `words` list defined above), add them up, and normalize by the number of words in the poem. The code in the following cell uses `.phonemefeatures()` for each word and then numpy's `concatenate()` function to stack them into one big array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 114,
   "metadata": {},
   "outputs": [],
   "source": [
    "word_feats = np.concatenate([pin.phonemefeatures(word) for word in words])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 115,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(903, 32)"
      ]
     },
     "execution_count": 115,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "word_feats.shape"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then we normalize by the length of the array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 101,
   "metadata": {},
   "outputs": [],
   "source": [
    "word_feats_normal = word_feats.sum(axis=0) / word_feats.shape[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following cell prints out the top ten phoneme features in the text:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 116,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "vwl 0.23524545046580508\n",
      "alv 0.21426492435773972\n",
      "unr 0.18771861979648408\n",
      "beg 0.18493909788737944\n",
      "str 0.18301307811362896\n",
      "end 0.1766665947982219\n",
      "stp 0.1471571560480099\n",
      "fnt 0.14340445468376978\n",
      "vcd 0.13304183994694335\n",
      "vls 0.11157506774346303\n"
     ]
    }
   ],
   "source": [
    "for idx in np.argsort(word_feats_normal)[::-1][:10]:\n",
    "    print(idxfeature(pin, idx), word_feats_normal[idx])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So: lots of vowels, mainly unrounded and front; lots of alveolar stops, more voiced than voiceless. If you were to mimic the sound of this text, in other words, you might say something like \"dee dee dat dittee tee day...\"\n",
    "\n",
    "The following cell compares the phoneme feature probabilities in *each line* of the poem to the phoneme feature probabilities of a poem as a whole, and then prints out the top five phoneme features for each line that occur with higher frequency than they do on average in the entire poem. (This is a complicated bit of code, so I included some comments in-line.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 118,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "'Twas brillig, and the slithy toves\n",
      "vcd: +0.066, alv: +0.064, frc: +0.057, lat: +0.029, dnt: +0.019\n",
      "\n",
      "Did gyre and gimble in the wabe:\n",
      "vcd: +0.087, smh: +0.057, stp: +0.047, fnt: +0.046, unr: +0.035\n",
      "\n",
      "All mimsy were the borogoves,\n",
      "bck: +0.047, lmd: +0.039, rnd: +0.039, vcd: +0.038, blb: +0.038\n",
      "\n",
      "And the mome raths outgrabe.\n",
      "low: +0.054, blb: +0.049, nas: +0.042, dnt: +0.036, bck: +0.023\n",
      "\n",
      "\"Beware the Jabberwock, my son!\n",
      "apr: +0.046, lbv: +0.045, low: +0.043, blb: +0.041, vwl: +0.033\n",
      "\n",
      "The jaws that bite, the claws that catch!\n",
      "frc: +0.088, dnt: +0.066, stp: +0.065, vls: +0.062, vcd: +0.057\n",
      "\n",
      "Beware the Jubjub bird, and shun\n",
      "vcd: +0.123, stp: +0.088, cnt: +0.059, mid: +0.057, blb: +0.055\n",
      "\n",
      "The frumious Bandersnatch!\"\n",
      "frc: +0.093, alv: +0.075, hgh: +0.067, vls: +0.060, nas: +0.055\n",
      "\n",
      "He took his vorpal sword in hand;\n",
      "apr: +0.064, glt: +0.062, alv: +0.022, rzd: +0.018, rnd: +0.016\n",
      "\n",
      "Long time the manxome foe he sought---\n",
      "nas: +0.074, vls: +0.062, vel: +0.053, rnd: +0.036, bck: +0.034\n",
      "\n",
      "So rested he by the Tumtum tree\n",
      "vls: +0.056, unr: +0.035, mid: +0.035, cnt: +0.034, hgh: +0.033\n",
      "\n",
      "And stood awhile in thought.\n",
      "alv: +0.094, vls: +0.039, bck: +0.037, rnd: +0.037, str: +0.030\n",
      "\n",
      "And, as in uffish thought he stood,\n",
      "vls: +0.070, frc: +0.038, end: +0.029, pla: +0.026, beg: +0.021\n",
      "\n",
      "The Jabberwock, with eyes of flame,\n",
      "frc: +0.082, lbd: +0.047, lbv: +0.041, str: +0.033, smh: +0.028\n",
      "\n",
      "Came whiffling through the tulgey wood,\n",
      "apr: +0.050, smh: +0.050, lbv: +0.045, vel: +0.035, lat: +0.024\n",
      "\n",
      "And burbled as it came!\n",
      "stp: +0.093, blb: +0.058, vcd: +0.049, rzd: +0.031, lmd: +0.030\n",
      "\n",
      "One, two! One, two! And through and through\n",
      "rnd: +0.064, bck: +0.064, alv: +0.051, str: +0.049, nas: +0.046\n",
      "\n",
      "The vorpal blade went snicker-snack!\n",
      "alv: +0.056, vls: +0.054, lmd: +0.039, lat: +0.028, vel: +0.022\n",
      "\n",
      "He left it dead, and with its head\n",
      "fnt: +0.069, alv: +0.041, vls: +0.040, glt: +0.035, stp: +0.032\n",
      "\n",
      "He went galumphing back.\n",
      "vel: +0.088, nas: +0.051, unr: +0.051, mid: +0.046, glt: +0.023\n",
      "\n",
      "\"And hast thou slain the Jabberwock?\n",
      "low: +0.047, frc: +0.040, alv: +0.026, glt: +0.025, vls: +0.025\n",
      "\n",
      "Come to my arms, my beamish boy!\n",
      "blb: +0.144, nas: +0.078, smh: +0.077, bck: +0.046, end: +0.029\n",
      "\n",
      "O frabjous day! Callooh! Callay!\"\n",
      "vwl: +0.051, lat: +0.045, vel: +0.040, low: +0.035, unr: +0.033\n",
      "\n",
      "He chortled in his joy.\n",
      "alv: +0.094, glt: +0.060, apr: +0.048, lmd: +0.039, smh: +0.036\n",
      "\n",
      "'Twas brillig, and the slithy toves\n",
      "vcd: +0.066, alv: +0.064, frc: +0.057, lat: +0.029, dnt: +0.019\n",
      "\n",
      "Did gyre and gimble in the wabe:\n",
      "vcd: +0.087, smh: +0.057, stp: +0.047, fnt: +0.046, unr: +0.035\n",
      "\n",
      "All mimsy were the borogoves,\n",
      "bck: +0.047, lmd: +0.039, rnd: +0.039, vcd: +0.038, blb: +0.038\n",
      "\n",
      "And the mome raths outgrabe.\n",
      "low: +0.054, blb: +0.049, nas: +0.042, dnt: +0.036, bck: +0.023\n",
      "\n"
     ]
    }
   ],
   "source": [
    "for line in text.split(\"\\n\"):\n",
    "    # get all words in the line\n",
    "    line_words = [item.lower() for item in re.findall(r\"\\b(\\w+)\\b\", line)]\n",
    "    if len(line_words) == 0:  # skip empty lines\n",
    "        continue\n",
    "    # calculate then normalize phoneme feature probabilities for each word\n",
    "    line_word_feats = np.concatenate([pin.phonemefeatures(word) for word in line_words])\n",
    "    line_word_feats_normal = line_word_feats.sum(axis=0) / line_word_feats.shape[0]\n",
    "    # subtract the average of the entire text\n",
    "    diff = line_word_feats_normal - word_feats_normal\n",
    "    # print line with top five features\n",
    "    out = []\n",
    "    for idx in np.argsort(diff)[::-1][:5]:\n",
    "        out.append(\"%s: %+0.3f\" % (idxfeature(pin, idx), diff[idx]))\n",
    "    print(line.strip())\n",
    "    print(\", \".join(out))\n",
    "    print()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To illustrate how to interpret this output, let's look at the following excerpt:\n",
    "\n",
    "    Come to my arms, my beamish boy!\n",
    "    blb: +0.144, nas: +0.078, smh: +0.077, bck: +0.046, end: +0.029\n",
    "    \n",
    "This tells us that this line has comparatively more bilabial sounds (Co*m*e to *m*y ar*m*s *m*y *b*ea*m*ish *b*oy), nasal sounds (all of the `m`s), semi-high back vowel sounds, and ends of words. Likewise:\n",
    "\n",
    "    One, two! One, two! And through and through\n",
    "    rnd: +0.064, bck: +0.064, alv: +0.051, str: +0.049, nas: +0.046\n",
    "    \n",
    "This shows us that the line has round, back, stressed vowels (i.e., the \"oo\" sounds in \"two\" and \"through\") compared to the rest of the poem. Nice!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example: Spelling from phoneme features\n",
    "\n",
    "The Pincelate class has another method, `.spellfeatures()`, which works like `.spell()` except it takes an array of phoneme features (such as that returned from `.phonemefeatures()`) instead of a list of Arpabet phonemes. You can use this to re-spell phoneme feature arrays that you have manipulated. In the following cell, I get the phoneme feature probability array for the word `pug`, then overwrite the probability of the \"voiced\" feature for its first phoneme, then respell:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 119,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'bug'"
      ]
     },
     "execution_count": 119,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pug = pin.phonemefeatures(\"pug\")\n",
    "pug[1][pin.featureidx('vcd')] = 1\n",
    "pin.spellfeatures(pug)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or, you can spell from completely random feature probabilities:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 136,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "kholeshoosh\n",
      "khuolnsioow\n",
      "ttholtiowsh\n",
      "hhohlsieuhe\n",
      "hhhlolkiew\n",
      "kkhoulsishow\n",
      "khhohsioshiot\n",
      "khwolsiwo\n",
      "kloulsioshoo\n",
      "skholthiewide\n",
      "khwleskiewidu\n",
      "kkhullisgiou\n"
     ]
    }
   ],
   "source": [
    "for i in range(12):\n",
    "    print(pin.spellfeatures(np.random.uniform(0, 1, size=(12,32))))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "... which (weirdly) seems like someone trying to imitate the sound of white noise.\n",
    "\n",
    "Or, you might want to build up neologism from scratch, specifying their phoneme features by hand. To do this, use Pincelate's `.vectorizefeatures()` method, passing it an array of tuples of phoneme features. It returns a phoneme probability array that you can then send to `.spellfeatures()`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 137,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'bee'"
      ]
     },
     "execution_count": 137,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "bee = pin.vectorizefeatures([\n",
    "    ['beg'], ['blb', 'stp', 'vcd'], ['hgh', 'fnt', 'vwl'], ['end']\n",
    "])\n",
    "pin.spellfeatures(bee)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As an example, the code in the following cell builds up random five-syllable words from phoneme features (picking places and methods of articulation at random) and spells them out:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 217,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "gippugumbi\n",
      "puciguidity\n",
      "tukidubiub\n",
      "dubugutupu\n",
      "kibitubcuo\n",
      "gubidubupo\n",
      "putudicubu\n",
      "detebutio\n",
      "gugudiuptu\n",
      "gucchicupiut\n"
     ]
    }
   ],
   "source": [
    "for i in range(10):\n",
    "    feats = [[\"beg\"]]\n",
    "    for j in range(5):\n",
    "        place = random.choice(['blb', 'alv', 'vel'])\n",
    "        voice = random.choice(['vcd', 'vls'])\n",
    "        feats.append([place, voice, 'stp'])\n",
    "        vowel_place = random.choice([[\"fnt\", \"unr\"], [\"bck\", \"rnd\"]])\n",
    "        feats.append(vowel_place + [\"hgh\", \"vwl\"])\n",
    "    feats.append([\"end\"])\n",
    "    word_feats = pin.vectorizefeatures(feats)\n",
    "    print(pin.spellfeatures(word_feats))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example: Resizing feature probability arrays\n",
    "\n",
    "Once you have the phonetic feature probability arrays, you can treat them the same way you'd treat any other numpy array. One thing I like to do is use scipy's image manipulation functions and use them resample the phonetic feature arrays. This lets us use the same phonetic information to spell a shorter or longer word. In particular, `scipy.ndimage.interpolation` has a handy [zoom](https://docs.scipy.org/doc/scipy-0.15.1/reference/generated/scipy.ndimage.interpolation.zoom.html) function that resamples an array and interpolates it. Normally you'd use this to resize an image, but nothing's stopping us from using it to resize our phonetic feature array.\n",
    "\n",
    "First, import the function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "from scipy.ndimage.interpolation import zoom"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then get some phoneme feature probabilities:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "feats = pin.phonemefeatures(\"alphabet\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then resize with `zoom()`. The second parameter to `zoom()` is a tuple with the factor by which to scale the dimensions of the incoming array. We only want to scale along the first axis (i.e., the phonemes), keeping the second axis (i.e., the features) constant.\n",
    "\n",
    "A shorter version of the word:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'labe'"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "shorter = zoom(feats, (0.67, 1))\n",
    "pin.spellfeatures(shorter)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A longer version:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'all-phabestab'"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "longer = zoom(feats, (2.0, 1))\n",
    "pin.spellfeatures(longer)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you've downloaded this notebook and you're following along running the code, the following cell will create an interactive widget that lets you \"stretch\" and \"shrink\" the words that you type into the text box by dragging the slider."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "ccd3c5ae147f40aeb9c9009a7cba55ef",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "interactive(children=(Text(value='how to spell expressively', description='words'), FloatSlider(value=1.0, des…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import warnings\n",
    "warnings.filterwarnings('ignore')\n",
    "@interact(words=\"how to spell expressively\", factor=(0.1, 4.0, 0.1))\n",
    "def stretchy(words, factor=1.0):\n",
    "    out = []\n",
    "    for word in words.split():\n",
    "        word = word.lower()\n",
    "        vec = pin.phonemefeatures(word)\n",
    "        if factor < 1.0:\n",
    "            order = 3\n",
    "        else:\n",
    "            order = 0\n",
    "        zoomed = zoom(vec, (factor, 1), order=order)\n",
    "        out.append(pin.spellfeatures(zoomed))\n",
    "    print(\" \".join(out))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Round-trip spelling manipulation\n",
    "\n",
    "Pincelate actually consists of *two* models: one that knows how to sound out words based on how they're spelled, , and another that knows how to spell words from sounds. Pincelate's `.manipulate()` function does a \"round trip\" re-spelling of a word, passing it through both models to return back to the original word. Try it out:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'spelling'"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pin.manipulate(\"spelling\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "On the surface, this isn't very interesting! You don't need Pincelate to tell you how to spell a word that you already know how to spell. But the `.manipulate()` has a handful of parameters that allow you to mess around with the model's internal workings in fun and interesting ways. The first is the `temperature` parameter, which artificially increases or decreases the amount of randomness in the model's output probabilities.\n",
    "\n",
    "### Spelling temperature\n",
    "\n",
    "When the temperature is close to zero, the model will always pick the most likely spelling of the word at each step."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'spelling'"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pin.manipulate(\"spelling\", temperature=0.01)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you increase the temperature to 1.0, the model starts picking values at random according to the underlying probabilities."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'spelling'"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pin.manipulate(\"spelling\", temperature=1.0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "At temperatures above 1.0, the model has a higher chance of picking from letters with lower probabilities, producing a more unlikely spelling:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'spelling'"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pin.manipulate(\"spelling\", temperature=1.5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "At a high enough temperature, the model's spelling feels essentially random:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'lifinug'"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pin.manipulate(\"spelling\", temperature=3.0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following interactive widget lets you play with the `temperature` parameter:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "c300b28d69294a70a0ebae00fe486543",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "interactive(children=(Text(value='your text here', description='s'), FloatSlider(value=1.2500000000000002, des…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "@interact(s=\"your text here\", temp=(0.05, 2.5, 0.05))\n",
    "def tempadjust(s, temp):\n",
    "    return ' '.join([pin.manipulate(w.lower(), temperature=temp) for w in s.split()])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example: Manipulating letter frequencies"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'spilling'"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pin.manipulate(\"spelling\", letters={'e': 10})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example: Manipulating sounds"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'smnenking'"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pin.manipulate(\"spelling\", features={'nas': -10})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Interactive manipulation tool"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ipywidgets as widgets\n",
    "from IPython.display import display\n",
    "from ipywidgets import interact, interactive_output, Layout, HBox, VBox"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [],
   "source": [
    "def manipulate(instr=\"allison\", temp=0.25, **kwargs):\n",
    "    return ' '.join([\n",
    "        pin.manipulate(\n",
    "            w,\n",
    "            letters={k: v*-1 for k, v in kwargs.items()\n",
    "                  if k in pin.orth2phon.src_vocab_idx_map.keys()},\n",
    "            features={k: v*-1 for k, v in kwargs.items()\n",
    "                      if k in pin.orth2phon.target_vocab_idx_map.keys()},\n",
    "            temperature=temp\n",
    "        ) for w in instr.split()]\n",
    "    )"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "0df16043fb3e48b5820b162f46b82ee4",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "VBox(children=(HBox(children=(VBox(children=(FloatSlider(value=0.0, continuous_update=False, description='$', …"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "2529865572b946a28b651eae08398ab7",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "Output(layout=Layout(height='100px'))"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "orth_sliders = {}\n",
    "phon_sliders = {}\n",
    "for ch in pin.orth2phon.src_vocab_idx_map.keys():\n",
    "    if ch in \"'-.\": continue\n",
    "    orth_sliders[ch] = widgets.FloatSlider(description=ch,\n",
    "                               continuous_update=False,\n",
    "                               value=0,\n",
    "                               min=-20,\n",
    "                               max=20,\n",
    "                               step=0.5,\n",
    "                               layout=Layout(height=\"10px\"))\n",
    "for feat in pin.orth2phon.target_vocab_idx_map.keys():\n",
    "    if feat in (\"beg\", \"end\", \"cnt\", \"dnt\"): continue\n",
    "    phon_sliders[feat] = widgets.FloatSlider(description=feat,\n",
    "                               continuous_update=False,\n",
    "                               value=0,\n",
    "                               min=-20,\n",
    "                               max=20,\n",
    "                               step=0.5,\n",
    "                               layout=Layout(height=\"10px\"))\n",
    "instr = widgets.Text(description='input', value=\"spelling words with machine learning\")\n",
    "tempslider = widgets.FloatSlider(description='temp', continuous_update=False, value=0.3, min=0.01, max=5, step=0.05)\n",
    "left_box = VBox(tuple(orth_sliders.values()) + (tempslider,))\n",
    "right_box = VBox(tuple(phon_sliders.values()))\n",
    "all_sliders = HBox([left_box, right_box])\n",
    "\n",
    "out = interactive_output(lambda *args, **kwargs: print(manipulate(*args, **kwargs)),\n",
    "                         dict(instr=instr, temp=tempslider, **orth_sliders, **phon_sliders))\n",
    "out.layout.height = \"100px\"\n",
    "display(VBox([all_sliders, instr]), out)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Phonetic states"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example: Homotopies (blending words)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 353,
   "metadata": {},
   "outputs": [],
   "source": [
    "pairs = [('paper', 'plastic'),\n",
    "         ('kitten', 'puppy'),\n",
    "         ('birthday', 'anniversary'),\n",
    "         ('artificial', 'intelligence'),\n",
    "         ('allison', 'parrish'),\n",
    "         ('moses', 'middletown'),\n",
    "         ('day', 'night'),\n",
    "         ('january', 'december')]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 354,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "paper → paceter → plastic\n",
      "kitten → cuppey → puppy\n",
      "birthday → artherday → anniversery\n",
      "artificial → antelifical → intelligence\n",
      "allison → aarishen → parish\n",
      "moses → midelsown → middletown\n",
      "day → night → night\n",
      "january → daneuber → december\n"
     ]
    }
   ],
   "source": [
    "for start_s, end_s in pairs:\n",
    "    start = pin.phonemestate(start_s)\n",
    "    end = pin.phonemestate(end_s)\n",
    "    steps = 2\n",
    "    out = []\n",
    "    for i in range(steps+1):\n",
    "        out.append(\n",
    "            pin.spellstate(\n",
    "                (start*(1-(i/steps))) + (end*(i/steps))\n",
    "            )\n",
    "        )\n",
    "    print(\" → \".join(out))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [],
   "source": [
    "centroid = (o2ps_tr.translate(\"wordhack\") + \\\n",
    "           o2ps_tr.translate(\"open\") + \\\n",
    "           o2ps_tr.translate(\"projector\")) / 3"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'pordechan'"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ps2o_tr.translate(centroid, temp=0.55)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example: Phonetic resizing of texts"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 355,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "ba0336f65c5043e88ab6af37915d7f60",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "interactive(children=(Text(value='your text here', description='s'), FloatSlider(value=1.0, description='facto…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "@interact(s=\"your text here\", factor=(0.00, 4, 0.1), continuous_update=False)\n",
    "def resizer(s, factor=1.0):\n",
    "    orig = np.array(\n",
    "        [pin.phonemestate(tok.lower()) for tok in s.split()]\n",
    "    )\n",
    "    resized = zoom(orig, (factor, 1), order=4)\n",
    "    return \" \".join([pin.spellstate(vec) for vec in resized])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example: Phonetic similarity with phoneme states"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 358,
   "metadata": {},
   "outputs": [],
   "source": [
    "from scipy.spatial.distance import cosine"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 359,
   "metadata": {},
   "outputs": [],
   "source": [
    "def similarity(s1, s2):\n",
    "    return 1 - cosine(pin.phonemestate(s1), pin.phonemestate(s2))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 360,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.7862290740013123"
      ]
     },
     "execution_count": 360,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "similarity(\"hello\", \"bellow\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 361,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.3832130432128906"
      ]
     },
     "execution_count": 361,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "similarity(\"kiki\", \"bouba\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 362,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.9999770522117615"
      ]
     },
     "execution_count": 362,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "similarity(\"righter\", \"writer\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 363,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.7818005084991455"
      ]
     },
     "execution_count": 363,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "similarity(\"this\", \"that\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 364,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.7280817031860352"
      ]
     },
     "execution_count": 364,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "similarity(\"moop\", \"poom\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 365,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.720030665397644"
      ]
     },
     "execution_count": 365,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "similarity(\"lipstick\", \"plastic\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 366,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.520671010017395"
      ]
     },
     "execution_count": 366,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "similarity(\"lipstick\", \"mascara\")"
   ]
  }
 ],
 "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.7.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}