Macro REGTOX documentation
Presentation
This Excel Macro is freely distributed with the moral obligation to cite its source whenever it is being cited. In conformity with the GNU public licence the source code is available and may be modified. Any improvement is welcomed and should be sent to the author Éric VINDIMIAN : Eric.VINDIMIAN@wanadoo.fr
The file is called REGTOX_evy.xls y depending on the version.
The images shown on this doc were drawn using REGTOX_EV7.0.xls
The models used
Toxicity dose-response models
Three toxicity dose-response models are used. The
common form is the following :
where p1 and p4 are the boundaries of the effect zone, p1 is the known or calculated response at zero dose and p4 is the effect expected for a dose tending towards infinity. The dose response curve is a monotonic function varying from p1 to p4.
X is the dose and f(x) is a probability function of the dose varying from 0 to 1 with the dose.
Model of Hill
The equation of Hill (1910) was described to model the binding of oxygen to haemoglobin. It was shown to be relevant for many other mechanisms like binding of a ligand to a receptor, michaelian or non michaelian enzymatic kinetics, dose or concentration response in toxicology and ecotoxicology (Vindimian 1983, Garric 1990). The logistic model is also used which is similar to the Hill model.
The model used in this macro is written in the form proposed by Duggleby in 1981. It fits different cases where the measurement of a biological parameter is plotted versus concentration or dose. Two parameters : Hill number and EC50, are characteristics of the probability function written as follows :
.
It should be noticed that f(x)=1/2 when x = EC50.
Model of Weibull
This model uses a function :
the parameters p2 and p3 have no specific biological meaning.
Model Log-Normal
This is the classical Gaussian normal law using log-transformed concentrations. EC50 is the average and s is the standard deviation.
Comparison of those three models
The next graph shows the three models fitted to the same data set : the algal toxicity test that can be found on the sheet named Tox in the macro file. The three model are almost confounded the Weibull model being slightly different from the other two.
Data treatment in ecotoxicolgy evolves. It is now possible to use the on line platform Mosaic. Mosaic calculate Ecx parameters for survival and reproduction using time. Regtox builds a data file which is compatible with Mosaic for reproduction data. Algal growth is assimilated to reproduction with one single mother cell. You may use this file at the URL : http://pbil.univ-lyon1.fr/software/mosaic/. The two following figures show the goodness of fit between Regtox and mosaic using the datafile from Regtox.
GENTOX model
For genotoxicity data, where in some cases a linear induction is observed followed by a toxic inhibition the model GENTOX is used. The induction phase is fitted to a straight line and the toxic phase uses a Hill equation. The sheet genotox shows an example of the calculation. The induction potential found is the slope at the origin of the induction phase. The equation is the following :
The corresponding graph is shown on the next figure. This graph shows the induction of a micronucleus in Barley roots, the control value is zero the first phase of the curve shows the induction of the micronuclei which is linear with concentration, then after toxicity occurs which inhibit the micronuclei induction.
How it works
The fitting is based on the algorithm of Marquardt (1963) which is robust and fast. It needs initial estimates of the parameters and optimise them by successive iterations. The software estimates the parameters by means of a linear aproximation of the curve, this initial estimation may be accepted or modified by the user.
The confidence intervals on the parameters are estimated by a bootstrap simulation which is entirely non parametric and is considered to be well adapted to non linear models (Efron 1990).
The results are expressed as the parameter values with their confidence intervals with two different significance levels. Five effect doses are given with their confidence intervals, the user may choose the effect levels. A graph is systematically drawn. The results are grouped on a sheet which may be printed or edited using the interactive facilities of Excel spreadsheet.
Installation and operating
The excel file contains the macro code, it need to be opened using Excel spreadsheet. The macro is called using the menu Tools/macro/macros and ran from this menu, the user should first open a sheet containing the experimental data in a matrix form. The following example comes from the sheet "tox" provided with the macro. The macro language is English or French. The first menu allows the choice of language.
The following screenshots illustrate the different steps of the calculation.
Interactive screens
Screen 1
This screen is seen after a series of warnings, it is the first interacting screen which allows you to enter data or parameters to the programme. You need to fill in the different boxes either with text or by selecting a range of cells in the data sheet :
Title : enter here a title or a reference to a set of cells within a single line containing the title.
Column or line of independent variable (X) : select the vector of X values here, it can be a column or a line but not a table.
Columns or lines of dependent variable (Y) : select the table of the effect observed with replicates, the values must correspond to the X vector each vector of replicates being on the same line or column than the corresponding X value. The number of replicates for each dose does not need to be constant. Missing values may be entered using a text format (missing, ND, -, etc). Attention should be paid to the fact that deleted values are shown as empty boxes but are given the value zero by Excel, this leads to unexpected errors, you should enter a text value rather than deleting any of the values.
Name of results sheet : enter here a name for the sheet where the results will be written, this name needs to be different from existing sheet names. Default name is the name of the sheet containing the data with the suffix _RESn added.
Model : select the model in this box. Refer to the model section of this document for explanation on the different models proposed.
Language : select here English or French. The chosen language will be set as a default.
Estimation of parameters : clic here when you are ready for the initial automatic estimation of the model parameters. You will then see the next sheet.
Screen 2
Parameter values boxes : each parameter is written in a box that you can edit if you want to change it. You may also ask for each parameter to be adjusted by the programme or impose it to a defined value. This is especially useful when you know some parameters, for instance if your data is expressed as an inhibition percentage you might want to impose the control to 0 and the maximum effect to 100%.
Optimise : clic here when you are happy with the parameter values and the adjustable/imposed set. The programme will then calculate the best estimates of the adjustable parameters in order to minimize the sum of squares of the deviations from the data to the model.
Sum of squares : indicates the sum of squares of deviations from the data to the curve using the estimation of parameters.
Simulations : you can enter here the number of bootstrap simulations for the calculation of confidence intervals. 500 is the default since it was shown to give good results. The calculation duration is directly proportional to this number.
Auto estimate : performs a new automatic estimation in case you own estimation is even worse than that of the programme.
Trace graph : allows you to redraw the graph to chack the quality of your estimation
Calculate sum squares : calculate the sum of squares to check the quality of your estimation.
Advanced : gives you access to the advanced programme parameter set that you may change using the next sheet if you are an experienced user of this macro. The values will be printed on the Def_par sheet in order to keep them as default values.
Sheet 3
This sheet shows the advanced parameters dialog box displayed after a clic on the advanced button in the parameters dialog box.
Algorithm optimization
Lambda : this parameter is used by the algorithm as a weight for the gradient. It should only be changed with care by users who known the algorithm of Marquardt, the default value has been optimized by a long series of trials on dose-response data sets.
Delta lambda : this value is used to change Lamba when the algorithm converges. At each iteration Lambda is divided by delta Lambda if the new set of parameters is a better estimate and multiplied otherwise.
Convergence criterion : this is the relative change of each parameter that is used to decide that the algorithm found the best parameter set. If this value is higher convergence is quicker but precision decreases. A lower value might get you in trouble since numeric precision comes close to this criterion. Again be careful when changing this value.
% confidence level 1&2 : these parameters allow you to set up the confidence intervals that you need, the default are 5% and 1% but you might like to get other values depending on your needs. However very low probabilities can only be achieved with very high number of simulations and as a consequence long calculations.
EDx/ECx : x values
The programme calculates a set of effective doses (or concentrations) for five defined x% of response. You may enter your own set of values here. These values will also be plotted on the graph.
Parameter names
In these boxes you may customize the names of the model parameters that you use.
Bootstrap parameters
Three different bootstrap parameters are proposed here. You may simulate the residues, weighted residues to take into account the evolution of variance with dose or bootstrap on the actual values for each dose.
Printing parameters
You may use comprehensive printing and print all the bootstrap parameters obtained or simplified printing which is only printing the results.
Result sheet
Screen 4
The following screen shows the data as it is written on the result sheet, it allows you to check the data that was used for the calculation.
Screen 5
Just below the data table a graph is given showing the data points and the dose-response curve with the EDx/ECx values. This graph is very important since it give a fast visualisation of the quality of fit. It may be edited using excel facilities and imported in a report or printed.
Screen 6
Below the graph a table shows the parameters values with their confidence intervals. The optimal values are those fitted using the original data, average and median values are those from the pseudo-distributions of parameters generated by the bootstrap simulation.
The DEF_PAR sheet
This sheet will be installed automatically on your workbook, it allow to keep your own parameters. When you are used with running the macro you may edit directly the values within this sheet. It is quicker than using the Advanced parameters function, but you need to be careful not to insert lines or change the format of the values entered.
In case of a problem, just suppress this sheet and run the macro again, a new default one will be created.
Références
Efron B. (1981) Non parametric estimates of standard error : the jacknife, the bootstrap and other methods. Biometrika, 68, 589-599.
Duggleby R.G. (1981) Anal. Biochem. 110, 9
Garric J. Migeon B. & Vindimian E. (1990) Lethal effects of draining on brown trout. A predictive model based on field and laboratory studies. Wat. Res. 24, 59-65.
Hill A.V. (1910) The possible effects of aggregation of the molecules of hemoglobin on its dissociation curves. J. Physiol. (Lond.) 40, IV-VII.
Marquardt D.W. (1963) An algorithm for least squares estimation of non linear parameters. J. Soc. Indus. Appl. Math. 11, 431-441.
Vindimian E. Robaut C. & Fillion G. (1983) A method for cooperative and non cooperative binding studies using non linear regression analysis on a microcomputer. J. Appl. Biochem. 5, 261-268.