AmPtool contains Matlab functions for the visualisation and analysis of patterns in (functions of) parameter values of the Add-my-Pet (AmP) collection. It is an extension of DEBtool_M, and makes frequent use of it. All parameters and traits, population traits and eco-codes for all entries are available in dropdown COLLECTION/AmPdata as a zip-file. Save the files allStat.mat and popStat.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; 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.


All data (i.e. meta-data, parameters, meta-parameters, implied traits, but no empirical data) of all entries are 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] = read_allStat('t_g','c_T'); tg_Tref = var(:,1).*var(:,2); and print to screen with printpar(nm, tg_Tref). 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 are 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.

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. 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. 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.

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: [s1,nm]=select_01('Mammalia');s2=read_allStat('COMPLETE')>2.6;nm=nm(s1&s2). 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 North American freshwater fish with [sel,nm]=select_01('Pisces'); [~,sel_TH]=select_eco('ecozone','TH'); [~,sel_THp]=select_eco('ecozone','THp'); nm=nm(sel&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 sel1] = select_predict('Aves','male'); [x nm sel2] = select_predict(nm,'del_l'); nm(sel1|sel2).

Legends exploit 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. 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 legends

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.

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 function shstat_taxa.

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.