Returning data frame as main result but also informative list as side effect

Question

I'm writing a function where I want the main output to be a data frame (that can be piped to other functions), but I also want to allow users access to an informative list or vector of samples that were omitted from the final result. Are there best practices for how to go about this, or examples of functions/packages that do this well?

Currently I'm exploring returning the information as an attribute and throwing a warning informing users they can access the list with attr(resulting-df, "omitted")

Any advice would be greatly appreciated, thank you!

library(dplyr)

iris <- iris %>%
  mutate(index = 1:nrow(.))

return_filtered <- function(df) {

  res <- filter(df, Sepal.Length > 6)
  omitted <- setdiff(iris$index, res$index)

  attr(res, "omitted") <- omitted
  return(res)

}

iris2 <- return_filtered(iris)
attributes(iris2)
#> $names
#> [1] "Sepal.Length" "Sepal.Width"  "Petal.Length" "Petal.Width"  "Species"     
#> [6] "index"       
#> 
#> $class
#> [1] "data.frame"
#> 
#> $row.names
#>  [1]  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
#> [26] 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50
#> [51] 51 52 53 54 55 56 57 58 59 60 61
#> 
#> $omitted
#>  [1]   1   2   3   4   5   6   7   8   9  10  11  12  13  14  15  16  17  18  19
#> [20]  20  21  22  23  24  25  26  27  28  29  30  31  32  33  34  35  36  37  38
#> [39]  39  40  41  42  43  44  45  46  47  48  49  50  54  56  58  60  61  62  63
#> [58]  65  67  68  70  71  79  80  81  82  83  84  85  86  89  90  91  93  94  95
#> [77]  96  97  99 100 102 107 114 115 120 122 139 143 150

^{Created on 2022-04-02 by the reprex package (v2.0.1)}

Answer 1

The question is probably a little opinion-based, but I don't think it's off-topic, since there are certainly neater and more formal ways to achieve what you want than your current method.

It's reasonable to hold the extra information as an attribute, but if you are going to do this then it is more idiomatic and extensible to create an S3 class, so that you can hide default printing of attributes, ensure your attributes are protected, and define a getter function for the attributes so that users don't have to sift through multiple attributes to get the correct one.

First, we will tweak your function to work with any data frame, and allow it to take any predicate so that it works as expected with dplyr::filter. We also get the function to add to the returned object's class attribute, so that it returns a new S3 object which inherits from data.frame

return_filtered <- function(df, predicate) {
  predicate    <- rlang::enquo(predicate)
  df$`..id..`  <- seq(nrow(df))
  res          <- dplyr::filter(df, !!predicate)
  filtered     <- setdiff(seq(nrow(df)), res$`..id..`)
  res$`..id..` <- NULL
  
  attr(res, "filtered") <- filtered
  class(res)            <- c("filtered", class(df))
  
  return(res)
}

We will define a print method so that the attributes don't show when we print our object:

print.filtered <- function(x, ...) {
  class(x) <- class(x)[class(x) != "filtered"]
  print(x, ...)
}

To get the filtered-out data from the attributes, we can create a new generic function that will only work on our new class:

get_filtered <- function(x) UseMethod("get_filtered")

get_filtered.default <- function(x) {
  stop("'get_filtered' only works on filtered objects")
}

get_filtered.filtered <- function(x) {
  attr(x, "filtered")
}

So now, when we call return_filtered, it seems to work the same as dplyr::filter, returning what appears to be a normal data frame:

df <- return_filtered(iris, Sepal.Length > 7)

df
#>    Sepal.Length Sepal.Width Petal.Length Petal.Width   Species
#> 1           7.1         3.0          5.9         2.1 virginica
#> 2           7.6         3.0          6.6         2.1 virginica
#> 3           7.3         2.9          6.3         1.8 virginica
#> 4           7.2         3.6          6.1         2.5 virginica
#> 5           7.7         3.8          6.7         2.2 virginica
#> 6           7.7         2.6          6.9         2.3 virginica
#> 7           7.7         2.8          6.7         2.0 virginica
#> 8           7.2         3.2          6.0         1.8 virginica
#> 9           7.2         3.0          5.8         1.6 virginica
#> 10          7.4         2.8          6.1         1.9 virginica
#> 11          7.9         3.8          6.4         2.0 virginica
#> 12          7.7         3.0          6.1         2.3 virginica

But we can get the filtered-out data from it with our get_filtered function.

get_filtered(df)
#>   [1]   1   2   3   4   5   6   7   8   9  10  11  12  13  14  15  16  17  18
#>  [19]  19  20  21  22  23  24  25  26  27  28  29  30  31  32  33  34  35  36
#>  [37]  37  38  39  40  41  42  43  44  45  46  47  48  49  50  51  52  53  54
#>  [55]  55  56  57  58  59  60  61  62  63  64  65  66  67  68  69  70  71  72
#>  [73]  73  74  75  76  77  78  79  80  81  82  83  84  85  86  87  88  89  90
#>  [91]  91  92  93  94  95  96  97  98  99 100 101 102 104 105 107 109 111 112
#> [109] 113 114 115 116 117 120 121 122 124 125 127 128 129 133 134 135 137 138
#> [127] 139 140 141 142 143 144 145 146 147 148 149 150

And calling get_filtered on a non-filtered data frame returns an informative error:

get_filtered(iris)
#> Error in get_filtered.default(iris): 'get_filtered' only works on filtered objects

^{Created on 2022-04-02 by the reprex package (v2.0.1)}