This R package proposes tools for preprocessing and analyzing data collected through Ecological Momentary Assessment (EMA) or Experience Sampling Method (ESM) studies. The ‘esmtools’ package provides a range of functions to support preprocessing, to help researchers gain valuable insights from their datasets, and to help report their preprocessing practices and the quality of the preprocessing of the dataset.
It has been developed as part of a set of tools introduced by Revol and al. (in preparation). Among developed tools, you can find the ESM preprocessing Gallery (https://preprocess.esmtools.com/) which provides instructions, R code, and practical examples to preprocess your ESM dataset following a 5 steps framework.
Please remember to cite us if you find our package, framework, and resources helpful in your study:
- Revol, J., Carlier, C., Lafit, G., Verhees, M., Sels, L., & Ceulemans, E. (in preparation). Preprocessing ESM data: A step-by-step framework, reporting templates, and R code website
You can install the package like so:
install.packages("esmtools")
Once installed, you can load the package, as follows:
library(esmtools)
To learn more about the available functions and their usage, please refer to the documentation: https://package.esmtools.com/.
The calendar plot can provide a comprehensive overview of the time the data was collected, allowing you to identify periods (e.g., holidays vs. regular weeks), or detect missing observations for the whole dataset or a specific participant.
<style> .esmtools-container{ } .esmtools-container-open { border: 2px solid #2780e3; border-radius: 7px; margin: 0 -1em; padding: .4em 1em; } .esmtools-btn{ display:inline-block; padding:0.35em 1.2em; border:0.2em solid #2780e3; background-color:#2780e3; margin:0 0.3em 0.3em 0; border-radius:0.12em; box-sizing: border-box; text-decoration:none; font-family:'Roboto',sans-serif; font-weight: bold; color:#FFFFFF; text-align:center; transition: all 0.2s; margin: 4px 0px 4px 4px; } .esmtools-btn:hover{ color:#000000; background-color:#FFFFFF; } /* Highligh issue text */ .esm-issue{ font-weight: bold; color:#e61919; text-decoration: underline #e61919 2px; } /* Highlight data inspection text */ .esm-inspect{ font-weight: bold; text-decoration: underline 2px; } /* Highlight data modification text */ .esm-mod{ font-weight: bold; color:#0088a3; text-decoration: underline #0088a3 2px; } /* Warning message: hidden content */ .warning_hide{ font-weight: bold; margin: -.4em 0em 1em 2px; color: #595959; } </style> <script> function esmtools_toggleContent(button) { var parentDiv = button.parentElement; var childNodes = parentDiv.childNodes; // Toggle the 'esmtools-btn-open' class on the parent div parentDiv.classList.toggle("esmtools-container-open"); for (var i = 2; i < childNodes.length; i++) { var node = childNodes[i]; // if (!node.classList.contains("content-container")){ if (node.nodeType === Node.ELEMENT_NODE) { if (node.style.display === "none") { node.style.display = "block"; console.log("ok") } else { node.style.display = "none"; } } // } } } </script>
‘esmtools’ provides a set of RMarkdown templates that are bundled with the package. The templates are designed to assist in the reporting of the preprocessing phase and the assessment of data quality, allowing researchers to document and share their data preprocessing workflows efficiently. These templates can be accessed using the ‘esmtools::use_template()’ function, which copies the template files to your working directory. Available templates are: “preprocess_report”, “advanced_preprocess_report”, “data_quality_report”. For instance:
esmtools::use_template("preprocess_report")
For further information, please refer to the Preprocessing report and the Data characteristics report topics of the Preprocessing ESM Gallery.
Among the functions of this package, you can find functions that support reporting the preprocessing steps. For instance, you can highlight part of the text using the ‘txt()’ function:
Modification 1: The value of the x variable has been changed to …
Additionally, the ‘button()’ and ‘endbutton()’ functions from the ‘esmtools’ package delimite part of the document that can be revealed using a button. It is particularly useful to hide non-essential elements (but still important to report) to improve readibility.
print(1 + 1)
#> [1] 2print(2 + 2)
#> [1] 4
The package contains three dataset examples. The first one is a simulated dataset (‘esmdata_sim’) that is used in the ESM Preprocessing Gallery website (for further details see https://preprocess.esmtools.com/terminology.html). The second dataset (‘esmdata_raw’) is used as an illustrative dataset in the article (further details in the article). Finally, the third dataset (‘esmdata_preprocessed’), is the output of the preprocessing applied to the raw dataset. The preprocessing that was done can be found in the associated preprocessing report (for further details see the report).
There are two ways to import the datasets:
- Using the name of the dataset.
library(esmtools)
data = esmdata_raw- Importing the csv version by reconstructing the path to the file (stored in the package).
file_path = system.file("extdata", "esmdata_raw.csv", package="esmtools")
data = read.csv(file_path)To cite esmtools, please use:
- Revol, J., Carlier, C., Lafit, G., Verhees, M., Sels, L., & Ceulemans, E. (2023). Preprocessing ESM data: a step-by-step framework, tutorial website, R package, and reporting templates
For any questions, bug reports, or suggestions, please reach out to our team:
We value your feedback and are committed to improving ‘esmtools’ based on your needs and requirements.
The package source code in this repository is licensed under the GNU General Public License, version 3 license. The documentation, vignettes, and other website materials by Jordan Revol are licensed under CC BY 4.0.