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:
+ +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 configurationR 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:
+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); legacytinytestused 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.Rmdfiles
+ - 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
.9xxxsuffix
+ - Stable CRAN releases drop the dev suffix (e.g.,
3.0.1)
+ -
+
NEWS.mduses sections New, Fixes, Updates with GitHub issue references (#NNN)
+
Version bump required for every PR
+Before opening a pull request, always increment the four-digit dev counter by 1 in both of these files:
+-
+
+DESCRIPTION— theVersion:field:
+Version: 3.0.1.9021 → Version: 3.0.1.9022
+ -
+
+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.
