plot_utils

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

`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:

Name	Type	Description	Default
`ensemble1`	`varies`	filename or `pandas.DataFrame` or `pyemu.Ensemble`	required
`ensemble2`	`varies`	filename or `pandas.DataFrame` or `pyemu.Ensemble`	required
`pst`	`pyemu.Pst`	control file	required
`facecolor`	`str`	the histogram facecolor.	`'0.5'`
`filename`	`str`	the name of the multi-pdf to create. If None, return figs without saving. Default is None.	`None`

Returns:

Type	Description
	[`matplotlib.Figure`]: a list of figures. Returns None is
	`filename` is not None

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()

`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:

Name	Description	Default
`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).	required
`facecolor`	str the histogram facecolor. Only applies if ensemble is a single thing	required
`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	required
`filename`	str the name of the pdf to create. If None, return figs without saving. Default is None.	required
`func_dict`	dict a dictionary of unary functions (e.g., `np.log10` to apply to columns. Key is column name. Default is None	required
`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	required
`deter_vals`	dict dict of deterministic values to plot as a vertical line. key is ensemble column name	required
`std_window`	float the number of standard deviations around the mean to mark as vertical lines. If None, nothing happens. Default is None	required
`deter_range`	bool flag to set xlims to deterministic value +/- std window. If True, std_window must not be None. Default is False	required

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())

`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:

Name	Type	Description	Default
`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).	required
`pst`	`pyemu.Pst`	a control file instance	required
`facecolor`	`str`	the histogram facecolor. Only applies if `ensemble` is a single thing	`'0.5'`
`filename`	`str`	the name of the pdf to create. If None, return figs without saving. Default is None.	`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.	`None`

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()

`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:

Name	Type	Description	Default
`mean`	`float`	the mean of the distribution	required
`stdev`	`float`	the standard deviation of the distribution	required
`num_pts`	`int`	the number of points in the returned ndarrays. Default is 50	`50`

Returns:

Type	Description
	tuple containing:
	numpy.ndarray: the x-values of the distribution
	numpy.ndarray: the y-values of the distribution

Example::

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

`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:

Name	Type	Description	Default
`pst`	`pyemu.Pst`	a control file instance	required
`logger`	`pyemu.Logger`	if None, a generic one is created. Default is None	`None`
`filename`	`str`	PDF filename to save figures to. If None, figures are returned. Default is None	`None`
`kwargs`	`dict`	optional keyword args to pass to plotting function	`{}`

Returns:

Type	Description
	`matplotlib.axis`: the axis the plot was made on

Example::

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

`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:

Name	Type	Description	Default
id_df (`pandas.DataFrame`)		dataframe of identifiability	required
`nsv`	`int`	number of singular values to consider	`None`
`logger`	`pyemu.Logger`	a logger. If None, a generic one is created	`None`
`kwargs`	`dict`	a dict of keyword arguments to pass to the plotting function	`{}`

Returns:

Type	Description
	`matplotlib.Axis`: the axis with the plot

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)

`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:

Name	Type	Description	Default
`csvin`	`str`	name of csv file used as input to sweep, typically developed with static method pyemu.helpers.build_jac_test_csv()	required
`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	required
`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 than 10 pages of output are requested per parameter. If none, all observations in the output csv file are used.	`None`
`filetype`	`str`	file type to store output, if None, plt.show() is called.	`None`
`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).	`1`
`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.	`None`

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.

`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:

Name	Type	Description	Default
`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 be the index	required
`ax`	`matplotlib.pyplot.axis`	If None, and not subplots, then one is created and all distributions are plotted on a single plot	`None`
`label_post`	`bool`	flag to add text labels to the peak of the posterior	`False`
`label_prior`	`bool`	flag to add text labels to the peak of the prior	`False`
`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	`False`
`figsize`	`tuple`	matplotlib figure size	`(11, 8.5)`

Returns:

Type	Description
	tuple containing:
	[`matplotlib.figure`]: list of figures
	[`matplotlib.axis`]: list of axes

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()

`pst_helper(pst, kind=None, **kwargs)`

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

Parameters:

Name	Type	Description	Default
`kind`	`str`	the kind of plot to make	`None`
`**kargs`	`dict`	keyword arguments to pass to the plotting function and ultimately to `matplotlib`	required

Returns:

Name	Type	Description
`varies`		usually a combination of `matplotlib.figure` (s) and/or
		`matplotlib.axis` (s)

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()

`pst_prior(pst, logger=None, filename=None, **kwargs)`

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

Parameters:

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

Returns:

Type	Description
	[`matplotlib.Figure`]: a list of figures created.

Example::

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

`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:

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

Returns:

Type	Description
	`matplotlib.axis`: the axis the plot was made on

Example::

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

`res_phi_pie(pst, logger=None, **kwargs)`

plot current phi components as a pie chart.

Parameters:

Name	Type	Description	Default
`pst`	`pyemu.Pst`	a control file instance with the residual datafrane instance available.	required
`logger`	`pyemu.Logger`	a logger. If None, a generic one is created	`None`
`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:

Type	Description
	`matplotlib.Axis`: the axis with the plot.

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))