{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# simplelife Space Overview\n",
    "\n",
    "This notebook tutorial explains the basics of spaces, by taking a closer look at spaces defined in the simplelife model as an example.\n",
    "\n",
    "If you're viewing this page as a static HTML page on https://lifelib.io, the same contents are also available [here on binder] as Jupyter notebook executable online (it may take a while to load). To run this notebook and get all the outputs below, Go to the **Cell** menu above, and then click **Run All**.\n",
    "\n",
    "[here on binder]: https://mybinder.org/v2/gh/fumitoh/lifelib/binder?filepath=lifelib%2Fprojects%2Fsimplelife%2Fsimplelife-space-overview.ipynb"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Building a simplelife model\n",
    "\n",
    "A new simplelife model is created and returned by ``build`` function in lifelib project. Import simplelife in your working folder."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Nextime you create the same model, you can give ``load_saved`` parameter ``True``, to save time to load input data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import modelx as mx\n",
    "model = mx.read_model(\"model\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The previously created model is renamed automatically to avoid name conflict. To get all existing models, ``get_models`` modelx API function can be used. ``get_models`` returns a dict of all the existing models associated with their names."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import modelx as mx\n",
    "mx.get_models()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Access spaces in the model\n",
    "\n",
    "In the model, there are child spaces and other objects referenced in the model. ``spaces`` property holds pairs of child space names and objects as a dict-like view."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model.spaces"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To just get all the names of the spaces, use the idiomatic expression below. To get all the space objects, ``values`` method can be used instead of ``keys``.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "list(model.spaces.keys())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To get a specific space, simply type its name as model's attribute, or pass the name as a key to spaces property. For example, to get ``Projection`` space:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model.Projection"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "or"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model.spaces['Projection']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A space can in turn contain other spaces, forming a space tree. To access child spaces of a space, the ``spaces`` property and attribute access by name as we used on models can be used."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model.Projection.spaces"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model.Projection.Assumptions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model.Projection.spaces['Assumptions']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Space overview"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Below is the list of the names of the spaces in the simplelife model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "list(model.spaces.keys())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Below is a brief explanation of each space directly under the model.\n",
    "\n",
    "* ``Input``: Parent space containing spaces and cells hoding data read from the input file.\n",
    "* ``LifeTable``: Space containing cells related to commutation functions and actuarial notations.\n",
    "* ``Policy``: Parametric space whose dynamic child spaces hold attribute data of each policy read from the input file. \n",
    "* ``Assumption``: Parametric space whose dynamic child spaces hold assumptions for each policy.\n",
    "* ``Economic``: Parametric space whose dynamic child spaces hold economic assumptions for each scenario.\n",
    "* ``BaseProj``: Base space of ``Projection`` space, which contains cells to carry out projections.\n",
    "* ``PV``: Mixin space to ``Projection`` space, which contains cells to calculate present values of cashflows.\n",
    "* ``Projection``: Parametric space, whose dynamic child spaces carry out projection for each policy."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Base spaces\n",
    "\n",
    "``BaseProj`` and ``PV`` are base spaces of ``Projection``, and cells defined in those cells are copied into ``Projection`` space."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model.Projection.bases"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Parametric spaces\n",
    "\n",
    "Among the spaces listed above, parametric spaces along with their parameters are listed below.\n",
    "\n",
    "* ``LifeTable[Sex, IntRate, TableID]``\n",
    "* ``Policy[PolicyID]``\n",
    "* ``Assumption[PolicyID]``\n",
    "* ``Economic[ScenID]``\n",
    "* ``Projection[PolicyID, ScenID=1]``\n",
    "\n",
    "To check parameters of a parametric space, call its ``parameters`` property."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model.LifeTable.parameters"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A space becomes parametric when it has the ``formula`` property. By calling the ``formula`` property, the source code of the function the formula is created from is printed.\n",
    "\n",
    "The paramters of a parametric space, and their default values if any, are taken from the signature of its associated function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model.LifeTable.formula"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Parameter spaces serve as factories to create their child spaces dynamically.\n",
    "\n",
    "When a parametric space is called with specific arguments being passed to the parameters, a dynamic child space associated with the arguments is created if it's not yet created, and returned. This can be achieved either by the call operation ``()`` or by subscription ``[]`` on the parametric space. If a parameter has its default value, and the arguments to the parameter is omitted, the default value is passed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model.Projection[1]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Space formula\n",
    "\n",
    "Space formulas have 2 roles relating to dynamic element spaces.\n",
    "\n",
    "* To define the space's parameters and their default values. \n",
    "* To specify arguments used for constructing element spaces.\n",
    "\n",
    "When the user tries to access the element space of a space, such as ``model.Projection[1]``, for the first time, the formula of the space is called in order to pass a dictionary of pairs of parameters and arguments used for constructing and initializing the element space.\n",
    "\n",
    "The parameters include:\n",
    "\n",
    "* ``bases``: a list of base spaces of the element space. If not specified, the space itself becomes the direct base space of the element space. \n",
    "* ``refs``: a dictionary of references to be defined in the element space.\n",
    "\n",
    "Both of the parameters are optional.\n",
    "As we have seen in the above, space formulas are created from function definitions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model.Projection.formula"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The formula code is executed in the namespace associated with the space. Note that the global scope of the function underlying the formula has nothing to do with the formula's scope. So, names such as ``Policy``, ``Assumption``, ``Economic`` that appear in the formula above are defined in the namespace of ``model.Projection``. \n",
    "The names defined in the namespace consists of child cells, child spaces and references in the space,  \n",
    "i.e. the namespace is the union of ``cells``, ``spaces``, ``refs`` properties.\n",
    "\n",
    "``dir`` function on a space lists all the names defined in the namespace associated with the space."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dir(model.Projection)"
   ]
  }
 ],
 "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.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}