`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.

## 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.

## Value

A `Duration`

object corresponding to the vectorized weighted mean of
`sd_w`

and `sd_f`

with `n_w`

and `n_f`

as weights.

## 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 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.

## Guidelines

Juda, Vetter, & Roenneberg (2013) and The Worldwide Experimental Platform
(n.d.) guidelines for `sd_overall()`

(\(\emptyset SD^{M/E/N}\))
computation are as follows.

### Notes

The computation below must be applied to each shift section of the questionnaire. If you're using the three-shift design proposed by the 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 (

`ASCII`

), you may have some trouble understanding the equations. If you want a better viewer, you can see this documentation on the package website.

### Computation

**$$\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:

\(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/

## 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)"
#> [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)"
#> [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
#> [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)"
#> [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)"
#> [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
x <- sd_overall(sd_w, sd_f, n_w, n_f)
x
#> [1] "22500s (~6.25 hours)"
#> [1] "22500s (~6.25 hours)" # Expected
hms::as_hms(as.numeric(x))
#> 06:15:00
#> 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
x <- sd_overall(sd_w, sd_f, n_w, n_f)
x
#> [1] "26324.784s (~7.31 hours)"
#> [1] "26324.784s (~7.31 hours)" # Expected
round_time(x)
#> [1] "26325s (~7.31 hours)"
#> [1] "26325s (~7.31 hours)" # Expected
```