mirror of
https://github.com/msberends/AMR.git
synced 2026-11-16 02:20:49 +01:00
- the list of known defects is development data and must not ship with the package - tests read it from the source repository; mo_repository_root() now walks up from the working directory, so the tests also find the repository from an R CMD check directory inside it (GitHub Actions) - the integrity, known-defects and sentinel tests skip when the source repository is not available - CLAUDE.md: on local commits to main, the git hooks set the version number and date Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
46 lines
3.9 KiB
Markdown
46 lines
3.9 KiB
Markdown
# MO code registry
|
|
|
|
MO codes (such as `B_ESCHR_COLI`) are stored by users in their own data, sometimes for years. A code must
|
|
therefore **always mean the same taxon**, in every future version of the AMR package. This folder contains
|
|
the registry that guarantees this.
|
|
|
|
## Files
|
|
|
|
| File | Contents |
|
|
|---|---|
|
|
| `mo_code_registry.csv` | Every MO code that was ever part of a **released** version of the AMR package since v2.0.0, with the taxon it denotes (name, rank, domain, genus, species, subspecies), the first and last release it was in, and older names of the same code (e.g. a corrected spelling). |
|
|
| `build_mo_code_registry.R` | Recreates `mo_code_registry.csv` from the git tags of all releases. Run it after every new release. |
|
|
| `mo_code_renames.csv` | The only allowed exceptions: registered codes that get another name, because it is the same taxon (e.g. a corrected spelling or a renamed species group). Every row needs `approved_by` and `approved_date`. |
|
|
| `mo_code_retirements.csv` | Registered codes that are retired on purpose, because their taxon was another organism (e.g. the *Graphium* butterflies, which were wrongly in the Fungi until v3.0.1). Written by the taxonomy build, with the reason; `as.mo()` translates these codes to `NA` with that reason. Every new row must be reviewed in the git diff. |
|
|
| `microorganisms_known_defects.csv` | Known defects of the `microorganisms` data set on the main branch, so that the unit tests fail on every new defect. This list may only become shorter, and the file must be deleted once it is empty (after the next taxonomy rebuild). The tests that use it only run in the source repository. |
|
|
|
|
## Rules
|
|
|
|
1. **Only releases count.** Development versions (the main branch) are never part of the registry. Codes that
|
|
only existed in a development version carry no weight and may be reassigned.
|
|
2. **Codes from before v2.0.0 are not supported.** Decision by Matthijs S. Berends, 3 October 2026: MO codes
|
|
from releases before v2.0.0 (12 March 2023) are not supported. Every code in all releases since v2.0.0 has
|
|
always meant the same taxon (checked on 3 October 2026), so the registry starts without conflicts.
|
|
3. **A registered code is never given to another taxon.** The taxonomy build
|
|
(`data-raw/_reproduction_scripts/reproduction_of_microorganisms.R`) reuses the code of every taxon in the
|
|
registry (most recent release first), never gives a registered code to a new taxon, and stops if a
|
|
registered code would get another name than in the registry, unless that is listed and approved in
|
|
`mo_code_renames.csv`.
|
|
4. **A released taxon is never removed.** Decision by Matthijs S. Berends, 3 October 2026. If a released taxon is
|
|
missing in a new build (e.g. not validly published or not clinically relevant anymore), the build restores it
|
|
from its last release, with its old code and last known status. The only exception are retired codes (see
|
|
`mo_code_retirements.csv`).
|
|
5. **A registered code that is no longer in the data still works.** `as.mo()` translates it to the current
|
|
code of the same taxon (by its name, so also if the taxon moved to another domain), using an internal lookup
|
|
table (`MO_RETIRED_CODES`) that is created from the registry in `data-raw/_pre_commit_checks.R`. If the
|
|
taxon is no longer in the data at all, the result is `NA` with a warning. The package never guesses.
|
|
6. **Tests enforce all of this.** `tests/testthat/test-data-microorganisms.R` checks the current data against
|
|
the registry and the renames, and checks that every registered code resolves to its own taxon.
|
|
|
|
## After a release
|
|
|
|
1. Make sure the git tag of the release exists (e.g. `v3.1.0`).
|
|
2. Run `source("data-raw/microorganisms_files/build_mo_code_registry.R")` from the root of the repository.
|
|
3. Review the changes to `mo_code_registry.csv` (`git diff`): only new codes may be added, and existing codes
|
|
may only get a later `last_release`. Commit the result.
|