Skip to content

Improve reference index and clarify w_max terminology in docs#449

Open
gustavdelius wants to merge 1 commit into
masterfrom
improve-reference-docs
Open

Improve reference index and clarify w_max terminology in docs#449
gustavdelius wants to merge 1 commit into
masterfrom
improve-reference-docs

Conversation

@gustavdelius

Copy link
Copy Markdown
Member

Documentation-only improvements to make the website more useful for fisheries-science researchers and to make the maximum-size terminology consistent across the package. No behaviour changes.

Reference index (pkgdown/_pkgdown.yml)

  • New "Overview: the mizer workflow" section at the top of the reference index. It frames the whole page as a five-stage pipeline — create → calibrate → tune dynamics → project → analyse — with links to the key function in each stage, so a reader arriving cold can see how the sections below fit together. (Anchored on the mizer-package topic, which moved out of "Classes".)
  • Disambiguated related function families in the section descriptions: calibrate...() vs match...(), ...Biomass vs ...Number, and the plot...() variants (...2 = overlay two objects, ...Relative = ratio, ...ObservedVsModel).
  • Fisheries-notation map in the "Calculating rates" section: getPredMort()M2, getExtMort() ↔ residual M, getFMort()F, getMort()Z, with an explicit warning that getResourceMort() is mortality on the resource, not a component of fish M.

w_max message wording (R/setReproduction.R, R/manipulate_species.R)

Error messages that referred to w_max as a species' "maximum size" now describe it as the upper size-grid boundary, consistent with w_max being a purely computational parameter (the biological maximum size is w_inf; the reproduction cut-off is w_repro_max). The three affected test assertions were updated to match.

Model-setup wrappers (R/newSingleSpeciesParams.R, R/wrapper_functions.R)

newSingleSpeciesParams(), newTraitParams() and newCommunityParams() now document why they set w_max = w_repro_max: because they do not yet set up stochastic growth by diffusion, no individual grows beyond w_repro_max, so no grid headroom above it is needed. This is deferred, not changed — to be revisited when the constructors gain a diffusion parameter (#339). Man pages regenerated.

Notes

  • No behaviour changes; changes are limited to roxygen, message strings, _pkgdown.yml, and the matching test assertions.
  • The affected tests (test-setReproduction.R, test-manipulate_species.R) pass, and all three constructors build with the documented w_max == w_repro_max invariant holding.
  • The rendered docs/ site is intentionally excluded from this PR (following the repo convention of source-only commits); rebuild the site on merge as usual.

🤖 Generated with Claude Code

Documentation-only changes to make the website more useful and to make
the maximum-size terminology consistent.

Reference index (pkgdown/_pkgdown.yml):
- Add an "Overview: the mizer workflow" section at the top framing the
  page as a five-stage pipeline (create -> calibrate -> tune dynamics ->
  project -> analyse) with links to the key function in each stage.
- Disambiguate related function families: calibrate...()/match...() and
  ...Biomass/...Number, and the plot...() variants (...2, ...Relative,
  ...ObservedVsModel).
- Map mizer's mortality-rate names onto standard fisheries notation
  (M2, F, Z), noting getResourceMort() is resource mortality, not fish M.

w_max message wording (R/setReproduction.R, R/manipulate_species.R):
- Error messages that called w_max a species' "maximum size" now
  describe it as the upper size-grid boundary, consistent with w_max
  being purely computational (biological max size is w_inf, reproduction
  cut-off is w_repro_max). Tests updated to match.

Model-setup wrappers (R/newSingleSpeciesParams.R, R/wrapper_functions.R):
- Document why newSingleSpeciesParams(), newTraitParams() and
  newCommunityParams() set w_max = w_repro_max: without diffusion no
  individual grows beyond w_repro_max, so no grid headroom is needed.
  To be revisited when the constructors gain a diffusion parameter (#339).

No behaviour changes. docs/ site regeneration is intentionally excluded;
rebuild on merge as usual.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant