mctq is an R package that provides a complete and consistent toolkit to process the Munich ChronoType Questionnaire (MCTQ), a quantitative and validated method to assess peoples’ sleep behavior presented by Till Roenneberg, Anna Wirz-Justice, and Martha Merrow in 2003. The aim of mctq is to facilitate the work of sleep and chronobiology scientists with MCTQ data while also helping with research reproducibility.

This package is currently under a software peer-review by the rOpenSci initiative. We plan to submit it to CRAN soon after the review process ends.

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

Although it may look like a simple questionnaire, MCTQ requires a lot of date/time manipulation. This poses a challenge for many scientists, being that most people have difficulties with date/time data, especially when dealing with an extensive set of data. The mctq package comes to address this issue.

mctq can handle the processing tasks for the three MCTQ versions (standard, micro, and shift) with few dependencies, relying much of its applications on the lubridate and hms packages from tidyverse. We also designed mctq with the user experience in mind, by creating an interface that resembles the way the questionnaire data is shown in MCTQ publications, and by providing extensive and detailed documentation about each computation proposed by the MCTQ authors. The package also includes several utility tools to deal with different time representations (e.g., decimal hours, radians) and time arithmetic issues, along with fictional datasets for testing and learning purposes.

You only need to have some familiarity with the R programming language to use the mctq main functions.

In case you don’t feel comfortable with R, we strongly recommend checking Hadley Wickham and Garrett Grolemund free and online book R for Data Science and the Coursera course from John Hopkins University Data Science: Foundations using R (free for audit students).

The first stable mctq version is already out, we’re just waiting for the software peer-review to promote it to the public. We hope that it will be available on CRAN soon. Until that moment comes, you can install it from GitHub with:

# install.packages("devtools")
devtools::install_github("gipsousp/mctq", dependencies = TRUE)

mctq works with a set of object classes specially created to hold time values. These classes can be found in the lubridate and hms packages from tidyverse. If your data do not conform to the object classes required, you can use mctq convert() function to convert it.

Here are some examples of how to convert your data using convert():

# From decimal hours to `hms`
convert(6.5, "hms", input_unit = "H")
#> 06:30:00
# From radians to `Duration`
convert(1.308997, "Duration", input_unit = "rad")
#> [1] "18000s (~5 hours)"
# From radians to decimal minutes
convert(0.2617994, "numeric", input_unit = "rad", output_unit = "M")
#> [1] 60
# From `character` `HMS` to `Duration`
convert("19:55:17", "Duration", orders = "HMS")
#> [1] "71717s (~19.92 hours)"
# From `character` `HM AM/PM ` to `hms`
convert("10:00 PM", "hms", orders = "IMp")
#> 22:00:00

After your data is set to start, just use the mctq functions below to process it.

Note that the mctq functions uses a similar naming scheme to that used in the MCTQ publications. That makes it easy to find and apply any computation necessary.

• fd(): compute MCTQ work-free days
• so(): compute MCTQ local time of sleep onset
• gu(): compute MCTQ local time of getting out of bed
• sd(): compute MCTQ sleep duration
• tbt(): compute MCTQ total time in bed
• ms(): 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_hms("23:45:00"), hms::parse_hms("02:15:00"))
# 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

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 corrected local time of mid-sleep on work-free days
• sjl_rel() and sjl(): compute MCTQ social jet lag
• 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_hms("02:05:00"), hms::parse_hms("04:05:00"))
# Local time of mid-sleep on work-free days
msf <- c(hms::parse_hms("23:05:00"), hms::parse_hms("08:30:00"))
# Relative social jetlag
sjl_rel(msw, msf)
#> [1] "-10800s (~-3 hours)"  "15900s (~4.42 hours)"

See a quick tour of all MCTQ main functions here.

In addition to convert(), mctq is also equipped with many other utility functions. The package also provides fictional datasets of the standard, micro, and shift MCTQ versions for testing and learning purposes.

All functions are well documented, showing all the guidelines behind the computations. Click here to see a list of them.

If you use mctq in your research, please consider citing it. We put a lot of work to build and maintain a free and open-source R package. You can find the mctq citation below.

citation("mctq")
#> 
#> To cite mctq in publications use:
#> 
#>   Vartanian, D., Benedito-Silva, A. A., Pedrazzoli, M. (2021). mctq: An
#>   R package for the Munich ChronoType Questionnaire. Retrieved from
#>   https://gipsousp.github.io/mctq/.
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Unpublished{,
#>     title = {mctq: An R package for the Munich ChronoType Questionnaire},
#>     author = {Daniel Vartanian and Ana Amelia Benedito-Silva and Mario Pedrazzoli},
#>     year = {2021},
#>     url = {https://gipsousp.github.io/mctq/},
#>     note = {Lifecycle: maturing},
#>   }

mctq is a community project, everyone is welcome to contribute. Take a moment to review our Guidelines for Contributing.

Please note that mctq is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.