Merge branch 'master' into frollapply-nneg

Author: jangorecki

NEWS.md

@@ -32,18 +32,7 @@
     ```
     Additionally argument names in `frollapply` has been renamed from `x` to `X` and `n` to `N` to avoid conflicts with common argument names that may be passed to `...`, aligning to base R API of `lapply`. `x` and `n` continue to work with a warning, for now.
 
-5. Adaptive rolling functions no longer tolerate `NA`s and negative values passed to `n` argument.
-    ```r
-    n = c(2,NA,2)
-    frollsum(1:3, n, adaptive=TRUE)
-    #Error in froll(fun = "sum", x = x, n = n, fill = fill, algo = algo, align = align,  :
-    #  'n' must be non-negative integer values (>= 0)
-    ```
-    If for some reason previous `NA`s behavior is needed, it can be achieved by replacing `NA`s with a value big enough
-    ```r
-    n = nafill(c(2,NA,2), fill=.Machine$integer.max)
-    frollsum(1:3, n, adaptive=TRUE)
-    ```
+5. Negative and missing values of `n` argument of adaptive rolling functions trigger an error.
 
 ### NOTICE OF INTENDED FUTURE POTENTIAL BREAKING CHANGES 
 
@@ -223,6 +212,7 @@
     #[1] TRUE
     ```
 
+<<<<<<< HEAD
 18. New `frolladapt` helper function has been added to aid in preparation of adaptive length of rolling window width when dealing with _irregularly spaced ordered data_. This lets the user to apply a rolling function over a period without having to deal with gaps in a data where some periods might be missing, [#3241](https://github.com/Rdatatable/data.table/issues/3241). Thanks to @jangorecki for implementation.
 ```r
 idx = as.Date("2025-09-08") + c(0,1,4,5,6,7,9,10,14)
@@ -256,6 +246,41 @@ dt
 #8: 2025-09-18     8         7           7.5
 #9: 2025-09-22     9         8           9.0
 ```
+=======
+18. New helper `frolladapt` to facilitate applying rolling functions over windows of fixed calendar-time width in irregularly-spaced data sets, thereby bypassing the need to "augment" such data with placeholder rows, [#3241](https://github.com/Rdatatable/data.table/issues/3241). Thanks to @jangorecki for implementation.
+    ```r
+    idx = as.Date("2025-09-05") + c(0,4,7,8,9,10,12,13,17)
+    dt = data.table(index=idx, value=seq_along(idx))
+    dt
+    #        index value
+    #       <Date> <int>
+    #1: 2025-09-05     1
+    #2: 2025-09-09     2
+    #3: 2025-09-12     3
+    #4: 2025-09-13     4
+    #5: 2025-09-14     5
+    #6: 2025-09-15     6
+    #7: 2025-09-17     7
+    #8: 2025-09-18     8
+    #9: 2025-09-22     9
+    dt[, c("rollmean3","rollmean3days") := list(
+      frollmean(value, 3),
+      frollmean(value, frolladapt(index, 3), adaptive=TRUE)
+      )]
+    dt
+    #        index value rollmean3 rollmean3days
+    #       <Date> <int>     <num>         <num>
+    #1: 2025-09-05     1        NA            NA
+    #2: 2025-09-09     2        NA           2.0
+    #3: 2025-09-12     3         2           3.0
+    #4: 2025-09-13     4         3           3.5
+    #5: 2025-09-14     5         4           4.0
+    #6: 2025-09-15     6         5           5.0
+    #7: 2025-09-17     7         6           6.5
+    #8: 2025-09-18     8         7           7.5
+    #9: 2025-09-22     9         8           9.0
+    ```
+>>>>>>> master
 
 ### BUG FIXES
 

man/frolladapt.Rd

@@ -8,9 +8,9 @@
   frolladapt(x, n, align="right", partial=FALSE, give.names=FALSE)
 }
 \arguments{
-  \item{x}{ Integer. Other objects of type numeric (including \code{Date}, \code{POSIXct} and any others numeric-based class) will be coerced to integer, which, for example, in case of \code{POSIXct} means truncating to whole seconds. Must be sorted, have no duplicate and have no missing values. }
-  \item{n}{ Integer, positive, vector giving rolling window size(s). This is the \emph{total} number of included values in aggregate function. Value corresponds to unit of \code{x}. When \code{x} is a \code{POSIXct} then \code{n} are seconds, when \code{x} is a \code{Date} then \code{n} are days. }
-  \item{align}{ Character, default \code{"right"}. Other alignments than the default have not yet been implemented. }
+  \item{x}{ Integer. Must be sorted with no duplicates or missing values. Other objects with numeric storage (including most commonly \code{Date} and \code{POSIXct}) will be coerced to integer, which, for example, in case of \code{POSIXct} means truncating to whole seconds. }
+  \item{n}{ Integer vector giving rolling positive window size(s). Up to \code{n} values nearest to each value of \code{x}, with distance in the units of \code{x} and according to the window implied by \code{align}, are included in each rolling aggregation window. Thus when \code{x} is a \code{POSIXct}, \code{n} are seconds, and when \code{x} is a \code{Date}, \code{n} are days. }
+  \item{align}{ Character, default \code{"right"}. Other alignments have not yet been implemented. }
   \item{partial}{ Logical, default \code{FALSE}. Should the rolling window size(s) provided in \code{n} be trimmed to available observations. For details see \code{\link{froll}}. }
   \item{give.names}{ Logical, default \code{FALSE}. When \code{TRUE}, names are automatically generated corresponding to names of \code{n}. If answer is an integer vector, then the argument is ignored, see examples. }
 }

src/frollR.c

@@ -216,7 +216,7 @@ SEXP frolladapt(SEXP xobj, SEXP kobj, SEXP partial) {
   int n = INTEGER(kobj)[0];
   if (n < 1L)
     error(_("'n' must be positive integer values (>= 1)"));
-  int *x = INTEGER_RO(xobj);
+  const int *x = INTEGER_RO(xobj);
   int64_t len = XLENGTH(xobj); // can be 0
 
   if (len && x[0] == NA_INTEGER)
@@ -239,7 +239,7 @@ SEXP frolladapt(SEXP xobj, SEXP kobj, SEXP partial) {
     if (an > n) {
       error(_("internal error: an > n, should not increment i in the first place")); // # nocov
     } else if (an == n) {           // an is same size as n, so we either have no gaps or will need to shrink an by j++
-      if (lhs == rhs+n-1) {         // no gaps - or a k gaps and a k dups?
+      if (lhs == rhs+n-1) {         // no gaps - or a n gaps and a n dups?
         ians[i] = n;                // could skip if pre-fill
         i++;
         j++;

vignettes/datatable-joins.Rmd

@@ -169,7 +169,7 @@ Products[ProductReceived,
          on = list(id = product_id)]
 ```
 
-- Wrapping the related columns in the `data.table` `list` alias `.`.
+- Wrapping the related columns in the `list` alias `.`.
 
 ```{r, eval=FALSE}
 Products[ProductReceived,

vignettes/datatable-reshape.Rmd

@@ -143,11 +143,11 @@ However, there are situations we might run into where the desired operation is n
 
 ```{r}
 s2 <- "family_id age_mother name_child1 name_child2 name_child3 gender_child1 gender_child2 gender_child3
-         1         30         Ben        Anna          NA             1             2            NA
-         2         27         Tom          NA          NA             2            NA            NA
-         3         26         Lia         Sam         Amy             2             2             1
-         4         32         Max         Zoe         Joe             1             1             1
-         5         29         Dan         Eva          NA             2             1            NA"
+1         30         Ben        Anna          NA             1             2            NA
+2         27         Tom          NA          NA             2            NA            NA
+3         26         Lia         Sam         Amy             2             2             1
+4         32         Max         Zoe         Joe             1             1             1
+5         29         Dan         Eva          NA             2             1            NA"
 DT <- fread(s2)
 DT
 ## 1 = female, 2 = male

vignettes/datatable-secondary-indices-and-auto-indexing.Rmd

@@ -24,7 +24,11 @@ knitr::opts_chunk$set(
 .old.th = setDTthreads(1)
 ```
 
-This vignette assumes that the reader is familiar with data.table's `[i, j, by]` syntax, and how to perform fast key based subsets. If you're not familiar with these concepts, please read the [`vignette("datatable-intro", package="data.table")`](datatable-intro.html), [`vignette("datatable-reference-semantics", package="data.table")`](datatable-reference-semantics.html), and [`vignette("datatable-keys-fast-subset", package="data.table")`](datatable-keys-fast-subset.html) vignettes first.
+This vignette assumes that the reader is familiar with data.table's `[i, j, by]` syntax, and how to perform fast key based subsets. If you're not familiar with these concepts, please read the following vignettes first:
+
+- [`vignette("datatable-intro", package="data.table")`](datatable-intro.html) 
+- [`vignette("datatable-reference-semantics", package="data.table")`](datatable-reference-semantics.html)
+- [`vignette("datatable-keys-fast-subset", package="data.table")`](datatable-keys-fast-subset.html)
 
 ***
 

vignettes/fr/datatable-benchmarking.Rmd

@@ -20,7 +20,7 @@ h2 {
 
 ```{r echo=FALSE, file='../_translation_links.R'}
 ```
-`r .write.translation.links("Translations of this document are available in: %s")`
+`r .write.translation.links("Une traduction de ce document est disponible en : %s")`
 
 Ce document a pour but de guider la mesure de la performance de `data.table`. Il centralise la documentation des meilleures pratiques et des pièges à éviter.
 

vignettes/fr/datatable-faq.Rmd

@@ -16,12 +16,19 @@ vignette: >
 h2 {
     font-size: 20px;
 }
-#TOC { width: 100%; }
+
+#TOC {
+  border: 1px solid #ccc;
+  border-radius: 5px;
+  padding-left: 1em;
+  background: #f6f6f6;
+  width: 100%; 
+}
 </style>
 
 ```{r echo=FALSE, file='../_translation_links.R'}
 ```
-`r .write.translation.links("Translations of this document are available in: %s")`
+`r .write.translation.links("Une traduction de ce document est disponible en : %s")`
 
 ```{r, echo = FALSE, message = FALSE}
 library(data.table)
@@ -582,7 +589,10 @@ DT[ , b := rnorm(5)] # « remplace » la colonne entière par une colonne num
 
 ## Lecture de data.table à partir d'un fichier RDS ou RData
 
-`*.RDS` et `*.RData` sont des types de fichiers qui permettent de stocker efficacement des objets R en mémoire sur le disque. Cependant, le stockage de data.table dans le fichier binaire perd sa sur-allocation de colonnes. Ce n'est pas très grave -- votre data.table sera copié en mémoire lors de la prochaine opération *par référence* et lancera un avertissement. Il est donc recommandé d'appeler `setalloccol()` sur chaque data.table chargée avec les appels `readRDS()` ou `load()`.
+`*.RDS` et `*.RData` sont des types de fichiers qui permettent de stocker efficacement des objets R en mémoire sur le disque. Cependant, le stockage de data.table dans le fichier binaire perd sa sur-allocation de colonnes (voir aussi `?truelength`). Ce n'est pas très grave -- votre `data.table` sera copié en mémoire lors de la prochaine opération _par référence_ et lancera un avertissement.
+C'est pourquoi il est recommandé d'appeler `setDT()` sur chaque `data.table` chargé par un appel à `readRDS()` ou `load()` afin de restaurer ses attributs internes. Si vous avez simplement besoin de préallouer de l'espace pour de nouvelles colonnes, vous pouvez également utiliser `setalloccol()`.
+
+Pour d'autres informations, voir `?setDT` et `?truelength`.
 
 # Questions générales sur le package
 

vignettes/fr/datatable-importing.Rmd

@@ -17,7 +17,7 @@ h2 {
 
 ```{r echo=FALSE, file='../_translation_links.R'}
 ```
-`r .write.translation.links("Translations of this document are available in: %s")`
+`r .write.translation.links("Une traduction de ce document est disponible en : %s")`
 
 Ce document se concentre sur l'utilisation de `data.table` comme dépendance dans d'autres packages R. Si vous souhaitez utiliser le code C de `data.table` à partir d'une application non-R, ou appeler directement ses fonctions C, passez à la [dernière section](#non-r-API) de cette vignette.
 
@@ -75,7 +75,7 @@ dt2 = aggr(dt)
 stopifnot(nrow(dt2) < 100)
 ```
 
-Lorsque vous testez votre package, vous pouvez utiliser `R CMD check --no-stop-on-test-error`, qui continuera après une erreur et exécutera tous vos tests (au lieu de s'arrêter à la première ligne de script qui a échoué).
+Lorsque vous testez votre package, vous pouvez utiliser `R CMD check --no-stop-on-test-error`, qui continuera après une erreur et exécutera tous vos tests (au lieu de s'arrêter à la première ligne du script qui a échoué).
 
 ## Tester en utilisant `testthat`
 

vignettes/fr/datatable-intro.Rmd

@@ -11,7 +11,7 @@ vignette: >
 
 ```{r echo=FALSE, file='../_translation_links.R'}
 ```
-`r .write.translation.links("Translations of this document are available in: %s")`
+`r .write.translation.links("Une traduction de ce document est disponible en : %s")`
 
 ```{r, echo = FALSE, message = FALSE}
 require(data.table)
@@ -101,7 +101,7 @@ Vous pouvez aussi convertir des objets existants en une `data.table` en utilisan
     getOption("datatable.print.nrows")
     ```
 
-* `data.table` ne définit ni n'utilise jamais de *nom de ligne*. Nous verrons pourquoi dans la vignette *"Sous-ensemble basé sur des clés et recherche binaire rapide"*.
+* `data.table` ne définit ni n'utilise jamais de *nom de ligne*. Nous verrons pourquoi dans la [`vignette("datatable-keys-fast-subset", package="data.table")`](datatable-keys-fast-subset.html).
 
 ### b) Forme générale - dans quel sens la 'data.table' est-elle *étendue* ? {#enhanced-1b}
 
@@ -479,7 +479,7 @@ ans
 
 **Clés :** actuellement `keyby` en fait un peu plus que *simplement trier*. Il *définit une clé* également après le tri en initialisant un `attribute` appelé `sorted`.
 
-Nous en apprendrons plus au sujet des `clés` dans la vignette *Clés et sous-ensembles basés sur la recherche binaire rapide*; pour l'instant, tout ce que vous devez savoir est que vous pouvez utiliser `keyby` pour trier automatiquement le résultat selon les colonnes spécifiées dans `by`.
+Nous en apprendrons plus au sujet des `clés` dans la [`vignette("datatable-keys-fast-subset", package="data.table")`](datatable-keys-fast-subset.html); pour l'instant, tout ce que vous devez savoir est que vous pouvez utiliser `keyby` pour trier automatiquement le résultat selon les colonnes spécifiées dans `by`.
 
 ### c) Chaînage
 
@@ -643,6 +643,31 @@ DT[, print(list(c(a,b))), by = ID] # (2)
 
 Dans (1), pour chaque groupe, un vecteur est renvoyé, de longueur = 6,4,2 ici. Néanmoins, (2) renvoie une liste de longueur 1 pour chaque groupe, dont chaque premier élément contient des vecteurs de longueur 6,4,2. C'est pourquoi, (1) a pour longueur totale `6+4+2 =`r 6+4+2``, alors que (2) renvoie `1+1+1=`r 1+1+1``.
 
+La flexibilité de j nous permet de ranger toute liste d'objets comme un élément de data.table. Par exemple lorsque des modèles statistiques sont adaptés aux groupes, ils peuvent être placés dans un data.table. Le code est concis et facile à comprendre.
+
+```{r}
+## les vols long courrier couvrent-ils les retards au départ davantage que les vols à courte distance ?
+## la couverture varie-t-elle selon les mois ?
+flights[, `:=`(makeup = dep_delay - arr_delay)]
+
+makeup.models <- flights[, .(fit = list(lm(makeup ~ distance))), by = .(month)]
+makeup.models[, .(coefdist = coef(fit[[1]])[2], rsq = summary(fit[[1]])$r.squared), by = .(month)]
+```
+
+Avec les data.frames il nous faut un code plus complexe pour obtenir le même résultat.
+
+```{r}
+setDF(flights)
+flights.split <- split(flights, f = flights$month)
+makeup.models.list <- lapply(flights.split, function(df) c(month = df$month[1], fit = list(lm(makeup ~ distance, data = df))))
+makeup.models.df <- do.call(rbind, makeup.models.list)
+data.frame(t(sapply(
+  makeup.models.df[, "fit"],
+  function(model) c(coefdist = coef(model)[2L], rsq =  summary(model)$r.squared)
+)))
+setDT(flights)
+```
+
 ## Résumé
 
 La forme générale de la syntaxe de `data.table` est :
@@ -659,7 +684,7 @@ Jusqu'ici nous avons vu que,
 
 * Nous pouvons également trier un `data.table` en utilisant `order()`, qui utilise en interne l’algorithme de tri rapide de data.table pour de meilleures performances.
 
-Nous pouvons faire beaucoup plus dans `i` en créant une `data.table` avec clés, ce qui permet de réaliser rapidement les sous-ensembles et les jointures. Nous verrons cela dans les vignettes *"Clés et sous-ensembles basés sur la recherche binaire rapide"* et *"Jointures et jointures liées au temps"*.
+Nous pouvons faire beaucoup plus dans `i` en créant une `data.table` avec clés, ce qui permet de réaliser rapidement les sous-ensembles et les jointures. Nous verrons cela dans les [`vignette("datatable-keys-fast-subset", package="data.table")`](datatable-keys-fast-subset.html) et [`vignette("datatable-joins", package="data.table")`](datatable-joins.html).
 
 #### En utilisant `j` :
 
@@ -693,7 +718,7 @@ Nous pouvons faire beaucoup plus dans `i` en créant une `data.table` avec clés
 
 Tant que `j` renvoie un objet `list`, chaque élément de la liste va devenir une colonne du `data.table` résultant.
 
-Nous verrons dans la vignette suivante comment *ajouter / mettre à jour / supprimer* des colonnes *par référence* et comment les combiner avec `i` et `by` .
+Nous verrons dans la prochaine [(`vignette("datatable-reference-semantics", package="data.table")`)](datatable-reference-semantics.html) comment *ajouter / mettre à jour / supprimer* des colonnes *par référence* et comment les combiner avec `i` et `by` .
 
 ***