report

report copied to clipboard

Describe the solution you'd like My codebook package does, I guess, a very extensive report on a dataset. I'm using rmarkdown partials for this, i.e. markdown that is echoed with the class knit_asis. That way, I can report on something using a mixture of text, tables and graphs.

How could we do it? Maybe this is out of scope for the report package, but I already see examples in the description that would benefit from markdown capabilities (italics, symbols, combining tables with text for model summaries).

I hit a few snags when implementing this, but it now works like a charm. Here are my relevant helper functions and a simple example. It's a bit more bothersome to write tests for, but I managed to get pretty good coverage anyway.

I feel like this is a bit out of scope for now, as report's main aim is to generate a "summary" of an object in plain text. Then, what happens with this text (that can be knitted, printed, saved, copied, processed...) is (currently) left up to the user.

Altough it is true that having a postprocessing of report's outputs, dealing with some special characters and all, to better render it in rmarkdown documents would be a cool feature...

Since one uses rmarkdown to write reports, we definitely should keep this feature in mind for the report package... I have currently no clear idea how the final result could look like, but once we have some ideas how to design this feature, we may think about implementing it.

Yeah, I just threw this out there – I don't know exactly where you're planning to take this package. But I can imagine that over time you'll find yourself wanting more complexity (I've found this for the little reporter functions I wrote for myself) and then you might end up there anyway.

Plus, markdown is readable as plaintext, so you wouldn't have to do everything twice. Just set the right class on the output basically.

I'm particularly open to pursuing this again, I've got a little more time over the coming weeks. I've got a quite ugly (but functional) implementation of Rmarkdown printing working for t-tests and ANOVAs — and mostly decent support for lmer models. The issue however is that to implement a functional markdown print for all our objects could verge on beyond the scope of the pacakge (and potentially merge into the goals of papaja).

Nevertheless, even just having the current text we have be able to be called from within R Markdown / Knitr (e.g., a report_rmd(function)) for the current features would be a start. It would be logical for the text to return as coloured plain text in console, but to be able to be returned as Markdown when in the appropriate scope.

This is somewhat a note to self for next week...

hey @humanfactors I've started work on a mini package to make making partials easier. there are also some examples which demonstrate how I think is the best way to use them.

I guess having a functional markdown print for all objects could just mean that for those where nothing is implemented you get plain text output. I would think basically you export knit_print and print methods for all report outputs.

https://github.com/rubenarslan/rmdpartials

@rubenarslan @humanfactors

Thanks a lot for giving this a thought.

I think there are three aspects to consider that stem out of the three ways of displaying a report object, which are the textual form, the table form, and the plot form (that will be added through the see pkg).

• Tables

The first thing that comes into my mind when I think about a compatibility with rmarkdown is the table form. This is going to be facilitated by the recent outsourcing of some table helpers to parameters (this PR). Basically, parameters can now "nicely" print tables in the console:

library(parameters)
model <- lm(mpg ~ wt + cyl, data = mtcars)
model_parameters(model, standardize = FALSE)
#> Parameter   | Coefficient |   SE |         95% CI |     t | DoF (residual) |      p
#> -----------------------------------------------------------------------------------
#> (Intercept) |       39.69 | 1.71 | [36.18, 43.19] | 23.14 |             29 | < .001
#> wt          |       -3.19 | 0.76 | [-4.74, -1.64] | -4.22 |             29 | < .001
#> cyl         |       -1.51 | 0.41 | [-2.36, -0.66] | -3.64 |             29 |   .001

^{Created on 2019-07-20 by the reprex package (v0.3.0)}

This system will be essentially re-used in report that will add-in stuff of the performance package (R2s, etc.). Since report integrates some automated "interpretation" tools (effect size classification and so on), I woud like to add on top of that some conditional coloring (e.g., print in yellow the significant p values). This could be a challenge for the further rmarkdown conversion.

However, having in mind this rmarkdown issue here, I dissociated the actual formatting and printing of the table to the console (with the columns separators and all) from the formatting of the tables per se (improving column names, rounding values etc.).

https://github.com/easystats/parameters/blob/2e5c024ec101fe1c1e655c06c521a1ff883f5292/R/parameters_table.R#L91-L95

Essentially, a parameters (and further down the road a report) table is first "prepared" through the parameters_table() function, and then passed to the console printing. Thus, for the RMD, I believe we would simply have to pass it to a RMD table display function instead of the console printing function. We would have a beautiful, consistent, yet adapted to the context output.

However, I have no experience with RMD stuff, so I am not sure if any of this makes sense 😅

• Text

For this, I have honestly no idea how to improve the rendering of a text chunk on RMD. With colors? With a nice font?

• Plot

This should be fairly easy as the plots are ggplot-based.

(Again, I apologize for the report package is currently broken, I will fix it once parameters is finally on CRAN).

Related to https://github.com/easystats/report/issues/91