From b590003b24e07af811d936c8dfe2a6e9ff080b9e Mon Sep 17 00:00:00 2001
From: Felipe <lipecaso@gmail.com>
Date: Tue, 30 Apr 2024 15:30:45 +0000
Subject: [PATCH] add docs in sits_merge

---
 R/api_merge.R     | 24 ++++++++++++++++++++++++
 R/sits_merge.R    | 44 +++++++++++++++++++-------------------------
 man/sits_merge.Rd | 20 ++++++++++++++++++++
 3 files changed, 63 insertions(+), 25 deletions(-)
 create mode 100644 R/api_merge.R

diff --git a/R/api_merge.R b/R/api_merge.R
new file mode 100644
index 00000000..8589f9f4
--- /dev/null
+++ b/R/api_merge.R
@@ -0,0 +1,24 @@
+.merge_diff_timeline <- function(t1, t2) {
+    abs(as.Date(t1) - as.Date(t2))
+}
+
+.merge_fi <- function(data1, data2) {
+    data1 <- slider::slide2_dfr(data1, data2, function(x, y) {
+        .fi(x) <- dplyr::arrange(
+            dplyr::bind_rows(.fi(x), .fi(y)),
+            .data[["date"]],
+            .data[["band"]],
+            .data[["fid"]]
+        )
+        # remove duplicates
+        .fi(x) <- dplyr::distinct(
+            .fi(x),
+            .data[["band"]],
+            .data[["date"]],
+            .keep_all = TRUE
+        )
+
+        return(x)
+    })
+    return(data1)
+}
diff --git a/R/sits_merge.R b/R/sits_merge.R
index 8c6f6603..5efff01a 100644
--- a/R/sits_merge.R
+++ b/R/sits_merge.R
@@ -11,6 +11,17 @@
 #' To merge data cubes, they should share the same sensor, resolution,
 #' bounding box, timeline, and have different bands.
 #'
+#' When the user requests a sits_merge operation for two regular cubes with
+#' the same number of time intervals but with timelines that are not equal
+#' the system issues a warning and asks the user to provide a \code{tolerance}
+#' parameter which will be used in the merging operation.
+#' The temporal tolerance parameter should be less than the time interval
+#' between two images of both cubes.
+#' In this case the second cube will have its timeline and the image
+#' file names changed to match the timeline of the first cube.
+#' The images of the second cube will be written in \code{output_dir}
+#' directory.
+#'
 #' @param data1      Time series (tibble of class "sits")
 #'                   or data cube (tibble of class "raster_cube") .
 #' @param data2      Time series (tibble of class "sits")
@@ -19,6 +30,14 @@
 #' @param suffix     If there are duplicate bands in data1 and data2
 #'                   these suffixes will be added
 #'                   (character vector).
+#' @param tolerance  A period tolerance to merge both cubes.
+#'                   ISO8601-compliant time period for regular data cubes,
+#'                   with number and unit, where "D", "M" and "Y" stand
+#'                   for days, month and year; e.g., "P16D" for 16 days.
+#'                   The temporal tolerance parameter should be less than
+#'                   the time interval between two images of both cubes.
+#' @param output_dir Valid directory for storing merged images.
+#'
 #' @return merged data sets (tibble of class "sits" or
 #'         tibble of class "raster_cube")
 #' @examples
@@ -152,31 +171,6 @@ sits_merge.raster_cube <- function(data1, data2, ...,
     return(data1)
 }
 
-.merge_diff_timeline <- function(t1, t2) {
-    abs(as.Date(t1) - as.Date(t2))
-}
-
-.merge_fi <- function(data1, data2) {
-    data1 <- slider::slide2_dfr(data1, data2, function(x, y) {
-        .fi(x) <- dplyr::arrange(
-            dplyr::bind_rows(.fi(x), .fi(y)),
-            .data[["date"]],
-            .data[["band"]],
-            .data[["fid"]]
-        )
-        # remove duplicates
-        .fi(x) <- dplyr::distinct(
-            .fi(x),
-            .data[["band"]],
-            .data[["date"]],
-            .keep_all = TRUE
-        )
-
-        return(x)
-    })
-    return(data1)
-}
-
 #' @rdname sits_merge
 #' @export
 sits_merge.default <- function(data1, data2, ...) {
diff --git a/man/sits_merge.Rd b/man/sits_merge.Rd
index a6f9aa46..d39d3879 100644
--- a/man/sits_merge.Rd
+++ b/man/sits_merge.Rd
@@ -27,6 +27,15 @@ or data cube (tibble of class "raster_cube") .}
 \item{suffix}{If there are duplicate bands in data1 and data2
 these suffixes will be added
 (character vector).}
+
+\item{tolerance}{A period tolerance to merge both cubes.
+ISO8601-compliant time period for regular data cubes,
+with number and unit, where "D", "M" and "Y" stand
+for days, month and year; e.g., "P16D" for 16 days.
+The temporal tolerance parameter should be less than
+the time interval between two images of both cubes.}
+
+\item{output_dir}{Valid directory for storing merged images.}
 }
 \value{
 merged data sets (tibble of class "sits" or
@@ -41,6 +50,17 @@ for the same set of locations in the same tibble.
 
 To merge data cubes, they should share the same sensor, resolution,
 bounding box, timeline, and have different bands.
+
+When the user requests a sits_merge operation for two regular cubes with
+the same number of time intervals but with timelines that are not equal
+the system issues a warning and asks the user to provide a \code{tolerance}
+parameter which will be used in the merging operation.
+The temporal tolerance parameter should be less than the time interval
+between two images of both cubes.
+In this case the second cube will have its timeline and the image
+file names changed to match the timeline of the first cube.
+The images of the second cube will be written in \code{output_dir}
+directory.
 }
 \examples{
 if (sits_run_examples()) {