pyemu.plot package

Submodules

pyemu.plot.plot_utils module

Plotting functions for various PEST(++) and pyemu operations

pyemu.plot.plot_utils.ensemble_change_summary(ensemble1, ensemble2, pst, bins=10, facecolor='0.5', logger=None, filename=None, **kwargs)

helper function to plot first and second moment change histograms between two ensembles

Parameters:

ensemble1 (varies) – filename or pandas.DataFrame or pyemu.Ensemble
ensemble2 (varies) – filename or pandas.DataFrame or pyemu.Ensemble
pst (pyemu.Pst) – control file
facecolor (str) – the histogram facecolor.
filename (str) – the name of the multi-pdf to create. If None, return figs without saving. Default is None.

Returns:

a list of figures. Returns None is filename is not None

Return type:

[matplotlib.Figure]

Example:

pst = pyemu.Pst("my.pst")
prior = pyemu.ParameterEnsemble.from_binary(pst=pst, filename="prior.jcb")
post = pyemu.ParameterEnsemble.from_binary(pst=pst, filename="my.3.par.jcb")
pyemu.plot_utils.ensemble_change_summary(prior,post)
plt.show()

pyemu.plot.plot_utils.ensemble_helper(ensemble, bins=10, facecolor='0.5', plot_cols=None, filename=None, func_dict=None, sync_bins=True, deter_vals=None, std_window=None, deter_range=False, **kwargs)

helper function to plot ensemble histograms

Parameters:

ensemble – varies the ensemble argument can be a pandas.DataFrame or derived type or a str, which is treated as a filename. Optionally, ensemble can be a list of these types or a dict, in which case, the keys are treated as facecolor str (e.g., ‘b’, ‘y’, etc).
facecolor – str the histogram facecolor. Only applies if ensemble is a single thing
plot_cols – enumerable a collection of columns (in form of a list of parameters, or a dict with keys for parsing plot axes and values of parameters) from the ensemble(s) to plot. If None, (the union of) all cols are plotted. Default is None
filename – str the name of the pdf to create. If None, return figs without saving. Default is None.
func_dict – dict a dictionary of unary functions (e.g., np.log10 to apply to columns. Key is column name. Default is None
sync_bins – bool flag to use the same bin edges for all ensembles. Only applies if more than one ensemble is being plotted. Default is True
deter_vals – dict dict of deterministic values to plot as a vertical line. key is ensemble columnn name
std_window – float the number of standard deviations around the mean to mark as vertical lines. If None, nothing happens. Default is None
deter_range – bool flag to set xlims to deterministic value +/- std window. If True, std_window must not be None. Default is False

Example:

# plot prior and posterior par ensembles
pst = pyemu.Pst("my.pst")
prior = pyemu.ParameterEnsemble.from_binary(pst=pst, filename="prior.jcb")
post = pyemu.ParameterEnsemble.from_binary(pst=pst, filename="my.3.par.jcb")
pyemu.plot_utils.ensemble_helper(ensemble={"0.5":prior, "b":post},filename="ensemble.pdf")

#plot prior and posterior simulated equivalents to observations with obs noise and obs vals
pst = pyemu.Pst("my.pst")
prior = pyemu.ObservationEnsemble.from_binary(pst=pst, filename="my.0.obs.jcb")
post = pyemu.ObservationEnsemble.from_binary(pst=pst, filename="my.3.obs.jcb")
noise = pyemu.ObservationEnsemble.from_binary(pst=pst, filename="my.obs+noise.jcb")
pyemu.plot_utils.ensemble_helper(ensemble={"0.5":prior, "b":post,"r":noise},
                                 filename="ensemble.pdf",
                                 deter_vals=pst.observation_data.obsval.to_dict())

pyemu.plot.plot_utils.ensemble_res_1to1(ensemble, pst, facecolor='0.5', logger=None, filename=None, skip_groups=[], base_ensemble=None, **kwargs)

helper function to plot ensemble 1-to-1 plots showing the simulated range

Parameters:

ensemble (varies) – the ensemble argument can be a pandas.DataFrame or derived type or a str, which is treated as a fileanme. Optionally, ensemble can be a list of these types or a dict, in which case, the keys are treated as facecolor str (e.g., ‘b’, ‘y’, etc).
pst (pyemu.Pst) – a control file instance
facecolor (str) – the histogram facecolor. Only applies if ensemble is a single thing
filename (str) – the name of the pdf to create. If None, return figs without saving. Default is None.
base_ensemble (varies) – an optional ensemble argument for the observations + noise ensemble. This will be plotted as a transparent red bar on the 1to1 plot.

Note

the vertical bar on each plot the min-max range

Example:

pst = pyemu.Pst("my.pst")
prior = pyemu.ObservationEnsemble.from_binary(pst=pst, filename="my.0.obs.jcb")
post = pyemu.ObservationEnsemble.from_binary(pst=pst, filename="my.3.obs.jcb")
pyemu.plot_utils.ensemble_res_1to1(ensemble={"0.5":prior, "b":post})
plt.show()

pyemu.plot.plot_utils.gaussian_distribution(mean, stdev, num_pts=50)

get an x and y numpy.ndarray that spans the +/- 4 standard deviation range of a gaussian distribution with a given mean and standard deviation. useful for plotting

Parameters:

mean (float) – the mean of the distribution
stdev (float) – the standard deviation of the distribution
num_pts (int) – the number of points in the returned ndarrays. Default is 50

Returns:

numpy.ndarray: the x-values of the distribution
numpy.ndarray: the y-values of the distribution

Return type:

tuple containing

Example:

mean,std = 1.0, 2.0
x,y = pyemu.plot.gaussian_distribution(mean,std)
plt.fill_between(x,0,y)
plt.show()

pyemu.plot.plot_utils.phi_progress(pst, logger=None, filename=None, **kwargs)

make plot of phi vs number of model runs - requires available “.iobj” file generated by a PESTPP-GLM run.

Parameters:

pst (pyemu.Pst) – a control file instance
logger (pyemu.Logger) – if None, a generic one is created. Default is None
filename (str) – PDF filename to save figures to. If None, figures are returned. Default is None
kwargs (dict) – optional keyword args to pass to plotting function

Returns:

the axis the plot was made on

Return type:

matplotlib.axis

Example:

import matplotlib.pyplot as plt
import pyemu
pst = pyemu.Pst("my.pst")
pyemu.plot_utils.phi_progress(pst)
plt.show()

pyemu.plot.plot_utils.plot_id_bar(id_df, nsv=None, logger=None, **kwargs)

Plot a stacked bar chart of identifiability based on a the pyemu.ErrVar.get_identifiability() dataframe

Parameters:

id_df (pandas.DataFrame) – dataframe of identifiability
nsv (int) – number of singular values to consider
logger (pyemu.Logger, optonal) – a logger. If None, a generic one is created
kwargs (dict) – a dict of keyword arguments to pass to the plotting function

Returns:

the axis with the plot

Return type:

matplotlib.Axis

Example:

import pyemu
pest_obj = pyemu.Pst(pest_control_file)
ev = pyemu.ErrVar(jco='freyberg_jac.jcb'))
id_df = ev.get_identifiability_dataframe(singular_value=48)
pyemu.plot_utils.plot_id_bar(id_df, nsv=12, figsize=(12,4)

pyemu.plot.plot_utils.plot_jac_test(csvin, csvout, targetobs=None, filetype=None, maxoutputpages=1, outputdirectory=None)

helper function to plot results of the Jacobian test performed using the pest++ program pestpp-swp.

Parameters:

csvin (str) – name of csv file used as input to sweep, typically developed with static method pyemu.helpers.build_jac_test_csv()
csvout (str) – name of csv file with output generated by sweep, both input and output files can be specified in the pest++ control file with pyemu using: pest_object.pestpp_options[“sweep_parameter_csv_file”] = jactest_in_file.csv pest_object.pestpp_options[“sweep_output_csv_file”] = jactest_out_file.csv
targetobs ([str]) – list of observation file names to plot, each parameter used for jactest can have up to 32 observations plotted per page, throws a warning if more tha 10 pages of output are requested per parameter. If none, all observations in the output csv file are used.
filetype (str) – file type to store output, if None, plt.show() is called.
maxoutputpages (int) – maximum number of pages of output per parameter. Each page can hold up to 32 observation derivatives. If value > 10, set it to 10 and throw a warning. If observations in targetobs > 32*maxoutputpages, then a random set is selected from the targetobs list (or all observations in the csv file if targetobs=None).
outputdirectory (str) – directory to store results, if None, current working directory is used. If string is passed, it is joined to the current working directory and created if needed. If os.path is passed, it is used directly.

Note

Used in conjunction with pyemu.helpers.build_jac_test_csv() and sweep to perform a Jacobian Test and then view the results. Can generate a lot of plots so easiest to put into a separate directory and view the files.

pyemu.plot.plot_utils.plot_summary_distributions(df, ax=None, label_post=False, label_prior=False, subplots=False, figsize=(11, 8.5), pt_color='b')

helper function to plot gaussian distributions from prior and posterior means and standard deviations

Parameters:

df (pandas.DataFrame) – a dataframe and csv file. Must have columns named: ‘prior_mean’,’prior_stdev’,’post_mean’,’post_stdev’. If loaded from a csv file, column 0 is assumed to tbe the index
ax (matplotlib.pyplot.axis) – If None, and not subplots, then one is created and all distributions are plotted on a single plot
label_post (bool) – flag to add text labels to the peak of the posterior
label_prior (bool) – flag to add text labels to the peak of the prior
subplots (bool) – flag to use subplots. If True, then 6 axes per page are used and a single prior and posterior is plotted on each
figsize (tuple) – matplotlib figure size

Returns:

[`matplotlib.figure`]: list of figures
[`matplotlib.axis`]: list of axes

Return type:

tuple containing

Note

This is useful for demystifying FOSM results

if subplots is False, a single axis is returned

Example:

import matplotlib.pyplot as plt
import pyemu
pyemu.plot_utils.plot_summary_distributions("pest.par.usum.csv")
plt.show()

pyemu.plot.plot_utils.pst_helper(pst, kind=None, **kwargs)

pyemu.Pst plot helper - takes the handoff from pyemu.Pst.plot()

Parameters:

kind (str) – the kind of plot to make
**kargs (dict) – keyword arguments to pass to the plotting function and ultimately to matplotlib

Returns:

usually a combination of matplotlib.figure (s) and/or matplotlib.axis (s)

Return type:

varies

Example:

pst = pyemu.Pst("pest.pst") #assumes pest.res or pest.rei is found
pst.plot(kind="1to1")
plt.show()
pst.plot(kind="phipie")
plt.show()
pst.plot(kind="prior")
plt.show()

pyemu.plot.plot_utils.pst_prior(pst, logger=None, filename=None, **kwargs)

helper to plot prior parameter histograms implied by parameter bounds. Saves a multipage pdf named <case>.prior.pdf

Parameters:

pst (pyemu.Pst) – control file
logger (pyemu.Logger) – a logger. If None, a generic one is created.
filename (str) – PDF filename to save plots to. If None, return figs without saving. Default is None.
kwargs (dict) – additional plotting options. Accepts ‘grouper’ as dict to group parameters on to a single axis (use parameter groups if not passed),’unqiue_only’ to only show unique mean-stdev combinations within a given group. Any additional args are passed to matplotlib.

Returns:

a list of figures created.

Return type:

[matplotlib.Figure]

Example:

pst = pyemu.Pst("pest.pst")
pyemu.pst_utils.pst_prior(pst)
plt.show()

pyemu.plot.plot_utils.res_1to1(pst, logger=None, filename=None, plot_hexbin=False, histogram=False, **kwargs)

make 1-to-1 plots and also observed vs residual by observation group

Parameters:

pst (pyemu.Pst) – a control file instance
logger (pyemu.Logger) – if None, a generic one is created. Default is None
filename (str) – PDF filename to save figures to. If None, figures are returned. Default is None
hexbin (bool) – flag to use the hexbinning for large numbers of residuals. Default is False
histogram (bool) – flag to plot residual histograms instead of obs vs residual. Default is False (use matplotlib.pyplot.scatter )
kwargs (dict) – optional keyword args to pass to plotting function

Returns:

the axis the plot was made on

Return type:

matplotlib.axis

Example:

import matplotlib.pyplot as plt
import pyemu
pst = pyemu.Pst("my.pst")
pyemu.plot_utils.phi_progress(pst)
plt.show()

pyemu.plot.plot_utils.res_phi_pie(pst, logger=None, **kwargs)

plot current phi components as a pie chart.

Parameters:

pst (pyemu.Pst) – a control file instance with the residual datafrane instance available.
logger (pyemu.Logger) – a logger. If None, a generic one is created
kwargs (dict) –
a dict of plotting options. Accepts ‘include_zero’ as a flag to include phi groups with only zero-weight obs (not sure why anyone would do this, but whatevs).

Also accepts ‘label_comps’: list of components for the labels. Options are [‘name’, ‘phi_comp’, ‘phi_percent’]. Labels will use those three components in the order of the ‘label_comps’ list.

Any additional args are passed to matplotlib.

Returns:

the axis with the plot.

Return type:

matplotlib.Axis

Example:

import pyemu
pst = pyemu.Pst("my.pst")
pyemu.plot_utils.res_phi_pie(pst,figsize=(12,4))
pyemu.plot_utils.res_phi_pie(pst,label_comps = ['name','phi_percent'], figsize=(12,4))

Module contents

plot module contains helpers for plotting various aspect of pyemu.