R

# R Programming Language Instructions

Purpose

Help GitHub Copilot generate idiomatic, safe, and maintainable R code across projects.

Core Conventions

- **Match the project’s style.** If the file shows a preference (tidyverse vs. base R, `%>%` vs. `|>`), follow it.

- **Prefer clear, vectorized code.** Keep functions small and avoid hidden side effects.

- **Qualify non-base functions in examples/snippets**, e.g., `dplyr::mutate()`, `stringr::str_detect()`. In project code, using `library()` is acceptable when that’s the repo norm.

- **Naming:** `lower_snake_case` for objects/files; avoid dots in names.

- **Side effects:** Never call `setwd()`; prefer project-relative paths (e.g., `here::here()`).

- **Reproducibility:** Set seeds locally around stochastic operations using `withr::with_seed()`.

- **Validation:** Validate and constrain user inputs; use typed checks and allowlists where possible.

- **Safety:** Avoid `eval(parse())`, unvalidated shell calls, and unparameterized SQL.

Pipe Operators

- **Native pipe `|>` (R ≥ 4.1.0):** Prefer in R ≥ 4.1 (no extra dependency).

- **Magrittr pipe `%>%`:** Continue using in projects already committed to magrittr or when you need features like `.`, `%T>%`, or `%$%`.

- **Be consistent:** Don't mix `|>` and `%>%` within the same script unless there's a clear technical reason.

Performance Considerations

- **Large datasets:** consider `data.table`; benchmark with your workload.

- **dplyr compatibility:** Use `dtplyr` to write dplyr syntax that translates to data.table operations automatically for performance gains.

- **Profiling:** Use `profvis::profvis()` to identify performance bottlenecks in your code. Profile before optimizing.

- **Caching:** Use `memoise::memoise()` to cache expensive function results. Particularly useful for repeated API calls or complex computations.

- **Vectorization:** Prefer vectorized operations over loops. Use `purrr::map_*()` family or `apply()` family for remaining iteration needs.

Tooling & Quality

- **Formatting:** `styler` (tidyverse style), two-space indents, ~100-char lines.

- **Linting:** `lintr` configured via `.lintr`.

- **Pre-commit:** consider `precommit` hooks to lint/format automatically.

- **Docs:** roxygen2 for exported functions (`@param`, `@return`, `@examples`).

- **Tests:** prefer small, pure, composable functions that are easy to unit test.

- **Dependencies:** manage with `renv`; snapshot after adding packages.

- **Paths:** prefer `fs` and `here` for portability.

Data Wrangling & I/O

- **Data frames:** prefer tibbles in tidyverse-heavy files; otherwise base `data.frame()` is fine.

- **Iteration:** use `purrr` in tidyverse code. In base-style code, prefer type-stable, vectorized patterns such as `vapply()`

(for atomic outputs) or `Map()` (for elementwise operations) instead of explicit `for` loops when they improve clarity or performance.

- **Strings & Dates:** use `stringr`/`lubridate` where already present; otherwise use clear base helpers (e.g., `nchar()`, `substr()`, `as.Date()` with explicit format).

- **I/O:** prefer explicit, typed readers (e.g., `readr::read_csv()`); make parsing assumptions explicit.

Plotting

- Prefer `ggplot2` for publication-quality plots. Keep layers readable and label axes and units.

Error Handling

- In tidyverse contexts, use `rlang::abort()` / `rlang::warn()` for structured conditions; in base-only code, use `stop()` / `warning()`.

- For recoverable operations:

- Use `purrr::possibly()` when you want a typed fallback value of the same type (simpler).

- Use `purrr::safely()` when you need to capture both results and errors for later inspection or logging.

- Use `tryCatch()` in base R for fine-grained control or compatibility with non-tidyverse code.

- Prefer consistent return structures—typed outputs for normal flows, structured lists only when error details are required.

Security Best Practices

- **Command execution:** Prefer `processx::run()` or `sys::exec_wait()` ov