html/scm_docs.php

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4   <title>PsN :: Documentation :: scm</title>
   5 <!--Adobe(R) LiveMotion(TM) 1.0 Generated JavaScript. Please do not edit. -->
   6   <script>
   7 <!--
   8 function newImage(arg) {
   9 if (document.images) {
  10 rslt = new Image();
  11 rslt.src = arg;
  12 return rslt;
  13 }
  14 }
  15 ImageArray = new Array;
  16 var preloadFlag = false;
  17 function preloadImages() {
  18 if (document.images) {
  19 ImageArray[ImageArray.length++] = newImage(/* OWNER('object', 'dflt') *//*URL*/'images/indexhome.jpg');
  20 ImageArray[ImageArray.length++] = newImage(/* OWNER('object', 'movr') *//*URL*/'images/indexhomeov.jpg');
  21 ImageArray[ImageArray.length++] = newImage(/* OWNER('object1', 'dflt') *//*URL*/'images/indexdocumentation.jpg');
  22 ImageArray[ImageArray.length++] = newImage(/* OWNER('object1', 'movr') *//*URL*/'images/indexdocumentationov.jpg');
  23 ImageArray[ImageArray.length++] = newImage(/* OWNER('object2', 'dflt') *//*URL*/'images/indexdownload.jpg');
  24 ImageArray[ImageArray.length++] = newImage(/* OWNER('object2', 'movr') *//*URL*/'images/indexdownloadov.jpg');
  25 ImageArray[ImageArray.length++] = newImage(/* OWNER('object3', 'dflt') *//*URL*/'images/indexbuglist.jpg');
  26 ImageArray[ImageArray.length++] = newImage(/* OWNER('object3', 'movr') *//*URL*/'images/indexbuglistov.jpg');
  27 ImageArray[ImageArray.length++] = newImage(/* OWNER('object4', 'dflt') *//*URL*/'images/indexmailing_list.jpg');
  28 ImageArray[ImageArray.length++] = newImage(/* OWNER('object4', 'movr') *//*URL*/'images/indexmailing_listov.jpg');
  29 preloadFlag = true;
  30 }
  31 }
  32 function changeImages() {
  33 if (document.images && (preloadFlag == true)) {
  34 for (var i=0; i<changeImages.arguments.length; i+=2) {
  35 document[changeImages.arguments[i]].src = changeImages.arguments[i+1];
  36 }
  37 }
  38 }
  39 // -->
  40   </script><!-- End generated JavaScript. -->
  41   <meta http-equiv="Content-Type"
  42  content="text/html; charset=ISO-8859-1">
  43   <?php
  44      include("styles.php");
  45   ?>
  46   <script language="JavaScript" type="text/JavaScript">
  47 <!--
  48 function MM_reloadPage(init) { //reloads the window if Nav4 resized
  49 if (init==true) with (navigator) {if ((appName=="Netscape")&&(parseInt(appVersion)==4)) {
  50 document.MM_pgW=innerWidth; document.MM_pgH=innerHeight; onresize=MM_reloadPage; }}
  51 else if (innerWidth!=document.MM_pgW || innerHeight!=document.MM_pgH) location.reload();
  52 }
  53 MM_reloadPage(true);
  54 //-->
  55   </script>
  56   <meta content="Pontus Pihlgren" name="author">
  57 </head>
  58 <body onLoad="preloadImages();"
  59  style="background-color: rgb(255, 255, 255);">
  60 <!-- The table is not formatted nicely because some browsers cannot join images in table cells if there are any hard carriage returns in a TD. -->
  61 <div id="Layer1"
  62  style="position: absolute; left: 335px; top: 42px; width: 388px; height: 43px; z-index: 1; font-size: x-small;">
  63 <div class="style1" align="right">Stepwise
  64 Covariate Modeling (<span style="font-family: monospace;">scm</span>)<br>
  65 </div>
  66 </div>
  67 <div id="Layer2"
  68  style="position: absolute; left: 226px; width: 497px; z-index: 2; top: 188px; height: 1110px;">
  69 <div align="justify">
  70 <?php
  71 include("scm_synopsis.php");
  72 include("scm_description.php");
  73 php?>
  74 <p class="heading2">Valid states for the parameter-covariate relations</p>
  75
  76 <p>The SCM tool in PsN is written to be flexible in the shape of the
  77 parameter-covariate relations. Currently there is a fixed set of
  78 available forms of relations but there is ongoing development aiming
  79 at full flexibility for the user with regard to relation-shape
  80 definitions.</p>
  81
  82 <p>The avaialable shapes or <em>states</em> for the
  83 parameter-covariate relations for continuous covariates are (1) not
  84 included, (2) included as a linear relation and (3) included as a
  85 piece-wise linear relation with two slopes. </p>
  86
  87 <p>Categorical covariates are either (1) not included or (2) included with an extra parameter added for each but the most common category. </p>
  88 <p>The figures, 1, 2 and 3, are used when specifying included relations below. </p>
  89 <?php
  90 include("scm_options.php");
  91 include("scm_examples.php");
  92 php?>
  93
  94 <h3 align="left" class="heading1">SCM configuration file options</h3>
  95
  96 <span class="heading2">General considerations</span>
  97
  98 <p>The syntax of the simple options is just the name of the option
  99 followed by the equal sign and a valid value for the option. For
 100 example:</p>
 101
 102 <p class="option">retries=5</p>
 103 <p>This states that a maximum of 5 retries will be used in the executions. </p>
 104 Some options accept Perl code:
 105 <p><span class="option">base_criteria_values={ ofv =&gt; -9571.234}</span> </p>
 106 Other take comma-separated lists:
 107 <p><span class="option">continuous_covariates=AGE,WT,ALBU,BILI,AST,ALT,ALKP,POT,MAG,CA,NA,TOTP</span></p>
 108
 109 Some options don't accept a value on the command line. They set the
 110 behavior of the utility simply by being specified or not. In the
 111 configuration file these options need to be followed by 1 or a 0. A 1
 112 indicates that it is used and a 0 that it is not used.
 113
 114 <p class="option">fix=1</p>
 115 You can place a comment anywhere in the file by prefixing the line with a semicolon:
 116 <p><span class="option">;ask_if_fail=0</span></p>
 117 If an option is long you can break the line with a backslash, just a linebreak will not work:
 118 <p class="option">categorical_covariates=SEX,ARR,SHD,NYHA,RACE,ALCO,SMOK,BETA,CGLY,LDIU,\<br>
 119   TDIU,CANT,ACE,NITR,ACOA,POTA,TWOC,TREA,TWOD,INDU,\<br>
 120   TUBS,ALQT,ANTP,ANTD,ANTM,ANTH,ANTB,SULP,ANT1,CLIA,\<br>
 121   CLIB,CLIC,CL3,CIME,METF,FENM,PROC,HEP1,HEP2,HEP3 </p>
 122
 123 <p class="heading2">Simple options</p>
 124
 125 The simple options are the SCM specific command line options and the
 126 command line options common to all PsN Utilties.
 127
 128 <p class="heading2">List options</p>
 129
 130 List options are options that take enumerations of values like the
 131 <span class="option">categorical_covariates</span> option:
 132
 133 <p class="option">categorical_covariates=SEX,ARR,SHD,NYHA,RAC<p>
 134
 135 The list options valid in the configuration file are:
 136
 137 <p class="option">categorical_covariates</p>
 138
 139 The <span class="option">categorical_covariates</span> list option is
 140 neccessary for the scm to know which type of NONMEM code to generate
 141 for the parameter covariate relation.
 142
 143 <p class="option">continuous_covariates</p>
 144
 145 The <span class="option">categorical_covariates</span> list option is
 146 neccessary for the scm to know which type of NONMEM code to generate
 147 for the parameter covariate relation.
 148
 149 <p class="option">do_not_drop</p>
 150
 151 If the dataset used with the scm is to wide, scm will drop the data
 152 columns that correponds to covariate which is not used in a particular
 153 step. However, if you have used that covariate in code that is not
 154 affected by the scm, NONMEM will produce an error. Therefore it is
 155 neccessary for you to specify which those covariates are, using the
 156 <span class="option">do_not_drop</span> list option.
 157
 158 <p class="option">extra_files</p>
 159
 160 If you need some extraordinary file to be copied into the NONMEM
 161 execution directory, specify them with the <span
 162 class="option">extra_files</span> list option.
 163
 164 <p class="heading2">Code options</p>
 165
 166 Code options are almost like a Simple option. With the difference that
 167 the right side is evaluted by the perl interpretor. If you don't
 168 understand the difference, it is probably not important. However, it
 169 is available for a reason. The SCM have hooks for custom goodness of
 170 fit functions. Those functions may need some special input data. And
 171 for flexibility, we allow that data to be just about anything, the
 172 side effect is that it becomes to complex for the configuration file
 173 structure. The solution is to allow options that are small Perl
 174 programs. Those options we refer to as code options.
 175
 176 <p class="option">base_criteria_values</p>
 177
 178 The <span class="option">base_criteria_values</span> overrides default
 179 criterias for the goodness of fit function used. The default goodness
 180 of fit function takes its base_criteria_value to be the ofv of the
 181 initial model. If you would like to change the base ofv to 400 you
 182 would write:
 183
 184 <p class="option">base_criteria_values= { ofv => 400 } }</p>
 185 <p class="heading2">Composite options </p>
 186
 187 <p>The composite options can not be specified on the command line. An
 188 exception is the <span class="option">extra_data_files</span> option
 189 which is valid for all utilities. A composite option section starts
 190 with an option header followed by a set of lines with a left side, an
 191 equal sign and a right side.  </p>
 192 <!--
 193 hash:
 194         $this -> {'ofv_backward'} = defined $parm{'ofv_backward'} ? $parm{'ofv_backward'} : {} unless defined $this -> {'ofv_backward'};
 195         $this -> {'ofv_change'} = defined $parm{'ofv_change'} ? $parm{'ofv_change'} : {} unless defined $this -> {'ofv_change'};
 196         $this -> {'ofv_forward'} = defined $parm{'ofv_forward'} ? $parm{'ofv_forward'} : {} unless defined $this -> {'ofv_forward'};
 197 -->
 198 <dl>
 199
 200   <dt><b>extra_data_files</b></dt>
 201
 202   <dd>The <span class="option">-extra_data_files</span> option is used
 203       to specify files with extra data. As NONMEM only accepts 20
 204       columns, it is sometimes necessary to split data files. The left
 205       side of each line holds the extra data file name. The right side
 206       is a comma-separated list of the column headers.
 207     <p><span class="option">[extra_data_files]<br>
 208       sub.dta=ID,GRP,AGE,SEX,ARR,SHD,NYHA,LVEF,WT,HT,RACE,ALCO,SMOK,BETA</span><br>
 209     </p>
 210   </dd>
 211
 212   <dt><b>test_relations</b></dt>
 213
 214   <dd><span class="option">The -test_relations </span>option is used
 215       to specify what parameter-covariate relations the scm utility
 216       will test. The left side of each row is a parameter name and the
 217       right side is a comma separated list of covariates.
 218
 219     <p class="option">[test_relations]<br>
 220       CL=AGE,SEX,ARR,SHD,NYHA,WT,RACE,ALCO,SMOK,BETA,\<br>
 221           ALBU,BILI,AST,ALT,ALKP,POT,MAG,CA,NA,TOTP, \<br>
 222           ANT1,CLIA,CLIB,CLIC,CL3,CIME,METF,PROC<br><br>
 223           V=SEX,WT,ALBU,TOTP,LDIU,TDIU,ACOA,SULP<br></p>
 224   </dd>
 225
 226   <dt><b>included_relations</b></dt>
 227
 228   <dd>If you want to start the search with some relations included you
 229       can add them to the <span
 230       class="option">included_relations</span>.  The left side of each
 231       row holds the name of a parameter and the right side a list of
 232       covariates. For each covariate you can specify a relation
 233       state. The general syntax is <span class="option">COV-X</span>
 234       where COV is you covariate and X is the state.  If the state is
 235       omitted it will be set to 2.
 236
 237     <p><span class="option">[included_relations]<br>
 238       CL=TDIU-2,CLIA-2,SEX-2<br>
 239       V=WT,ACOA-2,SEX-3,TOTP</span><br>
 240     </p>
 241   </dd>
 242
 243   <dt><b>valid_states</b></dt>
 244
 245   <dd>You can specify what states you want the SCM to test. By default
 246       it tests three states. 1 - not included, 2 - linear, 3 -
 247       piecewise linear and 4 - exponential parameterization.  The
 248       valid states are specified for separately continuous and
 249       categorical covariates.
 250
 251     <p class="option">[valid_states]<br>
 252           categorical=1,2<br>
 253           continuous=1,2,3</p>
 254   </dd>
 255
 256   <dt><b>code</b></dt>
 257
 258   <dd>If you are not satisfied with the state specific NONMEM code
 259       generated by the scm, you can overide it using the code
 260       option. It lets you specify code for specific parameters,
 261       specific paramater - covariate relations and even specific
 262       states. Each line under the <span class="option">[code]</span>
 263       header defines code for one parameter - covariate - state
 264       relation. Like this:
 265
 266       <p class="option">[code]<br>
 267           CL:WT-1=THETA(1)</p>
 268
 269       This will change the default code for state 1 of the CL - WT
 270       relation. You can also use wildcards to redefine the code for
 271       multiple relations:
 272
 273       <p class="option">[code]<br>
 274           CL:*-1=THETA(1)</p>
 275
 276       In this example you will redefine the code for all covaritates
 277       in a relation with CL.
 278
 279       <p class="option">[code]<br>
 280           *:*-1=THETA(1)</p>
 281
 282       This example will redefine the code for all relations in state
 283       1. Notice that you can not use a wildcard for the state.
 284       <p>
 285       Generally it is useful to include the parameter and/or the
 286       covariate in the code. So to make it possible when using
 287       wildcards you can use the generic variables PARM and COV which
 288       will be replaced with the parameter and covariate in question
 289       for the current relation.
 290
 291   </dd>
 292   <dt><b>lower_bounds, upper_bounds and inits</b></dt>
 293
 294   <dd>The inits and bounds option lets you set initial estimates for
 295       thetas introduced in the code and their corresponding bounds.  A
 296       hockeystick relation introduces two new thetas, so to set the
 297       thetas value and bounds for the CL - WT relation you would
 298       write:
 299
 300       <p class="option">[lower_bounds]<br>
 301          CL:WT-2=0.1, 0.05</p>
 302
 303       <p class="option">[upper_bounds]<br>
 304          CL:WT-2=0.3, 0.08</p>
 305
 306       <p class="option">[inits]<br>
 307          CL:WT-2=0.15,0.07</p>
 308
 309       This would correspond to the following lines in a NONMEM modelfile:
 310
 311         <p class="option">THETA(1) = 0.1,0.15,0.4<br>
 312           THETA(2) = 0.05,0.07,0.08</p>
 313
 314       Just like in the code option you can use wildcards. Notice that
 315       if you specify to few or to many values, those you exclude will
 316       be replaced by defaults and the extraneous will be ignored.
 317
 318    </dd>
 319
 320
 321 </dl>
 322
 323 <p></p>
 324 <h3 class="heading1">Output</h3>
 325 <h4>Result file</h4>
 326 Currently, the logfile is the best place to look for the results from the scm utility.
 327 <h4>&nbsp;</h4>
 328 <p></p>
 329 </div>
 330 <p align="justify">&nbsp;</p>
 331 </div>
 332 <table border="0" cellpadding="0" cellspacing="0" width="780">
 333   <tbody>
 334     <tr>
 335       <td height="600" width="780">
 336       <table border="0" cellpadding="0" cellspacing="0" width="780">
 337         <tbody>
 338           <tr>
 339             <td colspan="7" height="201" width="780"><img
 340  src="images/indexpane1_1_.jpg" name="" alt="" border="0" height="201"
 341  width="780"></td>
 342           </tr>
 343           <tr>
 344             <td height="46" width="26"><img
 345  src="images/indexpane1_2_.jpg" name="" alt="" border="0" height="46"
 346  width="26"></td>
 347             <td height="46" width="73"><a href="index.php"
 348  onmouseover="changeImages(/*CMP*/ 'object', /*URL*/ 'images/indexhomeov.jpg'); return true;"
 349  onmouseout="changeImages(/*CMP*/ 'object', /*URL*/ 'images/indexhome.jpg'); return true;"><img
 350  src="images/indexhome.jpg" name="object" alt="Home" border="0"
 351  height="46" width="73"></a></td>
 352             <td height="46" width="11"><img
 353  src="images/indexpane3_2_.jpg" name="" alt="" border="0" height="46"
 354  width="11"></td>
 355             <td height="46" width="25"><img
 356  src="images/indexpane4_2_.jpg" name="" alt="" border="0" height="46"
 357  width="25"></td>
 358             <td height="46" width="15"><img
 359  src="images/indexpane5_2_.jpg" name="" alt="" border="0" height="46"
 360  width="15"></td>
 361             <td height="46" width="40"><img
 362  src="images/indexpane6_2_.jpg" name="" alt="" border="0" height="46"
 363  width="40"></td>
 364             <td height="46" width="590"><img
 365  src="images/indexpane7_2_.jpg" name="" alt="" border="0" height="46"
 366  width="590"></td>
 367           </tr>
 368           <tr>
 369             <td colspan="7" height="7" width="780"><img
 370  src="images/indexpane1_3_.jpg" name="" alt="" border="0" height="7"
 371  width="780"></td>
 372           </tr>
 373           <tr>
 374             <td height="46" width="26"><img
 375  src="images/indexpane1_4_.jpg" name="" alt="" border="0" height="46"
 376  width="26"></td>
 377             <td colspan="5" height="46" width="164"><a href="docs.php"
 378  onmouseover="changeImages(/*CMP*/ 'object1', /*URL*/ 'images/indexdocumentationov.jpg'); return true;"
 379  onmouseout="changeImages(/*CMP*/ 'object1', /*URL*/ 'images/indexdocumentation.jpg'); return true;"><img
 380  src="images/indexdocumentation.jpg" name="object1" alt="Documentation"
 381  border="0" height="46" width="164"></a></td>
 382             <td height="46" width="590"><img
 383  src="images/indexpane7_4_.jpg" name="" alt="" border="0" height="46"
 384  width="590"></td>
 385           </tr>
 386           <tr>
 387             <td colspan="7" height="7" width="780"><img
 388  src="images/indexpane1_5_.jpg" name="" alt="" border="0" height="7"
 389  width="780"></td>
 390           </tr>
 391           <tr>
 392             <td height="46" width="26"><img
 393  src="images/indexpane1_6_.jpg" name="" alt="" border="0" height="46"
 394  width="26"></td>
 395             <td colspan="3" height="46" width="109"><a
 396  href="download.php"
 397  onmouseover="changeImages(/*CMP*/ 'object2', /*URL*/ 'images/indexdownloadov.jpg'); return true;"
 398  onmouseout="changeImages(/*CMP*/ 'object2', /*URL*/ 'images/indexdownload.jpg'); return true;"><img
 399  src="images/indexdownload.jpg" name="object2" alt="Download" border="0"
 400  height="46" width="109"></a></td>
 401             <td colspan="3" height="46" width="645"><img
 402  src="images/indexpane5_6_.jpg" name="" alt="" border="0" height="46"
 403  width="645"></td>
 404           </tr>
 405           <tr>
 406             <td colspan="7" height="7" width="780"><img
 407  src="images/indexpane1_7_.jpg" name="" alt="" border="0" height="7"
 408  width="780"></td>
 409           </tr>
 410           <tr>
 411             <td height="46" width="26"><img
 412  src="images/indexpane1_8_.jpg" name="" alt="" border="0" height="46"
 413  width="26"></td>
 414             <td colspan="2" height="46" width="84"><a href="buglist.php"
 415  onmouseover="changeImages(/*CMP*/ 'object3', /*URL*/ 'images/indexbuglistov.jpg'); return true;"
 416  onmouseout="changeImages(/*CMP*/ 'object3', /*URL*/ 'images/indexbuglist.jpg'); return true;"><img
 417  src="images/indexbuglist.jpg" name="object3" alt="Buglist" border="0"
 418  height="46" width="84"></a></td>
 419             <td colspan="4" height="46" width="670"><img
 420  src="images/indexpane4_8_.jpg" name="" alt="" border="0" height="46"
 421  width="670"></td>
 422           </tr>
 423           <tr>
 424             <td colspan="7" height="7" width="780"><img
 425  src="images/indexpane1_9_.jpg" name="" alt="" border="0" height="7"
 426  width="780"></td>
 427           </tr>
 428           <tr>
 429             <td height="46" width="26"><img
 430  src="images/indexpane1_10_.jpg" name="" alt="" border="0" height="46"
 431  width="26"></td>
 432             <td colspan="4" height="46" width="124"><a href="list.php"
 433  onmouseover="changeImages(/*CMP*/ 'object4', /*URL*/ 'images/indexmailing_listov.jpg'); return true;"
 434  onmouseout="changeImages(/*CMP*/ 'object4', /*URL*/ 'images/indexmailing_list.jpg'); return true;"><img
 435  src="images/indexmailing_list.jpg" name="object4" alt="Mailing List"
 436  border="0" height="46" width="124"></a></td>
 437             <td colspan="2" height="46" width="630"><img
 438  src="images/indexpane6_10_.jpg" name="" alt="" border="0" height="46"
 439  width="630"></td>
 440           </tr>
 441           <tr>
 442             <td colspan="7" height="141" width="780"><img
 443  src="images/indexpane1_11_.jpg" name="" alt="" border="0" height="141"
 444  width="780"></td>
 445           </tr>
 446         </tbody>
 447       </table>
 448       </td>
 449     </tr>
 450     <tr>
 451       <td><img src="images/is_single_pixel_gif.gif" alt="" height="1"
 452  width="780"></td>
 453     </tr>
 454   </tbody>
 455 </table>
 456 <!--Adobe(R) LiveMotion(TM) DataMap1.0 DO NOT EDIT
 457 end DataMap -->
 458 </body>
 459 </html>