documentation for CmdStanPy optimization

[bob-carpenter]

Summary:

A bunch of suggestions for making the optimization doc easier to understand.

• [ ] User's Guide: Maximum Likelihood Estimation

  • [ ] we should indicate that (a) we get penalized MLEs as well as MLE in the title and description, (b) explain that this means turning the Jacobian adjustment off, and (c) that with Jacobian adjustment off we do not get the posterior mode, aka the max a posteriori (MAP) estimate a Bayesian is likely to expect
  • [ ] we should indicate _np suffix is NumPy ndarray and _pd is a pandas data frame
  • [ ] we should break the output for running optimize, printing the _dict, printing the _np, and printing the _pd values
  • [ ] we should indicate the result is on the constrained scale

• [ ] API Docs

  • [ ] indicate that results are on the constrained scale in CmdStanMLE
  • [ ] replace forward apostrophes with back ticks to get rendered quotes (both here and above)

Current Version:

1.0.7

[WardBrian]

I'd prefer if we had your first sub-bullet fleshed out somewhere in the Stan documentation that we could link to as the authoritative source. Unfortunately it seems like the language reference page and the cmdstan user's guide page both fail to lay out those bullet points (the latter at least gets at a) and b), but seems to miss c)).

The other notes are quite useful, @mitzimorris did a similar set of clarifications for MCMC in #608

[bob-carpenter]

We might want to flesh it out elsewhere and provide a pointer, but the title shouldn't be "Maximum Likelihood"---can we switch that to "Optimization" instead? That way, the language will line up with CmdStan, too.

At the same time, it's tempting to put this all in statistical terms rather than algorithmic terms for our users. I'll leave it up to you and @mitzimorris to decide what to do.