Skip to content

Commit

Permalink
Fix some minor documentation issues
Browse files Browse the repository at this point in the history
danielvartan committed May 3, 2022
1 parent f725020 commit b22b1bf
Showing 33 changed files with 132 additions and 142 deletions.
4 changes: 2 additions & 2 deletions R/assign_date.R
Original file line number Diff line number Diff line change
@@ -70,8 +70,8 @@
#' @param start,end An [`hms`][hms::hms()] or [`POSIXt`][base::as.POSIXct()]
#' object indicating the start or end hour.
#' @param ambiguity (optional) a [`numeric`][numeric()] or `NA` value to
#' instruct `assign_date()` on how to deal with ambiguities (see the Details
#' section to learn more) (default: `0`).
#' instruct `assign_date()` on how to deal with ambiguities. See the Details
#' section to learn more (default: `0`).
#'
#' @return A `start`--`end` [`Interval`][lubridate::interval()] object.
#'
8 changes: 4 additions & 4 deletions R/cycle_time.R
Original file line number Diff line number Diff line change
@@ -144,11 +144,11 @@
#' [`difftime`][base::as.difftime()], or [`hms`][hms::hms()].
#' @param cycle A [`numeric`][base::numeric()] or
#' [`Duration`][lubridate::duration()] object of length `1`, equal or greater
#' than `0`, indicating the cycle length in seconds (see the Details section
#' to learn more).
#' than `0`, indicating the cycle length in seconds. See the Details section
#' to learn more.
#' @param reverse (optional) a [`logical`][logical()] value indicating if the
#' function must use a reverse cycle for negative values in `time` (see
#' the Details section to learn more) (default: `TRUE`).
#' function must use a reverse cycle for negative values in `time`. See
#' the Details section to learn more (default: `TRUE`).
#'
#' @return The same type of object of `time` cycled with the `cycle` parameter.
#'
14 changes: 8 additions & 6 deletions R/fd.R
Original file line number Diff line number Diff line change
@@ -20,12 +20,14 @@
#' * \eqn{WD} = number of workdays ("I have a regular work schedule and work ___
#' days per week").
#'
#' @param wd An [integerish][checkmate::test_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.
#'
#' @return An `integer` object corresponding to the difference between the
#' number of days in a week (7) and the number of workdays (`wd`).
#' @param wd An [integerish][checkmate::test_integerish()]
#' [`numeric`][base::numeric()] object or an [`integer`][base::integer()]
#' object corresponding to the __number of workdays per week__ from a standard
#' or micro version of the MCTQ questionnaire.
#'
#' @return An [`integer`][base::integer()] object corresponding to the
#' difference between the number of days in a week (7) and the number of
#' workdays (`wd`).
#'
#' @template details_a
#' @template references_a
16 changes: 7 additions & 9 deletions R/gu.R
Original file line number Diff line number Diff line change
@@ -17,11 +17,9 @@
#'
#' * The computation below must be applied to each section of the
#' questionnaire.
#'
#' * MCTQ\eqn{^{Shift}}{ Shift} uses \eqn{TGU} (time to get up) instead of
#' \eqn{SI} (sleep inertia). For the purpose of this computation, both represent
#' the same thing.
#'
#' * 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
@@ -56,14 +54,14 @@
#' \strong{*} \eqn{W} = workdays; \eqn{F} = work-free days, \eqn{M} =
#' morning shift; \eqn{E} = evening shift; \eqn{N} = night shift.
#'
#' @param se A `hms` object corresponding to the __local time of sleep end__
#' from a standard or shift version of the MCTQ questionnaire.
#' @param si A `Duration` object corresponding to the __sleep inertia__ or
#' __time to get up__ from a standard or shift version of the MCTQ
#' questionnaire.
#' @param se An [`hms`][hms::hms()] object corresponding to the __local time of
#' sleep end__ from a standard or shift version of the MCTQ questionnaire.
#' @param si A [`Duration`][lubridate::duration()] object corresponding to the
#' "__sleep inertia__" or __time to get up__ from a standard or shift version
#' of the MCTQ questionnaire.
#'
#' @return A `hms` object corresponding to the vectorized sum of `se` and `si`
#' in a circular time frame of 24 hours.
#' @return An [`hms`][hms::hms()] object corresponding to the vectorized sum of
#' `se` and `si` in a circular time frame of 24 hours.
#'
#' @template details_b
#' @template references_a
1 change: 0 additions & 1 deletion R/le_week.R
Original file line number Diff line number Diff line change
@@ -17,7 +17,6 @@
#'
#' * The average weekly light exposure 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 (`ASCII`), you may
#' have some trouble understanding the equations. If you want a better viewer,
#' you can see this documentation on the package
10 changes: 2 additions & 8 deletions R/msl.R
Original file line number Diff line number Diff line change
@@ -24,7 +24,6 @@
#'
#' * The computation below must be applied to each section of the
#' questionnaire.
#'
#' * 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
@@ -135,26 +134,21 @@ msl <- function(so, sd) {
#'
#' * For all cases, \eqn{MSF_{sc}}{MSF_sc} cannot be computed if the participant
#' wakes up with an alarm clock on work-free days (\eqn{Alarm_F}{Alarm_F}).
#'
#' * For MCTQ\eqn{^{Shift}}{ Shift}, the computation below must be applied to
#' each shift section of the questionnaire.
#'
#' * \eqn{MSF_{sc}}{MSF_sc} is a proxy for the participant 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 (\eqn{MSF^E}{MSF_E}). In case work
#' schedules do not comprise evening shifts, Juda, Vetter, & Roenneberg (2013)
#' propose to derive it from the \eqn{MSF_{sc}}{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.
#'
#' * \eqn{MSF_{sc}}{MSF_sc} depends on developmental and environmental
#' conditions (e.g., age, light exposure). For epidemiological and genetic
#' studies, \eqn{MSF_{sc}}{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 (`ASCII`), you may
#' have some trouble understanding the equations. If you want a better viewer,
#' you can see this documentation on the package
@@ -197,7 +191,7 @@ msl <- function(so, sd) {
#' \strong{*} \eqn{W} = workdays; \eqn{F} = work-free days, \eqn{M} =
#' morning shift; \eqn{E} = evening shift; \eqn{N} = night shift.
#'
#' @param msf A `hms` object corresponding to the __local time of mid-sleep on
#' @param 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 [mctq::msl()] to compute it.
#' @param sd_w A `Duration` object corresponding to the __sleep duration on work
@@ -219,7 +213,7 @@ msl <- function(so, sd) {
#' questionnaire considers only the work-free days when the respondent does
#' not use an alarm.
#'
#' @return A `hms` object corresponding to the MCTQ chronotype or corrected
#' @return An `hms` object corresponding to the MCTQ chronotype or corrected
#' local time of mid-sleep on work-free days.
#'
#' @template details_b
15 changes: 4 additions & 11 deletions R/sdu.R
Original file line number Diff line number Diff line change
@@ -24,7 +24,6 @@
#'
#' * The computation below must be applied to each section of the
#' questionnaire.
#'
#' * 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
@@ -59,10 +58,10 @@
#' \strong{*} \eqn{W} = workdays; \eqn{F} = work-free days, \eqn{M} =
#' morning shift; \eqn{E} = evening shift; \eqn{N} = night shift.
#'
#' @param so A `hms` object corresponding to the __local time of sleep onset__
#' @param 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 [mctq::so()] to compute it for the standard or shift version.
#' @param se A `hms` object corresponding to the __local time of sleep end__
#' @param se An `hms` object corresponding to the __local time of sleep end__
#' from a standard, micro, or shift version of the MCTQ questionnaire.
#'
#' @return A `Duration` object corresponding to the vectorized difference
@@ -123,7 +122,6 @@ sdu <- function(so, se) {
#'
#' * The computation below must be applied to each shift section of the
#' questionnaire.
#'
#' * 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
@@ -146,9 +144,9 @@ sdu <- function(so, se) {
#' \strong{*} \eqn{W} = workdays; \eqn{F} = work-free days, \eqn{M} =
#' morning shift; \eqn{E} = evening shift; \eqn{N} = night shift.
#'
#' @param napo A `hms` object corresponding to the __local time of nap onset__
#' @param napo An `hms` object corresponding to the __local time of nap onset__
#' from the shift version of the MCTQ questionnaire.
#' @param nape A `hms` object corresponding to the __local time of nap end__
#' @param nape An `hms` object corresponding to the __local time of nap end__
#' from the shift version of the MCTQ questionnaire.
#'
#' @return A `Duration` object corresponding to the vectorized difference
@@ -209,11 +207,9 @@ napd <- function(napo, nape) {
#'
#' * The computation below must be applied to each shift 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
#' \eqn{SD_{W/F}^{M/E/N}}{SD_W/F_M/E/N}.
#'
#' * 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
@@ -325,7 +321,6 @@ sd24 <- function(sd, napd, nap) {
#'
#' * 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 (`ASCII`), you may
#' have some trouble understanding the equations. If you want a better viewer,
#' you can see this documentation on the package
@@ -459,10 +454,8 @@ sd_week <- function(sd_w, sd_f, wd) {
#' authors, you need to compute three overall sleep duration (e.g.,
#' \eqn{\emptyset SD^M}{OSD_M}; \eqn{\emptyset SD^E}{OSD_E}; \eqn{\emptyset
#' SD^N}{OSD_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
6 changes: 3 additions & 3 deletions R/shorter_interval.R
Original file line number Diff line number Diff line change
@@ -156,13 +156,13 @@
#' longer_duration(x, y)
#' #> [1] "72000s (~20 hours)" "63000s (~17.5 hours)" # Expected
shorter_interval <- function(x, y) {
distance_interval(x, y, method = "shorter")
interval_build(x, y, method = "shorter")
}

#' @rdname shorter_interval
#' @export
longer_interval <- function(x, y) {
distance_interval(x, y, method = "longer")
interval_build(x, y, method = "longer")
}

#' @rdname shorter_interval
@@ -177,7 +177,7 @@ longer_duration <- function(x, y) {
longer_interval(x, y) %>% lubridate::as.duration()
}

distance_interval <- function(x, y, method = "shorter") {
interval_build <- function(x, y, method = "shorter") {
method_choices <- c("shorter", "longer")

checkmate::assert_multi_class(x, c("hms", "POSIXt"))
42 changes: 21 additions & 21 deletions R/sjl.R
Original file line number Diff line number Diff line change
@@ -260,7 +260,7 @@ sjl_rel <- function(msw, msf, method = "shorter") {
#'
#' In an article published in 2017, Konrad S. Jankowski argued that the original
#' formula for computing the social jetlag (\eqn{SJL}) captures not only the
#' misalignment between social and biological times, but also the sleep debt
#' misalignment between social and biological time, but also the sleep debt
#' resulting from sleep deprivation during workdays. Jankowski than proposed the
#' following guideline for the `sjl_sc()` (\eqn{SJL_{sc}}{SJL_sc}) computation.
#'
@@ -288,9 +288,9 @@ sjl_rel <- function(msw, msf, method = "shorter") {
#' Where:
#'
#' * \eqn{SO_W} = local time of sleep onset on workdays.
#' * \eqn{SE_W} = local time of sleep end/offset on workdays.
#' * \eqn{SE_W} = local time of sleep end on workdays.
#' * \eqn{SO_F} = local time of sleep onset on work-free days.
#' * \eqn{SE_F} = local time of sleep end/offset on work-free days.
#' * \eqn{SE_F} = local time of sleep end on work-free days.
#'
#' \strong{*} \eqn{W} = workdays; \eqn{F} = work-free days.
#'
@@ -307,12 +307,12 @@ sjl_rel <- function(msw, msf, method = "shorter") {
#'
#' * \eqn{SO_W^{M/E/N}} = local time of sleep onset between two days in a
#' particular shift.
#' * \eqn{SE_W^{M/E/N}} = local time of sleep end/offset between two days in a
#' * \eqn{SE_W^{M/E/N}} = local time of sleep end between two days in a
#' particular shift.
#' * \eqn{SO_F^{M/E/N}} = local time of sleep onset between two free days after
#' a particular shift.
#' * \eqn{SE_F^{M/E/N}} = local time of sleep end/offset between two free days
#' after a particular shift.
#' * \eqn{SE_F^{M/E/N}} = local time of sleep end between two free days after a
#' particular shift.
#'
#' \strong{*} \eqn{W} = workdays; \eqn{F} = work-free days, \eqn{M} =
#' morning shift; \eqn{E} = evening shift; \eqn{N} = night shift.
@@ -359,15 +359,15 @@ sjl_rel <- function(msw, msf, method = "shorter") {
#' the MCTQ questionnaire. You can use [`so()`][mctq::so()] to compute it for
#' the standard or shift version.
#' @param se_w An [`hms`][hms::hms()] object corresponding to the __local time
#' of sleep end/offset on workdays__ from a standard, micro, or shift version
#' of the MCTQ questionnaire.
#' of sleep end on workdays__ from a standard, micro, or shift version of the
#' MCTQ questionnaire.
#' @param so_f An [`hms`][hms::hms()] object corresponding to the __local time
#' of sleep onset on work-free days__ from a standard, micro, or shift version
#' of the MCTQ questionnaire. You can use [`so()`][mctq::so()] to compute it
#' for the standard or shift version.
#' @param se_f An [`hms`][hms::hms()] object corresponding to the __local time
#' of sleep end/offset on work-free days__ from a standard, micro, or shift
#' version of the MCTQ questionnaire.
#' of sleep end on work-free days__ from a standard, micro, or shift version
#' of the MCTQ questionnaire.
#'
#' @return
#'
@@ -568,12 +568,10 @@ sjl_sc_rel <- function(so_w, se_w, so_f, se_f, method = "shorter") {
#' * The absolute social jetlag across all shifts (\eqn{\emptyset
#' SJL_{weighted}}{OSJL_weighted}) is the weighted average of all absolute
#' social jetlags.
#'
#' * The authors describe an equation for a three-shift schedule, but this may
#' not be your case. That's why this function works a little bit differently
#' (see the Operation section), allowing you to compute a weighted average with
#' any shift combination.
#'
#' * 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
@@ -594,18 +592,20 @@ sjl_sc_rel <- function(so_w, se_w, so_f, se_f, method = "shorter") {
#' \strong{*} \eqn{W} = workdays; \eqn{F} = work-free days, \eqn{M} =
#' morning shift; \eqn{E} = evening shift; \eqn{N} = night shift.
#'
#' @param sjl A `list` object with `Duration` elements corresponding to the
#' @param sjl A [`list`][base::list()] object with
#' [`Duration`][lubridate::duration()] elements corresponding to the
#' __absolute social jetlag in each shift__ from a shift version of the MCTQ
#' questionnaire (you can use [mctq::sjl()] to compute it). `sjl` elements and
#' values must be paired with `n` elements and values.
#' @param n_w A `list` object with [integerish][checkmate::test_integerish()]
#' `integer` or `double` elements corresponding to the __number of days worked
#' in each shift within a shift cycle__ from a shift version of the MCTQ
#' questionnaire. `n` elements and values must be paired with `sjl` elements
#' and values.
#'
#' @return A `Duration` object corresponding to the vectorized weighted mean of
#' `sjl` with `n_w` as weights.
#' @param n_w A [`list`][base::list()] object with
#' [integerish][checkmate::test_integerish()] [`integer`][base:integer()] or
#' [`double`][base::double()] elements corresponding to the __number of days
#' worked in each shift within a shift cycle__ from a shift version of the
#' MCTQ questionnaire. `n` elements and values must be paired with `sjl`
#' elements and values.
#'
#' @return A [`Duration`][lubridate::duration()] object corresponding to the
#' vectorized weighted mean of `sjl` with `n_w` as weights.
#'
#' @template details_b
#' @template references_a
7 changes: 3 additions & 4 deletions R/so.R
Original file line number Diff line number Diff line change
@@ -20,7 +20,6 @@
#'
#' * The computation below must be applied to each section of the
#' questionnaire.
#'
#' * 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
@@ -60,13 +59,13 @@
#' morning shift; \eqn{E} = evening shift; \eqn{N} = night shift.
#'
#'
#' @param sprep A `hms` object corresponding to the __local time of preparing to
#' sleep__ from a standard or shift version of the MCTQ questionnaire.
#' @param sprep An `hms` object corresponding to the __local time of preparing
#' to sleep__ from a standard or shift version of the MCTQ questionnaire.
#' @param slat A `Duration` object corresponding to the __sleep latency or time
#' to fall asleep after preparing to sleep__ from a standard or shift version
#' of the MCTQ questionnaire.
#'
#' @return A `hms` object corresponding to the vectorized sum of `sprep` and
#' @return An `hms` object corresponding to the vectorized sum of `sprep` and
#' `slat` in a circular time frame of 24 hours.
#'
#' @template details_b
7 changes: 3 additions & 4 deletions R/tbt.R
Original file line number Diff line number Diff line change
@@ -17,7 +17,6 @@
#'
#' * The computation below must be applied to each section of the
#' questionnaire.
#'
#' * 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
@@ -53,11 +52,11 @@
#' morning shift; \eqn{E} = evening shift; \eqn{N} = night shift.
#'
#'
#' @param bt A `hms` object corresponding to the __local time of going to bed__
#' @param bt An `hms` object corresponding to the __local time of going to bed__
#' from a standard or shift version of the MCTQ questionnaire.
#' @param gu A `hms` object corresponding to the __local time of getting out of
#' @param gu An `hms` object corresponding to the __local time of getting out of
#' bed__ from a standard or shift version of the MCTQ questionnaire. You can
#' use [mctq::gu()] to compute it.
#' use [`gu()`][mctq::gu()] to compute it.
#'
#' @return A `Duration` object corresponding to the vectorized difference
#' between `gu` and `bt` in a circular time frame of 24 hours.
2 changes: 1 addition & 1 deletion R/utils-checks.R
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Sort by type or by alphabetical order.
# Sort by type or alphabetical order.

test_length_one <- function(x) length(x) == 1

2 changes: 1 addition & 1 deletion R/utils-dialogs.R
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Sort by type or by alphabetical order.
# Sort by type or alphabetical order.

dialog_line <- function(..., space_above = TRUE, space_below = TRUE,
abort = FALSE) {
Loading
Oops, something went wrong.

0 comments on commit b22b1bf

Please sign in to comment.