designing-oop-r

Original source / Raw SKILL.md

---
name: designing-oop-r
description: |
  Object-oriented programming in R: S7, S3, S4, and vctrs class design. Use this skill when designing classes for R projects, choosing between OOP systems, building class hierarchies with inheritance, or migrating between systems. Covers S7 class definitions and methods, the decision matrix for choosing S7 vs S3 vs S4 vs vctrs, practical guidelines for each system, and migration strategies.
---

# Designing OOP R

This skill covers object-oriented programming in R, including S7, S3, S4, and vctrs-based classes.

## Decision Tree: What Are You Building?

### 1. Vector-like objects (behave like atomic vectors)

**Use vctrs when:**
- Need data frame integration (columns/rows)
- Want type-stable vector operations
- Building factor-like, date-like, or numeric-like classes
- Need consistent coercion/casting behavior
- Working with existing tidyverse infrastructure

Examples: custom date classes, units, categorical data

### 2. General objects (complex data structures, not vector-like)

**Use S7 when:**
- NEW projects that need formal classes
- Want property validation and safe property access (`@`)
- Need multiple dispatch (beyond S3's double dispatch)
- Converting from S3 and want better structure
- Building class hierarchies with inheritance
- Want better error messages and discoverability

**Use S3 when:**
- Simple classes with minimal structure needs
- Maximum compatibility and minimal dependencies
- Quick prototyping or internal classes
- Contributing to existing S3-based ecosystems
- Performance is absolutely critical (minimal overhead)

**Use S4 when:**
- Working in Bioconductor ecosystem
- Need complex multiple inheritance (S7 doesn't support this)
- Existing S4 codebase that works well

## S7 vs S3 Comparison

| Feature | S3 | S7 | When S7 wins |
|---------|----|----|---------------|
| **Class definition** | Informal (convention) | Formal (`new_class()`) | Need guaranteed structure |
| **Property access** | `$` or `attr()` (unsafe) | `@` (safe, validated) | Property validation matters |
| **Validation** | Manual, inconsistent | Built-in validators | Data integrity important |
| **Method discovery** | Hard to find methods | Clear method printing | Developer experience matters |
| **Multiple dispatch** | Limited (base generics) | Full multiple dispatch | Complex method dispatch needed |
| **Inheritance** | Informal, `NextMethod()` | Explicit `super()` | Predictable inheritance needed |
| **Migration cost** | - | Low (1-2 hours) | Want better structure |
| **Performance** | Fastest | ~Same as S3 | Performance difference negligible |
| **Compatibility** | Full S3 | Full S3 + S7 | Need both old and new patterns |

## S7: Modern OOP

S7 combines S3 simplicity with S4 structure. See [s7-examples.md](references/s7-examples.md) for:
- Class definitions with `new_class()`
- Property validation
- Generic and method definition
- Inheritance with `parent`

## S3: Simple Classes

See [s3-examples.md](references/s3-examples.md) for:
- Constructor functions
- Print and format methods
- Simple class patterns

## Practical Guidelines

### Choose S7 when you have:

See [when-s7.md](references/when-s7.md) for:
- Complex validation needs
- Multiple dispatch needs
- Class hierarchies with clear inheritance

### Choose vctrs when you need:

See [when-vctrs.md](references/when-vctrs.md) for:
- Vector-like behavior in data frames
- Type-stable operations

### Choose S3 when you have:

See [when-s3.md](references/when-s3.md) for:
- Simple classes without complex needs
- Maximum performance needs (rare)
- Existing S3 ecosystem contributions

## Migration Strategy

1. **S3 → S7**: Usually 1-2 hours work, keeps full compatibility
2. **S4 → S7**: More complex, evaluate if S4 features are actually needed
3. **Base R → vctrs**: For vector-like classes, significant benefits
4. **Combining approaches**: S7 classes can use vctrs principles internally

source: Sarah Johnson's gist https://gist.github.com/sj-io/3828d64d0969f2a0f05297e59e6c15ad


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/s7-examples.md

```markdown
# S7: Modern OOP for New Projects

```r
library(S7)
```

### S7 class definition with properties and validation

```r
Range <- new_class("Range",
  properties = list(
    start = class_double,
    end = class_double
  ),
  validator = function(self) {
    if (self@end < self@start) {
      "@end must be >= @start"
    }
  }
)
```

### Usage - constructor and property access

```r
x <- Range(start = 1, end = 10)
x@start  # 1
x@end <- 20  # automatic validation

# Attempting invalid state triggers error
# x@end <- 0  # Error: @end must be >= @start
```

### Define a generic

```r
inside <- new_generic("inside", "x")
```

### Define a method for Range class

```r
method(inside, Range) <- function(x, y) {
  y >= x@start & y <= x@end
}
```

### Usage

```r
inside(x, 5)   # TRUE
inside(x, 25)  # FALSE
```

## Inheritance

```r
ColoredRange <- new_class("ColoredRange",
  parent = Range,
  properties = list(
    color = class_character
  )
)

cr <- ColoredRange(start = 1, end = 10, color = "red")
cr@color  # "red"
inside(cr, 5)  # TRUE - inherits method from Range
```

```

### references/s3-examples.md

```markdown
# S3: Simple Classes

### Constructor function

```r
new_simple <- function(x, label = "") {
  structure(
    x,
    label = label,
    class = "simple"
  )
}
```

### Print method

```r
print.simple <- function(x, ...) {
  label <- attr(x, "label")
  if (nzchar(label)) {
    cat(label, ": ", sep = "")
  }
  cat("Simple(", x, ")\n", sep = "")
  invisible(x)
}
```

### Format method

```r
format.simple <- function(x, ...) {
  paste0("Simple(", x, ")")
}
```

### Usage

```r
s <- new_simple(42, label = "Answer")
print(s)  # "Answer: Simple(42)"
```

### S3 dispatch

```r
summary.simple <- function(object, ...) {
  cat("A simple object with value:", object, "\n")
  cat("Label:", attr(object, "label"), "\n")
}
```

```

### references/when-s7.md

```markdown
# When to Choose S7

```r
library(S7)
```

## Complex validation needs

```r
Range <- new_class("Range",
  properties = list(
    start = class_double,
    end = class_double
  ),
  validator = function(self) {
    if (self@end < self@start) "@end must be >= @start"
  }
)
```

## Multiple dispatch needs

```r
combine <- new_generic("combine", c("x", "y"))

method(combine, list(Range, Range)) <- function(x, y) {
  Range(
    start = min(x@start, y@start),
    end = max(x@end, y@end)
  )
}
```

## Class hierarchies with clear inheritance

```r
Shape <- new_class("Shape",
  properties = list(
    color = class_character
  )
)

Circle <- new_class("Circle",
  parent = Shape,
  properties = list(
    radius = class_double
  )
)

Rectangle <- new_class("Rectangle",
  parent = Shape,
  properties = list(
    width = class_double,
    height = class_double
  )
)
```

### Generic with method for parent

```r
area <- new_generic("area", "x")

method(area, Circle) <- function(x) {
  pi * x@radius^2
}

method(area, Rectangle) <- function(x) {
  x@width * x@height
}
```

```

### references/when-vctrs.md

```markdown
# When to Choose vctrs

```r
library(vctrs)
```

## Vector-like behavior in data frames

### Define a percentage class

```r
new_percent <- function(x = double()) {
  vec_assert(x, double())
  new_vctr(x, class = "percentage")
}

percent <- function(x = double()) {
  x <- vec_cast(x, double())
  new_percent(x)
}

format.percentage <- function(x, ...) {
  paste0(vec_data(x) * 100, "%")
}
```

### Works seamlessly in data frames

```r
df <- data.frame(
  x = 1:3,
  pct = percent(c(0.1, 0.2, 0.3))
)
```

## Type-stable operations

### Combining maintains type

```r
vec_c(percent(0.1), percent(0.2))  # predictable behavior
```

### Explicit, safe casting

```r
vec_cast(0.5, percent())  # converts double to percent
```

## When vctrs is the right choice

- Custom date/time classes
- Unit-aware numbers (meters, kilograms)
- Categorical data with custom behavior
- Any "vector-like" data that should work in tidyverse

```

### references/when-s3.md

```markdown
# When to Choose S3

## Simple classes without complex needs

```r
new_simple <- function(x) {
  structure(x, class = "simple")
}

print.simple <- function(x, ...) {
  cat("Simple:", x, "\n")
  invisible(x)
}
```

## Maximum performance needs (rare)

S3 has the lowest overhead of any R OOP system. Only matters in very hot code paths.

## Existing S3 ecosystem contributions

When extending existing S3-based packages. Maintains consistency with ecosystem.

## Quick prototyping

Fast to set up, no dependencies. Can migrate to S7 later if needed.

## Internal classes

Classes only used within a package. Don't need robust external API.

```