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 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 and help with research reproducibility.
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.
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 dataset. 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, along with fictional datasets for
testing and learning purposes.
You need to have some familiarity with the R programming language and with
the lubridate and hms packages from tidyverse to use 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).
Please refer to the lubridate and hms package documentation to learn more about them. These two are essential packages to deal with date/time data in R. We also recommend that you read the Dates and times chapter from Wickham & Grolemund’s book R for Data Science.
You can install the released version of mctq from CRAN with:
install.packages("mctq", dependencies = TRUE)And the development version from GitHub with:
# install.packages("remotes")
remotes::install_github("ropensci/mctq", dependencies = TRUE)mctq makes use of the lubridate and hms packages from tidyverse, which provide special
objects to deal with date/time values in R. If your dataset does not
conform to this structure, you first need to convert your data to it.
Please refer to those package documentations to learn more about
them.
Due to the circular nature of time, we strongly recommend that you use appropriate temporal objects while dealing with date/time in R. This can help you get rid of several computation mistakes while trying to adapt your data from a base 10 to a system rooted in a base 12 numerical system.
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
pattern to those used in the MCTQ publications. This 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.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:00For 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)"See a quick tour of all MCTQ main functions here.
mctq is also equipped with many 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. (2022).
#> {mctq}: an R package for the Munich ChronoType Questionnaire (v.
#> 0.3.0). https://docs.ropensci.org/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 = {2022},
#> url = {https://docs.ropensci.org/mctq/},
#> note = {(v. 0.3.0). Lifecycle: maturing},
#> }We welcome contributions, including bug reports. Take a moment to review our Guidelines for Contributing.
Please note that this package is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.
mctq is supported by the Interdisciplinary Sleep Research Group
(GIPSO) of University of Sao Paulo
(USP).
mctq hex logo was based on an illustration created 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.