piegy.figures

This section describes the figures module of our package: make figures to visualize simulation results. We reserved the word “plot” for matplotlib plots, and use “figures” as the name of the module instead.

Dynamics Figures

This subsection contains the functions for plotting dynamics of certain values, i.e., how the values change over time, from time t = 0 to maxtime.

figures.UV_dyna(mod, ax=None, interval=20)
Plot population dynamics of the two species over time, specifically hawk’s population U, doves’ population V, and total population U + V.
Parameters:

  • mod (piegy.simulation.model object) – where the parameters of the model and data are stored.

  • ax (matplotlib axes) – matplotlib axes to plot upon. A new axes will be created if None is given.

  • interval (int) – the function takes average over every interval many data points and makes plot. Used to smooth curves. See details at Clarifications-interval

Returns:

a plot of the change of population over time.

Return type:

matplotlib axes.


figures.pi_dyna(mod, ax=None, interval=20)
Plot payoff dynamics of the two species over time, specifically hawk’s population Hpi, doves’ population Vpi, and total population Hpi + Vpi.
Parameters:

  • mod (piegy.simulation.model object) – where the parameters of the model and data are stored.

  • ax (matplotlib axes) – matplotlib axes to plot upon. A new axes will be created if None is given.

  • interval (int) – the function takes average over every interval many data points and makes plot. Used to smooth curves. See details at Clarifications-interval

Returns:

a plot of the change of population over time.

Return type:

matplotlib axes.


figures.UV_std(mod, ax=None, interval=20)
Plot dynamics of standard deviation of population over time.
Parameters:

  • mod (piegy.simulation.model object) – where the parameters of the model and data are stored.

  • ax (matplotlib axes) – matplotlib axes to plot upon. A new axes will be created if None is given.

  • interval (int) – the function takes average over every interval many data points and makes plot. Used to smooth curves. See details at Clarifications-interval

Returns:

a plot of the change of population over time.

Return type:

matplotlib axes.


figures.pi_std(mod, ax=None, interval=20)
Plot dynamics of standard deviation of payoff over time.
Parameters:

  • mod (piegy.simulation.model object) – where the parameters of the model and data are stored.

  • ax (matplotlib axes) – matplotlib axes to plot upon. A new axes will be created if None is given.

  • interval (int) – the function takes average over every interval many data points and makes plot. Used to smooth curves. See details at Clarifications-interval

Returns:

a plot of the change of population over time.

Return type:

matplotlib axes.


figures.UV_hist(mod, ax_H=None, ax_D=None, color_H='purple', color_D='green', start=0.95, end=1.0)

Make two histograms of average population density in a specified time interval.

Parameters:

  • mod (piegy.simulation.model object) – where the parameters of the model and data are stored.

  • ax_H (matplotlib axes) – matplotlib axes to plot the histogram of U upon. A new axes will be created if None is given.

  • ax_D (matplotlib axes) – matplotlib axes to plot the histogram of V upon. A new axes will be created if None is given.

  • color_H (str) – color for the histograms, using regular matplotlib colors.

  • color_D (str) – similar to color_H.

  • start (float or int, \(\le 1\)) – start of the time interval. Default 0.9 means the interval starts from 90% of maxtime.

  • end (float or int, \(\le 1\)) – end of the time interval. Default 1.0 means the interval ends at exactly maxtime. See details of start and end at Clarifications-start-end.

Returns:

two density histograms for U, V population.

Return type:

matplotlib axes.


figures.pi_hist(mod, ax_H=None, ax_D=None, color_H='purple', color_D='green', start=0.95, end=1.0)

Make two histograms of average payoff density in a specified time interval.

Parameters:

  • mod (piegy.simulation.model object) – where the parameters of the model and data are stored.

  • ax_H (matplotlib axes) – matplotlib axes to plot the histogram of U payoff upon. A new axes will be created if None is given.

  • ax_D (matplotlib axes) – matplotlib axes to plot the histogram of V payoff upon. A new axes will be created if None is given.

  • color_H (str) – color for the histograms, using regular matplotlib colors.

  • color_D (str) – similar to color_H.

  • start (float or int, \(\le 1\)) – start of the time interval. Default 0.9 means the interval starts from 90% of maxtime.

  • end (float or int, \(\le 1\)) – end of the time interval. Default 1.0 means the interval ends at exactly maxtime. See details of start and end at Clarifications-start-end.

Returns:

two density histograms for U, V payoff.

Return type:

matplotlib axes.

Distribution Figures

This subsection contains the distribution functions, i.e., the average distribution of either population or payoff in a specified time interval.

figures.UV_heatmap(mod, ax_H=None, ax_D=None, color_H='Purples', color_D='Greens', start=0.95, end=1.0)
Make two heatmaps for average population distributions of hawks and doves in a specified time interval.
Intended for the 2D spatial setting, where both N and M larger than 1. For 1D space, please use UV_bar.
Parameters:

  • mod (piegy.simulation.model object) – where the parameters of the model and data are stored.

  • ax_H (matplotlib axes) – matplotlib axes to plot the heatmap of U population upon. A new axes will be created if None is given.

  • ax_D (matplotlib axes) – matplotlib axes to plot the heatmap of V population upon. A new axes will be created if None is given.

  • color_H (str) – color to use for U’s heatmap. Uses matplotlib color maps.

  • color_D (str) – similar to color_H.

  • start (float or int, \(\le 1\)) – start of the time interval. Default 0.9 means the interval starts from 90% of maxtime.

  • end (float or int, \(\le 1\)) – end of the time interval. Default 1.0 means the interval ends at exactly maxtime. See details of start and end at Clarifications-start-end.

Returns:

two heatmaps of distribution of U, V population.

Return type:

matplotlib axes.


figures.pi_heatmap(mod, ax_H=None, ax_D=None, color_H='Purples', color_D='Greens', start=0.95, end=1.0)
Make two heatmaps for average payoff distributions of hawks and doves in a specified time interval.
Intended for 2D spatial setting, where both N and M larger than 1. For 1D space, please use pi_bar.

Recommend using different colors for population and payoff to avoid confusion.
Parameters:

  • mod (piegy.simulation.model object) – where the parameters of the model and data are stored.

  • ax_H (matplotlib axes) – matplotlib axes to plot the heatmap of U payoff upon. A new axes will be created if None is given.

  • ax_D (matplotlib axes) – matplotlib axes to plot the heatmap of V payoff upon. A new axes will be created if None is given.

  • color_H (str) – color to use for U’s heatmap. Uses matplotlib color maps.

  • color_D (str) – similar to color_H.

Returns:

two heatmaps of distribution of U, V population.

Return type:

matplotlib axes.


figures.UV_bar(mod, ax_H=None, ax_D=None, color_H='purple', color_D='green', start=0.95, end=1.0)
Make two heatmaps for average population distributions of hawks and doves in a specified time interval.
Intended for 1D spatial setting, where N = 1. For 2D space, please use UV_heatmap.
Parameters:

  • mod (piegy.simulation.model object) – where the parameters of the model and data are stored.

  • ax_H (matplotlib axes) – matplotlib axes to plot the heatmap of U payoff upon. A new axes will be created if None is given.

  • ax_D (matplotlib axes) – matplotlib axes to plot the heatmap of V payoff upon. A new axes will be created if None is given.

  • color_H (str) – color for the barplots. Note we are not making heatmaps, so please use regular colors rather than color maps.

  • color_D (str) – similar to color_H.

  • start (float or int, \(\le 1\)) – start of the time interval. Default 0.9 means the interval starts from 90% of maxtime.

  • end (float or int, \(\le 1\)) – end of the time interval. Default 1.0 means the interval ends at exactly maxtime. See details of start and end at Clarifications-start-end.

Returns:

two baplots of distribution of U, V population.

Return type:

matplotlib axes.


figures.pi_bar(mod, ax_H=None, ax_D=None, color_H='violet', color_D='yellowgreen', start=0.95, end=1.0)
Make two heatmaps for average payoff distributions of hawks and doves in a specified time interval.
Intended for 1D spatial setting, where N equal to 1. For 2D space, please use pi_heatmap.

Recommend using different colors for population and payoff to avoid confusion.
Parameters:

  • mod (piegy.simulation.model object) – where the parameters of the model and data are stored.

  • ax_H (matplotlib axes) – matplotlib axes to plot the barplot of U population upon. A new axes will be created if None is given.

  • ax_D (matplotlib axes) – matplotlib axes to plot the barplot of V population upon. A new axes will be created if None is given.

  • color_H (str) – color for the barplots. Note we are not making heatmaps, so please use regular colors rather than color maps.

  • color_D (str) – similar to color_H.

  • start (float or int, \(\le 1\)) – start of the time interval. Default 0.9 means the interval starts from 90% of maxtime.

  • end (float or int, \(\le 1\)) – end of the time interval. Default 1.0 means the interval ends at exactly maxtime. See details of start and end at Clarifications-start-end.

Returns:

two baplots of distribution of U, V population.

Return type:

matplotlib axes.


Other Functions

figures.UV_pi(mod, ax_H=None, ax_D=None, color_H='violet', color_D='yellowgreen', alpha=0.25, start=0.95, end=1.0)
Make a scatter plot for the correlation between average population and average payoff across a specified time interval.
Every point denotes a patch, its x-coord is the patch’s population, y-coord is payoff.
Parameters:

  • mod (piegy.simulation.model object) – where the parameters of the model and data are stored.

  • ax_H (matplotlib axes) – matplotlib axes to plot the corr plot of U population-payoff upon. A new axes will be created if None is given.

  • ax_D (matplotlib axes) – matplotlib axes to plot the corr plot of V population-payoff upon. A new axes will be created if None is given.

  • color_H (str) – color for the barplots. Note we are not making heatmaps, so please use regular colors rather than color maps.

  • color_D (str) – similar to color_H.

  • start (float or int, \(\le 1\)) – start of the time interval. Default 0.9 means the interval starts from 90% of maxtime.

  • end (float or int, \(\le 1\)) – end of the time interval. Default 1.0 means the interval ends at exactly maxtime. See details of start and end at Clarifications-start-end.

Returns:

two baplots of distribution of U, V population.

Return type:

matplotlib axes.

Returns:

two scatter plots for correlation between population and payoff, for U and V two species.

Return type:

matplotlib axes.


figures.UV_expected(mod, color_H='Purples', color_D='Greens')
Calculate and plot expected population of every patch only based on payoff matrices, assuming no migration or any stochastic process. Handles both 1D and 2D case.
For 2D, population is shown in heatmaps. And for 1D, uses barplots.
Parameters:

  • mod (piegy.simulation.model object) – where the parameters of the model and data are stored.

  • color_H (str) – color for U’s plot. Please use matplotlib color map if your space is 2D, use regular colors if 1D.

  • color_D (str) – same as color_H.

Returns:

two heatmaps or barplots about the distribution of U, V expected population.

Return type:

matplotlib figure


figures.UV_expected_val(mod)
Calculate expected U, V population based on payoff matrices, assuming no migration or any stochastic process.
To differentiate from peigy.figures.UV_expected, this funtion returns the exact values rather than figures.

We recommend using peigy.figures.UV_expected instead for visualization purposes. Use this function if you want the exact values.
Parameters:

mod (piegy.simulation.model object) – where the parameters of the model and data are stored.

Returns:

two 2D arrays containing the expected population at each patch.

Return type:

numpy.ndarray


Examples

Here are some usage examples for each of the piegy.figures functions.

First please import the piegy.simulation and piegy.figures modules:
from piegy import simulation, figures
import matplotlib.pyplot as plt
All figures below are generated based on our demo model. You get a copy by piegy.simulation.get_demo function:
mod = simulation.demo_model()
Let’s run the simulation:
simulation.run(mod)
After a simulation is completed, the first thing you probably want to do is convergence check: whether the population has reached equilibrium state.

Make a population dynamics figure by piegy.figures.UV_dyna function:
fig_UV_dyna, ax_UV_dyna = plt.subplots()
figures.UV_dyna(mod, ax_UV_dyna, interval = 10)
interval = 10 means to take average over every 10 data points. See more at Clarifications-interval.

It gives the following figure:
_images/UV_dyna.png

UV_dyna: Population Dynamics

We can similarly look at payoff dynamics by piegy.figures.pi_dyna function:
fig_pi_dyna, ax_pi_dyna = plt.subplots()
figures.pi_dyna(mod, ax_pi_dyna, interval = 10)
_images/pi_dyna_10.png

pi_dyna: Payoff Dynamics

Note there are many fluctuations in the figure. You can smooth them out (a bit) with larger interval value:
fig_pi_dyna40, ax_pi_dyna40 = plt.subplots()
figures.pi_dyna(mod, ax_pi_dyna40, interval = 40)
_images/pi_dyna_40.png

Smoother Payoff Dynamics with interval = 40

You can also look at change of standard deviation by piegy.figures.UV_std and piegy.figures.pi_std.

Let’s now look at distributions: the distribution of population and payoff in some certain time interval. Call piegy.figures.UV_heatmap function:

fig_UV_hmap, ax_UV_hmap = plt.subplots(2, 1, figsize = (6.4, 9.6))
figures.UV_hmap(mod, ax_UV_hmap[0], ax_UV_hmap[1], start = 0.95, end = 1.0)
start = 0.95 and end = 1.0 means we are plotting the average distribution over 95% ~ 100% of total time, i.e., the end of simulation.
_images/UV_hmap.png

U & V population Distribution in 95% ~ 100% Total Time

Interested in some other time intervals? You can plot any time interval by changing start and end values.

We can also make payoff distribution heatmaps by piegy.figures.pi_heatmap:
fig_pi_hmap, ax_pi_hmap = plt.subplots(2, 1, figsize = (6.4, 9.6))
figures.pi_hmap(mod, ax_pi_hmap[0], ax_pi_hmap[1], start = 0.95, end = 1.0)
_images/pi_hmap.png

U & V Payoff Distribution in 95% ~ 100% Total Time

You may notice the correlation between population and payoff: patches with higher population tend to have higher payoff. Let’s visualize the correlation with scatter plots. Call piegy.figures.UDpi:

fig_corr, ax_corr = plt.subplots(2, 1, figsize = (6.4, 9.6))
figures.UV_pi(mod, ax_corr[0], ax_corr[1], alpha = 0.5, start = 0.95, end = 1.0)
alpha is used to make points semi-transparent since there are lots of overlaps.
_images/corr.png

U and V Population - Payoff Correlation Plot

So far we have introduced most of our piegy.figures functions and basic usages. Explore the rest as well!