Package 'mctq'

Compute MCTQ work-free days

Description

fd() computes the number of work-free days per week for standard and micro versions of the Munich ChronoType Questionnaire (MCTQ).

Usage

fd(wd)

Arguments

wd	An integerish numeric object or an integer object corresponding to the number of workdays per week from a standard or micro version of the MCTQ questionnaire.

Details

Standard MCTQ functions were created following the guidelines in Roenneberg, Wirz-Justice, & Merrow (2003), Roenneberg, Allebrandt, Merrow, & Vetter (2012), and from The Worldwide Experimental Platform (theWeP, n.d.).

$\mu$MCTQ functions were created following the guidelines in Ghotbi et al. (2020), in addition to the guidelines used for the standard MCTQ.

MCTQ$^{Shift}$ functions were created following the guidelines in Juda, Vetter, & Roenneberg (2013), in addition to the guidelines used for the standard MCTQ.

See the References section to learn more.

Value

An integer object corresponding to the difference between the number of days in a week (7) and the number of workdays (wd).

Guidelines

Roenneberg, Allebrandt, Merrow, & Vetter (2012) and The Worldwide Experimental Platform (n.d.) guidelines for fd() ($FD$) computation are as follows.

$FD = 7 - WD$

Where:

• $FD$ = Number of work-free days per week.

• $WD$ = Number of workdays per week ("I have a regular work schedule and work ___ days per week").

References

Ghotbi, N., Pilz, L. K., Winnebeck, E. C., Vetter, C., Zerbini, G., Lenssen, D., Frighetto, G., Salamanca, M., Costa, R., Montagnese, S., & Roenneberg, T. (2020). The $\mu$MCTQ: an ultra-short version of the Munich ChronoType Questionnaire. Journal of Biological Rhythms, 35(1), 98-110. doi:10.1177/0748730419886986

Juda, M., Vetter, C., & Roenneberg, T. (2013). The Munich ChronoType Questionnaire for shift-workers (MCTQ$^{Shift}$). Journal of Biological Rhythms, 28(2), 130-140. doi:10.1177/0748730412475041

Roenneberg T., Allebrandt K. V., Merrow M., & Vetter C. (2012). Social jetlag and obesity. Current Biology, 22(10), 939-43. doi:10.1016/j.cub.2012.03.038

Roenneberg, T., Wirz-Justice, A., & Merrow, M. (2003). Life between clocks: daily temporal patterns of human chronotypes. Journal of Biological Rhythms, 18(1), 80-90. doi:10.1177/0748730402239679

The Worldwide Experimental Platform (n.d.). MCTQ. https://www.thewep.org/documentations/mctq/

See Also

Other MCTQ functions: gu(), le_week(), msf_sc(), msl(), napd(), sd24(), sd_overall(), sd_week(), sdu(), sjl(), sjl_sc(), sjl_weighted(), so(), tbt()

Examples

## Scalar example

fd(5)
#> [1] 2 # Expected
fd(4)
#> [1] 3 # Expected
fd(as.numeric(NA))
#> [1] NA # Expected

## Vector example

fd(0:7)
#> [1] 7 6 5 4 3 2 1 0 # Expected
fd(c(1, NA))
#> [1]  6 NA # Expected

---

Compute MCTQ local time of getting out of bed

Description

gu() computes the local time of getting out of bed for standard and shift versions of the Munich ChronoType Questionnaire (MCTQ).

Usage

gu(se, si)

Arguments

se	An hms object corresponding to the local time of sleep end from a standard or shift version of the MCTQ questionnaire.
si	A Duration object corresponding to the "sleep inertia" or time to get up from a standard or shift version of the MCTQ questionnaire.

Details

Standard MCTQ functions were created following the guidelines in Roenneberg, Wirz-Justice, & Merrow (2003), Roenneberg, Allebrandt, Merrow, & Vetter (2012), and from The Worldwide Experimental Platform (theWeP, n.d.).

$\mu$MCTQ functions were created following the guidelines in Ghotbi et al. (2020), in addition to the guidelines used for the standard MCTQ.

MCTQ$^{Shift}$ functions were created following the guidelines in Juda, Vetter, & Roenneberg (2013), in addition to the guidelines used for the standard MCTQ.

See the References section to learn more.

Class requirements

The mctq package works with a set of object classes specially created to hold time values. These classes can be found in the lubridate and hms packages. Please refer to those package documentations to learn more about them.

Rounding and fractional time

Some operations may produce an output with fractional time (e.g., "19538.3828571429s (~5.43 hours)", 01:15:44.505). If you want, you can round it with mctq:::round_time().

Our recommendation is to avoid rounding, but, if you do, make sure that you only round your values after all computations are done. That way you avoid round-off errors.

Value

An hms object corresponding to the vectorized sum of se and si in a circular time frame of 24 hours.

Guidelines

Roenneberg, Allebrandt, Merrow, & Vetter (2012), Juda, Vetter, & Roenneberg (2013), and The Worldwide Experimental Platform (n.d.) guidelines for gu() ($GU$) computation are as follows.

Notes

• This computation must be applied to each section of the questionnaire.

• MCTQ$^{Shift}$ uses $TGU$ (time to get up) instead of $SI$ (sleep inertia). For the purpose of this computation, both represent the same thing.

• If you are visualizing this documentation in plain text, you may have some trouble understanding the equations. You can see this documentation on the package website.

For standard and micro versions of the MCTQ

$GU_{W/F} = SE_{W/F} + SI_{W/F}$

Where:

• $GU_{W/F}$ = Local time of getting out of bed on work or work-free days.

• $SE_{W/F}$ = Local time of sleep end on work or work-free days.

• $SI_{W/F}$ = Sleep inertia on work or work-free days ("after ___ min, I get up").

* $W$ = Workdays; $F$ = Work-free days.

For the shift version of the MCTQ

$GU_{W/F}^{M/E/N} = SE_{W/F}^{M/E/N} + TGU_{W/F}^{M/E/N}$

Where:

• $GU_{W/F}^{M/E/N}$ = Local time of getting out of bed between two days in a particular shift or between two free days after a particular shift.

• $SE_{W/F}^{M/E/N}$ = Local time of sleep end between two days in a particular shift or between two free days after a particular shift.

• $TGU_{W/F}^{M/E/N}$ = Time to get up after sleep end between two days in a particular shift or between two free days after a particular shift ("after ___ min, I get up").

* $W$ = Workdays; $F$ = Work-free days, $M$ = Morning shift; $E$ = Evening shift; $N$ = Night shift.

References

Ghotbi, N., Pilz, L. K., Winnebeck, E. C., Vetter, C., Zerbini, G., Lenssen, D., Frighetto, G., Salamanca, M., Costa, R., Montagnese, S., & Roenneberg, T. (2020). The $\mu$MCTQ: an ultra-short version of the Munich ChronoType Questionnaire. Journal of Biological Rhythms, 35(1), 98-110. doi:10.1177/0748730419886986

Juda, M., Vetter, C., & Roenneberg, T. (2013). The Munich ChronoType Questionnaire for shift-workers (MCTQ$^{Shift}$). Journal of Biological Rhythms, 28(2), 130-140. doi:10.1177/0748730412475041

Roenneberg T., Allebrandt K. V., Merrow M., & Vetter C. (2012). Social jetlag and obesity. Current Biology, 22(10), 939-43. doi:10.1016/j.cub.2012.03.038

Roenneberg, T., Wirz-Justice, A., & Merrow, M. (2003). Life between clocks: daily temporal patterns of human chronotypes. Journal of Biological Rhythms, 18(1), 80-90. doi:10.1177/0748730402239679

The Worldwide Experimental Platform (n.d.). MCTQ. https://www.thewep.org/documentations/mctq/

See Also

Other MCTQ functions: fd(), le_week(), msf_sc(), msl(), napd(), sd24(), sd_overall(), sd_week(), sdu(), sjl(), sjl_sc(), sjl_weighted(), so(), tbt()

Examples

## Scalar example

gu(hms::parse_hm("08:00"), lubridate::dminutes(10))
#> 08:10:00 # Expected
gu(hms::parse_hm("11:45"), lubridate::dminutes(90))
#> 13:15:00 # Expected
gu(hms::as_hms(NA), lubridate::dminutes(90))
#> NA # Expected

## Vector example

se <- c(hms::parse_hm("12:30"), hms::parse_hm("23:45"))
si <- c(lubridate::dminutes(10), lubridate::dminutes(70))
gu(se, si)
#> 12:40:00 # Expected
#> 00:55:00 # Expected

---

Compute MCTQ average weekly light exposure

Description

le_week() computes the average weekly light exposure for the standard version of the Munich ChronoType Questionnaire (MCTQ).

Usage

le_week(le_w, le_f, wd)

Arguments

le_w	A Duration object corresponding to the light exposure on workdays from a standard version of the MCTQ questionnaire.
le_f	A Duration object corresponding to the light exposure on work-free days from a standard version of the MCTQ questionnaire.
wd	An integerish numeric object or an integer object corresponding to the number of workdays per week from a standard version of the MCTQ questionnaire.

Details

Standard MCTQ functions were created following the guidelines in Roenneberg, Wirz-Justice, & Merrow (2003), Roenneberg, Allebrandt, Merrow, & Vetter (2012), and from The Worldwide Experimental Platform (theWeP, n.d.).

$\mu$MCTQ functions were created following the guidelines in Ghotbi et al. (2020), in addition to the guidelines used for the standard MCTQ.

MCTQ$^{Shift}$ functions were created following the guidelines in Juda, Vetter, & Roenneberg (2013), in addition to the guidelines used for the standard MCTQ.

See the References section to learn more.

Class requirements

The mctq package works with a set of object classes specially created to hold time values. These classes can be found in the lubridate and hms packages. Please refer to those package documentations to learn more about them.

Rounding and fractional time

Some operations may produce an output with fractional time (e.g., "19538.3828571429s (~5.43 hours)", 01:15:44.505). If you want, you can round it with mctq:::round_time().

Our recommendation is to avoid rounding, but, if you do, make sure that you only round your values after all computations are done. That way you avoid round-off errors.

Value

A Duration object corresponding to the vectorized weighted mean of le_w and le_f with wd and fd(wd) as weights.

Guidelines

Roenneberg, Allebrandt, Merrow, & Vetter (2012) and The Worldwide Experimental Platform (n.d.) guidelines for le_week() ($LE_{week}$) computation are as follows.

Notes

• The average weekly light exposure ($LE_{week}$) is the weighted average of the light exposure on work and work-free days in a week.

• If you are visualizing this documentation in plain text, you may have some trouble understanding the equations. You can see this documentation on the package website.

Computation

$LE_{week} = \frac{(LE_W \times WD) + (LE_F \times FD)}{7}$

Where:

• $LE_{week}$ = Average weekly light exposure.

• $LE_W$ = Light exposure on workdays.

• $LE_F$ = Light exposure on work-free days.

• $WD$ = Number of workdays per week ("I have a regular work schedule and work ___ days per week").

• $FD$ = Number of work-free days per week.

* $W$ = Workdays; $F$ = Work-free days.

References

Ghotbi, N., Pilz, L. K., Winnebeck, E. C., Vetter, C., Zerbini, G., Lenssen, D., Frighetto, G., Salamanca, M., Costa, R., Montagnese, S., & Roenneberg, T. (2020). The $\mu$MCTQ: an ultra-short version of the Munich ChronoType Questionnaire. Journal of Biological Rhythms, 35(1), 98-110. doi:10.1177/0748730419886986

Juda, M., Vetter, C., & Roenneberg, T. (2013). The Munich ChronoType Questionnaire for shift-workers (MCTQ$^{Shift}$). Journal of Biological Rhythms, 28(2), 130-140. doi:10.1177/0748730412475041

Roenneberg T., Allebrandt K. V., Merrow M., & Vetter C. (2012). Social jetlag and obesity. Current Biology, 22(10), 939-43. doi:10.1016/j.cub.2012.03.038

Roenneberg, T., Wirz-Justice, A., & Merrow, M. (2003). Life between clocks: daily temporal patterns of human chronotypes. Journal of Biological Rhythms, 18(1), 80-90. doi:10.1177/0748730402239679

The Worldwide Experimental Platform (n.d.). MCTQ. https://www.thewep.org/documentations/mctq/

See Also

Other MCTQ functions: fd(), gu(), msf_sc(), msl(), napd(), sd24(), sd_overall(), sd_week(), sdu(), sjl(), sjl_sc(), sjl_weighted(), so(), tbt()

Examples

## Scalar example

le_w <- lubridate::dhours(1.5)
le_f <- lubridate::dhours(3.7)
wd <- 5
le_week(le_w, le_f, wd)
#> [1] "7662.85714285714s (~2.13 hours)" # Expected

le_w <- lubridate::dhours(3)
le_f <- lubridate::dhours(1.5)
wd <- 6
le_week(le_w, le_f, wd)
#> [1] "10028.5714285714s (~2.79 hours)" # Expected

le_w <- lubridate::dhours(5.6)
le_f <- lubridate::as.duration(NA)
wd <- 3
le_week(le_w, le_f, wd)
#> [1] NA # Expected

## Vector example

le_w <- c(lubridate::dhours(3), lubridate::dhours(2.45))
le_f <- c(lubridate::dhours(3), lubridate::dhours(3.75))
wd <- c(4, 5)
le_week(le_w, le_f, wd)
#> [1] "10800s (~3 hours)" # Expected
#> [2] "10157.1428571429s (~2.82 hours)" # Expected

## Checking second output from vector example

if (requireNamespace("stats", quietly = TRUE)) {
    i <- 2
    x <- c(le_w[i], le_f[i])
    w <- c(wd[i], fd(wd[i]))
    lubridate::as.duration(stats::weighted.mean(x, w))
}
#> [1] "10157.1428571429s (~2.82 hours)" # Expected

## Converting the output to `hms`

le_w <- lubridate::dhours(1.25)
le_f <- lubridate::dhours(6.23)
wd <- 3
le_week(le_w, le_f, wd)
#> [1] "14744.5714285714s (~4.1 hours)" # Expected

hms::hms(as.numeric(le_week(le_w, le_f, wd)))
#> 04:05:44.571429 # Expected

## Rounding the output at the seconds level

le_w <- lubridate::dhours(3.4094)
le_f <- lubridate::dhours(6.2345)
wd <- 2
le_week(le_w, le_f, wd)
#> [1] "19538.3828571429s (~5.43 hours)" # Expected

mctq:::round_time(le_week(le_w, le_f, wd))
#> [1] "19538s (~5.43 hours)" # Expected

---

A fictional $\mu$MCTQ dataset

Description

A fictional dataset, for testing and learning purposes, composed of basic/measurable and computed variables of the Munich ChronoType Questionnaire (MCTQ) micro ($\mu$) version.

This data was created following the guidelines in Ghotbi et al. (2020), in addition to the guidelines in Roenneberg, Wirz-Justice, & Merrow (2003), Roenneberg, Allebrandt, Merrow, & Vetter (2012), Jankowski (2017), and The Worldwide Experimental Platform (n.d.). See the References and Details sections to learn more.

Usage

micro_mctq

Format

A tibble with 19 columns and 50 rows:

id

A unique integer value to identify each respondent in the dataset.

Type: Control.

R class: integer.

shift_work

A logical⁠ value indicating if the respondent has been a shift- or night-worker in the past three months. \cr \cr Statement (⁠EN⁠): "I have been a shift- or night-worker in the past three months: Yes ( ___ ) No ( ___ )". \cr \cr Type: Basic. \cr \cr R class: [⁠logical']base::logical().

wd

Number of workdays per week.

Statement (EN): "Normally, I work ___ days/week".

Type: Basic.

R class: integer.

fd

Number of work-free days per week.

Type: Computed.

R class: integer.

so_w

Local time of sleep onset on workdays.

Statement (EN): "On WORKDAYS ... I normally fall asleep at ___ : ___ AM/PM (this is NOT when you get into bed, but rather when you fall asleep)".

Type: Basic.

R class: hms.

se_w

Local time of sleep end on workdays.

Statement (EN): "On WORKDAYS ... I normally wake up at ___ : ___ AM/PM (this is NOT when you get out of bed, but rather when you wake up)".

Type: Basic.

R class: hms.

sd_w

Sleep duration on workdays.

Type: Computed.

R class: Duration.

msw

Local time of mid-sleep on workdays.

Type: Computed.

R class: hms.

so_f

Local time of sleep onset on work-free days when the respondent doesn't use an alarm clock to wake up.

Statement (EN): "On WORK-FREE DAYS when I DON'T use an alarm clock ... I normally fall asleep at ___ : ___ AM/PM (this is NOT when you get into bed, but rather when you fall asleep)".

Type: Basic.

R class: hms.

se_f

Local time of sleep end on work-free days when the respondent doesn't use an alarm clock to wake up.

Statement (EN): "On WORK-FREE DAYS when I DON'T use an alarm clock ... I normally wake up at ___ : ___ AM/PM (this is NOT when you get out of bed, but rather when you wake up)".

Type: Basic.

R class: hms.

sd_f

Sleep duration on work-free days when the respondent doesn't use an alarm clock to wake up.

Type: Computed.

R class: Duration.

msf

Local time of mid-sleep on work-free days when the respondent doesn't use an alarm clock to wake up.

Type: Computed.

R class: hms.

sd_week

Average weekly sleep duration.

Type: Computed.

R class: Duration.

sloss_week

Weekly sleep loss.

Type: Computed.

R class: Duration.

msf_sc

Sleep-corrected local time of mid-sleep on work-free days.

Type: Computed.

R class: hms.

sjl_rel

Relative social jetlag.

Type: Computed.

R class: Duration.

sjl

Absolute social jetlag.

Type: Computed.

R class: Duration.

sjl_sc_rel

Jankowski's relative sleep-corrected social jetlag.

Type: Computed.

R class: Duration.

sjl_sc

Jankowski's sleep-corrected social jetlag.

Type: Computed.

R class: Duration.

Details

micro_mctq is a tidied, validated, and transformed version of raw_data("micro_mctq.csv").

Guidelines

To learn more about the Munich ChronoType Questionnaire (MCTQ), see Roenneberg, Wirz-Justice, & Merrow (2003), Roenneberg, Allebrandt, Merrow, & Vetter (2012), Roenneberg et al. (2015), and Roenneberg, Pilz, Zerbini, & Winnebeck (2019).

To know about different MCTQ versions, see Juda, Vetter, & Roenneberg (2013) and Ghotbi et.al (2020).

To learn about the sleep-corrected social jetlag, see Jankowski (2017).

If you're curious about the variable computations and want to have access to the full questionnaire, see The Worldwide Experimental Platform (n.d.).

Data building and data wrangling

This dataset was created by randomized sampling (see random_mctq()) and by manual insertions of special cases. Its purpose is to demonstrate common cases and data issues that researchers may find in their MCTQ data, in addition to be a suggested data structure for MCTQ data.

You can see the micro_mctq build and data wrangling processes here.

Variable naming

The naming of the variables took into account the naming scheme used in MCTQ publications, in addition to the guidelines of the tidyverse style guide.

Variable classes

The mctq package works with a set of object classes specially created to hold time values. These classes can be found in the hms and lubridate package.

Duration objects

If you prefer to view Duration objects as hms objects, run pretty_mctq(micro_mctq).

Source

Created by Daniel Vartanian (package author).

References

Ghotbi, N., Pilz, L. K., Winnebeck, E. C., Vetter, C., Zerbini, G., Lenssen, D., Frighetto, G., Salamanca, M., Costa, R., Montagnese, S., & Roenneberg, T. (2020). The $\mu$MCTQ: an ultra-short version of the Munich ChronoType Questionnaire. Journal of Biological Rhythms, 35(1), 98-110. doi:10.1177/0748730419886986

Jankowski K. S. (2017). Social jet lag: sleep-corrected formula. Chronobiology International, 34(4), 531-535. doi:10.1080/07420528.2017.1299162

Juda, M., Vetter, C., & Roenneberg, T. (2013). The Munich ChronoType Questionnaire for shift-workers (MCTQ$^{Shift}$). Journal of Biological Rhythms, 28(2), 130-140. doi:10.1177/0748730412475041

Roenneberg T., Allebrandt K. V., Merrow M., & Vetter C. (2012). Social jetlag and obesity. Current Biology, 22(10), 939-43. doi:10.1016/j.cub.2012.03.038

Roenneberg, T., Keller, L. K., Fischer, D., Matera, J. L., Vetter, C., & Winnebeck, E. C. (2015). Human activity and rest in situ. In A. Sehgal (Ed.), Methods in Enzymology (Vol. 552, pp. 257-283). Academic Press. doi:10.1016/bs.mie.2014.11.028

Roenneberg, T., Pilz, L. K., Zerbini, G., & Winnebeck, E. C. (2019). Chronotype and social jetlag: a (self-) critical review. Biology, 8(3), 54. doi:10.3390/biology8030054

Roenneberg, T., Wirz-Justice, A., & Merrow, M. (2003). Life between clocks: daily temporal patterns of human chronotypes. Journal of Biological Rhythms, 18(1), 80-90. doi:10.1177/0748730402239679

The Worldwide Experimental Platform (n.d.). MCTQ. https://www.thewep.org/documentations/mctq/

See Also

Other datasets: shift_mctq, std_mctq

---

Compute MCTQ sleep-corrected local time of mid-sleep on work-free days

Description

msf_sc() computes the sleep-corrected local time of mid-sleep on work-free days for standard, micro, and shift versions of the Munich ChronoType Questionnaire (MCTQ).

When using the shift version of the MCTQ, replace the value of sd_week to sd_overall, as instructed in the Arguments section.

Usage

msf_sc(msf, sd_w, sd_f, sd_week, alarm_f)

Arguments

msf	An hms object corresponding to the local time of mid-sleep on work-free days from a standard, micro, or shift version of the MCTQ questionnaire. You can use msl() to compute it.
sd_w	A Duration object corresponding to the sleep duration on work days from a standard, micro, or shift version of the MCTQ questionnaire. You can use sdu() to compute it.
sd_f	A Duration object corresponding to the sleep duration on work-free days from a standard, micro, or shift version of the MCTQ questionnaire. You can use sdu() to compute it.
sd_week	A Duration object corresponding to the average weekly sleep duration from a standard or micro version of the MCTQ questionnaire (you can use sd_week() to compute it) or the overall sleep duration of a particular shift from a shift version of the MCTQ questionnaire (you can use sd_overall() to compute it).
alarm_f	A logical object corresponding to the alarm clock use on work-free days from a standard, micro, or shift version of the MCTQ questionnaire. Note that, if alarm_f == TRUE, msf_sc cannot be computed, msf_sc() will return NA for these cases. For the $\mu$MCTQ, this value must be set as FALSE all times, since the questionnaire considers only the work-free days when the respondent does not use an alarm (e.g., alarm_f = rep(FALSE, length(msf))).

Details

Standard MCTQ functions were created following the guidelines in Roenneberg, Wirz-Justice, & Merrow (2003), Roenneberg, Allebrandt, Merrow, & Vetter (2012), and from The Worldwide Experimental Platform (theWeP, n.d.).

$\mu$MCTQ functions were created following the guidelines in Ghotbi et al. (2020), in addition to the guidelines used for the standard MCTQ.

MCTQ$^{Shift}$ functions were created following the guidelines in Juda, Vetter, & Roenneberg (2013), in addition to the guidelines used for the standard MCTQ.

See the References section to learn more.

Class requirements

The mctq package works with a set of object classes specially created to hold time values. These classes can be found in the lubridate and hms packages. Please refer to those package documentations to learn more about them.

Rounding and fractional time

Some operations may produce an output with fractional time (e.g., "19538.3828571429s (~5.43 hours)", 01:15:44.505). If you want, you can round it with mctq:::round_time().

Our recommendation is to avoid rounding, but, if you do, make sure that you only round your values after all computations are done. That way you avoid round-off errors.

Value

An hms object corresponding to the MCTQ chronotype or sleep-corrected local time of mid-sleep on work-free days.

Guidelines

Roenneberg, Allebrandt, Merrow, & Vetter (2012), Ghotbi et al. (2020), Juda, Vetter, & Roenneberg (2013), and The Worldwide Experimental Platform (n.d.) guidelines for msf_sc() ($MSF_{sc}$) computation are as follows.

Notes

• For all cases, $MSF_{sc}$ cannot be computed if the participant wakes up with an alarm clock on work-free days ($Alarm_F$).

• For MCTQ$^{Shift}$, the computation below must be applied to each shift section of the questionnaire.

• $MSF_{sc}$ is a proxy for the subject chronotype in standard and micro versions of the MCTQ.

• The basis for estimating chronotype in shift-workers is the mid-sleep on work-free days after evening shifts ($MSF^E$). In case work schedules do not comprise evening shifts, Juda, Vetter, & Roenneberg (2013) propose to derive it from the $MSF_{sc}$ of other shifts (e.g., by using a linear model). Unfortunately, the mctq package can't help you with that, as it requires a closer look at your data.

• $MSF_{sc}$ depends on developmental and environmental conditions (e.g., age, light exposure). For epidemiological and genetic studies, $MSF_{sc}$ must be normalized for age and sex to make populations of different age and sex compositions comparable (Roenneberg, Allebrandt, Merrow, & Vetter, 2012).

• If you are visualizing this documentation in plain text, you may have some trouble understanding the equations. You can see this documentation on the package website.

For standard and micro versions of the MCTQ

$\textrm{If } Alarm_{F} = True \; , \; MSF_{sc} = \textrm{Not Available (NA)}$

$\textrm{Else if } SD_F \leq SD_W \; , \; MSF_{sc} = MSF$

$\textrm{Else } \; , \; MSF_{sc} = MSF - \frac{SD_F - SD_{week}}{2}$

Where:

• $MSF_{sc}$ = Sleep-corrected local time of mid-sleep on work-free days.

• $Alarm_{F}$ = A logical value indicating if the respondent uses an alarm clock to wake up on work-free days.

• $MSF$ = Local time of mid-sleep on work-free days.

• $SD_W$ = Sleep duration on workdays.

• $SD_F$ = Sleep duration on work-free days.

• $SD_{week}$ = Average weekly sleep duration.

* $W$ = Workdays; $F$ = Work-free days.

Note that, since:

$MSF = SO_{F} + \frac{SD_{F}}{2}$

Where:

• $MSF$ = Local time of mid-sleep on work-free days.

• $SO_{F}$ = Local time of sleep onset on work-free days.

• $SD_{F}$ = Sleep duration on work-free days.

The last condition of the $MSF_{sc}$ computation can be simplified to:

$MSF_{sc} = SO_{F} + \frac{SD_{F}}{2} - \frac{SD_{F} - SD_{week}}{2}$

$MSF_{sc} = SO_{F} + \frac{SD_{F}}{2} - \frac{SD_{F}}{2} + \frac{SD_{week}}{2}$

$MSF_{sc} = SO_{F} + \frac{SD_{week}}{2}$

For the shift version of the MCTQ

$\textrm{If } Alarm_{F}^{M/E/N} = True \; , \; MSF_{sc}^{M/E/N} = \textrm{Not Available (NA)}$

$\textrm{Else if } SD_{F}^{M/E/N} \leq SD_{W}^{M/E/N} \; , \; MSF_{sc}^{M/E/N} = MSF^{M/E/N}$

$\textrm{Else } \; , \; MSF_{sc}^{M/E/N} = MSF^{M/E/N} - \frac{SD_{F}^{M/E/N} - \emptyset SD^{M/E/N}}{2}$

Where:

• $MSF_{sc}^{M/E/N}$ = Sleep-corrected local time of mid-sleep between two free days after a particular shift.

• $Alarm_{F}^{M/E/N}$ = A logical value indicating if the respondent uses an alarm clock to wake up between two free days after a particular shift.

• $MSF^{M/E/N}$ = Local time of mid-sleep between two free days after a particular shift.

• $SD_{W}^{M/E/N}$ = Sleep duration between two days in a particular shift.

• $SD_{F}^{M/E/N}$ = Sleep duration between two free days after a particular shift.

• $\emptyset SD^{M/E/N}$ = Overall sleep duration of a particular shift.

* $W$ = Workdays; $F$ = Work-free days, $M$ = Morning shift; $E$ = Evening shift; $N$ = Night shift.

Note that, since:

$MSF^{M/E/N} = SO_{F}^{M/E/N} + \frac{SD_{F}^{M/E/N}}{2}$

Where:

• $MSF^{M/E/N}$ = Local time of mid-sleep between two free days after a particular shift.

• $SO_{F}^{M/E/N}$ = Local time of sleep onset between two free days after a particular shift.

• $SD_{F}^{M/E/N}$ = Sleep duration between two free days after a particular shift.

The last condition of the $MSF_{sc}^{M/E/N}$ computation can be simplified to:

$MSF_{sc}^{M/E/N} = SO_{F}^{M/E/N} + \frac{SD_{F}^{M/E/N}}{2} - \frac{SD_{F}^{M/E/N} - \emptyset SD^{M/E/N}}{2}$

$MSF_{sc}^{M/E/N} = SO_{F}^{M/E/N} + \frac{SD_{F}^{M/E/N}}{2} - \frac{SD_{F}^{M/E/N}}{2} + \frac{\emptyset SD^{M/E/N}}{2}$

$MSF_{sc}^{M/E/N} = SO_{F}^{M/E/N} + \frac{\emptyset SD^{M/E/N}}{2}$

References

Ghotbi, N., Pilz, L. K., Winnebeck, E. C., Vetter, C., Zerbini, G., Lenssen, D., Frighetto, G., Salamanca, M., Costa, R., Montagnese, S., & Roenneberg, T. (2020). The $\mu$MCTQ: an ultra-short version of the Munich ChronoType Questionnaire. Journal of Biological Rhythms, 35(1), 98-110. doi:10.1177/0748730419886986

Juda, M., Vetter, C., & Roenneberg, T. (2013). The Munich ChronoType Questionnaire for shift-workers (MCTQ$^{Shift}$). Journal of Biological Rhythms, 28(2), 130-140. doi:10.1177/0748730412475041

Roenneberg T., Allebrandt K. V., Merrow M., & Vetter C. (2012). Social jetlag and obesity. Current Biology, 22(10), 939-43. doi:10.1016/j.cub.2012.03.038

Roenneberg, T., Wirz-Justice, A., & Merrow, M. (2003). Life between clocks: daily temporal patterns of human chronotypes. Journal of Biological Rhythms, 18(1), 80-90. doi:10.1177/0748730402239679

The Worldwide Experimental Platform (n.d.). MCTQ. https://www.thewep.org/documentations/mctq/

See Also

Other MCTQ functions: fd(), gu(), le_week(), msl(), napd(), sd24(), sd_overall(), sd_week(), sdu(), sjl(), sjl_sc(), sjl_weighted(), so(), tbt()

Examples

## Scalar example

msf <- hms::parse_hms("04:00:00")
sd_w <- lubridate::dhours(6)
sd_f <- lubridate::dhours(7)
sd_week <- lubridate::dhours(6.29)
alarm_f <- FALSE
msf_sc(msf, sd_w, sd_f, sd_week, alarm_f)
#> 03:38:42 # Expected

msf <- hms::parse_hm("01:00:00")
sd_w <- lubridate::dhours(5.5)
sd_f <- lubridate::dhours(9)
sd_week <- lubridate::dhours(6.75)
alarm_f <- FALSE
msf_sc(msf, sd_w, sd_f, sd_week, alarm_f)
#> 23:52:30 # Expected

msf <- hms::parse_hms("05:40:00")
sd_w <- lubridate::dhours(7.5)
sd_f <- lubridate::dhours(10)
sd_week <- lubridate::dhours(8.5)
alarm_f <- TRUE
msf_sc(msf, sd_w, sd_f, sd_week, alarm_f)
#> NA # Expected (`msf_sc` cannot be computed if `alarm_f == TRUE`)

## Vector example

msf <- c(hms::parse_hms("03:45:00"), hms::parse_hm("04:45:00"))
sd_w <- c(lubridate::dhours(9), lubridate::dhours(6.45))
sd_f <- c(lubridate::dhours(5), lubridate::dhours(10))
sd_week <- c(lubridate::dhours(8.5), lubridate::dhours(9.2))
alarm_f <- c(FALSE, FALSE)
msf_sc(msf, sd_w, sd_f, sd_week, alarm_f)
#> 03:45:00 # Expected
#> 04:21:00 # Expected

## Rounding the output at the seconds level

msf <- hms::parse_hms("05:40:00")
sd_w <- lubridate::dhours(5.43678)
sd_f <- lubridate::dhours(9.345111)
sd_week <- lubridate::dhours(7.5453)
alarm_f <- FALSE
msf_sc(msf, sd_w, sd_f, sd_week, alarm_f)
#> 04:46:00.3402 # Expected

mctq:::round_time(msf_sc(msf, sd_w, sd_f, sd_week, alarm_f))
#> 04:46:00 # Expected

---

Compute MCTQ local time of mid-sleep

Description

msl() computes the local time of mid-sleep for standard, micro, and shift versions of the Munich ChronoType Questionnaire (MCTQ).

Please note that, although we tried to preserve the original authors' naming pattern for the MCTQ functions, the name ms provokes a dangerous name collision with the ms() function (a function for parsing minutes and seconds components). That's why we named it msl. msl() and sdu() are the only exceptions, all the other mctq functions maintain a strong naming resemblance with the original authors' naming pattern.

Usage

msl(so, sd)

Arguments

so	An hms object corresponding to the local time of sleep onset from a standard, micro, or shift version of the MCTQ questionnaire. You can use so() to compute it for the standard or shift version.
sd	A Duration object corresponding to the sleep duration from a standard, micro, or shift version of the MCTQ questionnaire. You can use sdu() to compute it for any MCTQ version.

Details

Standard MCTQ functions were created following the guidelines in Roenneberg, Wirz-Justice, & Merrow (2003), Roenneberg, Allebrandt, Merrow, & Vetter (2012), and from The Worldwide Experimental Platform (theWeP, n.d.).

$\mu$MCTQ functions were created following the guidelines in Ghotbi et al. (2020), in addition to the guidelines used for the standard MCTQ.

MCTQ$^{Shift}$ functions were created following the guidelines in Juda, Vetter, & Roenneberg (2013), in addition to the guidelines used for the standard MCTQ.

See the References section to learn more.

Class requirements

The mctq package works with a set of object classes specially created to hold time values. These classes can be found in the lubridate and hms packages. Please refer to those package documentations to learn more about them.

Rounding and fractional time

Some operations may produce an output with fractional time (e.g., "19538.3828571429s (~5.43 hours)", 01:15:44.505). If you want, you can round it with mctq:::round_time().

Our recommendation is to avoid rounding, but, if you do, make sure that you only round your values after all computations are done. That way you avoid round-off errors.

Value

An hms object corresponding to the vectorized sum of so and (sd / 2) in a circular time frame of 24 hours.

Guidelines

Roenneberg, Allebrandt, Merrow, & Vetter (2012), Ghotbi et al. (2020), Juda, Vetter, & Roenneberg (2013), and The Worldwide Experimental Platform (n.d.) guidelines for msl() ($MSW$ or $MSF$) computation are as follows.

Notes

• This computation must be applied to each section of the questionnaire.

• If you are visualizing this documentation in plain text, you may have some trouble understanding the equations. You can see this documentation on the package website.

For standard and micro versions of the MCTQ

$MS_{W/F} = SO_{W/F} + \frac{SD_{W/F}}{2}$

Where:

• $MS_{W/F}$ = Local time of mid-sleep on work or work-free days.

• $SO_{W/F}$ = Local time of sleep onset on work or work-free days.

• $SD_{W/F}$ = Sleep duration on work or work-free days.

* $W$ = Workdays; $F$ = Work-free days.

For the shift version of the MCTQ

$MS_{W/F}^{M/E/N} = SO_{W/F}^{M/E/N} + \frac{SD_{W/F}^{M/E/N}}{2}$

Where:

• $MS_{W/F}^{M/E/N}$ = Local time of mid-sleep between two days in a particular shift or between two free days after a particular shift.

• $SO_{W/F}^{M/E/N}$ = Local time of sleep onset between two days in a particular shift or between two free days after a particular shift.

• $SD_{W/F}^{M/E/N}$ = Sleep duration between two days in a particular shift or between two free days after a particular shift.

* $W$ = Workdays; $F$ = Work-free days, $M$ = Morning shift; $E$ = Evening shift; $N$ = Night shift.

References

Ghotbi, N., Pilz, L. K., Winnebeck, E. C., Vetter, C., Zerbini, G., Lenssen, D., Frighetto, G., Salamanca, M., Costa, R., Montagnese, S., & Roenneberg, T. (2020). The $\mu$MCTQ: an ultra-short version of the Munich ChronoType Questionnaire. Journal of Biological Rhythms, 35(1), 98-110. doi:10.1177/0748730419886986

Juda, M., Vetter, C., & Roenneberg, T. (2013). The Munich ChronoType Questionnaire for shift-workers (MCTQ$^{Shift}$). Journal of Biological Rhythms, 28(2), 130-140. doi:10.1177/0748730412475041

Roenneberg T., Allebrandt K. V., Merrow M., & Vetter C. (2012). Social jetlag and obesity. Current Biology, 22(10), 939-43. doi:10.1016/j.cub.2012.03.038

Roenneberg, T., Wirz-Justice, A., & Merrow, M. (2003). Life between clocks: daily temporal patterns of human chronotypes. Journal of Biological Rhythms, 18(1), 80-90. doi:10.1177/0748730402239679

The Worldwide Experimental Platform (n.d.). MCTQ. https://www.thewep.org/documentations/mctq/

See Also

Other MCTQ functions: fd(), gu(), le_week(), msf_sc(), napd(), sd24(), sd_overall(), sd_week(), sdu(), sjl(), sjl_sc(), sjl_weighted(), so(), tbt()

Examples

## Scalar example

so <- hms::parse_hm("23:30")
sd <- lubridate::dhours(8)
msl(so, sd)
#> 03:30:00 # Expected

so <- hms::parse_hm("01:00")
sd <- lubridate::dhours(10)
msl(so, sd)
#> 06:00:00 # Expected

so <- hms::as_hms(NA)
sd <- lubridate::dhours(7.5)
msl(so, sd)
#> NA # Expected

## Vector example

so <- c(hms::parse_hm("00:10"), hms::parse_hm("01:15"))
sd <- c(lubridate::dhours(9.25), lubridate::dhours(5.45))
msl(so, sd)
#> [1] 04:47:30 # Expected
#> [1] 03:58:30 # Expected

---

Compute MCTQ nap duration (only for MCTQ$^{Shift}$)

Description

napd() computes the nap duration for the shift version of the Munich ChronoType Questionnaire (MCTQ).

Usage

napd(napo, nape)

Arguments

napo	An hms object corresponding to the local time of nap onset from the shift version of the MCTQ questionnaire.
nape	An hms object corresponding to the local time of nap end from the shift version of the MCTQ questionnaire.

Details

Standard MCTQ functions were created following the guidelines in Roenneberg, Wirz-Justice, & Merrow (2003), Roenneberg, Allebrandt, Merrow, & Vetter (2012), and from The Worldwide Experimental Platform (theWeP, n.d.).

$\mu$MCTQ functions were created following the guidelines in Ghotbi et al. (2020), in addition to the guidelines used for the standard MCTQ.

MCTQ$^{Shift}$ functions were created following the guidelines in Juda, Vetter, & Roenneberg (2013), in addition to the guidelines used for the standard MCTQ.

See the References section to learn more.

Class requirements

The mctq package works with a set of object classes specially created to hold time values. These classes can be found in the lubridate and hms packages. Please refer to those package documentations to learn more about them.

Rounding and fractional time

Some operations may produce an output with fractional time (e.g., "19538.3828571429s (~5.43 hours)", 01:15:44.505). If you want, you can round it with mctq:::round_time().

Our recommendation is to avoid rounding, but, if you do, make sure that you only round your values after all computations are done. That way you avoid round-off errors.

Value

A Duration object corresponding to the vectorized difference between nape and napo in a circular time frame of 24 hours.

Guidelines

Juda, Vetter & Roenneberg (2013) and The Worldwide Experimental Platform (n.d.) guidelines for napd() ($NapD$) computation are as follows.

Notes

• This computation must be applied to each section of the questionnaire.

• If you are visualizing this documentation in plain text, you may have some trouble understanding the equations. You can see this documentation on the package website.

Computation

$NapD_{W/F}^{M/E/N} = NapE_{W/F}^{M/E/N} - NapO_{W/F}^{M/E/N}$

Where:

• $NapD_{W/F}^{M/E/N}$ = Nap duration between two days in a particular shift or between two free days after a particular shift ("I take a nap from ___ o'clock [...]").

• $NapO_{W/F}^{M/E/N}$ = Local time of nap onset between two days in a particular shift or between two free days after a particular shift ("I take a nap from ___ o'clock [...]").

• $NapE_{W/F}^{M/E/N}$ = Local time of nap end between two days in a particular shift or between two free days after a particular shift ("[...] to ___ o'clock").

* $W$ = Workdays; $F$ = Work-free days, $M$ = Morning shift; $E$ = Evening shift; $N$ = Night shift.

References

Ghotbi, N., Pilz, L. K., Winnebeck, E. C., Vetter, C., Zerbini, G., Lenssen, D., Frighetto, G., Salamanca, M., Costa, R., Montagnese, S., & Roenneberg, T. (2020). The $\mu$MCTQ: an ultra-short version of the Munich ChronoType Questionnaire. Journal of Biological Rhythms, 35(1), 98-110. doi:10.1177/0748730419886986

Juda, M., Vetter, C., & Roenneberg, T. (2013). The Munich ChronoType Questionnaire for shift-workers (MCTQ$^{Shift}$). Journal of Biological Rhythms, 28(2), 130-140. doi:10.1177/0748730412475041

Roenneberg T., Allebrandt K. V., Merrow M., & Vetter C. (2012). Social jetlag and obesity. Current Biology, 22(10), 939-43. doi:10.1016/j.cub.2012.03.038

Roenneberg, T., Wirz-Justice, A., & Merrow, M. (2003). Life between clocks: daily temporal patterns of human chronotypes. Journal of Biological Rhythms, 18(1), 80-90. doi:10.1177/0748730402239679

The Worldwide Experimental Platform (n.d.). MCTQ. https://www.thewep.org/documentations/mctq/

See Also

Other MCTQ functions: fd(), gu(), le_week(), msf_sc(), msl(), sd24(), sd_overall(), sd_week(), sdu(), sjl(), sjl_sc(), sjl_weighted(), so(), tbt()

Examples

## Scalar example

napo <- hms::parse_hm("12:30")
nape <- hms::parse_hm("14:20")
napd(napo, nape)
#> [1] "6600s (~1.83 hours)"" # Expected

napo <- hms::parse_hm("23:45")
nape <- hms::parse_hm("00:30")
napd(napo, nape)
#> [1] "2700s (~45 minutes)" # Expected

napo <- hms::parse_hm("10:20")
nape <- hms::as_hms(NA)
napd(napo, nape)
#> [1] NA # Expected

## Vector example

napo <- c(hms::parse_hm("01:25"), hms::parse_hm("23:50"))
nape <- c(hms::parse_hm("03:10"), hms::parse_hm("01:10"))
napd(napo, nape)
#> [1] "6300s (~1.75 hours)" "4800s (~1.33 hours)"  # Expected

---

Make an MCTQ dataset more presentable

Description

pretty_mctq() helps you to transform your Munich ChronoType Questionnaire (MCTQ) data in many ways. See the Arguments and Details section to learn more.

Usage

pretty_mctq(data, round = TRUE, hms = TRUE)

Arguments

data	A data.frame object.
round	(optional) a logical value indicating if Duration and hms objects must be rounded at the seconds level (default: TRUE).
hms	(optional) a logical value indicating if Duration and difftime objects must be converted to hms (default: TRUE).

Details

Rounding

Please note that by rounding MCTQ values you discard data. That is to say that if you need to redo a computation, or do new ones, your values can be off by a couple of seconds (see round-off error).

Round your values only if and when you want to present them more clearly, like in graphical representations. You can also round values to facilitate data exporting to text formats (like .csv), but note that this will come with a precision cost.

Note also that pretty_mctq() uses round() for rounding, which uses uses the IEC 60559 standard ("go to the even digit") for rounding off a 5. Therefore, round(0.5) is equal to 0 and round(-1.5) is equal to -2. See ?round to learn more.

Value

A transformed data.frame object, as indicated in the arguments.

See Also

Other utility functions: random_mctq(), raw_data()

Examples

data <- data.frame(
    a = 1,
    b = lubridate::duration(1.12345),
    c = hms::hms(1.12345)
    )

## Rounding time objects from `data`

pretty_mctq(data, round = TRUE, hms = FALSE)

## Converting non-'hms' time objects from 'data' to 'hms'

pretty_mctq(data, round = FALSE, hms = TRUE)

---

Build a random MCTQ case

Description

random_mctq builds a fictional Munich ChronoType Questionnaire (MCTQ) case composed of MCTQ basic/measurable variables.

This function is for testing and learning purposes only. Please don't misuse it.

Usage

random_mctq(model = "standard")

Arguments

model

A string indicating the data model to return. Valid values are: "standard", "⁠shift"⁠, and "micro" (default: "standard").

Details

The case structure (variable names and classes) are the same as the datasets provided by the mctq package. See ?std_mctq, ?micro_mctq and ?shift_mctq to learn more.

Requirements

This function requires the stats package. This won't be an issue for most people since the package comes with a standard R installation.

If you don't have the stats package, you can install it with install.packages("stats").

Cases

Random standard and micro MCTQ cases were created with the general population in mind. The data was set to resemble the distribution parameters shown in Roenneberg, Wirz-Justice, & Merrow (2003).

MCTQ$^{Shift}$ random cases were created based on the shift configuration from "Study Site 1" shown in Vetter, Juda, & Roenneberg (2012). The data was set to resemble the distribution parameters shown in Juda, Vetter, & Roenneberg (2013).

You can see more about the distribution parameters used here.

Value

A named list with elements representing each MCTQ basic/measurable variable of the model indicated in the model argument.

References

Juda, M., Vetter, C., & Roenneberg, T. (2013). The Munich ChronoType Questionnaire for shift-workers (MCTQ$^{Shift}$). Journal of Biological Rhythms, 28(2), 130-140. doi:10.1177/0748730412475041

Roenneberg, T., Wirz-Justice, A., & Merrow, M. (2003). Life between clocks: daily temporal patterns of human chronotypes. Journal of Biological Rhythms, 18(1), 80-90. doi:10.1177/0748730402239679

Vetter, C., Juda, M., & Roenneberg, T. (2012). The influence of internal time, time awake, and sleep duration on cognitive performance in shiftworkers. Chronobiology International, 29(8), 1127-1138. doi:10.3109/07420528.2012.707999

See Also

Other utility functions: pretty_mctq(), raw_data()

Examples

## Not run: 
random_mctq("standard")
random_mctq("micro")
random_mctq("shift")

## End(Not run)

---

Get paths to mctq raw datasets

Description

mctq comes bundled with raw fictional datasets for testing and learning purposes. raw_data() makes it easy to access their paths.

Usage

raw_data(file = NULL)

Arguments

file	(optional) a character object indicating the raw data file name(s). If NULL, all raw data file names will be returned (default: NULL).

Value

If file == NULL, a character object with all file names available. Else, a string with the file name path.

See Also

Other utility functions: pretty_mctq(), random_mctq()

Examples

## Not run: 
## To list all raw data file names available

raw_data()

## To get the file path from a specific raw data

raw_data("std_mctq.csv")
## End(Not run)

---

Compute MCTQ overall sleep duration (only for MCTQ$^{Shift}$)

Description

sd_overall() computes the overall sleep duration in a particular shift for the shift version of the Munich ChronoType Questionnaire (MCTQ).

See sd_week() to compute the average weekly sleep duration for the standard and micro versions of the MCTQ.

Usage

sd_overall(sd_w, sd_f, n_w, n_f)

Arguments

sd_w	A Duration object corresponding to the sleep duration between two days in a particular shift from a shift version of the MCTQ questionnaire. You can use sdu() to compute it.
sd_f	A Duration object corresponding to the sleep duration between two free days after a particular shift from a shift version of the MCTQ questionnaire. You can use sdu() to compute it.
n_w	An integerish numeric object or an integer object corresponding to the number of days worked in a particular shift within a shift cycle from a shift version of the MCTQ questionnaire.
n_f	An integerish numeric object or an integer object corresponding to the number of free days after a particular shift within a shift cycle from a shift version of the MCTQ questionnaire.

Details

Standard MCTQ functions were created following the guidelines in Roenneberg, Wirz-Justice, & Merrow (2003), Roenneberg, Allebrandt, Merrow, & Vetter (2012), and from The Worldwide Experimental Platform (theWeP, n.d.).

$\mu$MCTQ functions were created following the guidelines in Ghotbi et al. (2020), in addition to the guidelines used for the standard MCTQ.

MCTQ$^{Shift}$ functions were created following the guidelines in Juda, Vetter, & Roenneberg (2013), in addition to the guidelines used for the standard MCTQ.

See the References section to learn more.

Class requirements

The mctq package works with a set of object classes specially created to hold time values. These classes can be found in the lubridate and hms packages. Please refer to those package documentations to learn more about them.

Rounding and fractional time

Some operations may produce an output with fractional time (e.g., "19538.3828571429s (~5.43 hours)", 01:15:44.505). If you want, you can round it with mctq:::round_time().

Our recommendation is to avoid rounding, but, if you do, make sure that you only round your values after all computations are done. That way you avoid round-off errors.

Value

A Duration object corresponding to the vectorized weighted mean of sd_w and sd_f with n_w and n_f as weights.

Guidelines

Juda, Vetter, & Roenneberg (2013) and The Worldwide Experimental Platform (n.d.) guidelines for sd_overall() ($\emptyset SD$) computation are as follows.

Notes

• This computation must be applied to each section of the questionnaire. If you're using the three-shift design proposed by the MCTQ authors, you need to compute three overall sleep duration (e.g., $\emptyset SD^M$; $\emptyset SD^E$; $\emptyset SD^N$).

• The overall sleep duration is the weighted average of the shift-specific mean sleep durations.

• If you are visualizing this documentation in plain text, you may have some trouble understanding the equations. You can see this documentation on the package website.

Computation

$\emptyset SD^{M/E/N} = \frac{(SD_{W}^{M/E/N} \times n_{W}^{M/E/N}) + (SD_{F}^{M/E/N} \times n_{F}^{M/E/N})}{n_W^{M/E/N} + n_{F}^{M/E/N}}$

Where:

• $\emptyset SD^{M/E/N}$ = Overall sleep duration in a particular shift.

• $SD_W^{M/E/N}$ = Sleep duration between two days in a particular shift.

• $SD_F^{M/E/N}$ = Sleep duration between two free days after a particular shift.

• $n_W^{M/E/N}$ = Number of days worked in a particular shift within a shift cycle.

• $n_F^{M/E/N}$ = Number of free days after a particular shift within a shift cycle.

* $W$ = Workdays; $F$ = Work-free days, $M$ = Morning shift; $E$ = Evening shift; $N$ = Night shift.

References

Ghotbi, N., Pilz, L. K., Winnebeck, E. C., Vetter, C., Zerbini, G., Lenssen, D., Frighetto, G., Salamanca, M., Costa, R., Montagnese, S., & Roenneberg, T. (2020). The $\mu$MCTQ: an ultra-short version of the Munich ChronoType Questionnaire. Journal of Biological Rhythms, 35(1), 98-110. doi:10.1177/0748730419886986

Juda, M., Vetter, C., & Roenneberg, T. (2013). The Munich ChronoType Questionnaire for shift-workers (MCTQ$^{Shift}$). Journal of Biological Rhythms, 28(2), 130-140. doi:10.1177/0748730412475041

Roenneberg T., Allebrandt K. V., Merrow M., & Vetter C. (2012). Social jetlag and obesity. Current Biology, 22(10), 939-43. doi:10.1016/j.cub.2012.03.038

Roenneberg, T., Wirz-Justice, A., & Merrow, M. (2003). Life between clocks: daily temporal patterns of human chronotypes. Journal of Biological Rhythms, 18(1), 80-90. doi:10.1177/0748730402239679

The Worldwide Experimental Platform (n.d.). MCTQ. https://www.thewep.org/documentations/mctq/

See Also

Other MCTQ functions: fd(), gu(), le_week(), msf_sc(), msl(), napd(), sd24(), sd_week(), sdu(), sjl(), sjl_sc(), sjl_weighted(), so(), tbt()

Examples

## Scalar example

sd_w <- lubridate::dhours(5)
sd_f <- lubridate::dhours(9)
n_w <- 2
n_f <- 2
sd_overall(sd_w, sd_f, n_w, n_f)
#> [1] "25200s (~7 hours)" # Expected

sd_w <- lubridate::dhours(3.45)
sd_f <- lubridate::dhours(10)
n_w <- 3
n_f <- 1
sd_overall(sd_w, sd_f, n_w, n_f)
#> [1] "18315s (~5.09 hours)" # Expected

sd_w <- lubridate::as.duration(NA)
sd_f <- lubridate::dhours(12)
n_w <- 4
n_f <- 4
sd_overall(sd_w, sd_f, n_w, n_f)
#> [1] NA # Expected

## Vector example

sd_w <- c(lubridate::dhours(4), lubridate::dhours(7))
sd_f <- c(lubridate::dhours(12), lubridate::dhours(9))
n_w <- c(3, 4)
n_f <- c(2, 4)
sd_overall(sd_w, sd_f, n_w, n_f)
#> [1] "25920s (~7.2 hours)" "28800s (~8 hours)"  # Expected

## Checking second output from vector example

if (requireNamespace("stats", quietly = TRUE)) {
    i <- 2
    x <- c(sd_w[i], sd_f[i])
    w <- c(n_w[i], n_f[i])
    lubridate::as.duration(stats::weighted.mean(x, w))
}
#> [1] "28800s (~8 hours)" # Expected

## Converting the output to 'hms'

sd_w <- lubridate::dhours(4.75)
sd_f <- lubridate::dhours(10)
n_w <- 5
n_f <- 2
sd_overall(sd_w, sd_f, n_w, n_f)
#> [1] "22500s (~6.25 hours)" # Expected

hms::as_hms(as.numeric(sd_overall(sd_w, sd_f, n_w, n_f)))
#> 06:15:00 # Expected

## Rounding the output at the seconds level

sd_w <- lubridate::dhours(5.9874)
sd_f <- lubridate::dhours(9.3)
n_w <- 3
n_f <- 2
sd_overall(sd_w, sd_f, n_w, n_f)
#> [1] "26324.784s (~7.31 hours)" # Expected

mctq:::round_time(sd_overall(sd_w, sd_f, n_w, n_f))
#> [1] "26325s (~7.31 hours)" # Expected

---

Compute MCTQ average weekly sleep duration

Description

sd_week() computes the average weekly sleep duration for the standard and micro versions of the Munich ChronoType Questionnaire (MCTQ).

See sd_overall() to compute the overall sleep duration of a particular shift for the shift version of the MCTQ.

Usage

sd_week(sd_w, sd_f, wd)

Arguments

sd_w	A Duration object corresponding to the sleep duration on workdays from a standard or micro version of the MCTQ questionnaire. You can use sdu() to compute it.
sd_f	A Duration object corresponding to the sleep duration on work-free days from a standard or micro version of the MCTQ questionnaire. You can use sdu() to compute it.
wd	An integerish numeric object or an integer object corresponding to the number of workdays per week from a standard or micro version of the MCTQ questionnaire.

Details

Standard MCTQ functions were created following the guidelines in Roenneberg, Wirz-Justice, & Merrow (2003), Roenneberg, Allebrandt, Merrow, & Vetter (2012), and from The Worldwide Experimental Platform (theWeP, n.d.).

$\mu$MCTQ functions were created following the guidelines in Ghotbi et al. (2020), in addition to the guidelines used for the standard MCTQ.

MCTQ$^{Shift}$ functions were created following the guidelines in Juda, Vetter, & Roenneberg (2013), in addition to the guidelines used for the standard MCTQ.

See the References section to learn more.

Class requirements

The mctq package works with a set of object classes specially created to hold time values. These classes can be found in the lubridate and hms packages. Please refer to those package documentations to learn more about them.

Rounding and fractional time

Some operations may produce an output with fractional time (e.g., "19538.3828571429s (~5.43 hours)", 01:15:44.505). If you want, you can round it with mctq:::round_time().

Our recommendation is to avoid rounding, but, if you do, make sure that you only round your values after all computations are done. That way you avoid round-off errors.

Value

A Duration object corresponding to the vectorized weighted mean of sd_w and sd_f with wd and fd(wd) as weights.

Guidelines

Roenneberg, Allebrandt, Merrow, & Vetter (2012), Ghotbi et al. (2020), and The Worldwide Experimental Platform (n.d.) guidelines for sd_week() ($SD_{week}$) computation are as follows.

Notes

• The average weekly sleep duration is the weighted average of the sleep durations on work and work-free days in a week.

• If you are visualizing this documentation in plain text, you may have some trouble understanding the equations. You can see this documentation on the package website.

Computation

$SD_{week} = \frac{(SD_{W} \times WD) + (SD_{F} \times FD)}{7}$

Where:

• $SD_{week}$ = Average weekly sleep duration.

• $SD_{W}$ = Sleep duration on workdays.

• $SD_{F}$ = Sleep duration on work-free days.

• $WD$ = Number of workdays per week ("I have a regular work schedule and work ___ days per week").

• $FD$ = Number of work-free days per week.

* $W$ = Workdays; $F$ = Work-free days.

References

Ghotbi, N., Pilz, L. K., Winnebeck, E. C., Vetter, C., Zerbini, G., Lenssen, D., Frighetto, G., Salamanca, M., Costa, R., Montagnese, S., & Roenneberg, T. (2020). The $\mu$MCTQ: an ultra-short version of the Munich ChronoType Questionnaire. Journal of Biological Rhythms, 35(1), 98-110. doi:10.1177/0748730419886986

Juda, M., Vetter, C., & Roenneberg, T. (2013). The Munich ChronoType Questionnaire for shift-workers (MCTQ$^{Shift}$). Journal of Biological Rhythms, 28(2), 130-140. doi:10.1177/0748730412475041

Roenneberg T., Allebrandt K. V., Merrow M., & Vetter C. (2012). Social jetlag and obesity. Current Biology, 22(10), 939-43. doi:10.1016/j.cub.2012.03.038

Roenneberg, T., Wirz-Justice, A., & Merrow, M. (2003). Life between clocks: daily temporal patterns of human chronotypes. Journal of Biological Rhythms, 18(1), 80-90. doi:10.1177/0748730402239679

The Worldwide Experimental Platform (n.d.). MCTQ. https://www.thewep.org/documentations/mctq/

See Also

Other MCTQ functions: fd(), gu(), le_week(), msf_sc(), msl(), napd(), sd24(), sd_overall(), sdu(), sjl(), sjl_sc(), sjl_weighted(), so(), tbt()

Examples

## Scalar example

sd_w <- lubridate::dhours(4)
sd_f <- lubridate::dhours(8)
wd <- 5
sd_week(sd_w, sd_f, wd)
#> [1] "18514.2857142857s (~5.14 hours)" # Expected

sd_w <- lubridate::dhours(7)
sd_f <- lubridate::dhours(7)
wd <- 4
sd_week(sd_w, sd_f, wd)
#> [1] "25200s (~7 hours)" # Expected

sd_w <- lubridate::as.duration(NA)
sd_f <- lubridate::dhours(10)
wd <- 6
sd_week(sd_w, sd_f, wd)
#> [1] NA # Expected

## Vector example

sd_w <- c(lubridate::dhours(4.5), lubridate::dhours(5.45))
sd_f <- c(lubridate::dhours(8), lubridate::dhours(7.3))
wd <- c(3, 7)
sd_week(sd_w, sd_f, wd)
#> [1] "23400s (~6.5 hours)"  "19620s (~5.45 hours)" # Expected

## Checking second output from vector example

if (requireNamespace("stats", quietly = TRUE)) {
    i <- 2
    x <- c(sd_w[i], sd_f[i])
    w <- c(wd[i], fd(wd[i]))
    lubridate::as.duration(stats::weighted.mean(x, w))
}
#> [1] "19620s (~5.45 hours)" # Expected

## Converting the output to 'hms'

sd_w <- lubridate::dhours(5.45)
sd_f <- lubridate::dhours(9.5)
wd <- 5
x <- sd_week(sd_w, sd_f, wd)
x
#> [1] "23785.7142857143s (~6.61 hours)" # Expected
hms::as_hms(as.numeric(x))
#> 06:36:25.714286 # Expected

## Rounding the output at the seconds level

sd_w <- lubridate::dhours(4.5)
sd_f <- lubridate::dhours(7.8)
wd <- 3
sd_week(sd_w, sd_f, wd)
#> [1] "22988.5714285714s (~6.39 hours)" # Expected

mctq:::round_time(sd_week(sd_w, sd_f, wd))
#> [1] "22989s (~6.39 hours)" # Expected

---

Compute MCTQ 24 hours sleep duration (only for MCTQ$^{Shift}$)

Description

sd24() computes the 24 hours sleep duration for the shift version of the Munich ChronoType Questionnaire (MCTQ).

Usage

sd24(sd, napd, nap)

Arguments

sd	A Duration object corresponding to the sleep duration from the shift version of the MCTQ questionnaire. You can use sdu() to compute it.
napd	A Duration object corresponding to the nap duration from the shift version of the MCTQ questionnaire. You can use napd() to compute it.
nap	A logical value corresponding to the "I usually take a nap" response from the shift version of the MCTQ questionnaire.

Details

Standard MCTQ functions were created following the guidelines in Roenneberg, Wirz-Justice, & Merrow (2003), Roenneberg, Allebrandt, Merrow, & Vetter (2012), and from The Worldwide Experimental Platform (theWeP, n.d.).

$\mu$MCTQ functions were created following the guidelines in Ghotbi et al. (2020), in addition to the guidelines used for the standard MCTQ.

MCTQ$^{Shift}$ functions were created following the guidelines in Juda, Vetter, & Roenneberg (2013), in addition to the guidelines used for the standard MCTQ.

See the References section to learn more.

Class requirements

The mctq package works with a set of object classes specially created to hold time values. These classes can be found in the lubridate and hms packages. Please refer to those package documentations to learn more about them.

Rounding and fractional time

Some operations may produce an output with fractional time (e.g., "19538.3828571429s (~5.43 hours)", 01:15:44.505). If you want, you can round it with mctq:::round_time().

Our recommendation is to avoid rounding, but, if you do, make sure that you only round your values after all computations are done. That way you avoid round-off errors.

Value

• If nap == TRUE, a Duration object corresponding to the vectorized sum of sd and napd in a circular time frame of 24 hours.

• If nap == FALSE, a Duration object equal to sd.

Guidelines

Juda, Vetter & Roenneberg (2013) and The Worldwide Experimental Platform (n.d.) guidelines for sd24() ($SD24$) computation are as follows.

Notes

• This computation must be applied to each section of the questionnaire.

• If the respondent don't usually take a nap in a particular shift or between two free days after a particular shift, sd24() will return only $SD_{W/F}^{M/E/N}$.

• If you are visualizing this documentation in plain text, you may have some trouble understanding the equations. You can see this documentation on the package website.

Computation

$SD24_{W/F}^{M/E/N} = SD_{W/F}^{M/E/N} + NapD_{W/F}^{M/E/N}$

Where:

• $SD24_{W/F}^{M/E/N}$ = 24 hours sleep duration between two days in a particular shift or between two free days after a particular shift.

• $SD_{W/F}^{M/E/N}$ = Sleep duration between two days in a particular shift or between two free days after a particular shift.

• $NapD_{W/F}^{M/E/N}$ = Nap duration between two days in a particular shift or between two free days after a particular shift.

* $W$ = Workdays; $F$ = Work-free days, $M$ = Morning shift; $E$ = Evening shift; $N$ = Night shift.

References

Ghotbi, N., Pilz, L. K., Winnebeck, E. C., Vetter, C., Zerbini, G., Lenssen, D., Frighetto, G., Salamanca, M., Costa, R., Montagnese, S., & Roenneberg, T. (2020). The $\mu$MCTQ: an ultra-short version of the Munich ChronoType Questionnaire. Journal of Biological Rhythms, 35(1), 98-110. doi:10.1177/0748730419886986

Juda, M., Vetter, C., & Roenneberg, T. (2013). The Munich ChronoType Questionnaire for shift-workers (MCTQ$^{Shift}$). Journal of Biological Rhythms, 28(2), 130-140. doi:10.1177/0748730412475041

Roenneberg T., Allebrandt K. V., Merrow M., & Vetter C. (2012). Social jetlag and obesity. Current Biology, 22(10), 939-43. doi:10.1016/j.cub.2012.03.038

Roenneberg, T., Wirz-Justice, A., & Merrow, M. (2003). Life between clocks: daily temporal patterns of human chronotypes. Journal of Biological Rhythms, 18(1), 80-90. doi:10.1177/0748730402239679

The Worldwide Experimental Platform (n.d.). MCTQ. https://www.thewep.org/documentations/mctq/

See Also

Other MCTQ functions: fd(), gu(), le_week(), msf_sc(), msl(), napd(), sd_overall(), sd_week(), sdu(), sjl(), sjl_sc(), sjl_weighted(), so(), tbt()

Examples

## Scalar example

sd <- lubridate::dhours(6)
napd <- lubridate::dhours(0.5)
nap <- TRUE
sd24(sd, napd, nap)
#> [1] "23400s (~6.5 hours)" # Expected

sd <- lubridate::dhours(9)
napd <- lubridate::dhours(1.5)
nap <- TRUE
sd24(sd, napd, nap)
#> [1] "37800s (~10.5 hours)" # Expected

sd <- lubridate::dhours(6.5)
napd <- lubridate::as.duration(NA)
nap <- FALSE
sd24(sd, napd, nap)
#> [1] "23400s (~6.5 hours)" # Expected

sd <- lubridate::as.duration(NA)
napd <- lubridate::dhours(2.3)
nap <- TRUE
sd24(sd, napd, nap)
#> [1] NA # Expected

## Vector example

sd <- c(lubridate::dhours(7.5), lubridate::dhours(8))
napd <- c(lubridate::dhours(0.75), lubridate::dhours(1))
nap <- c(TRUE, TRUE)
sd24(sd, napd, nap)
#> [1] "29700s (~8.25 hours)" "32400s (~9 hours)" # Expected

---

Compute MCTQ sleep duration

Description

sdu() computes the sleep duration for standard, micro, and shift versions of the Munich ChronoType Questionnaire (MCTQ).

Please note that, although we tried to preserve the original authors' naming pattern for the MCTQ functions, the name sd provokes a dangerous name collision with the widely used sd() function (standard deviation). That's why we named it sdu. sdu() and msl() are the only exceptions, all the other mctq functions maintain a strong naming resemblance with the original authors' naming pattern.

Usage

sdu(so, se)

Arguments

so	An hms object corresponding to the local time of sleep onset from a standard, micro, or shift version of the MCTQ questionnaire. You can use so() to compute it for the standard or shift version.
se	An hms object corresponding to the local time of sleep end from a standard, micro, or shift version of the MCTQ questionnaire.

Details

Standard MCTQ functions were created following the guidelines in Roenneberg, Wirz-Justice, & Merrow (2003), Roenneberg, Allebrandt, Merrow, & Vetter (2012), and from The Worldwide Experimental Platform (theWeP, n.d.).

$\mu$MCTQ functions were created following the guidelines in Ghotbi et al. (2020), in addition to the guidelines used for the standard MCTQ.

MCTQ$^{Shift}$ functions were created following the guidelines in Juda, Vetter, & Roenneberg (2013), in addition to the guidelines used for the standard MCTQ.

See the References section to learn more.

Class requirements

The mctq package works with a set of object classes specially created to hold time values. These classes can be found in the lubridate and hms packages. Please refer to those package documentations to learn more about them.

Rounding and fractional time

Some operations may produce an output with fractional time (e.g., "19538.3828571429s (~5.43 hours)", 01:15:44.505). If you want, you can round it with mctq:::round_time().

Our recommendation is to avoid rounding, but, if you do, make sure that you only round your values after all computations are done. That way you avoid round-off errors.

Value

A Duration object corresponding to the vectorized difference between se and so in a circular time frame of 24 hours.

Guidelines

Roenneberg, Allebrandt, Merrow, & Vetter (2012), Ghotbi et al. (2020), Juda, Vetter, & Roenneberg (2013), and The Worldwide Experimental Platform (n.d.) guidelines for sdu() ($SD$) computation are as follows.

Notes

• This computation must be applied to each section of the questionnaire.

• If you are visualizing this documentation in plain text, you may have some trouble understanding the equations. You can see this documentation on the package website.

For standard and micro versions of the MCTQ

$SD_{W/F} = SE_{W/F} - SO_{W/F}$

Where:

• $SD_{W/F}$ = Sleep duration on work or work-free days.

• $SE_{W/F}$ = Local time of sleep end on work or work-free days.

• $SO_{W/F}$ = Local time of sleep onset on work or work-free days.

* $W$ = Workdays; $F$ = Work-free days.

For the shift version of the MCTQ

$SD_{W/F}^{M/E/N} = SE_{W/F}^{M/E/N} - SO_{W/F}^{M/E/N}$

Where:

• $SD_{W/F}^{M/E/N}$ = Sleep duration between two days in a particular shift or between two free days after a particular shift.

• $SE_{W/F}^{M/E/N}$ = Local time of sleep end between two days in a particular shift or between two free days after a particular shift.

• $SO_{W/F}^{M/E/N}$ = Local time of sleep onset between two days in a particular shift or between two free days after a particular shift.

* $W$ = Workdays; $F$ = Work-free days, $M$ = Morning shift; $E$ = Evening shift; $N$ = Night shift.

References

Ghotbi, N., Pilz, L. K., Winnebeck, E. C., Vetter, C., Zerbini, G., Lenssen, D., Frighetto, G., Salamanca, M., Costa, R., Montagnese, S., & Roenneberg, T. (2020). The $\mu$MCTQ: an ultra-short version of the Munich ChronoType Questionnaire. Journal of Biological Rhythms, 35(1), 98-110. doi:10.1177/0748730419886986

Juda, M., Vetter, C., & Roenneberg, T. (2013). The Munich ChronoType Questionnaire for shift-workers (MCTQ$^{Shift}$). Journal of Biological Rhythms, 28(2), 130-140. doi:10.1177/0748730412475041

Roenneberg T., Allebrandt K. V., Merrow M., & Vetter C. (2012). Social jetlag and obesity. Current Biology, 22(10), 939-43. doi:10.1016/j.cub.2012.03.038

Roenneberg, T., Wirz-Justice, A., & Merrow, M. (2003). Life between clocks: daily temporal patterns of human chronotypes. Journal of Biological Rhythms, 18(1), 80-90. doi:10.1177/0748730402239679

The Worldwide Experimental Platform (n.d.). MCTQ. https://www.thewep.org/documentations/mctq/

See Also

Other MCTQ functions: fd(), gu(), le_week(), msf_sc(), msl(), napd(), sd24(), sd_overall(), sd_week(), sjl(), sjl_sc(), sjl_weighted(), so(), tbt()

Examples

## Scalar example

so <- hms::parse_hm("23:00")
se <- hms::parse_hm("08:00")
sdu(so, se)
#> [1] "32400s (~9 hours)" # Expected

so <- hms::parse_hm("02:00")
se <- hms::parse_hm("12:30")
sdu(so, se)
#> [1] "37800s (~10.5 hours)" # Expected

so <- hms::parse_hm("03:15")
se <- hms::as_hms(NA)
sdu(so, se)
#> [1] NA # Expected

## Vector example

so <- c(hms::parse_hm("04:12"), hms::parse_hm("21:20"))
se <- c(hms::parse_hm("14:30"), hms::parse_hm("03:45"))
sdu(so, se)
#> [1] "37080s (~10.3 hours)" "23100s (~6.42 hours)" # Expected

---

A fictional MCTQ$^{Shift}$ dataset

Description

A fictional dataset, for testing and learning purposes, composed of basic/measurable and computed variables of the Munich ChronoType Questionnaire (MCTQ) shift version.

This data was created following the guidelines in Juda, Vetter, & Roenneberg (2013), in addition to the guidelines found in Roenneberg, Wirz-Justice, & Merrow (2003), Roenneberg, Allebrandt, Merrow, & Vetter (2012), Jankowski (2017), and The Worldwide Experimental Platform (n.d.). See the References and Details sections to learn more.

Usage

shift_mctq

Format

A tibble with 135 columns and 50 rows:

id

A unique integer value to identify each respondent in the dataset.

Type: Control.

R class: integer.

n_w_m

Number of days worked in morning shifts within a shift cycle.

Type: Basic.

R class: integer.

bt_w_m

Local time of going to bed on workdays between two morning shifts.

Statement (EN): "I go to bed at ___ o'clock'".

Type: Basic.

R class: hms.

sprep_w_m

Local time of preparing to sleep on workdays between two morning shifts.

Statement (EN): "I actually get ready to fall asleep at ___ o'clock".

Type: Basic.

R class: hms.

slat_w_m

Sleep latency or time to fall asleep after preparing to sleep on workdays between two morning shifts.

Statement (EN): "I need ___ minutes to fall asleep".

Type: Basic.

R class: Duration.

so_w_m

Local time of sleep onset on workdays between two morning shifts.

Type: Computed.

R class: hms.

se_w_m

Local time of sleep end on workdays between two morning shifts.

Statement (EN): "I wake up at ___ o'clock".

Type: Basic.

R class: hms.

tgu_w_m

Time to get up on workdays between two morning shifts.

Statement (EN): "I get up after ___ minutes".

Type: Basic.

R class: Duration.

gu_w_m

Local time of getting out of bed on workdays between two morning shifts.

Type: Computed.

R class: hms.

alarm_w_m

A logical value indicating if the respondent uses an alarm clock to wake up on workdays between two morning shifts.

Statement (EN): "I wake up at ___ o'clock: ( ___ ) with alarm ( ___ ) without alarm".

Type: Basic.

R class: logical.

reasons_w_m

A logical value indicating if the respondent has any particular reasons for why they cannot freely choose their sleep times on workdays between two morning shifts.

Statement (EN): "There are particular reasons why I cannot freely choose my sleep times on morning shifts: Yes ( ___ ) No ( ___ )".

Type: Basic.

R class: logical.

reasons_why_w_m

Particular reasons for why the respondent cannot freely choose their sleep times on workdays between two morning shifts.

Statement (EN): "If "Yes": Child(ren)/pet(s) ( ___ ) Hobbies ( ___ ) Others, for example: ___".

Type: Basic.

R class: character.

sd_w_m

Sleep duration on workdays between two morning shifts.

Type: Computed.

R class: Duration.

tbt_w_m

Total time in bed on workdays between two morning shifts.

Type: Computed.

R class: Duration.

msw_m

Local time of mid-sleep on workdays between two morning shifts.

Type: Computed.

R class: hms.

nap_w_m

A logical value indicating if the respondent usually takes a nap on workdays between two morning shifts.

Statement (EN): "I usually take a nap: Yes ( ___ ) No ( ___ )".

Type: Basic.

R class: logical.

napo_w_m

Local time of nap onset on workdays between two morning shifts.

Statement (EN): "If "Yes": I take a nap from ___ o'clock to ___ o'clock".

Type: Basic.

R class: hms.

nape_w_m

Local time of nap end on workdays between two morning shifts.

Statement (EN): "If "Yes": I take a nap from ___ o'clock to ___ o'clock".

Type: Basic.

R class: hms.

napd_w_m

Nap duration on workdays between two morning shifts.

Type: Computed.

R class: Duration.

sd24_w_m

24 hours sleep duration (sleep duration + nap duration) on workdays between two morning shifts.

Type: Computed.

R class: Duration.

n_f_m

Number of free days after working in morning shifts within a shift cycle.

Type: Basic.

R class: integer.

bt_f_m

Local time of going to bed on work-free days between two free days after morning shifts.

Statement (EN): "I go to bed at ___ o'clock'".

Type: Basic.

R class: hms.

sprep_f_m

Local time of preparing to sleep on work-free days between two free days after morning shifts.

Statement (EN): "I actually get ready to fall asleep at ___ o'clock".

Type: Basic.

R class: hms.

slat_f_m

Sleep latency or time to fall asleep after preparing to sleep on work-free days between two free days after morning shifts.

Statement (EN): "I need ___ minutes to fall asleep".

Type: Basic.

R class: Duration.

so_f_m

Local time of sleep onset on work-free days between two free days after morning shifts.

Type: Computed.

R class: hms.

se_f_m

Local time of sleep end on work-free days between two free days after morning shifts.

Statement (EN): "I wake up at ___ o'clock".

Type: Basic.

R class: hms.

tgu_f_m

Time to get up on work-free days between two free days after morning shifts.

Statement (EN): "I get up after ___ minutes".

Type: Basic.

R class: Duration.

gu_f_m

Local time of getting out of bed on work-free days between two free days after morning shifts.

Type: Computed.

R class: hms.

alarm_f_m

A logical value indicating if the respondent uses an alarm clock to wake up on work-free days between two free days after morning shifts.

Statement (EN): "I wake up at ___ o'clock: ( ___ ) with alarm ( ___ ) without alarm".

Type: Basic.

R class: logical.

reasons_f_m

A logical value indicating if the respondent has any particular reasons for why they cannot freely choose their sleep times on work-free days between two free days after morning shifts.

Statement (EN): "There are particular reasons why I cannot freely choose my sleep times on morning shifts: Yes ( ___ ) No ( ___ )".

Type: Basic.

R class: logical.

reasons_why_f_m

Particular reasons for why the respondent cannot freely choose their sleep times on work-free days between two free days after morning shifts.

Statement (EN): "If "Yes": Child(ren)/pet(s) ( ___ ) Hobbies ( ___ ) Others, for example: ___".

Type: Basic.

R class: character.

sd_f_m

Sleep duration on work-free days between two free days after morning shifts.

Type: Computed.

R class: Duration.

tbt_f_m

Total time in bed on work-free days between two free days after morning shifts.

Type: Computed.

R class: Duration.

msf_m

Local time of mid-sleep on work-free days between two free days after morning shifts.

Type: Computed.

R class: hms.

nap_f_m

A logical value indicating if the respondent usually takes a nap on work-free days between two free days after morning shifts.

Statement (EN): "I usually take a nap: Yes ( ___ ) No ( ___ )".

Type: Basic.

R class: logical.

napo_f_m

Local time of nap onset on work-free days between two free days after morning shifts.

Statement (EN): "If "Yes": I take a nap from ___ o'clock to ___ o'clock".

Type: Basic.

R class: hms.

nape_f_m

Local time of nap end on work-free days between two free days after morning shifts.

Statement (EN): "If "Yes": I take a nap from ___ o'clock to ___ o'clock".

Type: Basic.

R class: hms.

napd_f_m

Nap duration on work-free days between two free days after morning shifts.

Type: Computed.

R class: Duration.

sd24_f_m

24 hours sleep duration (sleep duration + nap duration) on work-free days between two free days after morning shifts.

Type: Computed.

R class: Duration.

sd_overall_m

Overall sleep duration considering workdays between two morning shifts and work-free days between two free days after morning shifts.

Type: Computed.

R class: Duration.

msf_sc_m

Corrected local time of mid-sleep on work-free days between two free days after morning shifts.

Type: Computed.

R class: hms.

sjl_rel_m

Relative social jetlag considering workdays between two morning shifts and work-free days between two free days after morning shifts.

Type: Computed.

R class: Duration.

sjl_m

Absolute social jetlag considering workdays between two morning shifts and work-free days between two free days after morning shifts.

Type: Computed.

R class: Duration.

sjl_sc_rel_m

Jankowski's relative sleep-corrected social jetlag considering workdays between two morning shifts and work-free days between two free days after morning shifts.

Type: Computed.

R class: Duration.

sjl_sc_m

Jankowski's sleep-corrected social jetlag considering workdays between two morning shifts and work-free days between two free days after morning shifts.

Type: Computed.

R class: Duration.

...

For brevity, the subsequent variables, except for sjl_weighted and sjl_sc_weighted (described below), are not shown here. That's because they have the same configurations of the variables shown above, differing only by shift (evening shift (⁠_e⁠) and night shift (⁠_n⁠)).

sjl_weighted

Absolute social jetlag across all shifts.

Type: Computed.

R class: Duration.

#'

sjl_sc_weighted

Jankowski's sleep-corrected social jetlag across all shifts.

Type: Computed.

R class: Duration.

Details

shift_mctq is a tidied, validated, and transformed version of raw_data("shift_mctq.csv").

Guidelines

To learn more about the Munich ChronoType Questionnaire (MCTQ), see Roenneberg, Wirz-Justice, & Merrow (2003), Roenneberg, Allebrandt, Merrow, & Vetter (2012), Roenneberg et al. (2015), and Roenneberg, Pilz, Zerbini, & Winnebeck (2019).

To know about different MCTQ versions, see Juda, Vetter, & Roenneberg (2013) and Ghotbi et al. (2020).

To learn about the sleep-corrected social jetlag, see Jankowski (2017).

If you're curious about the variable computations and want to have access to the full questionnaire, see The Worldwide Experimental Platform (n.d.).

Data building and data wrangling

This dataset was created by randomized sampling (see random_mctq()) and by manual insertions of special cases. Its purpose is to demonstrate common cases and data issues that researchers may find in their MCTQ data, in addition to be a suggested data structure for MCTQ data.

You can see the shift_mctq build and data wrangling processes here.

Variable naming

The naming of the variables took into account the naming scheme used in MCTQ publications, in addition to the guidelines of the tidyverse style guide.

Variable classes

The mctq package works with a set of object classes specially created to hold time values. These classes can be found in the hms and lubridate package.

Duration objects

If you prefer to view Duration objects as hms objects, run pretty_mctq(shift_mctq).

Source

Created by Daniel Vartanian (package author).

References

Ghotbi, N., Pilz, L. K., Winnebeck, E. C., Vetter, C., Zerbini, G., Lenssen, D., Frighetto, G., Salamanca, M., Costa, R., Montagnese, S., & Roenneberg, T. (2020). The $\mu$MCTQ: an ultra-short version of the Munich ChronoType Questionnaire. Journal of Biological Rhythms, 35(1), 98-110. doi:10.1177/0748730419886986

Jankowski K. S. (2017). Social jet lag: sleep-corrected formula. Chronobiology International, 34(4), 531-535. doi:10.1080/07420528.2017.1299162

Juda, M., Vetter, C., & Roenneberg, T. (2013). The Munich ChronoType Questionnaire for shift-workers (MCTQ$^{Shift}$). Journal of Biological Rhythms, 28(2), 130-140. doi:10.1177/0748730412475041

Roenneberg T., Allebrandt K. V., Merrow M., & Vetter C. (2012). Social jetlag and obesity. Current Biology, 22(10), 939-43. doi:10.1016/j.cub.2012.03.038

Roenneberg, T., Keller, L. K., Fischer, D., Matera, J. L., Vetter, C., & Winnebeck, E. C. (2015). Human activity and rest in situ. In A. Sehgal (Ed.), Methods in Enzymology (Vol. 552, pp. 257-283). Academic Press. doi:10.1016/bs.mie.2014.11.028

Roenneberg, T., Pilz, L. K., Zerbini, G., & Winnebeck, E. C. (2019). Chronotype and social jetlag: a (self-) critical review. Biology, 8(3), 54. doi:10.3390/biology8030054

Roenneberg, T., Wirz-Justice, A., & Merrow, M. (2003). Life between clocks: daily temporal patterns of human chronotypes. Journal of Biological Rhythms, 18(1), 80-90. doi:10.1177/0748730402239679

The Worldwide Experimental Platform (n.d.). MCTQ. https://www.thewep.org/documentations/mctq/

See Also

Other datasets: micro_mctq, std_mctq

---

Compute MCTQ social jetlag

Description

sjl() computes the relative or absolute social jetlag for standard, micro, and shift versions of the Munich ChronoType Questionnaire (MCTQ).

sjl_rel() is just a wrapper for sjl() with abs = FALSE.

Usage

sjl(msw, msf, abs = TRUE, method = "shorter")

sjl_rel(msw, msf, method = "shorter")

Arguments

msw	An hms object corresponding to the local time of mid-sleep on workdays from a standard, micro, or shift version of the MCTQ questionnaire. You can use msl() to compute it.
msf	An hms object corresponding to the local time of mid-sleep on work-free days from a standard, micro, or shift version of the MCTQ questionnaire. You can use msl() to compute it.
abs	(optional) a logical object indicating if the function must return an absolute value (default: TRUE).
method	(optional) a string indicating which method the function must use to compute the social jetlag. See the Methods section to learn more (default: "shorter").

Details

Standard MCTQ functions were created following the guidelines in Roenneberg, Wirz-Justice, & Merrow (2003), Roenneberg, Allebrandt, Merrow, & Vetter (2012), and from The Worldwide Experimental Platform (theWeP, n.d.).

$\mu$MCTQ functions were created following the guidelines in Ghotbi et al. (2020), in addition to the guidelines used for the standard MCTQ.

MCTQ$^{Shift}$ functions were created following the guidelines in Juda, Vetter, & Roenneberg (2013), in addition to the guidelines used for the standard MCTQ.

See the References section to learn more.

Class requirements

The mctq package works with a set of object classes specially created to hold time values. These classes can be found in the lubridate and hms packages. Please refer to those package documentations to learn more about them.

Rounding and fractional time

Some operations may produce an output with fractional time (e.g., "19538.3828571429s (~5.43 hours)", 01:15:44.505). If you want, you can round it with mctq:::round_time().

Our recommendation is to avoid rounding, but, if you do, make sure that you only round your values after all computations are done. That way you avoid round-off errors.

Value

• If abs = TRUE, a Duration object corresponding to the absolute social jetlag.

• If abs = FALSE, a Duration object corresponding to the relative social jetlag.

The output may also vary depending on the method used.

Guidelines

Roenneberg, Allebrandt, Merrow, & Vetter (2012), Juda, Vetter, & Roenneberg (2013), and The Worldwide Experimental Platform (n.d.) guidelines for sjl() ($SJL_{rel}$ and $SJL$) computation are as follows.

Notes

• For MCTQ$^{Shift}$, the computation below must be applied to each shift section of the questionnaire.

• Due to time arithmetic issues, sjl() does a slightly different computation by default than those proposed by the authors mentioned above. See vignette("sjl-computation", package = "mctq") for more details.

• If you are visualizing this documentation in plain text, you may have some trouble understanding the equations. You can see this documentation on the package website.

For standard and micro versions of the MCTQ

$SJL_{rel} = MSF - MSW$

$SJL = | MSF - MSW |$

Where:

• $SJL_{rel}$ = Relative social jetlag.

• $SJL$ = Absolute social jetlag.

• $MSW$ = Local time of mid-sleep on workdays.

• $MSF$ = Local time of mid-sleep on work-free days.

* $W$ = Workdays; $F$ = Work-free days.

For the shift version of the MCTQ

$SJL_{rel}^{M/E/N} = MSF^{M/E/N} - MSW^{M/E/N}$

$SJL^{M/E/N} = | MSF^{M/E/N} - MSW^{M/E/N} |$

Where:

• $SJL_{rel}^{M/E/N}$ = Relative social jetlag in a particular shift.

• $SJL^{M/E/N}$ = Absolute social jetlag in a particular shift.

• $MSW^{M/E/N}$ = Local time of mid-sleep between two days in a particular shift.

• $MSF^{M/E/N}$ = Local time of mid-sleep between two free days after a particular shift.

* $W$ = Workdays; $F$ = Work-free days, $M$ = Morning shift; $E$ = Evening shift; $N$ = Night shift.

Methods for computing the social jetlag

There are different approaches to compute the social jetlag ($SJL$). By default, sjl() uses an approach that we call "the shorter interval approach" ("shorter").

The topics below provide a simple explanation of each method supported by sjl(). To get a detail understating of this methods, see vignette("sjl-computation", package = "mctq").

• "difference"

By using method = "difference", sjl() will do the exact computation proposed by the MCTQ authors, i.e., $SJL$ will be computed as the linear difference between $MSF$ and $MSW$ (see the Guidelines section).

We do not recommend using this method, as it has many limitations.

• "shorter"

This is the default method for sjl(). It's based on the shorter interval between $MSW$ and $MSF$, solving most of the issues relating to $SJL$ computation.

• "longer"

The "longer" method uses the same logic of the "shorter" method, but, instead of using the shorter interval between $MSW$ and $MSF$, it uses the longer interval between the two, considering a two-day window.

This method may help in special contexts, like when dealing with shift-workers that have a greater than 12 hours distance between their mid-sleep hours.

References

Ghotbi, N., Pilz, L. K., Winnebeck, E. C., Vetter, C., Zerbini, G., Lenssen, D., Frighetto, G., Salamanca, M., Costa, R., Montagnese, S., & Roenneberg, T. (2020). The $\mu$MCTQ: an ultra-short version of the Munich ChronoType Questionnaire. Journal of Biological Rhythms, 35(1), 98-110. doi:10.1177/0748730419886986

Jankowski K. S. (2017). Social jet lag: sleep-corrected formula. Chronobiology International, 34(4), 531-535. doi:10.1080/07420528.2017.1299162

Juda, M., Vetter, C., & Roenneberg, T. (2013). The Munich ChronoType Questionnaire for shift-workers (MCTQ$^{Shift}$). Journal of Biological Rhythms, 28(2), 130-140. doi:10.1177/0748730412475041

Roenneberg T., Allebrandt K. V., Merrow M., & Vetter C. (2012). Social jetlag and obesity. Current Biology, 22(10), 939-43. doi:10.1016/j.cub.2012.03.038

Roenneberg, T., Pilz, L. K., Zerbini, G., & Winnebeck, E. C. (2019). Chronotype and social jetlag: a (self-) critical review. Biology, 8(3), 54. doi:10.3390/biology8030054

Roenneberg, T., Wirz-Justice, A., & Merrow, M. (2003). Life between clocks: daily temporal patterns of human chronotypes. Journal of Biological Rhythms, 18(1), 80-90. doi:10.1177/0748730402239679

The Worldwide Experimental Platform (n.d.). MCTQ. https://www.thewep.org/documentations/mctq/

See Also

Other MCTQ functions: fd(), gu(), le_week(), msf_sc(), msl(), napd(), sd24(), sd_overall(), sd_week(), sdu(), sjl_sc(), sjl_weighted(), so(), tbt()

Examples

## Scalar example

msw <- hms::parse_hm("03:30")
msf <- hms::parse_hm("05:00")

sjl(msw, msf)
#> [1] "5400s (~1.5 hours)" # Expected
sjl(msw, msf, abs = FALSE)
#> [1] "5400s (~1.5 hours)" # Expected
sjl_rel(msw, msf) # Wrapper function
#> [1] "5400s (~1.5 hours)" # Expected

msw <- hms::parse_hm("04:30")
msf <- hms::parse_hm("23:30")

sjl(msw, msf)
#> [1] "18000s (~5 hours)" # Expected
sjl(msw, msf, abs = FALSE)
#> [1] "18000s (~-5 hours)" # Expected
sjl_rel(msw, msf) # Wrapper function
#> [1] "18000s (~-5 hours)" # Expected

msw <- hms::as_hms(NA)
msf <- hms::parse_hm("05:15")

sjl(msw, msf)
#> [1] NA # Expected

## Vector example

msw <- c(hms::parse_hm("02:05"), hms::parse_hm("04:05"))
msf <- c(hms::parse_hm("23:05"), hms::parse_hm("04:05"))

sjl(msw, msf)
#> [1] "10800s (~3 hours)" "0s" # Expected
sjl(msw, msf, abs = FALSE)
#> [1] "-10800s (~-3 hours)" "0s" # Expected
sjl_rel(msw, msf) # Wrapper function
#> [1] "-10800s (~-3 hours)" "0s" # Expected

## Using different methods

msw <- hms::parse_hm("19:15")
msf <- hms::parse_hm("02:30")

sjl(msw, msf, abs = FALSE, method = "difference")
#> [1] "-60300s (~-16.75 hours)" # Expected
sjl(msw, msf, abs = FALSE, method = "shorter") # Default method
#> [1] "26100s (~7.25 hours)" # Expected
sjl(msw, msf, abs = FALSE, method = "longer")
#> [1] "-60300s (~-16.75 hours)" # Expected

msw <- hms::parse_hm("02:45")
msf <- hms::parse_hm("04:15")

sjl(msw, msf, abs = FALSE, method = "difference")
#> [1] "5400s (~1.5 hours)" # Expected
sjl(msw, msf, abs = FALSE, method = "shorter") # Default method
#> [1] "5400s (~1.5 hours)" # Expected
sjl(msw, msf, abs = FALSE, method = "longer")
#> [1] "-81000s (~-22.5 hours)" # Expected

## Converting the output to 'hms'

msw <- hms::parse_hm("01:15")
msf <- hms::parse_hm("03:25")
sjl(msw, msf)
#> [1] "7800s (~2.17 hours)" # Expected

hms::as_hms(as.numeric(sjl(msw, msf)))
#> 02:10:00 # Expected

## Rounding the output at the seconds level

msw <- hms::parse_hms("04:19:33.1234")
msf <- hms::parse_hms("02:55:05")
sjl(msw, msf)
#> [1] "5068.12339997292s (~1.41 hours)" # Expected

mctq:::round_time(sjl(msw, msf))
#> [1] "5068s (~1.41 hours)" # Expected

---