8.9.2. Plotting Functions
*************************

Note:

  The plotting functions are not part of the "scm.params" package
  namespace and consequently will not be imported by default. They are
  mainly intended for use with the "params plot" command from the
  command line interface.

plot_residuals(datafile, outfile='default', bins=None, xmax=None, fontsize=22, dpi=200, _verbose=True, **kw)

   Plots a residuals histogram from any **residuals.dat*.

   Parameters:
   datafile : str
      Path to **residuals.dat* file

   outfile : str
      Filepath to the *.png* image to be written. Defaults to
      *datafile.png*.

   bins : int
      Number of bins for the histogram plot, Defaults to *len(x)/100*
      or *10*, whatever is larger.

   xmax : optional, float > 0
      If provided, will set the x-range to *(-xmax, xmax)*.

   fontsize : float
      Font size

   dpi : int
      DPI of the *outfile*

plot_predictions(data, outfile='default', range=None, regplot=True, kde=True, markersize=5, alpha=0.4, fontsize=20, dpi=200, figsize=8, bins=None, rcparams={}, _verbose=True, **kw)

   Plots the correlation between two distributions *x* and *y*.
   Requires the matplotlib package to be installed.

   Parameters:
   data : str or ScatterXYData
      Path to a predictions .txt file generated during a ParAMS
      optimization. By default located in
      *optimization/training_set_results/best/predictions_*.txt*.

      Can also be a ScatterXYData, in which case that is plotted.

   outfile : optional, str
      Filepath to be used for saving. By default (*None*), will call
      *plt.show()* instead -- useful for interactive plotting.

   range : optional, Tuple(float,float)
      Allows to change the x and y ranges of the plot (note that
      *xrange=yrange*).

   regplot : bool
      If *True*, will plot a solid line representing the linear
      regression fit in addition to the single data points.

   kde : bool
      Color-code the data points based on their density using a kernel
      density estimator. Requires scipy. Disable this plotting is
      slow, or the number of elements is small (<100).

   markersize : float
      Size of the plotted markers.

   alpha : 0 <= float <= 1
      Marker transparency. Always 1 if *kde`==`True*.

   fontsize : float
      Font size.

   dpi : int
      DPI of the *outfile*

   bins : int > 0
      Number of bins to use for the KDE

   rcparams : optional, dict
      Optional kwargs dict to be passed to *plt.rcParams*.

plot_history(datafile, outfile='default', linewidth=2.0, fontsize=20, markers=False, markersize=5, nan_to_zero=False, dpi=120, yscale='linear', _verbose=True, **kw)

   Plot the cost function values of test / validation sets as a
   function of total evaluations from a *history.dat*.

   Parameters:
   datafile : str
      Path to *history.dat*

   outfile : str
      Filepath to the *.png* image to be written. Defaults to
      *datafile.png*.

   linewidth : float
      Line width

   fontsize : float
      Font size of the plot

   markers : bool
      Whether to plot markers on top of the lineplot or not.

   markersize : bool
      Marker size, if "markers==True"

   nan_to_zero : bool
      Whether to convert possible *nan* / *inf* in the validation cost
      values to 0 to guarantee a continuous plot.

   dpi : int
      DPI of the *outfile*

   yscale : 'linear', 'log', 'symlog', 'logit'
      The pyplot.yscale value

plot_contributions(datafile, outfile='default', cutmin='default', n_max=100, sort=True, print_jobids=True, fontsize=20, dpi=200, _verbose=True, **kw)

   Generates a barplot based on the "contributions" from the last
   "evaluate()" call, depicting each cost function entry and it's
   respective contribution to the total cost function (see
   "Optimization.writefrequency").

   Parameters:
   datafile : str
      Path (and fname) where the plot should be stored. Will print the
      plot on screen (using matplotlib TkAgg) if *None*.

   outfile : str
      Filepath to the *.png* image to be written. Defaults to
      *datafile.png*.

   cutmin : 'default', float
      Entries with a contribution smaller than *cutmin* will not be
      plotted. If set to *default*, will set "cutmin = 5 *
      100/N_entries" (plotting everything that is 5 times larger than
      the uniform distribution).

   n_max : int
      Maximum number of entries to show. Will show the entries with
      the largest contributions first.

   sort : bool
      Whether to sort the entries by descending contributions or not.
      If *None*, will sort by the entries' index in the cost function
      instead.

   print_jobids : bool
      Whether to print the jobids of each entry on top of each bar.

   fontsize : float
      Font size.

   dpi : int
      DPI of the *outfile*
