{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Databases\n",
    "\n",
    "This notebook shows you have to work with `Database` classes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from brightway2 import *"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Create a project for this notebook:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "projects.set_current(\"databases demo\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before going any further, please read [about what a database is in Brightway2](https://docs.brightwaylca.org/intro.html#inventory-databases).\n",
    "\n",
    "## An example database\n",
    "\n",
    "One of the nicest ideas in Brightway2 is that data is just data, and not hidden behind a database and object-relational mapping (ORM). This makes it very easy to do data manipulation, and to add new fields to datasets.\n",
    "\n",
    "Let's define an example database: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "db = Database(\"example\")\n",
    "\n",
    "example_data = {\n",
    "    (\"example\", \"A\"): {\n",
    "        \"name\": \"A\",\n",
    "        \"exchanges\": [{\n",
    "            \"amount\": 1.0,\n",
    "            \"input\": (\"example\", \"B\"),\n",
    "            \"type\": \"technosphere\"\n",
    "            }],\n",
    "        'unit': 'kilogram',\n",
    "        'location': 'here',\n",
    "        'categories': (\"very\", \"interesting\")\n",
    "        },\n",
    "    (\"example\", \"B\"): {\n",
    "        \"name\": \"B\",\n",
    "        \"exchanges\": [],\n",
    "        'unit': 'microgram',\n",
    "        'location': 'there',\n",
    "        'categories': ('quite', 'boring')\n",
    "        }\n",
    "    }"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is quite a simple example - two activities, one of whom has no inputs. In fact, this example dataset has only a few fields. Actually, there are *no* required fields\\* in datasets, only some suggested ones, and general guidelines on how to use those [suggested fields](https://docs.brightwaylca.org/intro.html#activity-data-format). It's like not wearing underwear - Brightway2 gives you the freedom to do it, but most people you are interacting with would prefer that you didn't.\n",
    "\n",
    "\\* If you are using `Activity` proxies, then the `name` field is required."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's talk a bit about the fields in ``example_data``:\n",
    "\n",
    "* `name`: This one is pretty easy :)\n",
    "* `exchanges`: This is a list of inputs and outputs, like how much energy or material is needed for this dataset's production. Every `exchange` is an intput, unless it has the value `type = \"production\"`. A `production` exchange defines *how much* of the output is produced. Most of the time, you can ignore this, as the default value is one - this is what we do in the example data. However, sometimes it is useful to define a dataset that produces more.\n",
    "\n",
    "See also: [What happens with a non-unitary production amount in LCA?](http://chris.mutel.org/non-unitary.html)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Writing database data\n",
    "\n",
    "We need to write our example data to the database."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Writing activities to SQLite3 database:\n",
      "0%  100%\n",
      "[##] | ETA[sec]: 0.000 \n",
      "Total time elapsed: 0.017 sec\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Title: Writing activities to SQLite3 database:\n",
      "  Started: 07/15/2016 11:53:39\n",
      "  Finished: 07/15/2016 11:53:39\n",
      "  Total time elapsed: 0.017 sec\n",
      "  CPU %: 114.000000\n",
      "  Memory %: 0.350535\n"
     ]
    }
   ],
   "source": [
    "db.write(example_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Get a random activity\n",
    "\n",
    "If you just need an example dataset activity, use the `.random()` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'A' (kilogram, here, ('very', 'interesting'))"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "db.random()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Examining database data\n",
    "\n",
    "We can also loop over our database, and try to get some useful information. For example, say we were interested in the number of exchanges in each activity:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('B' (microgram, there, ('quite', 'boring')), 0),\n",
       " ('A' (kilogram, here, ('very', 'interesting')), 1)]"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "num_exchanges = [(activity, len(activity.exchanges())) for activity in db]\n",
    "num_exchanges"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Searching databases"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['B' (microgram, there, ('quite', 'boring')),\n",
       " 'A' (kilogram, here, ('very', 'interesting'))]"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "db.search(\"*\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Deleting databases\n",
    "\n",
    "You delete databases by deleting them from the `databases` object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "del databases[db.name]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": []
  }
 ],
 "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.5.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}
