This is a patch release made necessary by a change in CRAN’s requirement regarding the vignettes. It also includes a bug fix:
project() and projectToSteady(..., return_sim = TRUE) now correctly returns also the other components of the MizerSim object stored in n_other. #285This release introduces a change that requires you to upgrade your old MizerParams and MizerSim objects with upgradeParams() or upgradeSim().
Now the model can include an external encounter rate that represents the rate at which a predator encounters food that is not explicitly modelled. This encounter rate is set with setExtEncounter() or ext_encounter<-() and can be read with getExtEncounter() or ext_encounter(). So this is similar to how external mortality is handled.
You can now use given_species_params() to see the species parameter values that you have explicitly specified and calculated_species_params() to see the species parameter values that mizer has calculated automatically or set to defaults. You can continue to use species_params() to get all species parameters, irrespective of whether they were given or calculated.
You can still set parameter values with species_params<-(), but you can also use the stronger given_species_params<-() which not only sets the values you give but also triggers a re-calculation of the calculated species parameters. Using given_species_params<-() is therefore usually the better option.
There is now a three-part mizer course at https://mizer.course.sizespectrum.org with each part consisting of several tutorials, including code and exercises:
Part 1: Understand
You will gain an understanding of size spectra and their dynamics by exploring simple example systems hands-on with mizer.
Part 2: Build
You will build your own multi-species mizer model for the Celtic sea, following our example. You can also create a model for your own area of interest.
Part 3: Use
You will explore the effects of changes in fishing and changes in resource dynamics on the fish community and the fisheries yield. You will run your own model scenarios.
effort argument in project() is improved.h of the maximum intake rate is not given, it is now again given a default value. #282matchGrowth() no longer gives an error when there is no w_inf column. #279This minor release was made necessary to keep mizer on CRAN after a unit test failed on macOS 13.3 with version 14.3 of the CLT toolchain.
This release introduces a change that requires you to upgrade your old MizerParams and MizerSim objects with upgradeParams() or upgradeSim().
For an explanation see blog post at https://blog.mizer.sizespectrum.org/posts/2022-11-30-dont-use-von-bertalanffy-growth-parameters/
The species parameter that specifies the size at which also the largest fish stop growing is renamed from w_inf to w_max. The parameter w_inf is now reserved for the von Bertalanffy asymptotic size parameter. If you upgrade your existing MizerParams object with upgradeParams() the w_inf column is copied over to the w_max column automatically, but you may want to change the values yourself if they do not currently reflect the maximum size of the species. Otherwise the size distributions predicted by mizer will not match observations.
The resource parameters kappa and lambda are now used to set the abundance of the resource in the steady state rather than the carrying capacity, because the latter is not observable.
While tuning the steady state using the steady() function the resource abundance is now being kept fixed at the chosen value. Then the resource dynamics can be switched on later with setResource() without changing the steady state. At that stage you only choose either the resource intrinsic growth rate or the resource carrying capacity and the other is determined by setResource() in such a way that the resource replenishes at the same rate at which it is consumed. If you want to keep the old behaviour and switch off this automatic balancing you have to add the balance = FALSE argument when calling setResource().
You can also choose between semichemostat dynamics resource_semichemostat() or logistic dynamics resource_logistic() or you can write your own function implementing more sophisticated resource dynamics.
The setParams() function no longer includes the arguments for setting the resource parameters. Instead you set these separately with setResource().
As explained in the blog post at https://blog.mizer.sizespectrum.org/posts/2022-11-30-dont-use-von-bertalanffy-growth-parameters/, the von Bertalanffy curves fitted to size-at-age data are not suitable for estimating the size-dependent growth rates in mizer. It is therefore now recommended that instead of von Bertalanffy parameters you supply the age at maturity in the age_mat column of the species parameter data frame. This is then used by mizer to calculate a default for the maximum intake rate parameter h if you do not supply this.
In the past, whenever you changed any model parameters, you needed to re-tune other parameters to keep the growth rates in line with observations. There is now a new function matchGrowth() that automatically scales the search volume, the maximum consumption rate and the metabolic rate all by the same factor in order to achieve a growth rate that allows individuals to reach their maturity size by their maturity age while keeping the feeding level and the critical feeding level unchanged. This function does not however preserve the steady state, so you will need to also call steady() after matching the growth rates.
steadySingleSpecies() that only balances the size-spectrum dynamics while ignoring multi-species effects. In other words, it calculates the steady-state size spectrum of each species as it would be if the abundance of prey and predators could be kept constant at their current values.plotGrowthCurves() can now superimpose a scatterplot of size-at-age data if you supply this via the new size_at_age argument.calibrateNumber() and matchNumbers() that are like calibrateBiomass() and matchBiomasses() but work with observed numbers instead of observed biomasses.age_mat() to calculate the age at maturity from the growth rate and the size at maturity.project() now also works when called with a MizerSim object with additional components.steady() now preserves the RDD function in the MizerParams object rather than always setting it to “BevertonHoltRDD”.plotSpectra() or setInitialValues() the user can now choose geometric averaging with geometric_mean = TRUE.w_mat25 species parameter is no longer filled in automatically if it is not supplied. This makes it easier to change w_mat without having to change w_mat25 at the same time.compareParams() now also checks the validity of its second argument.newTraitParams().info_level argument in newMultispeciesParams() now leads to more messages.validSpeciesParams(). #136l2w() and w2l() for converting between length-based and weight-based species parameters. #258style argument to plotDataFrame() to facilitate producing area plots.wrap_scale argument to plotDataFrame() to control scaling of axes in faceted plots.plotDiet() can now show diets of several predator species in a faceted plot. #267size to linewidth aesthetic to avoid warnings in new version of ggplot2.compareParams() says so clearly.getReproductionLevel() works as long as R_max is set. #252gear_params().defaults_edition(). #186get_gamma_default() ensures a feeding level of f0 for larvae also if interaction_resource is not equal to 1. #238NS_paramsset_species_default(). #268w_inf no longer leads to error in plyr::aaply(). #269url field in metadata.plotYieldObservedVsModel() and plotBiomassObservedVsModel(). #266plotDiet() restored after change to ggplot2 package. #265mizerPredRate() between the argument t and the function base::t().upgradeSim() with a MizerSim object.getRequiredRDD()renameSpecies() no longer fails when linecolour and linetype are of different lengths.setInitialValues() can now average over a time_range.getSSB(), getBiomass(), getN(), getYieldGear() and getYield() can now be called with a MizerParams object as well as with a MizerSim object. (#200)plotBiomassObservedVsModel() and plotYieldObservedVsModel() contributed by @SamikDatta., together with their plotly counterparts.calibrateBiomass(), calibrateYield() to set the model scale to agree with total observed biomass or total observed yield. Uses the new scaleModel().matchBiomasses() and matchYields() will try to adjust the abundances of the species to produce the observed biomasses or yields. See blog post at https://bit.ly/2YqXESV .params <- setReproduction(params, maturity = my_maturity) one can simply use maturity(params) <- my_maturity. These are documented together with the setter functions. #213setMetadata() to add information to a MizerParams object describing the model, for example a title, a description, the author or list of authors, a url and a doi. This will be particularly useful for sharing your models with otherssaveParams() for saving a MizerParams object to a file and readParams() for reading it back in. The resulting files can be shared with others who want to run your model.getMetadata(). This helps you keep track of different versions of your model.steady() now has a preserve argument with possible values erepro, R_max or reproduction_level to specify which quantity to preserve. This means that one can continue to use steady() also once one has started to tune the density dependence in reproduction. #208gear_params are now set to “species, gear”, so that one can access individual entries with for example gear_params(NS_params)["Cod, Otter", "catchability"]. #212z0 argument of setExtMort() has been deprecated in favour of ext_mort in order to avoid confusion with the species parameter z0.setColours() and setLinetypes() now issue warnings when invalid values are given and ignores NAs.comment arguments to the setter functions have been removed. #214reset argument which, when set to TRUE will recalculate the rates from the species_, gear_ and resource_params even when custom values had been set. #214species argument to various functions, which is checked with valid_species_arg(), now does not throw an error even when there is no valid species included. Only a warning is issued. That means that for example plotSpectra(NS_params, species = list(), total = TRUE) is now allowed.getComponent() from the mizer extension mechanism now returns NULL when asked for a non-existent component instead of giving an error. This gives an easy way to check for the existence of a component.inter for the North Sea model now has the alternative name NS_interaction, with the old name deprecated.addSpecies() are now by default given a reproduction level of 1/4 instead of 0, because at the low densities at which they are introduced there would otherwise not be enough density dependence to stabilise them.min_w, max_w, min_l and max_l used in some summary functions and processed by get_size_range_array() accept vector values setting different limits for different species.resource_rate and the resource_capacity as arguments, which makes it easier to use them in extension packages.newMultispeciesParams(), #199linecolour or linetype in the species parameters now actually changes the linecolours and linetypes as intended.getGrowthCurves() and plotted with plotGrowthCurves() are now correct, and no longer extend above the asymptotic size.plotGrowthCurves() with species_panel = TRUE now respects the species argument to only show growth curves for selected species, it works with a MizerParams object as well as a MizerSim object, and it shows the panels in the correct order. #201setBevertonHolt() function has been expanded with more arguments. It allows you to change the density dependence in reproduction without changing the steady state of your model.getReproductionLevel() function tells you at what proportion of their maximum reproduction rate the species are operating in your model.NS_sim which holds a simulation of the North Sea model.plotDataFrame() allows easier creation of plots.setInitialValues() correctly preserves the gear names on the initial effort. Thanks to Axel Rossberg.getFMort() correctly passes the t argument on to any custom fishing mortality function you may have written.mizerPredMort() suggested by Axel Rossberg.plotSpectra() now only shows those species in the legend that are actually contained in the plot.initialNOther() also works with MizerSim object.projectToSteady() is called with effort, this effort is now also stored in the initial_effort slot.summary() which is now using sprintf() for better formatting and also gives the initial_effort.project_simple() have been given convenient defaults.projectToSteady().newSingleSpeciesParams() for creating a single species in a power-law background.animateSpectra() creating an animated plot of a simulation.addSpecies(), removeSpecies() and renameSpecies().setComponent() can now take any form, they no longer have to be a named list.return_data in the plot’s functions allows to return the data frame used for the ggplot instead of the plot.steady() no longer switches off the Beverton-Holt density dependence. You can do this manually with setBevertonHolt() with R_factor = Inf.getYield() now also works with density-dependent fishing mortality. Thanks to James Roger for discovering the problem.gamma argument now is no longer ignored in newTraitParams() but correctly overrides the f0 argument. #188getFMort() again works correctly when called with a MizerSim object.resource_semichemostat() no longer fail when at some sizes both the resource growth rate and the resource mortality rate are both zero.no_w in newTraitParams() is now always an integer.w_min_idx should point to the start of the size bin containing the egg size w_min”.valid_species_arg() is called with species = NULL and there are no background species then it returns NULL.getDiet() and plotDiet().projectToSteady() to run the full dynamics to steady state.distanceSSLogN() and distanceMaxRelRDI() to measure distance between two states.compareParams() to compare two MizerParams objects.constantEggRDI() to allow keeping egg densities fixed.customFunction() to allow users to overwrite mizer functions.plotGrowthCurves as a panel of species with their respective Von Bertalanffy curvesplotPredMort() and plotFMort will stop displaying mortality values past the species’ asymptotic size. The argumentall.sizes allows you to continue to show these values.getFMort() now passes time argument correctly. #181validEffortArray() now sets the dimnames correctly. #173lifecycle package to indicate status of some functions and arguments as ‘experimental’ or ‘deprecated’.setFishing(). #172species argument in mizer functions, via the new valid_species_arg() function. #170setInitialValues()min_w_pp is larger than min_wt passed to dynamics functions has been corrected.setReproduction() now correctly sets the the total proportion psi when the maturity proportion is changed.project() has been simplified. They are now either set by the arguments t_start, t_max and t_save or by the dimension names of the effort array.setRmax() to setBevertonHolt() and allow it to work on an arbitrary MizerParams object. The old name setRmax() is still available as alias.mizerFMort() now can also use the abundances and the rates e_growth and pred_mort. This is useful for example for implementing balanced harvesting.gear_params is allowed to have zero rows.validGearParams() the species name is used as gear name in case gear_name is NA.validGearParams() ensures that all required arguments of the selectivity function are supplied and checks validity of species names.species_params()<- suppresses warnings.steady() fails because RDI is zero it gives a meaningful error message.newCommunityParams() now protects its zero investment in reproduction with a comment.valid_species_arg() checks validity of species selection arguments.upgradeParams() can now also upgrade old MizerParams objects that do not have a consistent initial_effort.validParams() validates a MizerParams object and automatically upgrades it with upgradeParams() if necessary.project() or steady(), #163.getRates() to calculates all rates and collects them in a list.steady() with return_sim = TRUE now creates the MizerSim object the same way as project(), namely with the original values in the first time slot.species_params(), gear_params() and resource_params().project().getRates() functions by removing the arguments that passed in other rates. Instead the required rates are now always calculated within these functions.validGearParams() handle NAs more gracefully and check that there are no duplicates.upgradeParams() works also on params objects that were created with a development version of mizer.upgradeParams() does a better job at guessing the value for w_pp_cutoff.getFeedingLevel(), getPredMort(), setInitialValues() and steady() now work also when model has extra components.plotFeedinglevel() when called with include_critical = TRUE, see #162.species_params is a tibble.params(), effort() and times() to getParams(), getEffort() and getTimes() to avoid conflicts.getDiet() also takes into account possible contributions by user-defined other components.project() is called with t_max < t_save then t_save is automatically reduced so that the result at t_max will get saved.project().project_simple() that projects a given number of time steps. This might be useful to extension writers.... argument to project() is passed on to the dynamics and rate functions.steady() runs faster by using project_simple().summary() now also works with non-default feeding kernels. #159validSpeciesParams() no longer fails when w_mat25 is not specified. #160setInitialValues() also works in a model with only a single species. #161resource_params()<- now works and has unit tests.Some inconsistencies in the choice of names for parameters was removed by renaming
interaction_p -> interaction_resourcer_resource -> resource_rateK_resource -> resource_capacityother_params()<- and other_params() for setting and getting other parameters, for example to be used in user-defined rate functions.setInitialValues() also sets initial_effort. #157This is a major new release with many new features, an internal refactoring of the code and a new extension mechanism.
Nevertheless this version of mizer is almost fully backwards compatible with version 1.0 with the exception of bug fixes and the following breaking changes:
print_it argument from plot functions.plotFeedingLevel() now only plots the values within the size range of each species. If for some reason you want the old plots that show a feeding level also for sizes that the fish can never have, you need to supply an argument all.sizes = TRUE.RDD argument in setReproduction().sex_ratio argument has been removed from getRDI() and getRDD().set_scaling_model() function has been removed because such models can now be set up with newTraitParams() with the options perfect_scaling = TRUE and egg_size_scaling = TRUE.display_frames(), addSpecies(), setBackground() and retuneAbundance() have been removed to the “mizerExperimental” package (https://sizespectrum.org/mizerExperimental/)project() a progress bar is displayed by default. You can turn this off with the option `progress_bar = FALSE.The new functions
newCommunityParams()newTraitParams()newMultispeciesParams()replace the old functions set_community_model(), set_trait_model() and MizerParams(), which are now deprecated. The new functions choose better default values, in particular for metabolic rate and maximum intake rate.
After setting up a mizer model, it is possible to change specific model parameters with the new functions
species_params<-()resource_params<-()gear_params<-()setPredKernel()setSearchVolume()setInteraction()setMaxIntakeRate()setMetabolicRate()setExtMort()setReproduction()setFishing()setResource()The new function setParams() is a wrapper for all of the above functions and is also used when setting up a new model with newMultispeciesParams(). (#51)
The documentation for these functions serves to explain the details of the mizer model.
Along with these setter functions there are accessor functions for getting the parameter arrays: getPredKernel(), getSearchVolume(), getInteraction(), getMaxIntakeRate(), getMetabolicRate(), getExtMort(), getMaturityProportion(), getReproductionProportion(), getCatchability(), getSelectivity(), getResourceRate(), getResourceCapacity(), getResourceParams(), getResourceDynamics(),
setRmax().The MizerParams object now also contains the initial values for the size spectra. This is particularly useful if the model has been tuned to produce the observed steady state. The new function steady() finds a steady state for a model and sets it as the initial value. The initial values can be accessed and changed via functions initialN() and initialNResource(). The initial values can be set to the final values of a previous simulation with setInitialValues().
The MizerParams object now has a slot initial_effort that specifies the initial fishing effort to which the steady state has been calibrated.
Mizer now has an extension mechanism that allows other R packages to be written to generalise the mizer model. See setRateFunction() and setComponent(). This mechanism is still experimental and may change as we gain experience in writing extensions for mizer.
plotlyBiomass() as the plotly version of plotBiomass(), and so on.plotGrowthCurves() plots growth curves and compares them to the von Bertalanffy growth curve.plotDiet() plots the diet composition as a function of predator size.highlight argument to all plot functions that display curves for multiple species. Displays highlighted species with wider lines.plot() method for MizerParams object to plot the initial state.include_critical in plotFeedingLevel() allows to show also the critical feeding level.wlim argument to plotSpectra() in analogy to the existing ylim argument to limit the w range in the plot.setColours().solid but this can be changed via the setLinetypes() function.box_pred_kernel() implements a box-shaped kernel as an alternative to the default lognormal_pred_kernel().power_law_pred_kernel() implements a power-law kernel with sigmoidal cutoffs at both ends. This is suitable for filter feeders.setPredKernel()). Mizer automatically falls back on the old non-FFT code to handle this. (#41)getPredKernel() returns the full 3-dimensional predation kernel array, even when this is not stored in MizerParams object.Now it is finally possible to have several gears (or fleets) targeting the same species. The information is set up via a new gear_params() data frame. See setFishing() for details.
w(), w_full(), dw(), dw_full().upgradeParams() and upgradeSim() can upgrade objects from previous versions of mizer so they work with the new version.getDiet() calculates the diet of predators. (#43)RickerRDD() and SheperdRDD() for density-dependence in reproduction, as well as noRDD() and constantRDD().double_sigmoid_length() allows modelling of escape of large individuals.sigmoidal_weight() is weight-based trawl selectivity function. (Ken H Andersen)getGrowthCurves() calculates the growth curves (size at age).mizerRates() calculates all the rates needed in the model and collects them in a list.times() to extract the times at which simulation results are saved in a MizerSim object.finalN(), finalNResource() and finalNOther() as well as idxFinalT() to access the values at the final time of a simulation.getCriticalFeedingLevel() returns the critical feeding level for each species at each size.melt() function from the reshape2 package which allows users to convert the arrays returned by mizer functions into data frames that can be used for example in ggplot2 and plotly.validSpeciesParams() checks validity of species parameter data frame and sets defaults for missing but required parameters.n, p and q as well as the feeding level f0 can now be set at the species level via columns in species_params.fc can now be specified as a species parameter and will be used to calculate the metabolic rate parameter ks if it is not supplied.project() now shows a progress bar while a simulation is running. Can be turned off with progress_bar = FALSE argument.Inf.resource_semichemostat().interaction_resource column in the species parameter data frame.w_mat25 column in the species parameter dataframe, which gives the size at which 25% of the individuals of a species are mature.m column in the species parameter data frame.project() can now continue projection from last time step of a previous simulation if the first argument is a MizerSim object. The new append argument then controls whether the new results are appended to the old.newMultispeciesParams().n, n_pp and n_other arguments from the initial values in the params argument.perfect_scaling argument allows newTraitParams() to produce a perfectly scale-invariant model.ext_mort_prop argument in newTraitParams() allows the inclusion of external mortality.NS_params with the North Sea model MizerParams object.newMultispeciesParams().getmM2() -> getPredMort()plotM2 -> plotPredMort()getM2background() -> getResourceMort()getZ() -> getMort()getESpawning() -> getERepro()MizerParams() -> emptyParams() or set_multispecies_model()r_max to R_max.getSSB(), the calculation of the spawning stock biomass is done correctly using the maturity ogive instead of the proportion of energy allocated to reproduction. (#47)getEncounter() and getPredRate() now set names on the returned arrays.ylim argument is not handled correctly in plots.display_frame() is now exported.plotGrowthCurves() and getGrowthCurves() also works when there is only a single speciest_start argument in project() is used correctlyget_initial_n() gets values for n and q from params objectsummary() of MizerParams object reflects the number of non-empty resource bins. (@patricksykes)get_gamma_default(), get_h_default() and get_ks_default(), making it easier to change or extend these in the future.set_species_param_default() makes it easier to set default values for species parameters.@inherit functionality of roxygen2 to reduce duplication in roxygen documentation.getPhiPrey() is replaced by getEncounter() which now returns the full encounter rate, including the contribution from other components. Even in the absence of other components, getEncounter() differs from the old getPhiPrey() because it includes the search volume factor.params to refer to an argument of class MizerParams, sim to refer to an argument of class MizerSim, and object to an argument that can be either.setClass() to follow the new guidelines, replacing representation by class and removing prototype and validity.shiny_progress renamed to progress_bar because they control any type of progress bar.outer() instead of tapply() where possible to improve readability.hasArg() and anyNA() because they were not available in R 3.1@std_metab and @activity slots into a single @metab slot.@w_min_idx out of @species_params into its own slot.@maturity to hold the maturity ogive.@pred_kernel to hold predation kernel if it has variable predator/prey ratio.@resource_dynamics to allow user to specify alternative resource dynamics.@gear_dynamics to species to be targeted by multiple gears.@ft_mask that is used when calculating predation rates using the Fourier transform method.@rates_funcs to allow mizer extensions to replace mizer rate functions with their own rate functions.@srr we now have the name of the function in @rate_funcs$RDD, see #91.@other_dynamics, @other_params, @other_encounter, @other_mort and @initial_n_other to allow mizer extensions to add more ecosystem components.set_scaling_model(), see section 12 in the vignette.PlotYield() no longer fails when species names are numbers or when a species abundance is zerototal parameter to several plot functions to add the curve for the total community (sum over all species and resource)species parameter to all plot functions to allow for only a selection of species to be plotted@initial_n and @initial_n_pp slots to MizerParams class.getPhiPrey() and getPredRate().getPhiPrey() and getPredRate().