Enhancement request: provide additional reporter() functionality to support those writing reports in Rmarkdown

[mcguinlu]

Classification:

Enhancement Suggestion

Summary

Hi @wviechtb, following your great talk on the metafor::reporter() function at #ESMARConf2021, I've been thinking more about how I would integrate this truly fantastic functionality into my workflow. As someone who regularly writes papers in Rmarkdown, I wanted to suggest three enhancements that I feel would make it easier for me to make use of reporter(), but would not change the central aim of producing a self-contained report:

1. Having a output option that allows users to call reporter() within a larger Rmarkdown document (see this gist for an example of the current behaviour) would be very helpful, so that additional Rmarkdown text/elements could be added before/after the output from reporter() without having to use the workaround described in "Notes" below.
2. Providing an argument to allow users to subset what sections reporter() reports would also be extremely useful. This would be particularly useful as the analysis could be run in the first chunk to create the res object, then reporter(res, section = "methods") could be called in the methods and reporter(res, section = "results") in the results section of a manuscript. I've had a look at the code powering reporter() and it seems that the function is already creating each section separately, so it would just be a case of allowing users to define which of these sections are written to the final file.
3. In the current temporary markdown file, using in-line expressions rather than hard-coded numbers/values (e.g. "k=`r res$k`" rather than "k=13") would be helpful, particularly in the case where users copy the generated markdown text across to their manuscript and edit it, but then want to update the analysis. If the copied text used in-line expressions, the res object in the main manuscript could be updated without having to call reporter() and copy-paste the text again, which would remove user-changes. As most people will not look at the Rmarkdown file anyways, preferring to view the rendered version, this change should not have any major user-facing effects but would make working with the output of reporter() much easier for those writing in Rmarkdown.

I would be very happy to try and implement some of this functionality and then open a PR, but wanted to open an issue first and see what your thinking on it was!

Just to note as a discussion piece, while the above enhancements would be hugely helpful in their own right, the reason I am particularly interested in them is that they would allow for a data-driven generation of the methods/results section of a systematic review manuscript, particularly if other analytical packages provided similar reporter functions (e.g. robvis, PRISMA2020 by @nealhaddaway)

As an example, you could then have a chunk in the methods:

metafor::reporter(res, section = "methods") # Methods element of current fn

And in the results:

PRISMA2020::reporter(prisma) # Summary of included studies
metafor::reporter(res, section = "results") # Results element of current fn
robvis::reporter(rob) # Summary of ROB in included studies

Reproducible Example (if applicable)

Because Rmarkdown doesn't copy well into GitHub issues, I have created a reprex of the current behaviour of metafor::reporter() in this gist.

Notes

As a work-around to the functionality detailed in Enhancement 1, users can silently save the temp .Rmd to a user-defined direction and then include it as a child-Rmd file in a subsequent chunk.

I've created a full reprex of this workaround as a gist.

sessionInfo()

R version 3.6.1 (2019-07-05)
Platform: x86_64-w64-mingw32/x64 (64-bit)
Running under: Windows 10 x64 (build 19042)

Matrix products: default

locale:
[1] LC_COLLATE=English_United Kingdom.1252 
[2] LC_CTYPE=English_United Kingdom.1252   
[3] LC_MONETARY=English_United Kingdom.1252
[4] LC_NUMERIC=C                           
[5] LC_TIME=English_United Kingdom.1252    

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods  
[7] base     

other attached packages:
[1] metafor_2.4-0 Matrix_1.2-17

loaded via a namespace (and not attached):
 [1] Rcpp_1.0.5        highr_0.8         compiler_3.6.1   
 [4] prettyunits_1.0.2 remotes_2.2.0     tools_3.6.1      
 [7] testthat_2.3.0    digest_0.6.27     pkgbuild_1.0.6   
[10] pkgload_1.0.2     nlme_3.1-140      memoise_1.1.0    
[13] evaluate_0.14     lifecycle_0.2.0   lattice_0.20-38  
[16] rlang_0.4.9       cli_2.0.2         rstudioapi_0.11  
[19] yaml_2.2.1        xfun_0.19         stringr_1.4.0    
[22] withr_2.3.0       knitr_1.30        desc_1.2.0       
[25] fs_1.3.1          devtools_2.3.1    rprojroot_2.0.2  
[28] grid_3.6.1        glue_1.4.2        R6_2.5.0         
[31] processx_3.4.1    fansi_0.4.0       rmarkdown_2.5    
[34] sessioninfo_1.1.1 callr_3.4.3       purrr_0.3.3      
[37] magrittr_2.0.1    ps_1.3.0          ellipsis_0.3.0   
[40] htmltools_0.5.0   usethis_2.0.0     rsconnect_0.8.16 
[43] assertthat_0.2.1  stringi_1.4.6     crayon_1.3.4

[nealhaddaway]

Love this idea. I'd also suggest it could include (other) metaverse packages to generate standardised reports for methods like webscraping and search string generation. Great work!

…

________________________________ From: Luke McGuinness <[email protected]> Sent: 26 January 2021 12:53 To: wviechtb/metafor <[email protected]> Cc: nealhaddaway <[email protected]>; Mention <[email protected]> Subject: [wviechtb/metafor] Enhancement request: provide additional reporter() functionality to support those writing reports in Rmarkdown (#41) Classification: Enhancement Suggestion Summary Hi @wviechtb<https://github.com/wviechtb>, following your great talk on the metafor::reporter() function at #ESMARConf2021, I've been thinking more about how I would integrate this truly fantastic functionality into my workflow. As someone who regularly writes papers in Rmarkdown, I wanted to suggest three enhancements that I feel would make it easier for me to make use of reporter(), but would not change the central aim of producing a self-contained report: 1. Having a output option that allows users to call reporter() within a larger Rmarkdown document (see this gist for an example<https://gist.github.com/mcguinlu/a6db45964f0e0723834ae008fa29df21> of the current behaviour) would be very helpful, so that additional Rmarkdown text/elements could be added before/after the output from reporter() without having to use the workaround described in "Notes" below. 2. Providing an argument to allow users to subset what sections reporter() reports would also be extremely useful. This would be particularly useful as the analysis could be run in the first chunk to create the res object, then reporter(res, section = "methods") could be called in the methods and reporter(res, section = "results") in the results section of a manuscript. I've had a look at the code powering reporter() and it seems that the function is already creating each section separately<https://github.com/wviechtb/metafor/blob/bb3f6ad896de393c53d08c091039c8cfef2f66d3/R/reporter.rma.uni.r#L532-L537>, so it would just be a case of allowing users to define which of these sections are written to the final file. 3. In the current temporary markdown file, using in-line expressions rather than hard-coded numbers/values (e.g. "k=`r res$k`" rather than "k=13") would be helpful, particularly in the case where users copy the generated markdown text across to their manuscript and edit it, but then want to update the analysis. If the copied text used in-line expressions, the res object in the main manuscript could be updated without having to call reporter() and copy-paste the text again, which would remove user-changes. As most people will not look at the Rmarkdown file anyways, preferring to view the rendered version, this change should not have any major user-facing effects but would make working with the output of reporter() much easier for those writing in Rmarkdown. I would be very happy to try and implement some of this functionality and then open a PR, but wanted to open an issue first and see what your thinking on it was! Just to note as a discussion piece, while the above enhancements would be hugely helpful in their own right, the reason I am particularly interested in them is that they would allow for a data-driven generation of the methods/results section of a systematic review manuscript, particularly if other analytical packages provided similar reporter functions (e.g. robvis, PRISMA2020 by @nealhaddaway<https://github.com/nealhaddaway>) As an example, you could then have a chunk in the methods: metafor::reporter(res, section = "methods") # Methods element of current fn And in the results: PRISMA2020::reporter(prisma) # Summary of included studies metafor::reporter(res, section = "results") # Results element of current fn robvis::reporter(rob) # Summary of ROB in included studies Reproducible Example (if applicable) Because Rmarkdown doesn't copy well into GitHub issues, I have created a reprex of the current behaviour of metafor::reporter() in this gist.<https://gist.github.com/mcguinlu/a6db45964f0e0723834ae008fa29df21> Notes As a work-around to the functionality detailed in Enhancement 1, users can silently save the temp .Rmd to a user-defined direction and then include it as a child-Rmd file in a subsequent chunk. https://gist.github.com/mcguinlu/a6db45964f0e0723834ae008fa29df21#file-metafor_reporter_2-rmd-L31-L36 I've created a full reprex of this workaround as a gist.<https://gist.github.com/mcguinlu/a6db45964f0e0723834ae008fa29df21> sessionInfo() R version 3.6.1 (2019-07-05) Platform: x86_64-w64-mingw32/x64 (64-bit) Running under: Windows 10 x64 (build 19042) Matrix products: default locale: [1] LC_COLLATE=English_United Kingdom.1252 [2] LC_CTYPE=English_United Kingdom.1252 [3] LC_MONETARY=English_United Kingdom.1252 [4] LC_NUMERIC=C [5] LC_TIME=English_United Kingdom.1252 attached base packages: [1] stats graphics grDevices utils datasets methods [7] base other attached packages: [1] metafor_2.4-0 Matrix_1.2-17 loaded via a namespace (and not attached): [1] Rcpp_1.0.5 highr_0.8 compiler_3.6.1 [4] prettyunits_1.0.2 remotes_2.2.0 tools_3.6.1 [7] testthat_2.3.0 digest_0.6.27 pkgbuild_1.0.6 [10] pkgload_1.0.2 nlme_3.1-140 memoise_1.1.0 [13] evaluate_0.14 lifecycle_0.2.0 lattice_0.20-38 [16] rlang_0.4.9 cli_2.0.2 rstudioapi_0.11 [19] yaml_2.2.1 xfun_0.19 stringr_1.4.0 [22] withr_2.3.0 knitr_1.30 desc_1.2.0 [25] fs_1.3.1 devtools_2.3.1 rprojroot_2.0.2 [28] grid_3.6.1 glue_1.4.2 R6_2.5.0 [31] processx_3.4.1 fansi_0.4.0 rmarkdown_2.5 [34] sessioninfo_1.1.1 callr_3.4.3 purrr_0.3.3 [37] magrittr_2.0.1 ps_1.3.0 ellipsis_0.3.0 [40] htmltools_0.5.0 usethis_2.0.0 rsconnect_0.8.16 [43] assertthat_0.2.1 stringi_1.4.6 crayon_1.3.4 — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub<#41>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AKOBNXFF3GOUA7YHW6UFRPLS323OJANCNFSM4WTM6BXA>.

[wviechtb]

To begin, definitely interested in thinking about these enhancements.

With respect to 1: Would have to think about how to make this work, but I think the idea is nice.

With respect to 2: That is indeed quite trivial to add, given how the function already works.

With respect to 3: That should also not be too difficult, although I may have had some good reasoning for hard-coding the results into the report this way (or maybe not 🤷‍♂️).