Create custom summary.bmmfit method

[venpopov]

Currently the brms model returns a summary that include the internal terms such as constant mu, kappa2, etc

We can remove that with a bit of preprocessing - brms does the same internally for its own models.

[GidonFrischkorn]

Just to remind ourselves of the discussion we had today: We will implement this by writing a summary.bmmfit method to avoid changing any information in the fit object and keep it compatible with most of the brms post-processing.

[venpopov]

Yes, just as an example of why we really want to do this. I had never run the mixture3p model when there is setsize 1 (or I don't remember looking at the summary, maybe we did for the tutorial). I just did for testing. We did anticipate it and fixed the thetant to be a constant for setsize1, but if I didn't know why, I would be quite confused by this output:

[venpopov]

Before we dive into doing this, mayb discuss what we would like the summary to actually show.

For example, here's the summary from an example sdm model

For this particular model it actually mostly fine. I'd prefer to have it show

• mu_Intercept instead of Intercept, in line with our discussion of making all parameters explicit
• show the bmm formula instead of the brms formula
• keep the constant mu parameter, since it is part of the model that users can predict if they want
• perhaps move it to a new section called "Fixed parameters:" right under Regression Coefficients:, to avoid confusion

So my proposal for all models is:

• Change "Family:" to "Model:" and display the name of the bmm model
• Replace the formula with the bmmformula
• In regression coefficients, keep only the estimated parameters.
• In a new section "Fixed parameters", show SOME of the fixed parameters. For all models that will be:
  • mu or mu1
  • other potentially important parametrs. For the mixture3p this is thetant_SetSize1, because it is important to know if you try to calculate the p_mem and p_nt for all conditions. But you don't need to know mu5 and kappa5, since those are just tricks to use a VM distribution as a uniform. Perhaps also print "thetaguess", which is always 0, but makes it explicit. We can discuss how best to do that programmatically - maybe a part of the model info that specifies which parameters to include in the summary

Also, we can give an option summary_backend = 'bmm' or 'brms', with 'bmm' default, but people can use the brms option if they want to.

[venpopov]

Just a few notes about how brms produces the summary. Assume fit is the variable containing the model fit

• when you type fit into the console, it:

  • call the generic print() method
  • since fit is of class 'brmsfit', this calls print.brmsfit(), which is a simple fuction, ensuring that print produces the summary, so it's the same as calling summary(fit):

    function (x, digits = 2, ...) 
    {
    print(summary(x, ...), digits = digits, ...)
    }

• this then calls summary.brmsfit(), which produces a list (e.g. see str(summary(fit))) with class 'brmsummary`

• since the function above has one more print inside it, it calls print.brmssummary, which determines how the information from the summary object is displayed.

what do we need?

• we don't need print.bmmfit, since print.brmsfit will still work and call the generic summary(x,...) command
• we also don't need a complete rewrite of summary.brmsfit. We can have a function summary.bmmfit, which roughly looks like this:

summary.bmmfit <- function(object, priors = FALSE, prob = 0.95, robust = FALSE,  mc_se = FALSE, ..., backend = 'bmm') {
   # add some check about possible backends (bmm and brms only)

   # get summary object from brms, since it contains a lot of necessary information:
   out <- NextMethod('summary')

   # stop and give brms summary if user wants brms summary
   if (backend == 'brms') {
    return(out)
   }

   # out is just a list - at this point we can modify it any way we want. In a upcoming PR I have also saved the bmm model and bmm_formula objects in the output, so we can access them for info
   # here add, remove or change any parts of the summary list

   # assign bmmsummary class to handle the printing
   class(out) <- 'bmmsummary'
   out
}

and then a custom print.bmmsummary method (modifying the base code from brms:::print.brmssummary)

---

I think this will be the simplest approach

[GidonFrischkorn]

Agreed! If you want you can have a look at it. I took the more complicated road and actually looked into writing a whole summary.bmmfit function.

But I think given that we import brms your suggestion will work easiest.

I did not make much progress so far. So, if you want to feel free to have a look into this. I will get to this earliest by Tuesday or Wednesday next week.

[venpopov]

Ok, then if you don't mind I will give it ago :)

[venpopov]

Just fyi, I'm starting to work on this, so I will use the same branch