Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

documentation for CmdStanPy optimization #629

Open
8 tasks
bob-carpenter opened this issue Oct 24, 2022 · 2 comments
Open
8 tasks

documentation for CmdStanPy optimization #629

bob-carpenter opened this issue Oct 24, 2022 · 2 comments

Comments

@bob-carpenter
Copy link
Contributor

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
Copy link
Member

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
Copy link
Contributor Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants