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:

# 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:

# 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

Code Style

Follow the tidyverse style guide precisely. Key rules:

• 2-space indentation; no tabs
• <- for assignment, not =
• Spaces around all binary operators and after commas; no spaces inside parentheses
• When a function call must break across lines, place the first argument on a new line indented by 2 spaces, and put the closing ) on its own line — never align arguments to the opening parenthesis (no hanging/forced mid-line indentation)

# good
stop_(
  "some long message part one ",
  "part two"
)

# bad — forces indentation to match the opening parenthesis
stop_("some long message part one ",
      "part two")

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:

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 follows the style of the v3.0.0 section; see NEWS.md style below

NEWS.md style

Each version section follows the v3.0.0 section of NEWS.md:

• After the # AMR <version> heading, an optional line on the planned release, then a short intro paragraph summarising the main changes in plain prose
• Sub-headings, in this order and only when they have content: ### Breaking, ### New, ### Changed, ### Other
• Breaking: changes that can alter results or break existing code (renamed or removed arguments, options or values, changed return values, new requirements); explain what changed and how to get the old behaviour
• New: new functions, arguments, data sets, columns, selectors, antimicrobials and breakpoints, grouped under bold thematic bullets (e.g. * **Updated clinical breakpoints**) with nested bullets beneath; end with a * **Other** group for items that fit no theme
• Changed: improvements and bug fixes together (there is no separate fixes section), grouped by function or data set as a plain parent bullet (e.g. * SIR interpretation (`as.sir()`), * `microorganisms` data set) with nested bullets beneath; items that fit no group are single top-level bullets at the end
• Other: documentation, vignettes, website, contributors and console output
• Each function or data set gets exactly one group; never scatter entries for the same function (e.g. as.mo()) across the section
• Bug fixes start with "Fixed ..." or state the corrected behaviour (e.g. "now returns NA with a warning instead of an error")
• Write descriptive, complete sentences, in British English; a single-sentence bullet has no final full stop, a bullet of several sentences ends with one
• Use "e.g.," and "i.e.,", backticks for code, functions with (), and italics for taxonomic names
• Add GitHub issue references at the end of the item, as (#NNN) or (#NNN, #NNN)
• Never use em dashes

Local commits on main: never touch the version number

When committing directly on main in a local clone, never edit the Version: or Date: field in DESCRIPTION, nor line 1 of NEWS.md, and do not add a version prefix to the commit message. The git hooks in .github/prehooks/ do this on every commit to main: pre-commit sets the version (commit count since the last tag + 9001) and date in DESCRIPTION and line 1 of NEWS.md, and commit-msg prepends (vX.Y.Z.9NNN) to the commit message. Adding NEWS bullets is still allowed. The section below applies only to PRs.

Version and date bump required for every PR

All PRs are squash-merged, so each PR lands as exactly one commit on the default branch. Version numbers are kept in sync with the cumulative commit count since the last released tag. Therefore exactly one version bump is allowed per PR, regardless of how many intermediate commits are made on the branch.

Computing the correct version number

First, ensure git and gh are installed — both are required for the version computation and for pushing changes. Install them if missing before doing anything else:

which git || apt-get install -y git
which gh   || apt-get install -y gh
# Also ensure all tags are fetched so git describe works
git fetch --tags

Then run the following from the repo root to determine the version string to use:

currenttag=$(git describe --tags --abbrev=0 | sed 's/v//')
currenttagfull=$(git describe --tags --abbrev=0)
defaultbranch=$(git branch | cut -c 3- | grep -E '^master$|^main$')
git fetch origin ${defaultbranch} --quiet
currentcommit=$(git rev-list --count ${currenttagfull}..origin/${defaultbranch})
currentversion="${currenttag}.$((currentcommit + 9001 + 1))"
echo "$currentversion"

The + 1 accounts for the fact that this PR's squash commit is not yet on the default branch. Set both of these files to the resulting version string (and only once per PR, even across multiple commits):

1. DESCRIPTION — the Version: field
2. NEWS.md — only replace line 1 (the # AMR <version> heading) with the new version number; do not create a new section. NEWS.md is a continuous log for the entire current x.y.z.9nnn development series: all changes since the last stable release accumulate under that single heading. After updating line 1, add the new change to the appropriate sub-heading and group, following NEWS.md style above. If the change belongs to an existing group (e.g. as.mo()), add it there or amend the existing bullet instead of adding a new top-level bullet.

If git describe fails (e.g. no tags exist in the environment), fall back to reading the current version from DESCRIPTION and adding 1 to the last numeric component — but only if no bump has already been made in this PR.

Date field

The Date: field in DESCRIPTION must reflect the date of the last commit to the PR (not the first), in ISO format. Update it with every commit so it is always current:

Date: 2026-03-07

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.