Repository files navigation

mctq is an R package that provides a complete toolkit to process theMunich ChronoType Questionnaire (MCTQ), a quantitative and validatedtool to assess chronotypes using individuals’ sleep behavior, aspresented by Till Roenneberg, Anna Wirz-Justice, and Martha Merrow in2003. Its aim is tofacilitate the work of sleep and chronobiology scientists with MCTQ dataand improve reproducibility in research.

mctq adheres to thetidyverseprinciples andintegrates with thetidyverse ecosystem.

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

Although it may seem like a simple questionnaire, MCTQ requiresextensive date/time manipulation, which poses challenges for manyscientists. Themctq package addresses this issue by providing toolsto handle the processing tasks for the three MCTQ versions (standard,micro, and shift) with few dependencies, relying mainly on thelubridate andhms packages fromtidyverse.

We designedmctq with user experience in mind, creating an interfacethat resembles the questionnaire data as shown in MCTQ publications andproviding extensive documentation about each computation proposed by theMCTQ authors. The package also includes fictional datasets for testingand learning purposes.

You need some familiarity with theR programminglanguage and thelubridate andhms packages fromtidyverse to usemctq’s main functions.

If you are new to R, we recommend Hadley Wickham and Garrett Grolemund’sfree online bookR for Data Science and theCoursera course from Johns Hopkins UniversityData Science: FoundationsusingR(free for audit students).

Please refer to thelubridate andhms documentation to learn more abouthandling date/time data in R. We also recommend reading theDates andtimes chapter from Wickham &Grolemund’s bookR for Data Science.

You can install the released version ofmctq fromCRAN with:

install.packages("mctq")

And the development version fromGitHub with:

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

mctq uses thelubridate andhms packages, which provide specialobjects to handle date/time values in R. Ensure your dataset conforms tothis structure before usingmctq. Refer to the respective packagedocumentation for more details.

Because of thecircular nature of time,using appropriate temporal objects is crucial to avoid computationmistakes while adapting data from a base 10 to a base 12 numericalsystem.

For detailed usage instructions, visit ourGet startedguide.

After preparing your data, use the followingmctq functions to processit. 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 workdayssprep_w<- c(hms::parse_hm("23:45"),hms::parse_hm("02:15"))# Sleep latency or time to fall asleep after preparing to sleep on workdaysslat_w<- c(lubridate::dminutes(30),lubridate::dminutes(90))# Local time of sleep onset on workdaysso(sprep_w,slat_w)

00:15:0003: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 MCTQShift).
• 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 ofmid-sleep on work-free days.
• sjl() andsjl_rel(): compute MCTQ social jet lag.
• sjl_sc() andsjl_sc_rel(): compute Jankowski’s MCTQsleep-corrected social jetlag.
• sjl_weighted(): compute MCTQ absolute social jetlag across allshifts (only for MCTQ Shift).

Example:

# Local time of mid-sleep on workdaysmsw<- c(hms::parse_hm("02:05"),hms::parse_hm("04:05"))# Local time of mid-sleep on work-free daysmsf<- c(hms::parse_hm("23:05"),hms::parse_hm("08:30"))# Relative social jetlagsjl_rel(msw,msf)

[1] "-10800s (~-3 hours)"  "15900s (~4.42 hours)"

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

All functions are documented with guidelines behind the computations.Clickhere to seethe full list.

If you usemctq in your research, please consider citing it. We putsignificant effort into building and maintaining this free andopen-source R package. Find the citation below.

citation("mctq")

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

We welcome contributions, including bug reports. Take a moment to reviewourGuidelines forContributing.

The initial development ofmctq was supported by a scholarship fromtheUniversity of Sao Paulo (USP) (❤️).

Themctq hex logo is based on an illustration byhilda design mattersZurich for theDaylight Academy(DLA).

Become anmctq supporter!

Clickhere to make adonation. Please indicate themctq package in your donation message.