mirror of
https://github.com/msberends/AMR.git
synced 2026-03-24 17:22:22 +01:00
4171d5b778
* Modernise messaging infrastructure with cli support
Rewrites message_(), warning_(), stop_() to use cli::cli_inform(),
cli::cli_warn(), and cli::cli_abort() when the cli package is available,
with a fully functional plain-text fallback for environments without cli.
Key changes:
- New cli_to_plain() helper converts cli inline markup ({.fun}, {.arg},
{.val}, {.field}, {.cls}, {.pkg}, {.href}, {.url}, etc.) to readable
plain-text equivalents for the non-cli fallback path
- word_wrap() simplified: drops add_fn, ANSI re-index algorithm, RStudio
link injection, and operator spacing hack; returns pasted input unchanged
when cli is available
- stop_() no longer references AMR_env$cli_abort; uses pkg_is_available()
directly; passes sys.call() objects to cli::cli_abort() call= argument
- Removed add_fn parameter from message_(), warning_(), and word_wrap()
- All call sites across R/ updated: add_fn arguments removed, some paste0-
based string construction converted to cli glue syntax ({.fun as.mo},
{.arg col_mo}, {n} results, etc.)
- cli already listed in Suggests; no DESCRIPTION dependency changes needed
https://claude.ai/code/session_01XHWLohiSTdZvCutwD7ag2b
* Replace {.fun} with {.help} for all exported functions in messaging
All function names referenced via {.fun …} in cli-style messages are
exported in NAMESPACE, so {.help …} is the appropriate markup — it
renders as a clickable help link rather than plain function styling.
https://claude.ai/code/session_01XHWLohiSTdZvCutwD7ag2b
* Qualify all {.help} tags with AMR:: and convert backtick ?func references
- Add AMR:: namespace prefix and trailing () to all {.help} cli markup
so they render as clickable help links (e.g. {.help AMR::as.sir}())
- Convert `?funcname` backtick-quoted help references to {.help AMR::funcname}()
in aa_helper_functions.R, custom_eucast_rules.R, interpretive_rules.R,
key_antimicrobials.R, mo.R, plotting.R, resistance_predict.R, and sir.R
- Skipped `?proportion` in sir_calc.R as 'proportion' is not exported
https://claude.ai/code/session_01XHWLohiSTdZvCutwD7ag2b
* Require cli >= 3.0.0 for cli_inform/cli_warn/cli_abort availability checks
cli_inform, cli_warn, and cli_abort were introduced in cli 3.0.0.
Add min_version = "3.0.0" (as character) to all four pkg_is_available("cli")
checks so older cli versions fall back to base R messaging.
https://claude.ai/code/session_01XHWLohiSTdZvCutwD7ag2b
* Implement cli::code_highlight() for R code examples in messages (issue #191)
Add highlight_code() helper that wraps cli::code_highlight() when cli >= 3.0.0
is available, falling back to plain code otherwise. Apply it to all inline
R code examples embedded in message/warning/stop strings across the package.
Also convert remaining backtick-quoted function and argument references in
messaging calls to proper cli markup: {.help AMR::fn}(), {.arg arg},
{.code expr}, and {.pkg pkg} throughout ab.R, ab_from_text.R, av_from_text.R,
amr_selectors.R, count.R, custom_antimicrobials.R, custom_microorganisms.R,
interpretive_rules.R, mo.R, mo_property.R, sir.R, sir_calc.R.
Fixes #191
https://claude.ai/code/session_01XHWLohiSTdZvCutwD7ag2b
* Fix {.help} markup to use correct cli link format [{.fun fn}](AMR::fn)
Replace all instances of {.help AMR::fn}() (incorrect format with manual
parentheses outside the link) with {.help [{.fun fn}](AMR::fn)} which is
the correct cli hyperlink syntax: the display text [{.fun fn}] renders the
function name with parentheses automatically, and (AMR::fn) is the link target.
Also update the plain-text fallback handler in aa_helper_functions.R to
extract the display text from the [text](topic) markdown link format,
so that non-cli environments show just the function name (e.g. `fn()`),
not the raw link markup.
Dynamic cases in amr_selectors.R and mo_property.R also updated.
https://claude.ai/code/session_01XHWLohiSTdZvCutwD7ag2b
* Add {.topic} markup for non-function help page references
Replace {.code ?AMR-options} and backtick-style ?AMR-options / ?AMR-deprecated
references with proper {.topic AMR-options} / {.topic AMR-deprecated} cli markup
in count.R, interpretive_rules.R, proportion.R, and zz_deprecated.R.
Add {.topic} fallback handler to format_message() in aa_helper_functions.R:
plain-text environments render {.topic foo} as ?foo, and the [text](topic)
link form extracts just the display text (same pattern as {.help}).
Also convert remaining backtick function/arg references in proportion.R to
{.help [{.fun ...}](AMR::...)}, {.arg}, and {.code} markup for consistency.
Note: zzz.R intentionally keeps the backtick form since its startup message
goes through packageStartupMessage() which bypasses our cli infrastructure.
https://claude.ai/code/session_01XHWLohiSTdZvCutwD7ag2b
* Fix {.topic} to use required pkg::topic format with display text
{.topic} in cli requires a package-qualified topic reference to generate
a valid x-r-help:pkg::topic URI. Bare {.topic AMR-options} produced a
malformed x-r-help:AMR-options URI (no package prefix).
Use the [display_text](pkg::topic) form throughout:
{.topic [AMR-options](AMR::AMR-options)}
{.topic [AMR-deprecated](AMR::AMR-deprecated)}
The hyphen in the topic name is fine as a URI string even though
AMR::AMR-options is not a valid R symbol expression.
The fallback handler in format_message() already handles the [text](uri)
form by extracting the display text, so plain-text output is unchanged.
https://claude.ai/code/session_01XHWLohiSTdZvCutwD7ag2b
* Fix regexec() calls: remove perl=TRUE unsupported in older R
regexec() only gained the perl argument in R 4.1.0. The CI matrix
covers oldrel-1 through oldrel-4 (R 3.x/4.0.x), so perl=TRUE caused
an 'unused argument' error on every message_() call in those
environments.
All four affected regexec() calls use POSIX-extended compatible
patterns, so dropping perl=TRUE is safe.
https://claude.ai/code/session_01XHWLohiSTdZvCutwD7ag2b
* Slim CI matrix for PRs to ubuntu-latest / r-release only
For pull requests, check-recent now runs a single job (ubuntu-latest,
r-release) via a setup job that emits the matrix as JSON. On push and
schedule the full matrix is unchanged (devel + release on all OSes,
oldrel-1 through oldrel-4).
Also removed the pull_request trigger from check-recent-dev-pkgs; the
dev-packages check only needs to run on push/schedule.
https://claude.ai/code/session_01XHWLohiSTdZvCutwD7ag2b
* Restrict dev-versions and old-tinytest CI to main branch only
Both workflows were triggering on every push to every branch.
Narrowed push trigger to [main] so they only run after merging,
not on every feature/PR branch push.
https://claude.ai/code/session_01XHWLohiSTdZvCutwD7ag2b
* Update NEWS.md to continuous log + add concise style rules to CLAUDE.md
NEWS.md is now a single continuous log under one heading per dev series,
not a new section per version bump. CLAUDE.md documents: only replace
line 1 (heading), append new entries, keep them extremely concise with
no trailing full stop.
Merged 9035 and 9036 entries into one section; condensed verbose 9036
bullets; added CI workflow change entry.
https://claude.ai/code/session_01XHWLohiSTdZvCutwD7ag2b
* Replace single-quoted literals in messaging calls with cli markup
Converted bare 'value' strings inside stop_(), warning_(), message_()
to appropriate cli markup:
- {.val}: option values ('drug', 'dose', 'administration', 'SDD', 'logbook')
- {.cls}: class names ('sir', 'mo')
- {.field}: column names ('mo' in mo_source)
- {.code}: object/dataset names ('clinical_breakpoints')
Files changed: ab_from_text.R, av_from_text.R, sir.R, sir_calc.R, mo_source.R
https://claude.ai/code/session_01XHWLohiSTdZvCutwD7ag2b
* Apply {.topic}, {.cls}, and {.field} markup in sir.R messaging
- 'clinical_breakpoints' (dataset): {.code} -> {.topic [clinical_breakpoints](AMR::clinical_breakpoints)}
- "is of class" context: extract bad_col/bad_cls/exp_cls vars and use {.cls} + {.field} in glue syntax
- Column references in as.sir() messages: font_bold(col) with surrounding quotes -> {.field {col}}
https://claude.ai/code/session_01XHWLohiSTdZvCutwD7ag2b
* Replace glue-style dynamic markup with paste0() construction
{.field {variable}} and {.cls {variable}} patterns rely on glue
evaluation which is not safe in a zero-dependency package. Replace
all four occurrences with paste0("{.field ", var, "}") so the value
is baked into the markup string before reaching message_()/stop_().
https://claude.ai/code/session_01XHWLohiSTdZvCutwD7ag2b
* Limit push trigger to main in check-recent workflow
push: branches: '**' caused both the push event (9-worker matrix) and
the pull_request event (1-worker matrix) to fire simultaneously on every
PR commit. Restricting push to [main] means PR pushes only trigger the
pull_request path (1 worker), while direct pushes to main still get the
full 9-worker matrix.
https://claude.ai/code/session_01XHWLohiSTdZvCutwD7ag2b
* Limit push trigger to main in code-coverage workflow
Same fix as check-recent: push: branches: '**' caused the workflow to
run twice per PR commit (once for push, once for pull_request). Restricting
push to [main] ensures coverage runs only once per PR update.
https://claude.ai/code/session_01XHWLohiSTdZvCutwD7ag2b
* Replace bare backticks with cli inline markup across all messaging calls
- {.arg} for argument names in stop_/warning_/message_ calls
- {.cls} after "of class" text in format_class() and elsewhere
- {.fun} for function names (replaces `fn()` pattern)
- {.pkg} for tidyverse package names (dplyr, ggplot2)
- {.code} for code literals (TRUE, FALSE, expressions)
- Rewrite print.ab: use cli named-vector with * bullets and code
highlighting when cli >= 3.0.0; keep plain-text fallback otherwise
- Fix typo in as.sir(): "of must be" -> "or must be"
- switch sir.R verbose notes from message() to message_()
https://claude.ai/code/session_01XHWLohiSTdZvCutwD7ag2b
* Pre-evaluate inline expressions, add format_inline_(), fix print.ab
- All bare {variable}/{expression} in message_()/warning_()/stop_() calls
are now pre-evaluated via paste0(), so users without cli/glue never see
raw template syntax (mo_source.R, first_isolate.R, join_microorganisms.R,
antibiogram.R, atc_online.R)
- Add format_inline_() helper: formats a cli-markup string and returns it
(not emits it), using cli::format_inline() when available and cli_to_plain()
otherwise
- Rewrite .onAttach to use format_inline_() for all packageStartupMessage
calls; also adds {.topic} link and {.code} markup for option names
- print.ab: pre-evaluate function_name via paste0 (no .envir needed),
apply highlight_code() to each example bullet for R syntax highlighting
- join_microorganisms: pre-evaluate {type} and {nrow(...)} expressions
https://claude.ai/code/session_01XHWLohiSTdZvCutwD7ag2b
* fixes
* Replace all "in \`funcname()\`:" with {.help [{.fun funcname}](AMR::funcname)}
Converts all "in `funcname()`:" prefixes in warning_()/message_()/stop_()
calls to the full {.help} link format for clickable help in supported
terminals. Also fixes adjacent backtick argument names to {.arg}.
Files changed: ab.R, ab_property.R, av.R, av_property.R, antibiogram.R,
key_antimicrobials.R, mdro.R, mic.R, mo.R, plotting.R
https://claude.ai/code/session_01XHWLohiSTdZvCutwD7ag2b
* fixes
* definitive
* version fix
---------
Co-authored-by: Claude <noreply@anthropic.com>
189 lines
7.8 KiB
Markdown
189 lines
7.8 KiB
Markdown
# 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
|
||
|
||
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
|
||
|
||
Run the following from the repo root to determine the version string to use:
|
||
|
||
```bash
|
||
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$')
|
||
currentcommit=$(git rev-list --count ${currenttagfull}..${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, append the new change as a bullet under the appropriate sub-heading (`### New`, `### Fixes`, or `### Updates`).
|
||
|
||
Style rules for `NEWS.md` entries:
|
||
- Be **extremely concise** — one short line per item
|
||
- Do **not** end with a full stop (period)
|
||
- No verbose explanations; just the essential fact
|
||
|
||
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.
|