Starting an estimation for a new species

From DEBwiki
Jump to: navigation, search
AmP estimation
Concepts

Data and completeness
Parameter estimation
Goodness-of-fit: SMSE / MRE
AmP Literature

Practice - essentials

Starting an estimation for a new species
Setting initial parameter values
Setting weight coefficients
Computing implied properties
Submitting to the collection

Practice - extra modules
Code specification
User-defined files: run, mydata, pars_init, predict
Data: Zero-variate, Univariate, Pseudo-data

Typified models
Estimation options

Download the DEBtool

For Matlab, download DEBTool_M.zip file here, unzip it and set the path to the DEBtool_M directory and all its subdirectories. Always work from your own directory outside of the DEBtool folder.

Think about which typified model(s) is/are applicable to your species

A number of extensions on the standard DEB model are needed to capture specific life-history of various groups of species - these extensions on the standard DEB model are called typified models. Each one is attributed its own label. This has some importance for the procedure.

Some examples of model extensions are relaxing the assumption of constant shape whereby changes in shape allow metabolism to accelerate for part of the life-cycle (Kooijman, Pecquerie et al. 2011). Or including extra-life stages (for instance weaning for mammals, pupation in insects), and choosing different modes of reproduction (foetal or egg development). Parameter values can still be compared over across different species.

Go the AmP species list page and see what Typified model corresponds to a similar species or taxonomic group. Bear in mind, that this is a starting point and you may need some research and testing to come to a final decision on which Typified model applies to the species.

ChoosingTypifiedModel.PNG

Create a folder which will contain the 4 user-defined files of your species

Create a repository with the name of 'your pet' e.g. Chromis_chromis.

Next you will need to have four user-derfined files inside named: mydata_Chromis_chromis, predict_Chromis_chromis, pars_init_Chromis_chromis and finally run_Chromis_chromis.

AmP files.PNG

Use empty templates to make the user-defined files

In your local DEBtool folder go to DEBtool_M\lib\pet and you will find zipped folders containing empty templates for the 'std' and the 'abj' models (templates_std.zip and templates_abj.zip) respectively. You can extract the files, place them in your working folder, rename them and then start filling them out.

Using these empty templates avoids errors from having old stuff that was not deleted. On the other hand, starting with a related species has the advantage that the model type and taxonomy are probably correct and the initial parameters, as specified in the pars_init file are probably not too far from the one for the species at hand. Yet, this more risky start requires discipline to avoid the presence of material that does not relate to your species. A useful procedure is to start with removing all bibkeys of the data and update the bibliography list. Then continue by replacing all data, and adding the correct bibkey, till all bibkeys are filled again or the whole existing data set removed. Don't forget to update the labels for the zero- and uni-variate data sets in the entry, in the header of the mydata file.

Modify a working example

Save the following files from the DEBtool folder /lib/pet into your working folder:

  • mydata_my_pet for setting data and references
  • predict_my_pet for specifying model predictions
  • pars_init_my_pet for initiating parameter values and fix/free them
  • run_my_pet for checking, setting estimation options and run estimation

You subsequently edit the name of these files, replacing my_pet by the latin name of your species (genus and species in the name connected by an underscore). Open the files and make the same change in the header of the files. Run by typing the name of your run file in your active window.

Alternatively, download the files of a similar species online and replace the name of that pet by the latin name of your species (genus and species in the name connected by an underscore). Open the files and make the same change in the header of the files. Run by typing the name of your run file in your active window.

DownloadAmPfiles.PNG

Make the entry

Replace the test data, other information and references in the mydata file by the corresponding information for your species. Replace the code in the predict file to compute the predictions that match your data.

Go to the specific page for each one to find instructions on how to create each file.

Depending on option settings, results will be printed to screen and/or a .mat file and/or .html file. This .mat file can be read with printmat('my_pet'). You can start parameter estimation from an automatized setting, the initial setting as specified in pars_init, or from the results_my_pet.mat file, which was written after a previous run. You can reduce or enhance the effect of particular data sets/points by changing weight coefficients in mydata. The function parscomp_st is used in predict files to compute compound parameter from primary parameters; most DEBtool/animal functions work with scaled parameters. The script run_my_pet first checks the consistency of the three user-defined functions with check_my_pet, assuming that they have no Matlab errors. Then estimation-options are set, such as the maximum number of iterations, or no estimation at all. Finally the estimation and automatized presentation of results are called; the presentation of results can (optionally) be customized with function custom_results_my_pet. Plots with the same labels and units can be combined into one plot, by assigning datasets to a group and setting a caption.

Effect of parameter values on predictions

Before you start parameter estimation, it makes sense to study the effect of parameter values on the predictions. This is done using, in run_my_pet, the two options:

  • estim_options ('method', 'no')
  • estim_options('pars_init_method', 2)

Then you can manually bring the parameter values in the neighborhood of realistic ones by following the nine steps procedure. Please note that this works well for the 'std' model, but needs to be adjusted if using 'abj'.

See also

How to set and read the initial parameter values, weight coefficients, etc. See 'Practice and getting started' section on the right hand side.