06-Multivariate-Kalman-Filters.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[Table of Contents](./table_of_contents.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Multivariate Kalman Filters\n",
    "\n",
    "Filtering Multiple Random Variables"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from __future__ import division, print_function\n",
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#format the book\n",
    "import book_format\n",
    "book_format.set_style()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Introduction"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We are now ready to study and implement the full, multivariate form of the Kalman filter. In the last chapter we learned how multivariate Gaussians express the correlation between multiple random variables, such as the position and velocity of an aircraft. We also learned how correlation between variables drastically improves the posterior. If we only roughly know position and velocity, but they are correlated, then our new estimate can be very accurate.\n",
    "\n",
    "I prefer that you develop an intuition for how these filters work through several worked examples. I'm going to gloss over many issues. Some things I show you will only work for special cases, others will be 'magical' - it will not be clear how I derived a certain result. If I started with rigorous, generalized equations you would be left scratching your head about what all these terms mean and how you might apply them to your problem. In later chapters I will provide a more rigorous mathematical foundation, and at that time I will have to either correct approximations that I made in this chapter or provide additional information that I did not cover here. \n",
    "\n",
    "To make this possible we will restrict ourselves to a subset of problems which we can describe with Newton's equations of motion. These filters are called *discretized continuous-time kinematic filters*. In the **Kalman Filter Math** chapter we will develop the math for non-Newtonian systems. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-info\">\n",
    "    <b>NOTE</b><br/>\n",
    "    <p>\n",
    "        The bicycle model could also be a good and more accurate model for certain situations\n",
    "    </p>\n",
    "    <a href=\"https://www.coursera.org/lecture/intro-self-driving-cars/lesson-2-the-kinematic-bicycle-model-Bi8yE\">https://www.coursera.org/lecture/intro-self-driving-cars/lesson-2-the-kinematic-bicycle-model-Bi8yE</a>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Newton's Equations of Motion\n",
    "\n",
    "Newton's equations of motion tells us that given a constant velocity $v$ of a system we can compute its position $x$ after time $t$ with:\n",
    "\n",
    "$$x = vt + x_0$$\n",
    "\n",
    "For example, if we start at position 13, our velocity is 10 m/s, and we travel for 12 seconds our final position is 133 ($10\\times 12 + 13$).\n",
    "\n",
    "We can incorporate constant acceleration with this equation\n",
    "\n",
    "$$x = \\frac{1}{2}at^2 + v_0t + x_0$$\n",
    "\n",
    "And if we assume constant jerk we get\n",
    "\n",
    "$$x = \\frac{1}{6}jt^3 +  \\frac{1}{2}a_0 t^2 + v_0 t + x_0$$\n",
    "\n",
    "These equations were generated by integrating a differential equation. Given a constant velocity v we can compute the distance traveled over time with the equation\n",
    "\n",
    "$$x = vt + x_0$$\n",
    "\n",
    "which we can derive with\n",
    "\n",
    "$$\\begin{aligned} v &= \\frac{dx}{dt}\\\\\n",
    "dx &= v\\, dt \\\\\n",
    "\\int_{x_0}^x\\, dx &= \\int_0^t v\\, dt\\\\\n",
    "x - x_0 &= vt - 0\\\\\n",
    "x &= vt + x_0\\end{aligned}$$\n",
    "\n",
    "\n",
    "When you design a Kalman filter you start with a system of differential equations that describe the dynamics of the system. Most systems of differential equations do not easily integrate in this way. We start with Newton's equation because we can integrate and get a closed form solution, which makes the Kalman filter easier to design. An added benefit is that Newton's equations are the right equations to use to track moving objects, one of the main uses of Kalman filters."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Kalman Filter Algorithm\n",
    "\n",
    "The algorithm is the same Bayesian filter algorithm that we have used in every chapter. The update step is slightly more complicated, but I will explain why when we get to it.\n",
    "\n",
    "**Initialization**\n",
    "\n",
    "    1. Initialize the state of the filter\n",
    "    2. Initialize our belief in the state\n",
    "    \n",
    "**Predict**\n",
    "\n",
    "    1. Use process model to predict state at the next time step\n",
    "    2. Adjust belief to account for the uncertainty in prediction    \n",
    "**Update**\n",
    "\n",
    "    1. Get a measurement and associated belief about its accuracy\n",
    "    2. Compute residual between estimated state and measurement\n",
    "    3. Compute scaling factor based on whether the measurement\n",
    "    or prediction is more accurate\n",
    "    4. set state between the prediction and measurement based \n",
    "    on scaling factor\n",
    "    5. update belief in the state based on how certain we are \n",
    "    in the measurement\n",
    "    \n",
    "As a reminder, here is a graphical depiction of the algorithm:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import kf_book.book_plots as book_plots\n",
    "book_plots.show_residual_chart()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The univariate Kalman filter represented the state with a univariate Gaussian. Naturally the multivariate Kalman filter will use a multivariate Gaussian for the state. We learned in the last chapter that multivariate Gaussians use a vector for the mean and a matrix for the covariances. That means that the Kalman filter needs to use linear algebra to perform the estimations.\n",
    "\n",
    "I don't want you to memorize these equations, but I have listed the univariate and multivariate equations below. They are quite similar.\n",
    "\n",
    "<u>**Predict**</u>\n",
    "\n",
    "$\\begin{array}{|l|l|l|}\n",
    "\\hline\n",
    "\\text{Univariate} & \\text{Univariate} & \\text{Multivariate}\\\\\n",
    "& \\text{(Kalman form)} & \\\\\n",
    "\\hline\n",
    "\\bar \\mu = \\mu + \\mu_{f_x} & \\bar x = x + dx & \\bar{\\mathbf x} = \\mathbf{Fx} + \\mathbf{Bu}\\\\\n",
    "\\bar\\sigma^2 = \\sigma_x^2 + \\sigma_{f_x}^2 & \\bar P = P + Q & \\bar{\\mathbf P} = \\mathbf{FPF}^\\mathsf T + \\mathbf Q \\\\\n",
    "\\hline\n",
    "\\end{array}$\n",
    "\n",
    "Without worrying about the specifics of the linear algebra, we can see that:\n",
    "\n",
    "$\\mathbf x,\\, \\mathbf P$ are the state mean and covariance. They correspond to $x$ and $\\sigma^2$.\n",
    "\n",
    "$\\mathbf F$ is the *state transition function*. When multiplied by $\\bf x$ it computes the prior. \n",
    "\n",
    "$\\mathbf Q$ is the process covariance. It corresponds to $\\sigma^2_{f_x}$.\n",
    "\n",
    "$\\mathbf B$ and $\\mathbf u$ are new to us. They let us model control inputs to the system.\n",
    "\n",
    "<u>**Update**</u>\n",
    "\n",
    "$\\begin{array}{|l|l|l|}\n",
    "\\hline\n",
    "\\text{Univariate} & \\text{Univariate} & \\text{Multivariate}\\\\\n",
    "& \\text{(Kalman form)} & \\\\\n",
    "\\hline\n",
    "& y = z - \\bar x & \\mathbf y = \\mathbf z - \\mathbf{H\\bar x} \\\\\n",
    "& K = \\frac{\\bar P}{\\bar P+R}&\n",
    "\\mathbf K = \\mathbf{\\bar{P}H}^\\mathsf T (\\mathbf{H\\bar{P}H}^\\mathsf T + \\mathbf R)^{-1} \\\\\n",
    "\\mu=\\frac{\\bar\\sigma^2\\, \\mu_z + \\sigma_z^2 \\, \\bar\\mu} {\\bar\\sigma^2 + \\sigma_z^2} & x = \\bar x + Ky & \\mathbf x = \\bar{\\mathbf x} + \\mathbf{Ky} \\\\\n",
    "\\sigma^2 = \\frac{\\sigma_1^2\\sigma_2^2}{\\sigma_1^2+\\sigma_2^2} & P = (1-K)\\bar P &\n",
    "\\mathbf P = (\\mathbf I - \\mathbf{KH})\\mathbf{\\bar{P}} \\\\\n",
    "\\hline\n",
    "\\end{array}$\n",
    "\n",
    "$\\mathbf H$ is the measurement function. We haven't seen this yet in this book and I'll explain it later. If you mentally remove $\\mathbf H$ from the equations, you should be able to see these equations are similar as well.\n",
    "\n",
    "$\\mathbf z,\\, \\mathbf R$ are the measurement mean and noise covariance. They correspond to $z$ and $\\sigma_z^2$ in the univariate filter (I've substituted $\\mu$ with $x$ for the univariate equations to make the notation as similar as possible).\n",
    "\n",
    "$\\mathbf y$ and $\\mathbf K$ are the residual and Kalman gain. \n",
    "\n",
    "The details will be different than the univariate filter because these are vectors and matrices, but the concepts are exactly the same: \n",
    "\n",
    "-  Use a Gaussian to represent our estimate of the state and error\n",
    "-  Use a Gaussian to represent the measurement and its error\n",
    "-  Use a Gaussian to represent the process model\n",
    "-  Use the process model to predict the next state (the prior)\n",
    "-  Form an estimate part way between the measurement and the prior\n",
    "\n",
    "Your job as a designer will be to design the state $\\left(\\mathbf x, \\mathbf P\\right)$, the process $\\left(\\mathbf F, \\mathbf Q\\right)$, the measurement $\\left(\\mathbf z, \\mathbf R\\right)$, and the  measurement function $\\mathbf H$. If the system has control inputs, such as a robot, you will also design $\\mathbf B$ and $\\mathbf u$."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "I have programmed the equations of the Kalman filter into the `predict` and `update` functions in FilterPy. You will import them with:\n",
    "\n",
    "```python\n",
    "from filterpy.kalman import predict, update\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Tracking a Dog\n",
    "\n",
    "Let's go back to our tried and true problem of tracking a dog. This time we will include the fundamental insight of the previous chapter and use *hidden variables* to improve our estimates. I could start with the math, but instead let's implement a filter, learning as we go. On the surface the math is different and perhaps more complicated than the previous chapters, but the ideas are all the same - we are just multiplying and adding Gaussians.\n",
    "\n",
    "We start by writing a simulation for the dog. The simulation will run for `count` steps, moving the dog forward approximately 1 meter for each step. At each step the velocity will vary according to the process variance `process_var`. After updating the position we compute a measurement with an assumed sensor variance of `z_var`. The function returns an NumPy array of the positions and another of the measurements."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import math\n",
    "import numpy as np\n",
    "from numpy.random import randn\n",
    "\n",
    "def compute_dog_data(z_var, process_var, count=1, dt=1.):\n",
    "    \"returns track, measurements 1D ndarrays\"\n",
    "    x, vel = 0., 1.\n",
    "    z_std = math.sqrt(z_var) \n",
    "    p_std = math.sqrt(process_var)\n",
    "    xs, zs = [], []\n",
    "    for _ in range(count):\n",
    "        v = vel + (randn() * p_std)\n",
    "        x += v*dt        \n",
    "        xs.append(x)\n",
    "        zs.append(x + randn() * z_std)        \n",
    "    return np.array(xs), np.array(zs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Predict Step\n",
    "\n",
    "For the prediction we need to design the state and covariance, the process model and the process noise, and optionally the control input. We'll take them in order."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Design State Variable (x)\n",
    "\n",
    "We previously tracked a dog in one dimension by using a Gaussian. The mean $(\\mu)$ represented the most likely position, and the variance ($\\sigma^2$) represented the probability distribution of the position. The position is the *state* of the system, and we call $\\mu$ the *state variable*. \n",
    "\n",
    "In this problem we will be tracking both the position and velocity of the dog. This requires us to use a multivariate Gaussian represented with the state vector $\\mathbf x$ and its corresponding covariance matrix $\\mathbf P$. \n",
    "\n",
    "State variables can either be *observed variables* - directly measured by a sensor, or *hidden variables* - inferred from the observed variables. For our dog tracking problem the sensor only reads position, so position is observed and velocity is hidden. We will learn how to track hidden variables soon.\n",
    "\n",
    "It is important to understand that tracking position and velocity is a design choice with implications and assumptions that we are not yet prepared to explore. For example, we could also track acceleration, or even jerk. For now, recall that in the last chapter we showed that including velocity in the covariance matrix resulted in much smaller variances in position. We will learn how the Kalman filter computes estimates for hidden variables later in this chapter. \n",
    "\n",
    "In the univariate chapter we represented the dog's position with a scalar value (e.g. $\\mu=3.27$). In the last chapter we learned to use a multivariate Gaussian for multiple variables. For example, if we wanted to specify a position of 10.0 m and a velocity of 4.5 m/s, we would write:\n",
    "\n",
    "$$\\mu = \\begin{bmatrix}10.0\\\\4.5\\end{bmatrix}$$\n",
    "\n",
    "The Kalman filter is implemented using linear algebra. We use an $n\\times 1$ matrix (called a *vector*) to store  $n$ state variables. For the dog tracking problem, we use $x$ to denote position, and the first derivative of $x$, $\\dot x$, for velocity. I use Newton's dot notation for derivatives; $\\dot x$ represents the first derivative of x with respect to t: $\\dot x = \\frac{dx}{dt}$. Kalman filter equations use $\\mathbf x$ for the state, so we define $\\mathbf x$ as:\n",
    "\n",
    "$$\\mathbf x =\\begin{bmatrix}x \\\\ \\dot x\\end{bmatrix}$$\n",
    "\n",
    "We use $\\mathbf x$ instead of $\\mu$, but recognize this is the mean of the multivariate Gaussian.\n",
    "\n",
    "Another way to write this is $\\mathbf x =\\begin{bmatrix}x & \\dot x\\end{bmatrix}^\\mathsf T$ because the transpose of a row vector is a column vector. This notation is easier to use in text because it takes less vertical space.\n",
    "\n",
    "$\\mathbf x$ and the position $x$ coincidentally have the same name. If we were tracking the dog in the y-axis we would write $\\mathbf x =\\begin{bmatrix}y & \\dot y\\end{bmatrix}^\\mathsf T$, not  $\\mathbf y =\\begin{bmatrix}y & \\dot y\\end{bmatrix}^\\mathsf T$. $\\mathbf x$ is the standard name for the state variable used in the Kalman filter literature and we will not vary it to give it a more meaningful name. This consistency in naming allows us to communicate with our peers.\n",
    "\n",
    "Let's code this. Initialization of `x` is as simple as"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = np.array([[1000.0],\n",
    "              [4.5]])\n",
    "x"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "I often use the transpose in my code to turn a row matrix into a column vector, as I find it easier to type and read:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = np.array([[10., 4.5]]).T\n",
    "x"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However, NumPy recognizes 1D arrays as vectors, so I can simplify this line to use a 1D array."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = np.array([10.0, 4.5])\n",
    "x"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All of the array elements have the same type, typically either `float` or `int`. If the list contains all `int`s then the created array will also have a data type of `int`, otherwise it will be `float`. I will often take advantage of this by only specifying one number as a floating point:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "np.array([1., 0, 0, 0, 0, 0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here are some examples."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "A = np.array([[1, 2], [3, 4]])\n",
    "x = np.array([[10.0], [4.5]])\n",
    "\n",
    "# matrix multiply\n",
    "print(np.dot(A, x))\n",
    "print()\n",
    "\n",
    "x = np.array([[10.0, 4.5]]).T\n",
    "print(np.dot(A, x))\n",
    "print()\n",
    "\n",
    "x = np.array([10.0, 4.5])\n",
    "print(np.dot(A, x))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The last returns a 1D array, but I have written the Kalman filter class to be able to handle this. In retrospect that might lead to confusion, but it does work. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Design State Covariance (P)\n",
    "\n",
    "The other half of the state Gaussian is the covariance matrix $\\mathbf P$. In the univariate Kalman filter we specified an initial value for $\\sigma^2$, and then the filter took care of updating its value as measurements were added to the filter. The same thing happens in the multidimensional Kalman filter. We specify an initial value for $\\mathbf P$ and the filter updates it during each epoch.\n",
    "\n",
    "We need to set the variances to reasonable values. For example, we may choose $\\sigma_\\mathtt{pos}^2=500 m^2$ if we are quite uncertain about the initial position. Top speed for a dog is around 21 m/s, so in the absence of any other information about the velocity we can set $3\\sigma_\\mathtt{vel}=21$, or $\\sigma_\\mathtt{vel}^2=7^2=49$. \n",
    "\n",
    "In the last chapter we showed that the position and velocities are correlated. But how correlated are they for a dog? I have no idea. As we will see the filter computes this for us, so I initialize the covariances to zero. Of course, if you know the covariances you should use them.\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "    <b>NOTE</b><br/>\n",
    "    <p>\n",
    "        The filter computes the covariances in the prediction step using the \"knowledge\" for correlation given in the F function (State transition function, see later)\n",
    "    </p>\n",
    "</div>\n",
    "\n",
    "Recall that the diagonals of the covariance matrix contains the variance of each variable, and the off-diagonal elements contains the covariances. Thus we have:\n",
    "\n",
    "$$\n",
    "\\mathbf P = \\begin{bmatrix}500 & 0 \\\\ 0&49\\end{bmatrix}\n",
    "$$\n",
    "\n",
    "We can use `numpy.diag`, which creates a diagonal matrix from the values for the diagonal. Recall from linear algebra that a diagonal matrix is one with zeros in the off-diagonal elements."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "P = np.diag([500., 49.])\n",
    "P"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "I could have written:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "P = np.array([[500., 0.],\n",
    "              [0., 49.]])\n",
    "P"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We are done. We've expressed the state of the filter as a multivariate Gaussian and implemented it in code."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "###  Design the Process Model (F)\n",
    "\n",
    "The next step is designing the *process model*. It is a mathematical model which describes the behavior of the system. The filter uses it to predict the state after a discrete time step. We do this with a set of equations that describe the dynamics of the system.\n",
    "\n",
    "In the univariate chapter we modeled the dog's motion with\n",
    "\n",
    "$$ x = v \\Delta t + x_0$$\n",
    "\n",
    "We implemented this as follows:\n",
    "\n",
    "```python\n",
    "def predict(pos, movement):\n",
    "    return gaussian(pos.mean + movement.mean, \n",
    "                    pos.var + movement.var)\n",
    "```\n",
    "\n",
    "We will do the same thing in this chapter, using multivariate Gaussians instead of univariate Gaussians. You might imagine this sort of implementation:\n",
    "\n",
    "$$ \\mathbf x = \\begin{bmatrix}5.4\\\\4.2\\end{bmatrix}, \\, \\, \n",
    "\\dot{\\mathbf x} =  \\begin{bmatrix}1.1\\\\0.\\end{bmatrix} \\\\\n",
    "\\mathbf x = \\dot{\\mathbf x}t + \\mathbf x$$\n",
    "\n",
    "But we need to generalize this. The Kalman filter equations work with any linear system, not just Newtonian ones. Maybe the system you are filtering is the plumbing system in a chemical plant, and the flow in a given pipe is determined by a linear combination of the settings of different valves. \n",
    "\n",
    "$$\\mathtt{pipe_1} = 0.134(\\mathtt{valve}_1) + 0.41(\\mathtt{valve}_2 - \\mathtt{valve}_3) + 1.34$$\n",
    "$$\\mathtt{pipe_2} = 0.210(\\mathtt{valve}_2) - 0.62(\\mathtt{valve}_1 - \\mathtt{valve}_5) + 1.86$$\n",
    "\n",
    "Linear algebra has a powerful way to express systems of equations. Take this system\n",
    "\n",
    "$$\\begin{cases}\n",
    "2x+3y=8\\\\4x-y=2\n",
    "\\end{cases}$$\n",
    "\n",
    "We can put this in matrix form by writing:\n",
    "\n",
    "$$\\begin{bmatrix}2& 3 \\\\ 4&-1\\end{bmatrix} \\begin{bmatrix}x\\\\y\\end{bmatrix} = \\begin{bmatrix}8\\\\2\\end{bmatrix}$$\n",
    "\n",
    "If you perform the [matrix multiplication](https://en.wikipedia.org/wiki/Matrix_multiplication#General_definition_of_the_matrix_product) in this equation the result will be the two equations above. In linear algebra we would write this as $\\mathbf{Ax}=\\mathbf B$, where\n",
    "\n",
    "$$\\mathbf{A} = \\begin{bmatrix}2& 3 \\\\ 4&-1\\end{bmatrix},\\, \\mathbf x = \\begin{bmatrix}x\\\\y\\end{bmatrix}, \\mathbf B=\\begin{bmatrix}8\\\\2\\end{bmatrix}$$\n",
    "\n",
    "And then we can use the SciPy's `linalg` package to solve for $\\mathbf x$:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from scipy.linalg import solve\n",
    "A = np.array([[2, 3],[4, -1]])\n",
    "b = np.array([[8], [2]])\n",
    "x = solve(A, b)\n",
    "x"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We use the process model to perform the *innovation*, because the equations tell us what the next state will be given the current state. Kalman filters implement this using this linear equation, where $\\mathbf{\\bar x}$ is the *prior*, or predicted state:\n",
    "\n",
    "$$\\mathbf{\\bar x} = \\mathbf{Fx}$$\n",
    "\n",
    "which we can make explicit as\n",
    "\n",
    "$$\\begin{bmatrix} \\bar x \\\\ \\dot{\\bar x}\\end{bmatrix} = \\begin{bmatrix}? & ? \\\\? & ?\\end{bmatrix}\\begin{bmatrix}x\\\\\\dot x\\end{bmatrix}$$\n",
    "\n",
    "Our job as Kalman filters designers is to specify $\\mathbf F$ such that $\\bar{\\mathbf x}  = \\mathbf{Fx}$ performs the innovation (prediction) for our system. To do this we need one equation for each state variable. In our problem $\\mathbf x = \\begin{bmatrix}x & \\dot x\\end{bmatrix}^\\mathtt{T}$, so we need one equation to compute the position $x$ and another to compute the velocity $\\dot x$ . We already know the equation for the position innovation:\n",
    "\n",
    "$$\\bar x = x + \\dot x \\Delta t$$\n",
    "\n",
    "What is our equation for velocity? We have no predictive model for how our dog's velocity will change over time. In this case we assume that it remains constant between innovations. Of course this is not exactly true, but so long as the velocity doesn't change too much over each innovation you will see that the filter performs very well. So we say\n",
    "\n",
    "$$\\bar{\\dot x} = \\dot x$$\n",
    "\n",
    "This gives us the process model for our system \n",
    "\n",
    "$$\\begin{cases}\n",
    "\\begin{aligned}\n",
    "\\bar x &= x + \\dot x \\Delta t \\\\\n",
    "\\bar{\\dot x} &= \\dot x\n",
    "\\end{aligned}\n",
    "\\end{cases}$$\n",
    "\n",
    "This correctly has one equation for each variable in the state, isolated on the left hand side. We need to express this set of equations in the form $\\bar{\\mathbf x}  = \\mathbf{Fx}$. Rearranging terms makes it easier to see what to do.\n",
    "\n",
    "$$\\begin{cases}\n",
    "\\begin{aligned}\n",
    "\\bar x &= 1x + &\\Delta t\\, \\dot x \\\\\n",
    "\\bar{\\dot x} &=0x + &1\\, \\dot x\n",
    "\\end{aligned}\n",
    "\\end{cases}$$\n",
    "\n",
    "We can rewrite this in matrix form as\n",
    "\n",
    "$$\\begin{aligned}\n",
    "\\begin{bmatrix}\\bar x \\\\ \\bar{\\dot x}\\end{bmatrix} &= \\begin{bmatrix}1&\\Delta t  \\\\ 0&1\\end{bmatrix}  \\begin{bmatrix}x \\\\ \\dot x\\end{bmatrix}\\\\\n",
    "\\mathbf{\\bar x} &= \\mathbf{Fx}\n",
    "\\end{aligned}$$\n",
    "\n",
    "$\\mathbf F$ is called the *state transition function* or the *state transition matrix*. In later chapters it will be a true function, not a  matrix, so calling it a function is a bit more general."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dt = 0.1\n",
    "F = np.array([[1, dt],\n",
    "              [0, 1]])\n",
    "F"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's test this! FilterPy has a `predict` method that performs the prediction by computing $\\mathbf{\\bar x} = \\mathbf{Fx}$. Let's call it and see what happens. We've set the position to 10.0 and the velocity to  4.5 meter/sec. We've defined `dt = 0.1`, which means the time step is 0.1 seconds, so we expect the new position to be 10.45 meters after the innovation. The velocity should be unchanged."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from filterpy.kalman import predict\n",
    "\n",
    "x = np.array([10.0, 4.5])\n",
    "P = np.diag([500, 49])\n",
    "F = np.array([[1, dt], [0, 1]])\n",
    "\n",
    "# Q is the process noise\n",
    "x, P = predict(x=x, P=P, F=F, Q=0)\n",
    "print('x =', x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This worked. If we call `predict()` several times in a row the value will be updated each time. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "for _ in range(4):\n",
    "    x, P = predict(x=x, P=P, F=F, Q=0)\n",
    "    print('x =', x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`predict()` computes both the mean and covariance of the innovation. This is the value of $\\mathbf P$ after five innovations (predictions), which we denote $\\mathbf{\\bar P}$ in the Kalman filter equations."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(P)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Inspecting the diagonals shows us that the position variance got larger. We've performed five prediction steps with no measurements, and our uncertainty grew. The off-diagonal elements became non-zero - the Kalman filter detected a correlation between position and velocity! The variance of the velocity did not change.\n",
    "\n",
    "Here I plot the covariance before and after the prediction. The initial value is in solid red, and the prior (prediction) is in dashed black. I've altered the covariance and time step to better illustrate the change."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "from filterpy.stats import plot_covariance_ellipse\n",
    "\n",
    "dt = 0.3\n",
    "F = np.array([[1, dt], [0, 1]])\n",
    "x = np.array([10.0, 4.5])\n",
    "P = np.diag([500, 500])\n",
    "plot_covariance_ellipse(x, P, edgecolor='r')\n",
    "x, P = predict(x, P, F, Q=0)\n",
    "plot_covariance_ellipse(x, P, edgecolor='k', ls='dashed')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can see that the center of the ellipse shifted by a small amount (from 10 to 11.35) because the position changed. The ellipse also elongated, showing the correlation between position and velocity. How does the filter compute new values for $\\mathbf{\\bar P}$, and what is it based on? Note that I set the process noise `Q` to zero each time, so it is not due to me adding noise. It's a little to early to discuss this, but recall that in every filter so far the predict step entailed a loss of information. The same is true here. I will give you the details once we have covered a bit more ground."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Design Process Noise (Q)\n",
    "\n",
    "A quick review on *process noise*. A car is driving along the road with the cruise control on; it should travel at a constant speed. We model this with $\\bar x_k=\\dot x_k\\Delta t + x_{k-1}$. However, it is affected by a number of unknown factors. The cruise control cannot perfectly maintain a constant velocity. Winds affect the car, as do hills and potholes. Passengers roll down windows, changing the drag profile of the car. \n",
    "\n",
    "We can model this system with the differential equation\n",
    "\n",
    "$$\\dot{\\mathbf x} = f(\\mathbf x) + w$$\n",
    "\n",
    "where $f(\\mathbf x)$ models the state transition and $w$ is *white process noise*.\n",
    "\n",
    "We will learn how to go from a set of differential equations to the Kalman filter matrices in the **Kalman Filter Math** chapter. In this chapter we take advantage of the fact that Newton already derived the equations of motion for us. For now you just need to know that we account for the  noise in the system by adding a process noise covariance matrix $\\mathbf Q$ to the covariance $\\mathbf P$. We do not add anything to $\\mathbf x$ because the noise is *white* - which means that the mean of the noise will be 0. If the mean is 0, $\\mathbf x$ will not change.\n",
    "\n",
    "The univariate Kalman filter used `variance = variance + process_noise` to compute the variance for the variance of the prediction step. The multivariate Kalman filter does the same, essentially `P = P + Q`. I say 'essentially' because there are other terms unrelated to noise in the covariance equation that we will see later.\n",
    "\n",
    "Deriving the process noise matrix can be quite demanding, and we will put it off until the Kalman math chapter. For now know that $\\mathbf Q$ equals the expected value of the white noise $w$, computed as $\\mathbf Q = \\mathbb E[\\mathbf{ww}^\\mathsf T]$. In this chapter we will focus on building an intuitive understanding on how modifying this matrix alters the behavior of the filter.\n",
    "\n",
    "FilterPy provides functions which compute $\\mathbf Q$ for the kinematic problems of this chapter. `Q_discrete_white_noise` takes 3 parameters. `dim`, which specifies the dimension of the matrix, `dt`, which is the time step in seconds, and `var`, the variance in the noise. Briefly, it discretizes the noise over the given time period under assumptions that we will discuss later. This code computes $\\mathbf Q$ for white noise with a variance of 2.35 and a time step of 1 seconds:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "from filterpy.common import Q_discrete_white_noise\n",
    "Q = Q_discrete_white_noise(dim=2, dt=1., var=2.35)\n",
    "print(Q)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Design the Control Function (B)\n",
    "\n",
    "The Kalman filter does not just filter data, it allows us to incorporate the control inputs of systems like robots and airplanes. Suppose we are controlling a robot. At each time step we would send steering and velocity signals to the robot based on its current position vs desired position. Kalman filter equations incorporate that knowledge into the filter equations, creating a predicted position based both on current velocity and control inputs to the drive motors. Remember, we *never* throw information away.\n",
    "\n",
    "For a linear system the effect of control inputs can be described as a set of linear equations, which we can express with linear algebra as\n",
    "\n",
    "$$\\Delta\\mathbf x = \\mathbf{Bu}$$\n",
    "\n",
    "Here $\\mathbf u$ is the *control input*, and $\\mathbf B$ is the *control input model* or *control function*. For example, $\\mathbf u$ might be a voltage controlling how fast the wheel's motor turns, and multiplying by $\\mathbf B$ yields $\\Delta[\\begin{smallmatrix}x\\\\\\dot x\\end{smallmatrix}]$. In other words, it must compute how much $\\mathbf x$ changes due to the control input.\n",
    "\n",
    "Therefore the complete Kalman filter equation for the prior mean is\n",
    "\n",
    "$$\\mathbf{\\bar x} = \\mathbf{Fx} + \\mathbf{Bu}$$\n",
    "\n",
    "and this is the equation that is computed when you call `KalmanFilter.predict()`.\n",
    "\n",
    "Your dog may be trained to respond to voice commands. All available evidence suggests that my dog has no control inputs whatsoever, so I set $\\mathbf B$ to zero. In Python we write:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "B = 0.  # my dog doesn't listen to me!\n",
    "u = 0\n",
    "x, P = predict(x, P, F, Q, B, u)\n",
    "print('x =', x)\n",
    "print('P =', P)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Setting $\\mathbf B$ and $\\mathbf u$ to zero is not necessary since `predict` uses 0 for their default value:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "predict(x, P, F, Q)[0] == predict(x, P, F, Q, B, u)[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "predict(x, P, F, Q)[1] == predict(x, P, F, Q, B, u)[1]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "#### Prediction: Summary\n",
    "\n",
    "Your job as a designer is to specify the matrices for\n",
    "\n",
    "* $\\mathbf x$, $\\mathbf P$: the state and covariance\n",
    "* $\\mathbf F$,  $\\mathbf Q$: the process model and noise covariance\n",
    "* $\\mathbf{B,u}$: Optionally, the control input and function"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Update Step\n",
    "\n",
    "Now we can implement the update step of the filter. You only have to supply two more matrices, and they are easy to understand. \n",
    "\n",
    "### Design the Measurement Function (H)\n",
    "\n",
    "The Kalman filter computes the update step in what we call *measurement space*. We mostly ignored this issue in the univariate chapter because of the complication it adds. We tracked our dog's position using a sensor that reported his position. Computing the *residual* was easy - subtract the filter's predicted position from the measurement:\n",
    "\n",
    "$$ \\mathtt{residual} = \\mathtt{measured\\, \\, position} - \\mathtt{predicted\\, \\, position}$$\n",
    "\n",
    "We need to compute the residual because we scale it by the Kalman gain to get the new estimate.\n",
    "\n",
    "What would happen if we were trying to track temperature using a thermometer that outputs a voltage corresponding to the temperature reading? The equation for the residual computation would be meaningless; you can't subtract a temperature from a voltage.\n",
    "\n",
    "$$ \\mathtt{residual} = \\mathtt{voltage} - \\mathtt{temperature}\\;\\;\\;(NONSENSE!)$$\n",
    "\n",
    "\n",
    "We need to convert the temperature into a voltage so we can perform the subtraction. For the thermometer we might write:\n",
    "\n",
    "```python\n",
    "CELSIUS_TO_VOLTS = 0.21475\n",
    "residual = voltage - (CELSIUS_TO_VOLTS * predicted_temperature)\n",
    "```\n",
    "    \n",
    "The Kalman filter generalizes this problem by having you supply a *measurement function* that converts a state into a measurement. \n",
    "\n",
    "Why are we working in measurement space? Why not work in state space by converting the voltage into a temperature, allowing the residual to be a difference in temperature?\n",
    "\n",
    "We cannot do that because most measurements are not *invertible*. The state for the tracking problem contains the hidden variable $\\dot x$. There is no way to convert a measurement of position into a state containing velocity. On the other hand, it is trivial to convert a state containing position and velocity into a equivalent \"measurement\" containing only position. We have to work in measurement space to make the computation of the residual possible.\n",
    "\n",
    "Both the measurement $\\mathbf z$ and state $\\mathbf x$ are vectors so we need to use a matrix to perform the conversion. The Kalman filter equation that performs this step is:\n",
    "\n",
    "$$\\mathbf y = \\mathbf z - \\mathbf{H \\bar x}$$\n",
    "\n",
    "where $\\mathbf y$ is the residual, $\\mathbf{\\bar x}$ is the prior, $\\mathbf z$ is the measurement, and $\\mathbf H$ is the measurement function. So we take the prior, convert it to a measurement by multiplying it with $\\mathbf H$, and subtract that from the measurement. This gives us the difference between our prediction and measurement in measurement space!\n",
    "<img src=\"./figs/residual_chart_with_h.png\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We need to design $\\mathbf H$ so that $\\mathbf{H\\bar x}$ yields a measurement. For this problem we have a sensor that measures position, so $\\mathbf z$ will be a one variable vector:\n",
    "\n",
    "$$\\mathbf z = \\begin{bmatrix}z\\end{bmatrix}$$\n",
    "\n",
    "The residual equation will have the form\n",
    "\n",
    "$$\n",
    "\\begin{aligned}\n",
    "\\textbf{y} &= \\mathbf z - \\mathbf{H\\bar x}  \\\\\n",
    "\\begin{bmatrix}y \\end{bmatrix} &= \\begin{bmatrix}z\\end{bmatrix} - \\begin{bmatrix}?&?\\end{bmatrix} \\begin{bmatrix}x \\\\ \\dot x\\end{bmatrix}\n",
    "\\end{aligned}\n",
    "$$\n",
    "\n",
    "$\\mathbf H$ has to be a 1x2 matrix for $\\mathbf{Hx}$ to be 1x1. Recall that multiplying matrices $m\\times n$ by $n\\times p$ yields a $m\\times p$ matrix.\n",
    "\n",
    "We will want to multiply the position $x$ by 1 to get the corresponding measurement of the position. We do not need to use velocity to find the corresponding measurement so we multiply  $\\dot x$ by 0.\n",
    "\n",
    "$$\\begin{aligned}\n",
    "\\textbf{y} &= \\mathbf z - \\begin{bmatrix}1&0\\end{bmatrix} \\begin{bmatrix}x \\\\ \\dot x\\end{bmatrix} \\\\\n",
    "&= [z] - [x]\n",
    "\\end{aligned}$$\n",
    "\n",
    "And so, for our Kalman filter we set\n",
    "\n",
    "$$\\mathbf H=\\begin{bmatrix}1&0\\end{bmatrix}$$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "H = np.array([[1., 0.]])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We have designed the majority of our Kalman filter. All that is left is to model the noise in the sensors."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "###  Design the Measurement (z, R)\n",
    "\n",
    "The measurement is implemented with $\\mathbf z$, the measurement mean, and $\\mathbf R$, the measurement covariance. \n",
    "\n",
    "$\\mathbf z$ is easy. it contains the measurement(s) as a vector. We have only one measurement, so we have:\n",
    "\n",
    "$$\\mathbf z = \\begin{bmatrix}z\\end{bmatrix}$$\n",
    "\n",
    "If we have two sensors or measurements we'd have:\n",
    "\n",
    "$$\\mathbf z = \\begin{bmatrix}z_1 \\\\ z_2\\end{bmatrix}$$\n",
    "\n",
    "\n",
    "The *measurement noise matrix* models the noise in our sensors as a covariance matrix. In practice this can be difficult. A complicated system may have many sensors, the correlation between them might not be clear, and usually their noise is not a pure Gaussian. For example, a sensor might be biased to read high if the temperature is high, and so the noise is not distributed equally on both sides of the mean. We will learn to deal with these problems later.\n",
    "\n",
    "The Kalman filter equations uses a covariance matrix $\\mathbf R$ for the measurement noise. The matrix will have dimension $m{\\times}m$, where $m$ is the number of sensors. It is a covariance matrix to account for correlations between the sensors. We have only 1 sensor so R is:\n",
    "\n",
    "$$R = \\begin{bmatrix}\\sigma^2_z\\end{bmatrix}$$\n",
    "\n",
    "If $\\sigma^2_z$ is 5 meters squared we'd have $R = \\begin{bmatrix}5\\end{bmatrix}$. \n",
    "\n",
    "If we had two position sensors, the first with a variance of 5 m$^2$, the second with a variance of 3 m$^2$, we would write\n",
    "\n",
    "$$R = \\begin{bmatrix}5&0\\\\0&3\\end{bmatrix}$$\n",
    "\n",
    "We put the variances on the diagonal because this is a *covariance* matrix, where the variances lie on the diagonal, and the covariances, if any, lie in the off-diagonal elements. Here we assume there is no correlation in the noise between the two sensors, so the covariances are 0.\n",
    "\n",
    "For our problem we only have one sensor, so we can implement this as"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "R = np.array([[5.]])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We perform the update by calling `update`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from filterpy.kalman import update\n",
    "z = 1.\n",
    "x, P = update(x, P, z, R, H)\n",
    "print('x =', x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Keeping track of all of these variables is burdensome, so FilterPy also implements the filter with the class `KalmanFilter`. I will use the class in the rest of this book, but I wanted you to see the procedural form of these functions since I know some of you are not fans of object oriented programming."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Implementing the Kalman Filter\n",
    "\n",
    "I've given you all of the code for the filter, but now let's collect it in one place. First we construct a `KalmanFilter` object. We have to specify the number of variables in the state with the `dim_x` parameter, and the number of measurements with `dim_z`. We have two random variables in the state and one measurement, so we write:\n",
    "\n",
    "```python\n",
    "from filterpy.kalman import KalmanFilter\n",
    "dog_filter = KalmanFilter(dim_x=2, dim_z=1)\n",
    "```\n",
    "\n",
    "This creates an object with default values for all the Kalman filter matrices:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from filterpy.kalman import KalmanFilter\n",
    "dog_filter = KalmanFilter(dim_x=2, dim_z=1)\n",
    "print('x = ', dog_filter.x.T)\n",
    "print('R = ', dog_filter.R)\n",
    "print('Q = \\n', dog_filter.Q)\n",
    "# etc..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we initialize the filter's matrices and vectors with values valid for our problem. I've put this in a function to allow you to specify different initial values for `R`, `P`, and `Q` and put it in a helper function. We will be creating and running many of these filters, and this saves us a lot of headaches."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from filterpy.kalman import KalmanFilter\n",
    "from filterpy.common import Q_discrete_white_noise\n",
    "\n",
    "def pos_vel_filter(x, P, R, Q=0., dt=1.0):\n",
    "    \"\"\" Returns a KalmanFilter which implements a\n",
    "    constant velocity model for a state [x dx].T\n",
    "    \"\"\"\n",
    "    \n",
    "    kf = KalmanFilter(dim_x=2, dim_z=1)\n",
    "    kf.x = np.array([x[0], x[1]]) # location and velocity\n",
    "    kf.F = np.array([[1., dt],\n",
    "                     [0.,  1.]])  # state transition matrix\n",
    "    kf.H = np.array([[1., 0]])    # Measurement function\n",
    "    kf.R *= R                     # measurement uncertainty\n",
    "    if np.isscalar(P):\n",
    "        kf.P *= P                 # covariance matrix \n",
    "    else:\n",
    "        kf.P[:] = P               # [:] makes deep copy\n",
    "    if np.isscalar(Q):\n",
    "        kf.Q = Q_discrete_white_noise(dim=2, dt=dt, var=Q)\n",
    "    else:\n",
    "        kf.Q[:] = Q\n",
    "    return kf"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`KalmanFilter` initializes `R`, `P`, and `Q` to the identity matrix, so `kf.P *= P` is one way to quickly assign all of the diagonal elements to the same scalar value. Now we create the filter:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dt = .1\n",
    "x = np.array([0., 0.]) \n",
    "kf = pos_vel_filter(x, P=500, R=5, Q=0.1, dt=dt)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can inspect the current values of all attributes of the filter by entering the variable on the command line."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "kf"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All that is left is to write the code to run the Kalman filter. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from kf_book.mkf_internal import plot_track\n",
    "\n",
    "def run(x0=(0.,0.), P=500, R=0, Q=0, dt=1.0, \n",
    "        track=None, zs=None,\n",
    "        count=0, do_plot=True, **kwargs):\n",
    "    \"\"\"\n",
    "    track is the actual position of the dog, zs are the \n",
    "    corresponding measurements. \n",
    "    \"\"\"\n",
    "\n",
    "    # Simulate dog if no data provided. \n",
    "    if zs is None:\n",
    "        track, zs = compute_dog_data(R, Q, count)\n",
    "\n",
    "    # create the Kalman filter\n",
    "    kf = pos_vel_filter(x0, R=R, P=P, Q=Q, dt=dt)  \n",
    "\n",
    "    # run the kalman filter and store the results\n",
    "    xs, cov = [], []\n",
    "    for z in zs:\n",
    "        kf.predict()\n",
    "        kf.update(z)\n",
    "        xs.append(kf.x)\n",
    "        cov.append(kf.P)\n",
    "\n",
    "    xs, cov = np.array(xs), np.array(cov)\n",
    "    if do_plot:\n",
    "        plot_track(xs[:, 0], track, zs, cov, \n",
    "                   dt=dt, **kwargs)\n",
    "    return xs, cov"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is the complete code for the filter, and most of it is boilerplate. I've made it flexible enough to support several uses in this chapter, so it is a bit verbose. Let's work through it line by line. \n",
    "\n",
    "The first lines checks to see if you provided it with measurement data in `data`. If not, it creates the data using the `compute_dog_data` function we wrote earlier.\n",
    "\n",
    "The next lines uses our helper function to create a Kalman filter.\n",
    "\n",
    "```python\n",
    "# create the Kalman filter\n",
    " kf = pos_vel_filter(x0, R=R, P=P, Q=Q, dt=dt)\n",
    "```\n",
    "\n",
    "All we need to do is perform the update and predict steps of the Kalman filter for each measurement. The `KalmanFilter` class provides the two methods `update()` and `predict()` for this purpose. `update()` performs the measurement update step of the Kalman filter, and so it takes a variable containing the sensor measurement. \n",
    "\n",
    "Absent the work of storing the results, the loop reads:\n",
    "\n",
    "```python\n",
    "    for z in zs:\n",
    "        kf.predict()\n",
    "        kf.update(z)\n",
    "```\n",
    "\n",
    "Each call to `predict` and `update` modifies the state variables `x` and `P`. Therefore, after the call to `predict`, `kf.x` contains the prior. After the call to update, `kf.x` contains the posterior. `data` contains the actual position and measurement of the dog, so we use `[:, 1]` to get an array of measurements.\n",
    "\n",
    "It really cannot get much simpler than that. As we tackle more complicated problems this code will remain largely the same; all of the work goes into setting up the `KalmanFilter` matrices; executing the filter is trivial.\n",
    "\n",
    "The rest of the code optionally plots the results and then returns the saved states and covariances.\n",
    "\n",
    "Let's run it. We have 50 measurements with a noise variance of 10 and a process variance of 0.01."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "P = np.diag([500., 49.])\n",
    "Ms, Ps = run(count=50, R=10, Q=0.01, P=P)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There is still a lot to learn, but we have implemented a Kalman filter using the same theory and equations as published by Rudolf Kalman! Code very much like this runs inside of your GPS, airliners, robots, and so on. \n",
    "\n",
    "The first plot plots the output of the Kalman filter against the measurements and the actual position of our dog (labelled *Track*). After the initial settling in period the filter should track the dog's position very closely. The yellow shaded portion between the black dotted lines shows 1 standard deviations of the filter's variance, which I explain in the next paragraph.\n",
    "\n",
    "The next two plots show the variance of $x$ and of $\\dot x$. I have plotted the diagonals of $\\mathbf P$ over time. Recall that the diagonal of a covariance matrix contains the variance of each state variable. So $\\mathbf P[0,0]$ is the variance of $x$, and $\\mathbf P[1,1]$ is the variance of $\\dot x$. You can see that we quickly converge to small variances for both. \n",
    "\n",
    "The covariance matrix $\\mathbf P$ tells us the *theoretical* performance of the filter *assuming* everything we tell it is true. Recall that the standard deviation is the square root of the variance, and that approximately 68% of a Gaussian distribution occurs within one standard deviation. If at least 68% of the filter output is within one standard deviation  the filter may be performing well. In the top chart I have displayed the one standard deviation as the yellow shaded area between the two dotted lines. To my eye it looks like perhaps the filter is slightly exceeding that bounds, so the filter probably needs some tuning.\n",
    "\n",
    "In the univariate chapter we filtered very noisy signals with much simpler code than the code above. However, realize that right now we are working with a very simple example - an object moving through 1-D space and one sensor. That is about the limit of what we can compute with the code in the last chapter. In contrast, we can implement very complicated, multidimensional filters with this code merely by altering our assignments to the filter's variables. Perhaps we want to track 100 dimensions in financial models. Or we have an aircraft with a GPS, INS, TACAN, radar altimeter, baro altimeter, and airspeed indicator, and we want to integrate all those sensors into a model that predicts position, velocity, and acceleration in 3D space. We can do that with the code in this chapter.\n",
    "\n",
    "I want you to get a better feel for how the Gaussians change over time, so here is a 3D plot showing the Gaussians every 7th epoch (time step). Every 7th separates them enough so can see each one independently. The first Gaussian at $t=0$ is to the left."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "from kf_book.book_plots import set_figsize, figsize\n",
    "from kf_book.nonlinear_plots import plot_gaussians\n",
    "\n",
    "P = np.diag([3., 1.])\n",
    "np.random.seed(3)\n",
    "Ms, Ps = run(count=25, R=10, Q=0.01, P=P, do_plot=False)\n",
    "with figsize(x=9, y=5):\n",
    "    plot_gaussians(Ms[::7], Ps[::7], (-5,25), (-5, 5), 75)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The Saver Class\n",
    "\n",
    "In the `run()` method I wrote boilerplate code to save the results of the filter\n",
    "```python\n",
    "    xs, cov = [], []\n",
    "    for z in zs:\n",
    "        kf.predict()\n",
    "        kf.update(z)\n",
    "        xs.append(kf.x)\n",
    "        cov.append(kf.P)\n",
    "\n",
    "    xs, cov = np.array(xs), np.array(cov)\n",
    "```\n",
    "\n",
    "There's an easy way to avoid this. `filtery.common` provides the `Saver` class which will save all attributes in the Kalman filter class each time `Saver.save()` is called. Let's see it in action and then we will talk about it more."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from filterpy.common import Saver\n",
    "kf = pos_vel_filter([0, .1], R=R, P=P, Q=Q, dt=1.) \n",
    "s = Saver(kf)\n",
    "for i in range(1, 6):\n",
    "    kf.predict()\n",
    "    kf.update([i])\n",
    "    s.save()  # save the current state"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `Saver` object now contains lists of all the attributes of the KalmanFilter object. `kf.x` is the current state estimate of the filter. Therefore `s.x` contains the saved state estimate that was computed inside the loop:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s.x"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can see all the available attributes with the `keys` attribute:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s.keys"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are many attributes there that we haven't discussed yet, but many should be familar.\n",
    "\n",
    "At this point you could write code to plot any of these variables. However, it is often more useful to use `np.array` instead of lists. Calling `Saver.to_array()` will convert the lists into `np.array`. There is one caveat: if the shape of any of the attributes changes during the run, the `to_array` will raise an exception since `np.array` requires all of the elements to be of the same type and size. \n",
    "\n",
    "If you look at the keys again you'll see that `z` is one of the choices. This is promising; apparently the measurement `z` is saved for us. Let's plot it against the estimate."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "s.to_array()\n",
    "book_plots.plot_measurements(s.z);\n",
    "plt.plot(s.x[:, 0]);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "While I've demonstrated this with the `KalmanFilter` class, it will work with all filter classes implemented by `FilterPy`. It will probably work with any class you write as well, as it inspects the object to retrieve the attribute names. We will use this class throughout the book to keep the code readable and short. Using the `Saver` will slow down your code because a lot happens behind the scenes, but for learning and exploring the convience cannot be beat."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The Kalman Filter Equations\n",
    "\n",
    "We are now ready to learn how `predict()` and `update()` perform their computations. \n",
    "\n",
    "A word about notation. I'm a programmer, and I am used to code that reads\n",
    "\n",
    "```python\n",
    "x = x + 1\n",
    "``` \n",
    "\n",
    "That is not an equation as the sides are not equal, but an *assignment*. If we wanted to write this in mathematical notation we'd write\n",
    "$$x_k = x_{k-1} + 1$$\n",
    "\n",
    "Kalman filter equations are littered with subscripts and superscripts to keep the equations mathematically consistent. I find this makes them extremely hard to read. In most of the book I opt for subscriptless assignments. As a programmer you should understand that I am showing you assignments which implement an algorithm that is to be executed step by step. I'll elaborate on this once we have a concrete example."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Prediction Equations\n",
    "\n",
    "The Kalman filter uses these equations to compute the *prior* - the predicted next state of the system. They compute the prior mean ($\\bar{\\mathbf x}$)  and covariance ($\\bar{\\mathbf P}$) of the system.\n",
    "\n",
    "$$\\begin{aligned}\n",
    "\\mathbf{\\bar x} &= \\mathbf{Fx} + \\mathbf{Bu}\\\\\n",
    "\\mathbf{\\bar P} &= \\mathbf{FPF}^\\mathsf T + \\mathbf Q\n",
    "\\end{aligned}$$\n",
    "\n",
    "$\\underline{\\textbf{Mean}}$\n",
    "\n",
    "$\\mathbf{\\bar x} = \\mathbf{Fx} + \\mathbf{Bu}$\n",
    "\n",
    "As a reminder, the linear equation $\\mathbf{Ax} = \\mathbf b$ represents a system of equations, where $\\mathbf A$ holds the coefficients set of equations, $\\mathbf x$ is the vector of variables. Performing the multiplication $\\mathbf{Ax}$ computes the right hand side values for that set of equations, represented by $\\mathbf b$.\n",
    "\n",
    "If $\\mathbf F$ contains the state transition for a given time step, then the product $\\mathbf{Fx}$ computes the state after that transition. Easy! Likewise, $\\mathbf B$ is the control function, $\\mathbf u$ is the control input, so $\\mathbf{Bu}$ computes the contribution of the controls to the state after the transition. Thus, the prior $\\mathbf{\\bar x}$ is computed as the sum of $\\mathbf{Fx}$ and $\\mathbf{Bu}$.\n",
    "\n",
    "The equivalent univariate equation is\n",
    "\n",
    "$$\\bar\\mu = \\mu + \\mu_{move}$$\n",
    "\n",
    "If you perform the matrix multiplication $\\mathbf{Fx}$ it generates this equation for $x$.\n",
    "\n",
    "Let's make this explicit. Recall the value for $\\mathbf F$ from the last chapter:\n",
    "\n",
    "$$\\mathbf F = \\begin{bmatrix}1&\\Delta t  \\\\ 0&1\\end{bmatrix}$$\n",
    "\n",
    "Thus $\\mathbf{\\bar x} = \\mathbf{Fx}$ corresponds to the set of linear equations:\n",
    "\n",
    "$$\\begin{cases}\n",
    "\\begin{aligned}\n",
    "\\bar x &= 1x + &\\Delta t\\, \\dot x \\\\\n",
    "\\bar{\\dot x} &=0x + &1\\, \\dot x\n",
    "\\end{aligned}\n",
    "\\end{cases}$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$\\underline{\\textbf{Covariance}}$\n",
    "\n",
    "$\\mathbf{\\bar P} = \\mathbf{FPF}^\\mathsf T + \\mathbf Q$\n",
    "\n",
    "This equation is not as easy to understand so we will spend more time on it. \n",
    "\n",
    "In univariate version of this equation is:\n",
    "\n",
    "$$\\bar\\sigma^2 = \\sigma^2 + \\sigma^2_{move}$$\n",
    "\n",
    "We add the variance of the movement to the variance of our estimate to reflect the loss of knowlege. We need to do the same thing here, except it isn't quite that easy with multivariate Gaussians. \n",
    "\n",
    "We can't simply write $\\mathbf{\\bar P} = \\mathbf P + \\mathbf Q$. In a multivariate Gaussians the state variables are *correlated*. What does this imply? Our knowledge of the velocity is imperfect, but we are adding it to the position with\n",
    "\n",
    "$$\\bar x = \\dot x\\Delta t + x$$\n",
    "\n",
    "Since we do not have perfect knowledge of the value of $\\dot x$ the sum $\\bar x = \\dot x\\Delta t + x$ gains uncertainty. Because the positions and velocities are correlated we cannot simply add the covariance matrices. For example, if $\\mathbf P$ and $\\mathbf Q$ are diagonal matrices the sum would also be diagonal. But we know position is correlated to velocity so the off-diagonal elements should be non-zero. \n",
    "\n",
    "The correct equation is\n",
    "\n",
    "$$\\mathbf{\\bar P} = \\mathbf{FPF}^\\mathsf T + \\mathbf Q$$\n",
    "\n",
    "Expressions in the form $\\mathbf{ABA}^\\mathsf T$ are common in linear algebra. You can think of it as *projecting* the middle term by the outer term. We will be using this many times in the rest of the book. I admit this may be a 'magical' equation to you. Let's explore it.\n",
    "\n",
    "When we initialize $\\mathbf P$ with\n",
    "\n",
    "$$\\mathbf P = \\begin{bmatrix}\\sigma^2_x & 0 \\\\ 0 & \\sigma^2_v\\end{bmatrix}$$\n",
    "\n",
    "\n",
    "the value for $\\mathbf{FPF}^\\mathsf T$ is:\n",
    "\n",
    "$$\\begin{aligned}\n",
    "\\mathbf{FPF}^\\mathsf T &= \\begin{bmatrix}1&\\Delta t\\\\0&1\\end{bmatrix}\n",
    "\\begin{bmatrix}\\sigma^2_x & 0 \\\\  0 & \\sigma^2_{v}\\end{bmatrix}\n",
    "\\begin{bmatrix}1&0\\\\\\Delta t&1\\end{bmatrix} \\\\\n",
    "&= \\begin{bmatrix}\\sigma^2_x&\\sigma_v^2\\Delta t\\\\  0 & \\sigma^2_{v}\\end{bmatrix}\n",
    "\\begin{bmatrix}1&0\\\\\\Delta t&1\\end{bmatrix} \\\\\n",
    "&= \\begin{bmatrix}\\sigma^2_x +  \\sigma_v^2\\Delta t^2  &  \\sigma_v^2\\Delta t \\\\\n",
    "\\sigma_v^2\\Delta t & \\sigma^2_{v}\\end{bmatrix}\n",
    "\\end{aligned}$$\n",
    "\n",
    "The initial value for $\\mathbf P$ had no covariance between the position and velocity.  Position is computed as $\\dot x\\Delta t + x$, so there is a correlation between the position and velocity. The multiplication $\\mathbf{FPF}^\\mathsf T$ computes a covariance of $\\sigma_v^2 \\Delta t$. The exact value is not important; you just need to recognize that $\\mathbf{FPF}^\\mathsf T$ uses the process model to automatically compute the covariance between the position and velocity!\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "    <b>NOTE</b><br/>\n",
    "    <ul>\n",
    "        <li>$\\sigma^2_x +  \\sigma_v^2\\Delta t^2$<br>The variance of the position is the previous variance plus the contribution due to the uncertainty in the velocity, which is correctly scaled by $\\Delta t^2$ </li>\n",
    "        <li>$\\sigma^2_{v}$<br>?</li>\n",
    "        <li>$\\sigma_v^2\\Delta t$<br>The varaince of the velocity is unchanged since it hasn't been updated</li>\n",
    "    </ul>\n",
    "    <b>NOTE 2</b><br/>\n",
    "    <p>\n",
    "        The covariance term that appears on the off-diagonal ($\\sigma_v^2\\Delta t$) is exactly $cov(x, \\dot x)$:\n",
    "        $$ x = x_0 + \\dot xt $$\n",
    "        $$ \\sigma_{x \\dot x} = cov(x_0 + \\dot x \\Delta t , \\dot x) = $$\n",
    "        $$ = cov(x_0, \\dot x) + cov(\\dot x \\Delta t, \\dot x) = $$\n",
    "        $$ = 0 + cov(\\dot x \\Delta t, \\dot x) = $$\n",
    "        $$ = \\Delta t \\cdot cov(\\dot x, \\dot x) = $$\n",
    "        $$ = \\Delta t \\cdot \\sigma_{\\dot x}^2 $$\n",
    "        <br>\n",
    "        $$ \\sigma_{x \\dot x} = \\Delta t \\cdot \\sigma_{\\dot x}^2 $$\n",
    "    </p>\n",
    "    <b>QUESTION</b><br/>\n",
    "    <p>\n",
    "        What happens if the off-diagonal values are non-zero (i.e. after the first iteration) ?\n",
    "    </p>\n",
    "</div>\n",
    "\n",
    "Another way to think of this is to reflect on the $\\mathbf{Fx}$ multiplication. That projected $\\mathbf x$ forward in time. $\\mathbf {FP}$ might seem to be the equivalent operation, but $\\mathbf P$ is a matrix while $\\mathbf x$ is a vector. The trailing $\\mathbf F^\\mathsf T$ term ensures that we multiply by both the rows and columns of $\\mathbf F$. In the second line of the computation of $\\mathbf{FPF}^\\mathsf T$ we have the value for $\\mathbf{FP}$. You can see that it is an upper triangular matrix because we haven't fully incorporated $\\mathbf F$ into the multiplication.\n",
    "\n",
    "If you have some experience with linear algebra and statistics, this may help. The covariance due to the prediction can be modeled as the expected value of the error in the prediction step, given by this equation. \n",
    "\n",
    "$$\\begin{aligned}\n",
    "\\bar{\\mathbf P} &= \\mathbb E[(\\mathbf{Fx})(\\mathbf{Fx})^\\mathsf T]\\\\\n",
    " &= \\mathbb E[\\mathbf{Fxx}^\\mathsf T\\mathbf F^\\mathsf T] \\\\\n",
    " &= \\mathbf F\\, \\mathbb E[\\mathbf{xx}^\\mathsf T]\\, \\mathbf F^\\mathsf T\n",
    "\\end{aligned}$$\n",
    "\n",
    "Of course, $\\mathbb E[\\mathbf{xx}^\\mathsf T]$ is just $\\mathbf P$, giving us\n",
    "\n",
    "$$\\bar{\\mathbf P} = \\mathbf{FPF}^\\mathsf T$$\n",
    "\n",
    "Let's look at its effect. Here I use $\\mathbf F$ from our filter and project the state forward 6/10ths of a second. I do this five times so you can see how $\\mathbf{\\bar P}$ continues to change. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dt = 0.6\n",
    "x = np.array([0., 5.])\n",
    "F = np.array([[1., dt], [0, 1.]])\n",
    "P = np.array([[1.5, 0], [0, 3.]])\n",
    "plot_covariance_ellipse(x, P, edgecolor='r')\n",
    "\n",
    "for _ in range(5):\n",
    "    x = np.dot(F, x)\n",
    "    P = np.dot(F, P).dot(F.T)\n",
    "    plot_covariance_ellipse(x, P, edgecolor='k', ls='dashed')\n",
    "book_plots.set_labels(x='position', y='velocity')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By looking at the ellipses above, you can notice 4 things happening:  \n",
    "1) With a velocity of 5 the position correctly moves 3 units in each 6/10ths of a second step, while the velocity stays unchanged. In other words, the center of the ellipse moves right.\n",
    "\n",
    "2) At each step the width of the ellipse increases, indicating that we have lost information about the position due to adding $\\dot x\\Delta t$ to x at each step. This causes the position variance to increase by $\\sigma_v^2 \\Delta t$, as discussed above.\n",
    "\n",
    "3) The height has not changed - our system model says the velocity does not change, so the belief we have about the velocity cannot change. \n",
    "\n",
    "4) As time continues you can see that the ellipse becomes more and more tilted. Recall that a tilt indicates *correlation*. $\\mathbf F$ linearly correlates $x$ with $\\dot x$ with the expression $\\bar x = \\dot x \\Delta t + x$. The $\\mathbf{FPF}^\\mathsf T$ computation correctly incorporates this correlation into the covariance matrix.\n",
    "\n",
    "Here is an animation of this equation that allows you to change the design of $\\mathbf F$ to see how it affects shape of $\\mathbf P$. The `F00` slider affects the value of F[0, 0]. `covar` sets the intial covariance between the position and velocity($\\sigma_x\\sigma_{\\dot x}$). I recommend answering these questions at a minimum\n",
    "\n",
    "* what if $x$ is not correlated to $\\dot x$? (set F01 to 0, the rest at defaults)\n",
    "* what if $x = 2\\dot x\\Delta t + x_0$? (set F01 to 2, the rest at defaults)\n",
    "* what if $x = \\dot x\\Delta t + 2x_0$? (set F00 to 2, the rest at defaults)\n",
    "* what if $x = \\dot x\\Delta t$?  (set F00 to 0, the rest at defaults)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "from ipywidgets import interact\n",
    "from kf_book.book_plots import IntSlider, FloatSlider\n",
    "\n",
    "def plot_FPFT(F00, F01, F10, F11, covar):   \n",
    "    plt.figure()\n",
    "    dt = 1.\n",
    "    x = np.array((0, 0.))\n",
    "    P = np.array(((1, covar), (covar, 2)))\n",
    "    F = np.array(((F00, F01), (F10, F11)))\n",
    "    plot_covariance_ellipse(x, P)\n",
    "    plot_covariance_ellipse(x, np.dot(F, P).dot(F.T), ec='r')\n",
    "    plt.gca().set_aspect('equal')\n",
    "    plt.xlim(-4, 4)\n",
    "    plt.ylim(-4, 4)\n",
    "    #plt.title(str(F))\n",
    "    plt.xlabel('position')\n",
    "    plt.ylabel('velocity')\n",
    "                 \n",
    "interact(plot_FPFT, \n",
    "         F00=IntSlider(value=1, min=0, max=2), \n",
    "         F01=FloatSlider(value=1, min=0, max=2, description='F01(dt)'),\n",
    "         F10=FloatSlider(value=0, min=0, max=2),\n",
    "         F11=FloatSlider(value=1, min=0, max=2),\n",
    "         covar=FloatSlider(value=0, min=0, max=1));"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(If you are reading this in a static form: instructions to run this online are here: https://git.io/vza7b). Or, go to binder using the link below, and open this notebook from there.\n",
    "\n",
    "http://mybinder.org/repo/rlabbe/Kalman-and-Bayesian-Filters-in-Python"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Update Equations\n",
    "\n",
    "The update equations look messier than the predict equations, but that is mostly due to the Kalman filter computing the update in measurement space. This is because measurements are not *invertible*. For example, consider a  sensor that gives the range to a target. It is impossible to convert a range into a position - an infinite number of positions in a circle will yield the same range. On the other hand, we can always compute the range (measurement) given a position (state).\n",
    "\n",
    "Before I continue, recall that we are trying to do something very simple: choose a new estimate chosen somewhere between a measurement and a prediction, as in this chart:\n",
    "<img src=\"./figs/residual_chart.png\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The equations will be complicated because the state has multiple dimensions, but this operations is what we are doing. Don't let the equations distract you from the simplicity of this idea.\n",
    "\n",
    "$\\underline{\\textbf{System Uncertainty}}$\n",
    "\n",
    "$\\textbf{S} = \\mathbf{H\\bar PH}^\\mathsf T + \\mathbf R$\n",
    "\n",
    "To work in measurement space the Kalman filter has to project the covariance matrix into measurement space. The math for this is $\\mathbf{H\\bar PH}^\\mathsf T$, where $\\mathbf{\\bar P}$ is the *prior* covariance and $\\mathbf H$ is the measurement function.\n",
    "\n",
    "\n",
    "You should recognize this $\\mathbf{ABA}^\\mathsf T$ form - the prediction step used $\\mathbf{FPF}^\\mathsf T$ to update $\\mathbf P$ with the state transition function. Here, we use the same form to update it with the measurement function. The linear algebra is changing the coordinate system for us. \n",
    "\n",
    "Once the state covariance is in measurement space we need to account for the sensor noise ($\\mathbf R$). This is very easy  - we just add matrices. The result is variously called the *system uncertainty* or *innovation covariance* and it is the covariance matrix of the residuals, in the measurement space. It is often identified with $\\mathbf S$\n",
    "\n",
    "If you ignore the $\\mathbf H$ term this equation is the equivalent to the denominator in the univariate equation for the Kalman gain:\n",
    "\n",
    "$$K = \\frac {\\bar\\sigma^2} {\\bar\\sigma^2 + \\sigma_z^2}$$\n",
    "\n",
    "Compare the equations for the system uncertainty and the covariance\n",
    "\n",
    "$$\\begin{aligned}\n",
    "\\mathbf{S} &= \\mathbf{H\\bar PH}^\\mathsf T + \\mathbf R\\\\\n",
    "\\mathbf{\\bar P} &= \\mathbf{FPF}^\\mathsf T + \\mathbf Q\n",
    "\\end{aligned}$$\n",
    "\n",
    "In each equation $\\mathbf P$ is put into a different space with either the function $\\mathbf H$ or $\\mathbf F$. Then we add the noise matrix associated with that space (measurement noise or process noise).\n",
    "\n",
    "$\\underline{\\textbf{Kalman Gain}}$\n",
    "\n",
    "$\\mathbf K = \\mathbf{\\bar PH}^\\mathsf T \\mathbf{S}^{-1}$\n",
    "\n",
    "Look back at the residual diagram. Once we have a prediction and a measurement we need to select an estimate somewhere between the two. If we have more certainty about the measurement the estimate will be closer to it. If instead we have more certainty about the prediction then the estimate will be closer to it. \n",
    "\n",
    "In the univariate chapter we scaled the mean using this equation\n",
    "\n",
    "$$\n",
    "\\mu =\\frac{\\bar\\sigma^2 \\mu_z + \\sigma_\\mathtt{z}^2 \\bar\\mu} {\\bar\\sigma^2 + \\sigma_\\mathtt{z}^2}$$\n",
    "\n",
    "which we simplified to\n",
    "\n",
    "$$\\mu = (1-K)\\bar\\mu + K\\mu_\\mathtt{z}$$\n",
    "\n",
    "which gave us\n",
    "\n",
    "$$K = \\frac {\\bar\\sigma^2} {\\bar\\sigma^2 + \\sigma_z^2}$$\n",
    "\n",
    "$K$ is the *Kalman gain*, and it is a real number between 0 and 1. Ensure you understand how it selects a mean somewhere between the prediction and measurement. The Kalman gain is a *percentage* or *ratio* - if K is .9 it takes 90% of the measurement and 10% of the prediction. \n",
    "\n",
    "For the multivariate Kalman filter $\\mathbf K$ is a vector, not a scalar. Here is the equation again: $\\mathbf K = \\mathbf{\\bar PH}^\\mathsf T \\mathbf{S}^{-1}$. Is this a *ratio*? We can think of the inverse of a matrix as linear algebra's way of finding the reciprocal. Division is not defined for matrices, but it is useful to think of it in this way. So we can read the equation for $\\textbf{K}$ as meaning\n",
    "\n",
    "$$\\begin{aligned} \\mathbf K &\\approx \\frac{\\mathbf{\\bar P}\\mathbf H^\\mathsf T}{\\mathbf{S}} \\\\\n",
    "\\mathbf K &\\approx \\frac{\\mathsf{uncertainty}_\\mathsf{prediction}}{\\mathsf{uncertainty}_\\mathsf{residual}}\\mathbf H^\\mathsf T\n",
    "\\end{aligned}$$\n",
    "\n",
    "The Kalman gain equation computes a ratio based on how much we trust the prediction vs the measurement. We did the same thing in every prior chapter. The equation is complicated because we are doing this in multiple dimensions via matrices, but the concept is simple. The $\\mathbf H^\\mathsf T$ term is less clear, I'll explain it soon. If you ignore that term the equation for the Kalman gain is the same as the univariate case: divide the uncertainty of the prior with the uncertainty of the residuals, which is the sum of the uncertainty of the prior and measurement.\n",
    "\n",
    "$\\underline{\\textbf{Residual}}$\n",
    "\n",
    "$\\mathbf y = \\mathbf z - \\mathbf{H\\bar{x}}$\n",
    "\n",
    "This is an easy one as we've covered this equation while designing the measurement function $\\mathbf H$. Recall that the measurement function converts a state into a measurement. So $\\mathbf{Hx}$ converts $\\mathbf x$ into an equivalent measurement. Once that is done, we can subtract it from the measurement $\\mathbf z$ to get the residual - the difference between the measurement and prediction.\n",
    "\n",
    "The univariate equation is\n",
    "\n",
    "$$y = z - \\bar x$$\n",
    "\n",
    "and clearly computes the same thing, but only in one dimension.\n",
    "\n",
    "$\\underline{\\textbf{State Update}}$\n",
    "\n",
    "$\\mathbf x = \\mathbf{\\bar x} + \\mathbf{Ky}$\n",
    "\n",
    "We select our new state to be along the residual, scaled by the Kalman gain. The scaling is performed by $\\mathbf{Ky}$, which both scales the residual and converts it back into state space with the $\\mathbf H^\\mathsf T$ term which is in $\\mathbf K$. This is added to the prior, yielding the equation: $\\mathbf x =\\mathbf{\\bar x} + \\mathbf{Ky}$. Let me write out $\\mathbf K$ so we can see the entire computation:\n",
    "\n",
    "$$\\begin{aligned}\n",
    "\\mathbf x &= \\mathbf{\\bar x} + \\mathbf{Ky} \\\\\n",
    "&= \\mathbf{\\bar x} + \\mathbf{\\bar PH}^\\mathsf T \\mathbf{S}^{-1}\\mathbf y \\\\\n",
    "&\\approx \\mathbf{\\bar x} + \\frac{\\mathsf{uncertainty}_\\mathsf{prediction}}{\\mathsf{uncertainty}_\\mathsf{residuals}}\\mathbf H^\\mathsf T\\mathbf y\n",
    "\\end{aligned}$$\n",
    "\n",
    "Perhaps a better way to *see* the ratio is to rewrite the estimate equation:\n",
    "\n",
    "$$\\begin{aligned}\n",
    "\\mathbf x &= \\mathbf{\\bar x} + \\mathbf{Ky} \\\\\n",
    "&= \\mathbf{\\bar x} +\\mathbf K(\\mathbf z - \\mathbf{H\\bar x}) \\\\\n",
    "&= (\\mathbf I - \\mathbf{KH})\\mathbf{\\bar x} + \\mathbf{Kz}\n",
    "\\end{aligned}$$\n",
    "\n",
    "The similarity between this and the univariate form should be obvious:\n",
    "$$\\mu = (1-K)\\bar\\mu + K\\mu_\\mathtt{z}$$\n",
    "\n",
    "$\\underline{\\textbf{Covariance Update}}$\n",
    "\n",
    "$\\mathbf P = (\\mathbf{I}-\\mathbf{KH})\\mathbf{\\bar P}$\n",
    "\n",
    "$\\mathbf{I}$ is the identity matrix, and is the way we represent $1$ in multiple dimensions. $\\mathbf H$ is our measurement function, and is a constant.  We can think of the equation as $\\mathbf P = (1-c\\mathbf K)\\mathbf P$. $\\mathbf K$ is our ratio of how much prediction vs measurement we use. If $\\mathbf K$ is large then $(1-\\mathbf{cK})$ is small, and $\\mathbf P$ will be made smaller than it was. If $\\mathbf K$ is small, then $(1-\\mathbf{cK})$ is large, and $\\mathbf P$ will be relatively larger. This means that we adjust the size of our uncertainty by some factor of the Kalman gain.\n",
    "\n",
    "This equation can be numerically unstable and I don't use it in FilterPy. The subtraction can destroy symmetry and lead to floating point errors over time. Later I'll share more complicated but numerically stable forms of this equation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### An Example not using FilterPy\n",
    "\n",
    "FilterPy hides the details of the implementation from us. Normally you will appreciate this, but let's implement the last filter without FilterPy. To do so we need to define our matrices as variables, and then implement the Kalman filter equations explicitly.\n",
    "\n",
    "Here we initialize our matrices:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dt = 1.\n",
    "R_var = 10\n",
    "Q_var = 0.01\n",
    "x = np.array([[10.0, 4.5]]).T\n",
    "P = np.diag([500, 49])\n",
    "F = np.array([[1, dt],\n",
    "              [0,  1]])\n",
    "H = np.array([[1., 0.]])\n",
    "R = np.array([[R_var]])\n",
    "Q = Q_discrete_white_noise(dim=2, dt=dt, var=Q_var)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from numpy import dot\n",
    "from scipy.linalg import inv\n",
    "\n",
    "count = 50\n",
    "track, zs = compute_dog_data(R_var, Q_var, count)\n",
    "xs, cov = [], []\n",
    "for z in zs:\n",
    "    # predict\n",
    "    x = dot(F, x)\n",
    "    P = dot(F, P).dot(F.T) + Q\n",
    "    \n",
    "    #update\n",
    "    S = dot(H, P).dot(H.T) + R\n",
    "    K = dot(P, H.T).dot(inv(S))\n",
    "    y = z - dot(H, x)\n",
    "    x += dot(K, y)\n",
    "    P = P - dot(K, H).dot(P)\n",
    "    \n",
    "    xs.append(x)\n",
    "    cov.append(P)\n",
    "\n",
    "xs, cov = np.array(xs), np.array(cov)\n",
    "plot_track(xs[:, 0], track, zs, cov, plot_P=False, dt=dt)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The results are identical to the FilterPy version. Which you prefer is up to you. I prefer not polluting my namespace with variables such as `x`, `P`, and so on; `dog_filter.x` is, to me, more readable.\n",
    "\n",
    "More importantly, this example requires you to remember and program the equations for the Kalman filter. Sooner or later you will make a mistake. FilterPy's version ensures that your code will be correct. On the other hand, if you make a mistake in your definitions, such as making $\\mathbf H$ a column vector instead of a row vector, FilterPy's error message will be harder to debug than this explicit code. \n",
    "\n",
    "FilterPy's KalmanFilter class provides additional functionality such as smoothing, batch processing, faded memory filtering, computation of the maximum likelihood function, and more. You get all of this functionality without having to explicitly program it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Summary\n",
    "\n",
    "We have learned the Kalman filter equations. Here they are all together for your review. There was a lot to learn, but I hope that as you went through each you recognized it's kinship with the equations in the univariate filter. In the *Kalman Math* chapter I will show you that if we set the dimension of $\\mathbf x$ to one that these equations revert back to the equations for the univariate filter. This is not \"like\" the univariate filter - it is a multidimensional implementation of it.\n",
    "\n",
    "$$\n",
    "\\begin{aligned}\n",
    "\\text{Predict Step}\\\\\n",
    "\\mathbf{\\bar x} &= \\mathbf{F x} + \\mathbf{B u} \\\\\n",
    "\\mathbf{\\bar P} &= \\mathbf{FP{F}}^\\mathsf T + \\mathbf Q \\\\\n",
    "\\\\\n",
    "\\text{Update Step}\\\\\n",
    "\\textbf{S} &= \\mathbf{H\\bar PH}^\\mathsf T + \\mathbf R \\\\\n",
    "\\mathbf K &= \\mathbf{\\bar PH}^\\mathsf T \\mathbf{S}^{-1} \\\\\n",
    "\\textbf{y} &= \\mathbf z - \\mathbf{H \\bar x} \\\\\n",
    "\\mathbf x &=\\mathbf{\\bar x} +\\mathbf{K\\textbf{y}} \\\\\n",
    "\\mathbf P &= (\\mathbf{I}-\\mathbf{KH})\\mathbf{\\bar P}\n",
    "\\end{aligned}\n",
    "$$\n",
    "\n",
    "I want to share a form of the equations that you will see in the literature. There are many different notation systems used, but this gives you an idea of what to expect.\n",
    "\n",
    " $$\n",
    "\\begin{aligned}\n",
    "\\hat{\\mathbf x}_{k\\mid k-1} &= \\mathbf F_k\\hat{\\mathbf x}_{k-1\\mid k-1} + \\mathbf B_k \\mathbf u_k  \\\\\n",
    "\\mathbf P_{k\\mid k-1} &=  \\mathbf F_k \\mathbf P_{k-1\\mid k-1} \\mathbf F_k^\\mathsf T + \\mathbf Q_k \\\\        \t\n",
    "\\tilde{\\mathbf y}_k &= \\mathbf z_k - \\mathbf H_k\\hat{\\mathbf x}_{k\\mid k-1}\\\\\n",
    "\\mathbf{S}_k &= \\mathbf H_k \\mathbf P_{k\\mid k-1} \\mathbf H_k^\\mathsf T + \\mathbf R_k \\\\\n",
    "\\mathbf K_k &= \\mathbf P_{k\\mid k-1}\\mathbf H_k^\\mathsf T \\mathbf{S}_k^{-1}\\\\\n",
    "\\hat{\\mathbf x}_{k\\mid k} &= \\hat{\\mathbf x}_{k\\mid k-1} + \\mathbf K_k\\tilde{\\mathbf y}_k\\\\\n",
    "\\mathbf P_{k|k} &= (I - \\mathbf K_k \\mathbf H_k) \\mathbf P_{k|k-1}\n",
    "\\\\\\end{aligned}\n",
    "$$\n",
    "\n",
    "This notation uses the Bayesian $a\\mid b$ notation, which means $a$ given the evidence of $b$. The hat means estimate. Thus $\\hat{\\mathbf x}_{k\\mid k}$ means the estimate of the state $\\mathbf x$ at step $k$ (the first k) given the evidence from step $k$ (the second k). The posterior, in other words. $\\hat{\\mathbf x}_{k\\mid k-1}$ means the estimate for the state $\\mathbf x$ at step $k$ given the estimate from step $k - 1$. The prior, in other words. \n",
    "\n",
    "This notation, copied from [Wikipedia](https://en.wikipedia.org/wiki/Kalman_filter#Details) [[1]](#[wiki_article]), allows a mathematician to express himself exactly. In formal publications presenting new results this precision is necessary. As a programmer I find it fairly unreadable. I am used to thinking about variables changing state as a program runs, and do not use a different variable name for each new computation. There is no agreed upon format in the literature, so each author makes different choices. I find it challenging to switch quickly between books and papers, and so have adopted my admittedly less precise notation. Mathematicians may write scathing emails to me, but I hope programmers and students will rejoice at my simplified notation.\n",
    "\n",
    "The **Symbology** Appendix lists the notation used by various authors. This brings up another difficulty. Different authors use different variable names. $\\mathbf x$ is fairly universal, but after that it is anybody's guess. For example, it is common to use $\\mathbf{A}$ for what I call $\\mathbf F$. You must read carefully, and hope that the author defines their variables (they often do not).\n",
    "\n",
    "If you are a programmer trying to understand a paper's equations, I suggest starting by removing all of the superscripts, subscripts, and diacriticals, replacing them with a single letter. If you work with equations like this every day this is superfluous advice, but when I read I am usually trying to understand the flow of computation. To me it is far more understandable to remember that $P$ in this step represents the updated value of $P$ computed in the last step, as opposed to trying to remember what $P_{k-1}(+)$ denotes, and what its relation to $P_k(-)$ is, if any, and how any of that relates to the completely different notation used in the paper I read 5 minutes ago."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise: Show Effect of Hidden Variables\n",
    "\n",
    "In our filter velocity is a hidden variable. How would a filter perform if we did not use velocity in the state?\n",
    "\n",
    "Write a Kalman filter that uses the state $\\mathbf x=\\begin{bmatrix}x\\end{bmatrix}$ and compare it against a filter that uses $\\mathbf x=\\begin{bmatrix}x & \\dot x\\end{bmatrix}^\\mathsf T$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# your code here"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Solution\n",
    "\n",
    "We've already implemented a Kalman filter for position and velocity, so I will provide the code without much comment, and then plot the result."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "from math import sqrt\n",
    "from numpy.random import randn\n",
    "\n",
    "def univariate_filter(x0, P, R, Q):\n",
    "    f = KalmanFilter(dim_x=1, dim_z=1, dim_u=1)\n",
    "    f.x = np.array([[x0]])\n",
    "    f.P *= P\n",
    "    f.H = np.array([[1.]])\n",
    "    f.F = np.array([[1.]])\n",
    "    f.B = np.array([[1.]])\n",
    "    f.Q *= Q\n",
    "    f.R *= R\n",
    "    return f\n",
    "\n",
    "def plot_1d_2d(xs, xs1d, xs2d):\n",
    "    plt.plot(xs1d, label='1D Filter')\n",
    "    plt.scatter(range(len(xs2d)), xs2d, c='r', alpha=0.7, label='2D Filter')\n",
    "    plt.plot(xs, ls='--', color='k', lw=1, label='track')\n",
    "    plt.title('State')\n",
    "    plt.legend(loc=4)\n",
    "    plt.show()\n",
    "    \n",
    "def compare_1D_2D(x0, P, R, Q, vel, u=0):\n",
    "    # storage for filter output\n",
    "    xs, xs1, xs2 = [], [], []\n",
    "\n",
    "    # 1d KalmanFilter\n",
    "    f1D = univariate_filter(x0, P, R, Q)\n",
    "\n",
    "    #2D Kalman filter\n",
    "    f2D = pos_vel_filter(x=(x0, vel), P=P, R=R, Q=0)\n",
    "    \n",
    "    pos = 0 # true position\n",
    "    for i in range(100):\n",
    "        pos += vel\n",
    "        xs.append(pos)\n",
    "\n",
    "        # control input u - discussed below\n",
    "        f1D.predict(u=u)\n",
    "        f2D.predict()\n",
    "        \n",
    "        z = pos + randn()*sqrt(R) # measurement\n",
    "        f1D.update(z)\n",
    "        f2D.update(z)\n",
    "        \n",
    "        xs1.append(f1D.x[0])\n",
    "        xs2.append(f2D.x[0])\n",
    "    plt.figure()\n",
    "    plot_1d_2d(xs, xs1, xs2)\n",
    "\n",
    "compare_1D_2D(x0=0, P=50., R=5., Q=.02, vel=1.) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Discussion\n",
    "\n",
    "The filter that incorporates velocity into the state produces much better estimates than the filter that only tracks position. The univariate filter has no way to estimate the velocity or change in position, so it lags the tracked object. \n",
    "\n",
    "In the univarate Kalman filter chapter we had a control input `u` to the predict equation:\n",
    "\n",
    "```python\n",
    "    def predict(self, u=0.0):\n",
    "        self.x += u\n",
    "        self.P += self.Q\n",
    "```\n",
    "\n",
    "Let's try using it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "compare_1D_2D(x0=0, P=50., R=5., Q=.02, vel=1., u=1.) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here the performance of the two filters are similar, and perhaps the univariate filter is tracking more cloesly. But let's see what happens when the actual velocity `vel` is different from the control input `u`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "compare_1D_2D(x0=0, P=50., R=5., Q=.02, vel=-2., u=1.) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we are tracking a robot which we are also controlling the univariate filter can do a very good job because the control input allows the filter to make an accurate prediction. But if we are tracking passively the control input is not much help unless we can make an accurate *apriori* guess as to the velocity. This is rarely possible."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How Velocity is Calculated\n",
    "\n",
    "I haven't explained how the filter computes the velocity, or any hidden variable. If we plug in the values we calculated for each of the filter's matrices we can see what happens.\n",
    "\n",
    "First we need to compute the system uncertainty.\n",
    "\n",
    "$$\\begin{aligned}\n",
    "\\textbf{S} &= \\mathbf{H\\bar PH}^\\mathsf T + \\mathbf R \\\\\n",
    "&= \\begin{bmatrix} 1 & 0\\end{bmatrix}\n",
    "\\begin{bmatrix}\\sigma^2_x & \\sigma_{xv} \\\\ \\sigma_{xv} & \\sigma^2_v\\end{bmatrix}\n",
    "\\begin{bmatrix} 1 \\\\ 0\\end{bmatrix} + \\begin{bmatrix}\\sigma_z^2\\end{bmatrix}\\\\\n",
    "&= \\begin{bmatrix}\\sigma_x^2 & \\sigma_{xv}\\end{bmatrix}\\begin{bmatrix} 1 \\\\ 0\\end{bmatrix}+ \\begin{bmatrix}\\sigma_z^2\\end{bmatrix} \\\\\n",
    "&= \\begin{bmatrix}\\sigma_x^2 +\\sigma_z^2\\end{bmatrix}\n",
    "\\end{aligned}$$\n",
    "\n",
    "Now that we have $\\mathbf S$ we can find the value for the Kalman gain:\n",
    "$$\\begin{aligned}\n",
    "\\mathbf K &= \\mathbf{\\bar PH}^\\mathsf T \\mathbf{S}^{-1} \\\\\n",
    "&= \\begin{bmatrix}\\sigma^2_x & \\sigma_{xv} \\\\ \\sigma_{xv} & \\sigma^2_v\\end{bmatrix}\n",
    "\\begin{bmatrix} 1 \\\\ 0\\end{bmatrix}\n",
    "\\begin{bmatrix}\\frac{1}{\\sigma_x^2 +\\sigma_z^2}\\end{bmatrix} \\\\\n",
    "&= \\begin{bmatrix}\\sigma^2_x  \\\\ \\sigma_{xv}\\end{bmatrix}\n",
    "\\begin{bmatrix}\\frac{1}{\\sigma_x^2 +\\sigma_z^2}\\end{bmatrix} \\\\\n",
    "&= \\begin{bmatrix}\\sigma^2_x/(\\sigma_x^2 +\\sigma_z^2)  \\\\ \\sigma_{xv}/(\\sigma_x^2 +\\sigma_z^2)\\end{bmatrix}\n",
    "\\end{aligned}\n",
    "$$\n",
    "\n",
    "In other words, the Kalman gain for $x$ is \n",
    "\n",
    "$$K_x = \\frac{VAR(x)}{VAR(x)+VAR(z)}$$\n",
    "\n",
    "This should be very familiar to you from the univariate case. \n",
    "\n",
    "The Kalman gain for the velocity $\\dot x$ is\n",
    "$$K_{\\dot x} = \\frac{COV(x, \\dot x)}{VAR(x)+VAR(z)}$$\n",
    "\n",
    "What is the effect of this? Recall that we compute the state as \n",
    "\n",
    "$$\\begin{aligned}\\mathbf x \n",
    "&=\\mathbf{\\bar x}+\\mathbf K(z-\\mathbf{Hx)} \\\\\n",
    "&= \\mathbf{\\bar x}+\\mathbf Ky\\end{aligned}$$\n",
    "\n",
    "Here the residual $y$ is a scalar. Therefore it is multiplied into each element of $\\mathbf K$. Therefore we have\n",
    "\n",
    "$$\\begin{bmatrix}x \\\\ \\dot x\\end{bmatrix}=\\begin{bmatrix}\\bar x \\\\ \\bar{\\dot x}\\end{bmatrix} + \\begin{bmatrix}K_x \\\\ K_{\\dot x}\\end{bmatrix}y$$\n",
    "\n",
    "Which gives this system of equations: \n",
    "\n",
    "$$\\begin{aligned}x& = \\bar x + yK_x\\\\\n",
    "\\dot x &= \\bar{\\dot x} + yK_{\\dot x}\\end{aligned}$$\n",
    "\n",
    "The prediction $\\bar x$ was computed as $x + \\bar x \\Delta t$. If the prediction was perfect then the residual will be $y=0$ (ignoring noise in the measurement) and the velocity estimate will be unchanged. On the other hand, if the velocity estimate was very bad then the prediction will be very bad, and the residual will be large: $y >> 0$. In this case we update the velocity estimate with $yK_{\\dot x}$. $K_{\\dot x}$ is proportional to $COV(x,\\dot x)$. Therefore the velocity is updated by the error in the position times the value proportional to the covariance between the position and velocity. The higher the correlation the larger the correction. \n",
    "\n",
    "To bring this full circle, $COV(x,\\dot x)$ are the off-diagonal elements of $\\mathbf P$. Recall that those values were computed with $\\mathbf{FPF}^\\mathsf T$. So the covariance of position and velocity is computed during the predict step. The Kalman gain for the velocity is proportional to this covariance, and we adjust the velocity estimate based on how inaccurate it was during the last epoch times a value proportional to this covariance. \n",
    "\n",
    "In summary, these linear algebra equations may be unfamiliar to you, but computation is actually very simple. It is essentially the same computation that we performed in the g-h filter. Our constants are different in this chapter because we take the noise in the process model and sensors into account, but the math is the same."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Adjusting the Filter\n",
    "\n",
    "Let's start varying our parameters to see the effect of various changes. This is a very normal thing to be doing with Kalman filters. It is difficult, and often impossible to exactly model our sensors. An imperfect model means imperfect output from our filter. Engineers spend a lot of time tuning Kalman filters so that they perform well with real world sensors. We will spend time now to learn the effect of these changes. As you learn the effect of each change you will develop an intuition for how to design a Kalman filter. Designing a Kalman filter is as much art as science. We are modeling a physical system using math, and models are imperfect.\n",
    "\n",
    "Let's look at the effects of the measurement noise $\\mathbf R$ and process noise $\\mathbf Q$. We will want to see the effect of different settings for $\\mathbf R$ and $\\mathbf Q$, so I have given the measurements a variance of 225 meters squared. That is very large, but it magnifies the effects of various design choices on the graphs, making it easier to recognize what is happening. Our first experiment holds $\\mathbf R$ constant while varying $\\mathbf Q$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "from numpy.random import seed\n",
    "seed(2)\n",
    "trk, zs = compute_dog_data(z_var=225, process_var=.02, count=50)\n",
    "\n",
    "run(track=trk, zs=zs, R=225, Q=200, P=P, plot_P=False, \n",
    "    title='R_var = 225 $m^2$, Q_var = 20 $m^2$')\n",
    "run(track=trk, zs=zs, R=225, Q=.02, P=P, plot_P=False, \n",
    "    title='R_var = 225 $m^2$, Q_var = 0.02 $m^2$');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The filter in the first plot should follow the noisy measurement closely. In the second plot the filter should vary from the measurement quite a bit, and be much closer to a straight line than in the first graph. Why does ${\\mathbf Q}$ affect the plots this way?\n",
    "\n",
    "Let's remind ourselves of what the term *process uncertainty* means. Consider the problem of tracking a ball. We can accurately model its behavior in a vacuum with math, but with wind, varying air density, temperature, and a spinning ball with an imperfect surface our model will diverge from reality. \n",
    "\n",
    "In the first case we set `Q_var=20 m^2`, which is quite large. In physical terms this is telling the filter \"I don't trust my motion prediction step\" as we are saying that the variance in the velocity is 20. Strictly speaking, we are telling the filter there is a lot of external noise that we are not modeling with $\\small{\\mathbf F}$, but the upshot of that is to not trust the motion prediction step. The filter will be computing velocity ($\\dot x$), but then mostly ignoring it because we are telling the filter that the computation is extremely suspect. Therefore the filter has nothing to trust but the measurements, and thus it follows the measurements closely. \n",
    "\n",
    "In the second case we set `Q_var=0.02 m^2`, which is quite small. In physical terms we are telling the filter \"trust the prediction, it is really good!\". More strictly this actually says there is very small amounts of process noise (variance 0.02 $m^2$), so the process model is very accurate. So the filter ends up ignoring some of the measurement as it jumps up and down, because the variation in the measurement does not match our trustworthy velocity prediction.\n",
    "\n",
    "Now let's set `Q_var` to $0.2\\, m^2$, and bump `R_var` up to $10,000\\, m^2$. This is telling the filter that the measurement noise is very large. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "run(track=trk, zs=zs, R=10000, Q=.2, P=P, plot_P=False, \n",
    "    title='R=$10,000\\, m^2$, Q=$.2\\, m^2$');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The effect of this can be subtle. We have created an suboptimal filter because the actual measurement noise variance is 225 $m^2$, not 10,000 $m^2$. By setting the filter's noise variance so high we force the filter to favor the prediction over the measurement. This can lead to apparently very smooth and good looking results. In the chart above the track may look extremely good to you since it follows the ideal path very closely. But, the 'great' behavior at the start should give you pause - the filter has not converged yet ($\\mathbf P$ is still large) so it should not be able to be so close to the actual position. We can see that $\\mathbf P$ has not converged because the entire chart is colored with the yellow background denoting the size of $\\mathbf P$. Let's see the result of a bad initial guess for the position by guessing the initial position to be 50 m and the initial velocity to be 1 m/s."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "run(track=trk, zs=zs, R=10000, Q=.2, P=P, plot_P=False,\n",
    "    x0=np.array([50., 1.]), \n",
    "    title='R=$10,000\\, m^2$, Q=$.2\\, m^2$');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here we can see that the filter cannot acquire the track. This happens because even though the filter is getting reasonably good measurements it assumes that the measurements are bad, and eventually predicts forward from a bad position at each step. If you think that perhaps that bad initial position would give similar results for a smaller measurement noise, let's set it back to the correct value of 225 $m^2$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "run(track=trk, zs=zs, R=225, Q=.2, P=P, plot_P=False, \n",
    "    x0=np.array([20., 1.]),\n",
    "    title='R=$225\\, m^2$, Q=$.2\\, m^2$');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here we see that the filter initially struggles for several iterations to acquire the track, but then it accurately tracks our dog. In fact, this is nearly optimum - we have not designed $\\mathbf Q$ optimally, but $\\mathbf R$ is optimal. A rule of thumb for $\\mathbf Q$ is to set it between $\\frac{1}{2}\\Delta a$ to $\\Delta a$, where $\\Delta a$ is the maximum amount that the acceleration will change between sample periods. This only applies for the assumption we are making in this chapter - that acceleration is constant and uncorrelated between each time period. In the Kalman Math chapter we will discuss several different ways of designing $\\mathbf Q$.\n",
    "\n",
    "To some extent you can get similar looking output by varying either ${\\mathbf R}$ or ${\\mathbf Q}$, but I urge you to not 'magically' alter these until you get output that you like. Always think about the physical implications of these assignments, and vary ${\\mathbf R}$ and/or ${\\mathbf Q}$ based on your knowledge of the system you are filtering. Back that up with extensive simulations and/or trial runs of real data."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## A Detailed Examination of the State Covariance Matrix\n",
    "\n",
    "Let's start by revisiting plotting a track. I've hard coded the data and noise in `zs_var_275` to avoid being at the mercy of the random number generator, which might generate data that does not illustrate what I want to talk about. I will start with `P=500`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import kf_book.mkf_internal as mkf_internal\n",
    "\n",
    "var = 27.5\n",
    "data = mkf_internal.zs_var_275()\n",
    "run(track=trk, zs=zs, R=var, Q=.02, P=500., plot_P=True, \n",
    "    title='$P=500\\, m^2$');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Looking at the output we see a very large spike in the filter output at the beginning. We set $\\text{P}=500\\, \\mathbf{I}_2$ (this is shorthand notation for a 2x2 diagonal matrix with 500 in the diagonal). We now have enough information to understand what this means, and how the Kalman filter treats it. The 500 in the upper left hand corner corresponds to $\\sigma^2_x$; therefore we are saying the standard deviation of `x` is $\\sqrt{500}$, or roughly 22.36 m. Roughly 99% of the samples occur withing $3\\sigma$, therefore $\\sigma^2_x=500$ is telling the Kalman filter that the prediction (the prior) could be up to 67 meters off. That is a large error, so when the measurement spikes the Kalman filter distrusts its own estimate and jumps wildly to try to incorporate the measurement. Then, as the filter evolves $\\mathbf P$ quickly converges to a more realistic value.\n",
    "\n",
    "Let's look at the math behind this. The equation for the Kalman gain is\n",
    "\n",
    "$$\\mathbf K = \\mathbf{\\bar P} \\mathbf H^\\mathsf T\\mathbf{S}^{-1} \\approx \\frac{\\mathbf{\\bar P}\\mathbf H^\\mathsf T}{\\mathbf{S}} \n",
    "\\approx \\frac{\\mathsf{uncertainty}_\\mathsf{prediction}}{\\mathsf{uncertainty}_\\mathsf{residuals}}\\mathbf H^\\mathsf T\n",
    "$$\n",
    "\n",
    "It is a ratio based on the uncertainty of the prediction vs measurement. Here the uncertainty in the prediction is large, so $\\mathbf K$ is large (near 1 if this was a scalar). $\\mathbf K$ is multiplied by the residual $\\textbf{y} = \\mathbf z - \\mathbf{H \\bar x}$, which is the measurement minus the prediction, so a large $\\mathbf K$ favors the measurement. Therefore if $\\mathbf P$ is large relative to the sensor uncertainty $\\mathbf R$ the filter will form most of the estimate from the measurement. \n",
    "\n",
    "\n",
    "Now let us see the effect of a smaller initial value of $\\mathbf P = 1.0\\, \\mathbf{I}_2$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "run(track=trk, zs=zs, R=var, Q=.02, P=1., plot_P=True, \n",
    "    title='$P=1\\, m^2$');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This *looks* good at first blush. The plot does not have the spike that the former plot did; the filter starts tracking the measurements and doesn't take any time to settle to the signal. However, if we look at the plots for P you can see that there is an initial spike for the variance in position, and that it never really converges back to zero. Poor design leads to a long convergence time, and suboptimal results. \n",
    "\n",
    "So despite the filter tracking very close to the actual signal we cannot conclude that the 'magic' is to use a small $\\mathbf P$. Yes, this will avoid having the Kalman filter take time to accurately track the signal, but if we are truly uncertain about the initial measurements this can cause the filter to generate very bad results. If we are tracking a living object we are probably very uncertain about where it is before we start tracking it. On the other hand, if we are filtering the output of a thermometer, we are as certain about the first measurement as the 1000th. For your Kalman filter to perform well you must set the initial value of $\\mathbf P$ to a value that truly reflects your knowledge about the data. \n",
    "\n",
    "Let's see the result of a bad initial estimate coupled with a very small $\\mathbf P$. We will set our initial estimate at x = 100 m (whereas the dog actually starts at 0m), but set `P=1` m$^2$. This is clearly an incorrect value for $\\mathbf P$ as the estimate is off by 100 m but we tell the filter that the $3\\sigma$ error is 3 m."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = np.array([100., 0.])\n",
    "run(track=trk, zs=zs, R=var, Q=.02, P=1., x0=x,\n",
    "    plot_P=False, title='$P=1\\, m^2$');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can see that the initial estimates are terrible and that it takes the filter a long time to start converging onto the signal . This is because we told the Kalman filter that we strongly believe in our initial estimate of 100 m and were incorrect in that belief.\n",
    "\n",
    "Now, let's provide a more reasonable value for `P` and see the difference."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = np.array([100., 0.])\n",
    "run(track=trk, zs=zs, R=var, Q=.02, P=500., x0=x,\n",
    "   plot_P=False, title='$P=500\\, m^2$');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this case the Kalman filter is very uncertain about the initial state, so it converges onto the signal much faster. It is producing good output after only 5 to 6 epochs. With the theory we have developed so far this is about as good as we can do. However, this scenario is a bit artificial; if we do not know where the object is when we start tracking we do not initialize the filter to some arbitrary value, such as 0 m or 100 m. I address this in the **Filter Initialization** section below.\n",
    "\n",
    "Let's do another Kalman filter for our dog, and this time plot the covariance ellipses on the same plot as the position."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "from kf_book.mkf_internal import plot_track_ellipses\n",
    "\n",
    "def plot_covariances(count, R, Q=0, P=20., title=''):    \n",
    "    track, zs = compute_dog_data(R, Q, count)\n",
    "    f = pos_vel_filter(x=(0., 0.), R=R, Q=Q, P=P)\n",
    "\n",
    "    xs, cov = [], []\n",
    "    for z in zs:\n",
    "        f.predict()\n",
    "        f.update(z)\n",
    "\n",
    "        xs.append(f.x[0])\n",
    "        cov.append(f.P)\n",
    "    plot_track_ellipses(count, zs, xs, cov, title)\n",
    "\n",
    "plt.figure(figsize=(10,6))\n",
    "plt.subplot(121)\n",
    "plot_covariances(R=5, Q=.02, count=20, title='$R = 5\\, m^2$')\n",
    "plt.subplot(122)\n",
    "plot_covariances(R=.1, Q=.02, count=20, title='$R = 0.5\\, m^2$')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you are viewing this in Jupyter Notebook or on the web, here is an animation of the filter filtering the data. I've tuned the filter parameters such that it is easy to see a change in $\\mathbf P$ as the filter progresses.\n",
    "<img src='animations/multivariate_track1.gif'>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The output on these is a bit messy, but you should be able to see what is happening. In both plots we are drawing the covariance matrix for each point. We start with the covariance $\\mathbf P=(\\begin{smallmatrix}20&0\\\\0&20\\end{smallmatrix})$, which signifies a lot of uncertainty about our initial belief. After we receive the first measurement the Kalman filter updates this belief, and so the variance is no longer as large. In the top plot the first ellipse (the one on the far left) should be a slightly squashed ellipse. As the filter continues processing the measurements the covariance ellipse quickly shifts shape until it settles down to being a long, narrow ellipse tilted in the direction of movement.\n",
    "\n",
    "Think about what this means physically. The x-axis of the ellipse denotes our uncertainty in position, and the y-axis our uncertainty in velocity. So, an ellipse that is taller than it is wide signifies that we are more uncertain about the velocity than the position. Conversely, a wide, narrow ellipse shows high uncertainty in position and low uncertainty in velocity. Finally, the amount of tilt shows the amount of correlation between the two variables. \n",
    "\n",
    "The first plot, with $R=5 m^2$, finishes up with an ellipse that is wider than it is tall. If that is not clear I have printed out the variances for the last ellipse in the lower right hand corner.\n",
    "\n",
    "In contrast, the second plot, with `R=0.5` $m^2$, has a final ellipse that is taller than wide. The ellipses in the second plot are all much smaller than the ellipses in the first plot. This stands to reason because a small $\\small\\mathbf R$ implies a small amount of noise in our measurements. Small noise means accurate predictions, and thus a strong belief in our position. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Question: Explain Ellipse Differences\n",
    "\n",
    "Why are the ellipses for $\\mathbf R=5 m^2$ more tilted towards the horizontal than the ellipses for $\\mathbf R=0.5 m^2$. Hint: think about this in the context of what these ellipses mean physically, not in terms of the math. If you aren't sure about the answer,change $\\mathbf R$ to truly large and small numbers such as 100 $m^2$ and 0.1 $m^2$, observe the changes, and think about what this means. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Solution\n",
    "\n",
    "The x-axis is for position, and y-axis is velocity. An ellipse that is vertical, or nearly so, says there is no correlation between position and velocity, and an ellipse that is diagonal says that there is a lot of correlation. Phrased that way, the results sound unlikely. The tilt of the ellipse changes, but the correlation shouldn't be changing over time. But this is a measure of the *output of the filter*, not a description of the actual, physical world. When $\\mathbf R$ is very large we are telling the filter that there is a lot of noise in the measurements. In that case the Kalman gain $\\mathbf K$ is set to favor the prediction over the measurement, and the prediction comes from the velocity state variable. Thus there is a large correlation between $x$ and $\\dot x$. Conversely, if $\\mathbf R$ is small, we are telling the filter that the measurement is very trustworthy, and $\\mathbf K$ is set to favor the measurement over the prediction. Why would the filter want to use the prediction if the measurement is nearly perfect? If the filter is not using much from the prediction there will be very little correlation reported. \n",
    "\n",
    "**This is a critical point to understand!**. The Kalman filter is a mathematical model for a real world system. A report of little correlation *does not mean* there is no correlation in the physical system, just that there was no *linear* correlation in the mathematical model. It's a report of how much measurement vs prediction was incorporated into the model.  \n",
    "\n",
    "Let's bring that point home with a truly large measurement error. We will set $\\mathbf R=200\\, m^2$. Think about what the plot will look like before looking at it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plot_covariances(R=200., Q=.2, count=5, title='$R = 200\\, m^2$')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "I hope the result was what you were expecting. The ellipse quickly became very wide and not very tall. It did this because the Kalman filter mostly used the prediction vs the measurement to produce the filtered result. We can also see how the filter output is slow to acquire the track. The Kalman filter assumes that the measurements are extremely noisy, and so it is very slow to update its estimate for $\\dot x$. \n",
    "\n",
    "Keep looking at these plots until you grasp how to interpret the covariance matrix $\\mathbf P$. When you work with a $9{\\times}9$ matrix it may seem overwhelming - there are 81 numbers to interpret. Just break it down - the diagonal contains the variance for each state variable, and all off diagonal elements are the product of two variances and a scaling factor $p$. You cannot plot a $9{\\times}9$ matrix on the screen so you have to develop your intuition and understanding in this simple, 2-D case. \n",
    "\n",
    ">When plotting covariance ellipses, make sure to always use ax.set_aspect('equal') or plt.axis('equal') in your code (the former lets you set the xlim and ylim values). If the axis use different scales the ellipses will be drawn distorted. For example, the ellipse may be drawn as being taller than it is wide, but it may actually be wider than tall."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Filter Initialization\n",
    "\n",
    "\n",
    "There are many schemes for initializing the filter. The following approach performs well in most situations. In this scheme you do not initialize the filter until you get the first measurement, $\\mathbf z_0$. From this you can compute the initial value for $\\mathbf x$ with $\\mathbf x_0 = \\mathbf z_0$. If  $\\mathbf z$ is not of the same size, type, and units as $\\mathbf x$, which is usually the case, we can use our measurement function as follow.\n",
    "\n",
    "We know\n",
    "\n",
    "$$\\mathbf z = \\mathbf{Hx}$$\n",
    "\n",
    "Hence,\n",
    "\n",
    "$$\\begin{aligned}\n",
    "\\mathbf H^{-1}\\mathbf{Hx} &= \\mathbf H^{-1}\\mathbf z \\\\\n",
    "\\mathbf x &= \\mathbf H^{-1}\\mathbf z\\end{aligned}$$\n",
    "\n",
    "Matrix inversion requires a square matrix, but $\\mathbf H$ is rarely square. SciPy will compute the Moore-Penrose pseudo-inverse of a matrix with `scipy.linalg.pinv`, so your code might look like"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from scipy.linalg import pinv\n",
    "\n",
    "H = np.array([[1, 0.]]) \n",
    "z0 = 3.2\n",
    "x = np.dot(pinv(H), z0)\n",
    "print(x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Specialized knowledge of your problem domain may lead you to a different computation, but this is one way to do it. For example, if the state includes velocity you might take the first two measurements of position, compute the difference, and use that as the initial velocity.\n",
    "\n",
    "Now we need to compute a value for $\\mathbf P$. This will vary by problem, but in general you will use the measurement error $\\mathbf R$ for identical terms, and maximum values for the rest of the terms. Maybe that isn't clear. In this chapter we have been tracking and object using position and velocity as the state, and the measurements have been positions. In that case we would initialize $\\mathbf P$ with\n",
    "\n",
    "$$\\mathbf P = \\begin{bmatrix}\\mathbf R_0 & 0 \\\\0 & vel_{max}^2\\end{bmatrix}$$\n",
    "\n",
    "The diagonal of $\\mathbf P$ contains the variance of each state variable, so we populate it with reasonable values. $\\mathbf R$ is a reasonable variance for the position, and the maximum velocity squared is a reasonable variance for the velocity. It is squared because variance is squared: $\\sigma^2$.\n",
    "\n",
    "You really need to understand the domain in which you are working and initialize your filter on the best available information. For example, suppose we were trying to track horses in a horse race. The initial measurements might be very bad, and provide you with a position far from the starting gate. We know that the horse must start at the starting gate; initializing the filter to the initial measurement would lead to suboptimal results. In this scenario we would want to always initialize the Kalman filter with the starting gate position of the horse."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Batch Processing\n",
    "\n",
    "The Kalman filter is designed as a recursive algorithm - as new measurements come in we immediately create a new estimate. But it is very common to have a set of data that have been already collected which we want to filter. Kalman filters can be run in a batch mode, where all of the measurements are filtered at once. We have implemented this in `KalmanFilter.batch_filter()`. Internally, all the function does is loop over the measurements and collect the resulting state and covariance estimates in arrays. It simplifies your logic and conveniently gathers all of the outputs into arrays. I often use this function, but waited until the end of the chapter so you would become very familiar with the predict/update cyle that you must run.\n",
    "\n",
    "First collect your measurements into an array or list. Maybe it is in a CSV file:\n",
    "\n",
    "```python\n",
    "zs = read_altitude_from_csv('altitude_data.csv')\n",
    "```\n",
    "\n",
    "Or maybe you will generate it using a generator:\n",
    "\n",
    "```python\n",
    "zs = [some_func(i) for i in range(1000)]\n",
    "```\n",
    "\n",
    "Then call the `batch_filter()` method.\n",
    "\n",
    "```python\n",
    "Xs, Ps, Xs_prior, Ps_prior = kfilter.batch_filter(zs)\n",
    "```\n",
    "\n",
    "The function takes the list of measurements, filters it, and returns an  NumPy array of state estimates (Xs), covariance matrices (Ps), and the priors for the same (Xs_prior, Ps_prior).\n",
    "\n",
    "Here is a complete example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "count = 50\n",
    "track, zs = compute_dog_data(10, .2, count)\n",
    "P = np.diag([500., 49.])\n",
    "f = pos_vel_filter(x=(0., 0.), R=3., Q=.02, P=P)\n",
    "xs, _, _, _ = f.batch_filter(zs)\n",
    "\n",
    "book_plots.plot_measurements(range(1, count + 1), zs)\n",
    "book_plots.plot_filter(range(1, count + 1), xs[:, 0])\n",
    "plt.legend(loc='best');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The batch filter takes an optional `filterpy.common.Saver` object. If provided, all of the filter's attributes will be saved as well. This is useful if you want to inspect values other than the state and covariance. Here I plot the residual to see if it appears like noise centered around 0. This is a quick visual inspection to see if the filter is well designed. If if drifts from zero, or doesn't look like noise, the filter is poorly designed and/or the processes are not Gaussian. We will discuss this in detail in later chapters. For now consider this a demonstration of the `Saver` class."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "track, zs = compute_dog_data(10, .2, 200)\n",
    "P = np.diag([500., 49.])\n",
    "f = pos_vel_filter(x=(0., 0.), R=3., Q=.02, P=P)\n",
    "s = Saver(f)\n",
    "xs, _, _, _ = f.batch_filter(zs, saver=s)\n",
    "s.to_array()\n",
    "plt.plot(s.y);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Smoothing the Results\n",
    "\n",
    "This book includes a chapter on smoothing the results; I will not repeat the information here. However, it is so easy to use, and offers such a profoundly improved output that I will tease you with a few examples. The smoothing chapter is not especially difficult; you are sufficiently prepared to read it now.\n",
    "\n",
    "Let's assume that we are tracking a car that has been traveling in a straight line. We get a measurement that implies that the car is starting to turn to the left. The Kalman filter moves the state estimate somewhat towards the measurement, but it cannot judge whether this is a particularly noisy measurement or the true start of a turn. \n",
    "\n",
    "However, if we have future measurements we can decide if a turn was made. Suppose the subsequent measurements all continue turning left. We can then be sure that that a turn was initiated. On the other hand, if the subsequent measurements continued on in a straight line we would know that the measurement was noisy and should be mostly ignored. Instead of making an estimate part way between the measurement and prediction the estimate will either fully incorporate the measurement or ignore it, depending on what the future measurements imply about the object's movement.\n",
    "\n",
    "`KalmanFilter` implements a form of this algorithm which is called an *RTS smoother*, named after the inventors of the algorithm: Rauch, Tung, and Striebel. The method is `rts_smoother()`. To use it pass in the means and covariances computed from the `batch_filter` step, and receive back the smoothed means, covariances, and Kalman gain. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from numpy.random import seed\n",
    "count = 50\n",
    "seed(8923)\n",
    "\n",
    "P = np.diag([500., 49.])\n",
    "f = pos_vel_filter(x=(0., 0.), R=3., Q=.02, P=P)\n",
    "track, zs = compute_dog_data(3., .02, count)\n",
    "Xs, Covs, _, _ = f.batch_filter(zs)\n",
    "Ms, Ps, _, _ = f.rts_smoother(Xs, Covs)\n",
    "\n",
    "book_plots.plot_measurements(zs)\n",
    "plt.plot(Xs[:, 0], ls='--', label='Kalman Position')\n",
    "plt.plot(Ms[:, 0], label='RTS Position')\n",
    "plt.legend(loc=4);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This output is fantastic! Two things are very apparent to me in this chart. First, the RTS smoother's output is much smoother than the KF output. Second, it is almost always more accurate than the KF output (we will examine this claim in detail in the **Smoothing** chapter). The improvement in the velocity, which is a hidden variable, is even more dramatic:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.plot(xs[:, 1], ls='--', label='Kalman Velocity')\n",
    "plt.plot(Ms[:, 1], label='RTS Velocity')\n",
    "plt.legend(loc=4)\n",
    "plt.gca().axhline(1, lw=1, c='k');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will explore why this is so in the next exercise."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise: Compare Velocities\n",
    "\n",
    "Since we are plotting velocities let's look at what the 'raw' velocity is, which we can compute by subtracting subsequent measurements. i.e the velocity at time 1 can be approximated by `xs[1] - xs[0]`. Plot the raw value against the values estimated by the Kalman filter and by the RTS filter. Discuss what you see."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# your code here"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Solution"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dx = np.diff(xs[:, 0], axis=0)\n",
    "plt.scatter(range(1, len(dx) + 1), dx, facecolor='none', \n",
    "            edgecolor='k', lw=2, label='Raw velocity')\n",
    "plt.plot(xs[:, 1], ls='--', label='Filter')\n",
    "plt.plot(Ms[:, 1], label='RTS')\n",
    "plt.xlim(0, 60)\n",
    "plt.legend(loc=4);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We see that the noise swamps the signal, causing the raw values to be essentially worthless. The filter is maintaining a separate estimate for velocity. The Kalman gain $\\mathbf K$ is multidimensional. For example, it might have the value  $\\mathbf K = [0.1274, 0.843]^\\mathsf T$. the first value is used to scale the residual of the position, and the second value will scale the residual of the velocity. The covariance matrix tells the filter how correlated the position and velocity are, and each will be optimally filtered. \n",
    "\n",
    "I show this to reiterate the importance of using Kalman filters to compute velocities, accelerations, and even higher order values. I use a Kalman filter even when my measurements are so accurate that I am willing to use them unfiltered because it allows me accurate estimates for velocities and accelerations."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Discussion and Summary\n",
    "\n",
    "Multivariate Gaussians allow us to simultaneously handle multiple dimensions, both spacial and others (velocity, etc). We made a key insight: hidden variables have the ability to significantly increase the accuracy of the filter. This is possible because the hidden variables are correlated with the observed variables. \n",
    "\n",
    "I gave an intuitive definition of *observability*. Observability was invented by Dr. Kalman for linear systems, and there is a fair amount of theory behind it. It answers the question of whether a system state can be determined by observing the system's output. For our problems this has been easy to determine, but more complicated systems may require rigorous analysis. Wikipedia's [Observability](https://en.wikipedia.org/wiki/Observability) article has an overview; if you need to learn the topic [[Grewal2008]](#References) is a good source. \n",
    "\n",
    "There is one important caveat about hidden variables. It is easy to construct a filter that produces estimates for hidden variables. I could write a filter that estimates the color of a tracked car. But there is no way to compute car color from positions, so the estimate for the color will be nonsense. The designer must verify that these variables are being estimated correctly. If you do not have a velocity sensor and yet are estimating velocity, you will need to test that the velocity estimates are correct.; do not trust that they are. For example, suppose the velocity has a periodic component to it - it looks like a sine wave. If your sample time is less than 2 times the frequency you will not be able to accurately estimate the velocity (due to Nyquist's Theorem). Imagine that the sample period is equal to the frequency of the velocity. The filter will report that the velocity is constant because it samples the system at the same point on the sin wave. \n",
    "\n",
    "Initialization poses a particularly difficult problem for hidden variables. If you start with a bad initialization the filter can usually recover the observed variables, but may struggle and fail with the hidden one. Estimating hidden variables is a powerful tool, but a dangerous one. \n",
    "\n",
    "I established a series of steps for designing a Kalman filter. These are not a usual part of the Kalman filter literature, and are only meant as a guide, not a prescription. Designing for a hard problem is an iterative process. You make a guess at the state vector, work out what your measurement and state models are, run some tests, and then alter the design as necessary. \n",
    "\n",
    "The design of $\\mathbf R$ and $\\mathbf Q$ is often quite challenging. I've made it appear to be quite scientific. Your sensor has Gaussian noise of $\\mathcal{N}(0, \\sigma^2)$, so set $\\mathbf R=\\sigma^2$. Easy! This is a dirty lie. Sensors are not Gaussian. We started the book with a bathroom scale. Suppose $\\sigma=1$ kg, and you try to weigh something that weighs 0.5 kg. Theory tells us we will get negative measurements, but of course the scale will never report weights less than zero. Real world sensors typically have *fat tails* (known as *kurtosis*) and *skew*. In some cases, such as with the scale, one or both tails are truncated.\n",
    "\n",
    "The case with $\\mathbf Q$ is more dire. I hope you were skeptical when I blithely assigned a noise matrix to my prediction about the movements of a dog. Who can say what a dog will do next? The Kalman filter in my GPS doesn't know about hills, the outside winds, or my terrible driving skills. Yet the filter requires a precise number to encapsulate all of that information, and it needs to work while I drive off-road in the desert, and when a Formula One champion drives on a track.\n",
    "\n",
    "These problems led some researchers and engineers to derogatorily call the Kalman filter a 'ball of mud'. In other words, it doesn't always hold together so well. Another term to know - Kalman filters can become *smug*. Their estimates are based solely on what you tell it the noises are. Those values can lead to overly confident estimates. $\\mathbf P$ gets smaller and smaller while the filter is actually becoming more and more inaccurate! In the worst case the filter diverges. We will see a lot of that when we start studying nonlinear filters. \n",
    "\n",
    "The Kalman filter is a mathematical model of the world. The output is only as accurate as that model. To make the math tractable we had to make some assumptions. We assume that the sensors and motion model have Gaussian noise. We assume that everything is linear. If that is true, the Kalman filter is *optimal* in a least squares sense. This means that there is no way to make a better estimate than what the filter gives us. However, these assumption are almost never true, and hence the model is necessarily limited, and a working filter is rarely optimal.\n",
    "\n",
    "In later chapters we will deal with the problem of nonlinearity. For now I want you to understand that designing the matrices of a linear filter is an experimental procedure more than a mathematical one. Use math to establish the initial values, but then you need to experiment. If there is a lot of unaccounted noise in the world (wind, etc.) you may have to make $\\mathbf Q$ larger. If you make it too large the filter fails to respond quickly to changes. In the **Adaptive Filters** chapter you will learn some alternative techniques that allow you to change the filter design in real time in response to the inputs and performance, but for now you need to find one set of values that works for the conditions your filter will encounter. Noise matrices for an acrobatic plane might be different if the pilot is a student than if the pilot is an expert as the dynamics will be quite different."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## References"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- <A name=\"[wiki_article]\">[1]</A> 'Kalman Filters'. Wikipedia\n",
    "https://en.wikipedia.org/wiki/Kalman_filter#Details\n",
    "\n",
    "* **[Grewal2008]** Grewal, Mohinder S., Andrews, Angus P. *Kalman Filtering: Theory and Practice Using MATLAB*. Third Edition. John Wiley & Sons. 2008."
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "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.3"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {
     "048d0de3675e47d891a02b4af859bbff": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "1.1.0",
      "model_name": "SliderStyleModel",
      "state": {
       "description_width": ""
      }
     },
     "0a8de965b22747098945664eeb9be73a": {
      "model_module": "@jupyter-widgets/base",
      "model_module_version": "1.0.0",
      "model_name": "LayoutModel",
      "state": {}
     },
     "0d005590353d40ad96a4e4c992ea28c0": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "1.1.0",
      "model_name": "SliderStyleModel",
      "state": {
       "description_width": ""
      }
     },
     "10595c1e709d40ebaf2f3c0b6501de30": {
      "model_module": "@jupyter-widgets/base",
      "model_module_version": "1.0.0",
      "model_name": "LayoutModel",
      "state": {}
     },
     "1ab24477f22349dcbec607799e29d07a": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "1.1.0",
      "model_name": "FloatSliderModel",
      "state": {
       "continuous_update": false,
       "description": "F10",
       "layout": "IPY_MODEL_ea1ae5b02f1b46c6ab7142ef8fd4e991",
       "max": 2,
       "step": 0.1,
       "style": "IPY_MODEL_b8b3a691d03d4f2dbabefc9ea9529d00"
      }
     },
     "1adb400d9d5e4ba7b379a0c942ce4ba3": {
      "model_module": "@jupyter-widgets/base",
      "model_module_version": "1.0.0",
      "model_name": "LayoutModel",
      "state": {}
     },
     "353562a0c2fb4990a948c7b13c874de7": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "1.1.0",
      "model_name": "FloatSliderModel",
      "state": {
       "continuous_update": false,
       "description": "F01(dt)",
       "layout": "IPY_MODEL_0a8de965b22747098945664eeb9be73a",
       "max": 2,
       "step": 0.1,
       "style": "IPY_MODEL_af84bbe3e56744deb318d6a9b6634ce5",
       "value": 1
      }
     },
     "3b2727f48017422886e76ef88a8a9e29": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "1.1.0",
      "model_name": "SliderStyleModel",
      "state": {
       "description_width": ""
      }
     },
     "3c2536f1fe3d4a159e86edb57685021c": {
      "model_module": "@jupyter-widgets/base",
      "model_module_version": "1.0.0",
      "model_name": "LayoutModel",
      "state": {}
     },
     "421e68c73e4247fa91acbe8746542624": {
      "model_module": "@jupyter-widgets/base",
      "model_module_version": "1.0.0",
      "model_name": "LayoutModel",
      "state": {}
     },
     "4a07442e2a0f45ad8cf35d125d8be3d8": {
      "model_module": "@jupyter-widgets/base",
      "model_module_version": "1.0.0",
      "model_name": "LayoutModel",
      "state": {}
     },
     "5b8d4623b47040d4ab226a1cad9eab18": {
      "model_module": "@jupyter-widgets/base",
      "model_module_version": "1.0.0",
      "model_name": "LayoutModel",
      "state": {}
     },
     "5c7014ca10fd4938b129dbf221c9527e": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "1.1.0",
      "model_name": "FloatSliderModel",
      "state": {
       "continuous_update": false,
       "description": "covar",
       "layout": "IPY_MODEL_999211a3c40e4d1483ccc601d258de0d",
       "max": 1,
       "step": 0.1,
       "style": "IPY_MODEL_fa812baa507d4a03a19d102c4b974a07"
      }
     },
     "690b240f5f4a49c8a5da1d776d041d6c": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "1.1.0",
      "model_name": "FloatSliderModel",
      "state": {
       "continuous_update": false,
       "description": "F11",
       "layout": "IPY_MODEL_6f60d46968e749039d2fc3b5ee95e417",
       "max": 2,
       "step": 0.1,
       "style": "IPY_MODEL_7754db5b1fd743e28112f09ccaab0fd5",
       "value": 1
      }
     },
     "6d6467b1199043b3ab04e269838c19ef": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "1.1.0",
      "model_name": "FloatSliderModel",
      "state": {
       "continuous_update": false,
       "description": "F11",
       "layout": "IPY_MODEL_5b8d4623b47040d4ab226a1cad9eab18",
       "max": 2,
       "step": 0.1,
       "style": "IPY_MODEL_a470dca5c2a24758843e6e03efdb9a2b",
       "value": 1
      }
     },
     "6f60d46968e749039d2fc3b5ee95e417": {
      "model_module": "@jupyter-widgets/base",
      "model_module_version": "1.0.0",
      "model_name": "LayoutModel",
      "state": {}
     },
     "7754db5b1fd743e28112f09ccaab0fd5": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "1.1.0",
      "model_name": "SliderStyleModel",
      "state": {
       "description_width": ""
      }
     },
     "7c0d25f017ed4be1a9c3e0e8b59bc715": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "1.1.0",
      "model_name": "VBoxModel",
      "state": {
       "_dom_classes": [
        "widget-interact"
       ],
       "children": [
        "IPY_MODEL_ae0a2fb2f57b4698864cf31d94dc927a",
        "IPY_MODEL_353562a0c2fb4990a948c7b13c874de7",
        "IPY_MODEL_1ab24477f22349dcbec607799e29d07a",
        "IPY_MODEL_6d6467b1199043b3ab04e269838c19ef",
        "IPY_MODEL_5c7014ca10fd4938b129dbf221c9527e",
        "IPY_MODEL_95bb473886d84868b4d50e3ae7cb4750"
       ],
       "layout": "IPY_MODEL_421e68c73e4247fa91acbe8746542624"
      }
     },
     "7c951421433244f38f2e8bd4e0bb0676": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "1.1.0",
      "model_name": "SliderStyleModel",
      "state": {
       "description_width": ""
      }
     },
     "95bb473886d84868b4d50e3ae7cb4750": {
      "model_module": "@jupyter-widgets/output",
      "model_module_version": "1.0.0",
      "model_name": "OutputModel",
      "state": {
       "layout": "IPY_MODEL_4a07442e2a0f45ad8cf35d125d8be3d8",
       "outputs": [
        {
         "data": {
          "image/png": "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\n",
          "text/plain": "<matplotlib.figure.Figure at 0x21f3657c358>"
         },
         "metadata": {},
         "output_type": "display_data"
        }
       ]
      }
     },
     "96ac41727a6a40edae699b28f4691efb": {
      "model_module": "@jupyter-widgets/base",
      "model_module_version": "1.0.0",
      "model_name": "LayoutModel",
      "state": {}
     },
     "999211a3c40e4d1483ccc601d258de0d": {
      "model_module": "@jupyter-widgets/base",
      "model_module_version": "1.0.0",
      "model_name": "LayoutModel",
      "state": {}
     },
     "9f26334c7fbf4edabae2fcdc1c4b1ba4": {
      "model_module": "@jupyter-widgets/base",
      "model_module_version": "1.0.0",
      "model_name": "LayoutModel",
      "state": {}
     },
     "a09597f645de42cb8a4b72cc241f1117": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "1.1.0",
      "model_name": "FloatSliderModel",
      "state": {
       "continuous_update": false,
       "description": "F10",
       "layout": "IPY_MODEL_f6f02ba933a849bfb94148de056d98e8",
       "max": 2,
       "step": 0.1,
       "style": "IPY_MODEL_0d005590353d40ad96a4e4c992ea28c0"
      }
     },
     "a470dca5c2a24758843e6e03efdb9a2b": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "1.1.0",
      "model_name": "SliderStyleModel",
      "state": {
       "description_width": ""
      }
     },
     "ae0a2fb2f57b4698864cf31d94dc927a": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "1.1.0",
      "model_name": "IntSliderModel",
      "state": {
       "continuous_update": false,
       "description": "F00",
       "layout": "IPY_MODEL_96ac41727a6a40edae699b28f4691efb",
       "max": 2,
       "style": "IPY_MODEL_ec6fc39134954a3b8569f1fde4ad57a9",
       "value": 1
      }
     },
     "af84bbe3e56744deb318d6a9b6634ce5": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "1.1.0",
      "model_name": "SliderStyleModel",
      "state": {
       "description_width": ""
      }
     },
     "b8b3a691d03d4f2dbabefc9ea9529d00": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "1.1.0",
      "model_name": "SliderStyleModel",
      "state": {
       "description_width": ""
      }
     },
     "c377c5e3efb74ffa94016da4d50d9f2d": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "1.1.0",
      "model_name": "VBoxModel",
      "state": {
       "_dom_classes": [
        "widget-interact"
       ],
       "children": [
        "IPY_MODEL_e1c5ba1b2b5043cbaaefa2f1fcd81d12",
        "IPY_MODEL_fd4dab7592c043f28ff3764ff3367f31",
        "IPY_MODEL_a09597f645de42cb8a4b72cc241f1117",
        "IPY_MODEL_690b240f5f4a49c8a5da1d776d041d6c",
        "IPY_MODEL_d27eda04d2704cde9c4c228b8e31a4eb",
        "IPY_MODEL_f95f821f610e4df2911cabdfb86ca3a7"
       ],
       "layout": "IPY_MODEL_10595c1e709d40ebaf2f3c0b6501de30"
      }
     },
     "d27eda04d2704cde9c4c228b8e31a4eb": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "1.1.0",
      "model_name": "FloatSliderModel",
      "state": {
       "continuous_update": false,
       "description": "covar",
       "layout": "IPY_MODEL_9f26334c7fbf4edabae2fcdc1c4b1ba4",
       "max": 1,
       "step": 0.1,
       "style": "IPY_MODEL_048d0de3675e47d891a02b4af859bbff"
      }
     },
     "d4097ec3b7b64499bc1156dc01ddff5c": {
      "model_module": "@jupyter-widgets/base",
      "model_module_version": "1.0.0",
      "model_name": "LayoutModel",
      "state": {}
     },
     "e1c5ba1b2b5043cbaaefa2f1fcd81d12": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "1.1.0",
      "model_name": "IntSliderModel",
      "state": {
       "continuous_update": false,
       "description": "F00",
       "layout": "IPY_MODEL_d4097ec3b7b64499bc1156dc01ddff5c",
       "max": 2,
       "style": "IPY_MODEL_3b2727f48017422886e76ef88a8a9e29",
       "value": 1
      }
     },
     "ea1ae5b02f1b46c6ab7142ef8fd4e991": {
      "model_module": "@jupyter-widgets/base",
      "model_module_version": "1.0.0",
      "model_name": "LayoutModel",
      "state": {}
     },
     "ec6fc39134954a3b8569f1fde4ad57a9": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "1.1.0",
      "model_name": "SliderStyleModel",
      "state": {
       "description_width": ""
      }
     },
     "f6f02ba933a849bfb94148de056d98e8": {
      "model_module": "@jupyter-widgets/base",
      "model_module_version": "1.0.0",
      "model_name": "LayoutModel",
      "state": {}
     },
     "f95f821f610e4df2911cabdfb86ca3a7": {
      "model_module": "@jupyter-widgets/output",
      "model_module_version": "1.0.0",
      "model_name": "OutputModel",
      "state": {
       "layout": "IPY_MODEL_3c2536f1fe3d4a159e86edb57685021c",
       "outputs": [
        {
         "data": {
          "image/png": "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\n",
          "text/plain": "<matplotlib.figure.Figure at 0x18694177940>"
         },
         "metadata": {},
         "output_type": "display_data"
        }
       ]
      }
     },
     "fa812baa507d4a03a19d102c4b974a07": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "1.1.0",
      "model_name": "SliderStyleModel",
      "state": {
       "description_width": ""
      }
     },
     "fd4dab7592c043f28ff3764ff3367f31": {
      "model_module": "@jupyter-widgets/controls",
      "model_module_version": "1.1.0",
      "model_name": "FloatSliderModel",
      "state": {
       "continuous_update": false,
       "description": "F01(dt)",
       "layout": "IPY_MODEL_1adb400d9d5e4ba7b379a0c942ce4ba3",
       "max": 2,
       "step": 0.1,
       "style": "IPY_MODEL_7c951421433244f38f2e8bd4e0bb0676",
       "value": 1
      }
     }
    },
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}