+--------------------------------------------------------------------+
 |                                                                    |
 |                      MODEL SPECIFICATION FILE                      |
 |                                                                    |
 +--------------------------------------------------------------------+

 MEANING: A NONMEM output and input file
 CONTEXT: NONMEM input/output file

 DISCUSSION:
 A Model Specification File (MSF) can be output by NONMEM.  It includes
 information from the Estimation Step  (initial  estimate  information,
 current  (or final) estimate information, search information) and from
 the Covariance Step (if this step is implemented).  It is requested in
 a certain field of the ESTIMATION control record (or, with NM-TRAN, by
 an option of the $ESTIMATION record).  NONMEM will use the information
 in the MSF in a later problem, either to continue the parameter search
 if the search did not terminate in the  current  run,  or  to  perform
 other  tasks  that  will  be based on final parameter estimates in the
 MSF.  These other tasks can be Simulation, Covariance, Table, Scatter-
 plot,  or  Finalization  Steps.   If the MSF contains the results of a
 search that terminated successfully,  even  an  additional  Estimation
 Step  can be performed, using the final parameter estimates in the MSF
 as initial estimates and an estimation method other than the one  used
 in  the  problem  with which the MSF was output.  If an MSF is output,
 and intermediate output with iteration summaries  is  requested,  then
 NONMEM  also writes the parameter estimates of these summaries to file
 INTER.

 MSF files are often used because they eliminate  needless  duplication
 of  computation  that has already occurred in the Estimation Step of a
 previous run.  If there should be a computer crash during or after the
 Estimation  Step  of  the previous run and a MSF was output, then with
 the current run, the MSF can be input, and the Estimation Step of  the
 current  run  will  continue  the  search begun with the previous run,
 starting from the last iteration whose summary was output  before  the
 crash occurred.

 With  NM-TRAN, specification that an existing Model Specification File
 is to be input is done by placing the file's name on the $MSFI record.

 With NONMEM 7.3, when MSF or MSFO option is used to  specify  an  MSFO
 file in the $EST record e.g.,
 $EST ... MSFO=msfroot.msf
 then  in addition to the main MSF file msfroot.msf, an extra file msf-
 root_ETAS.msf will also be produced, and provide  additional  informa-
 tion  when  a  $MSFI record is used in a subsequent problem or control
 stream.  File msfroot_ETAS.msf contains individual etas and phis  gen-
 erated  during  estimation  (except FO method, which does not generate
 non-zero etas during estimation, and not POSTHOC evaluated etas.)  The
 use  of  an  extension  in the file name, e.g., .msf, is optional.  If
 file _ETAS does not exist, NONMEM issues a warning, e.g.,

  WARNING: EXTRA MSF FILE COULD NOT BE OPENED: c5msf2x_ETAS

 If  the  Covariance  Step  is  also  implemented,  extra  files   msf-
 root_RMAT.msf and msfroot_SMAT.msf containing intermediate information
 on the R matrix and S matrix will also be produced.  These files  pro-
 vide  information  when  a  $MSFI  record along with a $COV ... RESUME
 record is used in a subsequent problem or control stream.  There is no
 warning if files _SMAT and/or _RMAT are missing.

 EXAMPLE OF USAGE:

 Here is an example using NM-TRAN. A fragment of the control stream for
 the first run follows.  The Estimation Step is run for a limited  num-
 ber of evaluations of the objective function (200).

 $THETA  (.1,3,5) (.008,.08,.5) (.004,.04,.9)
 $OMEGA BLOCK(3)  6 .005 .0002 .3 .006 .4
 $SIGMA  .4
 $EST     MAXEVAL=200  PRINT=5 MSFO=msf1

 After  review  of  the  first  run's  output, it is decided to let the
 search continue.  The continuation will start from the iteration  dur-
 ing which the 200th objective function evaluation occurred in the pre-
 vious search.  A fragment of the control stream  for  the  second  run
 follows.   $THETA,  $OMEGA,  and  $SIGMA  need  not,  and  may not, be
 present.  The Estimation Step is allowed to  run  to  completion,  and
 standard  errors  and  a  table are requested.  A new MSF is obtained,
 which will allow additional tables and  scatterplots  to  be  obtained
 later.

 $MSFI msf1
 $EST PRINT=5 MSFO=msf2
 $COV
 $TABLE ID TIME

REFERENCES: Guide I Section B.3
REFERENCES: Guide IV Section III.B.12


  
Go to main index.
  

    Created by nmhelp2html v. 1.0 written by Niclas Jonsson (Modified by AJB 5/2006,11/2007,10/2012)