search

stan-dev / cmdstanpy

CmdStanPy is a lightweight interface to Stan for Python users which provides the necessary objects and functions to compile a Stan program and fit the model to data using CmdStan.
BSD 3-Clause "New" or "Revised" License
149 stars 67 forks source link

doc default arguments for Pathfinder #736

Open bob-carpenter opened 4 months ago

bob-carpenter commented 4 months ago

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 commented 4 months ago

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 commented 4 months ago

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 commented 4 months ago

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!