README.md

mctq

Overview

mctq is an R package that provides a complete toolkit to process the Munich ChronoType Questionnaire (MCTQ), a quantitative and validated tool to assess chronotypes using individuals’ sleep behavior, as presented by Till Roenneberg, Anna Wirz-Justice, and Martha Merrow in 2003. Its aim is to facilitate the work of sleep and chronobiology scientists with MCTQ data and improve reproducibility in research.

mctq adheres to the tidyverse principles and integrates with the tidyverse ecosystem.

Learn more about the MCTQ questionnaire at https://www.thewep.org/documentations/mctq.

Why an R package for a questionnaire?

Although it may seem like a simple questionnaire, MCTQ requires extensive date/time manipulation, which poses challenges for many scientists. The mctq package addresses this issue by providing tools to handle the processing tasks for the three MCTQ versions (standard, micro, and shift) with few dependencies, relying mainly on the lubridate and hms packages from tidyverse.

We designed mctq with user experience in mind, creating an interface that resembles the questionnaire data as shown in MCTQ publications and providing extensive documentation about each computation proposed by the MCTQ authors. The package also includes fictional datasets for testing and learning purposes.

Prerequisites

You need some familiarity with the R programming language and the lubridate and hms packages from tidyverse to use mctq’s main functions.

If you are new to R, we recommend Hadley Wickham and Garrett Grolemund’s free online book R for Data Science and the Coursera course from Johns Hopkins University Data Science: Foundations using R (free for audit students).

Please refer to the lubridate and hms documentation to learn more about handling date/time data in R. We also recommend reading the Dates and times chapter from Wickham & Grolemund’s book R for Data Science.

Installation

You can install the released version of mctq from CRAN with:

install.packages("mctq")

And the development version from GitHub with:

# install.packages("remotes")
remotes::install_github("ropensci/mctq")

Usage

mctq uses the lubridate and hms packages, which provide special objects to handle date/time values in R. Ensure your dataset conforms to this structure before using mctq. Refer to the respective package documentation for more details.

Because of the circular nature of time, using appropriate temporal objects is crucial to avoid computation mistakes while adapting data from a base 10 to a base 12 numerical system.

For detailed usage instructions, visit our Get started guide.

Workdays and work-free days variables

After preparing your data, use the following mctq functions to process it. The function names follow the patterns used in MCTQ publications, making it easy to apply the necessary computations:

• fd(): compute MCTQ work-free days.
• so(): compute MCTQ local time of sleep onset.
• gu(): compute MCTQ local time of getting out of bed.
• sdu(): compute MCTQ sleep duration.
• tbt(): compute MCTQ total time in bed.
• msl(): compute MCTQ local time of mid-sleep.
• napd(): compute MCTQ nap duration (only for MCTQ Shift).
• sd24(): compute MCTQ 24 hours sleep duration (only for MCTQ Shift).

Example:

# Local time of preparing to sleep on workdays
sprep_w <- c(hms::parse_hm("23:45"), hms::parse_hm("02:15"))
# Sleep latency or time to fall asleep after preparing to sleep on workdays
slat_w <- c(lubridate::dminutes(30), lubridate::dminutes(90))
# Local time of sleep onset on workdays
so(sprep_w, slat_w)
#> 00:15:00
#> 03:45:00

Combining workdays and work-free days variables

For computations combining workdays and work-free days, use:

• sd_week(): compute MCTQ average weekly sleep duration.
• sd_overall(): compute MCTQ overall sleep duration (only for MCTQ Shift).
• sloss_week(): compute MCTQ weekly sleep loss.
• le_week(): compute MCTQ average weekly light exposure.
• msf_sc(): compute MCTQ chronotype or sleep-corrected local time of mid-sleep on work-free days.
• sjl() and sjl_rel(): compute MCTQ social jet lag.
• sjl_sc() and sjl_sc_rel(): compute Jankowski’s MCTQ sleep-corrected social jetlag.
• sjl_weighted(): compute MCTQ absolute social jetlag across all shifts (only for MCTQ Shift).

Example:

# Local time of mid-sleep on workdays
msw <- c(hms::parse_hm("02:05"), hms::parse_hm("04:05"))
# Local time of mid-sleep on work-free days
msf <- c(hms::parse_hm("23:05"), hms::parse_hm("08:30"))
# Relative social jetlag
sjl_rel(msw, msf)
#> [1] "-10800s (~-3 hours)"  "15900s (~4.42 hours)"

Utilities

mctq includes utility tools to help with your MCTQ data and provides fictional datasets for the standard, micro, and shift MCTQ versions for testing and learning purposes.

All functions are documented with guidelines behind the computations. Click here to see the full list.

Citation

If you use mctq in your research, please consider citing it. We put significant effort into building and maintaining this free and open-source R package. Find the citation below.

citation("mctq")
#> To cite {mctq} in publications use:
#> 
#>   Vartanian, D. (2024). {mctq}: Munich ChronoType Questionnaire tools
#>   (Version 0.3.2.9001) [Computer software - R package]. CRAN; rOpenSci.
#>   https://doi.org/10.32614/CRAN.package.mctq
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Misc{,
#>     title = {{mctq}: Munich ChronoType Questionnaire tools},
#>     author = {Daniel Vartanian},
#>     year = {2024},
#>     publisher = {CRAN; rOpenSci},
#>     doi = {10.32614/CRAN.package.mctq},
#>     note = {R package version 0.3.2.9001},
#>   }

Contributing

We welcome contributions, including bug reports. Take a moment to review our Guidelines for Contributing.

Acknowledgments

The initial development of mctq was supported by a scholarship from the University of Sao Paulo (USP) (❤️).

The mctq hex logo is based on an illustration by hilda design matters Zurich for the Daylight Academy (DLA).

Become an mctq supporter!

Click here to make a donation. Please indicate the mctq package in your donation message.