We welcome contributions to the openESM database, both in the form of new datasets and improvements to existing metadata and the software infrastructure.

Adding a New Dataset

You do not need to restructure or rename your data before submitting them. Once you have checked the points below, send us the data and the documentation you have. We then annotate the variables, clean and harmonize the data, and publish the dataset on Zenodo and openESM. See the Dataset Journey for details on these steps.

Before you start

Please check that:

• The dataset meets our inclusion criteria: at least 20 participants, at least 20 possible time points, and at least 2 self-report variables measured repeatedly (see Data Documentation).
• You have permission to share the data publicly, and participants consented to data sharing.
• The data are anonymized. Because the data will be publicly available, it must not be possible to re-identify participants, even in combination with other information. Please follow the data protection rules that apply to you and your institution’s guidelines, and contact us if you are unsure.

Submission process

flowchart TD
    A(["You have ESM or daily diary data"]) --> B{"Meets inclusion criteria?"}
    B -- "No / unsure" --> Q["Contact us"]
    B -- "Yes" --> C{"Consent allows public sharing<br/>and data are anonymized?"}
    C -- "No / unsure" --> Q
    C -- "Yes" --> D{"Data already publicly available?"}
    D -- "Yes" --> E["Send us the link"]
    D -- "No" --> F["Share data via a private link"]
    E --> G{"Time to describe your variables<br/>in our format?"}
    F --> G
    G -- "No" --> H["Standard submission:<br/>send your codebook as it is"]
    G -- "Yes" --> I["Annotated submission:<br/>fill in our variable table<br/>(faster processing)"]
    H --> J(["We clean, harmonize, and publish the dataset"])
    I --> J

    style A fill:#085AB3,color:#fff,stroke:none
    style J fill:#085AB3,color:#fff,stroke:none
    style I fill:#E78A00,color:#fff,stroke:none

There are two ways to submit:

• Standard submission: send the data and your codebook in whatever form you have it. We do all the annotation.
• Annotated submission: additionally describe your variables in our format (see Variable metadata). Annotating variables takes up most of our time when adding a dataset, so annotated datasets are processed faster.

What to send

1. Data
   • CSV or Excel files are ideal. Other formats (e.g., SPSS) are also fine, but please list value labels in the codebook rather than only in the data file.
   • Include all parts you can share: the repeated measures (ESM or diary) and, if available, baseline questionnaires and passive/sensor data. Baseline data (especially demographics) and passive data are often harder to anonymize than ESM responses. Please check them carefully, and contact us if you are unsure.
   • Keep rows for prompts that were sent but not answered, if your data contain them.
   • Tell us which values indicate missing data if you use anything other than empty cells, NA, or NaN (e.g., -99).
   • If the data contain timestamps, tell us the time zone.
2. Codebook or item documentation. A table with one row per variable (e.g., Excel or CSV) is ideal, but any format is fine (e.g., a questionnaire PDF or the materials section of a paper). Please include as much detail as possible, such as exact item wording, response options and their labels, and any recoding (e.g., reverse-coded items).
3. License: by default, we publish datasets on Zenodo under CC BY 4.0.
   • If the data are already published under a license, we keep that license. It must allow redistribution and modification, as we publish a cleaned version of the data.
   • If the data are online without a license, we cannot redistribute them without your permission. By submitting, you agree to publication under CC BY 4.0, unless you choose a different open license.
   • Let us know if your consent forms restrict how the data may be reused.
4. Citation: the DOI of the paper(s) describing the data collection, or another preferred way for others to cite your data.
5. Optional: variable metadata in our format (see below).

Sharing your data

• Data already in a public repository (e.g., OSF, Zenodo): send us the link and tell us the license (see What to send).
• Data not yet public: share them through a private link, for example a private OSF project or a password-protected link from your institution’s cloud storage. If neither is available to you, contact us and we will send you an upload link.

To start, open a new dataset submission issue or contact us. Please do not attach data files to GitHub issues, as these are public.

Variable metadata (optional)

If you have the time, you can describe your variables in our format using our variable template (Excel). Fill in one row per variable in your data, and leave fields empty if you do not know them. Full field definitions are in the Data Documentation.

We add three further fields ourselves: variable_type (e.g., rating scale or binary), answer_categories (number of response options), and construct (the constructs a variable relates to, which we keep consistent across datasets).

Example

After submission

We first annotate the variables in your dataset and may contact you with questions about them. We then write a cleaning script that harmonizes variable names and formats. The cleaned data are published in the openESM Zenodo community with a DOI and become available on this website and through the R and Python packages.

FAQ

Should I include sum scores or other derived variables? Item-level data are most important. You can include derived variables as well; please note how they were computed.

What about open-text responses? Include them only if you have checked that they contain no identifying information. Otherwise, remove them before sharing.

Do I need a GitHub account? No. You can also contact us directly.

Contributing to Existing Datasets

If you find errors or have suggestions for existing datasets, please follow these steps:

1. Open an issue on the metadata GitHub repository describing the problem or suggestion.
2. If you can, fork the repository and make the changes directly.
3. Submit a pull request with your changes.

Improving the Software Infrastructure

If you have ideas for improving the openESM software infrastructure, such as the website or data processing scripts, we welcome your contributions. Please follow these steps:

1. Open an issue on the openESM GitHub repository for the website or metadata. Open an issue in the respective software package repositories to improve the software infrastructure.
2. Fork the repository and make your changes.
3. Submit a pull request with a clear description of your changes and their benefits.

Contact

If you have any questions or need help with contributions, feel free to reach out at [email address, requires JavaScript] .