Glossary of nouns and verbs for the package

[mjskay]

Pinging off of @jgabry's comment in #1 I thought I'd open an issue to gather thoughts on names of basic concepts in the package. Since it's easy to change names (as long as we do it before an official release) I don't think we should wait on finalizing these before continuing to build stuff, but I wanted to make sure we keep track of what names we need to discuss.

I suggest we edit this first comment to keep track of naming decisions and use discussion on this issue to make those decisions. For now I've filled in what we seem to have so far, not to suggest that these are set in stone at all.

core nouns / concepts

• chain: chain index
• iteration: within-chain index
• draw: unique index across all chains
• variable: a single variable / parameter / etc
• draws: a collection of variables, chain and iteration info, and draws

verbs / operations

• as_draws_{format}(): convert draws to {format}
• subset_draws(), subset(): select a subset of variables/iterations/chains/draws
• thin_draws(): thin draws
• summarise_draws(), summarize_draws(), summary(): compute summary measures for each variable
• extract_variable_matrix(): select a given variable and return its draws in a iterations x chains format; for use in convergence diagnostics and other summary measures
• repair_draws(): repair indices (iterations, chains, draws) of draws objects to be consistent after subsetting or related operations
• order_draws(): (re-)order draws objects after subsetting or related operations
• bind_draws: bind multiple draws objects together
• rename_variables(): change names of variables
• mutate_variables(): transform variables and add them to the draws object

If I've missed anything please edit this issue to add it.

[jgabry]

Good idea, thanks!

[paul-buerkner]

Some points to add to the discussion:

(1) The name extract_one_variable_matrix was ad-hoc to name the format which is expected by all the convergence diagnostic workhorse function (living in convergence.R for now), that is, a iteration times chain matrix. I don't necessarily like this name so we may want to come up with something else.

(2) We don't have to keep this format as the input format for the convergence diagnostic functions. Perhaps, this is a discussion for #2

(3) Likely, we are going to need four subsetting functions to subset variables, draws, iterations, and chains. Shall we simply name them subset_* (with * being one of the above), or shall we go for something else?

(4) Shall we use singular (e.g., variable) or plural (e.g., variables) for the subsetting functions?

[tjmahr]

Why not thin_draws()? Or I guess it would be thin_iterations()?

[mjskay]

Why not thin_draws()? Or I guess it would be thin_iterations()?

I could vote for that.

[jgabry]

Me too!

[paul-buerkner]

Which would be prefer? thin_draws or thin_iterations? The latter may be slightly more on point but the former would be perhaps easier to remember based on other names. I tend to favor thin_draws but I am fine with both.

[jgabry]

I'm ok with either.

For most the formats thin_iterations is more on point, but for the draws_matrix type the dimension is draw instead of iteration so thin_draws would make more sense for that, right?

[paul-buerkner]

I agree. Let's go for thin_draws then.

[paul-buerkner]

I think this issue has done its job to foster discussion of basic naming conventions on which we seem to have agreed now. Further discussions about names of newly added functions should better go in new corresponding issues instead of being done here.