What is setReplaceMethod() and how does it work?

Question

I'm confused about the usage of setReplaceMethod(). Looking at ?setReplaceMethod does not provide an explanation and Googling is less than helpful.

QUESTION : Please explain setReplaceMethod(), it's usage and how it works (preferably with an example).

Answer 1

Here is what I found. As pointed by @Hong Ooi in the comments setReplaceMethod("fun") is the same as setMethod("fun<-"), so setReplaceMethod is used to create a method for a generic replacement function in the S4 object system of R.

What is a replacement function is explained in what-are-replacement-functions-in-r. Very rougly, if you have a function called fun<-, because its name ends with <-, you can write fun(x)<-a and R will read x <- "fun<-"(x,a).

The S4 object system is described in S4 - Advanced R.

To give an example maybe it is easier to start by creating a method for an S4 generic function, which is not a replacement function:

## Define an S4 class 'Polygon' and an object of this class
setClass("Polygon", representation(sides = "integer"))
p1 <- new("Polygon", sides = 33L)
## Define a generic S4 function 'sides'
sides <- function(object){ NA }
setGeneric("sides")
## sides returns NA
sides( p1 )
## Define a method for 'sides' for the class 'Polygon'
setMethod("sides", signature(object = "Polygon"), function(object) {
  object@sides
})
## Now sides returns the sides of p1
sides( p1 )

Creating a method for a generic replacement function is similar:

## Define a generic replacement function 'sides<-'
"sides<-" <- function(object, value){ object }
setGeneric( "sides<-" )
## The generic 'sides<-' doesn't change the object
sides( p1 ) <- 12L
sides( p1 )
## Define a method for 'sides<-' for the class 'Polygon',
## setting the value of the 'sides' slot
setMethod( "sides<-", signature(object = "Polygon"), function(object, value) {
  object@sides <- value
  object
})
## Now 'sides<-' change the sides of p1
sides( p1 ) <- 12L
sides( p1 )

You asked also about $<-. My guess is this: x$name<-value is interpreted as "$"(x,name)<-value and then as x <- "$<-"(x,name,value). Note that a generic function $<- is already defined (isGeneric("$<-")), so we only define a method for our class Polygon:

setMethod( "$<-", signature(x = "Polygon"), function(x, name, value) {
  if( name=="sides" ){
    x@sides <- value
  }
  x
})
## Nothing changes if we try to set 'faces'
p1$faces <- 3L
p1
## but we can set the 'sides'
p1$sides <- 3L
p1

Note that the arguments x, name and value are dictated by the generic.

Answer 2

For an extraction method such as $, [, or names(), a replacement method such as $<-, [<-, or names<- replaces the value that would have been extracted.

Take, for example, a list:

example_object <- list(a = 1, b = 2)
# the extract method $, when called with arguments example_object and a,
# extracts and returns the value 1
example_object$a
# [1] 1
# the replace method $<-, when called with arguments example_object, a, and 42,
# replaces the value 1 (at example_object$a) with the value 42
example_object$a <- 42
example_object
# $a
# [1] 42
# 
# $b
# [1] 2

So, for S4 classes, setMethod("$", ...) will define the behavior of the extraction method $ while setMethod("$<-", ...) or equivalently setReplaceMethod("$", ...) will define the behavior of the replacement method $<-. setReplaceMethod("$") is just meant to be more expressive than setMethod("$<-"), to make clear that you are defining the replacement method for $.

An example using an S4 class:

setClass("MyClass", representation(a = "numeric", b = "numeric"))

setMethod("$", signature = "MyClass",
          function (x, name) {
              if ( name == "a" ) {
                  return(x@a)
              }
              else if ( name == "b" ) {
                  return(x@b)
              }
              else {
                  stop(paste("No slot", name, "for MyClass"), call. = FALSE)
              }
          }
)
# [1] "$"

my_object <- new("MyClass", a = 1, b = 2)
my_object@a
# [1] 1
my_object$a
# [1] 1

my_object@a <- 42
my_object@a
# [1] 42
my_object$a <- 3.14 # will not work because we have not set the method for $<-
# Error in `$<-`(`*tmp*`, a, value = 3.14) : 
#   no method for assigning subsets of this S4 class
my_object@a
# [1] 42

setReplaceMethod("$", signature = "MyClass",
                 function(x, name, value) {
                     if ( name == "a" ) {
                         x@a <- value
                         return(x)
                     }
                     else if ( name == "b" ) {
                         x@b <- value
                         return(x)
                     }
                     else {
                         stop(paste("No slot", name, "for MyClass"),
                              call. = FALSE)
                     }
                 }
)
# [1] "$<-"

my_object$a <- 3.14
my_object@a
# [1] 3.14