# Value-by-Alpha maps with `splot`

The last two  weeks of GSoC were still fully dedicated to expanding `plots` functionality. You can for example now create so called Value-by-Alpha maps using `splot.mapping`.

### What is a Value by Alpha choropleth?

In a nutshell, a Value-by-Alpha Choropleth is a bivariate choropleth that uses the values of the second input variable `y` as a transparency mask, determining how much of the choropleth displaying the values of a first variable `x` is shown. In comparison to a cartogram, Value-By-Alpha choropleths will not distort shapes and sizes but modify the alpha channel (transparency) of polygons according to the second input variable `y`.

### Value-by-Alpha functionality in `splot`

Imports you will need

```import libpysal as lp
from libpysal import examples
import geopandas as gpd
import pandas as pd
import matplotlib.pyplot as plt
import matplotlib
import numpy as np

from splot.mapping import vba_choropleth```

Let’s prepare the data

Load example data into a `geopandas.GeoDataFrame` and inspect column names. In this example we will use the `columbus.shp` file containing neighborhood crime data of 1980.

```link_to_data = examples.get_path('columbus.shp')

We extract two arrays `x` (housing value (in \$1,000)) and `y` (residential burglaries and vehicle thefts per 1000 households).

```x = gdf['HOVAL'].values
y = gdf['CRIME'].values```

We can now create a value by alpha map using `splot`’s `vba_choropleth` functionality.

Let’s plot a Value-by-Alpha Choropleth with `x` defining the rgb values and `y` defining the alpha value. For comparison we plot a choropleth of `x` with `gdf.plot()`:

```# Create new figure
fig, axs = plt.subplots(1,2, figsize=(20,10))

# use gdf.plot() to create regular choropleth
gdf.plot(column='HOVAL', scheme='quantiles', cmap='RdBu', ax=axs[0])

# use vba_choropleth to create Value-by-Alpha Choropleth
vba_choropleth(x, y, gdf, rgb_mapclassify=dict(classifier='quantiles'),
alpha_mapclassify=dict(classifier='quantiles'),
cmap='RdBu', ax=axs[1])

# set figure style
axs[0].set_title('normal Choropleth')
axs[0].set_axis_off()
axs[1].set_title('Value-by-Alpha Choropleth')

# plot
plt.show()```

You can see the original choropleth is fading into transparency wherever there is a high `y` value.

You can use the option to bin or classify your `x` and `y` values. `splot` uses mapclassify to bin your data and displays the new color and alpha ranges:

```# Create new figure
fig, axs = plt.subplots(2,2, figsize=(20,10))

# classifier quantiles
vba_choropleth(y, x, gdf, cmap='viridis', ax = axs[0,0],
rgb_mapclassify=dict(classifier='quantiles', k=3),
alpha_mapclassify=dict(classifier='quantiles', k=3))

# classifier natural_breaks
vba_choropleth(y, x, gdf, cmap='viridis', ax = axs[0,1],
rgb_mapclassify=dict(classifier='natural_breaks'),
alpha_mapclassify=dict(classifier='natural_breaks'))

# classifier std_mean
vba_choropleth(y, x, gdf, cmap='viridis', ax = axs[1,0],
rgb_mapclassify=dict(classifier='std_mean'),
alpha_mapclassify=dict(classifier='std_mean'))

# classifier fisher_jenks
vba_choropleth(y, x, gdf, cmap='viridis', ax = axs[1,1],
rgb_mapclassify=dict(classifier='fisher_jenks', k=3),
alpha_mapclassify=dict(classifier='fisher_jenks', k=3))

plt.show()```

Sometimes it is important in geospatial analysis to actually see the high values and let the small values fade out. With the `revert_alpha = True` argument, you can revert the transparency of the `y` values.

```# Create new figure
fig, axs = plt.subplots(1,2, figsize=(20,10))

# create a vba_choropleth
vba_choropleth(x, y, gdf, rgb_mapclassify=dict(classifier='quantiles'),
alpha_mapclassify=dict(classifier='quantiles'),
cmap='RdBu', ax=axs[0],
revert_alpha=False)

# set revert_alpha argument to True
vba_choropleth(x, y, gdf, rgb_mapclassify=dict(classifier='quantiles'),
alpha_mapclassify=dict(classifier='quantiles'),
cmap='RdBu', ax=axs[1],
revert_alpha = True)

# set figure style
axs[0].set_title('revert_alpha = False')
axs[1].set_title('revert_alpha = True')

# plot
plt.show()```

You can use the divergent argument to display divergent alpha values. This means values at the extremes of your data range will be displayed with an alpha value of 1. Values towards the middle of your data range will be mapped more and more invisible towards an alpha value of 0.

```# create new figure
fig, axs = plt.subplots(1,2, figsize=(20,10))

# create a vba_choropleth
vba_choropleth(y, x, gdf, cmap='RdBu',
divergent=False, ax=axs[0])

# set divergent to True
vba_choropleth(y, x, gdf, cmap='RdBu',
divergent=True, ax=axs[1])

# set figure style
axs[0].set_title('divergent = False')
axs[0].set_axis_off()
axs[1].set_title('divergent = True')

# plot
plt.show()```

Lastly, if your values are classified, you have the option to add a legend to your map:

```fig = plt.figure(figsize=(15,10))
Next week will already be the last week of GSoC. I am sad that this great summer is over, but am looking forward to keeping on working on `splot` and `PySAL` in future. Look out for my next blog post in which I will summarise all of my code and decisions made for the `splot` project.