WIP: JOSS paper

.github/workflows/draft-pdf.yml

@@ -0,0 +1,30 @@
+# TODO: delete this file once the paper is published
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Paper Draft
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          # This should be the path to the paper within your repo.
+          paper-path: paper/paper.md
+
+      - name: Upload
+        uses: actions/upload-artifact@v4
+        with:
+          name: paper
+          # This is the output path where Pandoc will write the compiled
+          # PDF. Note, this should be the same directory as the input
+          # paper.md
+          path: paper/paper.pdf

paper/paper.Rmd

@@ -3,6 +3,9 @@ title: "report: Automated Reporting of Results and Statistical Models in R"
 tags:
   - R
   - easystats
+  - statistical reporting
+  - tables
+  - manuscript
 authors:
 - affiliation: 1
   name: Dominique Makowski
@@ -19,24 +22,33 @@ authors:
 - affiliation: 5
   name: Daniel Lüdecke
   orcid: 0000-0002-8895-3206
-
+- affiliation: 6
+  name: Rémi Thériault
+  orcid: 0000-0003-4315-6788
+
 affiliations:
 - index: 1
   name: Nanyang Technological University, Singapore
 - index: 2
-  name: cynkra Analytics GmbH, Germany
+  name: Center for Humans and Machines, Max Planck Institute for Human Development, Berlin, Germany
 - index: 3
-  name: Ben-Gurion University of the Negev, Israel
+  name: Independent Researcher
 - index: 4
   name: Independent Researcher
 - index: 5
   name: University Medical Center Hamburg-Eppendorf, Germany
-
+- index: 6
+  name: Université du Québec à Montréal, Montréal, Canada
+
 date: "`r Sys.Date()`"
-bibliography: paper.bib
-output: rticles::joss_article
+
+output: 
+    md_document:
+      variant: "markdown"
+      preserve_yaml: true
+      standalone: true
 csl: apa.csl
-journal: JOSS
+bibliography: paper.bib
 link-citations: yes
 ---
 
@@ -47,23 +59,158 @@ knitr::opts_chunk$set(
   dpi = 300,
   comment = "#>",
   message = FALSE,
-  warning = FALSE
+  warning = FALSE,
+  results = "asis"
 )
 
+options(width = 60)
+
 library(report)
 set.seed(2016)
 ```
 
 # Summary
 
-The `{report}` package for the R programming language [@base2021] provides
+The `{report}` package is a powerful tool for researchers who use R to analyze data and create reports for publication. It bridges the gap between R's output and the formatted results to be included in a manuscript, allowing users to easily convert statistical models and data frames into textual reports that are suitable for publication. This paper provides an overview of this package, including its features, advantages, and ways to use it. We also provide examples of how the package can be used to standardize and improve results reporting in R.
 
 # Statement of Need
 
-The `{report}` package is part of `{easystats}`, a collection of R packages designed to make statistical analysis easier (@Ben-Shachar2020, @Lüdecke2020parameters, @Lüdecke2020performance, @Lüdecke2021see, @Lüdecke2019, @Makowski2019, @Makowski2020, @Patil2022datawizard). 
+Reporting results is a crucial part of scientific research. Researchers need to ensure that their results are reported accurately and clearly, so that other researchers can understand and reproduce their work. However, the process of results reporting can be time-consuming and error-prone, particularly when it comes to formatting data for publication [@nuijten2016prevalence]. The `{report}` package was developed to address this problem, providing researchers with a tool that can help standardize and improve reporting results from their workflows in R. `{report}` is part of the *easystats* ecosystem of packages that build an R framework for easy statistical modeling, visualization, and reporting [@easystatspackage].
 
 # Features
 
+The package includes several features that make it a valuable tool for researchers. It can convert statistical models and data frames into textual reports, which can be easily customized and formatted to meet the requirements of a particular journal or publication. It can also automatically report demographics information from column names. The package supports a wide range of output formats, including HTML, LaTeX, and Microsoft Word, via RMarkdown.
+
+Using this package in an analytic workflow has several advantages. First, it can help standardize results reporting across a research team or project, ensuring that everyone is using the same format and style. Second, the package can save researchers time by automating many of the tasks involved in reporting results, such as formatting tables and text. Third, the package can improve the quality of results reporting by providing users with a tool that is specifically designed for this purpose. Additionally, it prevents any copy-and-paste errors.
+
+The examples below illustrate the ease with which `{report}` can create detailed textual or tabular summaries for statistical objects.
+
+## Demographics
+
+Note that when using `rmarkdown`, setting a chunk option to `results = "asis"` will print the output as regular text, as below, for a rather seamless reading experience.
+
+```{r}
+library(report)
+
+data <- data.frame(
+  "Age" = c(22, 23, 54, 21, 8, 42, 18, 32, 24, 27, 45),
+  "Sex" = c("Intersex", "F", "F", "M", "M", "M", "F", "F", "F", "F", "F"),
+  "Gender" = c("N", "W", "W", "M", "M", "M", "W", "W", "W", "W", "W"),
+  "Race" = c(
+    "Black", NA, "White", "Asian", "Black", "Arab", "Black",
+    "White", "Asian", "Southeast Asian", "Mixed"
+  ),
+  "Education" = c(
+    "Bachelor", "PhD", "Highschool", "Master", "Bachelor",
+    "Highschool", "Highschool", "Bachelor", "Bachelor",
+    "Highschool", "Master"
+  ),
+  "Country" = c(
+    "USA", NA, "Canada", "Canada", "India", "Germany", "USA",
+    "USA", "USA", "USA", "Canada"
+  )
+)
+
+cat(paste0(
+  "This study includes data from ",
+  report_participants(data), "."
+))
+```
+
+## Models
+
+```{r, eval=FALSE}
+m_lm <- lm(mpg ~ qsec + wt, data = mtcars)
+report(m_lm)
+```
+
+::: {.blackbox data-latex=""}
+
+```{r, echo=FALSE}
+m_lm <- lm(mpg ~ qsec + wt, data = mtcars)
+report(m_lm)
+```
+
+:::
+
+```{r, eval=FALSE}
+library(lme4)
+m_lmer <- lmer(Sepal.Length ~ Petal.Length + (1 | Species), data = iris)
+report(m_lmer)
+```
+
+::: {.blackbox data-latex=""}
+
+```{r, echo=FALSE}
+library(lme4)
+m_lmer <- lmer(Sepal.Length ~ Petal.Length + (1 | Species), data = iris)
+report(m_lmer)
+```
+
+:::
+
+```{r, eval=FALSE}
+library(rstanarm)
+m_rstan <- stan_glm(mpg ~ qsec + wt, data = mtcars, refresh = 0, iter = 1000)
+report(m_rstan)
+```
+
+::: {.blackbox data-latex=""}
+
+```{r, echo=FALSE}
+library(rstanarm)
+m_rstan <- stan_glm(mpg ~ qsec + wt, data = mtcars, refresh = 0, iter = 1000)
+report(m_rstan)
+```
+
+:::
+
+## Tables
+
+If preferred, you can output the information as a table instead.
+
+```{r}
+library(insight)
+
+export_table(format_table(report_table(m_lm)), format = "markdown")
+
+export_table(format_table(report_table(m_lmer)), format = "markdown")
+
+export_table(format_table(report_table(m_rstan)), format = "markdown")
+```
+
+## Grouped Data
+
+You can also seamlessly integrate `{report}` with *tidyverse* workflows:
+
+```{r, warning=FALSE, eval=FALSE}
+library(dplyr)
+
+iris %>%
+  select(-starts_with("Sepal")) %>%
+  group_by(Species) %>%
+  report() %>%
+  summary()
+```
+
+::: {.blackbox data-latex=""}
+
+```{r, warning=FALSE, echo=FALSE}
+library(dplyr)
+
+iris %>%
+  select(-starts_with("Sepal")) %>%
+  group_by(Species) %>%
+  report() %>%
+  summary()
+```
+
+:::
+
+# Conclusion
+
+The `{report}` package is a valuable tool for researchers who use R to analyze data and create reports for publication. It can help standardize and improve results reporting while saving researchers time and improving the quality of their work.
+
 # Licensing and Availability
 
 `{report}` is licensed under the GNU General Public License (v3.0), with all source code openly developed and stored on GitHub (<https://github.com/easystats/report>), along with a corresponding issue tracker for bug reporting and feature enhancements. In the spirit of honest and open science, we encourage requests, tips for fixes, feature updates, as well as general questions and concerns via direct interaction with contributors and developers.

paper/paper.bib

@@ -126,3 +126,24 @@ @Manual{base2021
     url = {https://www.R-project.org/},
   }
 
+@article{nuijten2016prevalence,
+  title={The prevalence of statistical reporting errors in psychology (1985--2013)},
+  author={Nuijten, Mich{\`e}le B and Hartgerink, Chris HJ and Van Assen, Marcel ALM and Epskamp, Sacha and Wicherts, Jelte M},
+  journal={Behavior research methods},
+  volume={48},
+  pages={1205--1226},
+  year={2016},
+  publisher={Springer},
+  doi={doi.org/10.3758/s13428-015-0664-2}
+}
+
+@software{easystatspackage,
+  title = {{{easystats}}: Streamline Model Interpretation, Visualization, and Reporting},
+  shorttitle = {{{easystats}}},
+  author = {L\"udecke, Daniel and Makowski, Dominique and Ben-Shachar, Mattan S. and Patil, Indrajeet and Wiernik, Brenton M. and Bacher, Etienne and Thériault, Rémi },
+  date = {2023-02-04T22:06:06Z},
+  origdate = {2019-01-28T10:39:29Z},
+  url = {https://easystats.github.io/easystats/},
+  urldate = {2023-02-04},
+  version = {%s}
+}