S3-objects.Rmd

# S3 - generics and methods

In S3, methods belong to functions called generic functions

## generics 

```{r}
t
#> function (x)
#> UseMethod("t")
#> <bytecode: 0x7fc9474588a0>
#> <environment: namespace:base>

pryr::ftype(t)
#> [1] "s3"      "generic"
```

## methods

```{r}
pryr::ftype(t.data.frame)
#> [1] "s3"      "method"
```



# S3 - generics and methods

## Some generics have A LOT of methods


```{r}
methods(summary)
```

```{r}
[1] summary.aov                    summary.aovlist*               summary.aspell*
[4] summary.check_packages_in_dir* summary.connection             summary.data.frame
[7] summary.Date                   summary.default                summary.ecdf*
[10] summary.factor                 summary.glm                    summary.infl*
[13] summary.lm                     summary.loess*                 summary.manova
[16] summary.matrix                 summary.mlm*                   summary.nls*
[19] summary.packageStatus*         summary.PDF_Dictionary*        summary.PDF_Stream*
[22] summary.POSIXct                summary.POSIXlt                summary.ppr*
[25] summary.prcomp*                summary.princomp*              summary.proc_time
[28] summary.srcfile                summary.srcref                 summary.stepfun
[31] summary.stl*                   summary.table                  summary.tukeysmooth*
[34] summary.warnings
```



# Detecting/recognizing S3 objects

## Most objects in R are S3 objects <br> But it's not always straightforward to recognize them

```{r}
library(pryr)

# data.frame
otype(mtcars)
#> [1] "S3"

# vector
otype(c("a", "b", "c"))
#> [1] "base"

# factor
otype(as.factor(c("a", "b", "c")))
#> [1] "S3"

```



## S3 - Inspecting them

What methods are on the class `foo`

```{r}
methods(foo) #  or methods("foo")
```

What class is an object

```{r}
class(5)
class(mtcars)
```

Get method of an S3 class by name

```{r}
getS3method("foo", "numeric")
getS3method("foo", "character")
getS3method("foo", "default")
```

Does an object have a class?

```{r}
x <- "hello world"
class(x)
#> "character"
is.object(x)
#> [1] FALSE
class(x) <- "saying"
class(x)
#> [1] "character"
is.object(x)
#> [1] TRUE
```



# S3 - assigning classes

## You can assign any S3 class to any object

```{r}
x <- 5
class(x) <- "my_number"
```

## You can alternatively use the `structure()` function

```{r}
structure(5, class = "my_number")
```

## You can assign multiple classes to the same object

```{r}
structure(5, class = c("foo", "bar"))
# or
x <- 5
class(x) <- c("foo", "bar"))
```



# S3 - dropping classes

## You can also drop an S3 class from an object

```{r}
x <- structure(5, class = "stuff")
class(x)
#> [1] "suff"
class(x) <- NULL
class(x)
#> [1] "numeric"
```



# S3 - creating new methods and generics
```{r}
foo <- function(x) UseMethod("foo")
foo.character <- function(x) paste("hello ", x)
foo.numeric <- function(x) x^2
foo.default <- function(x) stop("no 'foo' method for ", class(x)[1L])
```

`.default`

```{r}
foo(data.frame())
#> Error: no 'foo' method for 'data.frame'
```

`.character`

```{r}
foo('bar')
#> [1] "hello bar"
```

`.numeric`

```{r}
foo(4)
#> [1] 16
```



# S3 - Dispatching not on the 1st parameter <i class="fa fa-surprise"></i>

On last slidde we chose which method to use based on 1st parameter.
Doesn't have to be the 1st parameter.

You may want to do this when the 1st parameter must stay as 1st parameter,
but it's not the one that the method decision depends on.

```{r}
foo <- function(x, y) UseMethod("foo", y)
foo.numeric <- function(x, y) y - x
```

```{r}
foo(5, 10)
#> [1] 5
```

Ideally, the parameter that the method toggle depends on is not optional.



# S3 - package documentation

Export generic and method, and ...

... just show the generic in `foo` manual file

```{r}
#' My function description
#' @export
#' @parameter x description of x
#' @examples ...
foo <- function(x) UseMethod("foo")

#' @export
foo.character <- function(x) paste("hello ", x)
```

... show generic and methods in `foo` manual file

```{r}
#' My function description
#' @export
#' @parameter x description of x
#' @examples ...
foo <- function(x) UseMethod("foo")

#' @export
#' @rdname foo
foo.character <- function(x) paste("hello ", x)
```



# S3 - attributes

List attributes on any object, including an S3 object

```{r}
attributes("foo bar")
#> NULL
x <- structure("foo bar", class = "stuff")
attributes(x)
#> $class
#> [1] "stuff"
```

Add arbitrary attributes

```{r}
attr(x, "fruit") <- "apple"
attributes(x)
#> $class
#> [1] "stuff"
#> $fruit
#> [1] "apple"
```

Access single attributes just as you set them

```{r}
attr(x, "fruit")
#> [1] "apple"
```             



# S3 - print methods

Often useful when returned data is very large/unwieldy

<br>

Make an S3 object

```{r}
x <- structure(list(foo = 5, bar = 9), class = "stuff")
```

Add a print methods for S3 objects

```{r}
print.stuff <- function(x, ...) {
cat(paste("foo: ", x$foo), sep = "\n")
cat(paste("bar: ", x$bar), sep = "\n")
}
```

Now any objects with class `stuff` will use the print method

```{r}
x
#> foo:  5
#> bar:  9
```             



# S3 - building on top of generics

* many packages build on top of functions in base R, e.g.: `plot`, `summary`, `print`
* to build on these in a package, you have to follow the parameter patterns used by the generic - if you don't, R CMD CHECK bops you on the head <i class="fa fa-dizzy"></i>:

<br>

```{r}
W  checking S3 generic/method consistency (2s)
print:
 function(x, ...)
print.some_class:
 function(x)
```



# S3 - classes are easily lost

### Create an object

```{r}
x <- structure(list("hello", "world"), class = "foobar")
```

### Apply some function to each element

```{r}
lapply(x, function(z) z)
#> [[1]]
#> [1] "hello"
#> 
#> [[2]]
#> [1] "world"
```
<br>
### Oh no <i class="far fa-sad-tear"></i>
<br>
### Just be aware - whether making or consuming S3 classes