Tutorial 8

Implementation Activity: Visualizaing Figures of Merit

October 28, 2013
During the rst project you learned how to convert your abstrac-
tion (i.e. a set of difference equations) into a MATLAB program that
produced time series of shark, ray, and scallop populations. You then
used this program to do some modeling work and ultimately pro-
duced some punchline graphs to illustrate your conclusions.
In this tutorial we will focus on moving beyond creating graphs
that summarize a single time series to producing graphs that sum-
marize multiple times series. In particular, we will focus on producing
graphs that summarize how gures of merit, numbers that character-
ize the overall behavior of a given time series, change as a function
of some aspect of a model (either a model parameter or an initial
condition). While you may already have some experience creating
visualizations of gures of merit from the rst project, the purpose
of this activity is to arm you with some additional tools so that you
become completely comfortable in creating these visualizations.
Modeling Alcohol Concentration in the Body
In order to illustrate some helpful techniques for visualizing gures
of merit, we are trotting out our old friend alcohol... errr.. um... the
alcohol model to be more specic!
In the pharmacokinetics version of the previous tutorial (dont
worry if you werent there, all the information to do this activity is
contained in this document), we developed a simplied version of the
alcohol model from the Peters, Wedel, and Schaafsma paper that is
dened by the following system of differential equations:
dy
1
dt
= d ky
1
(1)
dy
2
dt
= ky
1

V
m
y
2
K
m
+y
2
(2)
Where, the symbols have the following meanings:
Symbol Meaning Units
y
1
concentration of alcohol in the stomach
g
L
y
2
concentration of alcohol in the lean body mass
g
L
d drinking rate
g
Ls
k rate constant for absorption of alcohol from the
1
s
stomach to the lean body mass
V
m
maximum rate of elimination of alcohol from the
g
Ls
lean body mass
K
m
the M.M. constant
g
L
TUTORI AL 8 2
Note that the concentration of alcohol in a particular compartment
(e.g. the stomach or the lean body mass) is dened as the quantity of
alcohol in that compartment divided by V (where V is equal to the
water content of the lean body mass). Likewise, the drinking rate d is
dened as the quantity of alcohol put into the stomach per unit time
divided by V.
Once we have established some values for the parameters as well
as the initial concentration of alcohol in the stomach, we can run our
model to produce timeseries of both y
1
and y
2
. For instance, given a
bolous input of alcohol, our model might generate the timeseries:
0 0.5 1 1.5 2 2.5 3
x 10
4
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Two Compartment MM Model
Time (seconds)
A
l
c
o
h
o
l

C
o
n
c
e
n
t
r
a
t
i
o
n

(
g
/
l
)


stomach
lean body mass
If we were to instead examine a situation where alcohol was ingested
at a constant rate in addition to the bolous input at t = 0, our model
might generate the time series:
0 0.5 1 1.5 2 2.5 3
x 10
4
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Two Compartment MM Model
Time (seconds)
A
l
c
o
h
o
l

C
o
n
c
e
n
t
r
a
t
i
o
n

(
g
/
l
)


stomach
lean body mass
TUTORI AL 8 3
In order to get started with the tutorial, download the code used
to generate the preceding time series (http://bit.ly/1hfqoyB).
Once you have downloaded the code and ensured that you can run it
and produce some time series, you are ready to move on.
Brainstorming Potential Plots of Figures of Merit
Think about the alcohol pharmacokinetic model; what interesting
gures of merit might we extract from the resultant time series? What
relationships between model features (inputs or parameters) and
gures of merit might be worth investigating?
With the people sitting around you, take 10 minutes to brainstorm
some gures of merit that might be interesting to visualize. For each
idea you come up with, sketch a prediction for what the resulting
graph might look like. You may nd it helpful to actually run the
provided MATLAB code with different inputs and parameter values
in order to get a sense of what interesting relationships the model
could potentially capture.
TUTORI AL 8 4
Visualizing Figures of Merit in MATLAB
One way to think of visualizing a gure of merit in MATLAB is that
you need three bits of code:
1. A bit of MATLAB code that generates time series for different
values of the model parameters and initial values.
2. A bit of MATLAB code that takes a time series and computes a
relevant gure of merit (e.g. peak alcohol concentration)
3. A bit of MATLAB code that varies some feature of the model (pa-
rameter or initial value), generates a time series using bit (1), com-
putes the gure of merit using bit (2), and nally produces some
visualization (e.g. a plot) of the relationship between the feature of
the model being varied and the resultant gure of merit.
Next, we will walk through creating each of these pieces of code.
Creating a Time Series Function
Begin by creating a MATLAB function called alcoholTimeSeries. The
function should have the following inputs and outputs (illustrated
here using a MATLAB header comment):
%%
% Computes alcohol time series using a two compartment MM model.
% Inputs:
% tp: the timepoints where we want to evaluate the resultant
% time series
% y10: initial alcohol concentration in the stomach
% d: drinking rate (for continued alcohol ingestion) (g/L/s)
% k: rate constant for absorption of alcohol from stomach to
% lean body mass (1/s)
% Vm: maximum rate of elimination of alcohol from the lean
% body mass (g/L/s)
% Km: the M.M. constant (g/L)
% Outputs:
% Y: a matrix where column 1 is the timeseries of the
% concentration of alcohol in the stomach at the
% specified time points (tp), and column 2 is the
% timeseries of alcohol concentration in the lean body
% mass at the specified time points (tp).
Take about 15 minutes to create this function. You may nd it useful
to build upon the provided starter code. You should create a unit test
called alcoholTimeSeriesUnitTest that veries that your new function
alcoholTimeSeries produces the same output as alcoholStarterCode when
run with the appropriate inputs.
TUTORI AL 8 5
Creating a Function to Compute a Figure of Merit
Choose a particular gure of merit that youd like to investigate. Next,
dene a function that takes as input a time series and outputs the
gure of merit. For instance, if you want to compute a gure of merit
of maximum alcohol concentration in the lean body mass, then you
might create a function called maxAlcoholConcentrationInLeanBodyMass
with function header:
%%
% Computes the maximum alcohol concentration (over time) in the
% lean body mass for a given time series.
% Inputs:
% tp: the time points corresponding the timeseries
% Y: the alcohol concentration in each compartment over time.
% Column 1 holds the concentrations in the stomach.
% Column 2 holds the concentrations in the lean body mass.
% Outputs:
% res: the maximum concentration in the lean body mass
function res = maxAlcoholConcentrationInLeanBodyMass(tp,Y)
% function body here
end
Once you have created your function, you should create a unit test
that veries that it is working properly. In other words, you should
create a function that tests whether your gure of merit function gives
the appropriate answer for a particular timeseries (you might gener-
ate this timeseries by hand, or else save the output of your timeseries
generation function). Take about 10 minutes to generate at least one
gure of merit function. Depending on the complexity of your gure
of merit (for instance the gure of merit maxAlcoholConcentrationIn-
LeanBodyMass is basically a one-liner), you might generate several
such functions.
TUTORI AL 8 6
Plotting a gure of Merit
Now that you have both a function for computing timeseries as well
as one for computing a gure of merit, put the two of them together to
create a plot showing how the gure of merit changes as a function of
one model parameter or initial condition. Before beginning, sketch out
what you think the resulting plot will look like.
Now that you have a rough idea of what your plot might look like,
go ahead and create a function that generates this plot. Does the plot
match what you expected? If it does match, great! If it doesnt match,
how do you explain this? Are you reasonably condent that your im-
plementation is correct? If you are condent that your plot is correct,
how does the mismatch between the plot you just generated and your
prior expectations change your understanding of the system?
Take about 15 minutes to do this. If you nish early, go ahead and
repeat the last two steps (dening a function to compute a gure of
merit and then generating a plot based on the gure of merit) for a
different gure of merit.
TUTORI AL 8 7
Creating a BAC Prediction Table
There are various rules of thumb for how long it takes the body to
process alcohol. For instance, a rule of thumb is that it takes 1 hour
for the body to completely metabolize 1 drink of alcohol. If we are to
believe our pharmacokinetics model, then this simple rule of thumb is
missing quite a few effects (e.g. the persons lean body mass).
An alternative to this one size ts all rule, are tables like the fol-
lowing which show how the concentration of alcohol in the blood
varies as a function of the weight of the person and the number
of drinks consumed (source: http://dui.drivinglaws.org/
drink-table.php).
Your goal in this section is to make a richer / more accurate version
of this table. For example,
1. People have differing abilities to metabolize alcohol. For an indi-
vidual of a given weight, how does an individuals lean body mass
alcohol concentration depend on the number of drinks ingested as
well as their ability to metabolize alcohol (V
m
)?
2. Looking at total number of drinks (as is done in the above table)
might not be sufcient. Given a xed drinking rate and a xed
body weight, how does the length of the drinking period and the
length of the sobering up period effect the concentration of alco-
hol in the lean body mass? (note: examining this question would
require some minor tweaks to the model)
Each of these possibilities requires investigating how a gure of
merit changes as a function of two model features. Your next goal is
to create a MATLAB program that explores how the concentration
of alcohol in the lean body mass is affected by two factors, however,
instead of using a table (as above) to communicate the results of your
analysis, you should communicate the relationship between the gure
of merit and the two model factors using a visualization called a heat
map. In this context, a heat map is a graphical representation of a
TUTORI AL 8 8
function from two variables to one. An intuitive example of this is a
map of the average temperature during a week for different areas of
the United States:
In this case, the heat map represents a function from two variables to
one variable where the input variables are latitude and longitude and
the output variable is average temperature Feb 25 - Mar 3, 2001. The
bar on the righthand side containing various colored squares and the
corresponding numbers serves as a key for mapping from the visual
representation of a temperature (the color) to the actual temperature
itself. The black lines on the gure (not the state border lines, but
the ones that separate regions of differing colors) are called contour
lines which correspond to regions of the map where the temperature
is constant (i.e. as you traverse around a contour line, the average
temperature for the week in question would remain constant).
Once you have decided on your gure of merit and two model
factors, take a minute and sketch out what you think the resulting
heat map might look like. You can use darker shading to indicate
lower numbers. Draw the contour lines that you expect to see. Make
sure to clearly label your axes.
TUTORI AL 8 9
Now that you have some intuition regarding the appearance of
your heat map, create some MATLAB code to generate the heat map.
Here are some suggestions:
1. Use nested loops to sweep over the two model factors.
2. Use a matrix to store the resultant gures of merit.
3. Use the builtin function contourf to create a heat map with con-
tour lines.
4. Use the builtin function colorbar to display the mapping between
color and numerical value.
Does the heat map match what you expected? If it does match,
great! If it doesnt match, how do you explain this? Are you reason-
ably condent that your implementation is correct? If you are con-
dent that your heat map is correct, how does the mismatch between
the heat map you just generated and your prior expectations change
your understanding of the system?
Take the next 30 minutes to work on this.