AmPtool contains Matlab functions for the visualisation and analysis of patterns in (functions of) parameter values of the Add-my-Pet (AmP) collection; it has no data and is an extension of DEBtool_M, and makes frequent use of it. All parameters and (population) traits for all entries are available in dropdown COLLECTION/AmPdata as a zip-file. Save the files allStat.mat, popStat.mat, allUnits.mat and allLabel.mat from the linked zip into one directory. Open Matlab and set paths to AmPtool, DEBtool_M (including subdirectories) and to the directory with the .mat files. Make sure to work with the latest versions since AmPtool/taxa should correspond exactly with AmPdata and they both change frequently; check the date of the latest version in dropdown COLLECTION with date_allStat and date_popStat. If you downloaded new .mat versions during a Matlab-session (rather than before the start), don't forget to clear all in Matlab. This is because structures allStat and popStat are made persistent to avoid repeated loading of these large files. Subdirectory AmPtool/curation is only meant for curators to maintain the collection.

This page describes how to use AmPtool (in combination with DEBtool_M) for analysis of data in 4 stacked steps: tree, selections, legend and plotting.


The parameters and implied properties for all entries can be downloaded from AmPdata, the last item in the COLLECTION dropdown. Unpack the zip in a directory and make a path to this directory in Matlab. If you load a new version of AmPdata, the next thing you should do is to give the Matlab command clear all, else the previous version might be used. The size of allStat (and popStat), should exactly match the lists-of-lists of AmPtool (see below), else errors will occur. The functions date_allStat, date_popStat and date_taxa can be used to check version dates.

All data (i.e. meta-data, parameters, meta-parameters, implied traits, but no empirical data) of all entries is collected by function write_allStat into the Matlab-structure allStat.mat. Only curators who have all entries locally can run this function, but the result is available for anybody. To read data directly, use load allStat, or better read_allStat for all entries, or read_stat for specified entries. The structure allStat has as first level field names the names of all entries, as specified by select (see below). As the AmP collection grows, lists-of-lists change (see below), so does allStat; these two should be seen as a couple that should not be uncoupled. All rates and times that are not primary parameters are given at temperature T_typical, which is entry-specific; use temperature correction factor c_T to convert to the reference temperatures and temperature parameters to other temperatures. The primary parameters are given at T_ref = 20 C, but only those with time in their dimensions depend on temperature.

Empirical data is only stored in the mydata-files, so not collected in some huge structure. One way to get this data is to copy a mydata-file to local and run it; mydata-files require no input. Function get_data does the same and deletes the local mydata-file after running it: vars_pull(get_data('Daphnia_magna')) assigns all data specified in mydata_Daphnia_magna.m directly to variables in your work directory. The rest of this guidance page focusses on meta-data and derived data: parameters, meta-parameters and implied traits.

All functions that analyse data read in allStat, using function read_allStat or read_stat. For example, (expected) gestation time t_g is given at T_typical; convert to temperature T_ref with [var, nm, units, label] = read_allStat('t_g','c_T'); tg_Tref = var(:,1).*var(:,2); and print with prt_tab({nm, tg_Tref},{'name'}[label{1}, ', ', units{1,1}]}). Oviparous species will have value NaN (Not-a-Number). Find all entries that have model std with [model, nms] = read_allStat('model'); nms(strcmp('std', model)).

Subfields ecoCode in allStat specifies climate, ecozone, habitat, embryo environment, migration/torpor, food, gender and reproduction mode for each entry. The codes are explained in AmPeco, assigned in the mydata-files. All functions that analyse eco-codes use function read_allEco or read_eco.

prt_report_my_pet can be used to get parameters and implied traits for specific entries. prt_report_my_pet('Daphnia_magna'); will open an htlm-page in your browser, that allows for searching of traits and has the option "short/medium/long/pars" to reduce the length of the table. The "implied traits"-pages on the AmP-website present a subset of the shown list (but has no searching facilities). The function reads parameters in allStat and specifies scaled functional response and temperature for each trait. The function is also used during the parameter estimation procedure for entries that are not yet in the collection with estim_options('results_output', 4); in the run_my_pet file. In this application the data is not read from allStat, but computed from parameters, using the same routines that were used to obtain allStat. This is handy for checking that a particular parameter combination is yes or no realistic. With estim_options('results_output', 5);, related species are included in the report to compare parameters and implied traits. These related species in the collection are identified with function clade (see below), and if two or more related species are found, color coding is applied to highlight eccentricity of values. The selection of "related" species can be specified in the run-file explicitly by declaring global variable refPets and filling it with a cell-string of AmP-species names. Variable refPets is only used if results_output level is 5 or higher.

Taxonomic tree: lists-of-lists

Entries are organised according to the taxonomic position of the taxa that they represent. This position is determined in lists-of-lists, stored in AmPtool/taxa; the taxonomic info in the mydata-files is only used for presentation in the species-list and for the default value of the water content by function get_d_V and the default nitrogen waste by function get_N_waste. Further it is used to identify the phylum, class and order names in the function list_taxa (see below). A list is a simple text-file. Several functions link these lists into a tree. The tree has a root, here called Animalia, nodes, which are names of taxa, and leaves, which are names of entries. Most entries represent a species, but some species have multiple entries, such as geographical races. Each node once occurs in a list and once as name of a list; the root only occurs once as a name of a list. All entry (= leaf) names have an underscore in their name, while no node has an underscore. The last node (= list name) in tree-branches only contains leaves and is a genus, which is part of the name of the entries it contains. No other node contains leaves. Function list_taxa returns a list of all nodes and (optionally) leaves; you can also extract genera, families or phyla only. list_taxa('Deuterostomata',4) returns a list of all deuterostome families in the collection and list_taxa('',7) a list of all animal phyla. Print-and-open an html-table with numbers of AmP entries with e.g. get_n(list_taxa('Carnivora',4)). The species-sequence on the AmP web-pages species-list and species-tree is composed from this tree.

Compose your own interactive tree with treeview_taxa, with any node as root, including pictures on the nodes and links on the leaves, if you are web-connected, e.g. treeview_taxa('Crustacea'). It can also show the distribution of some statistic, i.e. parameter or implied trait, among the taxa in the (small) tree with background colour gradients. This statistic can be symbolic, with a name matching some field in allStat, or numeric, e.g. computed from values in allStat: treeview_taxa('Cladocera', 'kap'). Function select_taxon let you choose a taxon from a list of all possibilities. If you are not sure about the possible nodes, or want to avoid spelling errors: treeview_taxa(select_taxon('Arthropoda', 5)) let you choose from all arthropod orders.

The tree can be read in the direction from leaves to root with the function lineage, and in the direction from root to leaves with the function pedigree. The default input of pedigree is the root Animalia, but can also be any node, which becomes the root of the output-tree. The (character) string produced by pedigree can directly be printed to the screen, which is useful for small trees. The tree can be used to identify useful taxa for analysis. The function galleryAmP('Cephalopoda') composes a gallery of pictures for taxon Cephalopoda (in this case); clicking on a picture opens the tree at the seleted taxon.

A few taxa have a special status. Reptilia and Sarcopterygii are used in mydata, will not occur in lineage, but can be used in select. Pisces is not used in mydata, will not occur in lineage, but can be used in select.

Tree topology: Sampled at 1012 entries, the tree has 1998 nodes, which are the handles for selection. The left figure shows the survivor function of the number of branches per node and the right one that of the number of nodes between leaves and root. For comparison, a binary tree has 2 branches per node (by definition), 1012-1=1011 nodes and a mean of log2(1012)=9.98 nodes between leaves and root. At 2024 entries, the tree has 3052 nodes, so less nodes with a single branch, relatively; the nodes genus, family, order, class and phylum are always present.

Selection of entries

AmP has a number of select-functions, i.e. functions that either return a cell-string of entry names or a vector of booleans (i.e. of the true/false type). These functions scan the whole collection and select entries that comply to a variety of specified criteria.

Selection on taxonomy

A motivation for this type of selection could be to study evolutionary adaptations of parameter values and implied traits. Inclusion of very unrelated species in plots of traits typically results in a blurr that is not very informative. Selection of entries via the tree is done with the functions select and select_01. Select returns a cell-string with names of selected entries, select_01 a vector of booleans and a cell-string with the names of all entries. Notice that allStat and the lists-of-lists change continuously, so do the results of select and select_01.

Function clade finds the lowest taxon (= node in the tree) that contains a set of specified taxa, and all its members at exist in the collection. It combines functions lineage and pedigree and can also be used to find the closest relatives of a single specified taxon. If a species is not found in the AmP collection, it searches the Catalog of Life and the Taxonomicon for lineages, with functions lineage_CoL and lineage_Taxo and presents the AmP species that are most related.

Print (compound) parameters or statistics of selected entries to screen with prtStat, or, including the tree-structure, with pedigree. Use clade to select related entries and catenate with prtStat by e.g. prtStat(clade('Lemmus_trimucronatus'),'p_M');.
Include the tree as well by e.g. [~, taxon] = clade('Lemmus_trimucronatus'); pedigree(taxon,'p_M').

Selection on eco-codes

A motivation for this type of selection could be to study ecological adaptations of parameter values. Selection on eco-codes is done with function select_eco. It allows selection for a single variable, and multiple codes in OR mode. Selection of all (terrestrial and marine) Antarctic species is done with select_eco('ecozone', {'MS','TS'}). Apart from the names of the entries, it returns selection identifiers (booleans) for the whole collection, allowing to combine the result with multiple calls to this function. For example all species in the collection that eat invertebrates (in some stage) and occur in the North-Atlantic are found with: [nm, s1]=select_eco('food',{'Ci'}); [nm,s2]=select_eco('ecozone',{'MAN'}); nm=select; nm(s1&s2). While food-code Cim selects for feeding on molluscs, entries with code Ci will not be selected, but some of them might eat molluscs as well. In reverse, entries with code Cim will be selected if Ci is specified, due to the hierarchical nature of the coding system. Codes for one particular entry my_pet can be extracted with function read_stat: eco = read_stat({my_pet}, 'ecoCode'); eco{1}. Possible variables and codes are given on the AmP ecology page. Although the codes for food and habitat have stage-identifiers, they are presently not used in select_eco. Print, e.g. the value of reproduction efficiency kap_R for all entries that are simultaneous hermaphrodite: prtStat(select_eco('gender','Hh'),'kap_R');

Selection on data types that were used for estimation

A motivation for this type of selection could be to study effects of data combinations on the estimation process. Entries with a particular combination of zero-variate and uni-variate data can be selected with function select_data. This selection can be restricted to particular typified models, which can be handy for preparing a predict-file for a new species, and for linking parameter values to source data types. The Matlab expression prtStat(select_data({'t-Le','Wwb'},'std'),'v'); prints entry names and their values for the energy conductance at 20 C for all entries with standard (std) models that have the data time-length for embryos as well as wet weight at birth.

Selection on strings in mydata and predict files

A motivation for this type of selection could be the question 'which entries have a changing (scaled) function response in time' and which of these entries have males and females with different parameters)? The answer involves select_predict, using the knowlegde that such predict files make use of the string 'f = spline1(t, tf)' and 'male', respectively. The required code is [species, nm] = select_predict('f = spline1(t, tf)'); select_predict(nm, 'males'). Notice that the default first argument of select_predict is absent in the first call (so 'Animalia' is assumed), but present in the second call. Similarly, select_mydata can be used for mydata files, e.g. to search for particular authors in references.

Selection in general

A general multi-step way of selecting entries on the basis of a variety of criteria is, e.g. mammals that have a COMPLETE score larger than 2.6: [sel_M,nm]=select_01('Mammalia');sel_C=read_allStat('COMPLETE')>2.6;nm=nm(sel_M&sel_C). Plot for those entries e.g. energy conductance as function of specific somatic maintenance pM_v=read_stat(nm,'p_M','v') with: Hfig=figure(1);plot(pM_v(:,1),pM_v(:,2),'or');. See entry names by clicking on points in this figure with: h=datacursormode(Hfig);h.UpdateFcn=@(obj,event_obj)xylabels(obj,event_obj,nm,pM_v);datacursormode on. Select terrestrial Arthropods with [sel_A nm]=select_01('Arthropoda'); [~,sel_T]=select_eco('habitat','T'); nm(sel_A&sel_T). (Notice that the stage-codes are not used in the selection, and that the result includes species that combine terrestrial with aquatic life stages.) Select North American freshwater fish with [sel_P,nm]=select_01('Pisces'); [~,sel_TH]=select_eco('ecozone','TH'); [~,sel_THp]=select_eco('ecozone','THp'); nm=nm(sel_P&sel_TH&~sel_THp). (Notice that the holarctic, TH, comprises the palearctic, THp, and the nearctic, THn. Selection for nearctic species would miss the holarctic ones. Although Pisces is not a clade (= natural taxon), so not a node in the tree, it can serve handy functions.) Since the selection-booleans that result from select, select_eco and select_data all have the same sequence of entries, the three types of selection can be combined.

select_mydata and select_predict have selection-booleans as third output, which can be used for more advanced and/or conditions. The code for answering the question 'which birds have males different from females or varying body temperature during development' could read [x,nm,sel_m]=select_predict('Aves','male'); [x,nm,sel_T]=select_predict(nm,'del_l'); nm(sel_m|sel_T).

Legend exploits selections

Spotting patterns in (functions of) parameters of entries starts with plot function shstat (see below; the name stands for "show statistics"), which has inputs data and legend (and optional further inputs).

A (marker) legend is a (n,2)-array of cells specifiying markers and taxa (= nodes and/or leaves as character strings) or eco-codes (as cell strings). A line legend, called llegend, does this for lines and taxa; it is used for 1-variate data, e.g. survivor functions. Several legends are available as input-free functions that output the required cell-array, such as legend_RSED and legend_fish. Customised legends can be composed by functions select_legend, select_legend_eco and select_llegend. Alternatively, you can copy the contents of a template, such as legend_RSED, and edit it. The result does not need to be a function; it can be just a variable in some function. The choice of possible taxa is restricted to the ones present in the lists-of-lists and that of eco-codes to the codes mentioned in AmPeco. Legends can be shown in a figure with DEBtool_M functions shlegend and shllegend. Please notice that the sequence of rows of marker legends matters, see shstat; this is a consequence of the fact that one taxon can contain another one.

Spotting patterns in data with legend

Function shstat can be used in symbolic mode for 1-, 2- and 3-variate data, as given in allStat. In this mode, shstat is using read_allStat to read in allStat; a large number of symbols for (functions of) parameters is available, following DEB notation. Functions of parameters that do not depend on food, called compound parameters, were computed with DEBtool_M function parscomp_st, and that do with statistics_st. These functions briefly describe the various variables, which are presented in context in the DEB book.

Function shstat can also be used in numerical mode in the case that computations are required, e.g. for functions of parameters that are not already in allStat. In this case, shstat does not read in allStat, but still links data to entries via legends. An ecocode legend is recognized by the cell-strings in the second column, while taxa appear as character-strings.

Markers in plots can be clicked to show the names of the corresponding entries. The script mydata_shstat gives examples of use of shstat and shows how items can be added to figures that have been produced by shstat. If markers in 3D plots do not have color specifications, the third variable is used to set the colors in the lava color scheme, see shcolor_lava, using color_lava.

Get a rapid overview of distributions of a number of (compound) parameters or statistics for selected taxa with compare_taxa. Plot (compound) parameters or statistics as function of normalised taxonomic distance with (computation-time intensive) function shstat_taxa. An example of the use of presentation tools of AmPtool is given in mydata_Cephalopoda; the resulting graphs have been published in KooyAugu2022.

Plotting with entries that are not (yet) in the AmP collection

Suppose that you have an entry locally, i.e. the file results_my_pet.mat that is created by estim_pars, but this entry is not yet in the collection and you want to see how the implied traits relate to the ones in the collection. Three actions need to take place in preparation
  • the species needs to be added to the lists-of-lists in AmPtool/taxa. This means that the genus of your entry needs to be added to its family-list, if it is not already there, and your species needs to be added to the genus-list. If the genus is also not already present, a new list for that genus needs to be created with your entry-name, which must have an underscore and no spaces. Some large families have subfamilies, or even tribes, meaning that your genus might need to be added there, rather than in the family-list. Likewise, if the family is not already in the lists-of-lists, it should be added to its order-list and a new family list should be created. Each taxon above the species-level should occur exactly 2 times in the lists-of-lists, once as member of a higher taxon and once as name of its own list. Check the successful addition to the lists-of-lists with function pedigree. Notice that these edits go lost if you reload AmPtool from GitHub.
  • your entry needs to be added to the local structures allStat and popStat. This can be done by running addEntryLoc. Make sure that your entry is added to the lists-of-lists before you run addEntryLoc and that the path to AmPdata has been set within Matlab. The addition to allStat and popStat is done with the default temperature for allStat, namely T_typical, and food is abundant, f=1; Use the entry-specific temperature correction factor, c_T and the temperature parameters, for other temperatures. Check the successful addition to allStat with load allStat; allStat.my_pet, where my_pet is replaced by the name of your entry. Notice that these edits go lost if you re-download AmPdata from the AmP-website, while AmPdata is changing frequently.
  • you possibly want to edit a legend to recognize your species in plots. Allthough the example templates like legend_RSED are functions that fill a variable, it can be a variable directly. Check the proper formulation of a legend with shlegend. Notice that you can always click on a point in a figure that is produced by shstat to see the name of the corresponding species.
Functions shstat, read_stat, read_popStat and read_allStat assume that the leaves (= endpoints, so the entry-names) of the lists-of-lists exactly correspond with the fields of allStat and popStat.

Linked websites

Function get_links can be used for the addresses of all websites, as specified in the mydata-file for that species; type get_links('Homo_sapiens', 1) to open them all in your system-browser. Function get_id does something similar, but gets the identifiers from the web, not from the AmP collection. The species name can be any valid one, known in CoL. This function might make use of get_synonym; it first tries the corresponding accepted name in CoL, then the name that the user provided and finally an alternative name, if provided by CoL. If the species cannot be found, it tries the genus for several websites. Notice that several websites have problems with finding species due to the inclusion of the subgenus in the name (of some genera). E.g. CoL cannot find 'Daphnia magna', only 'Daphnia (Ctenodaphnia) magna'.

The id-table gives an overview of all id's for all entries and supported websites. Click on a web-site column-header to let it disappear, and on the entry-header to let it re-appear.

Distances between species: Multi-dimensional scaling

Function dist_taxa computes the taxonomic distances between species (it is computational intensive), and dist_traits for trait-distances. A trait is here any parameter or function of parameters, as present in allStat, and the set of traits can be arbitrarily large, with optional weights. The distance-measure is the symmetric bounded or unbouded loss function. Tools for MultiDimensional Scaling (MDS) can be used to further analyse these distance matrices; Matlab has, for instance, function cmdscale for this purpose. The script AmPtool/mydata_mds_Carnivora gives an example for a selection of traits for the Carnivora, showing the use of shstat in this context and connecting clades members with connect_subclade.