Diagnostic plots

For users who have Matplotlib installed, Pints offers a number of diagnostic plots that can be used to quickly check obtained results.

Plotting functions:

Diagnosing MCMC results:

Functions

pints.plot.function(f, x, lower=None, upper=None, evaluations=20)[source]

Creates 1d plots of a LogPDF or a ErrorMeasure around a point x (i.e. a 1-dimensional plot in each direction).

Returns a matplotlib figure object and axes handle.

Parameters:

  • f – A pints.LogPDF or pints.ErrorMeasure to plot.

  • x – A point in the function’s input space.

  • lower – Optional lower bounds for each parameter, used to specify the lower bounds of the plot.

  • upper – Optional upper bounds for each parameter, used to specify the upper bounds of the plot.

  • evaluations – The number of evaluations to use in each plot.

pints.plot.function_between_points(f, point_1, point_2, padding=0.25, evaluations=20)[source]

Creates and returns a plot of a function between two points in parameter space.

Returns a matplotlib figure object and axes handle.

Parameters:

  • f – A pints.LogPDF or pints.ErrorMeasure to plot.

  • point_1 – The first point in parameter space. The method will find a line from point_1 to point_2 and plot f at several points along it.

  • point_2 – The second point.

  • padding – Specifies the amount of padding around the line segment [point_1, point_2] that will be shown in the plot.

  • evaluations – The number of evaluation along the line in parameter space.

pints.plot.surface(points, values, boundaries=None, markers='+', figsize=None)[source]

Takes irregularly spaced points and function evaluations in a two-dimensional parameter space and creates a coloured surface plot using a voronoi diagram.

Returns a matplotlib figure object and axes handle.

Parameters:

  • points – A list of (two-dimensional) points in parameter space.

  • values – The values (e.g. error measure evaluations) corresponding to these points.

  • boundaries – An optional pints.RectangularBoundaries object to restrict the area shown. If set to None boundaries will be determined from the given points.

  • markers – An optional string indicating the matplotlib markers to use to plot the points. Set to None to hide.

  • figsize – An optional tuple (width, height) that will be passed to matplotlib when creating the figure. If set to None matplotlib will use its default figure size.

MCMC Diagnostics

pints.plot.autocorrelation(samples, max_lags=100, parameter_names=None)[source]

Creates and returns an autocorrelation plot for a given markov chain or list of samples.

Returns a matplotlib figure object and axes handle.

Parameters:

  • samples – A list of samples, with shape (n_samples, n_parameters), where n_samples is the number of samples in the list and n_parameters is the number of parameters.

  • max_lags – The maximum autocorrelation lag to plot.

  • parameter_names – A list of parameter names, which will be displayed in the legend of the autocorrelation subplots. If no names are provided, the parameters are enumerated.

pints.plot.histogram(samples, kde=False, n_percentiles=None, parameter_names=None, ref_parameters=None)[source]

Takes one or more markov chains or lists of samples as input and creates and returns a plot showing histograms for each chain or list of samples.

Returns a matplotlib figure object and axes handle.

Parameters:

  • samples – A list of lists of samples, with shape (n_lists, n_samples, n_parameters), where n_lists is the number of lists of samples, n_samples is the number of samples in one list and n_parameters is the number of parameters.

  • kde – Set to True to include kernel-density estimation for the histograms.

  • n_percentiles – Shows only the middle n-th percentiles of the distribution. Default shows all samples in samples.

  • parameter_names – A list of parameter names, which will be displayed on the x-axis of the histogram subplots. If no names are provided, the parameters are enumerated.

  • ref_parameters – A set of parameters for reference in the plot. For example, if true values of parameters are known, they can be passed in for plotting.

pints.plot.pairwise(samples, kde=False, heatmap=False, opacity=None, n_percentiles=None, parameter_names=None, ref_parameters=None)[source]

Takes a markov chain or list of samples and creates a set of pairwise scatterplots for all parameters (p1 versus p2, p1 versus p3, p2 versus p3, etc.).

The returned plot is in a ‘matrix’ form, with histograms of each individual parameter on the diagonal, and scatter plots of parameters i and j on each entry (i, j) below the diagonal.

Returns a matplotlib figure object and axes handle.

Parameters:

  • samples – A list of samples, with shape (n_samples, n_parameters), where n_samples is the number of samples in the list and n_parameters is the number of parameters.

  • kde – Set to True to use kernel-density estimation for the histograms and scatter plots. Cannot use together with heatmap.

  • heatmap – Set to True to plot heatmap for the pairwise plots. Cannot be used together with kde.

  • opacity – This value can be used to manually set the opacity of the points in the scatter plots (when kde=False and heatmap=False only).

  • n_percentiles – Shows only the middle n-th percentiles of the distribution. Default shows all samples in samples.

  • parameter_names – A list of parameter names, which will be displayed on the axes of the subplots. If no names are provided, the parameters are enumerated.

  • ref_parameters – A set of parameters for reference in the plot. For example, if true values of parameters are known, they can be passed in for plotting.

pints.plot.series(samples, problem, ref_parameters=None, thinning=None)[source]

Creates and returns a plot of predicted time series for a given list of samples and a single-output or multi-output problem.

Because this method runs simulations, it can take a considerable time to run.

Returns a matplotlib figure object and axes handle.

Parameters:

  • samples – A list of samples, with shape (n_samples, n_parameters), where n_samples is the number of samples in the list and n_parameters is the number of parameters.

  • problem – A :class:pints.SingleOutputProblem or :class:pints.MultiOutputProblem of a n_parameters equal to or greater than the n_parameters of the samples. Any extra parameters present in the chain but not accepted by the SingleOutputProblem or MultiOutputProblem (for example parameters added by a noise model) will be ignored.

  • ref_parameters – A set of parameters for reference in the plot. For example, if true values of parameters are known, they can be passed in for plotting.

  • thinning – An integer exceeding zero. If specified, only every n-th sample (with n = thinning) in the samples will be used. If left at the default value None, a value will be chosen so that 200 to 400 predictions are shown.

pints.plot.trace(samples, n_percentiles=None, parameter_names=None, ref_parameters=None)[source]

Takes one or more markov chains or lists of samples as input and creates and returns a plot showing histograms and traces for each chain or list of samples.

Returns a matplotlib figure object and axes handle.

Parameters:

  • samples – A list of lists of samples, with shape (n_lists, n_samples, n_parameters), where n_lists is the number of lists of samples, n_samples is the number of samples in one list and n_parameters is the number of parameters.

  • n_percentiles – Shows only the middle n-th percentiles of the distribution. Default shows all samples in samples.

  • parameter_names – A list of parameter names, which will be displayed on the x-axis of the trace subplots. If no names are provided, the parameters are enumerated.

  • ref_parameters – A set of parameters for reference in the plot. For example, if true values of parameters are known, they can be passed in for plotting.