Cmdstanr: save_warmup = TRUE doesn't put warmup draws in the output draws

[bbbales2]

I'm left to manually reading them out of the $output_files().

I can run a model:

library(cmdstanr)

model = cmdstan_model(paste0(cmdstan_path(), "/examples/bernoulli/bernoulli.stan"))

fit = model$sample(data = paste0(cmdstan_path(),
                   "/examples/bernoulli/bernoulli.data.R"),
                   cores = 4, save_warmup = TRUE)

And then I go to get the warmup draws:

> fit$draws() %>% posterior::as_draws_df() %>% nrow
[1] 4000

There should be 8000 draws there, not 4000 (4 chains with 1000 warmup 1000 post-warmup draws)

[rok-cesnovar]

You need to use fit$draws(inc_warmup=TRUE).

Is that confusing or would just need docs?

[bbbales2]

Oh weird. It's like I have to flip two switches to get a single thing to happen.

I see this was discussed and I probably thought it was okay or I woulda said something: https://github.com/stan-dev/cmdstanr/issues/123

I guess my complaint here is that the only docs I know how to access for cmdstanr are:

?model-method-*tab*

Like I can't type ?model_object

I can't type ?model_object$method

I think at this point I'm used to R packages doing all sorts of wild stuff, but then I can just go to the ol' ? and I'm good to go. But here I just got confused and made an issue.

What should I be doing to get docs on things?

[rok-cesnovar]

?CmdStanModel, ?CmdStanMCMC and such are probably the best way? I am bad at R docs so there might be easier ways.

[bbbales2]

@jgabry heeeeeeelp. I'm highly doc dependent.

[jgabry]

The doc for this would be at ?"fit-method-draws" or alternatively via ?CmdStanMCMC and clicking on the link to $draws(). I have an idea to make this better in #186.

[jgabry]

@bbbales2 can we close this now that ?draws links to the doc?

Oh weird. It's like I have to flip two switches to get a single thing to happen.

Yeah I can see why it would seem weird to set save_warmup=TRUE in $sample() and then also have to set inc_warmup=TRUE in $draws(), but I don't think the default behavior of $draws() should depend on an argument to a different method ($sample()) being TRUE or FALSE. That would be more confusing I think. (But maybe that's just me).

[bbbales2]

Yeah, the only thing I'd add is that right now the save_warmup docs look like:

"save_warmup: (logical) Should warmup iterations be saved? The default is FALSE."

I kinda want a note that says 'if you use draws, remember to add inc_warmup = TRUE' (not exactly that, but something like that).

There is an error message if you try to inc_warmup = TRUE without save_warmup = TRUE, which is good.

I guess it's also possible someone gets confused about if $summary() includes warmup or not if save_warmup is on, but that's anothe rquestion.

[jgabry]

Good points. I'll add some clarifications to the doc before closing this.

[jgabry]

Just opened a PR