doc default arguments for Pathfinder

[bob-carpenter]

Summary:

The arg = None style is used for the method pathfinder, but it would be nice if the doc listed what the default argument was.

Description:

For example, argument num_elbo_draws=None has documentation

num_elbo_draws (Optional[int]) – Number of Monte Carlo draws to evaluate ELBO.

with no indication of what the default value is.

Current Version:

1.20

[WardBrian]

We’re not always consistent with whether or not we explicitly say the defaults for the algorthmic parameters. Part of the reason we use None as a default is to avoid having to duplicate the defaults in CmdStan here.

We could add them to all the doc, but then we’re back in a situation where one can get out of sync with the other (or, if CmdStan does change them, our doc would need to say “if using version < X, the default is …”), and arguably we could just code them in (rather than having None everywhere) at that point. If I was starting over, I’d probably do that.

We could also say that the default value is the one CmdStan uses as a default, but that’s probably equally useless to not saying

[bob-carpenter]

I think we've had this discussion before!

I genuinely didn't know how to find the defaults because I didn't see anywhere that said it was using the CmdStan defaults, though I suppose I could have guessed that. Are these the right CmdStan defaults:

https://mc-stan.org/docs/cmdstan-guide/pathfinder-config.html

Is the idea that you get the defaults from whatever version of CmdStan is plugged in? I think that's more confusing than setting all the defaults in CmdStanPy and then showing them to the user in the doc. Then if CmdStan changes defaults, the behavior of CmdStanPy won't change out from under users without warning.

[WardBrian]

That’s the right link, yes. And yes, if a user doesn’t specify a value, we handle the default case by just not emitting anything and then letting cmdstan use its own default value.

This is part of the goal of making cmdstanpy independent of any specific version of cmdstan, something which isn’t fully successful, and I would argue is not necessary in Python, but has been around as a goal longer than I have!