Repository files navigation

{saros} (Semi-Automatic Reporting of Ordinary Surveys) is an R packagedesigned to handle repeating surveys within the same project that occurannually or biannually. It aims to automate the process of summarizingand reporting on survey data, helping researchers save time and maintainconsistency across survey iterations. Specifically, {saros} produceshighly customizable figures, tables, analyses and complex interactivereports for a batch of possible dependent-independent relations ofpossible interest.

• Simplicity: Setting up a reporting system, in particular asemi-automated one in Quarto, can be daunting - in particular if someof the chapter authors/collaborators have little familiarity withR/Python or Quarto/RMarkdown.
  • Created figures areminimal,meaning that you are given full power to adjust them post-hoc usingusualggplot2::theme()tools, includingggplot2::set_theme().
• Flexibility:
  • Several sets of chunk templates are built in, depending on the typeof report you want. These templates are provided as data frames, soyou can easily adjust these or create your own.
  • A multitude of settings with optional glue-templating of prefixes,infixes and suffixes allows translations and adaptations.
• Consistency and reproducibility: Ensure all your outputs within achapter, a report, a project, or even an organization, use the sameformatting and structure. Figures and plots are purposely simple intheming and aesthetics, so that the end-users can specify thisthemselves:
  • When editing/rendering reports, use global options (and overridewhen necessary). For the drafted report chunks, the saros contentfunctions for plots, tables, etc use inheritance for finding itssettings:
    • If specified in the function, it will use that setting.
    • If not specified, it will check global options, which can bespecified for the chapter (qmd-file), the entire report, theentire project, or the organization’s settings.
    • If none of the above is specified, function factory defaults areused.
  • Also link creation to automatically created
  • Convenience functions set, get and reset options
  • Instead of using probabilistic AI-tools, ensure your reports alwayscome out as expected.
• Aesthetics and accessibility:
  • Opinionated, yet highly flexible, interactive {ggiraph}-basedfigures (building on ggplot2) and gt-compatible tables.
• Performance: The saros tools draft a report in 3-4 seconds. Spendthe remaining time thinking aboutwhat towrite.
  • Although built-in plotting functions use (the somewhat slowerperforming) ggplot2, it is easier for the majority to modify suchplot objects, and to expand with their own compliant plottingfunctions. One can also easily insert other base/lattice-plottingfunctions in the report-drafting templates.

1. Optionally set up your project directory fora completely newproject.
2. Clean your raw data: - Variables should be stored in the data typethat they should be displayed as (factor, ordered factor, integer,character, etc). Ordered factors will in certain outputs be kept inthe given order, whereas a set of unordered factors may bee.g. sorted_by = ".upper" (e.g values of the upper-mostcategories). - Variables should have variable labels, and sets ofvariables should have the same variable label prefix. Prefix andsuffix can be split by e.g ” - “. Usee.g. {labelled}for most operations. For advanced cleaning, seesaros.utils

• makeme()makes most types of output for your report you would need for surveys.The function can be extended with S3-methods tailored for your needs.
  • The core idea behind this function is the reusability of globaloptions, which makes it possible to globally adjust all outputs witha small switch.
• make_link()will upon rendering save a plot, dataset or any other object to diskand return a “download plot”-link with a unique (hashed) filename.
• n_range()returns the sample size range given a dataset, dependent variables andindependent variables.
  • An alternativen_range2()allows directly using a makeme() output.
• fig_height_h_barchart()estimates the best figure height for a horizontal barchart, based on adata frame, dep and indep variables, and other arguments.
  • An alternativefig_height_h_barchart2()takes amakeme(type="cat_plot").

1. Optionally specify chunk templates for what you want for each set ofrelated variables. Or use among the built-in sets of templates.
2. Optionally, create a chapter_overview (a compact description ofwhich dependent (and independent) variables goes in whichchapter-file). A data.frame where a row is a chapter. Must containat least the columns ‘chapter’ and ‘dep’. ‘dep’ usestidyselect-syntax in each cell. If not using any, all variables areprocessed and placed in the same qmd-file.Moredetails
3. Combine the raw data, chunk templates and chapter_overview to makea chapterstructure.This will create a data frame containing your report structure,which can be further tailored. Arguments torefine_chapter_overview() allows e.g ignoring:
   • non-significant bivariate relationships between dependent andindependent variables,
   • low observation counts (sample size) for categories, variables ordependent-independent cell combinations, and/or
   • variables with all NA for a given “crowd” (a target group, allothers combined, or all)
4. Draft thereport,using the output from refine_chapter_overview() and your raw data.Optionally provide a range of YAML-defaults andQMD-prefixes/suffixes to your chapter-files, index-files or fullreport-files, as well as creating chapter-datasets forcompartmentalized authoring.
5. After rendering your Quarto Project (using regular Quarto/RStudiotools), optionallybatch configure accessrestrictionsandsend out glue-tailoredemailsto institutions that have participated in your survey, now receivingpassword-protected access to their own report.
6. Having done this once for a report, you might want to create aproject template for your organization. Folder structures can bemapped to a YAMLfileso that it can later be easilycreated at once with your preferreddirectory numberingscheme.If located on e.g. Github this can bedownloaded, unzipped andplaced in a new projectfolder.

The development version fromGitHub with:

install.packages("pak")pak::pak("saros")# pak::pak("NIFU-NO/saros") # Alternatively, latest developer-version at Github

library(saros)refine_chapter_overview(data=ex_survey,chapter_overview=ex_survey_ch_overview)|>  draft_report(data=ex_survey)

• Dropping

library(saros)refine_chapter_overview(data=ex_survey,chapter_overview=ex_survey_ch_overview,chunk_templates= get_chunk_template_defaults(2),always_show_bi_for_indep="x1_sex",hide_bi_entry_if_sig_above=.05)|>  draft_report(data=ex_survey,prefix_heading_for_group= c(".variable_name_indep"="---\n"),serialized_format="qs"# qs-format, if installed, is faster than rds               )

• The auxiliary variable f_uni is included in all chapter datasets sothat the YAML-header in the QMD-file can refer to it, and chunks laterrefer to that global parameter:

---params:mesos_var:"f_uni"mesos_group:"Uni of A"# This can be replaced in a command: `quarto render ch1.qmd -P mesos_group:'Uni of A'`---

library(saros)refine_chapter_overview(data=ex_survey,chapter_overview=ex_survey_ch_overview,chunk_templates= get_chunk_template_defaults(2),always_show_bi_for_indep="x1_sex",hide_bi_entry_if_sig_above=.05)|>  draft_report(data=ex_survey,prefix_heading_for_group= c(".variable_name_indep"="---\n"),auxiliary_variables="f_uni",serialized_format="qs"               )

Outside of Norway, this package can be used in accordance with the MITlicense. However, persons affiliated with Norwegian non-profit orprofit/commercial organizations must have the explicit writtenpermission from the author for use. Simply put, if yourdepartment/organization competes with NIFU on commissioned or openresearch calls within Norway, you are probably not going to getpermission unfortunately.

• The internal code for reordering unordered factors insaros:::make_contents.cat_plot_html() has been copied (withoutpermission) from Julia Silge’s and David Robinson’s excellent{tidytext}-package.
• The code for loading all saros-packages and resolving conflicts hasbeen copied (without permission) from the tidyverse-package andadapted.

Please note that the saros project is released with aContributor CodeofConduct.By contributing to this project, you agree to abide by its terms.