This vignette is for you if you need to extend mizer to meet the needs of your research project. You will already have read the mizer model description in vignette("model_description") and thus be familiar with what mizer can do out of the box. You now want to implement the extension or modification of the model required for your research, and for that you need to dive into the internal workings of mizer. This vignette is meant to make that as easy as possible.
The first thing you should do, even before reading this vignette, is to go to https://github.com/sizespectrum/mizer/issues and create a new “issue”" to share your ideas and plans with the mizer community. You may get back valuable feedback and advice. Another way to get in touch with the mizer community is via the size-spectrum modelling Google group.
In this section we describe how to set up your working environment to allow you to easily work with the mizer code. Much of it you may already have in place, so feel free to skip ahead.
Mizer is compatible with R versions 3.1 and later. If you still need to install R, simply install the latest version. This vignette was prepared with R version 3.5.3 (2019-03-11).
This guide assumes that you will be using RStudio to work with R. There is really no reason not to use RStudio and it makes a lot of things much easier. RStudio develops rapidly and adds useful features all the time and so it pays to upgrade to the latest version frequently. This guide was written with version 1.2.1268.
To work with R packages as a developer, you will need to install additional tools. Once you have these in place, you should install the devtools package with
You are now all set to develop R packages, and RStudio makes this extra easy. There is even a cheat sheet for package development accessible from the Help menu in RStudio.
In case git is not already installed on your system, you need to install it. You do not need to install any GUI for git because RStudio has built-in support for git. A good place to learn about using git and github is this chapter in the guide by Hadley on R package development.
Mizer is developed using the version control system git and the code is hosted on github. To work with the code you will create your own git repository with a copy of the mizer code.
Go to https://github.com/sizespectrum/mizer and fork it into your own repository. Then create a version control new project in Rstudio, and indicate your depository url.
Go the the Git tab and from “More” select “Shell…” to open up a Git shell. There issue the commands
git remote add upstream git@github.com:sizespectrum/mizer.git
git fetch upstreamThis will allow you to, from time to time, sync changes made in the sizespectrum/mizer repository into your own fork (see [https://help.github.com/en/articles/syncing-a-fork]). You do this with the command
git merge upstream/devYou will want to set up RStudio so that it automatically builds the documentation using roxygen. * Go to Build -> Configure Build Tools, tick the checkbox “Generate documentation with roxygen”.
On the “Git” tab select the “dev” branch. This contains the latest development code for mizer.
To run this code go to the “Build” tab in RStudio and click on “Install and Restart”. This builds and loads the mizer package based on this development code.
Mizer is organised in a modular fashion. It is separated into setup functions, simulation functions, and analysis and plotting functions. These will be described below after we have introduced the mizer model.
The core of mizer is the project() function that runs a simulation of the size-spectrum model. It takes a specification of the model contained in an object of type MizerParams and returns the results of the simulation in an object of type MizerSim.
There are several different methods for setting up a MizerParams object for specifying various concrete models. These setup functions make various simplifying assumptions about the model parameters to reduce the amount of information that needs to be specified. This usually takes the form of assuming allometric scaling laws. Below we will first describe the most general size spectrum model handled by mizer before describing the specialisations for which mizer has special setup functions.
There are many functions for analysing and plotting the results of a mizer simulation contained in a MizerSim object.
The MizerParams and MizerSim objects are S4 objects, meaning that their slots are rigorously defined and are accessed with the ‘@’ notation. You do not need to learn about S4 classes in order to understand the mizer code, because the code avoids using S4 methods. In the presentation below we assume that the MizerParams object is called params and the MixerSim object is called sim.
An object of class ‘MizerParams’ holds all the information needed for the ‘project()’ method to simulate a model.
If you need to add a new slot to the MizerParams class, you need to make the following additions in the file MizerParams-class.R:
representation list inside setClass.prototype list inside setClass. This gives a default value for the slot when a new oject of the class is created with new(). This is optional. If you do not provide a default then you must do the next step.emptyParams() go to the section “Make object” and inside the call to new() provide a default value for your slot. If your slot holds an array, then it is conventional in mizer to already give it the correct dimensions and dimnames here, if possible.What exactly to put into these places is usually clear in analogy to what is already there for other similar slots. You can see a good example in commit [https://github.com/gustavdelius/mizer/commit/c7236b7e1c320c4d6e65e48775bf1aac9f71a677]. Next you will probably want to provide code to fill the slot with what you want it to hold and write the code that actually uses the slot.
We use testthat and shinytest. The test are in the directory tests/testthat.
Some tests compare the results of calculations to the results the code gave in the past, using the testthat::expect_known_value() test. The past values are stored in tests/testthat/values. If one of the tests gives a value that is different from the stored value, then the test throws an error and overwrites the stored value with the new result. The second time the test is run, it then no longer fails. Luckily the original values will still be in the git repository. So after you think you have fixed the error that led to the wrong result, you should revert to the old stored values before re-running the test. Reverting to the old stored values is easy: Just go to the Git tab in RStudio, select the changed files in tests/testthat/values (select, not tick), then right-click and choose Revert.
When a plot has changed, the error message from testthat::expect_known_value() is not particularly useful, because it compares two ggplot objects. In this case you should carefully compare the plots by eye. To view the old plot you have to first revert the file in tests/testthat/values and then load the plot from that file with readRDS("tests/testthat/values/name_of_plot_function").
It may be that the change in the result of a calculation is intended, perhaps because your new code is more accurate than the old code. If you are 100% certain of this, but only then, should you commit the changed files in tests/testthat/values, so that these new values form the basis of future comparison tests.
If you make a change to mizer’s code you will have to rebuild the package after you are done. In RStudio this can be done by clicking on the Build tab at the top right and clicking Install and Restart. To be sure that the changes have taken proper effect it may also help to clean the environment and/or restart RStudio.
To be sure that the package builds properly, make sure that the Roxygen2 package is properly installed, and click the More dropdown, on the Build tab, and click Configure Build Tools and tick Use devtools package functions if available and Generate documentation with Roxygen, and click Configure and under Automatically roxygenize when running: tick Build & Reload.