AMR/CLAUDE.md

# CLAUDE.md — AMR R Package

This file provides context for Claude Code when working in this repository.

## Project Overview

**AMR** is a zero-dependency R package for antimicrobial resistance (AMR) data analysis using a One Health approach. It is peer-reviewed, used in 175+ countries, and supports 28 languages.

Key capabilities:
- SIR (Susceptible/Intermediate/Resistant) classification using EUCAST 2011–2025 and CLSI 2011–2025 breakpoints
- Antibiogram generation: traditional, combined, syndromic, and WISCA
- Microorganism taxonomy database (~79,000 species)
- Antimicrobial drug database (~620 drugs)
- Multi-drug resistant organism (MDRO) classification
- First-isolate identification
- Minimum Inhibitory Concentration (MIC) and disk diffusion handling
- Multilingual output (28 languages)

## Common Commands

All commands run inside an R session:

```r
# Rebuild documentation (roxygen2 → .Rd files + NAMESPACE)
devtools::document()

# Run all tests
devtools::test()

# Full package check (CRAN-level: docs + tests + checks)
devtools::check()

# Build pkgdown website locally
pkgdown::build_site()

# Code coverage report
covr::package_coverage()
```

From the shell:

```bash
# CRAN check from parent directory
R CMD check AMR
```

## Repository Structure

```
R/              # All R source files (62 files, ~28,000 lines)
man/            # Auto-generated .Rd documentation (do not edit manually)
tests/testthat/ # testthat test files (test-*.R) and helper-functions.R
data/           # Pre-compiled .rda datasets
data-raw/       # Scripts used to generate data/ files
vignettes/      # Rmd vignette articles
inst/           # Installed files (translations, etc.)
_pkgdown.yml    # pkgdown website configuration
```

## R Source File Conventions

**Naming conventions in `R/`:**

| Prefix/Name | Purpose |
|---|---|
| `aa_*.R` | Loaded first (helpers, globals, options, package docs) |
| `zz_deprecated.R` | Deprecated function wrappers |
| `zzz.R` | `.onLoad` / `.onAttach` initialization |

**Key source files:**

- `aa_helper_functions.R` / `aa_helper_pm_functions.R` — internal utility functions (large; ~63 KB and ~37 KB)
- `aa_globals.R` — global constants and breakpoint lookup structures
- `aa_options.R` — `amr_options()` / `get_AMR_option()` system
- `mo.R` / `mo_property.R` — microorganism lookup and properties
- `ab.R` / `ab_property.R` — antimicrobial drug functions
- `av.R` / `av_property.R` — antiviral drug functions
- `sir.R` / `sir_calc.R` / `sir_df.R` — SIR classification engine
- `mic.R` / `disk.R` — MIC and disk diffusion classes
- `antibiogram.R` — antibiogram generation (traditional, combined, syndromic, WISCA)
- `first_isolate.R` — first-isolate identification algorithms
- `mdro.R` — MDRO classification (EUCAST, CLSI, CDC, custom guidelines)
- `amr_selectors.R` — tidyselect helpers for selecting AMR columns
- `interpretive_rules.R` / `custom_eucast_rules.R` — clinical interpretation rules
- `translate.R` — 28-language translation system
- `ggplot_sir.R` / `ggplot_pca.R` / `plotting.R` — visualisation functions

## Custom S3 Classes

The package defines five S3 classes with full print/format/plot/vctrs support:

| Class | Created by | Represents |
|---|---|---|
| `<mo>` | `as.mo()` | Microorganism code |
| `<ab>` | `as.ab()` | Antimicrobial drug code |
| `<av>` | `as.av()` | Antiviral drug code |
| `<sir>` | `as.sir()` | SIR value (S/I/R/SDD) |
| `<mic>` | `as.mic()` | Minimum inhibitory concentration |
| `<disk>` | `as.disk()` | Disk diffusion diameter |

## Data Files

Pre-compiled in `data/` (do not edit directly; regenerate via `data-raw/` scripts):

| File | Contents |
|---|---|
| `microorganisms.rda` | ~79,000 microbial species with full taxonomy |
| `antimicrobials.rda` | ~620 antimicrobial drugs with ATC codes |
| `antivirals.rda` | Antiviral drugs |
| `clinical_breakpoints.rda` | EUCAST + CLSI breakpoints (2011–2025) |
| `intrinsic_resistant.rda` | Intrinsic resistance patterns |
| `example_isolates.rda` | Example AMR dataset for documentation/testing |
| `WHONET.rda` | Example WHONET-format dataset |

## Zero-Dependency Design

The package has **no `Imports`** in `DESCRIPTION`. All optional integrations (ggplot2, dplyr, data.table, tidymodels, cli, crayon, etc.) are listed in `Suggests` and guarded with:

```r
if (requireNamespace("pkg", quietly = TRUE)) { ... }
```

Never add packages to `Imports`. If new functionality requires an external package, add it to `Suggests` and guard usage appropriately.

## Testing

- **Framework:** `testthat` (R ≥ 3.1); legacy `tinytest` used for R 3.0–3.6 CI
- **Test files:** `tests/testthat/test-*.R`
- **Helpers:** `tests/testthat/helper-functions.R`
- **CI matrix:** GitHub Actions across Windows / macOS / Linux × R devel / release / oldrel-1 through oldrel-4
- **Coverage:** `covr` (some files excluded: `atc_online.R`, `mo_source.R`, `translate.R`, `resistance_predict.R`, `zz_deprecated.R`, helper files, `zzz.R`)

## Documentation

- All exported functions use **roxygen2** blocks (`RoxygenNote: 7.3.3`, markdown enabled)
- Run `devtools::document()` after any change to roxygen comments
- Never edit files in `man/` directly — they are auto-generated
- Vignettes live in `vignettes/` as `.Rmd` files
- The pkgdown website is configured in `_pkgdown.yml`

## Versioning

Version format: `major.minor.patch.dev` (e.g., `3.0.1.9021`)

- Development versions use a `.9xxx` suffix
- Stable CRAN releases drop the dev suffix (e.g., `3.0.1`)
- `NEWS.md` uses sections **New**, **Fixes**, **Updates** with GitHub issue references (`#NNN`)

### Version and date bump required for every PR

Before opening a pull request, always increment the four-digit dev counter by 1 in **both** of these files:

1. **`DESCRIPTION`** — the `Version:` field:
   ```
   Version: 3.0.1.9021  →  Version: 3.0.1.9022
   ```

2. **`NEWS.md`** — the top-level heading:
   ```
   # AMR 3.0.1.9021  →  # AMR 3.0.1.9022
   ```

Read the current version from `DESCRIPTION`, add 1 to the last numeric component, and write the new version to both files in the same commit as the rest of the PR changes.

Also bump the date to the current date in **`DESCRIPTION`**, where it's in the `Date:` field in ISO format:

```
Date: 2025-12-31
```

## Internal State

The package uses a private `AMR_env` environment (created in `aa_globals.R`) for caching expensive lookups (e.g., microorganism matching scores, breakpoint tables). This avoids re-computation within a session.