diff --git a/.github/workflows/check-standard.yaml b/.github/workflows/check-standard.yaml index a3ac618..2579d82 100644 --- a/.github/workflows/check-standard.yaml +++ b/.github/workflows/check-standard.yaml @@ -1,5 +1,6 @@ # Workflow derived from https://github.com/r-lib/actions/tree/v2/examples # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help + on: push: branches: [main, master] @@ -8,6 +9,8 @@ on: name: R-CMD-check +permissions: read-all + jobs: R-CMD-check: runs-on: ${{ matrix.config.os }} @@ -29,7 +32,7 @@ jobs: R_KEEP_PKG_SOURCE: yes steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - uses: r-lib/actions/setup-pandoc@v2 @@ -47,3 +50,4 @@ jobs: - uses: r-lib/actions/check-r-package@v2 with: upload-snapshots: true + build_args: 'c("--no-manual","--compact-vignettes=gs+qpdf")' diff --git a/.github/workflows/test-coverage.yaml b/.github/workflows/test-coverage.yaml index 2c5bb50..e5009c4 100644 --- a/.github/workflows/test-coverage.yaml +++ b/.github/workflows/test-coverage.yaml @@ -1,5 +1,6 @@ # Workflow derived from https://github.com/r-lib/actions/tree/v2/examples # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help + on: push: branches: [main, master] @@ -8,6 +9,8 @@ on: name: test-coverage +permissions: read-all + jobs: test-coverage: runs-on: ubuntu-latest @@ -15,7 +18,7 @@ jobs: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - uses: r-lib/actions/setup-r@v2 with: @@ -23,28 +26,37 @@ jobs: - uses: r-lib/actions/setup-r-dependencies@v2 with: - extra-packages: any::covr + extra-packages: any::covr, any::xml2 needs: coverage - name: Test coverage run: | - covr::codecov( + cov <- covr::package_coverage( quiet = FALSE, clean = FALSE, - install_path = file.path(Sys.getenv("RUNNER_TEMP"), "package") + install_path = file.path(normalizePath(Sys.getenv("RUNNER_TEMP"), winslash = "/"), "package") ) + covr::to_cobertura(cov) shell: Rscript {0} + - uses: codecov/codecov-action@v4 + with: + fail_ci_if_error: ${{ github.event_name != 'pull_request' && true || false }} + file: ./cobertura.xml + plugin: noop + disable_search: true + token: ${{ secrets.CODECOV_TOKEN }} + - name: Show testthat output if: always() run: | ## -------------------------------------------------------------------- - find ${{ runner.temp }}/package -name 'testthat.Rout*' -exec cat '{}' \; || true + find '${{ runner.temp }}/package' -name 'testthat.Rout*' -exec cat '{}' \; || true shell: bash - name: Upload test results if: failure() - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: coverage-test-failures path: ${{ runner.temp }}/package diff --git a/.gitignore b/.gitignore index 732da65..5356b1d 100644 --- a/.gitignore +++ b/.gitignore @@ -55,6 +55,6 @@ po/*~ # End of https://www.toptal.com/developers/gitignore/api/r # Others -.archive/ -pkgdown/ -revdep/ +/.archive/ +/pkgdown/ +/revdep/ diff --git a/CITATION.cff b/CITATION.cff index 0c78969..91136c0 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -1,18 +1,19 @@ -# ----------------------------------------------------------- -# CITATION file created with {cffr} R package, v0.5.0 +# -------------------------------------------- +# CITATION file created with {cffr} R package # See also: https://docs.ropensci.org/cffr/ -# ----------------------------------------------------------- +# -------------------------------------------- cff-version: 1.2.0 message: 'To cite package "mctq" in publications use:' type: software license: MIT -title: 'mctq: Tools to Process the Munich ChronoType Questionnaire (MCTQ)' -version: 0.3.2.9000 -abstract: A complete toolkit to process the Munich ChronoType Questionnaire (MCTQ) - for its three versions (standard, micro, and shift). MCTQ is a quantitative and - validated tool to assess chronotypes using peoples' sleep behavior, originally presented - by Till Roenneberg, Anna Wirz-Justice, and Martha Merrow (2003, ). +title: 'mctq: Munich ChronoType Questionnaire Tools' +version: 0.3.2.9001 +abstract: 'A complete toolkit for processing the Munich ChronoType Questionnaire (MCTQ) + in its three versions: standard, micro, and shift. The MCTQ is a quantitative and + validated tool used to assess chronotypes based on individuals'' sleep behavior. + It was originally presented by Till Roenneberg, Anna Wirz-Justice, and Martha Merrow + in 2003 (2003, ).' authors: - family-names: Vartanian given-names: Daniel @@ -20,15 +21,15 @@ authors: orcid: https://orcid.org/0000-0001-7782-759X preferred-citation: type: unpublished - title: 'mctq: tools to process the Munich ChronoType Questionnaire (MCTQ)' + title: 'mctq: Munich ChronoType Questionnaire tools' authors: - family-names: Vartanian given-names: Daniel email: danvartan@gmail.com orcid: https://orcid.org/0000-0001-7782-759X - year: '2023' + year: '2024' url: https://docs.ropensci.org/mctq/ - notes: R package version 0.3.2.9000 + notes: R package version 0.3.2.9001 repository: https://bioconductor.org/ repository-code: https://github.com/ropensci/mctq/issues/ url: https://docs.ropensci.org/mctq/ @@ -44,11 +45,10 @@ references: url: https://www.R-project.org/ authors: - name: R Core Team - location: - name: Vienna, Austria - year: '2023' institution: name: R Foundation for Statistical Computing + address: Vienna, Austria + year: '2024' version: '>= 4.2' - type: software title: checkmate @@ -61,7 +61,7 @@ references: given-names: Michel email: michellang@gmail.com orcid: https://orcid.org/0000-0001-9754-0393 - year: '2023' + year: '2024' version: '>= 2.2.0' - type: software title: cli @@ -73,7 +73,7 @@ references: - family-names: Csárdi given-names: Gábor email: csardi.gabor@gmail.com - year: '2023' + year: '2024' version: '>= 3.6.1' - type: software title: dplyr @@ -98,7 +98,7 @@ references: given-names: Davis email: davis@posit.co orcid: https://orcid.org/0000-0003-4777-038X - year: '2023' + year: '2024' version: '>= 1.1.2' - type: software title: hms @@ -111,7 +111,7 @@ references: given-names: Kirill email: kirill@cynkra.com orcid: https://orcid.org/0000-0002-1416-3412 - year: '2023' + year: '2024' version: '>= 1.1.3' - type: software title: lifecycle @@ -122,12 +122,12 @@ references: authors: - family-names: Henry given-names: Lionel - email: lionel@rstudio.com + email: lionel@posit.co - family-names: Wickham given-names: Hadley - email: hadley@rstudio.com + email: hadley@posit.co orcid: https://orcid.org/0000-0003-4757-117X - year: '2023' + year: '2024' version: '>= 1.0.3' - type: software title: lubridate @@ -143,7 +143,7 @@ references: given-names: Garrett - family-names: Wickham given-names: Hadley - year: '2023' + year: '2024' version: '>= 1.9.2' - type: software title: covr @@ -155,7 +155,7 @@ references: - family-names: Hester given-names: Jim email: james.f.hester@gmail.com - year: '2023' + year: '2024' version: '>= 3.6.2' - type: software title: datasets @@ -163,11 +163,10 @@ references: notes: Suggests authors: - name: R Core Team - location: - name: Vienna, Austria - year: '2023' institution: name: R Foundation for Statistical Computing + address: Vienna, Austria + year: '2024' version: '>= 4.2.0' - type: software title: knitr @@ -180,7 +179,7 @@ references: given-names: Yihui email: xie@yihui.name orcid: https://orcid.org/0000-0003-0645-5666 - year: '2023' + year: '2024' version: '>= 1.43' - type: software title: mockr @@ -192,7 +191,7 @@ references: - family-names: Müller given-names: Kirill email: kirill@cynkra.com - year: '2023' + year: '2024' version: '>= 0.2.1' - type: software title: readr @@ -210,7 +209,7 @@ references: given-names: Jennifer email: jenny@posit.co orcid: https://orcid.org/0000-0002-6983-2759 - year: '2023' + year: '2024' version: '>= 2.1.4' - type: software title: rlang @@ -225,7 +224,7 @@ references: - family-names: Wickham given-names: Hadley email: hadley@posit.co - year: '2023' + year: '2024' version: '>= 1.1.1' - type: software title: rmarkdown @@ -269,13 +268,13 @@ references: given-names: Richard email: rich@posit.co orcid: https://orcid.org/0000-0003-3925-190X - year: '2023' + year: '2024' version: '>= 2.23' - type: software title: spelling abstract: 'spelling: Tools for Spell Checking in R' notes: Suggests - url: https://docs.ropensci.org/spelling/ + url: https://ropensci.r-universe.dev/spelling repository: https://CRAN.R-project.org/package=spelling authors: - family-names: Ooms @@ -285,7 +284,7 @@ references: - family-names: Hester given-names: Jim email: james.hester@rstudio.com - year: '2023' + year: '2024' version: '>= 2.2.1' - type: software title: stats @@ -293,11 +292,10 @@ references: notes: Suggests authors: - name: R Core Team - location: - name: Vienna, Austria - year: '2023' institution: name: R Foundation for Statistical Computing + address: Vienna, Austria + year: '2024' version: '>= 4.2.0' - type: software title: testthat @@ -309,7 +307,7 @@ references: - family-names: Wickham given-names: Hadley email: hadley@posit.co - year: '2023' + year: '2024' version: '>= 3.1.10' - type: software title: usethis @@ -334,7 +332,7 @@ references: given-names: Andy email: andy.teucher@posit.co orcid: https://orcid.org/0000-0002-7840-692X - year: '2023' + year: '2024' version: '>= 2.2.2' - type: software title: utils @@ -342,12 +340,12 @@ references: notes: Suggests authors: - name: R Core Team - location: - name: Vienna, Austria - year: '2023' institution: name: R Foundation for Statistical Computing + address: Vienna, Austria + year: '2024' version: '>= 4.2.0' identifiers: - type: url value: https://github.com/ropensci/mctq/ + diff --git a/DESCRIPTION b/DESCRIPTION index 6e06b58..91b2a32 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,52 +1,53 @@ Package: mctq -Title: Tools to Process the Munich ChronoType Questionnaire (MCTQ) -Version: 0.3.2.9000 +Title: Munich ChronoType Questionnaire Tools +Version: 0.3.2.9001 Authors@R: c( - person( - given = "Daniel", - family = "Vartanian", - role = c("aut", "cre", "ccp", "cph"), - email = "danvartan@gmail.com", - comment = c(ORCID = "0000-0001-7782-759X") - ), - person( - given = "Ana Amelia", - family = "Benedito Silva", - role = c("sad"), - email = "aamelia@usp.br", - comment = c(ORCID = "0000-0003-4976-2623") - ), - person( - given = "Mario", - family = "Pedrazzoli", - role = c("sad"), - email = "pedrazzo@usp.br", - comment = c(ORCID = "0000-0002-5257-591X") - ), - person( - given = "Jonathan", - family = "Keane", - role = c("rev"), - email = "jkeane@gmail.com", - comment = c(ORCID = "0000-0001-7087-9776") - ), - person( - given = "Mario Andre", - family = "Leocadio-Miguel", - role = c("rev"), - email = "miguel.ml.mario@gmail.com", - comment = c(ORCID = "0000-0002-7248-3529") - ), - person( - given = "University of Sao Paulo (USP)", - role = c("fnd") - ) + person( + given = "Daniel", + family = "Vartanian", + role = c("aut", "cre", "ccp", "cph"), + email = "danvartan@gmail.com", + comment = c(ORCID = "0000-0001-7782-759X") + ), + person( + given = "Ana Amelia", + family = "Benedito Silva", + role = c("sad"), + email = "aamelia@usp.br", + comment = c(ORCID = "0000-0003-4976-2623") + ), + person( + given = "Mario", + family = "Pedrazzoli", + role = c("sad"), + email = "pedrazzo@usp.br", + comment = c(ORCID = "0000-0002-5257-591X") + ), + person( + given = "Jonathan", + family = "Keane", + role = c("rev"), + email = "jkeane@gmail.com", + comment = c(ORCID = "0000-0001-7087-9776") + ), + person( + given = "Mario Andre", + family = "Leocadio-Miguel", + role = c("rev"), + email = "miguel.ml.mario@gmail.com", + comment = c(ORCID = "0000-0002-7248-3529") + ), + person( + given = "University of Sao Paulo (USP)", + role = c("fnd") ) -Description: A complete toolkit to process the Munich ChronoType - Questionnaire (MCTQ) for its three versions (standard, micro, and shift). - MCTQ is a quantitative and validated tool to assess chronotypes using - peoples' sleep behavior, originally presented by Till Roenneberg, Anna - Wirz-Justice, and Martha Merrow (2003, ). + ) +Description: A complete toolkit for processing the Munich ChronoType + Questionnaire (MCTQ) in its three versions: standard, micro, and shift. + The MCTQ is a quantitative and validated tool used to assess chronotypes + based on individuals' sleep behavior. It was originally presented by Till + Roenneberg, Anna Wirz-Justice, and Martha Merrow in 2003 + (2003, ). biocViews: Infrastructure, Preprocessing, Visualization License: MIT + file LICENSE URL: https://docs.ropensci.org/mctq/, https://github.com/ropensci/mctq/ @@ -80,4 +81,4 @@ Encoding: UTF-8 Language: en-US LazyData: true Roxygen: list(markdown = TRUE) -RoxygenNote: 7.2.3 +RoxygenNote: 7.3.1 diff --git a/LICENSE b/LICENSE index 8a42935..fb61e25 100644 --- a/LICENSE +++ b/LICENSE @@ -1,2 +1,2 @@ -YEAR: 2023 +YEAR: 2024 COPYRIGHT HOLDER: Daniel Vartanian diff --git a/LICENSE.md b/LICENSE.md index 6739eec..58285c2 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,6 +1,6 @@ # MIT License -Copyright (c) 2023 Daniel Vartanian +Copyright (c) Daniel Vartanian Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/NEWS.md b/NEWS.md index 79fff1b..f635620 100644 --- a/NEWS.md +++ b/NEWS.md @@ -9,15 +9,17 @@ `shorter_interval()`, `longer_interval()`, `shorter_duration()`, `longer_duration()`, `sum_time()`, and `vct_sum_time()` were removed. These functions were deprecated on `mctq` 0.3.2. You can still - find them in the [`lubritime`](https://github.com/giperbio/lubritime) package. + find them in the [`lubritime`](https://github.com/danielvartan/lubritime) package. * The utility function `qplot_walk()` was removed. This function was deprecated on `mctq` 0.3.2. You can still find it in the - [`gutils`](https://github.com/giperbio/gutils) package. + [`rutils`](https://github.com/danielvartan/rutils) package. * The `ggplot2` package was removed as an import. It was only needed for `qplot_walk()`. * The dependencies versions were updated. * Code indentation was changed to 2 spaces (it was 4 spaces). * `magrittr` pipe (`%>%`) was changed to the native R pipe (`|>`) when possible. +* MCTQ now has a CRAN DOI: [10.32614/CRAN.package.mctq](https://doi.org/10.32614/CRAN.package.mctq). +* The vignette "Why Duration and not Period?" was removed. # mctq 0.3.2 (2023-02-19) @@ -30,10 +32,10 @@ `shorter_interval()`, `longer_interval()`, `shorter_duration()`, `longer_duration()`, `sum_time()`, and `vct_sum_time()` are now deprecated. These functions will be removed on the next `mctq` version. You can still find - them in the [`lubritime`](https://github.com/giperbio/lubritime) package. + them in the [`lubritime`](https://github.com/danielvartan/lubritime) package. * The utility function `qplot_walk()` is now deprecated. This function will be removed on the next `mctq` version. You can still find it in the - [`gutils`](https://github.com/giperbio/gutils) package. + [`rutils`](https://github.com/danielvartan/rutils) package. * `qplot_walk()` now uses `ggplot2::geom_bar()` or `ggplot2::geom_histogram()` to generate plots. It used `ggplot2::qplot()` before, now deprecated. * The `ggplot2` package was added as an import. It's needed while `qplot_walk()` diff --git a/README.Rmd b/README.Rmd index 408c2ac..ce9e5f7 100644 --- a/README.Rmd +++ b/README.Rmd @@ -21,10 +21,11 @@ library(hms) [![Status at rOpenSci Software Peer Review](https://badges.ropensci.org/434_status.svg)](https://github.com/ropensci/software-review/issues/434) +[![Repo status](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) [![CRAN status](https://www.r-pkg.org/badges/version/mctq)](https://cran.r-project.org/package=mctq) +[![CRAN DOI](http://img.shields.io/badge/DOI-10.32614/CRAN.package.mctq-1284C5.svg)](https://doi.org/10.32614/CRAN.package.mctq) [![CRAN downloads](https://cranlogs.r-pkg.org/badges/grand-total/mctq)](https://cran.r-project.org/package=mctq) -[![mctq status badge](https://ropensci.r-universe.dev/badges/mctq)](https://ropensci.r-universe.dev) -[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) +[![R-universe](https://ropensci.r-universe.dev/badges/mctq)](https://ropensci.r-universe.dev) [![Lifecycle: maturing](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://lifecycle.r-lib.org/articles/stages.html#maturing) [![R-CMD-check](https://github.com/ropensci/mctq/workflows/R-CMD-check/badge.svg)](https://github.com/ropensci/mctq/actions) [![Codecov test coverage](https://codecov.io/gh/ropensci/mctq/branch/main/graph/badge.svg)](https://app.codecov.io/gh/ropensci/mctq?branch=main) @@ -35,26 +36,26 @@ library(hms) ## Overview -`mctq` is an R package that provides a complete toolkit to process the Munich ChronoType Questionnaire (MCTQ), a quantitative and validated tool to assess chronotypes using peoples' sleep behavior presented by Till Roenneberg, Anna Wirz-Justice, and Martha Merrow in [2003](https://doi.org/10.1177/0748730402239679). Its aim is to facilitate the work of sleep and chronobiology scientists with MCTQ data and to improve reproducibility in research. +`mctq` is an R package that provides a complete toolkit to process the Munich ChronoType Questionnaire (MCTQ), a quantitative and validated tool to assess chronotypes using individuals' sleep behavior, as presented by Till Roenneberg, Anna Wirz-Justice, and Martha Merrow in [2003](https://doi.org/10.1177/0748730402239679). Its aim is to facilitate the work of sleep and chronobiology scientists with MCTQ data and improve reproducibility in research. `mctq` adheres to the [tidyverse principles](https://tidyverse.tidyverse.org/articles/manifesto.html) and integrates with the [tidyverse ecosystem](https://www.tidyverse.org/). Learn more about the MCTQ questionnaire at . -### Wait, an R package for a questionnaire? +### Why an R package for a questionnaire? -Although it may look like a simple questionnaire, MCTQ requires a lot of date/time manipulation. This poses a challenge for many scientists, being that most people have difficulties with date/time data, especially when dealing with an extensive dataset. The `mctq` package comes to address this issue. +Although it may seem like a simple questionnaire, MCTQ requires extensive date/time manipulation, which poses challenges for many scientists. The `mctq` package addresses this issue by providing tools to handle the processing tasks for the three MCTQ versions (standard, micro, and shift) with few dependencies, relying mainly on the [lubridate](https://lubridate.tidyverse.org/) and [hms](https://hms.tidyverse.org/) packages from [tidyverse](https://www.tidyverse.org/). -`mctq` can handle the processing tasks for the three MCTQ versions (standard, micro, and shift) with few dependencies, relying much of its applications on the [lubridate](https://lubridate.tidyverse.org/) and [hms](https://hms.tidyverse.org/) packages from [tidyverse](https://www.tidyverse.org/). We also designed `mctq` with the user experience in mind, by creating an interface that resembles the way the questionnaire data is shown in MCTQ publications, and by providing extensive and detailed documentation about each computation proposed by the MCTQ authors. The package also includes fictional datasets for testing and learning purposes. +We designed `mctq` with user experience in mind, creating an interface that resembles the questionnaire data as shown in MCTQ publications and providing extensive documentation about each computation proposed by the MCTQ authors. The package also includes fictional datasets for testing and learning purposes. ## Prerequisites -You need to have some familiarity with the [R programming language](https://www.r-project.org/) and with the [lubridate](https://lubridate.tidyverse.org/) and [hms](https://hms.tidyverse.org/) packages from [tidyverse](https://www.tidyverse.org/) to use `mctq` main functions. +You need some familiarity with the [R programming language](https://www.r-project.org/) and the [lubridate](https://lubridate.tidyverse.org/) and [hms](https://hms.tidyverse.org/) packages from [tidyverse](https://www.tidyverse.org/) to use `mctq`'s main functions. -If you don't feel comfortable with R, we strongly recommend checking Hadley Wickham and Garrett Grolemund's free and online book [R for Data Science](https://r4ds.had.co.nz/) and the Coursera course from John Hopkins University [Data Science: Foundations using R](https://www.coursera.org/specializations/data-science-foundations-r) (free for audit students). +If you are new to R, we recommend Hadley Wickham and Garrett Grolemund's free online book [R for Data Science](https://r4ds.hadley.nz/) and the Coursera course from Johns Hopkins University [Data Science: Foundations using R](https://www.coursera.org/specializations/data-science-foundations-r) (free for audit students). -Please refer to the [lubridate](https://lubridate.tidyverse.org/) and [hms](https://hms.tidyverse.org/) package documentation to learn more about them. These two are essential packages to deal with date/time data in R. We also recommend that you read the [Dates and times](https://r4ds.had.co.nz/dates-and-times.html) chapter from Wickham & Grolemund's book [R for Data Science](https://r4ds.had.co.nz/). +Please refer to the [lubridate](https://lubridate.tidyverse.org/) and [hms](https://hms.tidyverse.org/) documentation to learn more about handling date/time data in R. We also recommend reading the [Dates and times](https://r4ds.hadley.nz/datetimes) chapter from Wickham & Grolemund's book [R for Data Science](https://r4ds.hadley.nz/). ## Installation @@ -73,17 +74,15 @@ remotes::install_github("ropensci/mctq") ## Usage -`mctq` makes use of the [lubridate](https://lubridate.tidyverse.org/) and [hms](https://hms.tidyverse.org/) packages from [tidyverse](https://www.tidyverse.org/), which provide special objects to deal with date/time values in R. If your dataset does not conform to this structure, you first need to convert your data to it. Please refer to those package documentations to learn more about them. +`mctq` uses the [lubridate](https://lubridate.tidyverse.org/) and [hms](https://hms.tidyverse.org/) packages, which provide special objects to handle date/time values in R. Ensure your dataset conforms to this structure before using `mctq`. Refer to the respective package documentation for more details. -Due to the [circular nature of time](https://youtu.be/eelVqfm8vVc), we strongly recommend that you use appropriate temporal objects while dealing with date/time in R. This can help you get rid of several computation mistakes while trying to adapt your data from a base 10 to a system rooted in a base 12 numerical system. +Because of the [circular nature of time](https://youtu.be/eelVqfm8vVc), using appropriate temporal objects is crucial to avoid computation mistakes while adapting data from a base 10 to a base 12 numerical system. -For a more detailed explanation of the `mctq` usage, go to our [Get started guide](https://docs.ropensci.org/mctq/articles/mctq.html). +For detailed usage instructions, visit our [Get started guide](https://docs.ropensci.org/mctq/articles/mctq.html). ### Workdays and work-free days variables -After your data is set to start, just use the `mctq` functions below to process it. - -Note that the `mctq` functions uses a similar naming pattern to those used in the MCTQ publications. This makes it easy to find and apply any computation necessary. +After preparing your data, use the following `mctq` functions to process it. The function names follow the patterns used in MCTQ publications, making it easy to apply the necessary computations: * `fd()`: compute MCTQ work-free days. * `so()`: compute MCTQ local time of sleep onset. @@ -131,13 +130,13 @@ sjl_rel(msw, msf) ### Utilities -`mctq` is also equipped with some utility tools to help with your MCTQ data. The package also provides fictional datasets of the standard, micro, and shift MCTQ versions for testing and learning purposes. +`mctq` includes utility tools to help with your MCTQ data and provides fictional datasets for the standard, micro, and shift MCTQ versions for testing and learning purposes. -All functions are properly documented, showing all the guidelines behind the computations. Click [here](https://docs.ropensci.org/mctq/reference/index.html) to see a list of them. +All functions are documented with guidelines behind the computations. Click [here](https://docs.ropensci.org/mctq/reference/index.html) to see the full list. ## Citation -If you use `mctq` in your research, please consider citing it. We put a lot of work to build and maintain a free and open-source R package. You can find the citation below. +If you use `mctq` in your research, please consider citing it. We put significant effort into building and maintaining this free and open-source R package. Find the citation below. ```{r} citation("mctq") @@ -145,15 +144,13 @@ citation("mctq") ## Contributing -We welcome contributions, including bug reports. - -Take a moment to review our [Guidelines for Contributing](https://docs.ropensci.org/mctq/CONTRIBUTING.html). +We welcome contributions, including bug reports. Take a moment to review our [Guidelines for Contributing](https://docs.ropensci.org/mctq/CONTRIBUTING.html). ## Acknowledgments -The initial development of `mctq` was supported by a scholarship provided by the [University of Sao Paulo (USP)](http://usp.br/) (❤️). +The initial development of `mctq` was supported by a scholarship from the [University of Sao Paulo (USP)](http://usp.br/) (❤️). -`mctq` hex logo was based on an illustration created by [hilda design matters Zurich](https://hilda.ch/) for the [Daylight Academy (DLA)](https://daylight.academy/). +The `mctq` hex logo is based on an illustration by [hilda design matters Zurich](https://hilda.ch/) for the [Daylight Academy (DLA)](https://daylight.academy/).
diff --git a/README.md b/README.md index 9176a3e..76b4a23 100644 --- a/README.md +++ b/README.md @@ -7,15 +7,15 @@ [![Status at rOpenSci Software Peer Review](https://badges.ropensci.org/434_status.svg)](https://github.com/ropensci/software-review/issues/434) +[![Repo +status](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) [![CRAN status](https://www.r-pkg.org/badges/version/mctq)](https://cran.r-project.org/package=mctq) [![CRAN +DOI](http://img.shields.io/badge/DOI-10.32614/CRAN.package.mctq-1284C5.svg)](https://doi.org/10.32614/CRAN.package.mctq) +[![CRAN downloads](https://cranlogs.r-pkg.org/badges/grand-total/mctq)](https://cran.r-project.org/package=mctq) -[![mctq status -badge](https://ropensci.r-universe.dev/badges/mctq)](https://ropensci.r-universe.dev) -[![Project Status: Active – The project has reached a stable, usable -state and is being actively -developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) +[![R-universe](https://ropensci.r-universe.dev/badges/mctq)](https://ropensci.r-universe.dev) [![Lifecycle: maturing](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://lifecycle.r-lib.org/articles/stages.html#maturing) [![R-CMD-check](https://github.com/ropensci/mctq/workflows/R-CMD-check/badge.svg)](https://github.com/ropensci/mctq/actions) @@ -32,11 +32,11 @@ Practices](https://bestpractices.coreinfrastructure.org/projects/6244/badge)](ht `mctq` is an R package that provides a complete toolkit to process the Munich ChronoType Questionnaire (MCTQ), a quantitative and validated -tool to assess chronotypes using peoples’ sleep behavior presented by -Till Roenneberg, Anna Wirz-Justice, and Martha Merrow in +tool to assess chronotypes using individuals’ sleep behavior, as +presented by Till Roenneberg, Anna Wirz-Justice, and Martha Merrow in [2003](https://doi.org/10.1177/0748730402239679). Its aim is to facilitate the work of sleep and chronobiology scientists with MCTQ data -and to improve reproducibility in research. +and improve reproducibility in research. `mctq` adheres to the [tidyverse principles](https://tidyverse.tidyverse.org/articles/manifesto.html) and @@ -45,46 +45,43 @@ integrates with the [tidyverse ecosystem](https://www.tidyverse.org/). Learn more about the MCTQ questionnaire at . -### Wait, an R package for a questionnaire? - -Although it may look like a simple questionnaire, MCTQ requires a lot of -date/time manipulation. This poses a challenge for many scientists, -being that most people have difficulties with date/time data, especially -when dealing with an extensive dataset. The `mctq` package comes to -address this issue. +### Why an R package for a questionnaire? -`mctq` can handle the processing tasks for the three MCTQ versions -(standard, micro, and shift) with few dependencies, relying much of its -applications on the [lubridate](https://lubridate.tidyverse.org/) and +Although it may seem like a simple questionnaire, MCTQ requires +extensive date/time manipulation, which poses challenges for many +scientists. The `mctq` package addresses this issue by providing tools +to handle the processing tasks for the three MCTQ versions (standard, +micro, and shift) with few dependencies, relying mainly on the +[lubridate](https://lubridate.tidyverse.org/) and [hms](https://hms.tidyverse.org/) packages from -[tidyverse](https://www.tidyverse.org/). We also designed `mctq` with -the user experience in mind, by creating an interface that resembles the -way the questionnaire data is shown in MCTQ publications, and by -providing extensive and detailed documentation about each computation -proposed by the MCTQ authors. The package also includes fictional -datasets for testing and learning purposes. +[tidyverse](https://www.tidyverse.org/). + +We designed `mctq` with user experience in mind, creating an interface +that resembles the questionnaire data as shown in MCTQ publications and +providing extensive documentation about each computation proposed by the +MCTQ authors. The package also includes fictional datasets for testing +and learning purposes. ## Prerequisites -You need to have some familiarity with the [R programming -language](https://www.r-project.org/) and with the +You need some familiarity with the [R programming +language](https://www.r-project.org/) and the [lubridate](https://lubridate.tidyverse.org/) and [hms](https://hms.tidyverse.org/) packages from -[tidyverse](https://www.tidyverse.org/) to use `mctq` main functions. +[tidyverse](https://www.tidyverse.org/) to use `mctq`’s main functions. -If you don’t feel comfortable with R, we strongly recommend checking -Hadley Wickham and Garrett Grolemund’s free and online book [R for Data -Science](https://r4ds.had.co.nz/) and the Coursera course from John -Hopkins University [Data Science: Foundations using +If you are new to R, we recommend Hadley Wickham and Garrett Grolemund’s +free online book [R for Data Science](https://r4ds.hadley.nz/) and the +Coursera course from Johns Hopkins University [Data Science: Foundations +using R](https://www.coursera.org/specializations/data-science-foundations-r) (free for audit students). Please refer to the [lubridate](https://lubridate.tidyverse.org/) and -[hms](https://hms.tidyverse.org/) package documentation to learn more -about them. These two are essential packages to deal with date/time data -in R. We also recommend that you read the [Dates and -times](https://r4ds.had.co.nz/dates-and-times.html) chapter from Wickham -& Grolemund’s book [R for Data Science](https://r4ds.had.co.nz/). +[hms](https://hms.tidyverse.org/) documentation to learn more about +handling date/time data in R. We also recommend reading the [Dates and +times](https://r4ds.hadley.nz/datetimes) chapter from Wickham & +Grolemund’s book [R for Data Science](https://r4ds.hadley.nz/). ## Installation @@ -104,30 +101,25 @@ remotes::install_github("ropensci/mctq") ## Usage -`mctq` makes use of the [lubridate](https://lubridate.tidyverse.org/) -and [hms](https://hms.tidyverse.org/) packages from -[tidyverse](https://www.tidyverse.org/), which provide special objects -to deal with date/time values in R. If your dataset does not conform to -this structure, you first need to convert your data to it. Please refer -to those package documentations to learn more about them. +`mctq` uses the [lubridate](https://lubridate.tidyverse.org/) and +[hms](https://hms.tidyverse.org/) packages, which provide special +objects to handle date/time values in R. Ensure your dataset conforms to +this structure before using `mctq`. Refer to the respective package +documentation for more details. -Due to the [circular nature of time](https://youtu.be/eelVqfm8vVc), we -strongly recommend that you use appropriate temporal objects while -dealing with date/time in R. This can help you get rid of several -computation mistakes while trying to adapt your data from a base 10 to a -system rooted in a base 12 numerical system. +Because of the [circular nature of time](https://youtu.be/eelVqfm8vVc), +using appropriate temporal objects is crucial to avoid computation +mistakes while adapting data from a base 10 to a base 12 numerical +system. -For a more detailed explanation of the `mctq` usage, go to our [Get -started guide](https://docs.ropensci.org/mctq/articles/mctq.html). +For detailed usage instructions, visit our [Get started +guide](https://docs.ropensci.org/mctq/articles/mctq.html). ### Workdays and work-free days variables -After your data is set to start, just use the `mctq` functions below to -process it. - -Note that the `mctq` functions uses a similar naming pattern to those -used in the MCTQ publications. This makes it easy to find and apply any -computation necessary. +After preparing your data, use the following `mctq` functions to process +it. The function names follow the patterns used in MCTQ publications, +making it easy to apply the necessary computations: - `fd()`: compute MCTQ work-free days. - `so()`: compute MCTQ local time of sleep onset. @@ -182,54 +174,52 @@ sjl_rel(msw, msf) ### Utilities -`mctq` is also equipped with some utility tools to help with your MCTQ -data. The package also provides fictional datasets of the standard, -micro, and shift MCTQ versions for testing and learning purposes. +`mctq` includes utility tools to help with your MCTQ data and provides +fictional datasets for the standard, micro, and shift MCTQ versions for +testing and learning purposes. -All functions are properly documented, showing all the guidelines behind -the computations. Click -[here](https://docs.ropensci.org/mctq/reference/index.html) to see a -list of them. +All functions are documented with guidelines behind the computations. +Click [here](https://docs.ropensci.org/mctq/reference/index.html) to see +the full list. ## Citation -If you use `mctq` in your research, please consider citing it. We put a -lot of work to build and maintain a free and open-source R package. You -can find the citation below. +If you use `mctq` in your research, please consider citing it. We put +significant effort into building and maintaining this free and +open-source R package. Find the citation below. ``` r citation("mctq") #> To cite {mctq} in publications use: #> -#> Vartanian, D. (2023). {mctq}: tools to process the Munich ChronoType -#> Questionnaire (MCTQ). R package version 0.3.2. +#> Vartanian, D. (2023). {mctq}: Munich ChronoType Questionnaire tools +#> (Version 0.3.2.9001) [Computer software - R package]. CRAN; rOpenSci. #> https://docs.ropensci.org/mctq/ #> -#> A BibTeX entry for LaTeX users is +#> Uma entrada BibTeX para usuários(as) de LaTeX é #> #> @Unpublished{, -#> title = {{mctq}: tools to process the Munich ChronoType Questionnaire (MCTQ)}, +#> title = {{mctq}: Munich ChronoType Questionnaire tools}, #> author = {Daniel Vartanian}, -#> year = {2023}, +#> year = {2024}, #> url = {https://docs.ropensci.org/mctq/}, -#> note = {R package version 0.3.2}, +#> note = {R package version 0.3.2.9001}, #> } ``` ## Contributing -We welcome contributions, including bug reports. - -Take a moment to review our [Guidelines for +We welcome contributions, including bug reports. Take a moment to review +our [Guidelines for Contributing](https://docs.ropensci.org/mctq/CONTRIBUTING.html). ## Acknowledgments -The initial development of `mctq` was supported by a scholarship -provided by the [University of Sao Paulo (USP)](http://usp.br/) (❤️). +The initial development of `mctq` was supported by a scholarship from +the [University of Sao Paulo (USP)](http://usp.br/) (❤️). -`mctq` hex logo was based on an illustration created by [hilda design -matters Zurich](https://hilda.ch/) for the [Daylight Academy +The `mctq` hex logo is based on an illustration by [hilda design matters +Zurich](https://hilda.ch/) for the [Daylight Academy (DLA)](https://daylight.academy/).
diff --git a/_pkgdown.yml b/_pkgdown.yml index a6f11d7..52b1628 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -19,8 +19,8 @@ navbar: reference: - title: MCTQ desc: > - A complete toolkit to process the Munich ChronoType Questionnaire (MCTQ) - for its three versions (standard, micro, and shift). + A complete toolkit for processing the Munich ChronoType Questionnaire + (MCTQ) in its three versions: standard, micro, and shift. contents: - fd - so @@ -49,7 +49,7 @@ reference: - title: Utilities desc: > - Other functions to help with MCTQ data manipulation. + Other functions to help with MCTQ data. contents: - pretty_mctq - random_mctq @@ -64,7 +64,6 @@ articles: - title: Notes navbar: ~ contents: - - time-span-objects - missing-sections - sjl-computation diff --git a/codemeta.json b/codemeta.json index c775a38..65cac4a 100644 --- a/codemeta.json +++ b/codemeta.json @@ -2,19 +2,19 @@ "@context": "https://doi.org/10.5063/schema/codemeta-2.0", "@type": "SoftwareSourceCode", "identifier": "mctq", - "description": "A complete toolkit to process the Munich ChronoType Questionnaire (MCTQ) for its three versions (standard, micro, and shift). MCTQ is a quantitative and validated tool to assess chronotypes using peoples' sleep behavior, originally presented by Till Roenneberg, Anna Wirz-Justice, and Martha Merrow (2003, ).", - "name": "mctq: Tools to Process the Munich ChronoType Questionnaire (MCTQ)", + "description": "A complete toolkit for processing the Munich ChronoType Questionnaire (MCTQ) in its three versions: standard, micro, and shift. The MCTQ is a quantitative and validated tool used to assess chronotypes based on individuals' sleep behavior. It was originally presented by Till Roenneberg, Anna Wirz-Justice, and Martha Merrow in 2003 (2003, ).", + "name": "mctq: Munich ChronoType Questionnaire Tools", "relatedLink": ["https://docs.ropensci.org/mctq/", "https://CRAN.R-project.org/package=mctq"], "codeRepository": "https://github.com/ropensci/mctq/", "issueTracker": "https://github.com/ropensci/mctq/issues/", "license": "https://spdx.org/licenses/MIT", - "version": "0.3.2.9000", + "version": "0.3.2.9001", "programmingLanguage": { "@type": "ComputerLanguage", "name": "R", "url": "https://r-project.org" }, - "runtimePlatform": "R version 4.3.0 (2023-04-21 ucrt)", + "runtimePlatform": "R version 4.4.1 (2024-06-14 ucrt)", "provider": { "@id": "https://cran.r-project.org", "@type": "Organization", @@ -278,11 +278,11 @@ }, "SystemRequirements": null }, - "fileSize": "633.813KB", + "fileSize": "628.069KB", "citation": [ { "@type": "CreativeWork", - "datePublished": "2023", + "datePublished": "2024", "author": [ { "@type": "Person", @@ -292,9 +292,9 @@ "@id": "https://orcid.org/0000-0001-7782-759X" } ], - "name": "{mctq}: tools to process the Munich ChronoType Questionnaire (MCTQ)", + "name": "{mctq}: Munich ChronoType Questionnaire tools", "url": "https://docs.ropensci.org/mctq/", - "description": "R package version 0.3.2.9000" + "description": "R package version 0.3.2.9001" } ], "releaseNotes": "https://github.com/ropensci/mctq/blob/master/NEWS.md", diff --git a/data-raw/micro_mctq.R b/data-raw/micro_mctq.R index b921eb3..484d670 100644 --- a/data-raw/micro_mctq.R +++ b/data-raw/micro_mctq.R @@ -5,7 +5,7 @@ # library(checkmate) # library(dplyr) -# library(gutils) # https://github.com/giperbio/gutils +# library(rutils) # https://github.com/danielvartan/rutils # library(hms) # library(lubridate) # library(mctq) @@ -529,13 +529,13 @@ validate_micro_mctq <- function(write = FALSE) { dplyr::across( -.data$id, .fns = ~ dplyr::if_else( - .data$id %in% invalid, gutils:::na_as(.x), .x + .data$id %in% invalid, rutils:::na_as(.x), .x ) ), dplyr::across( -c(id:shift_work), .fns = ~ dplyr::if_else( - shift_work, gutils:::na_as(.x), .x + shift_work, rutils:::na_as(.x), .x ) ) ) |> diff --git a/data-raw/shift_mctq.R b/data-raw/shift_mctq.R index 8d570e4..2b124f5 100644 --- a/data-raw/shift_mctq.R +++ b/data-raw/shift_mctq.R @@ -5,7 +5,7 @@ # library(checkmate) # library(dplyr) -# library(gutils) # https://github.com/giperbio/gutils +# library(rutils) # https://github.com/danielvartan/rutils # library(hms) # library(lubridate) # library(mctq) @@ -1381,7 +1381,7 @@ validate_shift_mctq <- function(write = FALSE) { dplyr::mutate( dplyr::across( dplyr::ends_with(i), - ~ dplyr::if_else(dummy, gutils:::na_as(.x), .x) + ~ dplyr::if_else(dummy, rutils:::na_as(.x), .x) ) ) |> dplyr::select(-dummy) @@ -1400,7 +1400,7 @@ validate_shift_mctq <- function(write = FALSE) { dplyr::mutate( dplyr::across( -.data$id, - .fns = ~ dplyr::if_else(.data$id %in% invalid, gutils:::na_as(.x), .x) + .fns = ~ dplyr::if_else(.data$id %in% invalid, rutils:::na_as(.x), .x) ) ) |> dplyr::ungroup() diff --git a/data-raw/std_mctq.R b/data-raw/std_mctq.R index 0f9aacf..7c1bfd2 100644 --- a/data-raw/std_mctq.R +++ b/data-raw/std_mctq.R @@ -6,7 +6,7 @@ # library(checkmate) # library(cli) # library(dplyr) -# library(gutils) # https://github.com/giperbio/gutils +# library(rutils) # https://github.com/danielvartan/rutils # library(hms) # library(lubridate) # library(mctq) @@ -890,7 +890,7 @@ validate_std_mctq <- function(write = FALSE) { dplyr::bind_cols(test) |> dplyr::mutate(dplyr::across( dplyr::ends_with(i), - ~ dplyr::if_else(dummy, gutils:::na_as(.x), .x) + ~ dplyr::if_else(dummy, rutils:::na_as(.x), .x) )) |> dplyr::select(-dummy) } @@ -907,7 +907,7 @@ validate_std_mctq <- function(write = FALSE) { dplyr::mutate(dplyr::across( -.data$id, .fns = ~ dplyr::if_else( - .data$id %in% invalid, gutils:::na_as(.x), .x + .data$id %in% invalid, rutils:::na_as(.x), .x ) ) ) |> diff --git a/inst/CITATION b/inst/CITATION index 45b97bd..f0dff50 100644 --- a/inst/CITATION +++ b/inst/CITATION @@ -3,7 +3,7 @@ utils::bibentry( bibtype = "Unpublished", title = paste0( "{mctq}:", " ", - "tools to process the Munich ChronoType Questionnaire (MCTQ)" + "Munich ChronoType Questionnaire tools" ), author = c( utils::person( @@ -14,18 +14,18 @@ utils::bibentry( comment = c(ORCID = "0000-0001-7782-759X") ) ), - year = "2023", + year = "2024", url = paste0( "https://docs.ropensci.org/", "mctq/" ), - note = "R package version 0.3.2.9000", + note = "R package version 0.3.2.9001", textVersion = paste0( "Vartanian, D.", " ", "(2023)", ". ", "{mctq}:", " ", - "tools to process the Munich ChronoType Questionnaire (MCTQ)", " ", - "(Version 0.3.2.9000) [Computer software - R package]", ". ", + "Munich ChronoType Questionnaire tools", " ", + "(Version 0.3.2.9001) [Computer software - R package]", ". ", "CRAN; rOpenSci", ". ", "https://docs.ropensci.org/", "mctq/" diff --git a/inst/WORDLIST b/inst/WORDLIST index 06e016e..a3d42a0 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -9,6 +9,7 @@ Codecov Costa Coursera DLA +DOI Enzymology Frighetto GIPSO @@ -35,6 +36,7 @@ OpenSSF Paulo Pilz RStudio +Repo Roenneberg SJL Salamanca @@ -59,11 +61,11 @@ eu funder hilda hms +individuals’ jetlag jetlags lubridate midsleep -peoples’ prerelease rOpenSci readr @@ -77,4 +79,5 @@ sjl theWeP tidyverse vectorized +’s ️ diff --git a/man/fd.Rd b/man/fd.Rd index 3057674..439a80d 100644 --- a/man/fd.Rd +++ b/man/fd.Rd @@ -104,9 +104,9 @@ Other MCTQ functions: \code{\link{sd_overall}()}, \code{\link{sd_week}()}, \code{\link{sdu}()}, +\code{\link{sjl}()}, \code{\link{sjl_sc}()}, \code{\link{sjl_weighted}()}, -\code{\link{sjl}()}, \code{\link{so}()}, \code{\link{tbt}()} } diff --git a/man/gu.Rd b/man/gu.Rd index d53fa07..f9e5b79 100644 --- a/man/gu.Rd +++ b/man/gu.Rd @@ -163,9 +163,9 @@ Other MCTQ functions: \code{\link{sd_overall}()}, \code{\link{sd_week}()}, \code{\link{sdu}()}, +\code{\link{sjl}()}, \code{\link{sjl_sc}()}, \code{\link{sjl_weighted}()}, -\code{\link{sjl}()}, \code{\link{so}()}, \code{\link{tbt}()} } diff --git a/man/le_week.Rd b/man/le_week.Rd index 7bac420..983e944 100644 --- a/man/le_week.Rd +++ b/man/le_week.Rd @@ -193,9 +193,9 @@ Other MCTQ functions: \code{\link{sd_overall}()}, \code{\link{sd_week}()}, \code{\link{sdu}()}, +\code{\link{sjl}()}, \code{\link{sjl_sc}()}, \code{\link{sjl_weighted}()}, -\code{\link{sjl}()}, \code{\link{so}()}, \code{\link{tbt}()} } diff --git a/man/mctq-package.Rd b/man/mctq-package.Rd index 80a5241..c54939f 100644 --- a/man/mctq-package.Rd +++ b/man/mctq-package.Rd @@ -4,11 +4,11 @@ \name{mctq-package} \alias{mctq} \alias{mctq-package} -\title{mctq: Tools to Process the Munich ChronoType Questionnaire (MCTQ)} +\title{mctq: Munich ChronoType Questionnaire Tools} \description{ \if{html}{\figure{logo.png}{options: style='float: right' alt='logo' width='120'}} -A complete toolkit to process the Munich ChronoType Questionnaire (MCTQ) for its three versions (standard, micro, and shift). MCTQ is a quantitative and validated tool to assess chronotypes using peoples' sleep behavior, originally presented by Till Roenneberg, Anna Wirz-Justice, and Martha Merrow (2003, \doi{10.1177/0748730402239679}). +A complete toolkit for processing the Munich ChronoType Questionnaire (MCTQ) in its three versions: standard, micro, and shift. The MCTQ is a quantitative and validated tool used to assess chronotypes based on individuals' sleep behavior. It was originally presented by Till Roenneberg, Anna Wirz-Justice, and Martha Merrow in 2003 (2003, \doi{10.1177/0748730402239679}). } \seealso{ Useful links: diff --git a/man/msf_sc.Rd b/man/msf_sc.Rd index 1b07576..833bc21 100644 --- a/man/msf_sc.Rd +++ b/man/msf_sc.Rd @@ -293,9 +293,9 @@ Other MCTQ functions: \code{\link{sd_overall}()}, \code{\link{sd_week}()}, \code{\link{sdu}()}, +\code{\link{sjl}()}, \code{\link{sjl_sc}()}, \code{\link{sjl_weighted}()}, -\code{\link{sjl}()}, \code{\link{so}()}, \code{\link{tbt}()} } diff --git a/man/msl.Rd b/man/msl.Rd index 3cd9f2e..c6a5e46 100644 --- a/man/msl.Rd +++ b/man/msl.Rd @@ -180,9 +180,9 @@ Other MCTQ functions: \code{\link{sd_overall}()}, \code{\link{sd_week}()}, \code{\link{sdu}()}, +\code{\link{sjl}()}, \code{\link{sjl_sc}()}, \code{\link{sjl_weighted}()}, -\code{\link{sjl}()}, \code{\link{so}()}, \code{\link{tbt}()} } diff --git a/man/napd.Rd b/man/napd.Rd index 22fd5ab..589ceff 100644 --- a/man/napd.Rd +++ b/man/napd.Rd @@ -151,9 +151,9 @@ Other MCTQ functions: \code{\link{sd_overall}()}, \code{\link{sd_week}()}, \code{\link{sdu}()}, +\code{\link{sjl}()}, \code{\link{sjl_sc}()}, \code{\link{sjl_weighted}()}, -\code{\link{sjl}()}, \code{\link{so}()}, \code{\link{tbt}()} } diff --git a/man/sd24.Rd b/man/sd24.Rd index adb0203..ba9950c 100644 --- a/man/sd24.Rd +++ b/man/sd24.Rd @@ -171,9 +171,9 @@ Other MCTQ functions: \code{\link{sd_overall}()}, \code{\link{sd_week}()}, \code{\link{sdu}()}, +\code{\link{sjl}()}, \code{\link{sjl_sc}()}, \code{\link{sjl_weighted}()}, -\code{\link{sjl}()}, \code{\link{so}()}, \code{\link{tbt}()} } diff --git a/man/sd_overall.Rd b/man/sd_overall.Rd index 167662b..ae09fd3 100644 --- a/man/sd_overall.Rd +++ b/man/sd_overall.Rd @@ -215,9 +215,9 @@ Other MCTQ functions: \code{\link{sd24}()}, \code{\link{sd_week}()}, \code{\link{sdu}()}, +\code{\link{sjl}()}, \code{\link{sjl_sc}()}, \code{\link{sjl_weighted}()}, -\code{\link{sjl}()}, \code{\link{so}()}, \code{\link{tbt}()} } diff --git a/man/sd_week.Rd b/man/sd_week.Rd index 28afd5a..abf2ace 100644 --- a/man/sd_week.Rd +++ b/man/sd_week.Rd @@ -195,9 +195,9 @@ Other MCTQ functions: \code{\link{sd24}()}, \code{\link{sd_overall}()}, \code{\link{sdu}()}, +\code{\link{sjl}()}, \code{\link{sjl_sc}()}, \code{\link{sjl_weighted}()}, -\code{\link{sjl}()}, \code{\link{so}()}, \code{\link{tbt}()} } diff --git a/man/sdu.Rd b/man/sdu.Rd index 96509de..f3a508f 100644 --- a/man/sdu.Rd +++ b/man/sdu.Rd @@ -173,9 +173,9 @@ Other MCTQ functions: \code{\link{sd24}()}, \code{\link{sd_overall}()}, \code{\link{sd_week}()}, +\code{\link{sjl}()}, \code{\link{sjl_sc}()}, \code{\link{sjl_weighted}()}, -\code{\link{sjl}()}, \code{\link{so}()}, \code{\link{tbt}()} } diff --git a/man/sjl_sc.Rd b/man/sjl_sc.Rd index 5738b43..4bb01de 100644 --- a/man/sjl_sc.Rd +++ b/man/sjl_sc.Rd @@ -298,8 +298,8 @@ Other MCTQ functions: \code{\link{sd_overall}()}, \code{\link{sd_week}()}, \code{\link{sdu}()}, -\code{\link{sjl_weighted}()}, \code{\link{sjl}()}, +\code{\link{sjl_weighted}()}, \code{\link{so}()}, \code{\link{tbt}()} } diff --git a/man/sjl_weighted.Rd b/man/sjl_weighted.Rd index 90c79c5..2872def 100644 --- a/man/sjl_weighted.Rd +++ b/man/sjl_weighted.Rd @@ -210,8 +210,8 @@ Other MCTQ functions: \code{\link{sd_overall}()}, \code{\link{sd_week}()}, \code{\link{sdu}()}, -\code{\link{sjl_sc}()}, \code{\link{sjl}()}, +\code{\link{sjl_sc}()}, \code{\link{so}()}, \code{\link{tbt}()} } diff --git a/man/so.Rd b/man/so.Rd index 4f2ffbc..e1f2545 100644 --- a/man/so.Rd +++ b/man/so.Rd @@ -173,9 +173,9 @@ Other MCTQ functions: \code{\link{sd_overall}()}, \code{\link{sd_week}()}, \code{\link{sdu}()}, +\code{\link{sjl}()}, \code{\link{sjl_sc}()}, \code{\link{sjl_weighted}()}, -\code{\link{sjl}()}, \code{\link{tbt}()} } \concept{MCTQ functions} diff --git a/man/tbt.Rd b/man/tbt.Rd index 66b7218..ffb57db 100644 --- a/man/tbt.Rd +++ b/man/tbt.Rd @@ -168,9 +168,9 @@ Other MCTQ functions: \code{\link{sd_overall}()}, \code{\link{sd_week}()}, \code{\link{sdu}()}, +\code{\link{sjl}()}, \code{\link{sjl_sc}()}, \code{\link{sjl_weighted}()}, -\code{\link{sjl}()}, \code{\link{so}()} } \concept{MCTQ functions} diff --git a/vignettes/mctq.Rmd b/vignettes/mctq.Rmd index 6c151e5..361091a 100644 --- a/vignettes/mctq.Rmd +++ b/vignettes/mctq.Rmd @@ -23,7 +23,7 @@ The same features presented here can also be used with $\mu$MCTQ. To make it eas We assume that you already have [R](https://www.r-project.org/) installed and have some familiarity with R and MCTQ data. We also strongly recommend using [RStudio](https://posit.co/products/open-source/rstudio/) as your IDE (Integrated Development Environment). -It's a good idea to have the standard MCTQ questionnaire open while reading this introduction. That way you can have a better understanding of the data objects we are going to deal with. You can download a copy of the MCTQ full standard version [here](https://www.thewep.org/documentations/mctq/item/english-mctq-full). +It's helpful to have the standard MCTQ questionnaire and the guidelines for standard MCTQ variable computation open while reading this article. This will enhance your understanding of the data objects discussed. You can download the MCTQ full standard version [here](https://www.thewep.org/documentations/mctq/item/english-mctq-full). ## First things first diff --git a/vignettes/missing-sections.Rmd b/vignettes/missing-sections.Rmd index 1f12da7..04dffae 100644 --- a/vignettes/missing-sections.Rmd +++ b/vignettes/missing-sections.Rmd @@ -1,5 +1,5 @@ --- -title: "Missing sections" +title: "Dealing with missing sections" output: rmarkdown::html_vignette description: > This article shows a possible workaround to deal with missing sections when @@ -19,7 +19,7 @@ knitr::opts_chunk$set( This article shows a possible workaround to a common problem encountered when dealing with a __standard__ Munich ChronoType Questionnaire (MCTQ) and __$\mu$MCTQ__ data. -It's a good idea to have the standard MCTQ questionnaire and the guidelines for the standard MCTQ variable computation open while reading this article/vignette. That way you can have a better understanding of the data objects we are going to deal with. You can download a copy of the MCTQ full standard version [here](https://www.thewep.org/documentations/mctq/item/english-mctq-full). Click [here](https://www.thewep.org/documentations/mctq/item/mctq-variables) to download a copy of the guidelines for the standard MCTQ variables. +It's helpful to have the standard MCTQ questionnaire and the guidelines for standard MCTQ variable computation open while reading this article. This will enhance your understanding of the data objects discussed. You can download the MCTQ full standard version [here](https://www.thewep.org/documentations/mctq/item/english-mctq-full) and the guidelines for standard MCTQ variables [here](https://www.thewep.org/documentations/mctq/item/mctq-variables). ## Working around missing sections diff --git a/vignettes/sjl-computation.Rmd b/vignettes/sjl-computation.Rmd index 9ec9157..fc081a1 100644 --- a/vignettes/sjl-computation.Rmd +++ b/vignettes/sjl-computation.Rmd @@ -1,11 +1,11 @@ --- -title: "Social jetlag computation" +title: "The social jetlag computation" output: rmarkdown::html_vignette description: > - This article shows some notes about different approaches that can be used to - compute the social jetlag for the Munich ChronoType Questionnaire (MCTQ). It - also explains how the 'method' argument from the 'sjl_rel()', 'sjl()', - 'sjl_sc_rel()', and 'sjl_sc()' functions works. + This article provides notes on different approaches to computing social jetlag + for the Munich ChronoType Questionnaire (MCTQ). It also explains how the + 'method' argument in the 'sjl_rel()', 'sjl()', 'sjl_sc_rel()', and 'sjl_sc()' + functions works. vignette: > %\VignetteIndexEntry{Social jetlag computation} %\VignetteEngine{knitr::rmarkdown} @@ -19,20 +19,23 @@ knitr::opts_chunk$set( ) ``` -This article shows some notes about different approaches that can be used to compute the social jetlag ($SJL$) for the Munich ChronoType Questionnaire (MCTQ). It also explains how the `method` argument from the `sjl_rel()`, `sjl()`, `sjl_sc_rel()`, and `sjl_sc()` functions work. +This article provides notes on different approaches to computing social jetlag ($SJL$) for the Munich ChronoType Questionnaire (MCTQ). It also explains how the `method` argument in the `sjl_rel()`, `sjl()`, `sjl_sc_rel()`, and `sjl_sc()` functions works. -It's a good idea to have the standard MCTQ questionnaire and the guidelines for the standard MCTQ variable computation open while reading this article/vignette. That way you can have a better understanding of the data objects we are going to deal with. You can download a copy of the MCTQ full standard version [here](https://www.thewep.org/documentations/mctq/item/english-mctq-full). Click [here](https://www.thewep.org/documentations/mctq/item/mctq-variables) to download a copy of the guidelines for the standard MCTQ variables. +It's helpful to have the standard MCTQ questionnaire and the guidelines for standard MCTQ variable computation open while reading this article. This will enhance your understanding of the data objects discussed. You can download the MCTQ full standard version [here](https://www.thewep.org/documentations/mctq/item/english-mctq-full) and the guidelines for standard MCTQ variables [here](https://www.thewep.org/documentations/mctq/item/mctq-variables). ## The two intervals problem -According to Roenneberg et al. ([2012](https://doi.org/10.1016/j.cub.2012.03.038)) supplemental materials, the relative social jetlag ($SJL_{ rel}$), i.e., the discrepancy between social and biological time, must be computed as the difference between $MSF$ (local time of mid-sleep on work-free days) and $MSW$ (local time of mid-sleep on workdays). +According to Roenneberg et al. ([2012](https://doi.org/10.1016/j.cub.2012.03.038)), the relative social jetlag ($SJL_{ rel}$), i.e., the discrepancy between social and biological time, must be computed as the difference between $MSF$ (local time of mid-sleep on work-free days) and $MSW$ (local time of mid-sleep on workdays). $$SJL_{rel} = MSF - MSW$$ -This simple equation may seem trivial until you take into account that you're are dealing with two time values detached from a timeline. In other words, $MSW$ and $MSF$ represent two moments in two different contexts (one on workdays and the other on work-free days). +This simple equation seems trivial until you consider that it deals with two time values detached from a timeline. In other words, $MSW$ and $MSF$ represent two moments in different contexts (workdays and work-free days). If you dive into the MCTQ articles, you can see that this computation have two objectives: +1. Represent the distance between $MSW$ and $MSF$ (i.e., the discrepancy). +2. Establish what value comes before or after the other, representing that with a $+/-$ signal. That is, when $MSW$ comes before $MSF$, $SJL_{rel}$ must be positive, and when $MSW$ comes after $MSF$, $SJL_{rel}$ must be negative. + 1. To represent the distance between $MSW$ and $MSF$ (i.e., the discrepancy). 2. To establish what value comes before or after the other, representing that with a $+/-$ signal. That is, when $MSW$ comes before $MSF$, $SJL_{rel}$ must be positive, and when $MSW$ comes after $MSF$, $SJL_{rel}$ must be negative. diff --git a/vignettes/time-span-objects.Rmd b/vignettes/time-span-objects.Rmd deleted file mode 100644 index 0a3ca97..0000000 --- a/vignettes/time-span-objects.Rmd +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: "Why Duration and not Period?" -output: rmarkdown::html_vignette -description: > - This article explains why the {mctq} package use `Duration` instead - of `Period` (objects from the {lubridate} package) as the default object - for time spans. -vignette: > - %\VignetteIndexEntry{Why Duration and not Period?} - %\VignetteEngine{knitr::rmarkdown} - %\VignetteEncoding{UTF-8} ---- - -```{r, include = FALSE} -knitr::opts_chunk$set( - collapse = TRUE, - comment = "#>" -) -``` - -This article explains why the `mctq` package uses `Duration` instead of `Period` (objects from the [lubridate](https://lubridate.tidyverse.org/) package) as the default object for time spans. - -## `Duration` versus `Period` objects - -The [`lubridate`](https://lubridate.tidyverse.org/) package offers three types of objects for storing and manipulating time spans: [`Duration`](https://lubridate.tidyverse.org/reference/duration.html), [`Period`](https://lubridate.tidyverse.org/reference/period.html), and [`Interval`](https://lubridate.tidyverse.org/reference/interval.html). - -To understand the difference between `Duration` and `Period` objects you must first remember that the timeline is not always consistent, as it can have irregularities caused by, for example, leap years, DST (Daylight Saving Time), or leap seconds. That's when `Period` objects differ from `Duration` objects. - -[`Duration`](https://lubridate.tidyverse.org/reference/duration.html) objects represent time spans by their exact number of seconds. That is, a `Duration` object of 1 hour will always represent a 1-hour time span, even with possible timeline irregularities. - -```{r echo = TRUE} -start <- lubridate::ymd_hms("2020-01-01 10:00:00", tz = "America/New_York") - -start + lubridate::duration(1, units = "hour") - -``` - -[`Period`](https://lubridate.tidyverse.org/reference/period.html) objects work a little bit differently. They are a special type of object developed by the `lubridate` team that represents _human units_, ignoring possible timeline irregularities. That is to say that 1 day as `Period` can have different time spans when looking to a timeline after an irregular event. - -To illustrate this behavior, take the case of a DST event, starting at 2016-03-13 01:00:00 EST. - - -```{r echo = TRUE} -start <- lubridate::ymd_hms("2016-03-13 01:00:00", tz = "America/New_York") - -start + lubridate::duration(1, units = "hour") -start + lubridate::period(1, units = "hour") -``` - -You might ask: why the result is `NA` when adding 1 hour as a `Period` object? That's because `Period` objects ignore time irregularities. When the DST starts at `01:00:00` the timeline "jumps" to `03:00:00`, so the period from `02:00:00` to `02:59:59` does not exist. - -``` -base: 2016-03-13 01:00:00, tz = "America/New_York" - - DST + 1 hour ------|---------------| |---------------|-----> - 01:00 NA 03:00 04:00 - -From the `Duration` perspective: base + 1 hour = 2016-03-13 03:00:00 - - |-------------------------------|---------------| - 1 hour 1 hour - -From the `Period` perspective: base + 1 hour = NA - - |---------------|---------------|---------------| - 1 hour 1 hour 1 hour -``` - -`Period` objects are useful when you need to consider the human units of time. For example: - -```{r echo = TRUE} -start <- lubridate::ymd_hms("2016-03-13 01:00:00", tz = "America/New_York") - -start + lubridate::duration(1, units = "day") -start + lubridate::period(1, units = "day") -``` - -In this case, `1 day`, by human standards, represents the same `time of day` on the next day. But, considering the DST event, that `1 day` has a time span of 23 hours. - -You can learn more about [`lubridate`](https://lubridate.tidyverse.org/) time span objects in the [Dates and times](https://r4ds.had.co.nz/dates-and-times.html#time-spans) chapter from Wickham & Grolemund's book "R for Data Science". - -## The MCTQ context - -At first glance you might think that, since MCTQ was made for human respondents, the best representation for time spans would be the one that better represents _human units_, right? That would be fine if we were talking about a time span in a timeline irregularity context, but MCTQ does not deal with this scenario. - -When using MCTQ, the interest is to measure the exact time span between one local time to another. By ignoring irregularities in the timeline, `Periods` produce a fluctuating time span, hence `Period` objects are not compatible with other time span like objects (e.g., `hms`). - -```{r echo = TRUE, eval = FALSE} -hms::parse_hm("10:00") + lubridate::period(1, units = "hours") - -#> Error: Incompatible classes: + -``` - -In summary, `Period` objects were made considering a very specific context that does not apply to MCTQ. That's why `Duration` objects are the default object for time spans.