diff --git a/.github/workflows/draft-pdf.yml b/.github/workflows/draft-pdf.yml new file mode 100644 index 00000000..08a5ede8 --- /dev/null +++ b/.github/workflows/draft-pdf.yml @@ -0,0 +1,23 @@ +on: [push] + +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.md + - name: Upload + uses: actions/upload-artifact@v1 + 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.pdf \ No newline at end of file diff --git a/paper.bib b/paper.bib new file mode 100644 index 00000000..c6889dca --- /dev/null +++ b/paper.bib @@ -0,0 +1,60 @@ +@Article{modelsummary, + title = {{modelsummary}: Data and Model Summaries in {R}}, + author = {Vincent Arel-Bundock}, + journal = {Journal of Statistical Software}, + year = {2022}, + volume = {103}, + number = {1}, + pages = {1--23}, + doi = {10.18637/jss.v103.i01}, +} + +@Manual{sjPlot, + title = {sjPlot: Data Visualization for Statistics in Social Science}, + author = {Daniel Lüdecke}, + note = {R package version 2.8.15}, + url = {https://CRAN.R-project.org/package=sjPlot}, +} + +@Article{see, + title = {{see}: An {R} Package for Visualizing Statistical Models}, + author = {Daniel Lüdecke and Indrajeet Patil and Mattan S. Ben-Shachar and Brenton M. Wiernik and Philip Waggoner and Dominique Makowski}, + journal = {Journal of Open Source Software}, + year = {2021}, + volume = {6}, + number = {64}, + pages = {3393}, + doi = {10.21105/joss.03393}, +} + +@Book{car, + title = {An {R} Companion to Applied Regression}, + edition = {Third}, + author = {John Fox and Sanford Weisberg}, + year = {2019}, + publisher = {Sage}, + address = {Thousand Oaks {CA}}, + url = {https://socialsciences.mcmaster.ca/jfox/Books/Companion/}, +} + +@Article{sandwich, + title = {Various Versatile Variances: An Object-Oriented Implementation of Clustered Covariances in {R}}, + author = {Achim Zeileis and Susanne K\"oll and Nathaniel Graham}, + journal = {Journal of Statistical Software}, + year = {2020}, + volume = {95}, + number = {1}, + pages = {1--36}, + doi = {10.18637/jss.v095.i01}, +} + +@Article{pbkrtest, + title = {A Kenward-Roger Approximation and Parametric Bootstrap Methods for Tests in Linear Mixed Models -- The {R} Package {pbkrtest}}, + author = {Ulrich Halekoh and S{\o}ren H{\o}jsgaard}, + journal = {Journal of Statistical Software}, + year = {2014}, + volume = {59}, + number = {9}, + pages = {1--30}, + url = {http://www.jstatsoft.org/v59/i09/}, +} diff --git a/paper.md b/paper.md new file mode 100644 index 00000000..8886bae6 --- /dev/null +++ b/paper.md @@ -0,0 +1,119 @@ +--- +title: 'jtools: Analysis and Presentation of Social Scientific Data' +tags: + - R + - social science + - regression +authors: + - name: Jacob A. Long + orcid: 0000-0002-1582-6214 + affiliation: 1 +affiliations: + - name: School of Journalism and Mass Communications, University of South Carolina, USA + index: 1 +date: 26 October 2023 +bibliography: paper.bib + +--- + +# Summary + +`jtools` is an R package designed to ease the exploration and +presentation of regression models with a focus on the needs of social scientists. +Most notably, it generates results summaries that are meant to provide some +of the conveniences of commercial software such as Stata (e.g., calculating +robust standard errors and integrating them into a results table). +Additionally, `jtools` includes plotting functions to help users better +understand and share the results and predictions from fitted regression models. + +# Statement of need + +Among the users of R are working or trainee scientists who are accustomed to +software that provides detailed and customizable summaries of regression results +"out of the box" (i.e., integrated into the modules that fit the model). While +R's `summary()` function provides useful information for many regression +models — such as the method provided for `lm()` including coefficients, +standard errors, test statistics, and *p*-values — there is typically little +flexiblity for customizing the output. Generating results summaries with +additional information, such as robust standard errors, confidence intervals, +transformed/centered variables, and variance inflation factors demands +considerably more programming knowledge and effort for the user, requiring more +time and making mistakes more likely. These same concerns exist for the case of +plotting predicted values from regression models. + +`jtools` provides an alternative to `summary()`, `summ()`, that allows users +more flexibility in generating results tables for supported regression models. +Importantly, these capabilities are accessible almost solely through +arguments to `summ()`, thereby requiring little more programming knowledge +than what is already required to fit a regression model and print a minimal +summary to the console. For plotting, the package includes `effect_plot()` +for creating line plots for a focal predictor variable. Users may add +confidence intervals (including the ability to use robust standard errors for +the plotted intervals), the observed data as plotted points, partial residuals +as plotted points, and rug plots. Categorical predictors can be plotted as +bar charts of single points with error bars as well. Finally, `jtools` features +the function `plot_coefs()` that allows users to plot regression coefficients +with confidence intervals for one or more models. This is particularly useful +for comparing nested/related model specifications. Plots are generated with +`ggplot2` — allowing knowledgeable users to further customize the appearance — +but do not require the user to know how to use `ggplot2`. + +Other R packages exist to achieve some of these ends. In some cases, `jtools` +is using third-party packages for computation and simply repackaging the results +(e.g., `sandwich` [@sandwich] for robust standard errors and `pbkrtest` for computation of +*p*-values for multilevel models). `modelsummary` provides comparable +functionality to `summ()` and has some advantages, such as a greater range +of supported models and more support for exporting to external documents. +`marginaleffects`, `sjPlot`, and `see` offer support for plotting predicted +values from fitted regression models and again have some of their own +advantages, such as more supported model types. There is also overlap in +functionality with the `car` package (e.g., the computation of variance +inflation factors and partial residuals), although `jtools` aims to improve +the user interface and support more model types in some cases. + +# Mathematics + +Single dollars ($) are required for inline mathematics e.g. $f(x) = e^{\pi/x}$ + +Double dollars make self-standing equations: + +$$\Theta(x) = \left\{\begin{array}{l} +0\textrm{ if } x < 0\cr +1\textrm{ else} +\end{array}\right.$$ + +You can also use plain \LaTeX for equations +\begin{equation}\label{eq:fourier} +\hat f(\omega) = \int_{-\infty}^{\infty} f(x) e^{i\omega x} dx +\end{equation} +and refer to \autoref{eq:fourier} from text. + +# Citations + +Citations to entries in paper.bib should be in +[rMarkdown](http://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html) +format. + +If you want to cite a software repository URL (e.g. something on GitHub without a preferred +citation) then you can do it with the example BibTeX entry below for @fidgit. + +For a quick reference, the following citation commands can be used: +- `@author:2001` -> "Author et al. (2001)" +- `[@author:2001]` -> "(Author et al., 2001)" +- `[@author1:2001; @author2:2001]` -> "(Author1 et al., 2001; Author2 et al., 2002)" + +# Figures + +Figures can be included like this: +![Caption for example figure.\label{fig:example}](figure.png) +and referenced from text using \autoref{fig:example}. + +Figure sizes can be customized by adding an optional second parameter: +![Caption for example figure.](figure.png){ width=20% } + +# Acknowledgements + +We acknowledge contributions from Brigitta Sipocz, Syrtis Major, and Semyeong +Oh, and support from Kathryn Johnston during the genesis of this project. + +# References \ No newline at end of file