intro/Intro_Data_Model.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" src=\"imgs/fonduer-logo.png\" width=\"100px\" style=\"margin-right:20px\">\n",
    "\n",
    "# Tutorial: Navigating the Fonduer Data Model"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Running locally?\n",
    "\n",
    "If you're running this tutorial interactively on your own machine, you'll need to create a new PostgreSQL database named `intro_data_model`.\n",
    "\n",
    "If you have already the database `intro_data_model` in your postgresql, please uncomment the first line to drop it. Otherwise, download our database snapshots by executing `./download_data.sh` in the intro tutorial directory."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#! dropdb --if-exists intro_data_model\n",
    "! createdb intro_data_model\n",
    "! psql intro_data_model < data/intro_data_model.sql > /dev/null"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# The Fonduer Data Model API\n",
    "_Complete Fonduer API documentation is available on [Read the Docs](https://fonduer.readthedocs.io)_\n",
    "\n",
    "## The Fonduer Data Model\n",
    "The Fonduer Data Model serves two high-level purposes. First, it allows Fonduer to capture the immense data variety of richly formatted data in a unified representation. Second, it allows users to provide multimodal supervision that leverages document-level context. Nearly everything in the Fonduer pipeline uses information stored in the Fonduer Data Model. The Fonduer Data Model is heirarchical, as shown below.\n",
    "\n",
    "<img src=\"imgs/dag.png\" width=\"250px\">\n",
    "\n",
    "Each box represents a `Context` object, which are units that a document can be broken down into. For example, a `Sentence` can be part of a `Paragraph` in a `Cell` in a `Table`. The default `Context` objects provided by Fonduer are shown above.\n",
    "\n",
    "To explore the data model, we first load the Fonduer `Meta` class, which creates a connection with our PostgreSQL database."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%load_ext autoreload\n",
    "%autoreload 2\n",
    "%matplotlib inline\n",
    "import os\n",
    "import sys\n",
    "import logging\n",
    "from pprint import pprint\n",
    "\n",
    "from fonduer.parser.models import Document, Sentence, Table, Figure\n",
    "from fonduer import Meta, init_logging\n",
    "\n",
    "\n",
    "ATTRIBUTE = \"intro_data_model\"\n",
    "conn_string = f'postgresql://localhost:5432/{ATTRIBUTE}'\n",
    "\n",
    "# Configure logging for Fonduer\n",
    "init_logging(log_dir=\"logs\")\n",
    "\n",
    "session = Meta.init(conn_string).Session()\n",
    "\n",
    "# Print metadata about the tutorial corpus\n",
    "print(f\"Num Docs: {session.query(Document).count()}\")\n",
    "print(f\"Num Sentences: {session.query(Sentence).count()}\")\n",
    "print(f\"Num Tables: {session.query(Table).count()}\")\n",
    "print(f\"Num Figures: {session.query(Figure).count()}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Parsing Documents into the Data Model\n",
    "\n",
    "The process of parsing input documents containing richly formatted data into Fonduer's data model typically consists of two steps. First, documents can be run through a [Preprocessor](https://fonduer.readthedocs.io/en/stable/user/parser.html#preprocessors), and then fed through the Fonduer Parser to turn the input documents into the directed acyclic graph shown above. For more information about parsing documents, please check out our [end-to-end tutorials](../hardware/max_storage_temp_tutorial.ipynb). The rest of this tutorial assumes that your documents have already been parsed, and instead focuses on the data model itself.\n",
    "\n",
    "\n",
    "### Navigating the Data Model\n",
    "\n",
    "With the `session` object, you can make queries for any of `Context` objects in the data model using the [SQLAlchemy Query API](http://docs.sqlalchemy.org/en/latest/orm/query.html). For example, if we wanted to get a list of all of the Documents in the database, we can issue the following query, which gets all of the Documents ordered by name."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "docs = session.query(Document).order_by(Document.name).all()\n",
    "\n",
    "pprint(docs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Similarly, if we wanted to inspect all of the Sentences parsed, we could issue the following query."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sentences = session.query(Sentence).order_by(Sentence.position).all()\n",
    "pprint(sentences[:5])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In addition to simply querying for specific `Context` objects in the database, we can also navigate the data model heirarchy from each `Context` object. The core `Context` objects are described on [Read the Docs](https://fonduer.readthedocs.io/en/stable/user/parser.html#multimodal-data-model). Let's see some examples.\n",
    "\n",
    "#### Ex. 1: Getting a Sentence's Document"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bc182 = sentences[0].document\n",
    "print(bc182)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Ex. 2: Iterate over all a Document's Sentences"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pprint([sentence for sentence in bc182.sentences][:10])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Ex. 3: Find the first Sentence in the first Table in the Document"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(bc182.tables[0].sentences[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Ex. 4: Inspect the html attributes of a Sentence"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pprint(bc182.tables[0].sentences[0].html_attrs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Ex. 5: Listing the attributes of a Context Object\n",
    "\n",
    "If you forget the API and want to inspect the attributes of a particular Context object, you can just call dir() for a full list if you're working interactively. Otherwise, we'd recommend referring to [Read the Docs](https://fonduer.readthedocs.io/en/stable/user/parser.html#multimodal-data-model).\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dir(bc182.tables[0].sentences[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Ex. 6: Inspect the Cell containing a particular Sentence"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(bc182.tables[0].sentences[0].cell)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Ex. 7: Iterate over all the Cells in a particular row\n",
    "\n",
    "Note that Cells in a Table can span rows or columns. Thus, each Cell's row and column is indicated with `(row_start, row_end)` and `(col_start, col_end)`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "table = bc182.tables[0].sentences[0].cell.table\n",
    "pprint([cell for cell in table.cells if cell.row_start == 1])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Summary\n",
    "The Fonduer Data Model is a heirarchical representation of the input documents. Using the data model APIs, you can traverse anywhere in the data model and inspect the attributes of your data. Visit [Fonduer's Documentation](https://fonduer.readthedocs.io/en/stable/user/parser.html#multimodal-data-model) for a reference of the API."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}