Added tests to the new functions

NAMESPACE

@@ -7,6 +7,7 @@ export(Brown2reference)
 export(Datetime_breaks)
 export(Datetime_limits)
 export(aggregate_Datetime)
+export(count.difftime)
 export(create_Time.data)
 export(cut_Datetime)
 export(data2reference)

NEWS.md

@@ -1,8 +1,10 @@
 # LightLogR 0.2.1.9000
 
+* Exports the up to now internal function `count.difftime()` that is the basis for `dominant_epoch()`. But whereas the latter gets only the most common epoch, `count.difftime()` returns a table with the counts of all epochs. This is useful in conjunction with `gap_finder()`, to check the distribution of data intervals.
+
 * Added the `gg_days()` function to visualize multiple days of data in a single plot. Alongside come two helper functions, `Datetime_limits()` and `Datetime_breaks()`, to set the limits and breaks of the x-axis. 
 
-* Added the `filter_Datetime_multiple()` function to filter for multiple Datetime ranges depending on certain conditions, e.g. different filter cutoffs for different participants.
+* Added the `filter_Datetime_multiple()` function to filter for multiple Datetime ranges depending on certain conditions, e.g. different filter cutoffs for different participants. It wraps around `filter_Datetime()` or `filter_Date()`.
 
 * Reworked the internals of the light logger data import functions. They now use a more straightforward function factory approach. For users the only visible change it that device specific functions now have the form `import$device()` instead of the old `import.device()`.
 

R/aaa.r

@@ -1,4 +1,4 @@
-Time <- mEDI <- Time.data <- Datetime <- timestamp <- tz <- Day.data <- `DATE/TIME` <- n <- Datetime.rounded <- id <- sleep.colname.string <- file.name <- Interval <- original.datapoints.fleeting <- MEDI <- State.Brown <- Reference <- Reference.check <- Id <- Start.date.shift <- data <- Shift <- `MELANOPIC EDI` <- State <- group <- End <- Start <- Quant.x <- Quant.y <- is.implicit <- group.indices <- Id2 <- gap.id <- start <- end <- path <- auto.id <- n_max <- manual.id <- NULL
+Time <- mEDI <- Time.data <- Datetime <- timestamp <- tz <- Day.data <- `DATE/TIME` <- n <- Datetime.rounded <- id <- sleep.colname.string <- file.name <- Interval <- original.datapoints.fleeting <- MEDI <- State.Brown <- Reference <- Reference.check <- Id <- Start.date.shift <- data <- Shift <- `MELANOPIC EDI` <- State <- group <- End <- Start <- Quant.x <- Quant.y <- is.implicit <- group.indices <- Id2 <- gap.id <- start <- end <- path <- auto.id <- n_max <- manual.id <- silent <-  NULL
 
 empty_function <- function() {
   rsconnect::accountInfo()

R/gg_day.r

@@ -1,9 +1,9 @@
 
 #' Create a simple Time-of-Day plot of light logger data, faceted by Date
 #'
-#' [gg_day()] will create a simple ggplot for every data in a dataset. The result
-#' can further be manipulated like any ggplot. This will be sensible to refine
-#' styling or guides.
+#' [gg_day()] will create a simple ggplot for every data in a dataset. The
+#' result can further be manipulated like any ggplot. This will be sensible to
+#' refine styling or guides.
 #'
 #' Besides plotting, the function creates two new variables from the given
 #' `Datetime`:
@@ -35,20 +35,20 @@
 #' @param start.date,end.date Choose an optional start or end date within your
 #'   `dataset`. Expects a `date`, which can also be a `character` that is
 #'   interpretable as a date, e.g., `"2023-06-03"`. If you need a Datetime or
-#'   want to cut specific times of each day, use the [filter_Datetime()] function.
-#'   Defaults to `NULL`, which means that the plot starts/ends with the
-#'   earliest/latest date within the `dataset`.
+#'   want to cut specific times of each day, use the [filter_Datetime()]
+#'   function. Defaults to `NULL`, which means that the plot starts/ends with
+#'   the earliest/latest date within the `dataset`.
 #' @param scales For [ggplot2::facet_wrap()], should scales be "fixed", "free"
 #'   or free in one dimension ("free_y" is the default). Expects a `character`.
 #' @param y.scale How should the y-axis be scaled?
 #' * Defaults to `"symlog"`, which is a logarithmic scale that can also handle negative values.
 #' * `"log10"` would be a straight logarithmic scale, but cannot handle negative values.
 #' * `"identity"` does nothing (continuous scaling).
 #' * a transforming function, such as [symlog_trans()] or [scales::identity_trans()], which allow for more control.
-#' @param col optional column name that defines separate sets and colors them.
-#'   Expects anything that works with the layer data [ggplot2::aes()]. The
-#'   default color palette can be overwritten outside the function (see
-#'   examples).
+#' @param aes_col,aes_fill optional arguments that define separate sets and
+#'   colors or fills them. Expects anything that works with the layer data
+#'   [ggplot2::aes()]. The default color palette can be overwritten outside the
+#'   function (see examples).
 #' @param x.axis.breaks,y.axis.breaks Where should breaks occur on the x and
 #'   y.axis? Expects a `numeric vector` with all the breaks. If you want to
 #'   activate the default behaviour of [ggplot2], you need to put in
@@ -85,7 +85,7 @@
 #' x.axis = Datetime,
 #' y.axis = `MELANOPIC EDI`,
 #' y.axis.label = "mEDI (lx)",
-#' col = Source)
+#' aes_col = Source)
 #' plot
 #'
 #' #you can easily overwrite the color scale afterwards
@@ -99,7 +99,8 @@ gg_day <- function(dataset,
                    end.date = NULL,
                    x.axis = Datetime,
                    y.axis = MEDI,
-                   col = NULL,
+                   aes_col = NULL,
+                   aes_fill = NULL,
                    group = NULL,
                    geom = "point",
                    scales = "fixed",
@@ -149,7 +150,8 @@ gg_day <- function(dataset,
         ggplot2::geom_ribbon(
           ggplot2::aes(ymin = 0, ymax = !!y,
                        group = {{ group }},
-                       col = {{ col }}),
+                       col = {{ aes_col }},
+                       fill = {{ aes_fill }}),
           outline.type = "upper",
           ...
           )
@@ -209,7 +211,8 @@ gg_day <- function(dataset,
     eval(geom_function_expr)(
       ggplot2::aes(
         group = {{ group }},
-        col = {{ col }},
+        col = {{ aes_col }},
+        fill = {{ aes_fill }},
       ), ...) +
     ribbon +
     # Scales --------------------------------------------------------------

R/gg_overview.R

@@ -109,6 +109,7 @@ gg_overview <- function(dataset,
     #general information
     ggplot2::labs(x = "Datetime")+
     #theming and styling
+    ggplot2::scale_x_datetime()+
     cowplot::theme_cowplot()+
     ggplot2::theme(
       panel.grid.major = ggplot2::element_line(colour = "grey98"), 

R/helper.R

@@ -38,14 +38,36 @@ is.all.scalar <- function(...) {
     purrr::every(\(x) length(x) == 1)
 }
 
-#counts the different time differences per group (in a grouped dataset)
+#' Counts the Time differences (epochs) per group (in a grouped dataset)
+#'
+#' @inheritParams cut_Datetime
+#'
+#' @return a `tibble` with the number of occurences of each time difference per
+#'   group
+#' @export
+#'
+#' @examples
+#' #get a dataset with irregular intervals
+#' filepath <- system.file("extdata/sample_data_LYS.csv", package = "LightLogR")
+#' dataset <- import$LYS(filepath)
+#' 
+#' #count.difftime returns the number of occurences of each time difference
+#' #and is more comprehensive in terms of a summary than `gap_finder` or 
+#' #`dominant_epoch`
+#' count.difftime(dataset)
+#' dominant_epoch(dataset)
+#' gap_finder(dataset)
+#' 
+#' #irregular data can be regularized with `aggregate_Datetime`
+#' dataset %>% aggregate_Datetime(unit = "15 secs") %>% count.difftime()
+
 count.difftime <- function(dataset, Datetime.colname = Datetime) {
   dataset %>% 
     dplyr::mutate(
       difftime = c(NA, diff({{Datetime.colname}}) %>% lubridate::as.duration())
       ) %>% 
     tidyr::drop_na(difftime) %>% 
-    dplyr::count(difftime, sort = TRUE)
+    dplyr::count(difftime = difftime %>% lubridate::as.duration(), sort = TRUE)
 }
 
 #calculate the nth Quantile of time differences per group (in a grouped dataset)

R/import_LL.R

@@ -124,6 +124,7 @@ imports <- function(device,
       auto.id = ".*",
       manual.id = NULL,
       locale = readr::default_locale(),
+      silent = FALSE,
       ... =
     ),
     #function expression
@@ -169,7 +170,7 @@ imports <- function(device,
         dplyr::arrange(Datetime, .by_group = TRUE)
 
       #give info about the file
-      import.info(tmp, !!device, tz, !!ID.colname)
+      if(!silent) import.info(tmp, !!device, tz, !!ID.colname)
 
       #return the file
       tmp

R/symlog_trans.R

@@ -23,13 +23,13 @@
 #'                                      .default = `MELANOPIC EDI`))
 #' #basic application where transformation, breaks and labels are set manually
 #' dataset %>%                                     
-#' gg_day(col = Source) +
+#' gg_day(aes_col = Source) +
 #' ggplot2::scale_y_continuous(
 #' trans = "symlog")
 #'
 #' #the same plot, but with breaks and labels set manually                            
 #' dataset %>%                                     
-#' gg_day(col = Source) +
+#' gg_day(aes_col = Source) +
 #' ggplot2::scale_y_continuous(
 #' trans = "symlog", 
 #' breaks = c(-10^(5:0), 0, 10^(0:5)),
@@ -38,7 +38,7 @@
 #' #setting individual arguments of the symlog function manually allows
 #' #e.g., to emphasize values smaller than 1
 #' dataset %>%                                     
-#' gg_day(col = Source) +
+#' gg_day(aes_col = Source) +
 #' ggplot2::scale_y_continuous(
 #' trans = symlog_trans(thr = 0.01),
 #' breaks = c(-10^(5:-1), 0, 10^(-1:5)),

README.Rmd

@@ -90,7 +90,7 @@ There is a wide range of options to the `gg_day()` function to customize the out
 ```{r, fig.retina=2}
 dataset %>% 
   gg_day(
-    col = MEDI >= 250, scales = "fixed", size = 0.5) + 
+    aes_col = MEDI >= 250, scales = "fixed", size = 0.5) + 
   scale_color_discrete(type = c("orange", "skyblue"))
 ```
 
@@ -103,7 +103,7 @@ sample.data.environment %>%
   gg_day(
     start.date = "2023-08-18",
     y.axis = `MELANOPIC EDI`,
-    col = Source,
+    aes_col = Source,
     scales = "fixed",
     geom = "line")
 ```
@@ -114,7 +114,7 @@ sample.data.environment %>%
   gg_day(
     end.date = "2023-08-15",
     y.axis = `MELANOPIC EDI`,
-    col = Source,
+    aes_col = Source,
     scales = "fixed",
     geom = "boxplot",
     group = interaction(Source, Datetime.rounded)) + 

README.md

@@ -126,7 +126,7 @@ options. You can also override most of the defaults, e.g., for different
 ``` r
 dataset %>% 
   gg_day(
-    col = MEDI >= 250, scales = "fixed", size = 0.5) + 
+    aes_col = MEDI >= 250, scales = "fixed", size = 0.5) + 
   scale_color_discrete(type = c("orange", "skyblue"))
 #> Scale for colour is already present.
 #> Adding another scale for colour, which will replace the existing scale.
@@ -147,7 +147,7 @@ sample.data.environment %>%
   gg_day(
     start.date = "2023-08-18",
     y.axis = `MELANOPIC EDI`,
-    col = Source,
+    aes_col = Source,
     scales = "fixed",
     geom = "line")
 #> Only Dates will be used from start.date and end.date input. If you also want to set Datetimes or Times, consider using the `filter_Datetime()` function instead.
@@ -170,7 +170,7 @@ sample.data.environment %>%
   gg_day(
     end.date = "2023-08-15",
     y.axis = `MELANOPIC EDI`,
-    col = Source,
+    aes_col = Source,
     scales = "fixed",
     geom = "boxplot",
     group = interaction(Source, Datetime.rounded)) + 

_pkgdown.yml

@@ -15,20 +15,29 @@ reference:
     - import
     - import.Statechanges
 
-  - title: Process
+  - title: Insight
     desc: >
-      This section includes functions to process light logger data, e.g., to
-      validate and clean data, to filter, cut or aggreagate data, or to join 
-      datasets.
+      This section includes functions to gain more insight into light logger. 
+      Functions in this section will not return a version of the input dataset, 
+      but rather information based on it.
     contents:
+    - count.difftime
     - dominant_epoch
     - gapless_Datetimes
-    - gap_handler
     - gap_finder
+
+  - title: Validate & Process
+    desc: >
+      This section includes functions to process light logger data, e.g., to
+      validate and clean data, to filter, cut or aggreagate data, or to join 
+      datasets. All of these functions will return a version of the input dataset.
+    contents:
+    - gap_handler
     - cut_Datetime
     - aggregate_Datetime
     - create_Time.data
     - filter_Datetime
+    - filter_Datetime_multiple
     - filter_Date
     - filter_Time
     - join.datasets
@@ -53,7 +62,15 @@ reference:
     contents:
     - gg_overview
     - gg_day
+    - gg_days
+
+  - title: Helpers
+    desc: >
+      This section includes helper functions that are used in the other sections.
+    contents:
     - symlog_trans
+    - Datetime_breaks
+    - Datetime_limits
 
   - title: Datasets
     desc: >