mizer is an R package for dynamic multi-species size-spectrum modelling of fish communities.
MizerParams (S3) — central object passed to nearly all functions. Stored as a list with class "MizerParams" (or c(extensions, "MizerParams")). Slots/fields are accessible via @ and @<- for full backwards compatibility or via standard $ and [[]]. Modified via setter functions that return new copies: setFishing(params, ...), etc.
MizerSim (S3) — stores simulation output: arrays n (time × species × size), n_pp, n_other, effort, and the MizerParams used. Accessible via @ / $ / [[]].
ArraySpeciesBySize / ArrayTimeBySpecies / ArrayTimeBySpeciesBySize / ArrayTimeByResourceBySize / ArrayResourceBySize (S3) — wrap some arrays with metadata. Follow .claude/skills/array-wrapper-classes.md.
species_params / given_species_params / gear_params (S3) — parameter tables subclassing data.frame stored in params elements. Users should access/modify these tables via S3 generics (e.g. species_params(params) or gear_params(params)), but package code and developers can modify elements directly (e.g. params$species_params or params@species_params) when appropriate. Editing one of these tables on its own does nothing but edit it: the subclass is preserved (by the base data.frame methods — there are deliberately no [<-, $<- or [[<- methods), and no validation, conversion or warning happens. The checks and conversions (misspelled column names, length-to-weight, consistency) run when the table is validated, which is what species_params()/gear_params() do to a plain data frame and what species_params<-()/gear_params<-() do to the table they are given. The length/weight precedence rule is a consequence of this; see inst/skills/change-parameters/SKILL.md.
given_species_params holds what the user supplied plus the defaults of any function argument that sets a species parameter (e.g. n and p from newMultispeciesParams()), even when the user did not override the argument; defaults that are not function arguments stay out of it.
resource_params — a plain named list (not a classed table) of the resource scalars kappa, lambda, n, w_pp_cutoff, and optionally r_pp, a, b. Assigning with resource_params(params) <- validates them and rebuilds cc_pp/rr_pp without balancing; editing params@resource_params directly leaves those arrays stale. See inst/skills/change-parameters/SKILL.md.
Customisable rate functions: users replace rate functions by storing a custom function name in params@rates_funcs. Dispatch via get(params@rates_funcs$FunctionName)(params, ...).
Two quadrature schemes: the second_order_w slot selects how the model is discretised on the size grid — flux picks the advective reconstruction, and bin_average decides whether size-dependent factors are integrated over their bin or point-sampled at the left bin boundary. The default follows the model's defaults edition (default_second_order_w()): editions 1 and 2 default to the first-order scheme, so previous mizer versions reproduce byte-for-byte, and edition 3 defaults to second order. The test fixtures are of edition 1, so this is invisible in the code you are likely to be reading: a function that ignores bin_average still looks correct and still passes its tests on the default path. Anything that integrates over the size grid must handle both schemes and be tested under both.
Defaults editions: a model records in its defaults_edition slot the edition that was active when it was created. Code that chooses a default by edition must read the model's edition, defaults_edition(params). The bare defaults_edition() is the active edition, and only the code that creates a new model (emptyParams(), and before a model exists validGearParams() and the wrapper constructors' resolve_second_order_w() call) may use it; elsewhere it makes an existing model change its defaults when the user switches edition. A function that builds a new model as a step in changing an existing one (addSpecies(), adjustSizeGrid()) wraps that build in with_defaults_edition(defaults_edition(params), ...).
Gated validation: validParams() splits into three jobs — upgrade (gated on the version string), repair plus validObject() (gated on a fingerprint), and the unconditional is.finite() scans of the rate arrays. The fingerprint, validation_key(), is a hash of every slot that repair_params() reads or writes and every slot that validMizerParams() inspects, taking only the dimensions and dimension names of the big rate arrays, never their values. It is recalculated on every call and never stored on the object, so it cannot go stale. This gate stays sound only as long as that correspondence holds: if you make repair_params() or validMizerParams() depend on a slot, add that slot to validation_key(), or the new logic will be silently skipped for objects mizer has already seen. Values inside the rate arrays are deliberately out of the fingerprint and are guarded by check_finite() instead.
Auto-generated files — never edit NAMESPACE, man/, RcppExports.R, or RcppExports.cpp directly. The vignettes/guide-*.Rmd articles are also generated: their single source is inst/skills/<topic>/SKILL.md, which doubles as the agent skill. Edit the skill and re-run source("dev_scripts/build_guides.R"); build_guides(). Content that belongs in the skill but not in the article (an agent's diagnostic procedure, a lookup table keyed by symptom rather than by topic) goes in an <!-- agent-only --> block, which the generator drops. Likewise docs/llms.txt and inst/llms.txt are generated: pkgdown writes a raw docs/llms.txt during build_site(), and source("dev_scripts/build_llms.R"); build_llms() then swaps its README-derived preamble for pkgdown/llms-header.md — the file to edit — and copies the result to inst/llms.txt. That installed copy is how mizerAgents::setup_mizer_agent() points an agent at the API index for the mizer it has, so it must ship: do not add it to .Rbuildignore. Follow .claude/skills/build-documentation.md.
Articles with pre-computed results — vignettes/discontinuous_rates.Rmd and vignettes/dynamic_stability.Rmd would each take many minutes to knit, so their long-running calculations live in dev_scripts/save_<article>.R, which writes vignettes/<article>.rds. The article loads that file in its setup chunk, shows the expensive code with eval = FALSE, and displays the saved objects from a following echo = FALSE chunk. The script and the article therefore hold the same code twice: change one and you must change the other and re-run the script, or the article will show numbers that its own code no longer produces. Save small objects — a rate array or a summary data frame, not a MizerSim; plotBiomass(sim) is plot(getBiomass(sim)), and the biomass array carries everything the plot needs.
Before modifying, designing, or debugging core features, consult the design intent, mathematical formulations, and user-facing workflows documented in inst/skills/:
| When working on... | Consult skill |
|---|---|
| Modifying parameter accessors, downward propagation, rate setters, or freeze mechanisms | inst/skills/change-parameters/SKILL.md |
Calibration functions (tuneSteadyState, calibrateBiomass, matchGrowth), steady states, or reproduction levels |
inst/skills/calibrate-model/SKILL.md |
Extension points (setExtEncounter, setExtMort, setComponent, setRateFunction) |
inst/skills/extend-mizer/SKILL.md |
Packaging an extension: S3 extension classes, recordExtension(), NextMethod() dispatch, bundled data, upgrading saved objects |
inst/skills/create-extension-package/SKILL.md |
| Using extension packages, or saving/reading params and sim objects | inst/skills/use-extension-packages/SKILL.md |
Model constructors (newMultispeciesParams, etc.), size grids, or allometric defaults |
inst/skills/build-model/SKILL.md |
Fishing gears, selectivity functions, catchability, or gear_params |
inst/skills/set-up-fishing/SKILL.md |
| Simulation stepping, projection methods, or effort scenarios | inst/skills/run-simulation/SKILL.md |
Stability analysis, limit cycles, the solver argument, or getStability |
inst/skills/analyse-stability/SKILL.md |
| Summary or plotting functions | inst/skills/analyse-and-plot/SKILL.md |
| Renaming/deprecating arguments, changing defaults, or investigating breaking changes | inst/skills/upgrade-mizer-code/SKILL.md |
- Indentation: 4 spaces
- Naming: camelCase or snake_case for functions/variables; PascalCase for classes
- Language: British English (en-GB) — "colour", "behaviour", "modelling"
- When documenting a mizer S3 generic whose methods share a man page (combined with
@rdname/@name), follow the steps in.claude/skills/document-s3-generics.md. - When adding, moving or removing a species parameter default, follow
.claude/skills/species-param-defaults.md. A default belongs to the rate setter that reads the parameter; only parameters that no single rate setter owns are defaulted centrally. - When writing anything that integrates over the size grid — a summary or indicator function, a diagnostic derived from a rate, a rate setter with a size-dependent parameter — follow
.claude/skills/size-grid-integrals.md. Each bin integral is performed in exactly one place, so a size-dependent factor is bin-averaged where its integral is performed and nowhere else; doing it twice is a silent uniform error. - When mizer code needs to tell the user something — a default filled in, an input adjusted, an instruction that could not be carried out — follow
.claude/skills/info-signals.md. Raise it withsignal_info()and friends, never a plainmessage()orwarning(): those ignoreinfo_level, are not collected with the other reports, and are swallowed by thesuppressMessages()on thespecies_params<-()path. Progress reports, deprecations and argument errors are the deliberate exceptions.
- Run
devtools::load_all()before running tests - Run only relevant tests with
devtools::test(filter = "pattern"). Running all tests is too slow. - Never compare two rate arrays with
identical(). The freeze mechanism writes acommentattribute onto an array that has been set by hand, so two arrays holding the same numbers compare unequal whenever one of them has been through a setter. This reports a difference where there is none and has already produced a wrong conclusion about whether a setter argument works. Compare values:all.equal()after stripping attributes down todim, orall.equal(..., check.attributes = FALSE). The internaldifferent()(R/helpers.R:14) is the in-package form of this. - Use
expect_doppelganger()(vdiffr) for plot tests, and snapshot tests for complex outputs - When snapshot tests fail because values legitimately changed, run
testthat::snapshot_accept()to promote the.new.mdfiles into the canonical.mdsnapshots. - Run
devtools::document()after adding or changing exports - Lint a file with
lintr::lint() - After editing C++ source:
devtools::clean_dll(); devtools::load_all() - After modifying the
MizerParamsorMizerSimclass (new/removed slots, changes to@rates_funcs, etc.), follow the steps in.claude/skills/upgrade-mizer-data.md. - Tests go in the file named after the R file that defines the function under test — not one named after the feature. Before adding a test, or any new test file, follow
.claude/skills/test-organisation.md. - Use the shared
_smallfixtures fromhelper.R; never a top-leveldata()call, astestthat 3.xshares.GlobalEnvacross all tests. The fixtures give 3 species and 4 time steps, so any hardcoded species or time index must be valid for that. For the full catalogue, for adding a fixture, and for the parallel and experimental-test settings, see.claude/skills/test-fixtures.md.
- After adding a new file under
R/, add it to theCollate:field inDESCRIPTION(roxygen2 does not manage this automatically in this package). - After adding or renaming exported functions, add them to the
appropriatesection inpkgdown/_pkgdown.ymlso they appear on the reference page of the website. - Update
NEWS.mdwhen adding features or fixing bugs. - If the change can alter the behaviour of code users have already written — a renamed or removed argument, a changed default, a deprecation — also record it in the
upgrade-mizer-codeskill, which is split in two: the prose goes ininst/skills/upgrade-mizer-code/references/mizer-<version>.mdfor the release being prepared (create the file for a new release; the generator orders them by version), and a row goes in the agent-only symptom index in itsSKILL.md, giving the symptom a user would actually see and naming the section heading verbatim. If the change emits a message, quote a literal run of it in the row as`"..."`— that is the string the user will paste.build_guides()then checks that every row resolves to a heading, every heading has a row, and every quoted fragment is still a literal inR/, and updatesvignettes/upgrading.Rmd. Do not edit that article directly. Bug fixes do not go in this skill, even when they move results; they are listed only inNEWS.md. - The
upgrade-mizer-codeskill addresses users. If the change is one only an extension author can act on — a method that stops dispatching, a workaround that can now be dropped, a mechanism an extension package has to adopt — put that guidance ininst/skills/upgrade-extension-package/SKILL.mdinstead, which generates theupgrading-extension-packagesarticle, and keep the user-facing wording inupgrade-mizer-codefree of extension asides. - When creating a pull request, always include the summary of your changes in the PR body.
- Committing Changes: When asking the user for permission to commit, the agent must first provide a clear summary of all implemented changes. When executing the commit, the agent must only stage and commit the specific files it modified (using
git add <file1> <file2> ...). The agent must never usegit commit -aorgit add ., to avoid committing unrelated unstaged changes in the user's workspace.