Tutorial Figurennetzwerke.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Kallimachos: Tutorial zur Erstellung von Figurennetzwerken\n",
    "\n",
    "Im Rahmen des Projekts Kallimachos wurde eine Preprocessing-Pipeline entwickelt, die speziell auf deutschsprachige Romane angepasst ist. Insbesondere enthält sie Komponenten zur Erkennung von Figurenreferenzen und Koreferenzauflösung, die im Rahmen von Kallimachos entwickelt wurden und auf die Domäne literarischer Texte angepasst sind. \n",
    "\n",
    "Das Ziel dieses Tutorials ist es, anhand eines realistischen Anwendungsbeispiels darzustellen, wie mit dem Output der Kallimachos-Preprocessing-Pipeline in Python weitergearbeitet werden kann. Als Beispiel wurde dabei die Erstellung und Visualisierung von Figurennetzwerken aus Romanen gewählt.\n",
    "\n",
    "\n",
    "## Voraussetzungen\n",
    "Dieses Tutorial ist für Python 3 konzipiert. Grundlegende Python-Kenntnisse werden vorausgesetzt. Einen interaktiven, kostenlosen Kurs zum Erlernen von Python findet man beispielsweise bei [Codecademy](https://www.codecademy.com/learn/python). \n",
    "\n",
    "Außerdem werden die folgenden Python-Packages benötigt:\n",
    "* [Pandas](http://pandas.pydata.org/)\n",
    "* [NetworkX](https://networkx.github.io/)\n",
    "* [Matplotlib](http://matplotlib.org/)\n",
    "* [Ipywidgets](https://ipywidgets.readthedocs.io/en/latest/)\n",
    "\n",
    "Die Installation von Python-Packages ist am einfachsten mit Pip möglich ([Userguide](https://pip.pypa.io/en/stable/user_guide/)). Unter Windows kann es bei Pandas zu Compiler-Problemen kommen. Auf der Webseite von Pandas finden sich jedoch auch Windows-Binaries für die Installation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Output der Kallimachos-Preprocessing-Pipeline\n",
    "Die Kallimachos-Preprocessing-Pipeline kann über eine Konfigurationsdatei angepasst werden. Für das vorliegende Tutorial werden die Einteilung des Texts in Absätze, die Erkennung der Figurenreferenzen (NER) und die Koreferenzauflösung benötigt. Diese müssen also in der Konfigurationsdatei aktiviert sein. Eine ausführliche Beschreibung, sowie die Pipeline als .jar zum Download, befinden sich [hier](https://gitlab2.informatik.uni-wuerzburg.de/kallimachos/KallimachosEngines).\n",
    "\n",
    "Neben XMI kann die Pipeline ein tabellarisches Format liefern, das sehr stark dem [Output-Format](http://webdoc.sub.gwdg.de/pub/mon/dariah-de/dwp-2016-20.pdf) des [DARIAH-DKPro-Wrappers](http://dariah-de.github.io/DARIAH-DKPro-Wrapper/) nachempfunden ist. In diesem Format steht jedes Token des Texts in einer eigenen Zeile. Mehrere Spalten enthalten Informationen zu diesem Token, wie beispielsweise POS-Tags, NE-Tags oder Coreference-IDs. Die Spalten *SectionId*, *ParagraphId* und *SentenceId* geben über eine numerische Zählung an, in welchem Kapitel, Absatz und Satz sich das Token befindet. Aufgrund seines tabellarischen Aufbaus kann das Format gut mit Excel oder ähnlichen Programmen angezeigt werden. Zur Verarbeitung in Python bieten sich Pandas-Dataframes an, da sie die Datenstruktur gut abbilden können und viele Funktionen, beispielsweise zum Import und Export, bieten.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>SectionId</th>\n",
       "      <th>ParagraphId</th>\n",
       "      <th>SentenceId</th>\n",
       "      <th>TokenId</th>\n",
       "      <th>Begin</th>\n",
       "      <th>End</th>\n",
       "      <th>Token</th>\n",
       "      <th>Lemma</th>\n",
       "      <th>CPOS</th>\n",
       "      <th>POS</th>\n",
       "      <th>Morphology</th>\n",
       "      <th>DependencyHead</th>\n",
       "      <th>DependencyRelation</th>\n",
       "      <th>NamedEntity</th>\n",
       "      <th>CorefId</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>null</td>\n",
       "      <td>4</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>8</td>\n",
       "      <td>14</td>\n",
       "      <td>Johann</td>\n",
       "      <td>Johann</td>\n",
       "      <td>N</td>\n",
       "      <td>NE</td>\n",
       "      <td>masc|sg|</td>\n",
       "      <td>--</td>\n",
       "      <td>--</td>\n",
       "      <td>B-PER_CORE</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>null</td>\n",
       "      <td>4</td>\n",
       "      <td>0</td>\n",
       "      <td>1</td>\n",
       "      <td>15</td>\n",
       "      <td>23</td>\n",
       "      <td>Wolfgang</td>\n",
       "      <td>Wolfgang</td>\n",
       "      <td>N</td>\n",
       "      <td>NE</td>\n",
       "      <td>masc|sg|</td>\n",
       "      <td>--</td>\n",
       "      <td>--</td>\n",
       "      <td>I-PER_CORE</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>null</td>\n",
       "      <td>4</td>\n",
       "      <td>0</td>\n",
       "      <td>2</td>\n",
       "      <td>24</td>\n",
       "      <td>30</td>\n",
       "      <td>Goethe</td>\n",
       "      <td>Goethe</td>\n",
       "      <td>N</td>\n",
       "      <td>NE</td>\n",
       "      <td>masc|sg|</td>\n",
       "      <td>--</td>\n",
       "      <td>--</td>\n",
       "      <td>I-PER_CORE</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>null</td>\n",
       "      <td>5</td>\n",
       "      <td>0</td>\n",
       "      <td>3</td>\n",
       "      <td>32</td>\n",
       "      <td>35</td>\n",
       "      <td>Die</td>\n",
       "      <td>die</td>\n",
       "      <td>ART</td>\n",
       "      <td>ART</td>\n",
       "      <td>fem|pl|</td>\n",
       "      <td>--</td>\n",
       "      <td>--</td>\n",
       "      <td>I-PER_CORE</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>null</td>\n",
       "      <td>5</td>\n",
       "      <td>0</td>\n",
       "      <td>4</td>\n",
       "      <td>36</td>\n",
       "      <td>56</td>\n",
       "      <td>Wahlverwandtschaften</td>\n",
       "      <td>Wahlverwandtschaft</td>\n",
       "      <td>N</td>\n",
       "      <td>NN</td>\n",
       "      <td>fem|pl|</td>\n",
       "      <td>--</td>\n",
       "      <td>--</td>\n",
       "      <td>O</td>\n",
       "      <td>-</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>null</td>\n",
       "      <td>6</td>\n",
       "      <td>0</td>\n",
       "      <td>5</td>\n",
       "      <td>58</td>\n",
       "      <td>61</td>\n",
       "      <td>Ein</td>\n",
       "      <td>eine</td>\n",
       "      <td>ART</td>\n",
       "      <td>ART</td>\n",
       "      <td>masc|sg|</td>\n",
       "      <td>--</td>\n",
       "      <td>--</td>\n",
       "      <td>O</td>\n",
       "      <td>-</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>null</td>\n",
       "      <td>6</td>\n",
       "      <td>0</td>\n",
       "      <td>6</td>\n",
       "      <td>62</td>\n",
       "      <td>67</td>\n",
       "      <td>Roman</td>\n",
       "      <td>Roman</td>\n",
       "      <td>N</td>\n",
       "      <td>NN</td>\n",
       "      <td>masc|sg|</td>\n",
       "      <td>--</td>\n",
       "      <td>--</td>\n",
       "      <td>O</td>\n",
       "      <td>-</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>7</th>\n",
       "      <td>null</td>\n",
       "      <td>7</td>\n",
       "      <td>0</td>\n",
       "      <td>7</td>\n",
       "      <td>69</td>\n",
       "      <td>75</td>\n",
       "      <td>Erstes</td>\n",
       "      <td>erst</td>\n",
       "      <td>ADJA</td>\n",
       "      <td>ADJA</td>\n",
       "      <td>neut|sg|</td>\n",
       "      <td>--</td>\n",
       "      <td>--</td>\n",
       "      <td>O</td>\n",
       "      <td>-</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>8</th>\n",
       "      <td>null</td>\n",
       "      <td>7</td>\n",
       "      <td>0</td>\n",
       "      <td>8</td>\n",
       "      <td>76</td>\n",
       "      <td>83</td>\n",
       "      <td>Kapitel</td>\n",
       "      <td>Kapitel</td>\n",
       "      <td>N</td>\n",
       "      <td>NN</td>\n",
       "      <td>neut|sg|</td>\n",
       "      <td>--</td>\n",
       "      <td>--</td>\n",
       "      <td>O</td>\n",
       "      <td>-</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>9</th>\n",
       "      <td>null</td>\n",
       "      <td>8</td>\n",
       "      <td>0</td>\n",
       "      <td>9</td>\n",
       "      <td>85</td>\n",
       "      <td>91</td>\n",
       "      <td>Eduard</td>\n",
       "      <td>Eduard</td>\n",
       "      <td>N</td>\n",
       "      <td>NE</td>\n",
       "      <td>neut|sg|</td>\n",
       "      <td>--</td>\n",
       "      <td>--</td>\n",
       "      <td>B-PER_CORE</td>\n",
       "      <td>990</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "  SectionId ParagraphId  SentenceId  TokenId  Begin  End  \\\n",
       "0      null           4           0        0      8   14   \n",
       "1      null           4           0        1     15   23   \n",
       "2      null           4           0        2     24   30   \n",
       "3      null           5           0        3     32   35   \n",
       "4      null           5           0        4     36   56   \n",
       "5      null           6           0        5     58   61   \n",
       "6      null           6           0        6     62   67   \n",
       "7      null           7           0        7     69   75   \n",
       "8      null           7           0        8     76   83   \n",
       "9      null           8           0        9     85   91   \n",
       "\n",
       "                  Token               Lemma  CPOS   POS Morphology  \\\n",
       "0                Johann              Johann     N    NE   masc|sg|   \n",
       "1              Wolfgang            Wolfgang     N    NE   masc|sg|   \n",
       "2                Goethe              Goethe     N    NE   masc|sg|   \n",
       "3                   Die                 die   ART   ART    fem|pl|   \n",
       "4  Wahlverwandtschaften  Wahlverwandtschaft     N    NN    fem|pl|   \n",
       "5                   Ein                eine   ART   ART   masc|sg|   \n",
       "6                 Roman               Roman     N    NN   masc|sg|   \n",
       "7                Erstes                erst  ADJA  ADJA   neut|sg|   \n",
       "8               Kapitel             Kapitel     N    NN   neut|sg|   \n",
       "9                Eduard              Eduard     N    NE   neut|sg|   \n",
       "\n",
       "  DependencyHead DependencyRelation NamedEntity CorefId  \n",
       "0             --                 --  B-PER_CORE       1  \n",
       "1             --                 --  I-PER_CORE       1  \n",
       "2             --                 --  I-PER_CORE       1  \n",
       "3             --                 --  I-PER_CORE       1  \n",
       "4             --                 --           O       -  \n",
       "5             --                 --           O       -  \n",
       "6             --                 --           O       -  \n",
       "7             --                 --           O       -  \n",
       "8             --                 --           O       -  \n",
       "9             --                 --  B-PER_CORE     990  "
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import pandas as pd\n",
    "\n",
    "infile = \"Goethe,-Johann-Wolfgang_Die Wahlverwandtschaften.jtf\"\n",
    "#read jtf to dataframe\n",
    "df = pd.read_table(infile, encoding=\"cp1252\", index_col=False, dtype={'SectionId': str, 'ParagraphId' : str})\n",
    "#df.head anzeigen\n",
    "df.head(10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Figurennetzwerke\n",
    "Wir modellieren ein Figurennetzwerk als mathematischen Graphen, der aus Entitäten, sog. Knoten, und Verbindungen zwischen diesen Entitäten, sog. Kanten, besteht. In einem Figurennetzwerk wird jede Figur als Knoten und ihre Interaktionen als Kanten repräsentiert. Die Kanten können außerdem gewichtet sein, also eine zusätzliche numerische Information tragen, die angibt, wie wichtig eine Kante ist. Eine gute Einführung in die Graphentheorie bietet das Kapitel \"Netzwerke\" in [Fotis Jannidis / Hubertus Kohle / Malte Rehbein (Hg.): Digital Humanities. Eine Einführung. Stuttgart: Metzler 2017, S. 147-161](http://link.springer.com/book/10.1007/978-3-476-05446-3).\n",
    "\n",
    "\n",
    "Zunächst benötigen wir also die Information, welche Figuren vorhanden sind - wir müssen also alle Figurenreferenzen im Text erkennen. Die NER-Komponente von [Jannidis et al. (2015)](https://opus.bibliothek.uni-wuerzburg.de/frontdoor/index/index/year/2017/docId/14333) liefert uns diese Daten, die in der Spalte \"NamedEntity\" im tabellarischen Format zu finden sind. Dabei wird unterschieden zwischen \"Core\", also tatsächlichen Namen, \"App\", also Appellativa wie Verwandtschafts- oder Berufsbezeichnungen und \"Pron\", also pronominalen Referenzen.\n",
    "\n",
    "Die Koreferenzauflösung versucht festzustellen, welche Referenzen sich auf die gleichen Figuren beziehen - alle zusammengehörigen Figurenreferenzen haben also die gleiche *CorefId* [(Krug et al., 2015)](http://www.aclweb.org/anthology/W15-0711).\n",
    "\n",
    "## ID-Dictionary erstellen\n",
    "Aus der Menge aller Referenzen zu einer CorefId wollen wir einen möglichst aussagekräftigen Anzeige-Namen ermitteln, der im Figurennetzwerk genutzt werden kann. Es bietet sich an, die häufigste Referenz auszuwählen. Pronomen werden dabei nur berücksichtigt, falls kein konkreter Name oder Appelativ zu einer Figur vorhanden ist.\n",
    "\n",
    "Manche Figurenreferenzen bestehen aus mehreren Wörtern, wie z.B. \"Frau von Briest\". Dies wird durch die NE-Tags \"B-PER\" und \"I-PER\" gekennzeichnet. Die einzelnen Tokens befinden sich jedoch in separaten Zeilen. Für den Anzeige-Namen wollen wir diese Tokens wieder zu dem kompletten Namen zusammenfügen.\n",
    "\n",
    "Es ist außerdem möglich, dass mehrere CorefIds den gleichen Anzeige-Namen zugeordnet bekommen. Dies passiert bei sehr generischen Ausdrücken wie \"Frau\" oder \"Herr\". Daher wird die CorefId an den ermittelten Anzeige-Namen angehängt, um solche Fälle auch später noch unterscheiden zu können.\n",
    "\n",
    "Die ermittelten Anzeige-Namen werden in einem Dictionary gespeichert, sodass sie jederzeit anhand der CorefId wieder abgerufen werden können."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'Eduard_783'"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from collections import defaultdict\n",
    "\n",
    "# für jede CorefId alle zugehörigen Referenzen ermitteln und daraus Anzeige-Name auswählen\n",
    "def make_id_dict(df):\n",
    "    \"\"\"\n",
    "    Waehlt fuer jede Figur die haeufigste Mention im Coreference Cluster als Anzeigenamen aus.\n",
    "    \"\"\"\n",
    "    #Figurenreferenzen werden als Listen in Defaultdicts gesammelt\n",
    "    id_dict_long = defaultdict(list)\n",
    "    id_dict_pron = defaultdict(list)\n",
    "    for i, word, tag, id in zip(df.index, df['Token'], df['NamedEntity'], df['CorefId']):\n",
    "        #mehrteilige NEs zusammenfassen\n",
    "        if \"B-PER\" in tag and \"I-PER\" in df.ix[i+1, \"NamedEntity\"] or \"I-PER\" in tag and \"I-PER\" in df.ix[i+1, \"NamedEntity\"]:\n",
    "            continue\n",
    "        elif \"I-PER\" in tag and not \"I-PER\" in df.ix[i+1, \"NamedEntity\"]:\n",
    "            j = i\n",
    "            person = \"\"\n",
    "            while \"I-PER\" in df.ix[j, \"NamedEntity\"] and i > 0:\n",
    "                person = df.ix[j-1, \"Token\"] +\" \"+person\n",
    "                j -= 1\n",
    "            id_dict_long[id].append(person+word)\n",
    "        #Figurenreferenzen im defaultdict sammeln\n",
    "        else:\n",
    "            if tag == \"B-PER_APP\" or tag == \"B-PER_CORE\":\n",
    "                id_dict_long[id].append(word)\n",
    "            #pronominale Referenzen in eigenem defaultdict sammeln\n",
    "            elif tag == \"B-PER_PRON\":\n",
    "                id_dict_pron[id].append(word)\n",
    "                if id not in id_dict_long.keys():\n",
    "                    id_dict_long[id] = []\n",
    "    #Anzeige-Name auswählen: häufigste Referenz\n",
    "    id_dict = {}\n",
    "    for id, names in id_dict_long.items():\n",
    "        #falls es keine Core- oder App-Referenz gibt, häufigstes Pronomen verwenden\n",
    "        if not names:\n",
    "            names = id_dict_pron[id]\n",
    "        id_dict.update({id: max(set(names), key=names.count)+ \"_\"+id})\n",
    "    return id_dict\n",
    "\n",
    "id_dict = make_id_dict(df)\n",
    "id_dict['783']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Interaktionslisten erstellen\n",
    "Um ein Figurennetzwerk erstellen zu können, müssen wir festlegen, wann eine Interaktion zwischen zwei Figuren vorliegt, also wann eine Kante erstellt werden soll. Hierfür gibt es mehrere Ansätze. Zum Einen können die Kanten eines Figurennetzwerks auf Dialogstrukturen basieren, wobei Interaktionen dann vorliegen, wenn zwei oder mehrere Figuren in direkter Rede miteinander kommunizieren. Dieser Ansatz setzt allerdings voraus, dass Passagen direkter Rede und die jeweiligen Sprecher und ggf. Angesprochenen identifiziert werden können, wofür zusätzliche, aufwändigere Vorverarbeitungsschritte nötig sind. Eine zweite Möglichkeit ist, dann eine Interaktion anzunehmen, wenn zwei oder mehr Figuren in einem festgelegten Textabschnitt, beispielsweise einem Absatz, gleichzeitig vorkommen. Da die Erhebung der Interaktionsdaten bei dieser Vorgehensweise deutlich einfach ist und sich in Untersuchungen ([Coll Ardanuy und Sporleder 2014](http://aclweb.org/anthology/W/W14/W14-0904.pdf), [Jannidis et al. 2016](http://dh2016.adho.org/abstracts/297)) gezeigt hat, dass diese relative einfache Modellierung trotzdem gute Repräsentationen liefert, soll dieser Ansatz auch in diesem Tutorial verwendet werden.\n",
    "\n",
    "Wenn also mehr als zwei Figuren in einem Absatz enthalten sind, haben alle untereinander eine Interaktion. Dies lässt sich über die Funktion ```combinations()``` ermitteln, die aus einer Menge von Elementen alle möglichen Zweierkombinationen ermitteln kann.\n",
    "\n",
    "Als Kantengewicht kann gezählt werden, in wie vielen Absätzen dies der Fall ist. Hierzu lässt sich ein [```Counter()```](https://docs.python.org/3/library/collections.html#collections.Counter) verwenden, quasi ein Dictionary, das automatisch mitzählt, wie oft ein Element hinzugefügt wurde."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(('Eduard_783', 'Ottilie_754'), 161),\n",
       " (('Charlotte_780', 'Eduard_783'), 152),\n",
       " (('Charlotte_780', 'Ottilie_754'), 151),\n",
       " (('Kind_750', 'Ottilie_754'), 52),\n",
       " (('Charlotte_780', 'Kind_750'), 42)]"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from itertools import combinations\n",
    "from collections import Counter\n",
    "\n",
    "interactions = Counter()\n",
    "#Dataframe nach Absätzen gruppieren\n",
    "paragraphs = df.groupby(\"ParagraphId\")\n",
    "#für jeden Absatz die enthaltenen Figuren und die möglichen Zweierkombinationen ermitteln\n",
    "for para_i, paragraph in paragraphs:\n",
    "    #alle Figurenreferenzen ermitteln und Anzeige-Namen im Dictionary nachschlagen\n",
    "    coref_ids = [id_dict[id] for id in paragraph['CorefId'] if id != \"-\"]\n",
    "    if len(coref_ids) >= 2:\n",
    "        #alle möglichen Interaktionen im Absatz ermitteln und im Counter speichern\n",
    "        relations = [tuple(sorted(rel)) for rel in list(combinations(set(coref_ids), 2))]\n",
    "        interactions.update(relations)\n",
    "\n",
    "interactions.most_common(5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Interaktionslisten speichern\n",
    "\n",
    "In dem Counter sind nun alle Interaktionen (also gemeinsames Vorkommen zweier Figuren in einem Absatz) und deren Häufigkeit gespeichert. Diese Informationen reichen aus, um ein Figurennetzwerk zu erstellen. Es kann nützlich sein, diese Interaktionsliste in einer txt-Datei zu speichern, sodass die Extraktion nicht öfter wiederholt werden muss. Außerdem können die Interaktionslisten auch in anderen Programmen, wie beispielsweise zur Visualisierung in [Gephi](https://gephi.org/), verwendet werden.\n",
    "\n",
    "Die Interaktionsliste besitzt drei Spalten: die ersten beiden enthalten die Figuren (Knoten), zwischen denen eine Kante vorliegt und die dritte Spalte das entsprechende Kantengewicht.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "#Interaktionsliste in txt-Datei speichern\n",
    "with open(\"interactions.txt\", \"w\", encoding=\"utf-8\") as outfile:\n",
    "    for pair, weight in interactions.most_common():\n",
    "        outfile.write(pair[0] + \"\\t\" + pair[1] + \"\\t\" + str(weight) + \"\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Figurennetzwerke erstellen\n",
    "\n",
    "Zur Erstellung von Figurennetzwerken in Python wird das Package [NetworkX](https://networkx.github.io/) verwendet, das entsprechende Datenstrukturen für Graphen sowie deren Visualisierung und Analyse bereitstellt.\n",
    "\n",
    "Unsere Interaktionsliste kann direkt von NetworkX [eingelesen werden](http://networkx.readthedocs.io/en/stable/reference/generated/networkx.readwrite.edgelist.read_edgelist.html?highlight=read%20edgelist). In den ersten beiden Spalten stehen die beiden Knoten zu einer Kanten, während in der dritten Spalte eine weitere Eigenschaft, in unserem Fall das Kantengewicht, gelistet ist. Beim Einlesen muss daher mittels eines Dictionaries festgelegt werden, welche Information in dieser Spalte steht und welchen Datentyp diese hat. Es wären auch noch weitere Spalten für zusätzliche Eigenschaften möglich.\n",
    "\n",
    "Ein Roman kann sehr viele Figurenreferenzen enthalten, von denen viele auch nur sehr selten vorkommen. Dieser Effekt wird durch Fehler bei der automatischen Coreference Resolution noch verstärkt. Daher kann ein Figurennetzwerk ein paar Hundert Knoten enthalten, von denen der Großteil jedoch uninteressant ist. Im Hinblick auf Visualisierungen und Analysen ist es somit sinnvoll, das Netzwerk zu filtern, also auf wenige Knoten zu beschränken. Da auch ein menschlicher Betrachter erst in einer stark reduzierten Visualisierung eine Struktur erkennen kann, wird angenommen, dass die Filterung auch für die automatische Verarbeitung nützlich ist.\n",
    "\n",
    "\n",
    "Dabei sind natürlich mehrere Vorgehensweisen denkbar. Beispielsweise könnte man nur Kanten ab einem bestimmten Mindestgewicht oder eine bestimmte Anzahl von Kanten mit hohem Gewicht vom Anfang der Interaktionsliste berücksichtigen. In diesem Beispiel wurde das Netzwerk auf die x wichtigsten Knoten (Parameter ```node_filter```) beschränkt. Die wichtigsten Knoten wurden über den Knotengrad (node degree) ermittelt. Dieser Wert berechnet sich als die Summe der Kantengewichte aller Kanten, die an dem Knoten anliegen.\n",
    "Zusätzlich wurden x% der Kanten mit dem geringsten Gewicht (Parameter ```edge_filter```) herausgefiltert, da sonst fast immer alle Knoten untereinander verbunden sind. Diese beiden Grenzwerte für die Filterung können nur empirisch festgelegt werden.\n",
    "\n",
    "Isolierte Knoten, die nach der Anwendung beider Filter ohne anliegende Kanten übrigbleiben, werden entfernt."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<networkx.classes.graph.Graph at 0xa1545c0>"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import networkx as nx\n",
    "from operator import itemgetter\n",
    "\n",
    "#Graph-Objekt mit NetworkX erstellen und filtern\n",
    "def make_graph(file, node_filter=10, edge_filter=0.3):\n",
    "    \"\"\"\n",
    "    Erstellt ein Netzwerk aus einer Interaktionsliste, mit Filtermoeglichkeiten.\n",
    "    Parameter\n",
    "    ---------\n",
    "    file : Datei mit Interaktionsliste\n",
    "    node_filter: Knotenfilter (max. Knoten im Netzwerk)\n",
    "    edge_filter: Prozentangabe zwischen 0 und 1\n",
    "\n",
    "    Returns\n",
    "    -------\n",
    "    graph : NetworkX Graph-Objekt\n",
    "    \"\"\"\n",
    "    graph = nx.read_edgelist(file, nodetype=str, delimiter=\"\\t\", data=(('weight', float),))\n",
    "    #node_filter: die x wichtigsten Knoten berücksichtigen, nach gewichtetem Knotengrad\n",
    "    if node_filter:\n",
    "        #Sortierung nach Alphabet und nach Grad, um gleiche Reihenfolge bei jedem Durchlauf sicherzustellen\n",
    "        degree = sorted(graph.degree(weight='weight').items())\n",
    "        degree = sorted(degree, key=itemgetter(1), reverse=True)\n",
    "        graph = graph.subgraph([n for n, d in degree[:node_filter]])\n",
    "    #edge_filter: unterste x% der Kanten (nach Gewicht) rausfiltern\n",
    "    if edge_filter:\n",
    "        #mehrfache Sortierung, um gleiche Reihenfolge sicherzustellen\n",
    "        edgelist = [(sorted((u,v)),k['weight']) for u,v,k in graph.edges(data=True)] #Knotenpaare nach Alphabet sortiert\n",
    "        edgelist = sorted(edgelist) #gesamte Liste nach Alphabet sortiert\n",
    "        sorted_edgelist = sorted(edgelist, key=itemgetter(1)) #nach Kantengewicht sortiert, aufsteigend!\n",
    "        sorted_edgelist = [(u,v,k) for [u,v],k in sorted_edgelist]\n",
    "        summe = 0.0\n",
    "        i= 0\n",
    "        for u,v,k in sorted_edgelist:\n",
    "            summe += k\n",
    "            if summe/graph.size(weight='weight') >= edge_filter:\n",
    "                break\n",
    "            else:\n",
    "                i+=1\n",
    "        graph.remove_edges_from(sorted_edgelist[:i])\n",
    "        #isolierte Knoten entfernen\n",
    "        graph.remove_nodes_from([n for n, d in graph.degree().items() if d == 0])\n",
    "    return graph\n",
    "\n",
    "#Graph aus Interaktionsliste erstellen\n",
    "graph = make_graph(\"interactions.txt\", 10, 0.3)\n",
    "graph"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Netzwerk visualisieren\n",
    "\n",
    "Das erstellte Netzwerk kann nun auch visualisiert werden. NetworkX bietet hierfür Funktionen an, die den Graphen dann mithilfe von Matplotlib plotten.\n",
    "\n",
    "In der Visualisierung können Kantengewichte über die Dicke der Kanten dargestellt werden: je höher das Kantengewicht, desto dicker erscheint die Kante. Da eine direkte Verwendung des Kantengewichts jedoch zu extrem dicken Kanten führen würde, wird zunächst das relative Gewicht (im Bezug auf die Summe aller Kantengewichte im Graphen) berechnet und dann mit einem Faktor x multipliziert. Dieser Faktor muss empirisch gewählt werden, sodass eine brauchbare Visualisierung entsteht.\n",
    "\n",
    "Außerdem muss festgelegt werden, welcher Knoten wo auf der Zeichenfläche platziert wird. Dafür gibt es eine Reihe von [Layout-Algorithmen für Graphen](https://de.wikipedia.org/wiki/Graphzeichnen), von denen einige auch in NetworkX zur Verfügung stehen. Hier wird der [Fruchterman-Reingold-Algorithmus](https://networkx.github.io/documentation/networkx-1.10/reference/generated/networkx.drawing.layout.spring_layout.html#networkx.drawing.layout.spring_layout) verwendet, der anziehende und abstoßende Kräfte zwischen den Knoten annimmt und diese so platziert, dass diese Kräfte möglichst im Gleichgewicht sind und die Kanten möglichst gleich lang sind.\n",
    "\n",
    "Die interaktive Visualisierung bietet Schieberegler, mit denen der Knoten- und Kantenfilter, sowie der Faktor für die Kantendicke verändert werden können. Die Visualisierung des Netzwerks aktualisiert sich dann direkt, sodass sich die Auswirkungen der jeweiligen Einstellungen schön mitverfolgen lassen. Die Funktionen für interaktiven Output in Jupyter/iPython-Notebooks werden von dem Package [ipywidgets](https://ipywidgets.readthedocs.io/en/latest/) zur Verfügung gestellt.\n",
    "\n",
    "Bemerkung: Je mehr Knoten in das Netzwerk aufgenommen werden, desto länger dauert die Erstellung des Graphen und der Visualisierung. Hier ist dann ein Augenblick Geduld gefragt, bis die Visualisierung sich aktualisiert!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<function __main__.interactive_visualisation>"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x4bc9a20>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%matplotlib inline\n",
    "import matplotlib.pyplot as plt\n",
    "from ipywidgets import interact, fixed\n",
    "\n",
    "def visualize_graph(graph, width_factor=40):\n",
    "    \"\"\"\n",
    "    Visualisiert das Netzwerk.\n",
    "    Parameter\n",
    "    ---------\n",
    "    graph : Graph-Objekt\n",
    "    \"\"\"\n",
    "    fig = plt.figure(figsize=(8,8))\n",
    "    #Kantendicke anhand des Kantengewichts berechnen\n",
    "    widths = [dic['weight']/graph.size(weight='weight')*width_factor for (p1, p2, dic) in graph.edges(data=True)]\n",
    "    #Layout-Algorithmus anwenden\n",
    "    pos = nx.spring_layout(graph, k=1.5)\n",
    "    #Netzwerk plotten und speichern\n",
    "    nx.draw_networkx(graph, pos, width = widths, font_size=13, alpha=0.5, edge_color=\"blue\")\n",
    "    plt.axis('off')\n",
    "    plt.savefig(\"network.png\", dpi=100)\n",
    "\n",
    "#visualize_graph(graph)\n",
    "    \n",
    "#Interaktive Visualisation mit ipywidgets\n",
    "def interactive_visualisation(file, node_filter=10, edge_filter=0.3, width_factor=40):\n",
    "    graph = make_graph(file, node_filter, edge_filter)\n",
    "    visualize_graph(graph, width_factor)\n",
    "\n",
    "interact(interactive_visualisation, file=fixed(\"interactions.txt\"), node_filter=(0,200), edge_filter=(0.0, 1.0), width_factor=(1,100,10))\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Ausblick: Berechnung von Netzwerkmetriken\n",
    "\n",
    "\n",
    "Ausgehend von einem NetworkX-Graphobjekt können diverse Funktionen zur Berechnung von Netzwerkmetriken angewandt werden. Eine große Zahl solcher Algorithmen ist in NetworkX vorhanden. Mithilfe solcher Netzwerkmetriken können strukturelle Eigenschaften eines Netzwerks als Zahlenwerte ausgedrückt und analysiert werden.\n",
    "\n",
    "Als zwei einfache Beispiele werden hier die Berechnung der Gradzentralität, die bereits zur Filterung des Graphen verwendet wurde, sowie die Netzwerk-Dichte genannt. Es existiert eine Vielzahl weiterer Maße zur Netzwerkanalyse, wobei häufig mehrere in Kombination verwendet werden.\n",
    "\n",
    "Die Gradzentralität kann für jeden Knoten einzeln berechnet werden und gibt die Anzahl aller an dem Knoten anliegenden Kanten, als Bruchteil aller möglichen Kanten für diesen Knoten, an. Gibt es einen Knoten mit der Gradzentralität 1, während alle anderen Knoten einen geringeren Wert haben, so deutet das auf ein sternförmiges Netzwerk hin. Hat jeder Knoten den Wert 1, so ist das Netzwerk vollständig vernetzt.\n",
    "\n",
    "In diesem Beispiel sind also \"Charlotte\" und \"Ottilie\" die am stärksten vernetzten Knoten. Die Werte der Gradzentralität sind natürlich auch von der Netzwerkfilterung abhängig.\n",
    "\n",
    "Andere Maße, wie die Netzwerkdichte, beziehen sich auf ein Netzwerk als Ganzes. Die Dichte gibt das Verhältnis der Anzahl aller tatsächlich im Netzwerk realisierten Kanten zu der Anzahl aller theoretisch möglichen Kanten an. Folglich kann sich ein Wert zwischen 0 (Netzwerk ohne Kanten) und 1 (vollständig vernetzter Graph) ergeben."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'Ottilie_754': 0.7142857142857142, 'Gesellschaft_27': 0.14285714285714285, 'Luciane_523': 0.14285714285714285, 'Kind_750': 0.42857142857142855, 'Architekt_567': 0.14285714285714285, 'Freund_712': 0.2857142857142857, 'Eduard_783': 0.5714285714285714, 'Charlotte_780': 0.7142857142857142}\n",
      "0.39285714285714285\n"
     ]
    }
   ],
   "source": [
    "degrees = nx.degree_centrality(graph)\n",
    "print(degrees)\n",
    "density = nx.density(graph)\n",
    "print(density)\n"
   ]
  }
 ],
 "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.4.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}