NAME:
  mcmcsamp
 PURPOSE:   (one line only)
  Markov-chain Monte-Carlo sampling tool
 DESCRIPTION:
 CATEGORY:
  Statistics
 CALLING SEQUENCE:
  mcmcsamp,vals,scale,region,pdf
 INPUTS:
  vals - n-dimensional vector with initial guess for solution
  scale - inital estimate of size of variation to sample, roughly 2x of
            the expected standard deviation.  One value per input variable.
            If burn-in is running, this input information is modified and will
            contain the final dynamically determined values.
  region - size of sampling region, roughly 5x bigger than scale.  One value
            per input variable.
 OPTIONAL INPUT PARAMETERS:
 KEYWORD INPUT PARAMETERS:
  FUNCTION_NAME - [REQUIRED!!!]  Name of function that evaluates the merit
            function being minimized and sampled.   This function must take
            a single vector of input (ie., vals) and will return a scalar
            value (typically a chi-squared metric).
  NSTEPS - Number of samples to collect in the chain.  Default=1000
  NOBURNIN - Flag, if set, will suppress any burn-in calculations and
                vals/scale are assumed to already be fully tuned and ready
                to go.  With judicious use of the input arguments you can,
                if desired, fully control the burn-in process if the built-in
                algorithm is not effective.
  VERBOSE - Flag, if set, will generate some verbose comments to be printed
             during operation.  Default is no printed output.
  DISPLAY - Flag, if set, will provide output graphics to watch the sampling
             process.
 OUTPUTS:
  pdf    - [NxM] array that is the Markov chain.  N is the dimenison of vals
             and M is the number of steps requested.
 KEYWORD OUTPUT PARAMETERS:
  ACCEPTANCE - Scalar value that is the total acceptance rate for the returned
                   chain (does not include burn-in).
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
 PROCEDURE:
 MODIFICATION HISTORY:
  2016/12/22, Written by Marc W. Buie, Southwest Research Institute with
                input from Alex Parker.
  2017/01/06, MWB, modified to allow imposing restricted domains for sampling
  2017/09/21, MWB, fixed a bug when the number of free parameters was not
                equal to three
  2020/03/30, MWB, minor modifications to plot output for only two fitted
                parameters