*A tutorial adventure with Python 3, cytoolz, NumPy, and matplotlib*

This tutorial was adapted from the Linear Regression tutorial for the Clojure scientific computing platform Incanter. It has been significantly modified to take advantage of the following, however:

- Python 3
- Hy - Clojure-Flavoured Python
- cytoolz - a Cython implementation of the famous pytoolz suite
- NumPy - a full-featured numeric library for Python
- matplotlib - a Python mathematical plotting library, originally inspired by MATLAB

Okay, to be honest, we don't really use cytoolz in the linear regression exercise; but we really *wanted* to :-) The opportunity just didn't arise. Seriously, though, cytoolz some some pretty sweet stuff, and provides fast utility functions you may be missing if you're coming (or returning!) to Python after living in the land of functional programming. In particular, it borrows heavily from the Clojure API (which is, quite bluntly, awesome).

From wikipedia:

Curve fitting is the process of constructing a curve, or mathematical function, that has the best fit to a series of data points, possibly subject to constraints. Curve fitting can involve either interpolation, where an exact fit to the data is required, or smoothing, in which a "smooth" function is constructed that approximately fits the data.

A related topic is regression analysis, which focuses more on questions of statistical inference such as how much uncertainty is present in a curve that is fit to data observed with random errors. Fitted curves can be used as an aid for data visualization, to infer values of a function where no data are available, and to summarize the relationships among two or more variables. Extrapolation refers to the use of a fitted curve beyond the range of the observed data, and is subject to a degree of uncertainty since it may reflect the method used to construct the curve as much as it reflects the observed data.

The suite of tools available for scientific computing in Python are pretty stunning. Here's an abridged list:

- NumPy
- SciPy
- matplotlib
- SymPy
- Pandas
- IPython
- scikit-learn
- AstroPy

There are so many more, so much to enjoy.

Hy is a Lisp dialect that converts its structure into Python’s abstract syntax tree. It is to Python what LFE is to Erlang.This provides developers from many backgrounds with the following:

- A lisp that feels very Pythonic
- A great way to use Lisp’s crazy powers but in the wide world of Python’s libraries
- A great way to start exploring Lisp, from the comfort of python
- A pleasant language that has a lot of neat ideas :-)

To support different languages in IPython notebooks, one either needs to create an IPython kernel for the desired language, or create a cell magic command. To the best of our knowledge, there is as yet no Hy IPython kernel, however, yardsale8 has created HyMagic for hylang, and this entire notebook depends upon it. Thanks, @yardsale8!

If you are reading this with the IPython nbviewer and you want to run the examples on your machine, just do the following:

```
$ git clone https://github.com/oubiwann/linear-regression-tutorial.git
$ cd linear-regression-tutorial
$ make
```

That will:

- create a virtualenv
- download all the dependencies, and then
- start up this notebook using a local IPython HTTP server

Note that since this tutorial is written in Hy and there is no Hy IPython kernel yet, we use the `%%hymagic`

command for each cell, which will look like this:

In [1]:

```
%%hylang
(* 2 (reduce + (range 1 7) 0))
```

Out[1]:

Let's get started with the notebook prep, now.

This notebook is started with a custom IPython profile (defined in a `make`

include file), and that profile has already loaded the Hy lang cell magic extension, so we don't need to.

We do need to set up matplotlib for IPython, though:

In [2]:

```
import matplotlib
matplotlib.use('nbagg')
%matplotlib inline
```

Next, switching to Hy, we can do all our imports:

In [3]:

```
%%hylang
(import [functools [reduce]]
[pprint [pprint]]
[cytoolz [itertoolz]]
[numpy :as np]
[matplotlib :as mpl]
[matplotlib.pyplot :as plt]
[seaborn :as sns])
```

Now we can configure the color map we'll use in our plots:

In [4]:

```
%%hylang
(def palette_name "husl")
(def colors (sns.color_palette palette_name 8))
(colors.reverse)
(def cmap (mpl.colors.LinearSegmentedColormap.from_list palette_name colors))
```

In the case of this tutorial, the "observed data" is the same data set as that used in the Incanter linear regression tutorial: the NIST Filip.dat file. In the `./notebooks`

directoy we've saved a local copy of `Filip.dat`

as well as a CSV file converstion of the data (`filip.csv`

).

Let's read it in:

In [5]:

```
%%hylang
(def data (apply np.genfromtxt ["filip.csv"] {"dtype" float "delimiter" "," "names" True}))
```

Let's set some of that data to variables for use later on:

In [6]:

```
%%hylang
(def x (get data "x"))
(def y (get data "y"))
(def [x-min x-max] [(x.min) (x.max)])
```

Out[6]:

Here's what it looks like:

In [7]:

```
%%hylang
x
```

Out[7]:

In [8]:

```
%%hylang
y
```

Out[8]:

Our preparations are complete -- let's get started!

Let's take a look at our data with a quick plot:

In [9]:

```
%%hylang
(apply plt.scatter [x y])
(plt.show)
```

That's not the most beautiful graph in the world, so perhaps we can make it a little better. Let's do the following:

- increase the size of the plot
- also make the plot points bigger
- use the color map we defined earlier in the notebook
- and give the points some transparency

Let's start with sizing the points. We'll create an array that's the same size and shape as one of the dimensions from our data set, and then we'll give calculate an arbitrary area to display for each point size:

In [10]:

```
%%hylang
(def ones (np.ones_like x))
(def size (* np.pi (** (* 20 ones) 2)))
```

Let's do some more sizes: one for the figure, and another for the label fonts:

In [11]:

```
%%hylang
(def figsize {"figsize" [18 18]})
(def fontsize {"fontsize" 24})
```

We'll use the $x$-axis values as the basis for color value differences. For the pallete, we'll use our previously-defined `cmap`

variable:

In [12]:

```
%%hylang
(def plot-options {"s" size "c" x "alpha" 0.5 "cmap" cmap})
```

Let's set up our labels, create our plot, and then display it:

In [13]:

```
%%hylang
(apply plt.figure [] figsize)
(apply plt.title ["NIST Data Set for Linear Regression Demo"] fontsize)
(apply plt.xlabel ["$x$ values"] fontsize)
(apply plt.ylabel ["$y$ values"] fontsize)
(apply plt.scatter [x y] plot-options)
(plt.show)
```

Our graph is looking *much* better. Now let's get mathematical!

The NIST data set provided a polynomial describing this data:

`y = B0 + B1*x + B2*(x**2) + ... + B9*(x**9) + B10*(x**10) + e`

Or, if you prefer LaTeX:

\begin{equation} y = B_0 + B_1{x} + B_2{x^2} + ... + B_9{x^9} + B_{10}{x^{10}} + e \end{equation}

Using NumPy, we can easily fit an 10th-degree polynomial curve to this data. We will use `numpy.polyfit`

for finding a least squares polynomial fit, passing it the $x$ and $y$ values for the data to fit as well as the degree of our polynomial:

In [14]:

```
%%hylang
(def coeffs (np.polyfit x y 10))
```

In [15]:

```
coeffs
```

Out[15]:

`np.polyplot`

can return more data, if you are so inclined:

In [16]:

```
%%hylang
(def [coeffs residuals rank singular-values rcond]
(apply np.polyfit [x y 10] {"full" true}))
```

Out[16]:

There is a conveience class in NumPy `numpy.poly1d`

that, once instantiated with our fit data, we can use to evaluate at any given point. Let's try it out:

In [17]:

```
%%hylang
(def model (np.poly1d coeffs))
```

Let's call this function against several values as a sanity check:

In [18]:

```
%%hylang
[(model -9) (model -7) (model -6) (model -5) (model -4) (model -3)]
```

Out[18]:

Looking back at our graph, we can see that these check out fine.

Next, let's see if our linear model matches up with what NIST provided. We're going to need to calculate the coefficient of determination, or $R^2$, a value that indicates how well a statistical model fits with measured data. We'll start by feeding our $x$ values into our model:

In [19]:

```
%%hylang
(def y-predicted (model x))
```

We will also need several other values in order to calculate $R^2$, per the equation given on the Wikipedia page linked above:

- The mean value of our observed (original) data: $\bar{y}=\frac{1}{n}\sum_{i=1}^n y_i$
- The total sum of squares : $SS_\text{tot}=\sum_i (y_i-\bar{y})^2$
- The regression sum of squares : $SS_\text{reg}=\sum_i (f_i -\bar{y})^2$
- The sum of squares of residuals : $SS_\text{res}=\sum_i (y_i - f_i)^2$

We have already the following:

- $y_i$: the $y$ values from the observed (NIST) data
- $f_i$: the values generated by our model

With these, we will be able to calculate $R^2$:

\begin{equation} R^2 \equiv 1 - {SS_{\rm res}\over SS_{\rm tot}} \end{equation}

In [20]:

```
%%hylang
(def y-mean (/ (np.sum y) y.size))
(def sstot (np.sum (** (- y y-mean) 2)))
(def ssreg (np.sum (** (- y-predicted y-mean) 2)))
(def ssres (np.sum (** (- y y-predicted) 2)))
```

Now we're ready to get the $R^2$ value for our model:

In [21]:

```
%%hylang
(def rsquared (- 1 (/ ssres sstot)))
```

In [22]:

```
rsquared
```

Out[22]:

If we compare this to the value from NIST, `0.996727416185620`

, we see that our model did pretty well:

In [23]:

```
%%hylang
(- 0.99672741617239946 0.996727416185620)
```

Out[23]:

That's a tiny number ...

Mathematical!

This is great for an IPython notebook, but kind of awkward for reuse. So let's create a linear model class that gives us everything we need in one shot:

In [24]:

```
%%hylang
(defclass PolynomialLinearModel []
"A pretty sweet utility Python-Lisp class for creating
a polynomial curve fitting model")
(defun PolynomialLinearModel.--init-- [self x y degree]
(setv self.x x)
(setv self.y y)
(setv self.degree degree)
(setv self.results None)
(setv self.model None)
(setv [self.coeffs self.residuals self.rank self.singular-values self.rcond]
[None None None None None])
(self.polyfit)
None)
(defun PolynomialLinearModel.get-y-mean [self]
"Get the mean value of the observed data"
(/ (np.sum self.y) self.y.size))
(defun PolynomialLinearModel.get-ss-tot [self]
"Get total sum of the squares"
(np.sum (** (- self.y (self.get-y-mean)) 2)))
(defun PolynomialLinearModel.get-ss-reg [self]
"Get the regression sum of squares"
(np.sum (** (- self.y-predicted (self.get-y-mean)) 2)))
(defun PolynomialLinearModel.get-ss-res [self]
"Get the sum of squares of residuals"
(np.sum (** (- self.y self.y-predicted) 2)))
(defun PolynomialLinearModel.get-r-squared [self]
"Get the R^2 value for the polynomial fit"
(- 1 (/ (self.get-ss-res) (self.get-ss-tot))))
(defun PolynomialLinearModel.polyfit [self]
"Do all the business"
(setv [self.coeffs self.residuals self.rank self.singular-values self.rcond]
(apply np.polyfit [self.x self.y self.degree] {"full" true}))
(setv self.model (np.poly1d self.coeffs))
(setv self.y-predicted (self.model self.x))
(setv self.r-squared (self.get-r-squared))
(setv self.results {
"coeffs" (self.coeffs.tolist)
"residuals" (self.residuals.tolist)
"rank" self.rank
"singular-values" (self.singular-values.tolist)
"rcond" self.rcond
"r-squared" self.r-squared}))
(defun PolynomialLinearModel.--str-- [self]
"Provide a string representation of the data"
(str self.results))
(defun PolynomialLinearModel.--repr-- [self]
"Provide a representation of the data"
(self.--str--))
(defun PolynomialLinearModel.predict [self xs]
"Given a set of input values, produce outputs using the model"
(self.model xs))
```

Out[24]:

This approach to adding methods to a class is different from the standard Hy approach (which mirrors the standard Python approach). I chose this form as it more closely matches that used by Common Lisp, and to a certain extent, Clojure. In fact, this lead me to ponder the creation of a `defmethod`

macro for Hy (as I'm sure has happened to many who use Hy). Instead of clutter up this notebook, though, I've moved that over to a sibling notebook. But we digress ...

Let's take it for a spin!

In [25]:

```
%%hylang
(def model (PolynomialLinearModel x y 10))
```

When we created our first model, we ran it against several values to see if the outputs fit our measured data. Of of those was the value `-9`

which returned `0.77668860985022548`

. Let's try that again with our new object:

In [26]:

```
%%hylang
(model.predict -9)
```

Out[26]:

Looking good!

Let's see what our results data look like:

In [27]:

```
%%hylang
(pprint model.results)
```

We're going to need some data to feed to our `fitted-poly`

function so that it can create the smooth polynomial curve that we will overlay on our scatter plot. Let's create a linear space between our minimum and maximum $x$ values (200
points should give us a nice, smooth curve). Then let's use `fitted-poly`

to generate the $y$ values:

In [28]:

```
%%hylang
(def fitted-xs (np.linspace x-min x-max 200))
(def fitted-ys (model.predict fitted-xs))
```

Now we're ready to put them together:

In [29]:

```
%%hylang
(def [figure axes] (apply plt.subplots [] figsize))
(plt.hold True)
(apply axes.set_title ["NIST Data Set and Polynomial Fit"] fontsize)
(apply axes.set_xlabel ["$x$ values"] fontsize)
(apply axes.set_ylabel ["$y$ values"] fontsize)
(apply axes.scatter [x y] plot-options)
(axes.plot fitted-xs fitted-ys)
(plt.show)
```