|
| 1 | +#' Fill Gaps in Data Using Imputation (LOCF or Set-Value) |
| 2 | +#' |
| 3 | +#' This helper function fills gaps in time series or vector data based on the `remaining_epochs` vector. |
| 4 | +#' Gaps can be filled using Last Observation Carried Forward (LOCF) or a user-defined constant. |
| 5 | +#' |
| 6 | +#' @param ... Either a data frame, or one or more named numeric vectors of equal length. |
| 7 | +#' @param remaining_epochs An integer vector of the same length as the input data. |
| 8 | +#' Each value represents how many times each observation (including the original) |
| 9 | +#' should appear in the result. |
| 10 | +#' @param impute_strategy Character string, either `"locf"` (default) or `"set-value"`. |
| 11 | +#' Determines how gap rows are filled: |
| 12 | +#' - `"locf"` repeats the last observed value(s). |
| 13 | +#' - `"set-value"` fills gap rows with the constant provided in `value`. |
| 14 | +#' @param value A single numeric value used to fill gaps when `impute_strategy = "set-value"`. |
| 15 | +#' Required in that case; ignored for `"locf"`. |
| 16 | +#' |
| 17 | +#' @return A data frame (if multiple columns) or vector (if one column), |
| 18 | +#' with the appropriate number of rows and gap values filled. |
| 19 | +#' |
| 20 | +#' @details |
| 21 | +#' This function avoids full memory expansion of raw time series. Instead, it builds the filled |
| 22 | +#' result incrementally and supports efficient handling of imputation for gaps defined by |
| 23 | +#' `remaining_epochs`. It's especially helpful in constrained environments or with large data. |
| 24 | +#' |
| 25 | +#' @examples |
| 26 | +#' # LOCF with data frame |
| 27 | +#' df = data.frame(x = 1:3, y = c(10, 20, 30)) |
| 28 | +#' impute_gaps_epoch_level(df, remaining_epochs = c(1, 3, 2)) |
| 29 | +#' |
| 30 | +#' # LOCF with a vector |
| 31 | +#' impute_gaps_epoch_level(c(5, 6, 7), remaining_epochs = c(2, 1, 3)) |
| 32 | +#' |
| 33 | +#' # Set-value with a single vector |
| 34 | +#' impute_gaps_epoch_level(c(1, 2), remaining_epochs = c(3, 1), impute_strategy = "set-value", value = 99) |
| 35 | +#' |
| 36 | +#' # Set-value with multiple vectors |
| 37 | +#' impute_gaps_epoch_level(x = c(1, 2), y = c(10, 20), remaining_epochs = c(2, 2), |
| 38 | +#' impute_strategy = "set-value", value = 0) |
| 39 | +#' @export |
| 40 | +impute_gaps_epoch_level = function(..., remaining_epochs, |
| 41 | + impute_strategy = "locf", |
| 42 | + value = NULL) { |
| 43 | + inputs = list(...) |
| 44 | + |
| 45 | + # Determine data source: data frame or multiple vectors |
| 46 | + if (length(inputs) == 1 && is.data.frame(inputs[[1]])) { |
| 47 | + data = inputs[[1]] |
| 48 | + } else { |
| 49 | + data = as.data.frame(inputs) |
| 50 | + } |
| 51 | + |
| 52 | + stopifnot(impute_strategy %in% c("locf", "set-value")) |
| 53 | + if (impute_strategy == "set-value" && is.null(value)) { |
| 54 | + stop("You must provide a 'value' when using impute_strategy = 'set-value'.") |
| 55 | + } |
| 56 | + |
| 57 | + total_rows = sum(remaining_epochs) |
| 58 | + filled_list = vector("list", total_rows) |
| 59 | + index = 1 |
| 60 | + |
| 61 | + for (i in seq_len(nrow(data))) { |
| 62 | + reps = remaining_epochs[i] |
| 63 | + |
| 64 | + # Always include the original row |
| 65 | + filled_list[[index]] = data[i, , drop = FALSE] |
| 66 | + index = index + 1 |
| 67 | + |
| 68 | + # For additional rows, fill based on strategy |
| 69 | + if (reps > 1) { |
| 70 | + if (impute_strategy == "locf") { |
| 71 | + for (j in 2:reps) { |
| 72 | + filled_list[[index]] = data[i, , drop = FALSE] |
| 73 | + index = index + 1 |
| 74 | + } |
| 75 | + } else if (impute_strategy == "set-value") { |
| 76 | + for (j in 2:reps) { |
| 77 | + filled_list[[index]] = as.data.frame(lapply(data[i, , drop = FALSE], function(x) value)) |
| 78 | + index = index + 1 |
| 79 | + } |
| 80 | + } |
| 81 | + } |
| 82 | + } |
| 83 | + |
| 84 | + result = do.call(rbind, filled_list) |
| 85 | + rownames(result) = NULL |
| 86 | + |
| 87 | + if (ncol(result) == 1) { |
| 88 | + return(result[[1]]) |
| 89 | + } else { |
| 90 | + return(result) |
| 91 | + } |
| 92 | +} |
0 commit comments