Module simuPOP.plotter

This module defines several utility functions and Python operators that plot expressions and information fields of evolving populations using matplotlib. Plotting through rpy and rpy2 was supported in version 1.1.6 and earlier but was removed in version 1.1.7 due to stability problems of rpy2.

Each operator calls a sequence of matplotlib functions to draw and save figures. A special parameter passing mechanism is used so that you can specify arbitrary parameters to these functions.

class VarPlotter

class simuPOP.plotter.VarPlotter

This class defines a Python operator that uses R to plot the current and historical values of a Python expression (expr), which are evaluated (against each population’s local namespace) and saved during evolution. The return value of the expression can be a number or a sequence, but should have the same type and length across all replicates and generations. Histories of each value (or each item in the returned sequence) of each replicate form a line, with generation numbers as its x-axis. Number of lines will be the number of replicates multiplied by dimension of the expression. Although complete histories are usually saved, you can use parameter win to save histories only within the last win generations.

A figure will be draw at the end of the last replicate (except for the first generation where no line could be drawn) unless the current generation is less than update generations away from the last generation at which a figure has been drawn. Lines for multiple replicates or dimensions could be plotted in the same figure (by default), or be seperated to subplots by replicates (byRep), by each dimention of the results (byDim), or by both. These figure could be saved to files in various formats if parameter saveAs is specified. File format is determined by file extension. After the evolution, the graphic device could be left open (leaveOpen).

VarPlotter(expr, win=0, update=1, byRep=False, byDim=False, saveAs='', leaveOpen=False, legend=[], preHook=None, postHook=None, plotHook=None, begin=0, end=-1, step=1, at=[], reps=True, **kwargs)

expr

expression that will be evaluated at each replicate’s local namespace when the operator is applied. Its value can be a number or a list (or tuple) but the type and length of the return value should be consistent for all replicates and at all generations.

win

Window of generations. If given, only values from generation -win to -1 will be plotted.

update

Update the figure after specified generations. For example, you can evalulate an expression and save its values at every 10 generations (parameter step=10) but only draw a figure after every 50 generations (parameter update=50.

byRep

Separate values at different replicates to different subplots.

byDim

Separate items from sequence results of expr to different subplots. If both byRep and byDim are True, the subplots will be arranged by variable and then replicates.

saveAs

Save figures in files saveAs_gen.ext (e.g. figure_10.eps if saveAs='figure.eps'). If ext is given, a corresponding device will be used. Otherwise, a default postscript driver will be used. Currently supported formats include .pdf, .png, .bmp, .jpg, and .tif. The default filename could be overridden by derived argument dev_print_file.

leaveOpen

Whether or not leave the plot open when plotting is done. Default to False functions. If this option is set to True, you will have to close the graphic device explicitly using function r.dev_off(). Note that leaving the device open allows further manipuation of the figures outside of this operator.

legend

labels of the lines. This operator will look for keyword parameters such as col, lty, lwd, and pch and call the legend function to draw a legend. If figure has multiple lines for both replicates and dimensions, legends should be given to each dimension, and then each replicate.

preHook

A function that, if given, will be called before the figure is draw. The r object for rpy or Axes object for matplotlib will be passed to this function.

postHook

A function that, if given, will be called after the figure is drawn. The r object for rpy or Axes object for matplotlib will be passed to this function.

plotHook

A function that, if given, will be called after each plot function. The Figure object from the matplotlib module , generation list, data being plotted, replicate number (if applicable) and dimension index (if applicable) will be passed as keyword arguments gen, data, rep (optional) and dim (optional).

kwargs

Additional keyword arguments that will be interpreted and sent to underlying matplotlib functions. These arguments could have prefixes (destination function names) and suffixes (list parameters) _rep, _dim, and _repdim for the rpy option. Arguments without prefixes are sent to functions plot and lines. String values with a leading ! will be replaced by its evaluated result against the current population.

class ScatterPlotter

class simuPOP.plotter.ScatterPlotter

This class defines a Python operator that uses R to plot individuals in a Population, using values at two information fields as their x- and y-axis.

Arbitrary keyword parameters could be specified and be passed to the underlying matplotlib drawing functions plot and scatter.

The power of this operator lies in its ability to differentiate individuals from different (virtual) subpopulations. If you specify IDs of (virtual) subpopulations (VSPs) in parameter subPops, only individuals from these VSPs will be displayed. Points from these subpopulations will be drawn with different shapes and colors. You can also customize these points using list parameters with suffix _sp. For example, if you have defined two VSPs by sex and set subPops=[(0, 0), (0, 1)], col_sp=['blue', 'red'] will color male individuals with blue and female individuals with red. In addition, if the value of a parameter is a string starting with !, the evaluated result of the remaining string will be used as parameter value.

ScatterPlotter(infoFields=[], saveAs='', leaveOpen=False, legend=[], preHook=None, postHook=None, begin=0, end=-1, step=1, at=[], reps=True, subPops=[], **kwargs)

infoFields

Two information fields whose values will be the x- and y-axis of each point (individual) in the plot.

subPops

A list of subpopulations and virtual subpopulations. Only individuals from these subpopulations will be plotted. Default to subpopulation indexes.

saveAs

Save figures in files saveAs_gen_rep.ext (e.g. figure_10_0.eps if saveAs='figure.eps'). If ext is given, a corresponding device will be used. Otherwise, a default postscript driver will be used. Currently supported formats include .pdf, .png, .bmp, .jpg, and .tif. The default filename could be overriden by derived argument dev_print_file.

leaveOpen

Whether or not leave the plot open when plotting is done. Default to False functions. If this option is set to True, you will have to close the graphic device explicitly using function r.dev_off(). Note that leaving the device open allows further manipuation of the figures outside of this operator.

legend

labels of the points. It must match the specified subpopulations.

preHook

A function that, if given, will be called before the figure is draw. The plotter module or the Figure object from matplotlib will be passed to this function.

postHook

A function that, if given, will be called after the figure is drawn. The plotter module or the Figure object from matplotlib will be passed to this function.

kwargs

Additional keyword arguments that will be interpreted and sent to underlying matplotlib functions. String values with a leading ! will be replaced by its evaluated result against the current population.