PRECOND user guide PsN 4.4.8 Revised 2015-04-17 1 Introduction In order to increase the numerical stability of the variance covariance matrix computation, the precond script creates and runs a linearly re-parameterised model of the original model that is less sensitive to rounding errors. We refer to this process as preconditioning and the created model as the preconditioned model. Through numerical experiments[1] using published nonlinear mixed effect models, it has been found that the preconditioning can reduce the computational environment dependency, increase the chance of successful covariance computation, and unveil un-identifiability of the model parameters. Preconditioning will automatically first run the model normally and if the covariance step fails get the R-matrix from that run using that to precondition the model. Obtained R-matrix is decomposed using eigendecomposition and used to linearly re-parameterise the model in a way that the R-matrix of the preconditioned model is close to an identity matrix. This will reduce the influence of the rounding error for the computation of R matrix and often avoid the R-matrix appearing to be non-positive semi-definite. The precond script will initiate the modelfit of the preconditioned model and then convert back the obtained estimated parameter and covariance matrix to the parameter scale of the original model. Preconditioning can also be used for the modelfits with successful covariance step to verify that the resulting computation is not influenced by the computational error. 1 Preconditioning of the model will only help to stabilise the computation so that if the model is fundamentally unidentifiable (or have other issues) then the covariance step of the preconditioned model should not be successful. Example precond run1.mod 2 2.1 Input and options Required input The only required argument is a model file. 2.2 Optional input -always With this option, the preconditioning will be conducted regardless of if the covariance step of the original model is successful or not. Using this option and comparing raw_results_<modelname>.csv and base_raw_results.csv, we can observe how much the result of the standard error calculation is influenced by the computation instability. In addition by comparing the ofv and the estimated parameters appearing in raw_results_<modelname>.csv and base_raw_results.csv, if the model is not identifiable, one may find two different sets of parameters with the same maximised likelihood. -pre = precond_dir1 With this option the user can also specify a directory. If the modelfit directory is specified then the R-matrix is automatically extracted. If precond directory is specified then we can precondition the already preconditioned model. This will allow us to iteratively precondition deeply ill-conditioned model. In order for the iterative preconditioning to work properly, “precMatrix" file should be unmodified and available in the specified precond directory. 2 -pre = run1.rmt With this option the user can manually specify the R-matrix that will be used for preconditioning. In addition, a modelfit directory created by the execute command of PsN can be specified and R-matrix will be extracted from the directory. In addition, any symmetric matrix can be provided as a .csv file or NONMEM matrix file; however, the specified matrix needs to be similar to R-matrix to improve the computational stability (i.e., using covariance matrix will reduce the computational stability). -update_model = filename Copy the model with updated inital thetas to your work directory 2.3 Optional input for methodological research -cholesky Use cholesky decomposition of the preconditioning matrix instead of eigendecomposition. With this option the preconditioning matrix provided by -pre option should be similar to variance covariance matrix or the inverse of R matrix. (i.e., R matrix should not be used with this option) -cov = result.cov This option will break the normal execution flow and only perform a conversion of a covariance matrix of the preconditioned model to the covariance matrix of the original model. If this option is set no model will be run. -eigen_comp_only With this option, precond will not execute any NONMEM run. It will only compute the eigenvalues of the matrix that were to be used for the preconditioning. Use this option with -verbose option. -lu Use LU decomposition of the preconditioning matrix instead of eigendecomposition. With this option the preconditioning 3 matrix provided by -pre option should be similar to variance covariance matrix or the inverse of R matrix. (i.e., R matrix should not be used with this option) -nodec Turn off decomposition of preconditioning matrix. -output_model = run1_repara.mod This option will break the normal execution flow and have precond only create the preconditioned model without running it. The model will be created with the specified name. -perturb After the model is preconditioned the initial estimate is perturbed to the direction of the eigenvector that is corresponding negative eigenvalue of the R-matrix. This will increase the chance of finding the final parameter estimate that is not at the saddle point so that the R-matrix of the preconditioned model will be a positive semi-definite matrix. -verbose Print the eigenvalues of the matrix that will be used to precondition the model. -rawres_input = filename Create the preconditioning matrix from the supplied raw_results file. -offset_rawres = N Only relevant in combination with -rawres_input. Default 1. The number of result lines to skip in the input raw results file before starting to read final parameter estimates. In a regular bootstrap raw_results file, and also in an initial_estimates.csv file from an sse run, the first line of estimates refers to the input model with the full dataset, so therefore the default offset is 1. -in_filter = comma separated list of conditions Only relevant in combination with -rawres_input. Default not used. The parameter estimates lines in the file can be filtered 4 on values in the different columns. When specifying which column(s) the filtering should be based on, the exact column name must be used, e.g. minimization_successful. Filtering can only be based on columns with numeric values. The allowed relations are .gt. (greater than), .lt. (less than) and .eq. (equal to). If the value in the filter column is ’NA’ then that parameter set will be skipped, regardless of the defined filter relation. Conditions are separated with commas. If the remaining number of lines after filtering is smaller than -samples, sse will stop with an error message. Then the user must either change the filtering rules or change -samples. If the user has created a file with parameter estimates outside of PsN, filtering can be done on any numeric column in that file. Do not set column headers containing .eq. or .lt. or .gt. in the user-generated file as this would interfere with the in_filter option syntax. 3 Output Output of the first normal run will copied as if running a regular execute to the model directory. The raw_results can be found in the precond directory under the name base_raw_results.csv If the preconditioning step was run the results from that run will not be copied to your model directory but can be found in the precond directory: • The covariance matrix of the preconditioned run can be found in the <modelname>.cov file • Rawresults of the precondition run with parameters on the original scale are in the raw_results_<modelname>.csv • A copy of the model with updated initial estimates can be found in updated_model.mod In the terminal window, the precond script printout the condition number of the R matrix that will be used to precondition. A larger condition number means a more computationally unstable original model. If the covariance step of the preconditioned model fails then the precond script will display the eigenvalues of the R matrix of the preconditioned model with the condition number and number of negative eigenvalues. 5 4 Known issues • The current implementation cannot handle the model file with $MIX record. • Preconditioning does not honour the original parameter bounds hence the NONMEM run can fail if there are some implicit assumption on the range of the parameters. For the parameters that need to be positive (or negative) we suggest the users to absolute value of the parameter, e.g., abs(THETA(1)). • The current implementation of precond script only precondition THETA variables, if the user wishes to precondition also the ETA and EPS variables, we suggest the users to code ETA and EPS variables using THETA, e.g., THETA(11)*EPS(1), $SIGMA 1 FIX. • Using the option $COV MATRIX=R in the model will currently not work. The user can use PRINT=R option to obtain R matrix and then calculate 2R−1 outside of NONMEM (e.g., using R). 5 Actions if covariance step fails when preconditioning • If covariance matrix cannot be obtained, run precond script with -pre=precond_dir1 option. Every time the covariance matrix cannot be obtained through preconditioning, a message on the command line would suggest the next option to try. In addition, after every preconditioning, compare the raw_results files in the original model fit directory and the precond directory to make sure that OFV and esimated parameters are approximately the same. If OFVs are similar and a parameter is significantly different, then the model is most likely to be an unidentifiable model and no further attempt to obtain the covariance matrix should be made. 6 6 Description Below is a simple diagram of the internal automated precond workflow. Some automatic minor modifications of the model will be made before precond will do its first run to make sure that the R-matrix will be created. 7 add COV, PRINT=R, FORMAT and UNCONDITIONAL to model run model covariance step successful? no get R-matrix from run precondition model done yes 8 References [1] Yasunori Aoki, Rikard Nordgren and Andrew C. Hooker, Preconditioning of Nonlinear Mixed Effect models for Stabilization of the Covariance Matrix Computation, 2015, PAGE. Abstracts of the Annual Meeting of the Population Approach Group in Europe, www.page-meeting.org/?abstract=3583 9

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement