docs/advanced-usage.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Advanced usage"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This document illustrates some advance aspects of the package."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import zadeh"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Build a demo\n",
    "service = zadeh.FuzzyVariable(\n",
    "    zadeh.FloatDomain(\"service\", 0, 10, 100),\n",
    "    {\n",
    "        \"poor\": zadeh.GaussianFuzzySet(1.5, 0),\n",
    "        \"good\": zadeh.GaussianFuzzySet(1.5, 5),\n",
    "        \"excellent\": zadeh.GaussianFuzzySet(1.5, 10),\n",
    "    },\n",
    ")\n",
    "food = zadeh.FuzzyVariable(\n",
    "    zadeh.FloatDomain(\"food\", 0, 10, 100),\n",
    "    {\n",
    "        \"rancid\": zadeh.TrapezoidalFuzzySet(-2, 0, 1, 3),\n",
    "        \"delicious\": zadeh.TrapezoidalFuzzySet(7, 9, 10, 12),\n",
    "    },\n",
    ")\n",
    "tip = zadeh.FuzzyVariable(\n",
    "    zadeh.FloatDomain(\"tip\", 0, 30, 100),\n",
    "    {\n",
    "        \"cheap\": zadeh.TriangularFuzzySet(0, 5, 10),\n",
    "        \"average\": zadeh.TriangularFuzzySet(10, 15, 20),\n",
    "        \"generous\": zadeh.TriangularFuzzySet(20, 25, 30),\n",
    "    },\n",
    ")\n",
    "rule_set = [\n",
    "    ((service == \"poor\") | (food == \"rancid\")) >> (tip == \"cheap\"),\n",
    "    (service == \"good\") >> (tip == \"average\"),\n",
    "    ((service == \"excellent\") | (food == \"delicious\")) >> (tip == \"generous\"),\n",
    "]\n",
    "fis = zadeh.FIS([food, service], rule_set, tip)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Compiling models"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you have the gcc compiler available in your system, you can automatically fast, compiled versions of them. The outline of the procedure is following:\n",
    "\n",
    "- C code for the system is generated.\n",
    "- The code is compiled into a dynamic library.\n",
    "- The library is linked and interfaced in Python.\n",
    "- A FIS subclass allows its usage.\n",
    "\n",
    "To do all of this, just call the compile method of an existing FIS:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "fisc=fis.compile()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The time improvement can be checked below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "854 µs ± 57.7 µs per loop (mean ± std. dev. of 7 runs, 1000 loops each)\n"
     ]
    }
   ],
   "source": [
    "%%timeit\n",
    "fis.get_crisp_output({\"food\": 0, \"service\": 8})"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "10.4 µs ± 229 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each)\n"
     ]
    }
   ],
   "source": [
    "%%timeit\n",
    "fisc.get_crisp_output({\"food\": 0, \"service\": 8})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The difference might increase in more complex systems, so its worth considering. However, user-defined functions cannot be automatically converted into C code."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Saving and loading models"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Models can be saved and loaded using a json format"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "fis.save(\"/tmp/mymodel.zadeh\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\"variables\": [{\"name\": \"food\", \"values\": {\"rancid\": {\"type\": \"trapezoidal\", \"a\": -2.0, \"b\": 0.0, \"c\": 1.0, \"d\": 3.0}, \"delicious\": {\"type\": \"trapezoidal\", \"a\": 7.0, \"b\": 9.0, \"c\": 10.0, \"d\": 12.0}}, \"domain\": {\"type\": \"FloatDomain\", \"name\": \"food\", \"min\": 0, \"max\": 10, \"steps\": 100}}, {\"name\": \"service\", \"values\": {\"poor\": {\"type\": \"gaussian\", \"s\": 1.5, \"a\": 0}, \"good\": {\"type\": \"gaussian\", \"s\": 1.5, \"a\": 5}, \"excellent\": {\"type\": \"gaussian\", \"s\": 1.5, \"a\": 10}}, \"domain\": {\"type\": \"FloatDomain\", \"name\": \"service\", \"min\": 0, \"max\": 10, \"steps\": 100}}], \"rules\": {\"rule_list\": [{\"antecedent\": {\"type\": \"or\", \"children\": [{\"type\": \"is\", \"variable\": \"service\", \"value\": \"poor\"}, {\"type\": \"is\", \"variable\": \"food\", \"value\": \"rancid\"}]}, \"consequent\": {\"type\": \"is\", \"variable\": \"tip\", \"value\": \"cheap\"}, \"weight\": 1.0}, {\"antecedent\": {\"type\": \"is\", \"variable\": \"service\", \"value\": \"good\"}, \"consequent\": {\"type\": \"is\", \"variable\": \"tip\", \"value\": \"average\"}, \"weight\": 1.0}, {\"antecedent\": {\"type\": \"or\", \"children\": [{\"type\": \"is\", \"variable\": \"service\", \"value\": \"excellent\"}, {\"type\": \"is\", \"variable\": \"food\", \"value\": \"delicious\"}]}, \"consequent\": {\"type\": \"is\", \"variable\": \"tip\", \"value\": \"generous\"}, \"weight\": 1.0}]}, \"target\": {\"name\": \"tip\", \"values\": {\"cheap\": {\"type\": \"triangular\", \"a\": 0.0, \"b\": 5.0, \"c\": 10.0}, \"average\": {\"type\": \"triangular\", \"a\": 10.0, \"b\": 15.0, \"c\": 20.0}, \"generous\": {\"type\": \"triangular\", \"a\": 20.0, \"b\": 25.0, \"c\": 30.0}}, \"domain\": {\"type\": \"FloatDomain\", \"name\": \"tip\", \"min\": 0, \"max\": 30, \"steps\": 100}}, \"defuzzification\": \"centroid\"}"
     ]
    }
   ],
   "source": [
    "!cat /tmp/mymodel.zadeh"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "fis2=zadeh.FIS.load(\"/tmp/mymodel.zadeh\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Importing models from MATLAB files"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "MATLAB .fis models can be imported into zadeh, with limited support at the moment of writing."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "% $Revision: 1.1 $\r\n",
      "[System]\r\n",
      "Name='tipper'\r\n",
      "Type='mamdani'\r\n",
      "NumInputs=2\r\n",
      "NumOutputs=1\r\n",
      "NumRules=3\r\n",
      "AndMethod='min'\r\n",
      "OrMethod='max'\r\n",
      "ImpMethod='min'\r\n",
      "AggMethod='max'\r\n",
      "DefuzzMethod='centroid'\r\n",
      "\r\n",
      "[Input1]\r\n",
      "Name='service'\r\n",
      "Range=[0 10]\r\n",
      "NumMFs=3\r\n",
      "MF1='poor':'gaussmf',[1.5 0]\r\n",
      "MF2='good':'gaussmf',[1.5 5]\r\n",
      "MF3='excellent':'gaussmf',[1.5 10]\r\n",
      "\r\n",
      "[Input2]\r\n",
      "Name='food'\r\n",
      "Range=[0 10]\r\n",
      "NumMFs=2\r\n",
      "MF1='rancid':'trapmf',[0 0 1 3]\r\n",
      "MF2='delicious':'trapmf',[7 9 10 10]\r\n",
      "\r\n",
      "[Output1]\r\n",
      "Name='tip'\r\n",
      "Range=[0 30]\r\n",
      "NumMFs=3\r\n",
      "MF1='cheap':'trimf',[0 5 10]\r\n",
      "MF2='average':'trimf',[10 15 20]\r\n",
      "MF3='generous':'trimf',[20 25 30]\r\n",
      "\r\n",
      "[Rules]\r\n",
      "1 1, 1 (1) : 2 \r\n",
      "2 0, 2 (1) : 1 \r\n",
      "3 2, 3 (1) : 2  \r\n"
     ]
    }
   ],
   "source": [
    "!cat ../tests/data/tipper.fis"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "FuzzyRuleSet<if ((service is poor) or (food is rancid)) then (tip is cheap) [1.000000]\n",
       "if ((service is good) and (food is not delicious)) then (tip is average) [1.000000]\n",
       "if ((service is excellent) or (food is delicious)) then (tip is generous) [1.000000]>"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "fis3=zadeh.FIS.from_matlab(\"../tests/data/tipper.fis\")\n",
    "fis3.rules"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Tuning models"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Suppose you have a built a FIS and you gather some data to validate it. Could it be improved by altering the formal definitions used? You could use the data to evaluate the model with different parameters and choose the best option. The zadeh package provides a scikit-learn-based interface to do so."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>food</th>\n",
       "      <th>service</th>\n",
       "      <th>tip</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>0.0</td>\n",
       "      <td>0.000000</td>\n",
       "      <td>3.074485</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>0.0</td>\n",
       "      <td>0.204082</td>\n",
       "      <td>3.115666</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>0.0</td>\n",
       "      <td>0.408163</td>\n",
       "      <td>3.175973</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>0.0</td>\n",
       "      <td>0.612245</td>\n",
       "      <td>3.262110</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>0.0</td>\n",
       "      <td>0.816327</td>\n",
       "      <td>3.381884</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2495</th>\n",
       "      <td>10.0</td>\n",
       "      <td>9.183673</td>\n",
       "      <td>22.618116</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2496</th>\n",
       "      <td>10.0</td>\n",
       "      <td>9.387755</td>\n",
       "      <td>22.737890</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2497</th>\n",
       "      <td>10.0</td>\n",
       "      <td>9.591837</td>\n",
       "      <td>22.824027</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2498</th>\n",
       "      <td>10.0</td>\n",
       "      <td>9.795918</td>\n",
       "      <td>22.884334</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2499</th>\n",
       "      <td>10.0</td>\n",
       "      <td>10.000000</td>\n",
       "      <td>22.925515</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>2500 rows × 3 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "      food    service        tip\n",
       "0      0.0   0.000000   3.074485\n",
       "1      0.0   0.204082   3.115666\n",
       "2      0.0   0.408163   3.175973\n",
       "3      0.0   0.612245   3.262110\n",
       "4      0.0   0.816327   3.381884\n",
       "...    ...        ...        ...\n",
       "2495  10.0   9.183673  22.618116\n",
       "2496  10.0   9.387755  22.737890\n",
       "2497  10.0   9.591837  22.824027\n",
       "2498  10.0   9.795918  22.884334\n",
       "2499  10.0  10.000000  22.925515\n",
       "\n",
       "[2500 rows x 3 columns]"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Generate synthetic data to test the tuning\n",
    "# Assume the tipping model is exactly off by two units of tip\n",
    "import numpy as np\n",
    "import pandas as pd\n",
    "df = pd.DataFrame(\n",
    "    [\n",
    "        {\n",
    "            \"food\": f,\n",
    "            \"service\": s,\n",
    "            \"tip\": fis.get_crisp_output({\"food\": f, \"service\": s}) - 2.0,\n",
    "        }\n",
    "        for f in np.linspace(0, 10)\n",
    "        for s in np.linspace(0, 10)\n",
    "    ]\n",
    ")\n",
    "df"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For this constructed data, our model will overestimate the real tips. We could try to modify the definitions of the tip values to see what matches best (which should be lower values)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Grid parameter tuning\n",
    "tuner = zadeh.FuzzyGridTune(\n",
    "    fis,\n",
    "    {\n",
    "        \"target_tip_cheap_b\": [3, 5, 7],\n",
    "        \"target_tip_average_b\": [13, 15, 17],\n",
    "        \"target_tip_generous_b\": [23, 25, 27],\n",
    "    },\n",
    "    scoring=\"neg_root_mean_squared_error\",  # Equivalent to minimizing the RMSE\n",
    "    n_jobs=4,  # Parallel jobs\n",
    ")\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "tuner.fit(df)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'target_tip_average_b': 13,\n",
       " 'target_tip_cheap_b': 3,\n",
       " 'target_tip_generous_b': 23}"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# The best parameters can be checked\n",
    "tuner.best_params_"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<zadeh.fis.FIS at 0x7f90a7d2a370>"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# The tuned FIS is available\n",
    "tuner.tuned_fis_"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following table summarizes the parameter syntax:\n",
    "\n",
    "| Meaning                            | Syntax                             | Example            | Example value |\n",
    "|------------------------------------|------------------------------------|--------------------|---------------|\n",
    "| Parameter of a value of an input   | var\\_\\<variable>\\_\\<value>\\_\\<parameter> | var_food_rancid_b  | 2.0           |\n",
    "| Parameter of a value of the output | target\\_\\<name>\\_\\<value>\\_\\<parameter>  | target_tip_cheap_c | 3.0           |\n",
    "| Deffuzification method             | defuzzification                    | defuzzification    | centroid      |"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Serving models"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Created models can be served using a Flask server."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Consider the following example for model deployment"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "from zadeh import server\n",
    "fis_flask = server.FISFlask(\"myserver\", fis)\n",
    "app = fis_flask.app\n",
    "\n",
    "# This app object can be used to deploy the model\n",
    "# For example, to run a development server:\n",
    "# app.run(debug=False, host='0.0.0.0')\n",
    "# The object can be provied to middleware such as gunicorn for production deployment"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "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.8.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}