rstan arguments

[Andrew Gelman]

stan() has an argument called iter. It should be called n_iter. Also, the description in the help file is "A positive integer specifying how many iterations for all the chains (including warmup). The default is 2000." It should say "each chain" rather than "all the chains".

Also I think we should use n_warmup and n_thin rather than warmup and thin.

A

[Andrew Gelman]

P.S. This was a problem with releasing without me checking the latest version!

> --
>

[Ben Goodrich]

For rstan, I think it is fine to change the argument names now. Approximately no one was waiting for an official rstan release but not waiting for it to land on CRAN.

Ben

[Andrew Gelman]

Then we should change to n_iter, n_warmup, and n_thin in Stan also.
A

On Aug 30, 2012, at 9:50 PM, Jiqiang Guo wrote:

> The reason I made that change is to make it consistent with Stan
>
> Jiqiang
>
> PS. I cannot send mail to the list.

>> --
>>
>>

[Ben Goodrich]

On Thursday, August 30, 2012 9:56:14 PM UTC-4, Andrew Gelman wrote:

Then we should change to n_iter, n_warmup, and n_thin in Stan also. 

That is more dicey, given that Stan is officially released and that unofficial Stan had iter, warmup, and thin for a long time now.

Ben

[Andrew Gelman]

It's been released for about 5 minutes!  I think we can change it.  This is important to me, that the argument names make sense!

--
 
 

[Ben Goodrich]

Nothing is stopping us from changing the names, but to me, iter, warmup, and thin make as much sense as n_iter, n_warmup, and n_thin. I think anyone who has done any MCMC before would expect there to be an positive integer argument for the iterations and the thinning interval. But warmup is more difficult because it is nonstandard. I could see an experienced MCMC user thinking that warmup might be binary or something but making the connection that n_warmup was supposed to be a positive integer.

Ben

[Andrew Gelman]

To me it's important becausee it's n_chains, n_iter, n_warmup, n_thin.

--
 
 

[Ben Goodrich]

On Thursday, August 30, 2012 10:18:24 PM UTC-4, Andrew Gelman wrote:

To me it's important becausee it's n_chains, n_iter, n_warmup, n_thin.

At the moment, the command-line arguments to Stan include iter, warmup, and thin but there is no chains argument. Breaking the code for anyone who has used a prerelease of Stan is not a huge cost, but I don't really see much benefit of prefixing n_ to them. Although if we think n_warmup is better than warmup, then I would agree we should prefix all of them with n_ .

Ben

 

[Andrew Gelman]

So you're saying we could change "n_chains" to "chains".

Jiquang:  as an R expert, what do you think?  I am used to n_chains etc., but I could accept just removing "n" from all the arguments.

Too bad we didn't think of this before the release, but it's better to clear this up now than later!

--
 
 

[Jiqiang Guo]

Actually I prefer beginning with n_ overall.

Sometime with n_ is better, say, for n_iter, n_warmup, n_chains. But thin is fine since I cannot think of it can mean something else in our context. For consistency, then I would say n_thin.

I can think of that with n_ is a bit annoying for the user to input the underscore. But I am fine with it.

Jiqiang

[Andrew Gelman]

OK, then we just have to convince Ben and Bob!

> --
>

[Ben Goodrich]

I agree that the arguments to stan() should match those for Stan. Prefixing every argument that is a positive integer with n_ is not that bad, I just don't think it is good enough to justify changing a just-released Stan.

Ben

[Bob Carpenter]

n 8/30/12 9:32 PM, Andrew Gelman wrote:
> stan() has an argument called iter. It should be called n_iter.

Is the main reason to match R2WinBUGS or because
it's an R convention?

I think Jiqiang may have used R parameters to
match the command-line args in the command version.
Those have been the same for ages.

> Also, the description in the help file is "A positive integer specifying how
> many iterations for all the chains (including warmup). The default is 2000."
> It should say "each chain" rather than "all the chains".

Yup. I'll fix that in all the doc (C++ code,
manual, and RStan doc).

> Also I think we should use n_warmup and n_thin rather than warmup and thin.

I agree with Ben that it'd be OK to change these now.

- Bob

[Bob Carpenter]

All in all, a very minor point (because either
way makes sense).

On 8/30/12 10:18 PM, Andrew Gelman wrote:
> To me it's important becausee it's n_chains, n_iter, n_warmup, n_thin.

Actually, it is chains, iter, warmup, thin in Stan
at the moment :-)

Adding n_ seems very Fortran to me. It's no
big deal to change, but I prefer the command-line names
without prefixes suggesting their types.

- Bob

> --
>
>

[Bob Carpenter]

n 8/30/12 11:46 PM, Andrew Gelman wrote:
> OK, then we just have to convince Ben and Bob!

I don't think we need convincing. We just don't
see the point.

I also don't think it's worth spending any more time
on, so if it'll make Andrew and Jiqiang happy
and won't make Ben and me sad, let's do it :-)

We should do that ASAP.

And that'll take us to version 1.1.0 already, because
we'll be breaking backward compatibility in our
very first patch.

- Bob

[Ben Goodrich]

On Friday, August 31, 2012 3:37:49 AM UTC-4, Bob Carpenter wrote:

And that'll take us to version 1.1.0 already, because
we'll be breaking backward compatibility in our
very first patch.

I would say there should be a general rule that changes which break previously working code should increment the major number. Also, as a general rule, we should write the general rules down.

Ben

[Bob Carpenter]

Absolutely right. I even DID write those
rules down in the doc :-)

For me, changing the names now will be a medium
hassle for us.

-- we have to change code in R and C++ and in the
R that calls C++
-- we have to change the doc on the R and C++ side,
in the manual, on the web (actually, may not be
mentioned there explicitly), and in the manual
-- we have to release another version
-- we have to explain the change to users

It imposes a minor, but measurable negative impact
on the users having to update right out of the gate.
It's not huge, but it's not great for the trust you
need between users and developers.

And on top of all that, I like them better the way they
are, which is why I chose those names in the first place!

Having said all that, I'm not as concerned about
changing the command-line option names as I am changing
the model syntax.

- Bob

[Ben Goodrich]

On Friday, August 31, 2012 12:20:40 PM UTC-4, Bob Carpenter wrote:

It imposes a minor, but measurable negative impact
on the users having to update right out of the gate.
It's not huge, but it's not great for the trust you
need between users and developers.

We could allow iter, warmup, and thin to continue to work on the command-line but change the doc to say that the preferred arguments are now n_iter, n_warmup, and n_thin . If so, then we wouldn't have to go to Stan 2.0.0 .

Ben

[Bob Carpenter]

Excellent plan. If we can't convince Andrew that
the current versions are it's better as iter, warmup,
and thin, and do nothing, that is :-)

- Bob

[Andrew Gelman]

I'm happy to call the arguments iter, warmup, thin, and chains
or n_iter, n_warmup, n_thin, n_chains
I just want consistency.

> --
>

[Jiqiang Guo]

So the minimum change is to use chains in R instead of n_chains. 

As we have not really uploaded it to CRAN (actually I did but then I retracted),

it would have minimum effect on the users. 

Jiqiang

--

[Bob Carpenter]

Great. I like that solution a lot.

Thanks for being flexible, Andrew!

- Bob

> --
>
>