1 <!DOCTYPE HTML
PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4 <title
>PsN
:: Documentation
:: scm
</title
>
5 <!--Adobe(R
) LiveMotion(TM
) 1.0 Generated JavaScript
. Please
do not edit
. -->
8 function newImage(arg
) {
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');
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];
40 </script
><!-- End generated JavaScript
. -->
41 <meta http
-equiv
="Content-Type"
42 content
="text/html; charset=ISO-8859-1">
43 <style type
="text/css">
46 font
-family
: Helvetica
, Arial
, serif
;
55 background
-image
: url(gfx
/bg
.jpg
);
74 text
-decoration
: none
;
78 text
-decoration
: none
;
82 text
-decoration
: none
;
86 text
-decoration
: none
;
88 .style2
{font
-family
: "Courier New", Courier
, mono
}
95 <script language
="JavaScript" type
="text/JavaScript">
97 function MM_reloadPage(init
) { //reloads the window if Nav4 resized
98 if (init
==true) with (navigator
) {if ((appName
=="Netscape")&&(parseInt(appVersion
)==4)) {
99 document
.MM_pgW
=innerWidth
; document
.MM_pgH
=innerHeight
; onresize
=MM_reloadPage
; }}
100 else if (innerWidth
!=document
.MM_pgW || innerHeight
!=document
.MM_pgH
) location
.reload();
105 <meta content
="Pontus Pihlgren" name
="author">
107 <body onload
="preloadImages();"
108 style
="background-color: rgb(255, 255, 255);">
109 <!-- 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
. -->
111 style
="position: absolute; left: 335px; top: 42px; width: 388px; height: 43px; z-index: 1; font-size: x-small;">
112 <div
class="style1" align
="right">Stepwise
113 Covariate
Modeling (<span style
="font-family: monospace;">scm
</span
>)<br
>
117 style
="position: absolute; left: 226px; width: 497px; z-index: 2; top: 188px; height: 1110px;">
118 <div align
="justify">
120 include("scm_synopsis.php");
121 include("scm_description.php");
123 <p
class="heading2">Valid states
for the parameter
-covariate relations
</p
>
125 <p
>The SCM tool in PsN is written to be flexible in the shape of the
126 parameter
-covariate relations
. Currently there is a fixed set of
127 available forms of relations but there is ongoing development aiming
128 at full flexibility
for the user with regard to relation
-shape
131 <p
>The avaialable shapes
or <em
>states
</em
> for the
132 parameter
-covariate relations
for continuous covariates
are (1) not
133 included
, (2) included
as a linear relation
and (3) included
as a
134 piece
-wise linear relation with two slopes
. </p
>
136 <p
>Categorical covariates are
either (1) not included
or (2) included with an extra parameter added
for each but the most common category
. </p
>
137 <p
>The figures
, 1, 2 and 3, are used when specifying included relations below
. </p
>
139 include("scm_options.php");
140 include("scm_examples.php");
142 <!-- <h3
class="heading1">Synopsis
</h3
>
143 <p
class="style2">$ scm
[ -h |
-?
] [ --help
]<br
>
144 --config_file
='string'<br
>
145 [ --do_not_drop
='string' ]<br
>
146 [ --gof
='string' ]<br
>
147 [ --logfile
='string' ]<br
>
148 [ --model
='string' ]<br
>
149 [ --p_backward
='string' ]<br
>
150 [ --p_forward
='string' ]<br
>
151 [ --search_direction
='forward|backward|both' ]<br
>
152 [ --abort_on_fail
]<br
>
155 [ --cpu_time
='integer' ]<br
>
157 [ --debug_package
='string' ]<br
>
158 [ --debug_subroutine
='string' ]<br
>
159 [ --directory
='string' ]<br
>
160 [ --extra_data_file
='string' ]<br
>
161 [ --extra_files
='string' ]<br
>
162 [ --grid_batch_size
='integer' ]<br
>
163 [ --missing_data_token
='string' ]<br
>
164 [ --nm_directory
='string' ]<br
>
165 [ --nm_version
='string' ]<br
>
166 [ --outputfile
='string' ]<br
>
168 [ --remove_temp_files
]<br
>
169 [ --results_file
='string' ]<br
>
170 [ --retries
='integer' ]<br
>
171 [ --run_on_nordugrid
]<br
>
172 [ --seed
='string' ]<br
>
173 [ --threads
='integer' ]<br
>
174 [ --tweak_inits
]</p
>
175 <h3
class="heading1">Description
</h3
>
177 <p
>The Stepwise Covariate
Model (SCM
) building tool of PsN
implements
178 Forward Selection
and Backward Elimination of covariates to a
179 model
. In short
, one model
for each relevant parameter
-covariate
180 relationship is prepared
and tested in a univariate manner
. In the
181 first step the model that gives the best fit of the data according to
182 some criteria is retained
and taken forward to the next step
. In the
183 following steps all remaining parameter
-covariate combinations are
184 tested until no more covariates meet the criteria
for being included
185 into the model
. The Forward Selection can be followed by Backward
186 Elimination
, which proceeds
as the Forward Selection but reversely
,
187 using stricter criteria
for model improvement
.</p
>
189 <p
>The Stepwise Covariate Model building procedure is run by the scm
190 utility
. The options to the scm utility are of three diffrent types
,
191 first are the common options which works like the common options
for
192 all tools
. Then are the SCM specific command line options
. And last
193 are options which have a more complex structures
and are considered to
194 cumbersome to specify on the command line
. These options must
195 therefore be specified in a separate configuration file
. It is
196 possible to provide values
for all options
, including the common
197 options
, in the configuration file but it should be noted that the
198 command line overrides the configuration file
, if an option is
199 specified at both locations
. </p
>
201 <h3
class="heading1">Command line options
</h3
>
204 These are the non
-composite options specific to the
<span
205 class="style2">scm
</span
> utility
. Read the
<a
206 href
="execute_docs.php">execute documentation
</a
> for a
list of common
207 options
. The composite options are listed in the configuration file
212 <dt
><b
>config_file
</b
></dt
>
214 <p
>A path
and file name to a
215 file to read configuration settings from
.
219 <dt
><b
>search_direction
</b
></dt
>
221 <p
>Which search task to
222 perform
: backward
, forward
or both is allowed
.
226 <dt
><b
>logfile
</b
></dt
>
228 <p
>The name of the logfile
.
232 <dt
><b
>model
</b
></dt
>
234 <p
>The name of the basic model file
, without any parameter
-covariate relations included
.</p
>
237 <dt
><b
>p_forward
</b
></dt
>
239 <p
>Using the p_forward option
, you can specify the p
-value to
use for the forward selection
.</p
>
242 <dt
><b
>p_backward
</b
></dt
>
244 <p
>Using the p_backward option
, you can specify the p
-value to
use for the backward deletion
.</p
>
247 <dt
><b
>p_value
</b
></dt
>
248 </dl
><p
>Use this option to set the p_value
for both forward
and backward
251 <dt
><b
>do_not_drop
</b
></dt
>
254 <p
>Since the number of columns are restricted to
20 for NONMEM it is
255 necessary to minimize the number of undropped columns
. The scm utility
256 uses the
'=DROP' syntax of NONMEM to exclude the covariate columns
257 that are not used
. If some covariates are used in the PK
or PRED code
258 in the basic model you must
list them using the do_not_drop option to
259 prevent them from being dropped
.</p
>
261 <h3 align
="left" class="heading1">SCM configuration file options
</h3
>
263 <span
class="heading2">General considerations
</span
>
265 <p
>The syntax of the simple options is just the name of the option
266 followed by the equal sign
and a valid value
for the option
. For
269 <p
class="style2">retries
=5</p
>
270 <p
>This states that a maximum of
5 retries will be used in the executions
. </p
>
271 Some options accept Perl code
:
272 <p
><span
class="style2">base_criteria_values
={ 1 =>
; ofv
=>
; -9571.234}</span
> </p
>
273 Other take comma
-separated lists
:
274 <p
><span
class="style2">continuous_covariates
=AGE
,WT
,ALBU
,BILI
,AST
,ALT
,ALKP
,POT
,MAG
,CA
,NA
,TOTP
</span
></p
>
276 Some options don
't accept a value on the command line. They set the
277 behavior of the utility simply by being specified or not. In the
278 configuration file these options need to be followed by 1 or a 0. A 1
279 indicates that it is used and a 0 that it is not used.
281 <p class="style2">fix=1</p>
282 You can place a comment anywhere in the file by prefixing the line with a semicolon:
283 <p><span class="style2">;ask_if_fail=0</span></p>
284 If an option is long you can break the line with a backslash, just a linebreak will NOT work:
285 <p class="style2">categorical_covariates=SEX,ARR,SHD,NYHA,RACE,ALCO,SMOK,BETA,CGLY,LDIU,\<br>
286 TDIU,CANT,ACE,NITR,ACOA,POTA,TWOC,TREA,TWOD,INDU,\<br>
287 TUBS,ALQT,ANTP,ANTD,ANTM,ANTH,ANTB,SULP,ANT1,CLIA,\<br>
288 CLIB,CLIC,CL3,CIME,METF,FENM,PROC,HEP1,HEP2,HEP3 </p>
290 <p class="heading2">Simple options</p>
292 The simple options are the SCM specific command line options and the
293 command line options common to all PsN Utilties.
295 <p class="heading2">List options</p>
297 List options are options that take enumerations of values like the
298 <span class="style2">categorical_covariates</span> option:
300 <p class="style2">categorical_covariates=SEX,ARR,SHD,NYHA,RAC<p>
302 The list options valid in the configuration file are:
304 <p class="style2">categorical_covariates</p>
306 The <span class="style2">categorical_covariates</span> list option is
307 neccessary for the scm to know which type of NONMEM code to generate
308 for the parameter covariate relation.
310 <p class="style2">continuous_covariates</p>
312 The <span class="style2">categorical_covariates</span> list option is
313 neccessary for the scm to know which type of NONMEM code to generate
314 for the parameter covariate relation.
316 <p class="style2">do_not_drop</p>
318 If the dataset used with the scm is to wide, scm will drop the data
319 columns that correponds to covariate which is not used in a particular
320 step. However, if you have used that covariate in code that is not
321 affected by the scm, NONMEM will produce an error. Therefore it is
322 neccessary for you to specify which those covariates are, using the
323 <span class="style2">do_not_drop</span> list option.
325 <p class="style2">extra_files</p>
327 If you need some extraordinary file to be copied into the NONMEM
328 execution directory, specify them with the <span
329 class="style2">extra_files</span> list option.
331 <p class="heading2">Code options</p>
333 Code options are almost like a Simple option. With the difference that
334 the right side is evaluted by the perl interpretor. If you don't
335 understand the difference
, it is probably not important
. However
, it
336 is available
for a reason
. The SCM have hooks
for custom goodness of
337 fit functions
. Those functions may need some special input data
. And
338 for flexibility
, we allow that data to be just about anything
, the
339 side effect is that it becomes to complex
for the configuration file
340 structure
. The solution is to allow options that are small Perl
341 programs
. Those options we refer to
as code options
.
343 <p
class="style2">base_criteria_values
</p
>
345 The
<span
class="style2">base_criteria_values
</span
> overrides
default
346 criterias
for the goodness of fit
function used
. The
default goodness
347 of fit
function takes its base_criteria_value to be the ofv of the
348 initial model
. If you would like to change the base ofv to
400 you
351 <pre
>base_criteria_values
= { 1 => { ofv
=> 400 } }</pre
>
353 <p
class="heading2">Composite options
</p
>
355 <p
>The composite options can not be specified on the command line
. An
356 exception is the
<span
class="style2">extra_data_files
</span
> option
357 which is valid
for all utilities
. A composite option section starts
358 with an option header followed by a set of lines with a left side
, an
359 equal sign
and a right side
. </p
>
362 $this -> {'ofv_backward'} = defined
$parm{'ofv_backward'} ?
$parm{'ofv_backward'} : {} unless defined
$this -> {'ofv_backward'};
363 $this -> {'ofv_change'} = defined
$parm{'ofv_change'} ?
$parm{'ofv_change'} : {} unless defined
$this -> {'ofv_change'};
364 $this -> {'ofv_forward'} = defined
$parm{'ofv_forward'} ?
$parm{'ofv_forward'} : {} unless defined
$this -> {'ofv_forward'};
368 <dt
><b
>extra_data_files
</b
></dt
>
370 <dd
>The
<span
class="style2">-extra_data_files
</span
> option is used
371 to specify files with extra data
. As NONMEM only accepts
20
372 columns
, it is sometimes necessary to split data files
. The left
373 side of each line holds the extra data file name
. The right side
374 is a comma
-separated
list of the column headers
.
375 <p
><span
class="style2">[extra_data_files
]<br
>
376 sub
.dta
=ID
,GRP
,AGE
,SEX
,ARR
,SHD
,NYHA
,LVEF
,WT
,HT
,RACE
,ALCO
,SMOK
,BETA
</span
><br
>
380 <dt
><b
>test_relations
</b
></dt
>
382 <dd
><span
class="style2">The
-test_relations
</span
>option is used
383 to specify what parameter
-covariate relations the scm utility
384 will test
. The left side of each row is a parameter name
and the
385 right side is a comma separated
list of covariates
.
387 <p
class="style2">[test_relations
]<br
>
388 CL
=AGE
,SEX
,ARR
,SHD
,NYHA
,WT
,RACE
,ALCO
,SMOK
,BETA
,\
<br
>
389 ALBU
,BILI
,AST
,ALT
,ALKP
,POT
,MAG
,CA
,NA
,TOTP
, \
<br
>
390 ANT1
,CLIA
,CLIB
,CLIC
,CL3
,CIME
,METF
,PROC
<br
><br
>
391 V
=SEX
,WT
,ALBU
,TOTP
,LDIU
,TDIU
,ACOA
,SULP
<br
></p
>
394 <dt
><b
>included_relations
</b
></dt
>
396 <dd
>If you want to start the search with some relations included you
397 can add them to the
<span
398 class="style2">included_relations
</span
>. The left side of each
399 row holds the name of a parameter
and the right side a
list of
400 covariates
. For each covariate you can specify a relation
401 state
. The general syntax is
<span
class="style2">COV
-X
</span
>
402 where COV is you covariate
and X is the state
. If the state is
403 omitted it will be set to
2.
405 <p
><span
class="style2">[included_relations
]<br
>
406 CL
=TDIU
-2,CLIA
-2,SEX
-2<br
>
407 V
=WT
,ACOA
-2,SEX
-3,TOTP
</span
><br
>
411 <dt
><b
>valid_states
</b
></dt
>
413 <dd
>You can specify what states you want the SCM to test
. By
default
414 it tests three states
. 1 - not included
, 2 - linear
, 3 -
415 piecewise linear
and 4 - exponential parameterization
. The
416 valid states are specified
for separately continuous
and
417 categorical covariates
.
419 <p
class="style2">[valid_states
]<br
>
426 <dd
>If you are not satisfied with the state specific NONMEM code
427 generated by the scm
, you can overide it using the code
428 option
. It lets you specify code
for specific parameters
,
429 specific paramater
- covariate relations
and even specific
430 states
. Each line under the
<span
class="style2">[code
]</span
>
431 header defines code
for one parameter
- covariate
- state
434 <p
class="style2">[code
]<br
>
437 This will change the
default code
for state
1 of the CL
- WT
438 relation
. You can also
use wildcards to redefine the code
for
441 <p
class="style2">[code
]<br
>
444 In this example you will redefine the code
for all covaritates
445 in a relation with CL
.
447 <p
class="style2">[code
]<br
>
450 This example will redefine the code
for all relations in state
451 1. Notice that you can not
use a wildcard
for the state
.
453 Generally it is useful to
include the parameter
and/or the
454 covariate in the code
. So to make it possible when using
455 wildcards you can
use the generic variables PARM
and COV which
456 will be replaced with the parameter
and covariate in question
457 for the current relation
.
460 <dt
><b
>lower_bounds
, upper_bounds
and inits
</b
></dt
>
462 <dd
>The inits
and bounds option lets you set initial estimates
for
463 thetas introduced in the code
and their corresponding bounds
. A
464 hockeystick relation introduces two
new thetas
, so to set the
465 thetas value
and bounds
for the CL
- WT relation you would
468 <p
class="style2">[lower_bounds
]<br
>
469 CL
:WT
-2=0.1, 0.05</p
>
471 <p
class="style2">[upper_bounds
]<br
>
472 CL
:WT
-2=0.3, 0.08</p
>
474 <p
class="style2">[inits
]<br
>
475 CL
:WT
-2=0.15,0.07</p
>
477 This would correspond to the following lines in a NONMEM modelfile
:
479 <p
class="style2">THETA(1) = 0.1,0.15,0.4<br
>
480 THETA(2) = 0.05,0.07,0.08</p
>
482 Just like in the code option you can
use wildcards
. Notice that
483 if you specify to few
or to many values
, those you exclude will
484 be replaced by defaults
and the extraneous will be ignored
.
492 <h3
class="heading1">Output
</h3
>
494 Currently
, the logfile is the best place to look
for the results from the scm utility
.
498 <p align
="justify"> 
;</p
>
500 <table border
="0" cellpadding
="0" cellspacing
="0" width
="780">
503 <td height
="600" width
="780">
504 <table border
="0" cellpadding
="0" cellspacing
="0" width
="780">
507 <td colspan
="7" height
="201" width
="780"><img
508 src
="images/indexpane1_1_.jpg" name
="" alt
="" border
="0" height
="201"
512 <td height
="46" width
="26"><img
513 src
="images/indexpane1_2_.jpg" name
="" alt
="" border
="0" height
="46"
515 <td height
="46" width
="73"><a href
="index.php"
516 onmouseover
="changeImages(/*CMP*/ 'object', /*URL*/ 'images/indexhomeov.jpg'); return true;"
517 onmouseout
="changeImages(/*CMP*/ 'object', /*URL*/ 'images/indexhome.jpg'); return true;"><img
518 src
="images/indexhome.jpg" name
="object" alt
="Home" border
="0"
519 height
="46" width
="73"></a
></td
>
520 <td height
="46" width
="11"><img
521 src
="images/indexpane3_2_.jpg" name
="" alt
="" border
="0" height
="46"
523 <td height
="46" width
="25"><img
524 src
="images/indexpane4_2_.jpg" name
="" alt
="" border
="0" height
="46"
526 <td height
="46" width
="15"><img
527 src
="images/indexpane5_2_.jpg" name
="" alt
="" border
="0" height
="46"
529 <td height
="46" width
="40"><img
530 src
="images/indexpane6_2_.jpg" name
="" alt
="" border
="0" height
="46"
532 <td height
="46" width
="590"><img
533 src
="images/indexpane7_2_.jpg" name
="" alt
="" border
="0" height
="46"
537 <td colspan
="7" height
="7" width
="780"><img
538 src
="images/indexpane1_3_.jpg" name
="" alt
="" border
="0" height
="7"
542 <td height
="46" width
="26"><img
543 src
="images/indexpane1_4_.jpg" name
="" alt
="" border
="0" height
="46"
545 <td colspan
="5" height
="46" width
="164"><a href
="docs.php"
546 onmouseover
="changeImages(/*CMP*/ 'object1', /*URL*/ 'images/indexdocumentationov.jpg'); return true;"
547 onmouseout
="changeImages(/*CMP*/ 'object1', /*URL*/ 'images/indexdocumentation.jpg'); return true;"><img
548 src
="images/indexdocumentation.jpg" name
="object1" alt
="Documentation"
549 border
="0" height
="46" width
="164"></a
></td
>
550 <td height
="46" width
="590"><img
551 src
="images/indexpane7_4_.jpg" name
="" alt
="" border
="0" height
="46"
555 <td colspan
="7" height
="7" width
="780"><img
556 src
="images/indexpane1_5_.jpg" name
="" alt
="" border
="0" height
="7"
560 <td height
="46" width
="26"><img
561 src
="images/indexpane1_6_.jpg" name
="" alt
="" border
="0" height
="46"
563 <td colspan
="3" height
="46" width
="109"><a
565 onmouseover
="changeImages(/*CMP*/ 'object2', /*URL*/ 'images/indexdownloadov.jpg'); return true;"
566 onmouseout
="changeImages(/*CMP*/ 'object2', /*URL*/ 'images/indexdownload.jpg'); return true;"><img
567 src
="images/indexdownload.jpg" name
="object2" alt
="Download" border
="0"
568 height
="46" width
="109"></a
></td
>
569 <td colspan
="3" height
="46" width
="645"><img
570 src
="images/indexpane5_6_.jpg" name
="" alt
="" border
="0" height
="46"
574 <td colspan
="7" height
="7" width
="780"><img
575 src
="images/indexpane1_7_.jpg" name
="" alt
="" border
="0" height
="7"
579 <td height
="46" width
="26"><img
580 src
="images/indexpane1_8_.jpg" name
="" alt
="" border
="0" height
="46"
582 <td colspan
="2" height
="46" width
="84"><a href
="buglist.php"
583 onmouseover
="changeImages(/*CMP*/ 'object3', /*URL*/ 'images/indexbuglistov.jpg'); return true;"
584 onmouseout
="changeImages(/*CMP*/ 'object3', /*URL*/ 'images/indexbuglist.jpg'); return true;"><img
585 src
="images/indexbuglist.jpg" name
="object3" alt
="Buglist" border
="0"
586 height
="46" width
="84"></a
></td
>
587 <td colspan
="4" height
="46" width
="670"><img
588 src
="images/indexpane4_8_.jpg" name
="" alt
="" border
="0" height
="46"
592 <td colspan
="7" height
="7" width
="780"><img
593 src
="images/indexpane1_9_.jpg" name
="" alt
="" border
="0" height
="7"
597 <td height
="46" width
="26"><img
598 src
="images/indexpane1_10_.jpg" name
="" alt
="" border
="0" height
="46"
600 <td colspan
="4" height
="46" width
="124"><a href
="list.php"
601 onmouseover
="changeImages(/*CMP*/ 'object4', /*URL*/ 'images/indexmailing_listov.jpg'); return true;"
602 onmouseout
="changeImages(/*CMP*/ 'object4', /*URL*/ 'images/indexmailing_list.jpg'); return true;"><img
603 src
="images/indexmailing_list.jpg" name
="object4" alt
="Mailing List"
604 border
="0" height
="46" width
="124"></a
></td
>
605 <td colspan
="2" height
="46" width
="630"><img
606 src
="images/indexpane6_10_.jpg" name
="" alt
="" border
="0" height
="46"
610 <td colspan
="7" height
="141" width
="780"><img
611 src
="images/indexpane1_11_.jpg" name
="" alt
="" border
="0" height
="141"
619 <td
><img src
="images/is_single_pixel_gif.gif" alt
="" height
="1"
624 <!--Adobe(R
) LiveMotion(TM
) DataMap1
.0
DO NOT EDIT