Sie sind auf Seite 1von 852

WinNonlin

Users Guide
Version 4.1
Pharsight Corporation
800 West El Camino Real, Suite 200, Mountain View, California 94040
Voice +1-650-314-3800 Fax +1-650-314-3810
http://www.pharsight.com support@pharsight.com
WinNonlin

Version 4.1
WinNonlin copyright 1998-2003 Pharsight Corporation. All rights reserved. This software and manual are
owned by Pharsight Corporation, and may be used only as authorized in the license agreement controlling
such use. No part of this publication or the software it describes may be reproduced, transmitted, or translated,
in any form or by any means, electronic, mechanical, manual, optical, or otherwise, except as expressly pro-
vided by the license agreement or with the prior written permission of Pharsight Corporation. This product
may contain the following software that is provided to Pharsight Corporation under license: Tidestone For-
mula One copyright 1993-02 Actuate, Inc. All rights reserved. SentinelLM 6.0 copyright 1998 Rainbow
Technologies, Inc. All rights reserved. Microsoft XML Parser version 3.0 copyright 1998-2000 Microsoft
Corporation. All rights reserved. IMSL copyright 1993 Visual Numerics, Inc. All rights reserved.
Information in this document is subject to change without notice and does not represent a commitment on the
part of Pharsight Corporation. This document contains proprietary information of Pharsight Corporation and is
for use by Pharsight Corporation customers only. Use of the information contained in this document for any
purpose other than that for which it is intended is not authorized. NEITHER PHARSIGHT CORPORATION NOR
ANY OF THE CONTRIBUTORS TO THIS DOCUMENT MAKES ANY REPRESENTATION OR WARRANTY, NOR SHALL
ANY WARRANTY BE IMPLIED, AS TO THE COMPLETENESS, ACCURACY, OR USEFULNESS OF THE INFORMATION
CONTAINED IN THIS DOCUMENT, NOR DO THEY ASSUME ANY RESPONSIBILITY FOR LIABILITY OR DAMAGE OF
ANY KIND WHICH MAY RESULT FROM THE USE OF SUCH INFORMATION.
Destination Control Statement
All technical data contained in this publication are subject to the export control laws of the United States of
America. Disclosure to nationals of other countries may violate such laws. It is the reader's responsibility to
determine the applicable regulations and to comply with them.
United States Government Rights
The Software and Documentation constitute commercial computer software and commercial computer
software documentation as such terms are used in 48 CFR 12.212 (Sept. 1995). United States Government
end users acquire the Software under the following terms: (i) for acquisition by or on behalf of civilian agen-
cies, consistent with the policy set forth in 48 CFR 12.212 (Sept. 1995); or (ii) for acquisition by or on behalf
of units of the Department of Defense, consistent with the policies set forth in 48 CFR 227.7202-1 (June 1995)
and 227.7202-3 (June 1995). The manufacturer is Pharsight Corporation, 800 West El Camino Real, Suite 200,
Mountain View, CA 94040.
Trademarks
Trial Simulator, PKS Reporter and Knowledgebase Server are trademarks, and Pharsight, WinNonlin and
WinNonMix are registered trademarks, of Pharsight Corporation. Tidestone is a trademark and Formula One is
a licensed trademark of Actuate, Inc. SentinelLM is a trademark of Rainbow Technologies, Inc. Microsoft
Word, Microsoft Excel, MS, MS-DOS, Windows, Windows 98, Windows NT, Windows 2000, Windows XP
and Fortran Powerstation are trademarks or registered trademarks of Microsoft Corporation. IMSL is a regis-
tered trademark of Visual Numerics, Inc. Compaq Visual Fortran is trademark of Compaq Computer Corpora-
tion. SAS and all other SAS Institute Inc. product or service names are registered trademarks or trademarks of
SAS Institute Inc. in the USA and other countries. All other brand or product names mentioned in this docu-
mentation are trademarks or registered trademarks of their respective companies or organizations.
iii
Contents
Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1
WinNonlin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
WinNonlin editions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
WinNonlin user documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Modeling and nonlinear regression. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Model fitting algorithms and features of WinNonlin. . . . . . . . . . . . . . . . 5
Summary of regression methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Pharsight Corporation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Scientific and consulting services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Training . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Pharsight contact information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Chapter 2 Data Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
WinNonlin windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Workbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Text windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Chart windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Hidden windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Data files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
File types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Pharsight object files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
File type limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
WinNonlin and WinNonMix file compatibility . . . . . . . . . . . . . . . . . . . 22
Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Print all . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
WinNonlin
Users Guide
iv
Page setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
WinNonlin options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Workbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Dependencies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Saving dependencies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Refreshing results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Unlocking derived data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Data history worksheets and log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
History worksheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
WinNonlin Log Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Data export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Microsoft Word export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
SAS Transport file export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
NONMEM export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Chapter 3 ODBC Data Sharing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
ODBC import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Import settings file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Connecting to the data source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Loading a saved connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Building a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Loading a saved query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Loading an import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Refreshing a data set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Importing data with the custom query builder . . . . . . . . . . . . . . . . . . . . 64
ODBC export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Export settings file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Defining an export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Loading a saved export definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Loading an export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
The Enterprise Software Development Kit . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Import file format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Export file format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Custom query builder interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
VB example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Contents
v
Chapter 4 Worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
Editing data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Using formulas and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Filling adjacent cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Clearing cell values and formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Inserting and deleting rows, columns or cells . . . . . . . . . . . . . . . . . . . . 90
Inserting or deleting worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Find, find next and replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Undo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Go to . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Formatting cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Setting column names and units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Data manipulation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Freezing rows and columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Sorting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Merge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Data exclusion and inclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Status code transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Rule sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Chapter 5 Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
Units display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Units options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Unit types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Dosing units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Dose normalization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Preferred units. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Worksheet units. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Entering units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Clearing units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Converting units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Chapter 6 Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
Chart Wizard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
X-Y variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Sort and group variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Error bars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Chart titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
WinNonlin
Users Guide
vi
Axis options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Chart Designer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Starting the chart designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Selecting the plot type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Specifying chart backdrops. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Selecting a location for the plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Formatting the walls of a plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Formatting a series on the plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Formatting series data point labels and axis labels. . . . . . . . . . . . . . . . 157
Formatting an axis. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Formatting axis titles, footnotes, legends, and chart titles . . . . . . . . . . 171
Frequently used graph formatting options. . . . . . . . . . . . . . . . . . . . . . . . . . 178
Changing line style and markers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Changing the axis scaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Creating a semi-log plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Removing grid lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Removing walls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Chart templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Preview and page setup for charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Copy and paste. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Save options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Chapter 7 Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Table Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Missing table values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Table templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Templates 1-3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Templates 4-8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Template 9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Table template variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
ID variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Group variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Variables (or regular variables). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Cross, or X-Cross variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Aggregate variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Mapping variables to the template . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Joining data sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Summary statistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Significant digits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Contents
vii
Table formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Reformatting data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Data-only tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Table export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Exporting to Microsoft Word. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Exporting to Microsoft Excel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Table definition files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Creating a table definition file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Loading a table definition file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Chapter 8 Descriptive Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .207
Computing summary statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Output and computational formulae. . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Weighted summary statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Output and computational formulae. . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Chapter 9 Noncompartmental Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . .215
NCA model selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Model variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Lambda z estimation settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Lambda z range selection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Calculation of Lambda z . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Setting Lambda z ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Partial areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Therapeutic response window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Dosing regimen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Rules for handling of steady-state data. . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Model options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Output options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Weight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
NCA settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Parameter names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
WinNonlin
Users Guide
viii
Computational rules for WinNonlins noncompartmental analysis engine. 234
Data checking and pre-treatment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
AUC calculation and interpolation formulas . . . . . . . . . . . . . . . . . . . . 235
Partial areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Computational details for pharmacokinetic parameters . . . . . . . . . . . . 240
Chapter 10 Compartmental Modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Loading the model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Model properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Data variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Model parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Dosing regimen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Model options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Output options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Weight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
PK settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Running the model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Stop modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Text (ASCII) output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Workbook output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Chart output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Chapter 11 User Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Model structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Model components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Transform block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Command block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Temporary variables block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Function block. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Starting values block. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Differential equation block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Secondary parameters block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
WinNonlin variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Variable names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
PNAMES, SNAMES, and DNAMES. . . . . . . . . . . . . . . . . . . . . . . . . . 286
Contents
ix
The WinNonlin programming language . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
WinNonlin statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
WinNonlin comparison operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Bioassay functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
ASCII models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
User libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Example 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Example 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Example 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Creating a new ASCII model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Loading an existing ASCII user model . . . . . . . . . . . . . . . . . . . . . . . . 300
Compiled user models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Using FORTRAN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Example using Compaq Visual FORTRAN 6.0. . . . . . . . . . . . . . . . . . 302
Using C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Example using Microsoft Visual C++ 6.0 . . . . . . . . . . . . . . . . . . . . . . 305
Using compiled user models in a command file . . . . . . . . . . . . . . . . . 307
Chapter 12 Command Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .309
Command file structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Model definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
WinNonlin commands: basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Model definition commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Loading ASCII models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Model initialization commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Weighting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Model parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Dosing regimen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Model options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Data commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Execution control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Chapter 13 Weighting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .325
Weighted least squares . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Iterative reweighting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
WinNonlin
Users Guide
x
Reading weights from the data file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Scaling of weights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Weights in ASCII models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Chapter 14 The WinNonlin Toolbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Nonparametric superposition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Data and assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Computation method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Performing nonparametric superposition . . . . . . . . . . . . . . . . . . . . . . . 332
Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Semicompartmental modeling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Data and assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Computation method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Performing semicompartmental modeling . . . . . . . . . . . . . . . . . . . . . . 337
Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Crossover design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Data and assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Descriptive analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Hypothesis testing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Using the Crossover Design tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Deconvolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Deconvolution methodology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Convolution methodology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Using deconvolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Deconvolution output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Chapter 15 Linear Mixed Effects Modeling . . . . . . . . . . . . . . . . . . . . . . . . . . 363
An example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
The linear mixed effects model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
Construction of the X matrix. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Linear combinations of elements of . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Determining estimability numerically . . . . . . . . . . . . . . . . . . . . . . . . . 373
Substitution of estimable functions for non-estimable functions . . . . . 373
Fixed effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Output parameterization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Contents
xi
Variance structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Repeated effect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Random effects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
Least squares means . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Contrasts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
Joint versus single contrasts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
Nonestimability of contrasts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
Degrees of freedom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
Other options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
Estimates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
LinMix Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
LinMix limits and constraints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
Fixed effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
Variance structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
Contrasts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
Estimates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
Least squares means . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
LinMix general options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
LinMix output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Linear mixed effects text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Linear mixed effects workbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Tests of hypotheses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Akaikes Information Criterion (AIC) . . . . . . . . . . . . . . . . . . . . . . . . . 404
Schwarzs Bayesian Criterion (SBC) . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Hessian eigenvalues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Predicted values and residuals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Fixed effects parameter estimates . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Coefficients. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
Iteration history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
Parameter key. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
Computational details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
Restricted maximum likelihood . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
Newtons Algorithm for maximization of restricted likelihood. . . . . . 408
Starting values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Convergence criterion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Satterthwaites approximation for degrees of freedom . . . . . . . . . . . . 411
Comparing LinMix to ANOVA and SASs PROC MIXED . . . . . . . . . . . 413
WinNonlin
Users Guide
xii
Chapter 16 Bioequivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
Introduction to bioequivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
Basic terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
Bioequivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
The model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Linear model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Variance structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Average bioequivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Study designs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Recommended models for average bioequivalence . . . . . . . . . . . . . . . 421
Least squares means . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
Classical and Westlake confidence intervals . . . . . . . . . . . . . . . . . . . . 424
Two one-sided T-tests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
Anderson-Hauck test. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
Power . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
Individual and population bioequivalence. . . . . . . . . . . . . . . . . . . . . . . . . . 430
Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Bioequivalence criterion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Details of computations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
Bioequivalence Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
Using average bioequivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
Using population/individual bioequivalence . . . . . . . . . . . . . . . . . . . . 444
Bioequivalence command files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
Bioequivalence output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
Average bioequivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
Population/Individual bioequivalence. . . . . . . . . . . . . . . . . . . . . . . . . . 447
Ratio tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
Missing data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
Chapter 17 Simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
Simulating responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
Simulation of a compiled library model . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
Creating the input data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
Setting up the model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
Data variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
Model parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
Dosing regimen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
Model options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
Running the simulation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
Comparing dosing schemes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
Dosing regimen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
Contents
xiii
Chapter 18 Using the Pharsight Knowledgebase Server . . . . . . . . . . . . . . .461
The PKS information structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
Study. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
Other documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
PKS sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
Accessing the PKS from WinNonlin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
Dosing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
Dosing workbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
Dosing dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
Connecting to the PKS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
Logging in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
Creating a study or scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
Loading a study or scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
Creating scenarios. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
Adding non-WinNonlin documents to a scenario. . . . . . . . . . . . . . . . . . . . 479
Optimizing PKS/WNL performance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
Change tracking and audit information. . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
Dosing information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
Changing the dose regimen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
Appending or updating a study. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
WinNonlin and PKS differences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
Studies and scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
Chapter 19 Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .489
Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
Writing and editing a script. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
Executing a script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
Within WinNonlin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
From the command line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
From file manager or explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
Scripting object properties and methods. . . . . . . . . . . . . . . . . . . . . . . . . . . 493
Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
Engines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
Script file components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
Note on saving files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
Processing multiple profiles in script files . . . . . . . . . . . . . . . . . . . . . . . . . 501
Special file formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
WinNonlin
Users Guide
xiv
Scripting the Pharsight Knowledgebase Server. . . . . . . . . . . . . . . . . . . . . . 512
Example PKS scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
Examples of individual scripting operations . . . . . . . . . . . . . . . . . . . . . . . . 520
Data manipulation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
Plots. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
Data transformations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
Descriptive statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
Modeling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
WinNonlin Model Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
ANOVA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536
Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
Word export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
Chapter 20 Scripting WinNonlin Using Visual Basic . . . . . . . . . . . . . . . . . . . 539
Summary of properties and methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539
Automating Pharsight Knowledgebase Server functions . . . . . . . . . . . . . . 545
Visual Basic scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
Creating a script using Microsoft Word 2000. . . . . . . . . . . . . . . . . . . . 546
Running a script using Microsoft Word 2000. . . . . . . . . . . . . . . . . . . . 548
Appendix A Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
Appendix B WinNonlin Model Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573
Notation and conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574
Pharmacokinetic models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
ASCII models and files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
PK models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
Pharmacodynamic models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596
ASCII library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596
Models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597
PK/PD link models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602
Notation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602
Linking PK and PD models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602
Output parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604
Indirect response models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605
Models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606
Running an indirect response model . . . . . . . . . . . . . . . . . . . . . . . . . . . 608
Michaelis-Menten models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
Contents
xv
Simultaneous PK/PD link models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612
Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612
ASCII library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612
Appendix C Worksheet Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .615
Appendix D Commands, Arrays and Functions. . . . . . . . . . . . . . . . . . . . . . . .621
Appendix E Scripting Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .645
Appendix F Warnings and Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . .707
Compartmental modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
Troubleshooting modeling problems . . . . . . . . . . . . . . . . . . . . . . . . . . 718
LinMix and Bioequivalence wizards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719
Table Wizard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721
Descriptive statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721
Noncompartmental analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
Error messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
Warnings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
Scripting language. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723
Appendix G Visual Basic Automation Reference . . . . . . . . . . . . . . . . . . . . . .725
Chart module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
Charts module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734
Crossover module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734
Deconvolution module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736
DescStats module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740
LinMix module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743
Merge module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 744
Model module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
PK module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
Plot module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751
PrintExportAll module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755
Rule module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759
Semicompartmental module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760
StatusCodes module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762
Superposition module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763
Table module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 769
WinNonlin
Users Guide
xvi
TextEditor module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771
TextEditors module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778
Variable module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778
Variables module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780
Wnl4 module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783
Workbook module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 784
Workbooks module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802
Workspace module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803
Appendix H References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813
Deconvolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813
Pharmacokinetics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 814
Regression and modeling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 815
Statistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817
Bioequivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 818
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 819
1
Chapter 1
Introduction
WinNonlin editions, user documentation, and
Pharsight contact information
WinNonlin
WinNonlin is a sophisticated tool for nonlinear modeling. It is particularly
suited to pharmacokinetic and pharmacodynamic (PK/PD) modeling and non-
compartmental analysis to evaluate data from bioavailability and clinical
pharmacology studies. WinNonlin includes a large library of pharmacoki-
netic, pharmacodynamic, noncompartmental, PK/PD link, and indirect
response models. It also supports creation of custom models to enable fitting
and analysis of virtually any kind of data.
WinNonlin editions
WinNonlin is distributed in two editions, WinNonlin Professional and Win-
Nonlin Enterprise. WinNonlin Professional is made for scientists involved
with nonlinear modeling. It supports the analyses and generates the figures,
tables, and listings required for regulatory submission. WinNonlin Enterprise
has been developed for use by scientists working in a networked environment.
In addition to all the features of WinNonlin Professional, the Enterprise edi-
tion can access ODBC-compliant databases, and serves as a portal to the Phar-
sight Knowledgebase Server (PKS), Pharsight's solution for secure
storage, management and tracking of clinical and pre-clinical data. The com-
bination of WinNonlin Enterprise and PKS supports compliance with the
Food and Drug Administrations (FDA) 21 CFR part 11 regulations.
WinNonlin user documentation
WinNonlin includes the following user documentation. Each manual is avail-
able in PDF format on the WinNonlin CD, and installed in the WinNonlin
WinNonlin
Users Guide
2
1
directory under \USER DOCS. In addition, the Getting Started Guide is pro-
vided in hardcopy with each WinNonlin CD shipment.
The manuals are not intended as a comprehensive text on nonlinear estimation
theory, noncompartmental analysis, or statistical analysis. A bibliography of
references on the underlying theory is provided under References on
page 813.
Modeling and nonlinear regression
The value of mathematical models is well recognized in all of the sciences
physical, biological, behavioral, and others. Models are used in the quantita-
tive analysis of all types of observations or data, and with the power and avail-
ability of computers, mathematical models provide convenient and powerful
ways of looking at data. Models can be used to help interpret data, to test
hypotheses, and to predict future results. The concern here is fitting models
to datathat is, finding a mathematical equation and a set of parameter values
such that values predicted by the model are in some sense close to the
observed values.
Most scientists have been exposed to linear models, models in which the
dependent variable can be expressed as the sum of products of the indepen-
dent variables and parameters. The simplest example is the equation of a line
(simple linear regression):
Table 1-1. WinNonlin user documentation
Document Default location Description
Getting
Started Guide
...\WinNonlin\User Docs and
hardcopy with CD shipments
Installation and licensing instructions, and a step-by-step test
to confirm that the installation is complete and functional.
Users Guide ...\WinNonlin\User Docs Operating procedures for each software feature, information
on the calculations performed by WinNonlin, and appendices
detailing WinNonlin functions.
Examples
Guide
...\WinNonlin\User Docs Step-by-step examples illustrating use of WinNonlin features
in realistic scenarios.
Online help Accessed from the application
via the Help menu, F1 key, or
Help button.
Operating procedures for the software features and refer-
ence material on WinNonlins computational engines.
Release
notes
...\WinNonlin\User Docs Known issues and work-arounds in the current version of
WinNonlin.
Introduction
Modeling and nonlinear regression
3
1
where Y is the dependent variable, X is the independent variable, A is the
intercept and B is the slope. Two other common examples are polynomials
such as:
and multiple linear regression.
These examples are all linear models since the parameters appear only as
coefficients of the independent variables.
Note: WinNonlins LinMix module handles linear regression, as well as Analysis of
Variance and Analysis of Covariance.
In nonlinear models, at least one of the parameters appears as other than a
coefficient. A simple example is the decay curve:
This model can be linearized by taking the logarithm of both sides, but as
written it is nonlinear.
Another example is the Michaelis-Menten equation:
This example can also be linearized by writing it in terms of the inverses of V
and C, but better estimates are obtained if the nonlinear form is used to model
the observations (Endrenyi, 1981, pages 304-305).
There are many models which cannot be made linear by transformation. One
such model is the sum of two or more exponentials, such as
+ + = BX A Y
+ + + + =
3
4
2
3 2 1
X A X A X A A Y
+ + + + =
3 4 2 3 1 2 1
X A X A X A A Y
( ) BX Y Y = exp
0
C K
C V
V
m
+
=
max
( ) ( ) X B A X B A Y
2 2 1 1
exp exp + =
WinNonlin
Users Guide
4
1
All of the models on this page are called nonlinear models, or nonlinear
regression models. This manual is not intended to be a comprehensive text on
nonlinear estimation theory. However, two good references for the topic of
general nonlinear modeling are Draper and Smith (1981) and Beck and
Arnold (1977). The books by Bard (1974), Ratkowsky (1983) and Bates and
Watts (1988) give a more detailed discussion of the theory of nonlinear
regression modeling. Modeling in the context of kinetic analysis and pharma-
cokinetics is discussed in Endrenyi (1981) and Gabrielsson and Weiner
(2001).
All pharmacokinetic models derive from a set of basic differential equations.
When the basic differential equations can be integrated to algebraic equations,
it is most efficient to fit the data to the integrated equations. But it is also pos-
sible to fit data to the differential equations by numerical integration. Win-
Nonlin can be used to fit models defined in terms of algebraic equations and
models defined in terms of differential equations as well as a combination of
the two types of equations.
Given a model of the data, and a set of data, how does one fit the model to
the data? Some criterion of best fit is needed, and many have been sug-
gested, but only two are much used. These are maximum likelihood and least
squares. With certain assumptions about the error structure of the data (no
random effects), the two are equivalent. A discussion of using nonlinear least
squares to obtain maximum likelihood estimates can be found in Jennrich and
Moore (1975). In least squares fitting the best estimates are those which
minimize the sum of the squared deviations between the observed values and
the values predicted by the model.
The sum of squared deviations can be written in terms of the observations and
the model. In the case of linear models it is easy to compute the least squares
estimates. One equates to zero the partial derivatives of the sum of squares
with respect to the parameters. This gives a set of linear equations with the
estimates as unknowns; well-known techniques can be used to solve these lin-
ear equations for the parameter estimates.
This method will not work for nonlinear models, because the system of equa-
tions which results by setting the partial derivatives to zero is a system of non-
linear equations for which there are no general methods for solving.
Consequently, any method for computing the least squares estimates in a non-
linear model must be an iterative procedure. That is, initial estimates of the
parameters are made and then in some way these initial estimates are modi-
fied to give better estimates, i.e., estimates which result in a smaller sum of
Introduction
Modeling and nonlinear regression
5
1
squared deviations. The iteration continues until hopefully the minimum (or
least) sum of squares is reached.
In the case of models with random effects, such as population PK/PD models,
the more general method of maximum likelihood (ML) must be employed. In
ML, the likelihood of the data is maximized with respect to the model param-
eters. WinNonMix fits models of this variety.
Since it is not possible to know exactly what the minimum is, some stopping
rule must be given at which point it is assumed that the method has converged
to the minimum sum of squares. A more complete discussion of the theory
underlying nonlinear regression can be found in the books cited previously.
Model fitting algorithms and features of WinNonlin
WinNonlin is a computer program for estimating the parameters in a nonlin-
ear model, using the information contained in a set of observations. WinNon-
lin can also be used to simulate a model. That is, given a set of parameter
values and a set of values of the independent variables in the model, WinNon-
lin will compute values of the dependent variable and also estimate the vari-
ance-inflation factors for the estimated parameters.
A computer program such as WinNonlin is only an aid or tool for the model-
ing process. As such it can only take the data and model supplied by the
researcher and find a best fit of the model to the data. The program cannot
determine the correctness of the model nor the value of any decisions or inter-
pretations based on the model. The program does, however, provide some
information about the goodness of fit of the model to the data and about
how well the parameters are estimated.
It is assumed that the user of WinNonlin has some knowledge of nonlinear
regression such as contained in the references mentioned earlier. WinNonlin
provides the least squares estimates of the model parameters as discussed
above. WinNonlin gives the option of three algorithms for minimizing the
sum of squared residuals: the simplex algorithm of Nelder and Mead (1965),
the Gauss-Newton algorithm with the modification proposed by Hartley
(1961), and a Levenberg-type modification of the Gauss-Newton algorithm
(Davies and Whitting, 1972).
The simplex algorithm is a very powerful minimization routine; its usefulness
has formerly been limited by the extensive amount of computation it requires.
The power and speed of current computers make it a more attractive choice,
especially for those problems where some of the parameters may not be well-
WinNonlin
Users Guide
6
1
defined by the data and the sum of squares surface is complicated in the
region of the minimum. The simplex method does not require the solution of a
set of equations in its search and does not use any knowledge of the curvature
of the sum of squares surface. When the Nelder-Mead algorithm converges,
WinNonlin restarts the algorithm using the current estimates of the parameters
as a new set of initial estimates and resetting the step sizes to their original
values. The parameter estimates which are obtained after the algorithm con-
verges a second time are treated as the final estimates. This modification
helps the algorithm locate the global minimum (as opposed to a local mini-
mum) of the residual sum of squares for certain difficult estimation problems.
The Gauss-Newton algorithm uses a linear approximation to the model. As
such it must solve a set of linear equations at each iteration. Much of the diffi-
culty with this algorithm arises from singular or near-singular equations at
some points in the parameter space. WinNonlin avoids this difficulty by using
singular value decomposition rather than matrix inversion to solve the system
of linear equations. (See Kennedy and Gentle, 1980.) One result of using this
method is that the iterations do not get hung up at a singular point in the
parameter space, but rather move on to points where the problem may be bet-
ter defined. To speed convergence, WinNonlin uses the modification to the
Gauss-Newton method proposed by Hartley (1961) and others; with the addi-
tional requirement that at every iteration the sum of squares must decrease.
Many nonlinear estimation programs, including the original NONLIN, have
found Hartley's modification to be very useful. Beck and Arnold (1977) com-
pare various least squares algorithms and conclude that the Box-Kanemasu
method (almost identical to Hartley's) is the best under many circumstances.
As indicated, the singular value decomposition algorithm will always find a
solution to the system of linear equations. However, if the data contain very
little information about one or more of the parameters, the adjusted parameter
vector may be so far from the least squares solution that the linearization of
the model is no longer valid. Then the minimization algorithm may fail due to
any number of numerical problems. One way to avoid this is by using a 'trust
region' solution; that is, a solution to the system of linear equations is not
accepted unless it is sufficiently close to the parameter values at the current
iteration. The Levenberg and Marquardt algorithms are examples of 'trust
region' methods.
Note: Note that the Gauss-Newton method with the Levenberg modification is the
default estimation method used by WinNonlin.
Introduction
Modeling and nonlinear regression
7
1
Trust region methods tend to be very robust against ill-conditioned data sets.
There are two reasons, however, why one may not want to use them. (1) They
require more computation, and thus are not efficient with data sets and models
that readily permit precise estimation of the parameters. (2) More importantly,
the trust region methods obtain parameter estimates that are often meaning-
less because of their large variances. Although WinNonlin gives indications
of this, it is possible for users to ignore this information and use the estimates
as though they were really valid. For more information on trust region meth-
ods, see Gill, Murray and Wright (1981) or Davies and Whitting (1972).
In WinNonlin the partial derivatives required by the Gauss-Newton algorithm
are approximated by difference equations. There is little, if any, evidence that
any nonlinear estimation problem is better or more easily solved by the use of
the exact partial derivatives.
To fit those models that are defined by systems of differential equations, the
RKF45 numerical integration algorithm is used (Shampine et. al., 1976). This
algorithm is a 5th order Runge-Kutta method with variable step sizes.
It is often desirable to set limits on the admissible parameter space; this results
in constrained optimization. For example, the model may contain a parame-
ter which must be non-negative, but the data set may contain so much error
that the actual least squares estimate is negative. In such a case it may be pref-
erable to give up some of the properties of the unconstrained estimation in
order to obtain parameter estimates that are physically realistic. At other
times, setting reasonable limits on the parameter may prevent the algorithm
from wandering off and getting lost. For this reason, it is recommended that
users always set limits on the parameters (the means of doing this is discussed
in the modeling chapters of this document). In WinNonlin two different meth-
ods are used for bounding the parameter space. When the simplex method is
used, points outside the bounds are assigned a very large value for the residual
sum of squares. This sends the algorithm back into the admissible parameter
space.
With the Gauss-Newton algorithms, two successive transformations are used
to affect the bounding of the parameter space. The first transformation is from
the bounded space as defined by the input limits to the unit hypercube. The
second transformation uses the inverse of the normal probability function to
go to an infinite parameter space. This method of bounding the parameter
space has worked extremely well with a large variety of models and data sets.
Bounding the parameter space in this way is in effect a transformation of the
parameter space. It is well known that a reparameterization of the parameters
will often make a problem more tractable. (See Draper and Smith (1981) or
WinNonlin
Users Guide
8
1
Ratkowsky (1983) for discussions of reparameterization.) When encountering
a difficult estimation problem, the user may want to try different bounds to
see if the estimation is improved. It must be pointed out that it may be possi-
ble to make the problem worse with this kind of transformation of the param-
eter space. However, experience suggests that this will rarely occur.
Reparameterization to make the models more linear also may help.
Because of WinNonlins flexibility and generality, and the complexity of non-
linear estimation, a great many options and specifications may be supplied to
the program. To make WinNonlin easy to use, many of the most commonly
used options are set as WinNonlin defaults.
WinNonlin is capable of estimating the parameters in a very large class of
nonlinear models. Fitting pharmacokinetic and pharmacodynamic models is a
special case of nonlinear estimation, but it is important enough that WinNon-
lin is supplied with a library of the most commonly used pharmacokinetic and
pharmacodynamic models. To speed execution time, the main WinNonlin
library has been built in, or compiled. However, ASCII library files corre-
sponding to the same models as the built-in models, plus an additional utility
library of models, are also provided. The model libraries and their uses are
described in WinNonlin Model Libraries on page 573. Users can also create
custom libraries, as explained in User Models on page 273.
Summary of regression methods
Method 1: Nelder-Mead simplex
Method 1 is a very powerful algorithm. Since it doesn't require the estimated
variance-covariance matrix as part of its algorithm, it often performs very
well on ill-conditioned data sets. Ill-conditioned indicates that for the given
data set and model, there isn't enough information contained in the data to pre-
cisely estimate all of the parameters in the model or that the sum of squares
surface is highly curved. Although the procedure works well, it can be slow.
When used to fit a system of differential equations, it can be extremely slow.
Method 2: Gauss-Newton with Levenberg and Hartley modification
Method 2 is the default, and also performs well on a wide class of problems,
including ill-conditioned data sets. Although the Gauss-Newton method does
require the estimated variance-covariance matrix of the parameters, the Lev-
enberg modification suppresses the magnitude of the change in parameter val-
Introduction
Pharsight Corporation
9
1
ues from iteration to iteration to a reasonable amount. This enables the
method to perform well on ill-conditioned data sets.
Method 3: Gauss-Newton with Hartley modification
Method 3 is another Gauss-Newton method. It is not as robust as Methods 1
and 2 but is extremely fast. Method 3 is recommended when speed is a con-
sideration or when maximum likelihood estimation or linear regression analy-
sis is to be performed. It is not recommended for fitting complex models.
Pharsight Corporation
Pharsight Corporation provides software and services designed to improve the
efficiency of drug development. The company's proprietary technology and
world-class consulting expertise enable pharmaceutical and biotechnology
companies to make more confident decisions in dealing with complex issues
of drug development and product portfolio management. Pharsight Corpora-
tion helps companies make more informed and objective decisions that lead to
more successful and predictable trial outcomes.
Pharsight Corporation is a public company headquartered in Mountain View,
California. More information about the company, products and services is
available on the web at www.pharsight.com. See also Pharsight contact
information on page 10.
Products
Pharsight offers a comprehensive suite of software products, including Win-
Nonlin

, WinNonMix

, Trial Simulator, Clinical Workbench, and Phar-


sight Knowledgebase Server. For further information on these products,
please visit Pharsight on the web at www.pharsight.com.
Scientific and consulting services
Pharsight Scientific Services consultants can design and optimize clinical tri-
als and clinical development programs to meet an individual company's
objectives. Services range from project-based trial and program analyses
through strategic partnerships with drug companies in which complete
deployment of Pharsight's software and methodologies are included as part of
an overall plan to accelerate drug development.
WinNonlin
Users Guide
10
1
Pharsight consultants can also facilitate data gathering and interpretation,
population modeling, and process automation, e.g., WinNonlin scripting.
Training
Pharsight Corporation offers workshops and training courses at regular inter-
vals. On-site training is available by request. Contact Pharsight for schedules,
pricing and availability. The training schedule is also available on Pharsights
corporate web site at www.pharsight.com/training/.
Pharsight contact information
Technical support
Please consult the WinNonlin user documentation, described under WinNon-
lin user documentation on page 1, to address questions about the software. If,
after consulting the user documentation, further assistance is needed, please
contact Pharsight technical support via e-mail (preferred), fax or post.
Fax: 01-919-859-6871
E-mail: support@pharsight.com
Mail: Pharsight Corporation
5520 Dillard Road, Suite 210
Cary, North Carolina 27511
For the most efficient service include a complete description of the problem,
including copies of your input data and instructions to WinNonlin, as well as
the ASCII output, if applicable, detailing the error that occurred.
Licensing and product upgrades
For license renewals and product upgrades, please contact Pharsight sales:
E-mail: sales@pharsight.com
Telephone: 1-888-708-7444 (from US only)
Fax: +1-650-314-3811
Introduction
Pharsight Corporation
11
1
Assistance with Pharsight software licensing is available by telephone and e-
mail:
Telephone: 01-919-852-4620.
E-mail: license@pharsight.com
Customer feedback
Please submit requests for product enhancements and defect corrections by e-
mail, fax, or through Pharsights customer support web site, as follows.
e-mail: support@pharsight.com
Web: http://support.pharsight.com
Fax: 01-919-859-6871
WinNonlin
Users Guide
12
1
13
Chapter 2
Data Management
Data files, import, export, and formatting
WinNonlin windows
WinNonlin uses three kinds of data, each presented in a different window:
tabular data, presented in Workbooks;
plots, presented in Chart windows;
ASCII text, displayed in a Text windows.
Each window type can load from and save to a variety of file formats (see
Data files on page 19). Each can be hidden to reduce clutter in the WinNon-
lin parent window (see Hidden windows on page 19).
Workbooks
The workbook contains two or more spreadsheet-like worksheets to store, for-
mat and manipulate tabular data, such as modeling input or analysis output.
Figure 2-1. A workbook window
To create a new workbook:
1. Click the New Workbook button on the tool bar.
WinNonlin
Users Guide
14
2
or
1. Choose File>New from the menus (Alt+F, N). The New dialog appears.
2. Select the Workbook radio button.
3. Click OK. A new workbook opens.
Worksheets
Each worksheet is accessed using a tab at the bottom of the workbook win-
dow. Every workbook contains at minimum one data sheet and a History
worksheet, which details many of the changes and operations made on the
data. It is described in detail under Data history worksheets and log files on
page 40.
Worksheets support spreadsheet formulas, functions and formatting. See
Worksheets on page 85.
To add a new worksheet:
1. Open the workbook to the insertion point for the new worksheet. The new
worksheet will be inserted in front of the currently-selected worksheet.
2. Choose Edit>Insert Sheet from the WinNonlin menus.
To delete a worksheet:
1. Open the workbook to the worksheet to be deleted.
2. Choose Edit>Delete Sheet from the WinNonlin menus.
3. Click Yes to confirm deletion of the current worksheet.
Note: The History worksheet cannot be modified or deleted. Comments can be cap-
tured in the Annotations column. Workbooks must contain at least one work-
sheet in addition to the History worksheet.
Workbook data
Pharsight workbook objects (*.PWO) are WinNonlins native format for tabu-
lar data. In addition, WinNonlin can read (import) data from other file types:
Data Management
WinNonlin windows
15
2
ASCII files (*.DAT, *.DTA, *.PRN, *.CSV)
Microsoft Excel Version 4.0, 5.0/95, and Excel 97 files (*.XLS)
SAS Transport Files (*.XPT, *.STX)
WinNonlin data objects (*.WDO)
Data can also be copied between any spreadsheet and a WinNonlin worksheet
using the Windows Clipboard.
WinNonlin can save workbook data to several file formats, as detailed under
File types on page 19, and export to NONMEM, Microsoft Word, or SAS
Transport files as described under NONMEM export on page 47 and Data
export on page 44. Data can be exported directly to an external database
using either the ODBC Export function (see ODBC export on page 69) or
the Pharsight Knowledgebase Server menu (see Using the Pharsight Knowl-
edgebase Server on page 461).
Troubleshooting: loading tabular data
Non-numeric data
Occasionally, when transferring data from other packages, non-numeric data
may appear in workbook cells where the data should be numeric. This may be
caused by the introduction of leading or trailing blank spaces in some fields,
among other causes. One indicator that the data are non-numeric is that non-
numeric data will be left justified rather than centered in the cells.
Non-numeric data may cause problems in WinNonlin calculations, owing in
part to the different sort order inherent in non-numeric data.
To convert non-numeric data to numeric data; create a new variable, using a
formula or function, such as New = Old+0. This new column can be copied,
to paste only the values (not the formula) to another column, then delete the
other two columns.
Missing data
If a data set includes missing values, and the cells with the missing values are
not grayed, then check to be sure that the character used to denote missing
values has been specified in the Options dialog box accessed from the Open
dialog.
WinNonlin
Users Guide
16
2
Column problems
If all of the data appear in the first column, check the Options dialog box to be
sure that the correct delimiter has been specified.
If a number of blank columns or cells appear where they do not belong, check
the Treat Consecutive Delimiters as One option on the Options dialog box.
Text windows
WinNonlin text windows are most commonly used to build models and write
scripts. In addition, ASCII modeling output is displayed in text windows. Text
can also be used for notes, which can be exported to Microsoft Word or saved
to the Pharsight Knowledgebase Server.
Figure 2-2. A text window showing modeling output
To create a new text window:
1. Select the New command on the File menu. The New dialog appears.
2. Click on the Text File button.
3. Click OK. The new text window appears.
or
1. Click on the small arrow between the New File and Open File tool bar but-
tons. A shortcut menu appears.
Data Management
WinNonlin windows
17
2
2. Select New Text. The new text window appears.
Text data
In general, text files created in any other application can be opened as text
objects in WinNonlin. WinNonlin may not preserve formatting from the other
applications in the import process.
As with worksheet data, the Windows clipboard can be used to cut or copy
text from another application into a WinNonlin text window and vice-versa.
Text window data may be saved as ASCII text files (*.TXT), Rich Text Format
files (*.RTF), WinNonlin model library files (*.LIB), Pharsight text objects
(*.PTO), or Pharsight script files (*.PSC), as detailed under File types on
page 19. It is also possible to export text directly to Microsoft Word (see
Microsoft Word export on page 44). Text files can be saved to the Pharsight
Knowledgebase Server (see Using the Pharsight Knowledgebase Server on
page 461).
Chart windows
The chart window is used to display graphs, which may be generated manu-
ally, via the Chart Wizard, or automatically as output from modeling.
WinNonlin
Users Guide
18
2
Figure 2-3. A chart window
Multiple chart types may be included in one chart window. Each is accessed
using the tab in the lower left corner. When multiple charts of a given type are
generated for multiple sort levels, e.g., one per subject, the individual charts
can be selected using the page buttons at the bottom right corner of the chart
window.
See Charts on page 129 for instructions on creating and formatting graphs.
Charts can be exported from WinNonlin in a number of ways. First, the chart
in the active window can be saved as a windows metafile (.WMF), or a bitmap
(.BMP or .JPEG) file, and then opened in another application. The clipboard can
also be used to copy a chart and paste it into a Windows-based application
(such as Word or Excel) by using the Paste Special command. All of these
actions export an image for use in another application.
Restore positions
If elements within a chart window have been repositioned from their initial
locations, the Restore Positions command on the Charts menu will return all
elements to initial positions within the window.
Data Management
Data files
19
2
Hidden windows
Windows of all types can be hidden so as not to clutter the parent window.
The Hide Window command leaves the active window open, but hidden from
the WinNonlin workspace and commands. Hidden windows do not appear in
list boxes (for modeling, Descriptive Statistics, Table Wizard, and Chart Wiz-
ard, for example). Hidden windows cannot be saved to files or workspaces.
To hide a window:
1. Open or select the window to be hidden.
2. Choose Window>Hide Window from the WinNonlin menus.
To un-hide a window:
1. Choose Window>Unhide Windows... from the WinNonlin menus.
2. Check the window(s) to unhide and click OK.
Data files
File types
WinNonlin opens and saves data in the file types described in Table 2-1. Each
file type may save a different amount of information associated with the orig-
inal data, as discussed under File type limitations on page 21.The WinNon-
lin standard file extensions are listed here.
Table 2-1. Supported file formats
Data Example File formats: load/import File formats: save/export
Tabular data
(Workbooks)
Subject data
Modeling output
Dosing data
Model parame-
ters
ASCII (*.DAT, *.DTA, *.PRN, *.CSV)
Microsoft Excel 4.0, 5.0/95, 97, 2000
(*.XLS)
Pharsight Workbook Object (*.PWO)
SAS Transport (*.XPT, *.STX)
WinNonlin Data Object (*.WDO)
ASCII data (*.DAT, *.PRN, *.CSV)
ASCII model parameters (*.DTA)
Microsoft Excel 5.0/95, 97 (*.XLS)
Pharsight Workbook Object (*.PWO)
SAS Transport (*.XPT, *.STX)
WinNonlin
Users Guide
20
2
Note: Excel 4.0 files and WinNonlin data objects (*.WDO) and script files (*.wsc)
are import-only. WinNonlin 4.1 cannot save files back to these formats.
Pharsight object files
Pharsight objects (*.PWO, *.PTO, *.PCO) are WinNonlins native data file for-
mats. They preserve all data formatting, sorting and units information applied
in WinNonlin, and can save multiple worksheets in a workbook, or multiple
graphs in a chart window.
A Pharsight Workbook Object (*.PWO) saves all information in a workbook,
including the sort order, units, data exclusions and formatting. It includes all
worksheets in the workbook.
A Pharsight Model Object (*.PMO) contains not only the current model (either
the ASCII code or the number of the compiled model) and any associated
data, but also all values currently specified for the model parameters, con-
stants (dosing) information, data variables, and modeling options. When an
ASCII model is used with a Pharsight Model Object, the source ASCII model
is updated to include any changes made to the model.
Plots (Chart
windows)
Pharsight Chart Object (*.PMO)
WinNonlin Graph Object (*.WGO)
Pharsight Chart Object (*.PMO)
Bitmap image (*.BMP)
Vector graphic (*.JPG)
Windows Metafile (*.WMF)
Text windows Modeling output
ASCII models
Scripts
ASCII text (*.TXT)
Library model(s) (*.LIB)
Rich text (*.RTF)
Pharsight Script (*.PSC)
Pharsight Text Object (*.PTO)
WinNonlin Script (*.WSC)
WinNonlin Text Object (*.WTO)
ASCII text (*.TXT)
Library model(s) (*.LIB)
Rich text (*.RTF)
Pharsight Script (*.PSC)
Pharsight Text Object (*.PTO)
Model
settings
(Load/Save
in modeling
dialogs)
ANOVA set-
tings, Model set-
tings
ANOVA Command File (*.ANV)
LinMix or Bioequivalence Command
File (*.LML)
Pharsight Model Object (*.PMO)
WinNonlin Model Object (*.WMO)
WinNonlin Command File (*.CMD)
ANOVA Command File (*.ANV)
LinMix or Bioequivalence Command
File (*.LML)
Pharsight Model Object (*.PMO)
Table 2-1. Supported file formats (continued)
Data Example File formats: load/import File formats: save/export
Data Management
Data files
21
2
To save all charts in WinNonlin's multi-graph modeling output, a chart win-
dow must be saved as a Pharsight Chart Object (*.PCO). A Pharsight Chart
Object saves all graphs in the window, as well as the attributes associated with
the graph, including links to the graph data and all formatting information.
This formatting information is the same information that is stored in a graph
template.
A Pharsight Text Object (*.PTO) contains all text and formatting (bold, under-
line, fonts, point sizes, italics) in a text window.
File type limitations
Pharsight objects (*.PWO, *.PTO, *.PCO) preserve all data formatting, sorting
and units information applied in WinNonlin, and can save multiple work-
sheets in a workbook, or multiple graphs in a chart window. Non-Pharsight
file formats may limit the information that can be preserved, as follows.
ASCII data files save only the text of the active worksheet or text window.
Data formatting (including exclusions, alignment, etc.) and units will not be
preserved. Multiple worksheets cannot be saved to a single ASCII file.
Rich text files (*.RTF) preserve text and formatting in text windows.
Excel files preserve WinNonlin formatting, data exclusions, as well as multi-
ple worksheets in a workbook. However, units and column headers are not
preserved in Excel output.
Note that Excel 4.0 and WinNonlin object files (*.WDO, *.WTO, *.WGO,
*.WMO) cannot be saved back to their native formats, though these formats
can be opened, edited and saved to other file types. For example, Excel 4.0
files can be saved to newer Excel formats, e.g., Excel 97. WinNonlin data files
can be saved as ASCII files, Excel 5.0/95 files, Excel 97 files, or as Pharsight
Workbook Objects.
When saving worksheet data to an ASCII or Excel file, the entire data set is
always written to disk, even if a subset is selected.
When a chart is saved to a .WMF, .JPEG or .BMP file, a snapshot of the current
image that appears on-screen is saved. Saving the graph window as a Phar-
sight Chart Object saves all graphs in the window, as well as the attributes
associated with the graph
WinNonlin
Users Guide
22
2
WinNonlin and WinNonMix file compatibility
The following table outlines file types that can and cannot be shared between
WinNonMix and WinNonlin.
Table 2-2. WinNonlin and WinNonMix file compatibility
File Type WinNonlin Compatibility WinNonMix
ASCII Data *.dat, *.dta, *.prn, *.csv Identical *.dat, *.dta, *.prn, *.csv
Excel Data files Excel 4.0 (*.xls)
Excel 5.0/95 (*.xls)
Excel 97 (*.xls)
Identical Excel 4.0 (*.xls)
Excel 5.0/95 (*.xls)
Excel 97 (*.xls)
Text files *.txt, *.lib Identical *.txt, *.lib
Rich text files *.rtf Identical *.rtf
WinNonlin files:
Data
Text
Graph
Model
*.wdo
*.wto
*.wgo
*.wmo
Identical
Identical
Identical
Not available
*.wdo
*.wto
*.wgo
Pharsight files:
Data
Text
Chart
Model
*.pwo
*.pto
*.pco
*.pmo
Identical
Identical
Identical
Not compatible
*.pwo
*.pto
*.pco
*.pmo
SAS Transport
files
*.xpt, *.stx Not compatible Not available
ANOVA com-
mand files
a
*.anv Identical *.anv
LinMix com-
mand files
*.lml Not compatible Not available
Bioequivalence
command files
*.lml Not compatible Not available
Model object
files
b
*.pmo Not compatible *.pmo
Data Management
Workspaces
23
2
Workspaces
A workspace is a set of data files open in WinNonlin, and any associated dose
and model settings. This information can be saved to a workspace file
(*.WSP), to be reloaded in future WinNonlin sessions. When a workspace is
saved, it takes a snapshot of all current dose and model settings, and all data
windows that are currently open in WinNonlin. This information is saved to
the workspace file, which links to the relevant source data files. All work-
books, text windows, charts, and model settings that have not yet been saved
to disk are implicitly saved to separate files, named after the workspace.
Model settings, if not previously-saved, are saved to a Pharsight Model
Dosing files ASCII data:
*.dat, *.dta
Not compatible ASCII data:
*.dat, *.dta
Model parame-
ters
ASCII data:
*.dat, *.dta
Not compatible ASCII data:
*.dat, *.dta
Lambda z range ASCII data:
*.dat, *.dta
Not available
Partial areas ASCII data:
*.dat, *.dta
Not available
Graph template *.gtp Identical *.gtp
Table definition
files
*.tdf Identical *.tdf
Command files *.cmd Not available
Script files *.psc, *.wsc Not available
ODBC import
and export files
*.imp, *.exp Identical *.imp, *.exp
PKS files *.pks Not available
a. ANOVA command files can be imported into the Linear Mixed Effects Wizard or
the Bioequivalence Wizard in WinNonlin. New *.ANV files cannot be created.
b. WinNonMix model object files (*.PMO) include more information that WinNonlin
model object files.
Table 2-2. WinNonlin and WinNonMix file compatibility (continued)
File Type WinNonlin Compatibility WinNonMix
WinNonlin
Users Guide
24
2
Object (*.PMO), named after the workspace. Unsaved workbook data, such as
modeling output, are saved to a Pharsight Workbook Object (*.PWO). The
workspace file contains relative paths to these objects.
Note: Pharsight Model Object (*.PMO) files may use absolute paths to data files. If a
workspace containing model information is moved, then loaded, WinNonlin
may prompt the user for the location of some source data files.
To save current work to a workspace:
1. Choose File>Save Workspace (Alt+F, V) from the WinNonlin menus.
If the workspace is new, the Save Workspace dialog will appear.
Figure 2-4. The Save Workspace dialog.
2. Navigate to the appropriate directory and enter a name for the workspace.
Limit the name to alphanumeric, dash and space characters.
3. Click Save.
To create a new, empty workspace:
1. Choose File>New Workspace (Alt+F, W) from the WinNonlin menus.
WinNonlin will prompt the user to save any unsaved work, close all windows,
and start a new, empty, workspace.
Data Management
Printing
25
2
To save current work in a new workspace name or location:
1. Select File>Save Workspace As (Alt+F, K) from the WinNonlin menus.
The Save Workspace dialog appears.
2. Navigate to the appropriate directory and enter a name for the workspace.
Limit the name to alphanumeric, dash and space characters.
3. Click Save.
To load a saved workspace:
1. Choose File>Load Workspace (Alt+F, L) from the WinNonlin menus.
2. In the Load Workspace dialog, navigate to the appropriate directory and dou-
ble-click the desired workspace.
Printing
Customize print output using the following features:
Print on page 25 to print the selected window
Print all on page 26 to print selected items from any open windows
Page setup on page 27 to set formatting and layout options
To print the active window using the default print settings:
1. Click the Print button in the WinNonlin tool bar.
Print
To print the active window:
1. Select the window to be printed.
2. Choose File>Print (Alt+F, P) from the WinNonlin menus.
The Print dialog box appears. The print functions differ depending what kind
of object (workbook, chart, text) is in the active window.
WinNonlin
Users Guide
26
2
Note: When printing charts, the Page setup dialog may be used first in order to spec-
ify multiple charts per page and chart size.
3. Select the printer to use from those listed.
4. For workbooks, select the Print Range:
The entire worksheet: Select All in the Print Range box.
Selected Pages: Select Pages in the Print Range box and specify the page
number(s).
5. For workbooks, under Print What, select whether to print all worksheets
(Entire Workbook) or only the current worksheet (Selected Sheet(s)).
6. Set other print options as needed.
7. Click OK or Print.
Note: Page numbers are only printed for text objects when the printing is initiated
via the print button on the tool bar.
When printing graphs the lines may appear fuzzy. If this occurs, change the
color of the lines to black.
Print all
To print a selection from the open windows:
1. Open the window(s) to be printed.
2. Choose File>Print All from the WinNonlin menus.
Data Management
Printing
27
2
3. To print all open windows, including all worksheets and charts, click the
Print button in the Print All dialog box.
4. To select specific items to print:
a. Uncheck Select all objects.
b. Click the + symbols to view individual windows, worksheets or charts.
c. Check the box next to the items to be printed.
5. Use the Options button to set up the page layout for charts.
6. Click Print.
Note: Each object is printed on a separate page, unless the chart output has been set
for multiple charts per page using the Options button).
Page setup
To set page settings for print output:
1. Select Page Setup from the File menu (Alt+F, G). The page setup dialog box
appropriate to the active object appears. See:
Page setup for workbooks
Page setup for text windows on page 31 (including model windows)
Page setup for charts on page 32
WinNonlin
Users Guide
28
2
Page setup for workbooks
Page setup options for workbook windows are specified on four tabs:
Page Tab
Orientation
Select Portrait (vertical) or Landscape (horizontal) page layout.
Scaling
The workbook can be scaled as a percentage of the normal size or select Fit to
in order to make it fit on a certain number of pages.
Paper Size
Select the size paper to be used.
Page Numbering
Select Automatic to start numbering pages at 1. If page numbers are not to
start at 1, check the Start with page number check box and enter the page
number in the page number field.
Data Management
Printing
29
2
Margins Tab
The margins for the worksheet, including the header and footer margins, can
be specified. The units used are those from the machine's Windows set-
tings. Either inches or centimeters can be used. The data can be centered on
the page, either horizontally, vertically, or both.
Headers and Footers Tab:
The alignment, contents, and formatting of headers and footers can be speci-
fied. Enter the headers and footers to use.
The alignment codes (&L, &C, and &R) must go before font-related codes
(such as &B for bold or &I for italic). Codes for printing worksheet-specific
information like worksheet titles go last. If the codes are entered in the wrong
order WinNonlin may ignore some of them. Enter the codes in the upper or
lower field and separate them with a space.
Select from the following special character codes
&F Prints the Workbook Name.
WinNonlin
Users Guide
30
2
Codes and text are centered unless &L or &R is specified.
Sheet Tab:
&A Prints the Worksheet Name.
&P Prints the Page Number.
&D Prints the Current Date.
&T Prints the Current Time.
&L Left-aligns the characters that follow.
&C Centers the characters that follow.
&R Right-aligns the characters that follow.
&P + number Prints the page number plus number.
&P - number Prints the page number minus number
&& Prints an ampersand
&N Prints the total number of pages in the document
&B Uses a bold font
&I Uses an italic font
&U Underlines the header
&S Strikeout the header
&"fontname Uses the specified font
&nn Uses the specified font size - must be a two digit
number.
Data Management
Printing
31
2
Print Area
Enter the range on the selected worksheet to print. Enter either absolute or rel-
ative cell references. Separate non-contiguous ranges with commas.
Print Titles
Specify row or column titles to be printed on each page of the worksheet. If a
row is selected, the title is printed at the top of each page. If a column is
selected, the title is printed at the left edge of each page. Multiple rows or col-
umns may be selected, but they must then be adjacent.
In the Print Titles text box enter the row and/or column range of the selected
worksheet. Enter absolute or relative cell references. Separate non-contiguous
ranges with commas.
Print Options
Specify whether or not grid lines, row headers and column headers are to be
printed. Output can be specified to print in black and white.
Page Order
Specify the printing order for pages: Top to Bottom (from the top to bottom
margins; the data in the left-most columns prints before the data in columns
farther out) or Left to Right (from the left to right margins: the data in the
uppermost rows prints before the data in the lower rows.).
Page setup for text windows
Page setup options for text windows sets the page orientation and margins (in
inches).
WinNonlin
Users Guide
32
2
Page setup for charts
Page setup options for a chart window sets scaling (chart size) and the number
of charts per page.
Figure 2-5. Page Setup dialog for chart windows.
Orientation
Select whether the graph is to be printed using a vertical page orientation
(Portrait) or a horizontal page orientation (Landscape).
Scaling
Select Actual Size to print the chart at the original size it was created. Select
Best Fit to scale the graph proportionally to fit the page. Best Fit is recom-
mended.
Margins
Enter a value in inches or centimeters, depending on the Windows settings, to
specify the top, bottom, left and right margins of the page.
Layout
Select Screen Layout to print the graph at the size it displays on the screen.
Select Layout for Printer to expand the scale of the graph to the size and lay-
out of the selected paper orientation.
Multiple charts per page
If multiple charts are to be displayed/printed per page, select this check box
and select the format from the list box. Once this option is selected, the con-
trols for scaling and layout are disabled.
Data Management
WinNonlin options
33
2
WinNonlin options
WinNonlin provides options to set default file locations, worksheet behaviors,
and modeling and analysis default settings as described in Table 2-3.
Directories
To set or change the default model library directories:
1. Choose Tools>Options from the WinNonlin menus.
2. Click on the Directories tab, if it is not already open.
3. To set the default file location for WinNonlin model library or user model
library files, click on the Browse button for that directory.
4. Select the desired drive and directory. The picture of the folder opens.
5. Click Apply to set these options and keep the dialog open or OK to keep
these settings and close the Options dialog.
Table 2-3. WinNonlin options
Category Options
Directories default directory for WinNonlin Library and User Library files
Workbooks whether to display formulas in worksheets.
direction in which the Enter key moves the cursor in a worksheet
value used to denote missing data in worksheets
Models default output: workbooks, charts, and/or text with or without page
breaks
default orientation of the Final Parameters output table
default trapezoidal rule to be used for the calculation of AUC in non-
compartmental analyses
Tables treatment of group variables in the table generator
default use of page breaks in tables
Units display of units with column headers in worksheets, chart labels and
tables
WinNonlin
Users Guide
34
2
Workbooks
To set or change workbook options:
1. Choose Tools>Options from the WinNonlin menus.
2. Select the Workbooks tab.
3. Check the Show Formulas check box to display formulas, rather than the val-
ues computed by formulas, in individual worksheet cells. Note that the for-
mula bar at the top of each worksheet displays any formula contained in the
currently-selected cell.
4. Choose the direction of cursor movement between worksheet cells when the
Enter key is pressed: check Enter Moves Down to move the cursor down the
column; else, the cursor will move to the right when the Enter key is pressed.
5. To specify a character or character string to represent missing data, enter this
string in the box labeled Missing Value. Any cell containing this string will
be grayed and treated as missing in (excluded from) modeling and analyses.
6. Click Apply to set these options and keep the dialog open or OK to keep
these settings and close the Options dialog.
Models
To set model options:
1. Choose Tools>Options from the WinNonlin menus.
2. Click on the Models tab in the Options dialog box.
3. Use the check boxes to select the default form(s) of modeling output:
Workbook: check to include tabular results in a workbook.
Charts: check to include charts of model data and results.
Text: check to include text output listing model settings, fitting progress
and final results. Check Page breaks for paginated output.
4. Select the default format for the model parameter output. Transpose Final
Parameter Table, if checked, will create a Final Parameters worksheet with
one column for each statistic of each parameter, as shown in the upper win-
dow of Figure 2-6. A second worksheet called Non-transposed Final Parame-
Data Management
WinNonlin options
35
2
ters will present one row for each parameter and one column for each type of
statistic, as shown in the lower window of Figure 2-6. If the Transpose Final
Parameters option is not checked, the Final Parameters worksheet will present
the untransposed format, and the second worksheet, entitled Transposed Final
Parameters, will present the transposed version. This option is provided pri-
marily for WinNonlin scripts that depend on one format or the other in the
Final Parameters worksheet.
Figure 2-6. Example modeling output: transposed (upper) and non-transposed
(lower) Final Parameters.
5. Select the default NCA calculation method. The area under the curve (AUC)
in noncompartmental analyses will be calculated using one of the following:
A
Linear/log trapezoidal: log-trapezoidal rule, using linear interpolation
between log-transformed data through Clast.
Linear trapezoidal (linear interpolation): linear trapezoidal rule, using
linear interpolation between untransformed data through Clast
Linear up/log down: linear trapezoidal rule up to Cmax, log-trapezoidal
rule after Cmax; uses linear interpolation between untransformed data up
to Cmax, log-transformed data from Cmax through Clast.
A. See Section 3.7 of Gabrielsson and Weiner, 2001, for detailed discussion of AUC compu-
tation methods.
WinNonlin
Users Guide
36
2
Linear trapezoidal (linear/log interpolation): trapezoidal rule with lin-
ear interpolation between data points up to Cmax, log-linear interpolation
between data points from Cmax, extrapolated to Tinf.
6. Click Apply to set these options and keep the dialog open or OK to keep
these settings and close the Options dialog.
Tables
To specify table options:
1. Choose Tools>Options from the WinNonlin menus and click on the Tables
tab in the Options dialog box, or choose File>Options from the Table Wizard
menus.
2. Use the check box to set the default for creating page breaks when the value
of the group variable(s) changes.
3. To have Group variables and their values printed as a line above the Column
Headers, rather than as a column in the table body, check the Place Page
Break Data Outside Table Body check box.
4. Click Apply to set these options and keep the dialog open or OK to keep
these settings and close the Options dialog.
Units
To specify units options:
1. Choose Tools>Options from the WinNonlin menus.
2. Select the Units tab of the Options dialog box.
3. Select the Show Units with Column Headers check box to show the units
displayed in the column header.
4. Choose whether to have units (from workbook data) displayed on chart labels
or in tables, both, or neither. Note that these settings can be overridden in indi-
vidual tables and charts.
5. Click Apply to set these options and keep the dialog open or OK to keep
these settings and close the Options dialog.
Data Management
Dependencies
37
2
The default WinNonlin setting is to have units displayed in column headers.
Thus, for all data file types, when units are associated with a column in the
data set the units should be displayed. This display can be turned off in this
Options dialog. For Pharsight workbook objects (.pwo files), units will not
display if the file is saved and closed with the units hidden. If the units display
when the file was closed, the units will display on reopening.
Dependencies
When WinNonlin creates derived products, such as modeling or analysis out-
put, including workbooks, text windows, and charts, the application locks that
derived data against changes to protect the validity of the analysis results.
WinNonlin tracks changes to the source data set, and marks the derived prod-
uct as out of date if the source data change. The derived data can be refreshed
based on the new source data, or, if desired, unlocked so that it is no longer
dependent on the source data and can be edited.
To view dependencies for a workbook:
1. After running an analysis, select the desired window.
2. Choose File>Dependencies from the WinNonlin menus.
Figure 2-7. Example dependencies. The selected workbook, PROFILES_DSTATS, con-
tains output from descriptive statistics on the workbook PROFILES_570519, which, in
turn, is noncompartmental analysis output for the source data set PROFILES.PWO.
The Dependency View dialog opens. Select a derived data product, e.g., mod-
eling output, from the drop-down list at the top of this dialog. The Parent
WinNonlin
Users Guide
38
2
View shows the source data, if any, from which the selected item was created.
The Child View shows any output generated from the selected item.
Saving dependencies
Data locking and dependencies are preserved by saving the source data,
model and derived products as a workspace (.WSP), or by saving to the Phar-
sight Knowledgebase Server as a scenario (see Using the Pharsight Knowl-
edgebase Server on page 461). Otherwise, dependencies persist only during
the current modeling session. If the output product is saved, closed, and re-
opened, it is no longer locked and no longer dependent on the source object.
Refreshing results
If the source data for an analysis are modified (e.g., changing a value from 0.5
to 0.3), then all currently-open products generated from that source data,
including chart, text and workbook output, are marked as out of date, i.e., the
output window is shaded and includes red marks in the title bar.
If a PK or NCA model has been loaded and run, the output is locked and
linked to both the input data and the model, with its settings. If the original
data set changes, the derived data will be marked as out of date. If any of the
modeling dialogs, such as Model Properties, are opened and closed by click-
ing OK, whether the settings are changed or not, the derived data are marked
as out of date.
There are two ways to refresh derived output. One provides a means of
refreshing specific output. The other refreshes all derived products.
To update specific output after the source data changes:
1. Choose File>Dependencies from the WinNonlin menus.
Data Management
Dependencies
39
2
2. Select a derived output item in the drop-down list at the top of the Depen-
dency View dialog.
3. Click the Refresh button to re-generate related output, based on the latest
source data. For example, if a LinMix analysis included chart and workbook
output, the refresh feature will update both the charts and the workbook data.
To refresh all output after the source data changes:
1. Choose Tools>Refresh All from the WinNonlin menus. This command
refreshes all the derived data from the modified source.
Unlocking derived data
By default, data values in derived products (output workbooks, charts, or text)
cannot be changed. They are locked against changes to protect the integrity of
the analysis results. They can, however, be used as input for computational
operations (such as descriptive statistics, LinMix, etc.).
Analysis output can be unlocked, in which case it will no longer be considered
a product of the source data. Changes to the source data will no longer result
in notification that the derived product is out of date.
To unlock a derived product:
1. After running an analysis, choose File>Dependencies from the menus.
WinNonlin
Users Guide
40
2
2. Make sure the correct item is selected in the drop-down list at the top of the
Dependency View dialog.
3. Click the Detach button.
Data history worksheets and log files
WinNonlin provides multiple means of tracking the data operations in Win-
Nonlin. Each workbook loaded in WinNonlin includes a data history work-
sheet. Almost all operations
A
with and on data from that workbook are
written to the History sheet of that workbook. Note, however, that the Data
History documents only the events of a particular workbook. That is, the Data
History is specific to that workbook.
WinNonlin also has a separate application, the WinNonlin Log Viewer which
provides access to the log files created by the application. The log covers all
data operations. See WinNonlin Log Viewer on page 42.
History worksheet
The History worksheet logs operations made on data in the workbook.
A. Two known cases that are not captured in the History page are filling a range of cells and
moving a range of cells.
Data Management
Data history worksheets and log files
41
2
Figure 2-8. The History worksheet
The first line in the History worksheet always states that a new workbook was
created, and indicates how many worksheets it includes. The History work-
sheet logs edits to worksheet data, including application of units, and all data
manipulations, including sorts and transformations. The History also logs the
following analysis operations:
Table 2-4. Analysis operations logged in the History worksheet
Operation Items logged
PK and Non-
compartmental
analyses (NCA)
Source data workbook and worksheet
Missing/excluded values
Profiles with less than 2 usable records noted: cannot be processed
For urine NCA, notification of any profile that has all zero values for
volume or concentration
For NCA, if only 1 non-zero concentration is found for any profile, and
it occurs at time=0, notification that all parameters set to Missing
For NCA, lambda_z exclusions (or the lack of any) for each profile
Modeling halted using Stop button
Success or failure of the modeling process
Toolbox tools Source data workbook and worksheet
Success or failure of the toolbox engine operation
WinNonlin
Users Guide
42
2
Changes to the History worksheet are saved when the workbook is saved.
WinNonlin Log Viewer
WinNonlin has a separate application, the Log Viewer, for reviewing a record
of operations performed in the application. WinNonlin writes this information
to a separate log file. When the log file reaches its size limit, the file is purged
to a backup file. This log file size can be specified or changed using
View>Options in the Log Viewer application menus.
LinMix and
Bioequivalence
(BE)
Source data workbook and worksheet
Missing/excluded values
In BE, if a test or reference least square mean is negative, notification
that one or more calculations couldn't be performed
If Ln transformation is requested, notification if one or more values of
the dependent variable are less than or equal to 0
Notification of any regressor/covariate found to be alphanumeric
Warning or errors generated by the analysis operation, and the profile
number on which each occurred
If warnings were generated, but no errors: warnings generated on
one or more profiles of data
Success or failure of the LinMix/BioEq operation
Descriptive Sta-
tistics
Source data workbook and worksheet
Missing/excluded values
For weighted analyses, notification of any weights less than 0, and
that all values for that profile will be set to missing.
Notification of any floating point error in the engine, and note that all
values for that profile set to missing.
Success or failure of the LinMix/BioEq operation
Merge Source data workbook and worksheet #1
Missing/excluded values from source worksheet #1
Source data workbook and worksheet #2
Missing/excluded values from source worksheet #2
Sort variable used from each worksheet
Include variables from each worksheet
Success or failure of the Merge operation
Table 2-4. Analysis operations logged in the History worksheet (continued)
Operation Items logged
Data Management
Data history worksheets and log files
43
2
To run the WinNonlin Log Viewer:
1. From the Windows Start menu, choose Programs>Pharsight>WinNonlin
4.1>Log Viewer.
Figure 2-9. The Pharsight Application Log Viewer
The application log contains entries for:
WinNonlin startup and finish PK/PD modeling errors
Open/save workbook Cut/Copy/Paste operations
Replace/Remove data (reports replace/
remove parameters, not cell-by-cell
replacements)
Include/Exclude data operations (reports
include/exclude parameters, not cell-by-
cell parameters)
Changing WinNonlin registry settings Insert column/row
Transform operations Delete column/row
Specifying column units Undo operations
Clearing units Converting units, including messages of
success/failure
WinNonlin
Users Guide
44
2
Data export
A number of different kinds of file types can be imported into and exported
from WinNonlin for convenient data interchange with other applications. See
Supported file formats on page 19. WinNonlin also provides a facility to
export any or all open windows to Microsoft Word or export data to SAS or
NONMEM, as described under Microsoft Word export on page 44, SAS
Transport file export on page 47, and NONMEM export on page 47.
WinNonlins Enterprise edition also allows connection to ODBC-compliant
databases for importing and exporting WinNonlin data sets. Thus rows of PK
data can be read directly from a source ODBC-compliant database, eliminat-
ing the manual steps required to extract PK data from clinical databases. Fur-
ther, the Enterprise edition allows saving derived data produced within
WinNonlin directly back to a table stored within a target ODBC-compliant
database. See ODBC Data Sharing on page 53 for details.
Using WinNonlins Enterprise edition in conjunction with the Pharsight
Knowledgebase Server provides a complete system for data management and
security. See Using the Pharsight Knowledgebase Server on page 461.
Microsoft Word export
WinNonlin can export the data from any or all open WinNonlin windows to
Microsoft Word. Modeling output for both compartmental models and NCA
can also be exported automatically after modeling completes. Charts and
model objects are exported as Windows bitmaps; thus, Word contains a repre-
sentation of these objects, but they cannot be edited after export. Worksheets
are exported as Word tables.
To export the active object to a new or existing Microsoft Word document:
1. If the WinNonlin data will be appended to an existing Word document, open
that document.
2. In WinNonlin, open the worksheet, chart or text window to be exported.
Apply any formatting needed for a chart; charts cannot be edited after export.
3. Click the Export to Word tool bar button.
If Word is not already running, WinNonlin will launch it and export the active
window to a new document. If a document is already open in Word, the
exported data will be appended to the end of that document.
Data Management
Data export
45
2
If the active object in WinNonlin is a workbook, the selected worksheet will
be exported to a Word table. If the active object is a chart, the selected chart
will be exported as a Windows bitmap. Text will appear in Word as text, in the
normal paragraph style.
To export modeling output to Word automatically:
1. With a model (compartmental or NCA) loaded, click the Start Modeling and
Export to Word tool bar button. This begins the calculation process and cre-
ates the output in Word in addition to the selected WinNonlin output forms.
To export data from multiple objects to a new Microsoft Word document:
1. Choose File>Word Export from the WinNonlin menus.
The Word Export dialog appears, with all open objects selected for export.
2. To select specific windows or objects within a window for export, uncheck
the Select all objects check box.
3. Use the + markers to expand the list of windows of a given type, and list of
objects for a given window.
4. Check the data to export.
5. Use the Options button to specify the Word export options, detailed on
page 46.
6. Click the Export button.
WinNonlin will launch Word, if necessary, and export the data to a new .DOC
file.
WinNonlin
Users Guide
46
2
Word export options
The following options apply to Microsoft Word exports performed using
File>Word Export in the WinNonlin menus.
Document options
Orientation: choose Portrait (long side of the page is vertical) or Land-
scape (long side of the page is horizontal) page setup for the Word docu-
ment
Add source line to objects: check this option to include text describing the
source file and object name to each object exported as follows.
Charts: adds the chart name (tab in the chart window) and absolute
path, file name and most-recent save date for the chart, below the
chart picture.
Workbooks: adds the worksheet name (tab in the workbook window)
and absolute path, file name and save date for the data, below the data
table.
Text: adds a heading above the exported text that reads, Text -
followed by the file path and name (or window name, if unsaved) in
square brackets.
Chart options
Multiple charts per page: Check this box and select the chart layout below
to arrange more than one chart on a page, with page breaks between sets
of charts.
Add page break: forces a page break before and after each chart.
Add log charts: creates and exports a chart with a logarithmic Y-axis for
each linear scatter chart exported. Each log chart appears below the origi-
nal linear chart.
Start figure numbers at N: adds figure numbers to charts. Check this
option and enter a number for the first figure to include the text Figure
N at the top left corner of each chart, where N is an integer, and incre-
mented for each chart.
Chart format: select whether to export the chart as a Windows metafile or
bitmap.
Data Management
Data export
47
2
Workbook options
Preserve formatting for tables: the formatting and layout of a workbook
that was created in WinNonlin with the Table Wizard will be exported
with the workbook (table) data. This option can slow the export process
significantly.
Start table numbers at N: adds table numbers to exported worksheets.
Each worksheet is one table in the Word export. Check this option and
enter a number for the first table to include the text Table N above each
table (exported worksheet), where N is an integer, and incremented for
each table.
SAS Transport file export
Any worksheet can be saved to a SAS Transport file format and thus exported
to SAS.
To export data to SAS (via SAS Transport files):
1. With the worksheet open in the active window, select Save As from the File
menu. The Save File dialog appears.
2. Select SAS Transport (*.xpt, *.stx) in the Save as Type list.
3. Name the file and click Save to create the file.
Note: SAS field naming conventions are more restrictive than those of WinNonlin.
Before exporting the data, WinNonlin will scan the column names, and
request new names for any that would be invalid in SAS. The new names
must be no longer than 8 characters, and are limited to alphanumeric charac-
ters and the underscore.
NONMEM export
WinNonlin provides a NONMEM Export function on the File menu, for
exporting observation and dosing data in NONMEM format. The NONMEM
data file generally contains two sections: the headers, and data.
Headers
It may be useful to document the following four items in the header:
WinNonlin
Users Guide
48
2
1. Names of columns. The first will be the names of the columns in the data
file. This will appear as a comment like that below:
# ID TIME WT GEND AGE BP DV MDV DVID AMT RATE EVID
In this example, the comment character is #. The choice of comment char-
acter is arbitrary.
2. Encodings. All NONMEM data are numeric. Thus, anything stored as
A, B, etc. or as male and female in WinNonlin must be encoded
as numeric values for use in NONMEM. Typically, this encoding is
explained in the header. For example, the header might contain:
# Variable GEND
# male = 1
# female = 2
3. DV column. The DV column, which holds the dependent variable, can
hold the values of more than one variable. Another column, the DVID
column, is used to disambiguate. The header can include the DVID col-
umn mappings. For example:
# Variables in DV column
# DEPC = 1
# DEPQ = 2
Thus, whenever DVID is 2, the value in DV represents DEPQ.
4. Abbreviations. NONMEM places a four-character restriction on names. A
NONMEM user will want to know how WinNonlin variable names map
to those used in NONMEM.
Data
The data generally include the following columns.
Position Column name Presence Description
1 ID Always provided. Subject identifier.
2 TIME Usually required. Nominal or actual time.
3 independent
variables
Optional. User may include as
many as are available.
The value of the independent variables.
There will be one column for each indepen-
dent variable.
4 DV Required. The dependent variables values. The name
DV is a fixed name for NONMEM.
Data Management
Data export
49
2
To export data to NONMEM:
1. Load a data set and model, and set up the model variables and dosing informa-
tion as detailed under Compartmental Modeling on page 247.
2. Choose File>NONMEM Export. The Export to NONMEM dialog appears.
3. Set the export data and settings using the following tabs.
5 MDV Always provided. (If DV is never
missing, then MDV can be skipped,
but, for simplicity, one should
always provide MDV.)
The status of the dependent variable with
the following meanings:
0: The row includes a valid value of DV
1: The row does not include an observation
of DV or the value is missing.
6 DVID Provided only when more than one
DV item is present.
If more than one dependent variable (DV
item) is exported, this column disambigu-
ates. Thus, if three DV items are chosen, this
column will show the value 1 for the first, 2
for the second, and 3 for the third.
7 AMT Required for PK. The amount value of the dosing variable.
8 RATE Frequently provided. The rate at which the dose was administered
(for infusions). This has some special val-
ues: 0 means that the dose is a bolus. A pos-
itive value means it is an infusion. -1 means
that it is a zero-order bolus dose for which
NONMEM calculates the duration. -2 means
that a zero order bolus for the rate is calcu-
lated. The RATE column shows a dot when
no value is administered.
9 CMT Usually provided. Indicates the compartment into which a dose
was administered or the compartment from
which DV was observed.
10 EVID This form export should always
include it.
The event type:
0: An observation event (for DV)
1: A dosing event
2: An other-type event
3: A reset event
4: A reset-and-dose event
Position Column name Presence Description
WinNonlin
Users Guide
50
2
4. When all settings are complete, click OK to create the NONMEM export file.
Files
Problem (optional): when exported, this string becomes the heading for the
NONMEM export file. It is useful to enter descriptive comments here to make
it clear what is in the data file. If a control stream is to be output with the data,
then this string will appear in the $PROB statement.
Data File: Enter the name of the output data file to be created, including the
full (absolute) file path, or use the Browse button to create or select a file.
Comment character: Enter a character to precede and identify comments in
the output file. The default is: #. The header rows will be preceded with this
character, which will also appear on the $INPUT COMMENT= command
option in the optional control stream.
Control stream: The control stream consists of directives, abbreviated code,
and parameter settings. The abbreviated code controls the model being used.
Select the appropriate radio button:
Do not generate control stream: available for users who wish to gener-
ate their own control stream. Inhibits the creation of a new control stream.
Generate skeleton control stream generates a skeletal control stream,
consisting of the $PROB, $FILE, and $INPUT commands only. Specify
the file location or use the Browse button to set a file and path.
Generate control stream from template creates a control stream from a
user-supplied template. Specify the template files location or use the
Browse button to locate it.
Tab name Description
Files Export file path and name, header information, comment identifier
Dependent Variables Dependent variables and dependent variable ID column
Other Data Items Independent variables
Dose Information Dosing variables and compartment to dose into (optional)
Occasions Identifiers for within-subject occasions to be considered separately,
as an additional means to explain variability
Data Management
Data export
51
2
Dependent Variables
Specify one or more dependent variable(s) for the NONMEM export by
checking the box under Select? for the appropriate columns. There must be at
least one dependent variable. All must use numeric values.
CMT stands for compartment. If the dependent variable is associated with a
particular compartment of a PK model, enter the compartment number here.
The CMT must be a non-negative integer, usually less than 10.
If multiple dependent variables have been selected, the dependent variable ID
(DVID) column is used to disambiguate them, and generate a separate column
for each. If more than one dependent variable is chosen, distinct positive inte-
gral values of a DVID variable must be assigned for each.
Other Data Items
This tab in the NONMEM export dialog is used primarily to select indepen-
dent variables. Independent variables differ from dependent variables in that
they must be named.
Select independent variables by checking the box under Select?. NONMEM
abbreviations for the variables are proposed, and can be edited. Each 4-char-
acter abbreviation must be unique and cannot be a NONMEM reserved name.
Dose Information
Select the Dose Information tab of the NONMEM export dialog to set options
on how to dose information is exported. These options include:
Derive RATE from the data.
Treat as bolus. All doses will be given a RATE of 0.
Have NONMEM calculate duration (RATE=1). For infusions, this
allows estimation of the duration parameter.
Have NONMEM calculate rate (RATE=2). For infusions, this allows
estimation of the rate parameter.
Include no dose information. In this case, no dose data are output; only
the worksheet data are output.
Associate dose with a compartment: To dose to a specific PK compart-
ment, check this box, then enter the compartment number in the CMT
files. The CMT value must be a non-negative integer less than 10. See the
WinNonlin
Users Guide
52
2
NONMEM NMTRAN documentation to determine which numbers to
enter for each compartment.
Occasions
Including occasional variation in a model can sometimes explain additional
variability in the data. The Occasions tab allows export of data to be used as
an indicator of occasions. At the beginning of an occasion, all compartment
concentrations will be set to 0.
Use occasions: check this box to generate an occasion identifier, and select a
method for creating occasions:
explicitly indicate the TIME value at which each occasion starts
indicate how long each occasion lasts
53
Chapter 3
ODBC Data Sharing
Exchanging data between WinNonlin and Open
Database Connectivity-compliant databases
The Enterprise edition of WinNonlin can exchange data with Open Database
Connectivity (ODBC) compliant databases (e.g., Oracle, SAS, etc.). In addi-
tion, it includes a Software Development Kit (SDK) for those users who wish
to build custom query tools.
The following sections cover:
ODBC import
ODBC export
The Enterprise Software Development Kit
ODBC import
Use the ODBC import to query and load data from an ODBC-compliant data-
base directly into WinNonlin. Setting up and running such imports involves
establishing a connection to the data source, then building a database query.
Connecting to the data source sets up a pointer to the database, called a
connection string, defining the database type and location.
Building a query specifies which data are to be imported. WinNonlin
translates the query settings into Structured Query Language (SQL) for
communication with the ODBC database. The SQL can be edited directly
before executing the query.
Refreshing a data set: When ODBC-imported data are loaded in WinNon-
lin (or saved to a local file and reloaded in WinNonlin), the ODBC import
command provides the option to update the data based on the current
database content.
WinNonlin
Users Guide
54
3
In addition, the Custom Query Builder makes it possible to build custom
dynamic link library (DLL) files to access additional data source types,
including Watson version 6.0 DMLIMS. See Importing data with the custom
query builder on page 64.
Import settings file
The connection string and query can be saved to an import settings file
(*.IMP), or import, for future re-use in the following operations.
Loading a saved connection extracts only the connection string from a
selected import file. It sets up a link to the database, to be used with a new
(or separately-saved) query. The connection string saved in an import file
can also be used to export to the specified database.
Loading a saved query: after a database connection is set up via a new or
saved connection string, the query portion of any import file can be
loaded. Thus, one set of query specifications can be re-used with different
databases, so long as each database contains the tables, fields, and record
values referred to in the query.
Loading an import extracts both the connection string and the query from
a saved import (*.IMP). This feature can be used to script ODBC imports,
if the database password is saved in the import.
Connecting to the data source
The first time that WinNonlin shares data with an ODBC-compliant database,
using an ODBC import or ODBC export, it is necessary to define a connection
string to point to the database type and location.
Most databases will require a user name and password each time the database
is accessed. The option to save the user name and password is available when
saving an import (see Building a query on page 58) or export (see Defining
an export on page 70). Note that the import or export file, and the password
inside it, are not encrypted, and therefore are not secure.
To create a new connection string:
1. Choose File>ODBC Import (or Export) from the WinNonlin menus. The
dialog for imports is shown below.
ODBC Data Sharing
ODBC import
55
3
An import (*.IMP) contains all information necessary to draw data from a
remote data source. It includes a connection string and a query to draw spe-
cific data from the data source. Similarly, an export contains a connection
string and an export definition mapping WinNonlin data columns to database
fields. See also Loading an import on page 63 and Loading an export on
page 75.
2. Select Create a new Import (or Export), and click Next.

3. Select Create a new connection and click Next.
The connection is embodied in a connection string, which defines the data-
base type and location, and can include the user name and password to access
the database. This connection string can also be loaded from a previously-
saved import (*.IMP) or export (*.EXP) file, as detailed under Loading a
saved connection on page 57.
4. Select a data source from one of the two tabs in the Select Data Source dialog.
The File Data Source tab (below) lists all file Data Source Names (DSNs)
and subdirectories on the system. These are file-based data sources that can be
shared among all users who have the same drivers installed. The data sources
need not be dedicated to a single user or local to a specific computer.
WinNonlin
Users Guide
56
3
The Machine Data Source information is stored in the machine's registry. The
machine data sources contain the majority of the connection string informa-
tion.
New data sources can be set up using the New button. See the Microsoft Win-
dows documentation for details.
5. After selecting a data source, click OK.
A log in dialog may appear for the specified data source, requiring a user
name and password for that data source.
ODBC Data Sharing
ODBC import
57
3
6. Enter the appropriate log in ID and password. These are set up by the Data-
base Administrator or Information Technology personnel. Click OK to pro-
ceed with the import or export.
The next step is to set up a query to pull the desired data from the database
(see Building a query on page 58), or an export definition to map WinNon-
lin data columns to database fields (see Defining an export on page 70).
Loading a saved connection
Once a connection string is created and saved in an import (*.IMP) or export
(*.EXP) file, that connection string can be loaded for use with different import
queries or export definitions.
To load an existing connection for use with a new query or export definition:
1. Choose File>ODBC import or File>ODBC export from the menus.
2. Select Create a new Import (or Export) in the first dialog and click Next.
3. Select Load an existing connection and click Next. An Open dialog appears.
4. Select the import file (*.IMP) or export definition file (*.EXP) containing the
connection string for the desired database.
5. Click Open.
6. Proceed with the import or export, as detailed under the following headings.
Import Export
Building a query on page 58 Defining an export on page 70
Loading a saved query on page 62 Loading a saved export definition on page 73
WinNonlin
Users Guide
58
3
Building a query
A query specifies the data to be imported to WinNonlin from an ODBC-com-
pliant database (see ODBC import on page 53). It notes the database table
and fields (optional) to import, and can include filters to extract specific
records from the table.
To create a new query:
1. Choose File>ODBC Import from the WinNonlin menus.
2. Load a a new or previously-saved connection string, as detailed under Con-
necting to the data source on page 54 and Loading a saved connection on
page 57, respectively.
3. After the database connection is loaded, the ODBC Import: Query dialog
appears, asking whether to build a new query or load an existing query. If a
similar query, with identical table and field names, has been previously saved
to an import file, see Loading a saved query on page 62; else, select Build a
Query and click Next.
The WinNonlin Query Builder will access the database, and load a list of the
available tables.
If the ODBC drivers provide the appro-
priate functionality, the Schema Filter
dialog appears. It provides a means to
filter the available database tables by
schema, a metadata organizational tool.
ODBC Data Sharing
ODBC import
59
3
4. If the Schema Filter dialog appears, select the schema to use in filtering the
list of data tables then click OK. These schema have been created by IT per-
sonnel as part of generating the databases.
5. When the list of available tables appears, select the source table from the list.
6. Click Next to select specific fields to be imported, or click Done to create a
Structured Query Language (SQL) query that loads all fields in the table and
proceed to step 10 below.
7. Select one or more of the fields to import from the table. If all the data from
those fields is to be imported, click the Done button and proceed to step 10
below. To filter the records to be imported, click Next.
WinNonlin
Users Guide
60
3
8. To create the filter:
a. Select a Field Name to filter on from that list box.
b. Choose an operator from that field's list box.
c. Enter a value in the Field Value field, click on the List Distinct Values
button to select from among all existing values for that field.
d. Click the Add button to set the filter.
e. If more than one criterion will be applied, select the And or Or radio but-
ton and return to step a above. Filters are applied in the order created.
9. Click Done when the filters are complete.
10. The Import: Final Settings dialog appears. Its top section displays the connec-
tion string. The middle section contains the SQL string for the query, in an
editable field. The lower section determines how the data will be formatted in
WinNonlin. Choose settings in this dialog (below), and edit the SQL if
desired.
ODBC Data Sharing
ODBC import
61
3
Set Column Widths adjusts the destination worksheet's columns to
match the widths of the fields in the database.
Set Column Names adjusts the destination worksheet to have the same
column names as the source fields.
Set Column Formats automatically formats columns containing time,
currency, and date data.
Check Number of Records? provides a count of the rows of filtered data
to be imported before the import is performed, and the option to return
and edit the query if the number of records is not as expected.
11. Click Finish to run the query and import the selected data to a WinNonlin
workbook.
If the Check Number of Records? check box has been selected, a dialog
appears with the number of records that this filter now specifies.
12. Next, the application provides an opportunity to save the query in an import
file (*.IMP).
The Save Import Query dialog provides the option to save the database user
name and password in the connection string, as part of the import file. This
allows scripting to handle database connectivity without any end user inter-
vention. Note, however, that the import file, and the password saved inside,
are not encrypted, and therefore may provide database access to anyone with
access to the import file.
WinNonlin
Users Guide
62
3
WinNonlin can import up to 65,000 rows of data in any one worksheet. Each
cell can contain up to 16KB of text. Additional limits may be imposed by the
ODBC drivers.
Once a data set has been imported, the data can be refreshed using the ODBC
Import command with the imported data sheet in the active window. The
software asks whether to refresh the current worksheet or to create a new
workbook. See Refreshing a data set on page 63.
Loading a saved query
Once a connection string (new or existing) has been established, any saved
query can be loaded. See Building a query on page 58 for instructions on
creating and saving queries.
To load an existing query:
1. Use File>ODBC Import from the WinNonlin menus to connect to a new or
previously-saved database, as detailed under Connecting to the data source
on page 54 and Loading a saved connection on page 57, respectively.
2. In the ODBC Import: Query dialog select Load a query and click Next.
3. An Open dialog appears. Select the appropriate import (*.IMP) file and click
Open. The ODBC Import: Final Settings dialog appears with the connection
string and query loaded.
ODBC Data Sharing
ODBC import
63
3
4. Click Finish to load the data into a WinNonlin workbook.
Loading an import
An import setting file (.IMP) can be used to quickly re-load data into WinNon-
lin, or as a starting point for a new import query (see ODBC import on
page 53). If the database password is saved in the import file, the import can
be called from WinNonlin scripts.
To load an existing import:
1. Choose File>ODBC Import from the WinNonlin menus.
2. In the Import dialog select Load an existing Import and click Next. An Open
dialog appears. The default file type is *.IMP.
3. Select the file with the desired connection string and click Open. The ODBC
Import: Final Settings dialog appears with all settings for that import loaded.
4. To change any of the settings specified in the Import: Final Settings dialog,
use the Back button to step back and make the corrections.
5. When the settings are correct, click the Finish button. The data from the data-
base are then loaded into a WinNonlin worksheet.
Refreshing a data set
When data from an ODBC import operation are open in WinNonlin, those
data can be refreshed from the database source by choosing the Import ODBC
command from the File menu.
WinNonlin
Users Guide
64
3
WinNonlin will refresh the data in the worksheet if Yes is clicked. The refresh
can also be accomplished by saving the workbook locally, and later opening it
and following this same procedure.
Importing data with the custom query builder
The Custom Query Builder provides a means to build custom dynamic link
library (DLL) files to access additional data source types, including Watson
version 6.0 DMLIMS. Further, WinNonlin Enterprise provides templates for
creating the DLL files to access custom data sources.
To use the custom query builder with Watson v. 6.0:
1. Select File>ODBC Import from the menus. The ODBC Import: Import dia-
log appears.
2. Select Use Custom Query Builder in the dialog.
3. Click Next.
ODBC Data Sharing
ODBC import
65
3
The Select a Builder dialog appears, to specify the data resources to access. If
the Custom Query Builder has not been used before, this dialog may be
empty.
4. To add resources to the Query Builder, click the Add button, and double-click
the appropriate DLL file, for example, WINNONLIN\CUSTOM QUERY BUILD-
ERS\WATSON_DMLIMS.DLL. The data source now shows as an available cus-
tom resource.
5. To configure the Watson DMLIMS custom resource to ensure that data are
imported correctly, select that item in the Select a Builder dialog and click
Edit. The Configuration dialog appears.
6. Enter the name of the owner of the Watson LIMS tables.
7. Enter the full directory path for the Watson templates or use the Browse but-
ton to locate the directory with the Watson templates. The location can be on
the local machine or on a network server.
8. Click OK to close the Configuration dialog.
9. Highlight Watson DMLIMS (or another custom query builder) in the Select
a Builder dialog and click the OK button.
10. A dialog asks whether to load a query. If no query has been saved for this
builder, click No. A log on dialog appears.
WinNonlin
Users Guide
66
3
Note: The user name, password, and alias for any custom database system (such as
the Watson DMLINS) are set by the database administrator or IT personnel.
Request this information from that person or department.
11. Enter user name, password, and database alias, and click OK. The Study
Selection dialog appears, listing the resources available in the data source.
Note: If nothing is displayed in the Study Selection dialog, contact your IT depart-
ment.
12. Select one (or more) study by clicking on the row in the grid. Use the Order
Study By field to sort any category (e.g., study number/ID, study director,
etc.) in order to find a particular listing more quickly.
13. Click Next. The Import Data Variables dialog appears, containing the list of
variables available in the selected database. As with the ODBC Import facil-
ODBC Data Sharing
ODBC import
67
3
ity, the options include loading all variables, some variables, or selected data
by using a filter.
14. If all available variables are desired, click the Select All button. If only a sub-
set of those variables is the goal, drag them to the Selected Variables field.
15. A particular combination of variables can be specified by saving them as a
template. In this way the same fields can be accessed repeatedly. To create a
new template drag the variables for the template to the Selected Variables
field and click the New button. Then enter a name for the template.
WinNonlin
Users Guide
68
3
Figure 3-1. A custom template
Note: The fields are imported in the order shown in the list box. Thus the order of
the variables in the Selected Variables list is significant.
16. Click Done if all the data in the selected fields are to be imported. The data
can also be filtered further by clicking Next. The Filter dialog appears.
ODBC Data Sharing
ODBC export
69
3
This filter dialog works exactly as the ODBC Import filter dialog does. See
ODBC import on page 53. A filter is defined by specifying one field name,
operator, and field value.
17. Select the Field from that list box. Choose the operator from that field's list
box. Either enter a value in the Value field or select from all specified values
of that field. To select from the existing values, click on the List Distinct Val-
ues button. This action fills the Value field with all the distinct values in the
table for the selected field. Select from the field values to build a filter (for
example, Time > 2). Click the Add button to set the filter.
Compound filters (e.g., Age > 12 and Gender = Male) can be created using
the And/Or operator criteria.
18. Click Done when the filter is complete, to load the data into a worksheet in
WinNonlin.
The Check # of rows returned option counts the result of the filter. This
option provides an easy check of whether the size of the import is what might
be expected.
To load an existing query:
1. The Watson DMLIMS Custom Query Builder asks whether to load an exist-
ing query.
2. Select Yes. The Open File dialog appears and provides the opportunity to
select an existing query. Select a file (file type *.WTS for Watson LIMS).
3. Click Open. The query is read and the file data is loaded into a worksheet.
Queries (*.WTS) are currently stored as ASCII files. This format may change
with future releases of the Custom Query Builder, Watson DMLIMS, or both.
ODBC export
WinNonlin Enterprise edition can export data to any ODBC-compliant data-
base. Like the ODBC import, the export operation requires a connection
WinNonlin
Users Guide
70
3
string to point to the database. In addition, it requires an export definition, to
map variables in the WinNonlin worksheet to fields in the database.
Connecting to the data source sets up a pointer to the database, called a
connection string, defining the database type and location. See Connect-
ing to the data source on page 54.
Defining an export specifies which data are to be exported, to what tables
and fields in the selected database.
Export settings file
The export settings, including the connection string and the export definition,
can be saved in an export file (*.EXP) for later re-use in the following opera-
tions.
Loading a saved connection extracts only the connection string from a
selected export file. It sets up a link to the database, to be used with a new
(or separately-saved) export. The connection string saved in an export file
can also be used to import data from the specified database. See Loading
a saved connection on page 57.
Loading a saved export definition: after a database connection is set up
via a new or saved connection string, the data mappings portion of any
export file can be loaded. Thus, one set of export specifications can be re-
used with different databases, so long as each database contains the
tables, fields, and record values referred to in the export file.
Loading an export extracts both the connection string and the export defi-
nition from a saved export file (*.EXP). This feature can be used to script
ODBC exports, if the database password is saved in the export file.
Defining an export
ODBC export sends selected data from any worksheet opened in WinNonlin
to an external database.
To export data from WinNonlin to an ODBC database:
1. With a data set in the active window, choose File>ODBC Export from the
WinNonlin menus. The ODBC Export dialog appears.
ODBC Data Sharing
ODBC export
71
3
2. To create a new database connection, select Create a new Export and click
Next. (Otherwise, see Loading a saved export definition on page 73.) The
ODBC Export: Connection dialog appears.
3. If the connection string has not been established and saved, select Create a
new connection and follow the instructions starting at step 4 of Connecting
to the data source on page 54. Otherwise, choose Load an existing connec-
tion and follow the steps under Loading a saved connection on page 57.
Once the connection string has been loaded, the ODBC Export: Definition
dialog appears.
WinNonlin
Users Guide
72
3
An export definition is similar to a query in that it too can be saved and
reloaded in the future. A given connection string can use more than one defi-
nition, hence the independent loads and saves. The definition sets the database
table to export data to, and maps the worksheet columns to fields in that table.
4. Select Build a Definition and click Next. See also Loading a saved export
definition on page 73.
As with the ODBC import, the schemas to use in selecting the data variables
can be specified. The Schema Filter dialog appears displaying available sche-
mas, if any.
5. If the Schema Filter dialog appears, select one item and click OK. Using
schema filters can speed up export operations using saved export files.
The Field Selection dialog appears with the names of the available database
tables in the Table Name list box.
6. Select the appropriate table in the Table Name field at the top of the dialog.
ODBC Data Sharing
ODBC export
73
3
7. Drag the variables from the Variables list to the appropriate database fields
under Field Definitions. Note that the variable names do not need to be identi-
cal to the field names (as is shown above).
8. To export one constant value for all records in a given field, check the Fixed
check box for that variable and enter the constant value under the field name
(instead of dragging and dropping in a variable name). This method can be
used to differentiate one export from another.
The data type and field size for each fields are set by the Database Adminis-
trator of the ODBC database.
9. Click OK. The data are copied to the database and WinNonlin asks whether to
save this database definition to a file (*.EXP). This file contains all informa-
tion needed to reproduce the same export, excluding any constants in fixed
fields.
Loading a saved export definition
The field mappings in any ODBC export definition file (*.EXP) can be re-used
with any database connection, assuming the field and table names in the
export file exactly match a table in the selected database.
To load a definition:
1. With a data set in the active window, choose File>ODBC Export from the
WinNonlin menus. The ODBC Export dialog appears.
2. Select Create a new Export and click Next. The ODBC Export: Connection
dialog appears.
WinNonlin
Users Guide
74
3
3. If the connection string has not been established and saved, select Create a
new connection and follow the instructions starting at step 4 of Connecting
to the data source on page 54. Otherwise, choose Load an existing connec-
tion and follow the steps under Loading a saved connection on page 57.
Once the connection string has been loaded, the ODBC Export: Definition
dialog appears.
4. Select Load a Definition and click Next.
5. An Open dialog appears. Select the appropriate export file (*.EXP) and click
the Open button.
6. Log on to the data source, if necessary.
7. If the Schema Filter dialog appears, use the Schema Filter to narrow the set of
available data tables (optional) and click OK.
The Field Selection dialog appears with the variables loaded in the appropri-
ate fields for the selected database.
8. Click OK to load the selected data to the database.
ODBC Data Sharing
The Enterprise Software Development Kit
75
3
Loading an export
Once an ODBC export has been created and saved, the export settings, includ-
ing the connection string and/or the export definition, can be reloaded for re-
use with any data set containing the column names used in the export file.
To load an existing export:
1. Choose File>ODBC Export from the WinNonlin menus. The ODBC Export:
Export dialog appears.
2. To load both a connection string (pointer to a specific database) and export
definition (mappings), select Load an Export and click Next. An Open dia-
log appears.
3. Select the desired export definition file (*.EXP) and click Open.
4. Log on to the data source if needed.
The Field Definitions are loaded automatically in the Field Selection dialog.
5. Make any needed edits to the export settings, and click OK to export the data.
The Enterprise Software Development Kit
The WinNonlin Enterprise edition includes a Software Development Kit
(SDK) for Developers, System Administrators and Database Administrators
who wish to create custom query builders.
Import file format
The Import file is an ASCII file, 6 lines contained in quotes.
BEGIN FILE (Note 6 lines)
WinNonlin
Users Guide
76
3
1 Connect string
2 Query
3 Set Column Formats (0 or 1:True or False)
4 Set Column Names (0 or 1:True or False)
5 Set Column Widths (0 or 1:True or False)
6 Set Max RC (Always set to 1)
END FILE
Example:
BEGIN FILE
"DRIVER=SQL Server;SERVER=thun-
der;UID=dan;APP=Visual Basic;WSID=THUNDER;Net-
work=DBMSSOCN;"
"Select Subject,Time1,Conc from bguide1a where (Subject =
'2 ')"
"0"
"0"
"1"
"1"
END FILE
Usage
Generally, the creation of an import file for loading should leave the connect
string blank, and let the application define the connect string, since the con-
nect string is dependent on the drivers installed on the machine. So, an import
file distributed by an IT department would, potentially, contain the following:
BEGIN FILE
""
"Select Subject,Time1,Conc from bguide1a where (Subject = '2 ')"
"0"
"0"
"1"
"1"
END FILE
ODBC Data Sharing
The Enterprise Software Development Kit
77
3
This would allow WinNonlin Enterprise to define the connect string. When
the end-user gets to the point of creating or loading a query, this file is loaded.
At the completion of the query, the import could be saved to store the connect
string generated by WinNonlin Enterprise. At this point a complete import file
has been created.
Export file format
An Export file is an ASCII file which contains 2+3*n lines where n is the
number of column-field definitions. Each column-field definition is repre-
sented by three (3) consecutive lines. The definition consists of the column in
the worksheet that is exported, the table field that the column is exported to,
and another line to determine if this field is fixed or not (i.e., a Flag, True or
False). If a field is fixed, the exported column in the worksheet is left blank.
BEGIN FILE
1 Connect String
2 Table Name (Table that data is exported to)
3 Worksheet Column for definition 1
4 Table Field for definition 1
5 Fixed Field Flag for definition 1
6 Worksheet Column for definition 2
7 Table Field for definition 2
8 Fixed Field Flag for definition 2

2+3*n-2) Worksheet Column for definition 1


2+3*n-1) Table Field for definition 1
2+3*n) Fixed Field Flag for definition 1
END FILE
Custom query builder interface
File: QUERYBUILDERINTERFACES.DLL
The customized query building intent is twofold:
1. To allow site-specific customization of the query building process.
2. To allow database specific customization of query building. In some
cases, it may be necessary to code to a specific database API set in order
WinNonlin
Users Guide
78
3
to optimize performance when determining access rights and database
structure (i.e. tables, fields, types).
Current State:
This ActiveX in-process server [QUERYBUILDERINTERFACES.DLL] is essen-
tially a stubbed out API. When this DLL is registered on a developer's
machine, the developer can make a reference to it and implement its interface.
The developer's new code will NOT compile unless all the interfaces in the
DLL are implemented.
The interfaces:
There are two interfaces, one that WinNonlin application accesses (IQUERY-
BUILDER) and one that the Custom Query Builder accesses (ICONSUMER).
The one that the Custom Query Builder accesses is the consumer of the data
that is being imported. The Custom Query Builder is responsible for import-
ing data into the WinNonlin object implementing the IConsumer interface.
This object is set by WinNonlin via the IQueryBuilder interface.
IQueryBuilder interface
The interface is composed of seven (7) properties and six (6) methods. This
interface is implemented by the Custom Query Builder. They are:
Table 3-1. Properties
Property Name Type Function
ConnectString String This is the connect string used by the generic
ODBC query builder. The Custom Query Builder
could build its own string. It is not required to do so.
QueryString String This is the final query string to be accessed once
the custom query builder is done. This string is
then passed to WinNonlin for audit purposes.
QueryBuilderDescription String A description of the query builder. It is also stored
in the registry when the Custom Query Builder is
added to WinNonlin.
QueryBuilderVersion String The version of the custom query builder. It is stored
in the registry when the Custom Query Builder is
added to WinNonlin.
ODBC Data Sharing
The Enterprise Software Development Kit
79
3
QueryBuilderExt String The extension used by the query builder for saving
import files. This enables refreshing of the data
source.
QueryBuilderListName String This will be used as the name in the list of available
Custom Query Builders.
AppHelpFile String This is used to set or get the help file name used
by the Custom Query Builder. This should point to
the exact location of the help file. Currently, the
help file is located in the same directory as the
DLL. When the resource manager registers the
DLL, it takes the path of the DLL, the name of the
DLL and appends .HLP on to the end of the name
to create the help file name to be used by the Cus-
tom Query Builder. It is up to the developer of the
Custom Query Builder whether this file is used as
the help file or not
Table 3-2. Methods
Method Name Type Function
GetQuery Long This tells the custom query builder to get the query
(i.e. build it). The return values are: <0 (Cancel),
=0 (No error), >0 (Error)
GetError String Returns the error message if one exists.
ConfigureCustomQuery-
Builder
String This is a hook to allow the Custom Query Builder
Manager to configure the DLL, if necessary. For
instance, for the WATSONLIMS.DLL, the owner of
the Watson tables must be defined if the log on ID
is not the owner. This information is stored in the
registry by the WATSONLIMS.DLL. For the Inte-
graware LIMS, the base table must be defined.
This is also stored in the registry. Other Custom
Query Builders could implement the configuration
however the programmers prefer. This method is
accessed when the user highlights the Custom
Query Builder on the Custom Query Builder list
and clicks Edit.
Table 3-1. Properties (continued)
Property Name Type Function
WinNonlin
Users Guide
80
3
IConsumer interface
The interface is composed of three (3) properties and no (0) methods. This
interface is accessed by the Custom Query Builder. They are:
VB example
Create a new project of type ActiveX DLL.
Add a reference to QueryBuilderInterfaces.DLL
ImportDataViaImportFile ImportFile
as string
This function takes an import file name (usually
built and saved by the Custom Query Builder), and
attempts to Import data based on the contents of
the Import File. This is used for scripting purposes.
The structure of the import file is up to the devel-
oper. The extension of the file should be the same
as returned in QueryBuilderExt.
WorkSheet wrhSht As
Iconsumer
This subroutine is called by WinNonlin to set the
consumer object in the Custom Query Builder. The
consumer object is an interface to the Worksheet
within the WinNonlin.
PopulateWorkSheet Long This function is called after the GetQuery function
and the WorkSheet subroutine. This tells the cus-
tom query builder to populate the worksheet
object that was handed to it in the WorkSheet sub-
rountine. The return values are: <0 (Cancel), =0
(No error), >0 (Error)
Table 3-3. Properties
Property Type Function
Cell (row As Long, col
As Long)
Variant Sets/Gets the value for the given row and col.
ColumnHeader(idx As
Long)
String This sets/gets the column header for the given
column.
Units(idx As Long) String Not implemented yet. Held for future use.
Table 3-2. Methods (continued)
Method Name Type Function
ODBC Data Sharing
The Enterprise Software Development Kit
81
3
Create a class named CQueryBuilder and make it public (i.e. accessible to the
rest of the world), implement QueryBuilderInterfaces.IQueryBuilder. Cur-
rently, it is required that the class implementing the interface is named CQue-
ryBuilder. The calling application currently needs to know the name of the
class to create that implements the interface. In the future, this may not be
necessary.
=====Begin Code Snippet
Option Explicit
Implements QueryBuilderInterfaces.IQueryBuilder
=====End Code Snippet
Now each required method and property can be defined as illustrated below.
Figure 3-2. Since IQueryBuilder is implemented, the object list has IQueryBuilder, and the associated
property/method/event list has the associated properties and methods for IQueryBuilder. If the property/
method is not defined, when selected in the list, the stubbed code will be generated.
Next, finish the coding required to generate a valid SQL Query. Simple
Object Diagram:
WinNonlin
Users Guide
82
3
Figure 3-3. Interfaces
IQueryBuilder
Properties:
ConnectString
QueryString
QueryBuilderDescription
QueryBuilderVersion
QueryBuilerExt
QueryBuilderListName
AppHelpFile
Methods:
GetQuery
GetError
ConfigCutsomQueryBuilder
ImportDataViaImportFile
WorkSheet
PopulateWorkSheet
IConsumer
Properties:
Cell
ColumnHeader
Units
ODBC Data Sharing
The Enterprise Software Development Kit
83
3
Figure 3-4. Flow Chart of Custom Query builder usage
Create object
implementing
IConsumer:
IWrkSht
Create an Instance of the
Custom Query Builder
(CQB) with interface
IQueryBuilder
Set QueryString,
AppHelpfile,
ConnectString
properties of the
CQB
Call WorkSheet
method of CQB
with the IWkrSht
as parameter
Canceled, no data
loaded
Show error
Message, no data
loaded
Canceled, no data
loaded
Show error
Message, no data
loaded
rc>0
rc>0
rc=0
rc=0
rc<0
rc<0
Call GetQuery
on the CQB
Call
PopulateWorksheet
method of the CQB
Return to
WinNonlin
main processing
WinNonlin
Users Guide
84
3
85
Chapter 4
Worksheets
Data editing, formatting, and manipulation in
WinNonlin worksheets
Input and output data for WinNonlin analyses are stored and manipulated in
Excel-compatible worksheets, shown as individual tabs within a workbook
window. Data can be typed into a new worksheet or imported from another
source. Worksheet functions comprise:
Editing data: editing and formatting worksheet data using formulas, func-
tions, copy and paste and fill-down
Data manipulation: data sorting, transformations, inclusion and exclusion,
merging data from separate workbooks, and transformation of non-
numeric values
Editing data
WinNonlin worksheets support spreadsheet-like data entry and formatting.
Numerical and text values may be entered directly into worksheet cells, and
cut, copied, and/or pasted between WinNonlin worksheets, or between Win-
Nonlin and other applications that support Windows Clipboard operations.
WinNonlin edit operations include the following:
Using formulas and functions on page 86
Filling adjacent cells on page 88
Clearing cell values and formats on page 89
Inserting and deleting rows, columns or cells on page 90
Inserting or deleting worksheets on page 92
Find, find next and replace on page 93
WinNonlin
Users Guide
86
4
Undo on page 95
Go to on page 96
Formatting cells on page 97
Setting column names and units on page 100
Using formulas and functions
Worksheet values may be entered as mathematical formulas. These can be
very useful for creating new variables and for filling in the values of a vari-
able as a function of other columns in the worksheet.
WinNonlin worksheets also support an extensive list of functions. Complete
syntax and examples are provided in Worksheet Functions on page 615.
Cell references
A cell is identified in formulas by its row and column labels. For example, A3
denotes the third cell in the first column. A range of cells is denoted using a
colon character, :, between the top-left and bottom-right cell in the range.
For example A1:B4, denotes the first four cells in the first two columns (eight
cells total).
A $ may be used to make either a row or column reference absolute in copy
and paste operations. Without this symbol, cell references are represented
internally by position relative to the currently-selected cell. For example, to
create a formula which subtracts the value in cell B3 from all values in col-
umn C, one might enter the formula =C1-B3 in D1, then copy this formula
down to the remainder of the column. Cell D1 will have the value of C1-B3;
D2 will have the value of C2-B4, etc. Entering =C1-B$3 and copying this
formula down to the remainder of the column will subtract the value in B3
from all cells in column D.

Table 4-1. Workbook operators
Operator Description
+ Addition
- Subtraction
/ Division
* Multiplication
Worksheets
Editing data
87
4
To create a new variable using a formula:
To create a new variable whose values are the square root of an existing vari-
able:
1. Using the mouse, select the first cell in the column of the new variable.
2. Type =SQRT(.
3. Click on the appropriate cell in the source column.
or
Type in the name of the source cell, e.g., B1.
4. Type ) and press Enter.
5. Position the cursor over the small black square at the lower right hand corner
of this cell until the cursor changes to a small black cross.
6. Press and hold the mouse button, and drag the cursor over the target cells.
This will copy the formula to the target cells.
This example can also be accomplished using the Transform command. See
Worksheet Functions on page 615.
To fill the values of a variable using a formula:
To create a variable in a worksheet with the values 0, 5, 10, 15, ..., 90:
1. Open a new grid.
^ Exponentiation
% Percentage
= Equal to
> Greater than
< Less than
>= Greater than or equal to
<= Less than or equal to
<> Not equal to
Table 4-1. Workbook operators (continued)
Operator Description
WinNonlin
Users Guide
88
4
2. In cell A1, enter the value 0.
3. In cell A2, enter: =A1+5.
4. With cell A2 active, position the cursor over the small black square at the
lower right hand corner of cell A2 until it changes to a small black cross.
5. Press and hold the mouse button, and drag the cursor to cell A19.
6. Release the mouse button. The grid cells contain the values from 0 to 90.
The edit bar
An edit bar appears at the top of the WinNonlin worksheet for editing a value
or formula the selected cell.
Formula edits made in the edit bar must be completed by pressing either the
Enter key or Esc key. If the edit is not entered in one of these ways, clicking
on other cells causes a cell reference to be inserted into the formula.
Filling adjacent cells
A value or formula from one cell can be filled to adjacent cells up, down, or to
the left or right.
To fill adjacent cells to the right and/or down:
1. Select the cells to be filled, including the cells to be copied as the left-most
cells in the selection.
2. Select Edit>Fill>Down or Edit>Fill>Right from the menus, or place the cur-
sor at the bottom right corner of the selection, and drag to fill right or down, or
both.
Worksheets
Editing data
89
4
To fill adjacent cells to the left:
1. Select the cells to be filled, including the cells to be copied as the right-most
cells in the selection.
2. Select Edit>Fill>Left from the menus.
To fill up to adjacent cells:
1. Select the cells to be filled, including the cells to be copied as the bottom-most
cells in the selection.
2. Select Edit>Fill>Up from the menus.
Clearing cell values and formats
When cells are cleared, the values and/or formats are cleared, but the cells
remain in the grid. To delete a cell from the grid, see Inserting and deleting
rows, columns or cells on page 90.
To clear data values from cells:
1. Select the cells to be cleared.
2. Choose Edit>Clear>Values from the menus.
Right-click in the worksheet and select Clear Values from the Shortcut menu.
or
Press the Delete key.
To clear formatting, such as font face and borders, from cells:
1. Select the cells to be cleared.
2. Select Edit>Clear>Formats from the menus.
To clear data values and formats from cells:
1. Select the cells to be cleared.
2. Select Edit>Clear>All from the menus.
This will delete the information from the cells, but will not remove the cells.
WinNonlin
Users Guide
90
4
Inserting and deleting rows, columns or cells
To insert a row:
1. Highlight a row by clicking on the row label.
2. Select Insert from the Edit menu (Alt+E, I)
or
Select Insert from the Shortcut menu. One row is inserted.
or
1. Highlight a cell within the row.
2. Select Insert from the Edit menu (Alt+E, I).
3. In the Insert dialog box which appears, select Entire Row.
A new row is inserted and the highlighted row is moved down.
To insert a column:
1. Highlight a column by clicking on the column label.
2. Select Insert from the Edit menu (Alt+E, I).
or
Select Insert from the Shortcut menu. A new column is inserted at that point,
shifting the highlighted column (and any others) right.
or
1. Highlight a cell within the column.
2. Select Insert from the Edit menu (Alt+E, I) or right-click on the selection
and choose shortcut menu.
3. In the Insert dialog box which appears, select Entire Column.
A column will be inserted before the active column.
Note: To insert multiple row or columns quickly, select the same number of rows or
columns as the number of rows or columns to be inserted prior to selecting
Insert from the Edit menu. For example, highlighting both columns B and C
before selecting Insert will have two new columns inserted.
Worksheets
Editing data
91
4
To insert a cell:
1. Select a cell with the mouse.
2. Select Insert from the Edit menu (Alt+E, I)
or
Right-click on the selection and choose Insert from the Shortcut menu.
3. In the dialog box that appears, select either Shift Cells Right or Shift Cells
Down. A single cell is inserted.
To delete cells:
1. Select the cell(s) to be deleted.
2. Select Delete from the Edit menu (Alt+E, D).
or
Right-click on the selection and choose Delete from the Shortcut menu.
3. From the Delete dialog box, select the direction to move the surrounding
cells.
To delete rows:
1. Select the row(s) to be deleted by highlighting the row label(s).
2. Select Delete from the Edit menu (Alt+E, D).
or
Right-click on the selection and choose Delete from the Shortcut menu. The
row is removed and rows beneath it are shifted up.
or
1. Select a cell in the row to be deleted, or cells in the rows to be deleted.
2. Select Delete from the Edit menu (Alt+E, D).
3. From the Delete dialog box, select Entire Row. The row is removed and rows
beneath it are shifted up.
To delete columns:
1. Select the column(s) to be deleted by highlighting the column label(s).
WinNonlin
Users Guide
92
4
2. Select Delete from the Edit menu (Alt+E, D).
or
Right-click on the selection and choose Delete from the Shortcut menu. The
highlighted column is deleted and columns to the right are shifted left.
or
1. Select a cell in the column to be deleted, or cells in the columns to be deleted.
2. Select Delete from the Edit menu (Alt+E, D).
3. From the Delete dialog box, select Entire Column. The highlighted column
is deleted and columns to the right are shifted left.
Inserting or deleting worksheets
When a new data file is opened two sheets are available in that workbook: an
observation worksheet and a worksheet labeled Data History. Other work-
sheets can be added to that workbook. Worksheets can also be deleted from a
workbook so long as one (data) worksheet and the Data History worksheet
remain.
To insert a new worksheet:
1. Select Insert Sheet from the Edit menu. A new blank worksheet is inserted
on top of the current worksheet. Each worksheet is available from their tab at
the bottom of the window.
To name a worksheet:
1. Select the worksheet to be named.
2. Double click on the tab for the sheet. The Sheet Name dialog appears.
3. Enter the name to be displayed on the tab.
4. Click OK. The worksheet tab now shows the appropriate name.
To delete a worksheet:
1. Make the worksheet to be deleted the active worksheet.
Worksheets
Editing data
93
4
2. Select Delete Sheet from the Edit menu. WinNonlin prompts to insure that
the active worksheet is to be deleted.
Find, find next and replace
To locate specific data values within a worksheet:
1. Choose Edit>Find from the WinNonlin menus (Alt+e, f or Ctrl+f).
2. Enter a numeric or text search string in the box labeled Find.
3. Select the appropriate options. The example below will find concentration
values from -0.1 to 0.1.
Case Sensitive
Checking this box causes only occurrences with the exact combination of
uppercase and lowercase letters to be found.
Search Area
Allows searching over the entire data set, the currently-selected column or a
selection of cells. In this example, the column Subject is shown as a potential
search area because the column Subject was active when this dialog box was
opened.
Operation
This option searches for a value:
Equal to the search string (=),
Less than the search string (<),
Less than or equal to the search string (<=),
Greater than the search string (>),
Greater than or equal to the search string (>=), or
Not equal to the search string (<>).
WinNonlin
Users Guide
94
4
The default for this operation is Equal to the search string. This means that
the search will look for exact matches only.
Tolerance
Finds values not different from the (numeric) search string by more than the
tolerance (optional).
4. Click Find.
To repeat the designated search:
1. Select Find Next from the Edit menu (Alt+E, N).
To replace text or data in a grid:
1. Select Replace from the Edit menu (Alt+E, E).
The Replace dialog box appears:
2. Enter a numeric or text search string in the box labeled Replace.
3. Enter a numeric or text replacement string in the box labeled With.
4. Select the appropriate options. The example above will replace all concentra-
tions with a value of BQL with zero. Note that, since the Case Sensitive
option is checked, values of bql will not be replaced.
Case Sensitive
Checking this box causes only occurrences with the exact combination of
uppercase and lowercase letters to be found.
Remove Row Matching Criteria
To remove the row where the search string is found, check this check box.
Worksheets
Editing data
95
4
Search Area
Specifies whether to search over the entire data set, a single column or a selec-
tion of cells. In this example, the column Subject is shown as a potential
search area because the column Subject was active when this dialog box was
opened.
Operation
This option searches for a value:
Equal to the search string (=),
Less than the search string (<),
Less than or equal to the search string (<=),
Greater than the search string (>),
Greater than or equal to the search string (>=), or
Not equal to the search string (<>).
Tolerance
A value not different from the search string by more than the tolerance will be
considered equal to the search string. This option is only applicable when the
search string is numeric.
5. Click Replace to review each occurrence before replacement.
or
Click Replace All to replace all occurrences without reviewing each.
Undo
The Undo capability allows the single, most-recent action to be reversed,
when performing data entry in a worksheet. Thus, it provides a means to cor-
rect a mistake made in entering or editing data.
To undo an operation:
Do one of the following:
1. Select Undo from the Edit menu (Alt+E, U).
or
Use the keyboard shortcut Ctrl+Z.
WinNonlin
Users Guide
96
4
or
Right click in the window and select Undo from the Shortcut menu.
The following table shows the effect of the Undo feature in data objects.
When an operation has been performed that can be undone, Undo will appear
as a normal selection on the Edit and Shortcut menus. If none of the above
listed operations have been executed, the Undo command is disabled.
Undo can be used on objects as well as data. For example, if a user has copied
a graph and pasted the graph into a spreadsheet, this paste can be undone.
Undo is not available on a read-only data set.
Go to
The Go to function jumps to a specific cell in the worksheet.
Table 4-2. Undo effects
Operation Undo Effect
Cut Restore cut value(s)
Paste Remove newly pasted value(s)
Clear Restore cleared value(s)
Fill Restore original value(s) or clear new ones
Insert Remove value(s)
Insert Row(s) Remove inserted row(s)
Delete Restore deleted value(s)
Delete Row(s) Restore deleted row(s)
Replace Restore original value(s)
Change Attributes Restore previous attribute setting
Include Restore original status of selected cell(s)
Exclude Restore original status of selected cell(s)
Sort Restore previous sort order
Transform Remove column containing transformation
Worksheets
Editing data
97
4
To move to a given cell using the cell reference:
1. Choose Data>Goto from the menus (Alt+D, G). The Goto dialog appears.
2. Select any worksheet in the active workbook under Sheet.
3. Enter the grid location of the cell. For example, for the third cell (3) in the first
column (A), enter: A3.
4. Click Goto.
Formatting cells
When the Data>Format command (or the Format tool bar button with a work-
book in the active window) is selected, the Format Cells dialog appears. The
Format Cells dialog has five tabs for specifying the following.
Number format
Alignment
Font face and format
Borders
Fill color and pattern
The choices made apply to the cell or region selected before opening the Data
Format dialog.
Note: Data formatting is not preserved with ASCII (text) files.
Number format
This tab allows selection of the appropriate format for the numbers in a cell,
row, column, or region.
To set the number format for a cell or selection of cells:
1. Select the cells using the mouse. The entire row(s) or column(s) can be
selected by highlighting the row or column label(s).
2. Select Format from the Data menu or click the Format tool bar button. The
Format Cells dialog appears.
WinNonlin
Users Guide
98
4
3. Select the Number tab in the Format Cells dialog.
4. Select a category for the number format from the Category list.
5. Select a format from the list of formats in the Type box. An example is dis-
played in the Sample field.
6. Click OK, or select another tab to enter other attributes.
This option is only applicable to numeric data.
Alignment
Use this tab to assign text alignment to the selected cell or cells.
To assign an alignment:
1. Select the cells using the mouse. The entire row(s) or column(s) can be
selected by highlighting the row or column label(s).
2. Select Format from the Data menu or click on the Format tool bar button.
The Format Cells dialog appears.
3. Select the Alignment tab of the Format Cells dialog.
4. Specify the horizontal alignment and the vertical alignment of the data in the
selected cells.
5. Check the Wrap Text option to wrap long strings of data to multiple lines
within a cell.
6. Click OK, or select another tab to enter other attributes.
Font face and format
Use this tab to assign a font face and formatting to the selected cell or cells.
To assign a font:
1. Select the cells using the mouse. The entire row(s) or column(s) can be
selected by highlighting the row or column label(s).
2. Select Format from the Data menu or click on the Format tool bar button.
The Format Cells dialog appears.
3. Select the Font tab of the Format Cells dialog.
Worksheets
Editing data
99
4
4. Select the Font, Font Style, Color, and/or Size to use. A sample is displayed.
5. Choose font effects by clicking the Strikeout and Underline check boxes.
6. Click OK, or select another tab to enter other attributes.
Borders
Use this tab to assign borders, including color and size, to the selected cell or
cells.
To assign a border:
1. Select the cell(s) using the mouse. The entire row(s) or column(s) can be
selected by highlighting the row or column label(s).
2. Select Format from the Data menu or click on the Format tool bar button.
The Format Cells dialog appears.
3. Select the Border tab of the Format Cells dialog.
4. Click on a line style button to select a line border style.
5. Select a color to use as color for the border.
6. Click on a button to indicate the position of the border lines.
7. Click OK, or select another tab to enter other attributes.
Fill color and pattern
Use this tab to assign color and fill pattern to the selected cell or cells.
To assign a pattern:
1. Select the cells using the mouse. The entire row(s) or column(s) can be
selected by highlighting the row or column label(s).
2. Select Format from the Data menu or click on the Format tool bar button.
The Format Cells dialog appears.
3. Select the Patterns tab of the Format Cells dialog.
4. Select a fill color from the palette.
5. Select a pattern color from the Pattern Color palette.
WinNonlin
Users Guide
100
4
6. Click on a pattern style from the Fill Pattern palette.
7. Click OK.
Setting column names and units
Column headers and units are set in the Column Properties dialog. See
Worksheet units on page 125 for details and instructions on units.
To specify column headers:
1. Highlight a cell in the column to be named.
2. Click on the Column Properties tool bar button. The Column Properties dia-
log appears.
or
Double click on a column header. The Column Properties dialog appears.
3. Highlight the column to be named.
4. Click the Edit Header button.
5. Type the name as the column header. Note that long column names may affect
performance.
6. Press Enter or click Close. The new column header is displayed in the data
grid.
Note: WinNonlin does not allow embedded spaces in column headers. If a data set is
loaded which has column names with embedded spaces WinNonlin will ask if
it can substitute an underscore (_) for the spaces (and offer the opportunity to
save the data set to a different name); otherwise, the data cannot be used in
analyses and models.
Data manipulation
WinNonlin worksheet operations include the following:
Freezing rows and columns on page 101
Sorting on page 101
Worksheets
Data manipulation
101
4
Transformations on page 102
Merge on page 106
Data exclusion and inclusion on page 108
Status code transformations on page 111
Freezing rows and columns
When working with a large file it may be convenient to create a non-scrolling
region with one or more row or one or more column in order to keep them on
the screen while scrolling through the remaining rows or columns. This can be
accomplished by Freezing a pane.
To freeze a row or column:
1. Select the column or row with the mouse by clicking on the column or row
label, or on a single cell in the row or column.
2. Choose Freeze Panes from the Window menu.
For example, identifying information for each record may be displayed in
Columns 1 and 2. This information may be important to show at all times,
even while scrolling across at the remaining columns. Follow the steps above
to freeze Column 2. Now in the file, Columns 1 and 2 stay in the display as
other columns scroll across.
To unfreeze rows and/or columns:
1. Select Unfreeze Pane from the Window menu.
Sorting
Sorting provides a quick means of ordering worksheet data.
To sort the data in a grid:
1. Select Sort from the Tools menu.
or
Click the Sort button on the tool bar. The Sort dialog box appears.
WinNonlin
Users Guide
102
4
2. Click on a variable name and drag it to the Sort box.
or
Highlight the variable then type the letter S while holding down the SHIFT
key.
3. Repeat for any other sort variables.
4. Select the sort order (Ascending or Descending) for the sort variables.
5. Click OK.
The Variables list in the Sort dialog contains all of the variables in the active
data set. If the data has been sorted previously, the sorted variables are already
listed in the Sort list.
Transformations
The data in a data set can be used in numerous transformations. The following
kinds of transformations are available in WinNonlin:
Natural log
Log base 10
Square root
Absolute value
Change from baseline
Percent change from baseline
Ratio from Baseline
X/Y, X+Y, X-Y, X*Y
e
x
, 1/X, X
n
, X*n, X/n, X+n, X-n
Worksheets
Data manipulation
103
4
where X and Y are variables [columns] in the current worksheet and n is a
number to be specified.
Some of these options require only the column to be transformed, while others
require the input of a constant, or a Time column also be specified. Examples
of several types of transformations are in the following sections.
Note: Exclusions are ignored when performing transformations.
To transform data in a grid:
1. With a data set open, select Transform from the Tools menu or click on the
Transform button on the tool bar. The Transform Data dialog box appears.
2. Select the desired transformation from the pull-down menu for Transform.
3. Select the variable to be used for X from the pull-down menu for Column x.
4. If required, enter a value for n in the box labeled n.
5. If required, select a variable to be used for time from the pull-down menu for
Time.
6. If required, select a variable to be used for Y from the pull-down menu for
Column y.
7. Replace [New] with a column name for the new variable.
8. Select either Adjacent or Append in the Destination Area to designate a posi-
tion for the new variable.
Adjacent positions the new variable just after the 'Column x' variable.
Append positions the new variable after the last variable in the data set.
9. Click OK.
Note: When using the Change from baseline, % Change from baseline, or Ratio
from baseline transformations, WinNonlin will select the value in Column x
corresponding to a value of 0 in the Time box. If a profile has more than one
value of 0 in the variable specified in the Time box, WinNonlin will use the
first observation as baseline.
Change from baseline or % Change from baseline can be computed for multi-
ple subsets of data using a sort variable. See the examples below.
WinNonlin
Users Guide
104
4
Examples
1. In the first example, a new variable, ln_CP, is created and placed in a
new column at the right end of the worksheet.
Note: Notice that units show along with variable names.
2. A new variable, Effect_baseline_adjusted, is created and
placed to the right of the original Effect column.
To calculate a change from baseline:
1. Click on the Transform button on the main tool bar.
or
Select Transform from the Tools menu. The Transform Data dialog box
appears.
2. Select Change from baseline from the Transform pull-down menu.
3. Select B from the Column x pull-down menu.
4. Select A from the Time pull-down menu.
5. Type Change in place of [New Column] in the Destination box.
6. Select Append in the Destination Area group box.
Worksheets
Data manipulation
105
4
7. Click OK.
WinNonlin queries whether to specify sort variables. Sort variables are used
to define unique profiles and to compute change from baseline separately for
each profile. In this example, there is only one profile.
8. Click No.
The resulting transformation is shown.
Note: For each profile WinNonlin looks for a 0 in the column Time to identify
which value of X is to be used as the baseline value. There are two records
here with a value of 0 for A. The first record was used as the baseline.
To calculate a change from baseline for multiple data subsets:
Calculate the change from baseline for each subject.
1. Click on the Transform button on the tool bar.
or
Select Transform from the Tools menu.
The Transform Data dialog box will appear.
2. Select Change from baseline from the Transform pull-down menu.
3. Select Conc from the Column x pull-down menu.
4. Select Time from the Time pull-down menu.
5. Type Change in place of [NewColumn] in the Destination box.
6. Select Append in the Destination Area.
WinNonlin queries whether to specify sort variables. In this example, there
are multiple profiles.
7. Click Yes.
The Sort dialog box appears.
8. Drag Subject to the Sort Variables list.
In this example, Subject is enough to define a unique profile. Other data may
require more than one variable, such as Subject and Period.
WinNonlin
Users Guide
106
4
9. Click Sort.
The result of the transformation calculated and appears.
Merge
When two or more data sets are open, the Merge command is available in
WinNonlin.
Note: Exclusions are ignored when merging data sets.
To merge data sets:
1. Open the two data sets to be merged. The Merge command is not enabled
when only one data set is available.
2. Select Merge from the Tools menu.
The Merge dialog box appears. This dialog box is divided into two areas for
Data Set 1 and Data Set 2 respectively.
3. Select a data set from the pull-down menu for Data Set 1.
4. Select another data set from the pull-down menu for Data Set 2.
The variables in each selected data set appear in the corresponding Variable
Collection box.
5. Use the Load button to load settings from a previously-saved file. Note that
the two datasets must be selected before loading settings, in the appropriate
order (data set 1 must contain the variables used in by data set 1 in the settings
file).
Worksheets
Data manipulation
107
4
6. In Data Set 1 area, drag a variable from the Variable Collection box to the Sort
Variables box. Drag the corresponding Sort variable to the appropriate box for
data set 2. If a secondary sort variable is needed, repeat with another variable
set.
The final merged data records will be matched according to these variables. If
the names differ, the name from data set 1 will be used for the column header
and the contents of both sort variables will be combined in this column. If
multiple sort variables are used, be sure that they appear in the same order in
the Sort Variables box for each data set.
7. In Data Set 1 area, drag variables from the Variable Collection box to the
Include Variables box.
8. In Data Set 2 area, drag variables from the Variable Collection box to the
Include Variables box.
These variables will appear in individual columns of the final merged data set.
They need not match in data sets 1 and 2.
The check box for Carry along data for similar sort keys is checked by default.
When this option is specified, and one data set has more observations for a
given level of the Sort variable(s), the last values for that level of the Sort
variables in the other data set are carried down to all observations for that
level of the Sort variables in the new data set. An example is shown below.
9. Click Merge. The merged data set appears.
Carry along data for like sort levels
The following example shows the effect of selecting the option Carry along
data for like Sort levels. Column A (letters) is a Sort Variable, while column B
(the game) is the Include Variable.
Table 4-3. Data set 1
A Archery
B Basketball
B Badminton
C Cricket
WinNonlin
Users Guide
108
4
Data exclusion and inclusion
Data can be selected for exclusion from analyses. For example, one group of
subjects may be analyzed, then a single subject may need to be refit. Rather
than creating an entirely new data set with this single individual, just exclude
all but the one subject and refit the data.
These selections may be based on specified criteria or upon selections of cells
made with the mouse.
Table 4-4. Data Set 2
B Backgammaon
C Cards
C Chess
D Dominoes
Table 4-5. Carry along data for like sort levels = Yes
A Archery
B Basketball Backgammon
B Badminton Backgammon
C Cricket Cards
C Cricket Chess
D Dominoes
Table 4-6. Carry along data for like sort levels = No
A Archery
B Basketball Backgammon
B Badminton
C Cricket Cards
C Chess
D Dominoes
Worksheets
Data manipulation
109
4
The data selections are done using the Exclude and Include commands on the
Data menu.
Note: In the analyses, excluded cells are treated as though they contain missing data.
Exclusions are ignored when merging data sets or performing transforma-
tions.
Excluding and including a selected range of cells
To exclude a selected range of cells:
1. Select the cells using the mouse. Select entire row(s) or column(s) by high-
lighting the row or column label(s).
2. Select Exclude from the Data menu, then select Selection (Alt+D, E, S). The
selected region is highlighted in red to indicate that it has been excluded.
To include a selected range of cells:
1. Select excluded cells using the mouse. Select entire row(s) or column(s) by
highlighting the row or column label(s).
2. Select Include from the Data menu, then select Selection (Alt+D, I, S). The
selected region now is no longer marked in red.
Excluding and including data based on criteria
To exclude data:
1. Select Exclude from the Data menu, then select Criteria... (Alt+D, E, C).
The Exclude dialog appears.
2. Enter the value(s) to be found in the Find field.
3. Select any desired options.
WinNonlin
Users Guide
110
4
Search Area
Allows searching over the entire data set, a single column, or a selection of
cells. In the example shown above, the column Time is shown as a potential
search area because Time was the active column when the dialog box was
opened. Entire Data Set is the default.
Exclude Row Matching Criteria
To exclude cells rather than rows, un-select Exclude Entire Row Matching
Criteria in the dialog box.
Case Sensitive
Checking this box causes only occurrences with the exact combination of
uppercase and lowercase letters to be found.
Criteria
Using this option search for a value:
equal to the search string (=),
less than the search string (<),
less than or equal to the search string (<=),
greater than the search string (>),
greater than or equal to the search string (>=), or
not equal to the search string (<>).
Tolerance
A value not different from the search string by more than the tolerance will be
considered equal to the search string. This option is applicable only when
searching for numeric data.
4. Click OK.
Worksheets
Data manipulation
111
4
To include data:
Once an exclusion is made, it is possible to re-include specific excluded rows.
1. Select Include from the Data menu, then select Criteria... (Alt+D, I, C).
2. In the Include dialog box, specify the value(s) to be found.
3. Select any desired options, from those described under Excluding and
including data based on criteria above.
4. Click OK.
Resetting selections
Resetting the data selections clears all exclusions in the selected worksheet.
Other worksheets in the same workbook will not be affected.
To remove exclusions from the current worksheet:
1. Select Reset Selections from the Data menu (Alt+D, N).
Status code transformations
The analysis, tabulation, plotting, and summarization of data are problematic
when the data contain concentrations that fall below the lower limit of quanti-
fication (LLOQ) of the assay. Furthermore, standard laboratory procedures
may require that such data be reported as a character string rather than a
numerical value. Representing such a concentration as 0 (zero) is not appro-
priate, in all cases, as doing so introduces a statistical bias or data misrepre-
sentation in some analyses. Different substitution rules are required
depending on the intended use of the data, and substitution rules vary between
companies and departments. Some common substitution rules for BQL sam-
ples are presented in the table below.
Table 4-7. Common status code substitution rules
Conditional substitution
Use data for: Non-
numeric
code
Unconditional
substitution
Before
Tmax
After
Tmax
First of
consecutive
after Tmax
After first of
consecutive
after Tmax
PK analysis
BQL 0 Missing LLOQ/2 Missing
WinNonlin
Users Guide
112
4
The substitution rules applied in any given situation are typically defined in
standard operating procedures or method sheets for a given company or
department. The rules may become more complex when one wishes to make a
distinction between concentrations that are below the quantification limit
(BQL) and below the detection limit (BDL). In general, a substitution rule is
defined by the list of possible non-numeric representations for concentration
and the values to be substituted for each. One possible substitution rule for
pharmacokinetic analyses is presented below:
WinNonlin provides a tool for transforming observation values from non-
numeric status codes to number values, for use in analyses and plots. The Sta-
tus Code Transformation Wizard is accessed through the WinNonlin Tools
menu. It creates a new workbook based on an existing one, by copying over
selected columns. It transforms values of the column representing concentra-
tion, as specified by user-defined rules. The numeric concentration data and
Summary statistics
BQL 0
Listing of individual
data
BQL "BQL "
Plotting of individual
data on log-scale
BQL LLOQ/2
Plotting of individual
data on linear scale
BQL 0
Table 4-7. Common status code substitution rules (continued)
Conditional substitution
Use data for: Non-
numeric
code
Unconditional
substitution
Before
Tmax
After
Tmax
First of
consecutive
after Tmax
After first of
consecutive
after Tmax
Table 4-8. Possible substitutions for PK analysis
Non-numeric
code
Unconditional
substitution
Before Tmax After Tmax First of consecutive
after Tmax
After first of conse-
cutive after Tmax
BQL 0 Missing LLOQ/2 Missing
NS Missing
ISV Missing
NA Missing

Worksheets
Data manipulation
113
4
the non-numeric concentration status codes may be the same or different col-
umns of the data set.
The wizard also stores information about the lower limit of quantification
(LLOQ) for one or more sampling assays. The user may specify an LLOQ and
the new column header into which it will be placed or identify an existing col-
umn containing the LLOQ for each observed concentration. If an LLOQ is
specified, it can be used in defining how status codes are transformed.
The settings in the wizard, including the transformation rules, can be saved to
and loaded from a file stored locally. The transformation rules may be saved
to, and loaded from the Pharsight Knowledgebase Server (PKS) as a system
object. See Rule sets on page 114 for instructions.
To select data to be transformed:
1. Open the data set in WinNonlin.
2. Choose Tools>Status Codes (e.g., BQL)... in the WinNonlin menus to launch
the Status Code Transformation Wizard.
3. At any point in this wizard, the settings and transformation rules may be saved
to a file using the Load and Save buttons.
4. Make sure the appropriate data set is selected under Data Set.
5. Drag and drop columns from the Variables list to assign the variables to be
included, and that to be transformed, in the output workbook:
Sort Keys: each unique combination of sort key values defines one profile
from which T-max will be calculated.
WinNonlin
Users Guide
114
4
Carry Alongs: variables to be copied into the output data set.
Time Variable: column containing observation times for the data that will
be transformed.
Concentration Variable: column containing the data to be transformed.
Status Code Variable: (optional) column containing the non-numeric sta-
tus codes associated with each datum in the Concentration Variable
(above); will determine transformation of those concentration values.
LLOQ Variable: (optional) column containing the LLOQ value associated
with each measurement in the Concentration Variable column; alternately,
a fixed LLOQ value, set by checking Static Value and entering the value
under LLOQ Value. Can be used in setting transformation values.
6. Click Next to proceed to the Rule sets.
Rule sets
Up to three rule sets may be included in the Status code transformations. A
rule set consists of a list of non-numeric codes, and the value substitutions to
be made when each code is encountered in the data. The substitutions may
apply unconditionally across the data, or conditionally depending when the
data point occurs relative to Tmax, and whether two or more consecutive
observations of the same code occur. Each rule set will generate a new column
of transformed observation data. The new variables will use the units (if any)
of the original concentration data.
To set up the status code transformation rules:
1. Click the Add button under Rule Sets to create a new rule set.
Worksheets
Data manipulation
115
4
2. It is possible to load rule sets from a local file or the PKS:
a. To import a rule set from an external file, stored locally, click Load.
b. To load a rule set from the PKS, check PKS Load and click Load.
c. Use the following steps to edit (if desired) and apply the rules.
3. Enter a name for the rule set under Rule Set Name. This name will be used in
the default name for the column generated by this rule.
4. Enter any descriptive text under Rule Set Description (optional).
5. Enter each status code to be transformed in a separate row, under Non-
Numeric Code. For each code, enter the following:
a. Unconditional Substitution: if the transformation is not dependent on
whether the status code occurs before or after Tmax, or is repeated, then
enter the value to which that code will be transformed here.
b. Conditional Substitutions: if the transformation depends on the status
codes position relative to Tmax and/or whether the code is repeated in
consecutive observations, then enter all four of the following:
Before Tmax: value to assign if the status code occurs before Tmax.
After Tmax: value to assign if an isolated (not more than one
consecutive) status code occurs after Tmax.
First of consecutive after Tmax: if the status code appears in two or
more contiguous observations, after Tmax, this value will be assigned
to the first of those contiguous observations.
After First of Consecutive after Tmax: if the status code appears in
two or more contiguous observations, after Tmax, this value will be
assigned to all but the first of those contiguous observations.
WinNonlin
Users Guide
116
4
c. Use when < LLOQ: click to toggle between Yes and No. Only one row
may be set to Yes. Yes indicates that when numeric values less than the
LLOQ are encountered, those values will be transformed, as though they
contained the status code in that row. The LLOQ value is set in the first
dialog of the Status Code Transformation Wizard, above.
Syntax for the rules
The status rules are not case-sensitive. The values entered may include num-
bers, operators, and the variable LLOQ, if a LLOQ value or data column was
assigned (see Status code transformations on page 111).
6. It is possible to save rule sets to a local file or the PKS:
a. To save a rule set to an external file, stored locally, click Save.
b. To save a rule set to the PKS as a system object, check PKS Load and
click Save.
7. Click OK when the rule set is complete.
8. Repeat steps 1 to 7 to create up to three rule sets.
9. Each rule set will generate a new data column in the output. The column name
can be edited under Worksheet Columns.
10. Click Next to proceed to the final dialog of the wizard.
The wizard will detect the presence of unidentified non-numeric codes in the
specified column. The unidentified codes will be listed in an alert dialog.
11. Review the summary of the transformation settings. When they are correct,
click the Finish button to create the new workbook.
Worksheets
Data manipulation
117
4
Note: If code-transformed data are saved to the PKS as a scenario, the applied
rule(s) will be stored with the scenario.
WinNonlin
Users Guide
118
4
119
Chapter 5
Units
WinNonlin supports the use of units throughout all operationsmodeling and
simulations, summary statistics, charts, LinMix, tables, etc. This chapter
explains notations, expectations and limitations of these operations with units.
Data stored in the Pharsight Knowledgebase Server (PKS) can have units
specified at the cell levelthat is, each cell within a column can have different
units. The units can be specified in an associated column (see table below).
That is, the PKS can handle data:
Figure 5-1.
WinNonlin cannot operate with data that has different units in different rows
within the column. Thus, if data sets with different units exist in the PKS, the
Unit Conversion capabilities of the PKS must be used in order to convert the
entire column of data to one unit before these data sets can be loaded into
WinNonlin.
Once units are entered, they can be saved (in a Pharsight workbook object),
carried through in operations, and displayed in all output forms.
Subject
number
Time Time unit Observation Observation
unit
Subject
age
Subject
age Unit
1 0 hr 2.5 g/ml 245 days
1 1 hr 2.1 g/ml 245 days
1 2 hr 1.1 g/ml 245 days
2 0 hr 1.4 g/l 1 year
2 1 hr 1.8 g/l 1 year
WinNonlin
Users Guide
120
5
Units display
Units for a data set are entered in the Column Properties dialog and are associ-
ated with a particular variable/column in the data set. (See Worksheet units
on page 125 for an explanation of how to enter units for a data set.) Once units
are entered they will display in the column header of the worksheet.
Note: Units entered in a data set can be saved with the data in Pharsight workbook
objects (.PWO). Other file types do not preserve units.
If the units are not standard or recognizable, WinNonlin will display them in
braces: {furlongs}. Nonstandard unitsunits enclosed in braceswill
be carried throughout any operations, such as descriptive statistics, but Win-
Nonlin will not know how to operate with them in any calculations. If there
are conversions to be made, the user will have to make them.
In the data set PK.PWO the column named Effect has units of %, a unit that
WinNonlin does not recognize. Therefore it includes it in brackets.
All units associated with a data column are displayed in parentheses below the
column name/heading.
Units
Units options
121
5
Units options
WinNonlin provides options to display units in workbooks, charts, and tables.
The options are set on the Units tab of the Options dialog, accessed on the
Tools menu.
These options can be overridden for a particular modeling session in the
Model Options dialog.
Unit types
WinNonlin expects the X and Y variables to carry appropriate units, generally
time for the X variable. Permissible units include the following.
Table 5-1. Unit types
Unit type Unit Abbreviation
Time
day day
hour hr
minute min
second s
millisecond ms
microsecond us
nanosecond ns
WinNonlin
Users Guide
122
5
Prefixes
Prefixes can be used for units of mass and volume.
Note: Units are not case-sensitive.
Dosing units
Dosing units are specified on the Dosing Regimen tab, which is available only
after a model has been loaded and data variables have been specified.
Mass
gram g
mole mol
pound lb
IU IU
Volume
Liter L
Table 5-2. Prefixes
Prefix Abbreviation
femto
f
pico
p
nano
n
micro
u
milli
m
centi
c
deci
d
deca
dk
kilo
k
Table 5-1. Unit types (continued)
Unit type Unit Abbreviation
Units
Dosing units
123
5
To set dosing units:
1. Load a data set and model.
2. Set the model data variables (Model>Data Variables).
3. Select Model>Dosing Regimen from the menus. The Model Properties dia-
log appears with the Dosing Regimen tab active.
4. Enter values for each subject.
5. Enter the desired units in the Current Units field.
6. Click the Apply button.
7. Select the Model Parameters tab of the dialog.
WinNonlin
Users Guide
124
5
Notice that the units for the model parameters are displayed. The units cannot
be edited here. See Preferred units on page 125 to set these. The units will
appear in the modeling output.
Dose normalization
Dose normalization indicates that dose amounts are given per unit of body
weight or per unit of body surface area. For example, if 10 mg of a drug is
given for each kg of body weight, then the dose is 10 mg/kg. The user would
enter this as a dose amount of 10, dose units of mg, and dose normalization of
kg. The supplied units for body weight are kg, g, and mg, and the supplied
units for body surface area are m**2 or 1.73m**2. If the dose amount entered
is the total dose, i.e., not given per unit, then the dose normalization should be
set to None.
Supplying a dose normalization will affect the units displayed for some
parameters in the output as well as on the Units tab of the Model Options
frame. For example, if Volume units had been mL with no dose normalization,
and if a dose normalization of kg were used, the units for volume would
become mL/kg. For NCA models and PK models, all volume and clearance
parameters, such as V, V1, VSS., Vz, V_F, CL, CL_F, and CLD2, are affected
by dose normalization. Additional parameters affected by dose normalization
are AUC/D in NCA plasma models, and Percent_Recovered in NCA urine
models.
Units
Preferred units
125
5
Note: If the data sets X-variable and Y-variable already have units when doing PK
modeling, then specifying dosing units on the Dosing Regimen tab provides
units for the model parameters on the Model Parameters tab.
Preferred units
Preferred output units in a modeling or simulation can be specified only after
the X variable, Y variable, and dosing all have units specified.
When the preferred units for the model are changed, and therefore not the
defaults, WinNonlin will automatically convert the output data. Any combina-
tion of preferred units can be saved to an external file which can be loaded
and reused.
Worksheet units
WinNonlin provides the ability to associate a column with specific units. The
units are used throughout data calculations. Options include whether to have
the units displayed in input and output workbook columns and in tables and
charts. See WinNonlin options on page 33 for information on default units.
WinNonlin
Users Guide
126
5
Entering units
Any data column can have units associated with it, using either the Column
Properties dialog or the Units Builder.
To enter units for a column:
1. Click the Column Properties tool bar button or select Column Properties
from the Data menu. The Column Properties dialog appears.
2. Select the column name in the column header field.
3. Enter the units for that column in the New Units field.
4. Click the Specify Units button. The units now appear in the variable list box
and in the data set associated with that column.
5. Click Close to close the dialog.
Units can also be entered by using the Units Builder. The Units Builder uses
units of Time, Mass, and Volume and includes standard operators.
To use the Units Builder:
1. In the Column Properties dialog click on the Units Builder button. The Units
Builder dialog displays.
2. Select the kind of unit (Time, Mass, or Volume) and select the appropriate unit
from the list box.
3. Prefixes (kilo, milli, etc.) can be selected from the Prefix field.
4. Once the unit (with appropriate prefix) displays correctly click on the Add
button to the right of that kind of unit. The appropriate unit abbreviation dis-
plays in the New Units field.
5. Click OK to close the Units Builder.
6. Click the Specify Units button to associate the units with the data column.
7. Click Close to close the Column Properties dialog.
To build units with operators (grams/ml, for example), enter the units and
operators in order.
Units
Worksheet units
127
5
Note: Units can only be preserved in data saved as Pharsight Workbook Objects
(.PWO). Other file types can have units in labels of cells or in headings, but
units in the headers are lost when the file is closed.
Clearing units
The units associated with any data column/variable can be cleared.
To clear the units associated with a column:
1. Click on a cell in the column to operate on.
2. Click on the Column Properties tool bar button. The Column Properties dia-
log appears with the column selected. The current units display in the list box.
3. Click the Clear Units button.
4. Click Close to close the dialog.
Converting units
Units can be converted automatically using the Column Properties dialog of
WinNonlin.
To convert units:
1. Click on a cell in the column with the units to be converted.
2. Click on the Column Properties tool bar button. The Column Properties dia-
log appears with the column selected. The current units appears in the list box.
3. Enter the new units in the Specify Units field. The Convert Units button
becomes enabled.
4. Click the Convert Units button. The data in the column are converted along
with the units.
WinNonlin
Users Guide
128
5
129
Chapter 6
Charts
Using the Chart Wizard and Chart Designer to
create and format plots
WinNonlin provides high quality graphs of input data and modeling and anal-
ysis output. There are two ways to obtain a plot of data.
1. Chart Wizard: Use the Chart Wizard tool bar button or the Chart Wizard
command on the Tools menu to create an XY plot, bar chart, or histogram
of data in any worksheet. Edit the chart type (including additional types)
and formatting using the Chart Designer.
2. Post Model Fitting: Plots of the data from a model fitting or simulation
can be generated automatically. This option is selected on the Output tab
of the Model Options dialog (Tools>Model Options). See the sections on
Noncompartmental Analysis (page 215) and Compartmental Modeling
(page 247) for more information on charts generated during modeling.
Chart Wizard
Use the Chart Wizard to create an XY scatter plot, bar chart, or histogram.
Once the basic plot is created, the plot type and formatting can be changed
and enhanced using the Chart Designer, which provides a selection of addi-
tional plot and chart types.
To create a plot:
1. Open the workbook(s) and worksheet(s) containing data to plot. The work-
book must not be hidden. The worksheet containing data to plot must be the
active worksheet in the workbook window.
2. Click the Chart Wizard tool bar button or choose Tools>Chart Wizard
from the WinNonlin menus. The Chart Wizard appears.
WinNonlin
Users Guide
130
6
3. Choose a chart type.
Note: Additional chart types are available. Create a scatter plot, bar chart, or histo-
gram with the desired variables, then use the Chart Designer to modify the
plot type. See Chart Designer on page 137.
4. Click the Next button to set up the following.
X-Y variables
Sort and group variables
Error bars (scatter plots only)
Chart titles
X-Y variables
The X-Y variables tab, on the second dialog of the Chart Wizard, sets up the
of independent and dependent variables to be plotted. These settings differ for
Scatter plots and bar charts versus Histograms.
Scatter plots and bar charts
To select variables for a scatter plot or bar chart:
1. Make sure that the workbook to be plotted is displayed in the Data Set field.
The columns in the active worksheet are listed in the Variable Collection list.
Charts
Chart Wizard
131
6
2. To specify each X or Y variable, highlight a variable under Variable Collec-
tion and drag it to the appropriate Variable box. Each variable may be used
more than once.
3. To create an overlay chart, showing more than one pair of X and Y variables:
a. If all variables are in one workbook, drag paired sets of X and Y variables
to the appropriate variable boxes, so that pairs are listed side-by-side.
b. If the variables come from more than one workbook, select a second
workbook under Data Set to select X and Y variables from that data set.
4. (Scatter plots only) check Automatic Sorting to sort the data into ascending
X-value order before drawing plot lines. This option would not be selected for
a hysteresis curve. Figure 6-1 below provides an illustration of a simple data
set plotted with and without automatic sorting.
Figure 6-1. Plotting data with (right) and without (middle) automatic sorting
WinNonlin
Users Guide
132
6
5. To create multiple plots or multiple series within a plot, click the Sorting tab
and follow the directions under Sort and group variables on page 133.
6. (Scatter plots only) To set up error bars, open that tab of the dialog and see
Error bars on page 133.
7. Click Next to proceed to the Chart titles.
Histograms
To select variables for a histogram:
1. Make sure that the workbook to be plotted is displayed in the Data Set field.
The columns in the active worksheet are listed in the Variable Collection list.
2. To specify the variable(s) for which frequencies will be displayed, highlight a
variable under Variable Collection and drag it to the Y Variable box. Repeat to
add variables to be displayed on the same set of axes.
3. Enter the desired number of intervals for the X axis (optional) under Number
of Intervals.
WinNonlin will determine the range of the Y variable, divide this range into
the number of intervals (user-specified or generated by WinNonlin), then
count the number of observations that fall into each interval. This count deter-
minates the height of each bar, i.e., the frequency for each interval.
4. To create multiple plots, click the Sorting tab and follow the directions under
Sort and group variables on page 133.
5. Click Next to proceed to the Chart titles.
Charts
Chart Wizard
133
6
Sort and group variables
To sort data into multiple plots, or group data series within a plot:
1. On the Sorting tab of the Chart Wizard. (See Chart Wizard on page 129 to
access the Chart Wizard.)
2. Drag and drop variables from the Variable Collection list to the Sort or Group
variable boxes:
Sort variable(s): a separate plot (set of axes) will be created for each
unique combination of sort variable values.
Group variable: each plot will contain a separate line (scatter plot) or set
of bars (bar charts) for each unique combination of group variable values.
The example illustrated above will generate one plot for each drug formula-
tion, with individual lines (scatter) or bars (bar chart) for each subject.
3. (Scatter plots only) To set up error bars, open that tab of the dialog and see
Error bars on page 133.
4. Click Next to proceed to the Chart titles.
Error bars
To add error bars to a scatter plot:
1. On the Error Bars tab of the Chart Wizard (see Chart Wizard on page 129)
and set the following:
WinNonlin
Users Guide
134
6
a. Up variable: error values in the upward direction (Y-axis increase) from
the means.
b. Down variable: error values in the downward direction (Y-axis decrease)
from the means.
c. Relative error bars: error values are expressed as absolute difference from
the mean; that is, each error value is added to (up variable) or subtracted
from (down variable) the corresponding datum.
d. Absolute error bars: Error data are expressed as Y-axis co-ordinates for
the top (up variable) or bottom (down variable) of each error bar.
CAUTION: In overlay charts (more than one set of X-Y variables per chart), the selection
of absolute versus relative error bars applies to all data series in the chart.
Relative error bars may be used to plot average concentrations, or another
mean value, plus or minus the standard deviation or error at each time point.
In this case, the standard error supplies both the Up and Down variables.
Charts
Chart Wizard
135
6
Figure 6-2. Plotting mean and standard error using relative error bars
Absolute error bars are useful for plotting more than one value at each X-axis
point, e.g. minimum, mean and maximum, as illustrated below.
Figure 6-3. PLotting mean and minimum values using absolute error bars
2. Click Next to proceed to the Chart titles.
0
1
2
3
4
5
6
0 1 2 3 4 5 6
Mean = 3
Standard Error = 1
UP variable = Standard Error
Down variable = Standard
Error
Relative Error Bars
0
1
2
3
4
5
6
0 1 2 3 4 5 6
Mean = 3
Minimum = 1
Up variable = blank
Down variable = Minimum
Absolute Error Bars
WinNonlin
Users Guide
136
6
Chart titles
1. To include a chart title, enter it in the Title field.
2. Select or enter the other options:
Axis titles are entered automatically using the variable names from the
data set.To change an axis title, select that field and enter it in the appro-
priate axis title field.
Units: Enter or edit the units for the axis labels. If the option to show units
on chart labels is set and the variable already has units specified, those
units will appear here.
Sort key title: If sort variables are used the sort key title may be edited for
each variable by selecting each number in the sort key field.
Use group headers: Check this option to include a heading identifying the
group variable value(s) at the top of each chart.
Legend: When more than one pair of X and Y variables is included on a
chart, the Legend field is available. Enter legend text in the left-most field
under Legend, to identify each X-Y pair.
3. Click Finish to create the chart. The chart window displays the plot(s) of the
data.
Charts
Axis options
137
6
Axis options
Once a plot is created using the Chart Wizard, the X and Y axes can be altered
as follows. See also Chart Designer on page 137 for other formatting
options.
To set axis options
1. Choose Chart>Axis Options from the menus. The Axis Options dialog
appears.
2. Select the appropriate options from the following.
Uniform Axis: If a sort key was used to identify multiple profiles, uniform
axes (same axis range and divisions) can be applied to all profiles, for the
X-axis, the Y-axis, or both.
Logarithmic: Check this box to plot on a natural-log scale.
Intervals: For a histogram, enter the number of intervals under Intervals.
3. Click OK.
Chart Designer
WinNonlin provides flexibility in manipulating and printing plotted data. The
data can be formatted, organized and presented in many different ways.
The Chart Wizard (See Charts on page 129. ) is used to create basic scatter,
bar and histogram charts. The Chart Designer formats and enhances charts
created using the Chart Wizard. The Chart Designer allows a selection from
numerous additional plot and chart types: area charts, bar charts, line charts,
step charts, combination charts, pie charts, doughnut charts, radar charts, XY
charts, polar charts, bubble charts, hi-lo charts, Gantt charts, elevation charts,
XYZ charts, and scatter charts. Chart titles, footnotes, legends, axis and axis
titles, axis labels, series data points, data point labels, and series labels can be
added or edited.
This section includes:
Starting the chart designer on page 138
Selecting the plot type on page 139
Formatting a series on the plot on page 147
WinNonlin
Users Guide
138
6
Formatting series data point labels and axis labels on page 157
Formatting an axis on page 164
Formatting axis titles, footnotes, legends, and chart titles on page 171
Frequently used graph formatting options on page 178
Starting the chart designer
The Chart Designer is only accessible after a chart has been created, either
manually with the Chart Wizard or automatically as part of modeling output.
To start the Chart Designer:
1. With a chart in the active window, choose Chart>Chart Designer from the
WinNonlin menus, or double click within a chart in the active windowbut
not on a specific plot element.
or
1. With a chart in the active window, click the right mouse button on the chart.
The shortcut menu appears. Select Chart Designer.
The Chart Designer appears. The tabs displayed on the right side vary as dif-
ferent elements are selected in the tree view to the left.
The Chart Designer provides a tree view that allows all the design elements of
a chart to be seen. The tree view is very similar to Windows Explorer. Ele-
ments with a + before them can be expanded further by clicking on them. The
Chart Designer also provides tabbed pages in the main window with format-
ting controls.
Charts
Chart Designer
139
6
The tabs displayed depend upon which elements have been selected. When a
particular part of a chart (the X-axis, for example) has been selected, the Chart
Designer opens with the controls for that part available.
Multiple elements can be selected from that tree viewall chart series, for
example. The pages displayed then apply to all of the chart series rather than
just one of them.
Often chart elements can be manipulated without even having to access the
Chart Designer's dialogs. For example to move an existing text element (the
chart title, for example) just drag and drop it to a new location in the chart
window without having to go through the Chart Designer dialog.
When the Chart Designer dialog is used, it provides options for controls on
the tabbed pages. These options are applied to the chart once the Apply button
(which executes the changes and leaves the dialog open for any further action)
or the OK button (which executes the changes and closes the Chart Designer
dialog) has been clicked. Just moving from one tabbed page to another makes
no changes.
Selecting the plot type
To select the type of plot:
1. Start the Chart Designer. See Starting the chart designer on page 138.
2. If necessary, click on Chart at the top of the tree view. Three tabs (Type,
Backdrop, and Picture) appear on the right side of the dialog.
3. Select the Type tab.
The list of chart types changes depending upon whether two-dimensional or
three-dimensional chart types are selected. The Chart Designer provides an
extensive list of chart types. The plot format can be changed (depending upon
the data specified from the data set) for any plot created in WinNonlin, but the
default plot types are set in the Chart Wizard.
WinNonlin
Users Guide
140
6
4. Select the appropriate chart type from the list displayed in the list box. For
more information on each chart type click on the Help button. The online help
system includes information about the requirements for each chart type.
5. Set any Chart type options. When all options have been specified, click OK or
click the Apply button to redraw the plot on the screen to reflect the new set-
tings without closing the dialog box.
Plot type options
Layout text
For Printing Choose this radio button to use TrueType virtual font metrics to
optimize text layout for printing. TrueType virtual font metrics may not be
very accurate for text displayed on the screen. Text displayed on the screen
may be larger or smaller than the virtual metrics requested. Larger text may
not fit where it is supposed to, and part of a character, a whole character, or
even in some cases whole words may be clipped on the screen but will print
out correctly.
For Display Choose this radio button to optimize text layout for the screen.
Text in charts laid out for screen display always fits correctly within its chart
area. The printed text is generally a bit smaller and so the text may appear in
slightly different places.
Data in Rows Click this to read series data from data grid rows rather than
columns.
Reset Chart to Defaults Click this button to reset the chart to default settings.
Charts
Chart Designer
141
6
Specifying chart backdrops
Any chart's appearance can be enhanced by using a backdrop or placing indi-
vidual elements in the chart. The backdrop can include a frame or box around
the chart or chart element, a shadow behind the element, or a pattern or gradi-
ent behind the element.
To edit a plot backdrop:
1. Start the Chart Designer. See Starting the chart designer on page 138.
2. In the Chart Designer dialog box select the appropriate chart element(s).
When multiple elements are selected, only the common controls appear in the
pane on the right.
3. Select the Backdrop tab. This tab applies to the following chart elements:
Chart, Axis Label, Axis Title, Datapoint Label, Footnote, Axis Label, Legend,
Plot, Series Label, Title.
4. Select the options desired. The options include:
Fill
The fill settings in the Backdrop tab allow setting a backdrop color and/or
effect. A color gradient or patterned color brush and the fill/from color and
the pattern/to color can be specified. The choices include a number of colors
and patterns. These include:
No Fill The selected chart control or chart elements have no fill, so any for-
matting applied to the surface behind them shows through. A picture can still
be applied to an element with no fill.
WinNonlin
Users Guide
142
6
Gradient Select the type of gradient from the types in the list box.
Brush Fill Select a pattern or solid color from the color palettes.
Fill/From Color Click the control to display the color palette. Choose a pre-
defined color or choose custom to display the custom color palette.
The fill color is used to create a solid pattern that serves as the background
color behind a pattern.
For a gradient fill, use the Fill/From Color list box to specify the color used
as the top color in a horizontal gradient, the left color in a vertical gradient,
and the center color in a rectangle or oval gradient.
Pattern/To Color Click the control to display the color picker. Choose a pre-
defined color or choose custom to display the custom color palette.
The pattern color is used to draw the pattern on top of the fill color.
For a gradient fill, use the Pattern/To Color list box to specify the color used
as the bottom color in a horizontal gradient, the right color in a vertical gradi-
ent, and the outer color in a rectangle or oval gradient.
Frame
The settings in the Frame group box of the Backdrop tab allow creating an
outer border for the current backdrop.
Style Select a frame style from the list box.
Color Select a color for the frame lines from the Color palette or choose cus-
tom to display the custom color palette.
Width Enter the number of points to be used as the width for the frame lines.
A point is 1/72 of an inch. For the Thick Inner and Thick Outer frames, the
width setting applies to the thick line.
Shadow
The settings in the Shadow section allow creation of a shadow for the current
backdrop.
Shadow Select this check box to place a shadow on the frame.
Shadow Offset Specify the number of points the shadow is offset from the
frame. The shadow appears to the right and below the chart item.
Charts
Chart Designer
143
6
To specify a picture backdrop:
The Picture tab of the Chart Designer allows specification of a graphic image
to use as a picture backdrop. It is also possible to preview the picture, to select
a method for fitting the picture into the background, and to specify whether
the graphic image is saved with the chart.
Note: Chart types that are rendered in 3D perspective do not support pictures. Back-
drops for charts, plots, titles, footnotes, and legends on 3D charts can support
pictures because these chart items are not rendered in 3D perspective.
1. Start the Chart Designer. See Starting the chart designer on page 138.
2. In the Chart Designer dialog box select the appropriate chart element(s).
Note: When multiple elements have been selected in the tree view, the common
editing controls appear in the pane on the right.
3. Select the Picture tab. This tab applies to the following chart elements: Axis
Title, Datapoint, Datapoint Label, Footnote, Axis Label, Legend, Plot, Title,
Chart, Series Label.
4. Select the commands and options. These include:
Clear button
Click this button to clear an existing picture from the backdrop. Some graph-
ics files can be very large. In order to minimize performance problems,
always clear one picture from the backdrop before specifying a new one. This
WinNonlin
Users Guide
144
6
prevents the system from having to deal with two large graphics files simulta-
neously.
Paste button
Click this button to paste a .WMF or .BMP file from the clipboard into the cur-
rent backdrop. A graphic can also be pasted into an existing backdrop by
selecting the backdrop on the screen and selecting the Paste command from
the floating menu. Select the graphic file and click OK.
Browse button
Click Browse to display a standard Open dialog box. Select the file to display
and click OK. The path and file then appear in the File text box and a preview
of the graphic appears in the Picture control.
File text box
To add a picture to the backdrop, type the full path to the graphic file in the
File text box or press the Browse button to display an Open dialog box. When
a valid path is specified, a preview of the graphic appears in the dialog box.
Embed picture
Select the Embed check box to save the picture file with the chart. Embedding
a picture with a chart will increase the size of the chart file. This is not recom-
mended unless the chart file size is of little consequence.
Picture size
Choose one of these options to determine how to fit the graphic into the back-
drop space.
Actual Size Displays the graphic at the original size it was created. If the orig-
inal size of the graphic is too large, the graphic is cropped. If the original size
of the graphic is too small, it is centered.
Best Fit Scales the graphic proportionally to fit entirely within the backdrop.
If the graphic does not exactly fill the backdrop in a dimension (vertically or
horizontally), it is centered in that dimension.
Stretch to Fit Scales the graphic to fit backdrop regardless of its original pro-
portions.
Tiled Duplicates the graphic at its original size repeatedly to fill the backdrop.
Charts
Chart Designer
145
6
Crop Fitted Centers the graphic and scales it proportionally to fill the back-
drop. Any part of the image that falls outside the backdrop is cropped.
Selecting a location for the plot
Note: The text aspects of a chart (such as axis titles, chart titles, legends, etc.) can be
moved by dragging them and dropping them on the chart. The entire plot can
be moved by clicking on the chart and dragging it to a new position in the
chart window. These operations do not require use of the Chart Designer.
To resize or reposition a plot:
1. Double-click on the plot but not on a specific plot element. Click on Plot in
the tree view.
or
Use the right mouse button to display the shortcut menu and select Chart
Designer. Click on Plot in the tree view.
or
Select Chart Designer from the Chart menu. Click on Plot in the tree view.
The five tabbed pages for Plot appear on the right side pane.
2. Select the Position tab.
3. Uncheck the Automatic Location check box. This allows entering a custom
location for the plot.
4. Enter values in the Top, Left, Height, and Width fields to describe the coordi-
nates of the upper left corner of the object and its height and width.
5. Click OK.
Note: The measurement unit specified in the Windows default setting is used. This
setting is accessed via Regional Settings and allows the choice of US or met-
ric units.
WinNonlin
Users Guide
146
6
Formatting the walls of a plot
The colors and patterns applied to the walls of two-dimensional and three-
dimensional plots, the colors used to draw lines in the walls, and the width of
the walls can be changed. The width of the walls is measured in points.
Formatting the base of the plot applies only to three-dimensional plots.
To format the wall of the plot:
1. Double-click on the plot but not on a specific plot element. The Chart
Designer appears.
or
Use the right mouse button to display the shortcut menu and select Chart
Designer. The Chart Designer appears.
or
Select Chart Designer from the Chart menu. The Chart Designer appears.
2. Click on Plot in the tree view.
3. Click on the Walls tab.
4. Specify any changes to the wall width, pen and fill. The options are:
Width
Enter the number of points for the wall width.
Pen
Style Select a line style for the lines that frame the walls from the Style list.
Charts
Chart Designer
147
6
Width Choose a predefined width or click Custom to create a custom width.
Color Choose a predefined color or select Custom to create a custom color.
The fill color is used to create a solid pattern.
Fill
Pattern Select a pattern or solid fill from the Pattern list.
Fill List Select a predefined color or click Custom to create a custom color.
This fill color is used to create a solid pattern. It is used as the background
color for any other type of pattern. By default the line color for an element
matches this fill color.
Pattern Color Select a color or click Custom to create a custom color. The
pattern color is drawn on top of the fill color.
5. Make any changes and click OK or click the Apply button to redraw the plot
to reflect the changes without closing the dialog box.
Formatting a series on the plot
There are a number of options that can be specified to format individual series
or data points in a plot. These include:
Hiding or excluding a series
Changing the appearance of the elements that make up the series
Adding or modifying markers used to identify series elements or individ-
ual data points
Adding statistics lines or guidelines to highlight series information
Changing the fill and line colors used to display series elements or indi-
vidual data points
Changing the color and pattern of the edge pen used to display series ele-
ments
WinNonlin
Users Guide
148
6
Formatting the series appearance
To format the appearance of a series:
1. Select Series from the tree view in the Chart Designer, or double click a graph
element in an unselected series or the legend key identifying the series.
2. Select the series to format.
3. When all the formatting options required for the series have been specified,
click OK or click the Apply button to redraw the plot to reflect the changes
made without closing the Chart Designer.
Selecting series formatting options
The series tree view allows formatting of all series, individual series, data
points in a series, or individual data points, depending what is selected under
Series. Selecting the Series (top) level sets the attributes that all the series in
the current chart have in common. Selecting an individual series (second) sets
the attributes for a specific series. Selecting a default datapoint makes settings
for all data points in a series. Any data point that does not have any custom
settings inherits the settings of the default datapoint. Selecting an individual
data point allows custom changes to a specific point within a series.
Charts
Chart Designer
149
6
To select Series Formatting Options:
1. Select the series to format in the tree view pane. The operations pane displays
four tabbed pages: Options, Lines, Guidelines, and Statistics.
2. Select the Options tab and set the following.
Hide Series Check this box to hide the current series. The space occupied by
the series is still shown on the plot, but the data is not displayed. Uncheck this
box to redisplay the hidden series.
Exclude Series Check this box to remove a series from a plot. The data is not
displayed and the space occupied by the series is removed from the plot.
Uncheck this box to return the series to the plot.
Plot on 2nd Y-Axis Check this box to plot the current series on the secondary
Y-axis instead of the primary axis. The secondary Y-axis is plotted on the right
of the chart while the primary axis is on the left. It is also possible to change
the scale, type, or format of the secondary axis. Uncheck this box to plot the
data on the primary axis.
Note: The Plot on 2nd Y-Axis option is not available with XY scatter charts.
Show Markers Check this box to display markers on the currently selected
series. Uncheck this box to remove markers from the selected series.
Automatic Markers Check this box to allow WinNonlin to automatically
assign a marker to all non-custom data points in a series. A non-custom
datapoint is any datapoint that has no custom attributes.
WinNonlin
Users Guide
150
6
Uncheck this box to select a choice of marker.
Bars Enter a value between 1 and 360 to indicate the number of sides for the
bars. When 1 is entered, WinNonlin determines how many sides are necessary
to create a round column, given the size of the bar.
Top Ratio Enter a number between 0 and 10,000 to indicate the percent of the
bottom diameter used to draw the top of the bar. Values less than 100 result in
a top smaller than the bottom. Values greater than 100 result in the top wider
than the bottom.
Smoothing
The options in this section of the dialog box control the smoothing of series
data. Smoothing uses one of several mathematical formulas to divide the data
into a number of facets. When the plot is drawn using these facets, the result is
a smoother curve to the series lines.
Function The following list describes all smoothing types located in the
Function drop down list.
None No smoothing is applied to the data.
QuadraticBSpline A quadratic B-spline formula determines the smoothing
applied to the data. This form of smoothing results in a less-smooth curve that
stays closer to the data points.
CubicBSpline A cubic B-spline formula determines the smoothing applied to
the data. This form of smoothing results in a smoother curve but varies further
from the data point than a Quadratic B spline curve.
Factor Specify the number of facets or points sampled between the data
points to create the smoothing effect. The higher the number, the more
smoothing occurs.
HiLo Close Select colors used to display the elements of a hi-lo chart. The
gain color reflects all the elements that represent a gain and the loss color
reflects all the elements that represent a loss.
Gain Color Click the control to display the color palette and select the color
used to indicate a gain in value. Select a predefined color or click custom to
display the custom color palette. Select Automatic to have all elements that
reflect a gain in value use the fill color defined for the series.
Loss Color Click the control to display the color palette and select the color
used to indicate a loss in value. Select a predefined color or click custom to
Charts
Chart Designer
151
6
display the custom color palette. Select Automatic to have all elements that
reflect a loss in value use the fill color defined for the series.
3. Click OK or Apply to redraw the chart to reflect the changes.
Formatting series lines
The Lines tab of the Chart Designer has the controls for formatting two-
dimensional and three-dimensional lines and the lines in XY, radar, polar, and
hi-lo charts. The settings on this tab control the style, width, color, join and
end caps used to display lines.
To format Series Lines:
1. Start the Chart Designer. See Starting the chart designer on page 138.
2. In the Chart Designer tree view select a row or column label for series data.
3. Select the Lines tab. The options are:
Show Series Line Check this check box to display lines on a 2D chart.
Uncheck this check box to hide the lines on the chart.
Style Select from this drop down list to choose a style for the current line or
select NULL to hide the line.
Width Select from this drop down list to display the preset line widths.
Choose a width, or select Custom to assign the width.
Note: If a line width of 1 is selected, the series line may not appear on screen but
does appear in print outs and paste operations.
Color Select one of the predefined colors or click Custom to create a custom
color.
Join Select a method of joining line segments in the series. Join styles are par-
ticularly important when using thick lines.
Mitered The outer edges of the two lines are extended until they meet.
Round A circular arc is drawn around the point where the two lines meet.
Beveled The notch between the ends of two joining lines is filled.
Caps Select a type to specify how the ends of lines are displayed.
WinNonlin
Users Guide
152
6
Butt The line is squared off at the endpoint.
Round A semicircle with a diameter of the line thickness is drawn at the end
of the line.
Squared The line continues beyond the endpoint for a distance equal to half
the line thickness and is squared off.
4. Click OK or Apply to redraw the chart to reflect the changes.
Formatting series guidelines
Guidelines are lines that are drawn from a data point to one or more axes to
better identify the data point position. The Guidelines tab for a series controls
the display and format of guidelines in two dimensional and three dimen-
sional line, area, step charts, bubble charts, 3D XYZ and scatter charts.
To format series guidelines:
1. Start the Chart Designer. See Starting the chart designer on page 138.
1. Click on a series in the tree view.
2. Select the Guidelines tab for one or more series. The options on this tab con-
trol the style, color, size, and line width of markers.
The settings include:
Show Guidelines Check this box to display markers on a series. Uncheck this
box to remove markers from a series. The other options are enabled only if the
Show Guidelines check box is checked.
Style Select a marker type to identify the data points in the current series.
Width Select a width for the lines that form the marker, or click Custom and
set a custom width.
Color Select a color from the drop down list of colors for the marker or click
Custom to create a custom color.
Caps Select a type to specify how the ends of guidelines are displayed.
Butt The line is squared off at the endpoint.
Round A semicircle with a diameter of the line thickness is drawn at the end
of the line.
Charts
Chart Designer
153
6
Squared The line continues beyond the endpoint for a distance equal to half
the line thickness and is squared off.
3. Click OK or Apply.
Formatting series statistics lines
Statistics lines are useful for analyzing data by showing information such as
minimum value, maximum value, mean value, standard deviation, and regres-
sion trend lines in plots. WinNonlin can only display statistics lines on two-
dimensional line and XY charts.
To format Series Statistics Lines:
1. Start the Chart Designer. See Starting the chart designer on page 138.
2. Select Series in the tree view pane.
3. Click on the Statistics tab. The options on the Statistics tab control the display
and appearance of statistics lines for a series.
The options that apply to an XY scatter plot are described below. For each
type of statistic, check the box to display the line or uncheck the box to
remove the line.
Show check boxes:
Minimum Shows the minimum Y value in the series.
Maximum Shows the maximum Y value in the series.
Mean Shows the mathematical mean of all Y values in the series.
Standard Deviation Shows the standard deviation of all Y values in the series.
Regression Shows a trend line indicated by the Y value in the series.
Line Styles For each type of statistic, select a line style that uniquely identi-
fies it.
Width Select a width for the statistics lines, or click custom and set a new
width.
Color Select the color for the statistics lines that represent the current series.
4. Click OK (or Apply to keep the Chart Designer open) to redraw the chart.
WinNonlin
Users Guide
154
6
Note: Statistics lines can be added for any series of an XY plot.
Formatting a series label
Series labels can be used instead of a legend as a way to identify each series
on a line, area, step, XY, or radar plot.
To format Series labels:
1. Start the Chart Designer. See Starting the chart designer on page 138.
2. Double click Series Label in the tree view pane. This opens the tree view fur-
ther.
3. Select the series (one or more) to label.
4. Click on the Style tab.
5. Select the options. These options include:
Text Location To display a series label on the chart select one of the Text
Location radio buttons that represents a predefined position. The valid posi-
tions for series labels are:
None No label is displayed.
Left The label is displayed above the first data point in the series.
Center The label is displayed above the middle data point in the series.
Right The label is displayed above the last data point in the series.
Label Line Style To display a line connecting a label to a series it represents,
select one of the following radio buttons. The styles include:
None No line connects the label and series.
Angled An angled line connects the label and series.
Straight A straight line connects the label and series.
Formatting a series data point
By default, each data point in a series has the same format. However, there
may be times that one or more data points in a series should be highlighted by
changing their format.
Charts
Chart Designer
155
6
Changing the color, pattern, and edge pen for individual data points is possi-
ble. When a default data point is selected, these options apply to all the non-
custom data points. When a specific data point is selected, the options apply
only to that data point and override any default data point settings.
To format an individual data point:
1. Start the Chart Designer. See Starting the chart designer on page 138.
2. Double click on Series in the tree view. This opens up the series in the tree
view pane.
3. Double click on Datapoint in the tree view pane. Tabbed pages appear for
Fill, Markers, and Picture.
The datapoint options can now be set. See below.
Selecting series data point options
Fill The controls in the Fill section of this tab control the color and pattern
used to display data points.
Markers This tab sets or modifies the marker options for the data point.
If a default data point is selected, the options apply to all the non-custom data
points. If a specific data point is selected, the options apply only to that data
point and override any default data point settings.
To control the fill color and pattern:
1. In the Fill Color list select a predefined color or click Custom to create a cus-
tom color.
This fill color is used to create a solid pattern. It is used as the background
color for any other type of pattern. By default the line color for an element
matches this fill color.
2. In the Pattern Color list select a color or click Custom to create a custom
color. The pattern color is drawn on top of the fill color.
3. Click OK or Apply to redraw the chart to reflect the changes.
WinNonlin
Users Guide
156
6
Setting the edge color and width
The edge pen outlines all the 3D objects and all the two-dimensional elements
except the lines in line, XY, hi-lo, radar, and polar charts.
To set the edge style, color and width:
1. On the Edge section of the Fill tab select a line style from the Style list or
select Null to hide the line.
2. From the Width list select a preset line width or select Custom to assign a
custom width.
3. From the Color list choose a predefined color or click Custom to create a
custom color.
4. Click OK or Apply to redraw the chart to reflect the changes.
Selecting data point markers
Styles and colors for each data point in the series in the plot can be set. If the
default settings for data points are set in this tab, custom settings for individ-
ual data points can also be set and the custom settings override the default
data point settings.
To set data point markers:
1. Start the Chart Designer. See Starting the chart designer on page 138.
2. Select a series data point in the tree view.
3. Click the Markers tab to modify the marker options for that data point.
4. Click the Show Markers check box.
Charts
Chart Designer
157
6
5. From the Style list select a marker type to identify the data points in the cur-
rent series.
6. From the Color list choose a predefined color or click Custom to create a
custom color.
7. From the Size list select a size for the marker.
8. From the Pen Width list select a preset line width or select Custom to assign
a custom width.
9. Click OK or Apply to redraw the chart to reflect the changes.
Formatting series data point labels and axis labels
Labels can be placed on a series of data points or on individual data points to
annotate the chart or draw attention to a certain chart element. Many of the
same functions can be used to format axis labels.
The Format Data Point Label dialog box controls the type and location of the
label on an individual data point, formats the font and layout of the label text,
and formats the label backdrop. The Axis Label dialog controls the location of
the label for the axis, along with its formatting.
Selecting an individual datapoint label (such as R1) for a specific series (such
as C1) allows custom changes to a specific datapoint label within a series.
Selecting a specific default datapoint label makes possible setting default set-
tings for all datapoint labels in a particular series. Any datapoint that does not
have any custom settings inherits the settings of the default datapoint label.
Selecting all default datapoint labels (Datapoint Labels) for each series will
allow making default settings for all datapoint labels in all series. Any
WinNonlin
Users Guide
158
6
datapoint that does not have any custom settings inherits the settings of the
default datapoint labels. Selecting multiple datapoint labels (such as R1) for
multiple series (such as C1and C2) will allow making custom changes to the
selected datapoint labels for each series. Selecting all datapoint labels (such as
R1-R5) for all series (such as C1-C4) will allow making custom changes to all
the selected datapoint labels. It is important to note that this is considered a
custom datapoint label and would, therefore, override any default datapoint
label attributes.
Note: The formatting options for Axis Labels are nearly identical to those for
Datapoint Labels. Follow these directions, substituting Axis Label for
Datapoint Label.
To format data point labels:
1. Start the Chart Designer. See Starting the chart designer on page 138.
2. Click on Series in the tree view pane.
3. Click on one or more series.
4. Click on Datapoint Labels. A series of tabbed pages appears in the right
pane.
The following list contains a description of each of the tabs in the Datapoint
Labels dialog box.
Charts
Chart Designer
159
6
Note: Selecting a default data point label means that the options apply to all the non-
custom data point labels. Selecting a specific data point label means that the
options apply to that data point label only and override any default data point
label settings.
Appearance Controls the display, position and label type of series labels as
well as the line style used to connect labels to the series.
Value Format Controls the mask used to display the data point label when the
text is displayed as a value.
Percent Format Controls the mask used to display the data point label when
the text is displayed as a percentage.
Backdrop Controls the fill, frame, and shadow used to create a backdrop for
the label.
Picture Specifies a graphic image to use as a picture backdrop.
Layout Controls the alignment, orientation, and word wrap of text for the
datapoint labels.
Font Controls the font, font size, font style, font color, and special effect used
to display the label text.
5. Make any necessary changes to the tabs in the dialog box and click OK or
click the Apply button to redraw the plot to reflect the changes without clos-
ing the dialog box. See below for a more detailed description of each page's
function and controls.
Selecting datapoint label appearance
The Appearance tab controls the display, position and label type of series
labels as well as the line style used to connect labels to the series.
Controlling label location
To display a series label on the current chart:
1. Select a Text Location radio button for a predefined position. Select a loca-
tion to display the label in relation to the data point. The positions for series
labels include:
None No label displayed.
WinNonlin
Users Guide
160
6
Above Point The label is displayed above the data point.
Below Point The label is displayed below the data point.
Center The label is displayed centered on the data point.
Base The label is displayed along the category or X-axis, directly beneath the
data point. This location is only valid for bar, line, area, and step charts.
Inside The label is displayed inside a pie or doughnut slice.
Outside The label is displayed outside a pie or doughnut slice.
Left The label is displayed to the left of the data point. This location is only
valid for XY, polar, radar, and bubble charts.
Right The label is displayed to the right of the data point. This location is only
valid for XY, polar, radar, and bubble charts.
2. Select a Label Line Style to display a line connecting a label to the series it
represents.
None No line connects the label and series.
Line A straight line connects the label and data point.
Angle Line An angled line connects the label and data point.
3. Select a Label Type. Check the Automatic check box to automatically display
the data point value. Other valid label types for series labels include:
Value The value of the data point appears in the label.
Percent The value of the data point is displayed in the label as a percentage
according to the axis percent basis.
Series Name The series name is used to label the data point.
Point Name The category name is used to label the data point.
4. Make any necessary changes to the tabs in the dialog box and click OK or
click the Apply button to redraw the plot to reflect the changes without clos-
ing the dialog box
Charts
Chart Designer
161
6
Formatting the data point label text
A data points value, value as a percent, data point name, or series name can
be used as a label, as described above. It is also possible to type in text for a
custom data point label.
A display mask can be used to control the appearance of the data point labels.
Use the settings on the Value Format tab to format the label when it is dis-
played as a value. Use the settings on the Percent Format tab to format the
label when it is displayed as a percent.
To set the labels with the Value Format tab:
1. Select the Value Format tab.
2. From the Category list select a category to display a preset list of format
strings appropriate for the type of label in the Format Codes list.
3. Select one of the predefined data formats from the Format Codes list. A cus-
tom number format can also be created by entering valid format symbols in
the Custom Format text box. These symbols are fully documented in the
online help system.
4. Click Apply or OK to redraw the chart to reflect the changes.
To set the labels with the Percent Format tab:
1. Select the Percent Format tab.
2. From the Category list select a category to display a preset list of format
strings appropriate for the type of label in the Format Codes list.
WinNonlin
Users Guide
162
6
3. Select one of the predefined strings from the Format Codes list. It is also pos-
sible to create a custom number format by entering valid format symbols in
the Custom Format text box. These symbols are fully documented in the
online help system.
4. Click Apply or OK to redraw the chart to reflect the changes.
Formatting the backdrop of the data point label
A backdrop can improve the appearance of a data point label. The backdrop
can include a frame or box around the data point label, a shadow behind the
label, and a pattern, gradient, or graphic picture behind the label. See Speci-
fying chart backdrops on page 141.
Formatting the layout of datapoint labels
To specify the layout for the datapoint label:
The Layout tab controls the alignment, orientation and word wrap of the text
for the labels.
1. Double click the left mouse button on the data point label to format.
or
Select Series then select Data Point Label in the tree view pane.
2. Select the Layout tab.
3. In the Alignment section click the appropriate button to control the horizontal
alignment of text.
Charts
Chart Designer
163
6
a. Horizontal Alignment There are three options for the horizontal align-
ment of the label text.
Left. Each label is aligned at the left edge of the division.
Right. Each label is aligned at the right edge of the division.
Center. Each label is centered horizontally within the division.
4. In the Alignment section click the appropriate button to control the vertical
alignment of text.
a. Vertical Alignment. There are three options for the vertical alignment of
the label text.
Top. Each label is aligned at the top of the division.
Bottom. Each label is aligned at the bottom of the division.
Center. Each label is centered vertically within the division.
5. In the Orientation section click the appropriate button to control the orienta-
tion of the text.
6. Check the Word Wrap check box to wrap text that is too long to fit on one line
of the bounding box. Line breaks can be inserted manually by pressing CTRL
+ ENTER anywhere in the text.
7. Click OK or Apply to redraw the chart to reflect the changes.
Formatting the font of the data point label
The font, font style, font size, font color and special effects used to display a
series data point label can be specified.
To format a series data point label:
1. Double click the left mouse button on the data point label to format.
or
Select Series then select Data Point Label in the tree view pane.
2. Select the Font tab.
3. Select the font options for the data point label. The Font options include:
Font. Select a font from the list of fonts installed.
Font Style. Select a style from the list of supported styles.
WinNonlin
Users Guide
164
6
Size. Select a size from the list of valid sizes for the font selected. A valid size
can also be entered in the Size field.
Color. Select the color drop down list to display the table of colors. Select one
of these colors, or click Custom to create a custom color.
Effects. Check either or both the Strikeout and/or Underline check boxes to
apply those effects to the text.
Sample. As selections are made from the other controls in this dialog box, the
sample is updated to reflect the changes.
4. Click OK or click the Apply button to redraw the plot to include the new data
point label font without closing the dialog box.
Formatting an axis
There are a number of axis components that can be formatted on a two-dimen-
sional or three-dimensional chart. In addition to setting the backdrop or pic-
ture backdrop, layout, text, and font, it is possible to:
Change the axis scaling, settings and type.
Specify formatting for axis dates.
Change the color, width, and style of pens.
There are three types of axes that can appear on a chart: a value axis, a cate-
gory axis, and a date axis. Category axes have text labels identifying the cate-
gory or series in the chart. Value axes display numbers as values or
percentages. Date axes display a range of dates. It is important to know the
type of axis in each chart type because any formatting applied to an axis is
maintained when switching to a new chart type.
Formatting the appearance of an axis
To format the appearance of an axis:
1. Select the axis to format in the tree view pane. The Chart Designer provides
controls for the X-axis, Y-axis, second Y-axis, and Z-axis. Of course, different
plot types use different combinations of axes. Different kinds of plots provide
different formatting options for the axes.
Charts
Chart Designer
165
6
2. Select the desired axis options and click OK or click the Apply button to
redraw the axis with the new format without closing the dialog box.
Changing category, value, and date scales
The Category Scale tab, Value Scale tab, and Date Scale tab for any axis in the
Chart Designer provide common settings for formatting axes. The controls
include:
Show. Allows showing or hiding the axis scale, value scale or date scale.
When the Category Scale tab is used this setting also allows showing or hid-
ing lines, ticks, and titles on the axis.
Automatic (Scale). WinNonlin will scale the axis based on the data being
charted.
Ticks (Style). Allows the specification of the position of the tick on the axis.
Ticks (Length). Allows entering a length in points for the major tick marks.
Minor tick marks are drawn at half the length of the major tick marks.
Automatic (Intersection). Sets the axes to intersect at their usual position.
Cross At. Allows specification of the position where the current axis is to
cross its intersecting axis.
Labels Inside Plot. Allows moving the axis labels with the axis to the new
intersection point or leaving the labels in their original position. If axis labels,
labels are moved, they might display on top of the chart plot. Only the axis
line and tick marks are drawn at the new intersection point.
To show or hide the axis scale, value scale or date scale:
1. Select the appropriate axis to format the scale settings.
2. Select the Category Scale tab, Value Scale tab, or Date Scale tab.
WinNonlin
Users Guide
166
6
3. In the Scale section of the tab check the Show check box.
When the Category Scale tab is being used this setting also applies to lines,
ticks, and titles.
4. Click OK or Apply to redraw the chart to reflect the changes.
To position the tick on the axis:
1. In the Ticks section of the scale tab select the appropriate radio button for a
tick position. The choices are:
None. No tick marks are displayed on the axis.
Center. Tick marks are centered across the axis.
Inside. Tick marks are displayed inside the axis.
Outside. Tick marks are displayed outside the axis.
2. Click OK or Apply to redraw the chart to reflect the changes.
To specify a custom intersection setting:
1. In the Intersection section of the scale tab uncheck the Automatic check box.
2. In the Cross At text box enter the position where the current axis is to cross
its intersecting axis. If the intersecting axis is a value axis, enter the value
where to place the current axis. If the intersecting axis is a date or category
axis, enter the division number at which to place the current axis.
3. If desired, check the Labels Inside Plot check box to move the axis labels
with the axis to the new intersection point.
Charts
Chart Designer
167
6
4. Click OK or Apply to redraw the chart to reflect the changes.
Specifying category axis settings
Some settings described in this section are specific to the Category Scale tab.
This tab applies only for X axes and Z axes with discrete values.
1. Check the Show check box and uncheck the Automatic check box in the
Scale section of the tabbed page in order to be able to enter the number of
label and tick divisions in the Divisions text boxes.
Per Label. This setting allows setting divisions for labels. A value of 1 labels
every division. A value greater than 1 labels the first division and skips the
labels for the extra divisions.
Per Tick. This setting allows setting divisions for ticks. A value of 1 places a
tick mark at every division. A value greater than 1 places a tick mark at the
first division and skips the tick marks for the extra divisions.
Skipping labels and tick marks can help reduce the clutter of labels that can
occur when there are a large number of divisions along the category axis.
2. Click OK or Apply to redraw the chart to reflect the changes.
Specifying value axis settings
Some settings described in this section are specific to the Value Scale tab.
This tab applies to X-axes, Y-axes, 2nd Y-axes, and Z-axes.
The minimum and maximum values represent the lowest or beginning value
and the highest or ending value that is displayed on each axis scale. The major
divisions on the axis and the number of minor divisions between each major
division of the axis can be specified.
1. Double click on the axis to set.
or
Open the Chart Designer and select the axis to set.
2. Click on the Value Scale tab if it does not already appear.
3. Uncheck the Automatic check box.
4. Check the Show check box, if necessary.
5. Enter the lowest or beginning value for the scale in the Minimum text box.
WinNonlin
Users Guide
168
6
6. Enter the highest or ending value for the scale in the Maximum text box.
7. Enter the major divisions on the axis in the Major Divisions text box.
8. Enter the minor divisions between each major division of the axis in the
Minor Divisions text box.
9. Click OK or Apply to redraw the chart to reflect the changes.
Specifying date axis settings
Some settings described in this section are specific to the Date Scale tab. This
tab applies to X-axes and Y-axes.
The Minimum and Maximum values represent the lowest or beginning date
and the highest or ending date that is displayed on the scale. It is also possible
to specify how many intervals pass before a tick mark is placed on the axis.
To set minimum and maximum values for the scale:
1. Double click on the axis to set.
or
Open the Chart Designer and select the axis to set.
2. Click on the Date Scale tab if it does not already appear.
3. Uncheck the Automatic check box in the Scale section of the Date Scale tab.
4. Check the Show check box, if necessary.
5. Enter the lowest or beginning value for the date in the Minimum text box.
6. Enter the highest or ending value for the date in the Maximum text box.
7. Click OK or Apply to redraw the chart to reflect the changes.
To specify when tick marks are displayed:
1. Uncheck the Automatic check box in the Scale section of the Date Scale tab.
2. Check the Show check box, if necessary.
3. In the Major Interval and Minor Interval text boxes enter a number to spec-
ify how many intervals pass before a tick mark is placed on the axis.
Charts
Chart Designer
169
6
4. Select an interval type from the table to specify when tick marks are dis-
played. The major ticks and grid lines appear at major intervals, and the minor
ticks and grid lines appear at minor intervals. Axis labels are drawn at major
intervals. The options for tick marks are:
None No Interval
Daily A tick mark occurs each day.
Weekly A tick mark occurs Monday of each week.
Semi-monthly A tick mark occurs on the 1st and 15th day of each month.
Monthly A tick mark occurs on the 1st of each month.
Yearly A tick mark occurs on January 1 of each year.
For example, to create a quarterly scale, set the interval to 3 months.
5. Click OK or Apply to redraw the chart to reflect the changes.
Changing pen color, width and style
The Pens tab applies to X-axes, Y-axes, 2nd Y-axes, and Z-axes. It changes
the line width and color of the axis line as well as the style, width, and color of
minor and major grid lines.
To change the style and color of the axis pen:
1. Double click on the axis whose settings are to be changed.
or
Open the Chart Designer and select the axis whose settings are to be set.
2. Select the Pens tab.
3. In the Axis Pen section of the tab select a predefined width from the Width list
or select Custom to define a custom width.
4. In the Color box of the Axis Pen section select a predefined color or click
Custom to create a custom color.
5. Click OK or Apply to redraw the chart to reflect the changes.
WinNonlin
Users Guide
170
6
To change the style, width and color of the minor or major grid lines:
1. In the tree view pane of the Chart Designer select the axis whose settings are
to be changed.
2. Select the Pens tab for that axis.
3. In the Minor Grid Pen or Major Grid Pen section of the tab select a predefined
style from the Style list or select Custom to define a custom style for the grid
lines.
4. Select a predefined width from the Width list or select Custom to define a
custom width.
5. From the Color list choose a predefined color or click Custom to create a
custom color.
6. Click OK or Apply to redraw the chart to reflect the changes.
Changing scale types
The Scale Type tab applies to X-axes, Y-axes, 2nd Y-axes, and Z-axes. It pro-
vides settings for different kinds of scales. The controls for these scale types
include:
Scale Type Select a linear, logarithmic, or percentage scale for the value axis.
Log Base This setting specifies the base for a logarithmic scale axis. The
default base is 10.
Percent Basis This setting specifies a method for calculating percentages.
To change axis scaling:
1. In the tree view pane of the Chart Designer select the axis to format.
2. Select the Scale Type tab.
3. Select the radio button for the appropriate axis scale. The choices available
are:
Linear. Data points are plotted in a linear scale with values ranging from the
minimum to the maximum chart value. This is also the default scale type.
Logarithmic. Data points are plotted in a logarithmic scale with values based
on a specific log scale. Logarithmic axes are not appropriate for zero or nega-
tive data.
Charts
Chart Designer
171
6
Percent. Data points are plotted in a linear scale as percentages of the chart
values selected under Percent Basis. Changing the percent basis of a chart is
useful for determining the overall trends in data rather than specific values.
4. If Logarithmic has been selected, enter a number in the Log Base text box
for the logarithm base.
5. If Percent has been selected, select a percentage type from the Percent Basis
list.
The options in that list are:
Chart Maximum. The largest value in the chart is considered 100 percent,
and all the other values in the chart are displayed as percentages of that value.
Category Maximum. The largest value in each category is considered 100
percent, and all the other values in that category are displayed as percentages
of that value.
Series Maximum. The largest value in each series is considered 100 percent
and all the other values in that series are displayed as percentages of that
value.
Chart Total. All the values in the chart are added together and that value is
considered 100 percent. All the values in the chart are displayed as percent-
ages of that value.
Category Total. All the values in each category are added together to give a
total value for each category. All the values are displayed as a percentage of
their category total.
Series Total. All the values in each series are added together to give a total
value for each series. All the values are displayed as a percentage of their
series total.
6. Click OK or Apply to redraw the chart to reflect the changes.
Formatting axis titles, footnotes, legends, and chart titles
The title for each axis can be added or changed. Adding axis titles can provide
information about the axis in order to help the viewer interpret the plot. Chart
legends are entered automatically from the data set, although the legend can
be formatted or hidden. Legends cannot be edited. Footnotes and chart titles
can be added or edited as well as being formatted.
WinNonlin
Users Guide
172
6
Most of the formatting controls for these chart features are in common. Those
that are distinctive are noted.
To format an axis title:
1. Select the axis to be formatted in the Chart Designer tree view.
2. Select Axis Title in the tree view pane.
or
3. Double click on the axis title to be formatted. The following tabs appear.
Backdrop. Controls the fill, frame, and shadow used to create a backdrop for
the axis title.
Picture. Specifies a graphic image to use as the picture backdrop, previews
the picture, selects a method for fitting the picture into the background and
specifies whether the graphic is saved with the chart.
Layout. Controls the alignment, orientation and word wrap of the text for axis
titles.
Text. Controls the text used for the axis title as well as the orientation and
alignment of the text.
Font. Controls the font, font size, font color, font style, and special effects
used to display the axis title.
4. Select the Text tab.
5. Type the axis title text in the text field.
6. Specify all other Axis Title options. Click OK or click the Apply button to
redraw the graph with the new axis title without closing the dialog box.
Formatting the axis title location
1. Select the axis to be formatted in the Chart Designer tree view.
2. Select Axis Title in the tree view pane.
or
Double click on the axis title to be formatted.
3. Select the Layout tab.
Charts
Chart Designer
173
6
4. In the Alignment section click the appropriate button to control the horizontal
alignment of text.
Horizontal Alignment The following terms describe the horizontal align-
ment options for title text.
Left. Each label is aligned at the left edge of the division.
Right. Each label is aligned at the right edge of the division.
Center. Each label is centered horizontally within the division.
5. In the Alignment section click the appropriate button to control the vertical
alignment of text.
Vertical Alignment. The following terms describe the vertical alignment
options for title text.
Top. Each label is aligned at the top of the division.
Bottom. Each label is aligned at the bottom of the division.
Center. Each label is centered vertically within the division.
6. In the Orientation section click the appropriate button to control the orienta-
tion of the text.
7. Check the Word Wrap check box to wrap text that is too long to fit on one
line of the bounding box. Line breaks can be inserted manually by pressing
CTRL + ENTER anywhere in the text.
8. Click OK or Apply to redraw the chart to reflect the changes.
Specifying a picture for an axis title
It is possible to specify a picture backdrop for an axis title. It will appear
behind the title, in a rectangle several points wider and taller than the title text.
1. Select the axis to be formatted in the Chart Designer tree view.
2. Select Axis Title in the tree view pane.
or
Double click on the axis title to be formatted.
3. Select the Picture tab.
4. Select the commands and options. These can include:
WinNonlin
Users Guide
174
6
Clear button
Click this button to clear an existing picture from the backdrop. Some graph-
ics files can be very large. Always clear one picture from the backdrop before
specifying a new one. This prevents the system from having to deal with two
large graphics files simultaneously.
Paste button
Click this button to paste a .WMF or .BMP file from the clipboard into the cur-
rent backdrop. It is also possible to paste a graphic into an existing backdrop
by selecting the backdrop on the screen and selecting the Paste command
from the floating menu. Select the graphic file to paste into the backdrop and
click OK.
Browse button
Click Browse to display a standard Open dialog box. Select the file to display
and click OK. The path and file then appear in the File text box and a preview
of the graphic appears in the Picture control.
File text box
To add a picture to the backdrop, type the full path to the graphic file in the
File text box or press the Browse button to display an Open dialog box. When
a valid path is specified, a preview of the graphic appears in the dialog box.
Embed picture
Check the Embed check box to save the picture file with the chart. Embed-
ding a picture with a chart will increase the size of the chart file. This is not
recommended unless the chart size is of little consequence.
Picture size
Choose one of these options to determine how to fit the graphic into the back-
drop space:
Actual Size. Displays the graphic at the original size it was created. If the
original size of the graphic is too large, the graphic is cropped. If the original
size of the graphic is too small, it is centered.
Best Fit. Scales the graphic proportionally to fit entirely within the backdrop.
Charts
Chart Designer
175
6
Stretch to Fit. Scales the graphic to fit backdrop regardless of its original pro-
portions.
Tiled. Duplicates the graphic repeatedly to fill the backdrop.
Crop Fitted. Centers the graphic and scales it proportionally to fill the back-
drop. Any part of the image that falls outside the backdrop is cropped.
5. Click OK or click the Apply button to redraw the plot to include the new
backdrop without closing the dialog box.
Formatting an axis title backdrop
The axis title appearance can be improved by placing a backdrop on the axis
title itself. A backdrop can include a frame or box around the axis title, a
shadow behind the title, and a pattern, gradient, or graphic picture behind the
axis title.
To edit an axis title backdrop:
1. Double click the mouse button on the axis title whose backdrop is to be
edited.
or
Select the appropriate axis from the tree view pane of the Chart Designer.
2. Select Axis Title in the tree view pane.
3. Select the Backdrop tab.
4. After specifying the backdrop options, click OK or click the Apply button to
redraw the plot to include the new axis title backdrop without closing the dia-
log box. The options include:
Fill
The fill settings in the Backdrop tab allow setting a backdrop color and/or
effect. The gradient type or brush type and the fill/from color and the pattern/
to color can be selected. A number of colors and patterns can be chosen. The
options include:
No Fill. The chart control or chart elements have no fill, so any formatting
applied to the surface behind them shows through. A picture can still be
applied to an element with no fill.
Brush Fill. Select a pattern or solid color from the color palettes.
WinNonlin
Users Guide
176
6
Brush. Click the list box to display the pattern picker. Click one of the pat-
terns to fill the object.
Fill/From Color. Click the control to display the color palette. Choose a pre-
defined color or choose custom to display the custom color palette.
The fill color is used to create a solid pattern that serves as the background
color behind a pattern.
For a gradient fill, use the Fill/From Color list box to specify the color used
as the top color in a horizontal gradient, the left color in a vertical gradient,
and the center color in a rectangle or oval gradient.
Pattern/To Color. Click the control to display the color picker. Choose a pre-
defined color or choose custom to display the custom color palette.
The pattern color is used to draw the pattern color on top of the fill color.
For a gradient fill, use the Pattern/To Color list box to specify the color used
as the bottom color in a horizontal gradient, the right color in a vertical gradi-
ent, and the outer color in a rectangle or oval gradient.
Frame
The settings in the Frame section of the Backdrop tab allow creating a frame
for the current backdrop.
Style. Select a frame style from the list box.
Color. Select a color for the frame lines from the Color palette or choose cus-
tom to display the custom color palette.
Width. Enter the number of points to be used as the width for the frame lines.
A point is 1/72 of an inch. For the Thick Inner and Thick Outer frames, the
width sets the thick line.
Shadow
The settings in the Shadow section allow creating a shadow for the current
backdrop.
Shadow. Select this check box to place a shadow on the frame.
Shadow Offset. Specify the number of points the shadow is offset from the
frame.
Charts
Chart Designer
177
6
Formatting axis title text
It is possible to specify the font, font style, font size, font color and special
effects used to display the axis title.
To format the axis title text:
1. Double click the left mouse button on the text to format.
or
Select the appropriate axis in the tree view pane of the Chart Designer.
2. Select Axis Title in the tree view pane.
3. Select the Font tab.
4. After specifying the font options, click OK or click the Apply button to
redraw the plot to include the new axis title font without closing the dialog
box.
The Font options include:
Font. Select a font from the list of fonts installed.
Font Style. Select a style from the list of supported styles for the font
selected.
Size. Select a size from the list of valid sizes for the font selected. A valid size
can also be typed in the Size field.
Color. Select the color drop down list to display the table of colors. Select one
of these colors, or click Custom to create a custom color.
Effects. Check either or both the Strikeout and Underline check boxes to
apply those effects to the text.
Sample. When selections are made from the controls in this dialog box the
sample is updated to reflect the changes.
Specifying the location of chart legends, chart titles, and footnotes
To specify the location of chart legends, footnotes, and chart titles, open the
Chart Designer and select the appropriate control. Recall that one, several, or
all of the controls can be selected.
WinNonlin
Users Guide
178
6
To specify the location:
1. On the Location tab, check the Visible check box to display the legend. By
default, series labels are used to identify each series in the legend.
2. Select a location for the legend. The tab provides eight options for the text to
be located.
3. Click OK or click the Apply button to redraw the plot to include the legend
without closing the dialog box.
Note: The entire plot can be moved by clicking on the plot then dragging it to a new
location within the chart window. Likewise, text aspects of a chart (such as
axis titles, chart titles, legends, etc.) can be moved by dragging them and
dropping them on the chart. These operations do not require use of the Chart
Designer.
To resize or reposition chart legends:
1. Double click the left mouse button on the graph legend.
or
Select Legend from the tree view pane of Chart Designer.
2. Select the Location tab.
3. Select the Custom radio button.
4. Enter values in the Top, Left, Height, and Width fields to describe the coordi-
nates of the upper left corner of the object and its height and width.
5. Click OK or the Apply button.
WinNonlin uses the measurement unit specified in the Windows default set-
tings.
Frequently used graph formatting options
This section highlights some of the formatting options that are used most fre-
quently.
This section covers:
Changing Line Styles and Markers (Symbols)
Charts
Frequently used graph formatting options
179
6
Changing the Axis Scaling
Creating a Semi-log Plot
Removing Grid lines
Removing Walls
See also the Chart examples given in the Examples Guide.
Changing line style and markers
When a graph is created it uses the default colors, line styles, and markers (or
symbols). Any or all of these can be changed. Many line styles are available,
including different widths of solid lines and different patterns of dashes or
dots. Many markers are available, including solid and filled markers.
To format Series Lines:
1. To select a particular line for formatting, do one of the following:
Double-click on that line. The Chart Designer opens to the appropriate tab.
or
With the chart in the active window select Chart Designer from the Chart
menu. The Chart Designer opens. Then click on Series in the tree view. The
series in the plot appear in a list. Select the series to work on.
2. Click the Lines tab.
3. To hide the line, uncheck the Show Series Line check box.
4. To change the style of the line, select the desired style from the pull down list
for Style.
5. To change the width of the line, select the desired width from the pull down
list for Width.
6. To change the color of the line, select the desired color from the pull down
menu for Color.
7. To change the way the way the line segments join at the plot points select the
appropriate choice from the menu for Join.
8. To specify how the ends of lines are displayed select from the menu for Caps.
9. Click OK.
WinNonlin
Users Guide
180
6
For more information on Series lines See Formatting a series on the plot on
page 147.
Changing the axis scaling
When graphs are created an automatic scaling is done. Note that this auto-
matic scaling may change when the size of the child window in which the
graph is displayed is changed. The automatic scaling can be turned off or set
to a specified scale. Note that when the scale is specified, it does not change
with changing size of the window.
To change the scale of an axis:
1. To select an axis for formatting, do one of the following:
Double-click on that axis.
or
Select Chart Designer from the Chart menu. The Chart Designer opens.
Then select the appropriate axis in the tree view pane. The tree view opens
further and three tabs display in the right pane.
2. To create a logarithmic plot, select Logarithmic in the Scale Type box on the
Scale Type tab.
3. To change the scale sizes select the Value Scale tab.
4. Make sure that the Automatic check box is unchecked.
5. Enter the minimum and maximum to be displayed.
6. Enter the number of Major Divisions.
Note that this is the number of divisions, not the size of the divisions. If the
axis scale is to be 0, 5, 10. then enter 0 for the Minimum, 10 for the Maxi-
mum, and 2 for Major Divisions.
7. Click OK.
For more information on axis scaling and changing scale types, See Chang-
ing the axis scaling on page 180.
Creating a semi-log plot
A semi-log plot can be created quickly by using the Axis Options dialog.
Charts
Frequently used graph formatting options
181
6
To create a semi-log plot setting the Axis Options:
1. Select Axis Options from the Chart menu. The Axis Options dialog appears.
2. Select the Logarithmic check box for the Y-axis.
3. Click OK.
The Chart Designer can also be used to create a log or semi-log plot. See
Changing category, value, and date scales on page 165.
Removing grid lines
To remove the grid lines from a chart:
1. Start the Chart Designer. See Starting the chart designer on page 138.
2. Select the X-axis in the tree view.
3. On the tab labeled Pens change the Major Grid Pen Style to NULL.
4. Click Apply.
5. Repeat for the Y-axis.
6. Click OK.
Removing walls
To remove chart walls:
1. Start the Chart Designer. See Starting the chart designer on page 138.
2. Select Plot from the tree view menu.
3. Select the Walls tab.
4. In the Pen group box, change the Style to NULL.
5. Click OK.
WinNonlin
Users Guide
182
6
Chart templates
WinNonlin provides the capability of creating graph templates containing any
customized graph elements.
To save a graph template:
1. Format a plot with all the options to be saved in the template.
2. With the Chart window selected, choose Chart>Save Template from the
menus.
3. Select a file location and file name. Enter or select the graph template exten-
sion, .GTP.
4. Click Save.
To load a graph template:
1. Format a chart with the desired features.
2. With the graph selected, choose Load Template from the Chart menu.
3. The Load Template dialog box appears. Select the location and file that con-
tains the graph template (.GTP).
4. Click Open.
The graph is now updated with the formatting established in the template.
Note: If the template contains formatting for only one series of data and is applied to
a graph that contains more than one series, the template applies the formatting
to the first series only.
Preview and page setup for charts
WinNonlin provides a number of convenient features for printing charts. First,
the Page Setup command on the File menu can be used to specify how the
chart(s) in the active window are to be arranged on a printed page. This dialog
controls the layout of the page (portrait or landscape) and whether to print one
chart per page or multiple charts per page.
Charts
Preview and page setup for charts
183
6
To specify a chart's page layout:
1. With the chart in the active window, select Page Setup from the File menu.
The Page Setup dialog for charts appears.
2. Specify the page orientation and margins for the page.
3. Specify whether to display one chart per page (default) or more. If the Multi-
ple charts per page check box is selected, choose from the list of options for
the layout. When multiple charts per page is selected the Scaling and Layout
areas are disabled.
4. If one chart per page is selected, set the Scaling option. Select Actual Size to
print the chart at the original size that it was created. Select Best Fit to scale
the chart proportionally to fit the entire page.
5. If one chart per page is selected, set the Layout option. Select Screen Layout
to print the chart exactly as it appears on the screen. Select Layout for
Printer to layout the chart to best fit the page. Elements such as axis labels
and data points are repositioned as they would be when the chart is resized on
the screen.
6. Click OK. The chart layout is specified for the printer/screen.
Note: This setting is specific to the chart(s) in the active window. These settings are
preserved for that chart during the WinNonlin session. They are not retained/
saved to the file once WinNonlin is closed. It is also not a default setting for
any or all charts thereafter.
Chart(s) can be previewed using the Print Preview function. This function
may be particularly useful for evaluating page and chart layout.
WinNonlin
Users Guide
184
6
To preview a chart:
1. Make sure that the chart(s) are the active window in WinNonlin.
2. Select Print Preview from the File menu.
3. A Print Preview window appears with the chart in the layout specified from
the Page Setup dialog.
4. Click Next to scroll through multiple pages.
5. Click Close to close the window and return to WinNonlin.
Information on printing charts can be found in the File Management chapter
of this manual. See Printing on page 25.
Copy and paste
WinNonlin provides the capability to copy a graph paste it into another Win-
dows application in Windows Metafile (.WMF) format.
Note: The Export to Word tool bar button exports the active object directly to
Microsoft Word, and can be used to export an image of the current chart.
To copy and paste a chart:
1. Select the chart window containing the chart to copy.
2. Select Copy from the Edit menu. A copy of the chart image is placed on the
clipboard in Windows Metafile (.WMF) format.
3. Switch to the other application and (depending upon which application is
being used), use the Paste or Paste Special function to paste the image.
Note: In order to support cut and paste, the Windows Character Map is limited to the
255 characters noted in the Windows 98 ANSI version. Windows 2000 has
multiple Character Mapping options (use Programs>Accessories>System
Tools>Character Map in the Windows Start menu to view them). Windows:
Western must be selected as the default option in order to cut and paste the
characters supported in WinNonlin. Look to the lower, right corner of the
Character Map to see if Keystroke: Alt+XXXX is within the 255 range for
any special characters (characters not included on the computer keyboard).
Charts
Save options
185
6
Save options
Charts can be saved as Pharsight Chart Objects (.PCO), Windows Bitmaps
(.BMP), Joint Photographic Experts Group files (.JPG), or Windows Metafiles
(.WMF).
A Pharsight Chart Object (*.PCO) will save a snapshot of the current image
that appears on-screen and all attributes that are associated with the graph,
including the data that is being graphed and all formatting information. This
formatting information is the same as that stored in a graph template.
To save a chart:
1. With the chart in the active window, choose File>Save As from the menus
(Alt+F, A or Ctrl+A).
2. Choose the drive and directory in which to store the chart.
3. Select the file type in the Save as Type pull down menu. The following file
type options are available:
Windows Metafile (.WMF)
Windows Bitmap (.BMP)
Joint Photographic Experts Group format (.JPG)
Pharsight Chart Object (.PCO)
4. Specify the file name in the File Name box.
5. Click Save.
Note: When a chart is saved as a Windows Metafile (.WMF) WinNonlin prompts
whether to Include placeable header information. Some applications which
read Windows Metafiles will expect this information, while others will not.
The answer depends upon the application in which the Windows Metafile will
be used. If it is a Microsoft application, such as Word or Excel, answer Yes.
WinNonlin
Users Guide
186
6
187
Chapter 7
Tables
Creating formatted tables in WinNonlin
The Table Wizard is an easy-to-use tool to create report-ready tables of raw
and summarized data. WinNonlin templates can combine data listings and
summary statistics in a variety of table formats. This chapter discusses the
templates and operating instructions for the Table Wizard. For examples of its
usage, refer to the Examples Guide.
Table Wizard
Following are the basic steps in using the Table Wizard:
1. Open one or two data sets to provide table data.
2. Launch the Table Wizard, by doing one of the following:
Select Tools>Table Wizard from the menus.
Click the Table Wizard button on the tool bar.
3. If desired, set options for treatment of group variables. See Tables on
page 36 for the table options.
4. Select the table template, as detailed under Table templates on page 188.
5. Assign table variables: drag the variables to be used to the appropriate vari-
able boxes. See Table template variables on page 192.
6. If using template 9 to join data from two data sets, select the join variables as
described under Joining data sets on page 195.
7. Click Next.
8. If the table template includes summary statistics:
WinNonlin
Users Guide
188
7
a. Check the specific statistics to compute (see Summary statistics on
page 197) and click Next.
b. Select the number of decimal places/significant digits to be used in the
table output for each column. See Significant digits on page 198.
c. Specify the text alignment to be used for each column in the table.
d. Click Next.
9. Format the table. See Table formatting on page 200.
a. Enter a title and/or footer.
b. Specify the font size and style to be used with column titles, page title/
footer and table body.
c. Set page numbering.
d. Select the page orientation for the table: Portrait or Landscape.
e. Specify how units associated with output parameters are to be displayed.
f. Click Next.
10. Click Finish to create a preview of the table.
11. Click the Prev button to alter any table settings. Click Create to create the
table in a new WinNonlin workbook window.
Missing table values
If a value needed for any statistical calculations is missing, the row designated
for the result will be left blank. For example, when N = 1 the SD cannot be
calculated. As a result, the row where SD should be displayed is blank in the
resulting table.
If individual values in the source data set are marked as excluded, then these
will appear as missing in the final table. When an entire row is excluded then
the row will not appear in the table.
The representation of missing values is set in the Tools Options dialog, on the
Workbook tab. See Workbooks on page 34.
Table templates
Nine table templates are provided in the Table Wizard. Templates 1 through 8
use a single data set, while Template 9 combines data from two.
Tables
Table templates
189
7
Templates 1-3
Templates 1 through 3 use a single data set and simply list the columns speci-
fied. These templates use only three of the template variables: Group Vari-
ables, ID Variables, and Regular Variables.
Template 1
This template displays summary statistics for each column included under
Variables. These summary statistics are computed from the data in the input
data set. ID Variables are not included, since this template summarizes over
any potential ID Variables. These summary statistics are done separately for
each value of the Group Variable(s), if any.
Template 2
This template lists raw data for each column selected under Variables. No
summary statistics are generated or included. Data are sorted alphanumeri-
cally by the values of the Group Variables, then by ID Variables in the order
listed under Group Variables and ID Variables, respectively.
Template 3
This template lists the raw Variables data for each value of the ID Variables
and includes summary statistics. The summary statistics are done separately
for any values of the Group Variable(s).
Templates 4-8
Templates 4-8 re-arrange data in Regular Variables according to the values of
the Cross Variable(s). That is, the template takes data that appear in a long
column, and breaks this data into separate columns, with or without comput-
ing summary statistics. A typical use for this would be to take a data set with
the variables Trt, Subject, Time, and Conc, and create a table with a column
for Trt, another for Subject, and a separate column of concentration values at
each time.
These tables employ Group Variables, ID Variables, Cross Variables, and
Regular Variables.
Template 4
The data in the Regular Variable(s) are broken into separate columns for each
value of the Cross Variable(s). Once the data are re-arranged, summary statis-
WinNonlin
Users Guide
190
7
tics are computed for each column. This template displays these summary sta-
tistics. ID variables are not included, since this template summarizes over any
potential ID Variables. The summary statistics are done separately for any val-
ues of the Group Variable(s).
Template 5
The data in the Regular Variable(s) are broken into separate columns for each
value of the Cross Variable(s).
Template 6
The data in the Regular Variable(s) are broken into separate columns defined
by the Cross Variable(s). This template presents these new columns with one
row per value of any ID Variables and includes summary statistics. The sum-
mary statistics are done separately for each column, for any values of the
Group Variable(s).
Template 7
This template is very much like Template 6 except for the order in which the
columns are presented.
With Template 6 all of the Regular Variables are presented for the first value
of the Cross Variable; then all the Variables are presented for the second value
of the Cross Variable, etc.
With Template 7 all of the values of the Cross Variable are presented for the
first Regular Variable; then all of the values of the Cross Variable are pre-
sented for the second Regular Variable, etc.
Template 8
This template breaks the data into separate columns, much like Templates 6
and 7, but in this template, summary statistics are done for rows, rather than
columns. This template might be used, for example, with subjects as columns,
and Time as the ID Variable.
Template 9
Template 9 is very powerful in that it combines data from two data sets. With
this template tables can be created which combine raw data and derived PK
parameters and include summary statistics for each.
Tables
Table templates
191
7
Note: Template 9 does not appear in the template list unless at least 2 data sets are
already open.
This table employs Group Variables, ID Variables, and Cross Variables. It also
uses an Aggregate Variable. An Aggregate Variable is much like the Variable
used in Templates 1 through 8, although it is designated by using a template.
Because two data sets are combined into one table the user must define how
these data sets are to be joined.
With this template, Times and PK parameters are presented in columns, with
the separate profiles presented as rows. The two data sets for this template are
joined by the Group and ID Variables.
To select a template and data set(s):
1. Select a template from the list of templates displayed at the top of Table Wiz-
ard. A sample of the template is shown in this first dialog of the Table Wizard.
Clicking on this sample once expands the view of the sample to show the
entire sample template. Clicking on the sample once while in this expanded
mode returns it to its original size.
2. In the group box labeled Please select data set(s) and variables as needed,
select the appropriate data set from the pull-down list of data sets.
3. All of the data sets currently open are shown in the pull-down list box. The
variables in that data set are shown below the data set name.
Templates 1-8 use a single data set. When one of these templates is selected,
only one area for selecting a data set is available. Template 9 uses two data
sets. When this template is selected two areas for selecting a data set are avail-
able.
Note: In the pull-down list the path is included with the data set name. Holding the
cursor over the currently selected data set name will display the full file path.
4. Proceed to set the Table template variables.
WinNonlin
Users Guide
192
7
Table template variables
The following variable types are used in the Table Wizard. Table templates
vary in which variables are needed. If the selected template does not include a
given variable, then its list box is shown as gray to indicate it is unavailable.
ID variables
ID Variables are used to identify data in adjacent columns. When summary
statistics are included for a table, statistics are not computed for these vari-
ables. Typically, variables such as Subject, Period, or Treatment would be
included as ID Variables. Note that the rows in the table will be sorted by the
ID Variables.
When an ID Variable is included in a template, at least one ID Variable must
be specified. Note that multiple ID Variables may be used.
Group variables
Group Variables are much like ID Variables, except that only unique values of
Group Variables are printed. That is, they are printed only when the value
changes. The value of the Group Variables is also printed if values from a
group go over a page break.
The user may choose to have the page break each time the value of the Group
Variable(s) changes. When Group Variables are used as Page Break vari-
ables, the Group Variables may appear as an information line above the col-
umn titles, instead of as a column in the body of the table.
Note that the rows in the table will be sorted by the Group Variables, then the
ID Variables, if there are any. Note also that every template includes Group
Variables. Multiple Group Variables may be used, but Group Variables are not
required for any template.
Note: By default, Group Variables appear as a column of the table. This can be
changed, prior to using the Table Wizard, via the Options item on the Tools
menu. These two options are shown below.
Tables
Table template variables
193
7
To set the preference for treatment of group variables:
1. Select Options from the Tools menu, then select the Tables tab.
2. Check the Place page break data outside table body check box.
3. Click OK.
Note: The default for the Page Break status of Group variables can also be set.
Variables (or regular variables)
These variables are the data that goes into the body of the table. When sum-
mary statistics are requested, they are computed for these variables.
Cross, or X-Cross variables
Cross Variables divide data into separate columns, one per value of the Cross
Variable(s). For example, given a typical data set with the variables Formula-
Form Subject Time Conc
Capsule 1 0.00 0.00
1 5.00 340.32
1 10.00 1914.00
1 15.00 2069.17
1 20.00 1470.92
Form= Capsule
Subject Time Conc
1 0.00 0.00
1 5.00 340.32
1 10.00 1914.00
1 15.00 2069.17
1 20.00 1470.92
WinNonlin
Users Guide
194
7
tion, Subject, Time, and Concentration, using Template 5 with the assign-
ments:
The resulting table appears as follows:
Aggregate variables
An Aggregate Variable is used only in Template 9 (used to create a table from
two different data sets). An Aggregate Variable is much like the Variable
template variable used in Templates 1 through 8.
Mapping variables to the template
Once the template and the data set have been specified, drag the variables
from the list of available variables to the areas provided for each of the tem-
plate variables. When finished, click Next to move to the next screen.
Group Variable Formulation
ID Variable Subject
Cross Variable Time
Variable Concentration
Variable = Conc
Time
Form Subject 0.00 0.50 ... 24.00
Capsule 1.00 0.00 340.32 ... 19.32
2.00 0.00 887.67 ... 38.91
3.00 0.00 2164.60 ... 24.00
4.00 0.00 628.87 ... 93.85
5.00 0.00 384.63 ... 25.70
6.00 0.00 678.22 ... 46.55
Tablet 1.00 0.00 1474.20 ... 15.20
2.00 0.00 2609.83 ... 29.49
3.00 0.00 968.88 ... 55.22
4.00 0.00 1566.80 ... 32.00
5.00 0.00 1200.04 ... 12.54
6.00 0.00 1815.80 ... 36.20
Tables
Joining data sets
195
7
Note: To drag a group of variables that appear together in the Variable Collection
box, click on the first variable name of the variable group, then hold down the
Shift key and click on the last variable of that group. With the mouse button
still held down, slide the mouse to the intended variable box. Release the
mouse button.
A block will appear next to the name of each group variable. The block indi-
cates the page break settings for group variables. When the block is grayed the
page break settings are off. To indicate that a new page should start when the
value of a group variable changes, click on the block appearing next to that
variable name. A PB will appear in the block. To turn this off, click on that
block again.
If only one regular variable is specified, the name of that variable will be
included in a title line for the table. This is especially useful when using a
template that includes cross variables.
Joining data sets
Template 9 joins or merges two data sets into one table. For Template 9, the
two data sets are joined by the group and ID Variables. One must, therefore,
define these variables for each data set. The system will then merge the two
data sets together based on the values of these variables.
Although the variables may have different names in the two data sets, the two
data sets must have the same number of group and ID variables. When defin-
ing joins, select a variable from each data set in matched pairs. These matched
variables should represent related information. An example would be Formu-
lation with Formulation or Formulation with Treatment.
To define a join:
1. In the Table Wizard, select Table 9.
2. Select the two data sets that will provide table data, at the bottom left corner
of the Table Wizard.
3. Group variables: Click Define Join for Group Variables at the lower right, to
match variables in each data set to be used in identifying records to be
grouped together in descriptive statistics computations. One value of each sta-
tistic will be computed for each unique combination of group variable values.
WinNonlin
Users Guide
196
7
4. ID Variables: Click Define Join for ID Variables at the lower right to match
variables in each data set that uniquely identify individual records (e.g., pro-
files or subjects). The Select Join Variables dialog appears.
5. Select one variable from each data set at the top left and right. The values of
these variables will be used to merge records from the two data sets. For
example, if Subject and SubjID are selected from two data sets, WinNonlin
will look for unique values of Subject and SubjID, and merge records from
the two data sets that share identical values.
6. Click Add Join.
Tables
Summary statistics
197
7
7. Repeat the steps above until all appropriate pairs have been specified.
8. Click Done to return to the Tables.
Summary statistics
The Table Wizard can compute summary statistics, which are a part of most
table templates. (See Table templates on page 188.)
To select the summary statistics to be included in a table:
1. Check the check box preceding each summary statistic to be included in the
table. To select all of the available summary statistics, click All.
2. To include a confidence interval at a confidence level other than 95%, click in
the confidence interval check box, then enter the desired confidence level in
the box provided.
WinNonlin
Users Guide
198
7
Note: The statistics in the table will appear in the order listed here.
3. When finished, click Next to set the Significant digits.
Significant digits
The Table Wizard allows the user to select the number of decimal places or
the number of significant digits to be used. This selection is made separately
for each column in the final table as well as each summary statistic for each
column.
Tables
Summary statistics
199
7
Setting significant digits or decimal places
On this page, each column that will appear in the final table, and each sum-
mary statistic for each variable, appears as a separate row. For each one, spec-
ify significant digits or decimal places, the number of significant digits or
decimal places, and the alignment within the table column.
By default, WinNonlin displays the number of decimal places. To display
instead the number of significant digits for a particular item, type an S in the
column labeled Sig Digits/Dec Places for that row. Then type in the number
of significant digits in the column labeled # of Places or Digits.
Note: For variables in which an integer is displayed, such as Subject or Period,
choose Decimal places, and enter 0 for the number of places.
Setting column alignments
To set the alignment for an item in the table:
1. Select the appropriate row and column, and type L, C, or R, for Left justified,
Centered, or Right justified, respectively.
2. Once finished, click Next.
WinNonlin
Users Guide
200
7
Table formatting
The final dialog in the Table Wizard provides the means to format table cells
and headings, and the page layout. Using the pull down Item menu at the top
left corner, the user may format:
Column titles
Table body
Page headers, including the table title
Page footers, including page numbers and footnotes
Settings for Layout and Units are available to the bottom left. If no formatting
or cell borders are desired, see Data-only tables on page 203.
Column titles
To format column titles:
1. Select Column Titles from the pull-down list for Item.
2. To change the font, font size, or font style click the Set Font button. The Font
dialog appears, allowing the selection of the font, font size, and font style.
3. Once the font and style are set, click OK.
4. To change the alignment of the column titles, select the appropriate radio but-
ton in the Alignment group box.
5. To include the units already associated with the data set, select the layout and
format.
Table body
To format the table body:
1. Select Table Body from the pull-down list for Item. Note that the alignment
group box is not available, since alignment for the individual columns was
selected in the previous dialog. See Column titles on page 200.
2. To change the font, font size, or font style click the Set Font button. The Font
dialog appears, allowing selection of the font, font size, and font style for all
data in the body of the table.
Tables
Table formatting
201
7
3. Once the font and style are set, click OK.
Page headers
To format page headers:
1. Select Page Header from the pull-down list for Item.
2. Type a title for the table in the Page Header group box. As the title is typed it
appears in the display window. It is possible to move from one line to another
by pressing ENTER. The title is limited to 5 lines.
3. To change the font, font size, or style click the Set Font button. The Font dia-
log appears, allowing the selection of the font, font size, and font style.
4. Once the font and style are set, click OK.
5. To set the alignment of the title, select the appropriate radio button in the
Alignment group box.
Page footers
To format page footers:
1. Select Page Footer from the pull-down list for Item.
2. Type a footer for the table in the Page Footer group box. As it is entered it
appears in the display window. It is possible to move from one line to another
by pressing ENTER. The footer is limited to 5 lines.
3. To include page numbers on the table, check the Page numbers check box.
By default, the page numbering will start with 1. To specify another starting
number, enter this number in the box provided.
4. To change the font, font size, or style click the Set Font button. The Font dia-
log appears, allowing the selection of the font, font size, and font style.
5. Once the font and style are set, click OK.
6. To change the alignment of the footer text, select the appropriate radio button
in the Alignment group box.
WinNonlin
Users Guide
202
7
Layout
The page layout (Portrait or Landscape) may be specified at any time while on
this page.
To change the Page Layout:
1. Select the appropriate radio button in the Page Layout group box.
Units
If the input data set included units, those units can be displayed and/or printed
in the table. The default setting is to display all units in tables. This setting can
be changed on the Units tab of the Options dialog.
The default display setting has the variable units in parentheses after the
value.
To change the units display:
1. Select the appropriate radio button in the Unit Layout Presentation group box.
Note: The Units Presentation section only appears when the variable has units asso-
ciated with it. If the data set has no units associated with it, this group box will
not have any options about units.
Reformatting data sets
The Table Wizard can be used to reformat data in worksheets and to create
new worksheets for analysis. Two situations where this would be especially
useful are:
A long-skinny data set with IV and Oral data, with one column for For-
mulation, one for Subject, one for Time, and one for Concentration. One
option would be to use the Exclude feature to exclude IV data, and model
the Oral, and vice-versa, but it might be preferable to have the IV and
Oral data stored in separate columns, since these involve different mod-
els. This new data set can be created using Table 5 of the Table Generator,
with Formulation as a Cross variable.
A data set with multiple observations at some time points and what is
intended is to use the average of these observations as the Y variable. This
Tables
Table export
203
7
new data set can be created using Table 1 of the Table Generator module,
with Subject and Time as Group variables, thereby getting the average
concentration for each Subject and Time.
Data-only tables
Check Data Only at the top left of this dialog to create a table (worksheet)
without page breaks, column headers, borders or formatting.
Table export
WinNonlin provides the capability to export tables to other applications, such
as Microsoft Word and Microsoft Excel. This section describes how to move
the data in a table to other applications.
Exporting to Microsoft Word
A table is a new workbook in WinNonlin, easily exported to Word.
WinNonlin
Users Guide
204
7
To export a table to Word:
1. With the workbook open in the active window, select the Export to Word
tool bar button. Word is opened (if it was not already) and the table exported
to a Word document. If Word already has a document open, the table is
appended to that document.
Exporting to Microsoft Excel
To export a table to Microsoft Excel, save the workbook in WinNonlin as an
Excel spreadsheet. Saving data in Excel format will result in the loss of units
associated with columns. The worksheet can then be opened directly in
Microsoft Excel.
Table definition files
A table definition file stores a user-defined table format. The table definition
file can be used to store particular formatting, then reused to create tables in
this familiar format.
To use a table definition file, the data set(s) must include the exact variable
(column) names used in the definition file.
The table definition file includes:
Table template number
Names of ID Variables, Group Variables, Join Variables, Cross Variables
and Reg Variables
Summary statistics to be included (if applicable)
Titles (up to five lines)
Footers (up to five lines)
Formatting specifications:
Alignment and decimal places for the variables
Font, font style, font size and alignment for column titles, table body,
header and footer
Page layout
Layout and specification of units
Tables
Table definition files
205
7
Creating a table definition file
Table definition files must be created by WinNonlin. To create a table defini-
tion file (.TDF) a table must be created with all of the formatting desired. Then
save this information to a file.
To create and save a table definition file (.tdf):
1. Using the Table Wizard, complete all the steps to create the table until the pre-
view of the table (just before clicking the Create button).
2. From the File menu, select Save Definition As (Alt+F, S). The Save Current
Settings dialog box appears.
3. Select a drive and directory.
4. Enter a meaningful file name, using the file extension .TDF.
5. Click OK.
WinNonlin
Users Guide
206
7
Loading a table definition file
To load a table definition file (*.tdf) in the Table Wizard:
1. Open an existing data set or create a new data set.
2. Choose Tools>Table Wizard from the menus or click the Table Wizard but-
ton on the tool bar. The Table Wizard appears.
3. Select the appropriate data set.
4. From the File menu of the Table Wizard select Open Definition.
5. Select the appropriate Table Definition file using the Retrieve Saved Settings
dialog box.
6. Click Open.
Specifications made via the Table Definition file will be implemented. Other
changes can be made to the table using the Table Wizard.
207
Chapter 8
Descriptive Statistics
Summary statistics and weighted summary
statistics
WinNonlin can compute summary statistics for variables in any workbook.
This feature is frequently used to plot means and standard errors, for preclini-
cal summaries, and to summarize modeling results. Separate statistics for sub-
groups are obtained through the use of sort variable(s).
Computing summary statistics
To set up descriptive statistics:
1. Open the input data worksheet. The data set must be open and not hidden.
2. Choose Tools>Descriptive Statistics from the WinNonlin menus, or click the
Descriptive Statistics button on the tool bar.
Figure 8-1. The Descriptive Statistics dialog allows settings to be saved to an ASCII
file for later re-use, through the Save Setup and Load Setup buttons.
WinNonlin
Users Guide
208
8
3. Drag the variable(s) to be summarized to the Summary Variables box.
Note: Select variables either by dragging the variable name to the appropriate box,
or by highlighting the variable name then, while pressing the Shift key, typing
the underlined letter in the name of the destination box.
4. Select Sort variable(s) if desired. A separate analysis is done for each unique
combination of sort variable values.
5. Select the options for the statistics:
Confidence intervals: Enter the desired confidence interval in the % field.
Percentiles: Selecting the check box means that the first, fifth, tenth,
twenty-fifth, fiftieth, seventy-fifth, ninetieth, ninety-fifth, and the ninety-
ninth percentiles will be included in the output.
Box and Whiskers plot: The Box and Whiskers plot appears in a separate
text window. The box hinges are the 25th and 75th percentiles. The
median is plotted as an asterisk (*). The whiskers end at the data points
farthest from the median that are still within 1.5 times the H-spread (the
distance between the hinges) of the hinges. If there are no outliers beyond
this range, the whiskers end at the maximum and minimum points. Data
points between 1.5 and 3 H-spreads from the hinges are marked by an o,
and the those outside 3 H-spreads are marked by x. If there are fewer than
five data points, the data are graphed individually rather than as a box.
Weight Variable: (Optional) See Weighted summary statistics on
page 212.
Create Sheets for Summary Variables: When there are multiple summary
variables the output can be sent to one or multiple worksheets in the out-
put workbook. If output is combined onto one worksheet, no units will
appear with the output. See Units on page 212.
6. Click Calculate.
Output and computational formulae
The output worksheet for summary statistics contains a column indicating the
summary variable(s), and one for each sort variable and the statistics below.
Descriptive Statistics
Computing summary statistics
209
8
Table 8-1. Descriptive statistics output
Statistic Description
N Number of observations with non-missing data
Nmiss Number of observations with missing data
Nobs Number of observations
Mean Arithmetic Average
SD Standard Deviation:
SE Standard Error:
Variance Unbiased sample variance:
Min Minimum value
Median Median value
Max Maximum value
Range Range of values (maximum value minus minimum value)
CV% Coefficient of variation: (SD/Mean)*100
Geometric Mean Nth root of the product of the N observations
Harmonic Mean Reciprocal of the arithmetic mean of the reciprocals of the observations
Variance
SD
N
--------
X
i
X ( )
2
i 1 =
N

N 1
-------------------------------
WinNonlin
Users Guide
210
8
Pseudo SD Jackknife estimate of the standard deviation of the harmonic mean. For
n points, x
1
, .... x
n
the pseudo standard deviation is:
where:
and:
Mean log Arithmetic average of the natural logs of the observations
SD Log Standard deviation of the natural logs of the observations
CV% Geometric
Mean
Coefficient of variation of the geometric mean:
CI X% Lower Mean Lower limit of an X% confidence interval for the mean:
Table 8-1. Descriptive statistics output (continued)
Statistic Description
pseudo SD n 1 ( ) H
i
H ( )
2
i 1 =
n

=
H
1
n
---
H
i
i 1 =
n

=
H
i
n 1 ( )
1
x
1
-----
1
x
2
-----
1
x
i 1
----------
1
x
x 1 +
-----------
1
x
n
----- + + + + + +
\ .
| |
---------------------------------------------------------------------------------------------- =
n 1 ( )
1
x
j
----
j 1 =
n

\ .
|
|
| |
1
x
i
----
----------------------------- =
SD_log ( )
2
( ) exp 1 100
Mean t
2
SD
N
--------
Descriptive Statistics
Computing summary statistics
211
8
CI X% Upper Mean Upper limit of an X% confidence interval for the mean:
where is the percentage given for the confidence inter-
val, and is from the t-distribution with N-1 degrees of freedom.
Thus, a 95% confidence level indicates that alpha = 0.05. Note that for
N>30, the t-distribution is close to the normal distribution.
CI X% Lower Var Lower limit of an X% confidence interval for the variance:
CI X% Upper Var Upper limit of an X% confidence interval for the variance:
where
L
2
and
U
2
are from the
2
-distribution with N-1 degrees of
freedom.
L
2
cuts off a lower tail, and
U
2
cuts off an upper tail, of area
/2 where (1 - )*100 is the percentage for the confidence interval.
P(ercentiles)
The p
th
percentile divides the distribution at a point such that p percent
of the distribution are below this point
Skewness Coefficient of skewness:
Kurtosis Coefficient of excess (kurtosis):
Table 8-1. Descriptive statistics output (continued)
Statistic Description
Mean t
2
SD
N
--------
+
1 ( ) 100
t
2
N 1 ( ) Variance

U
2
------------------------------------------------
N 1 ( ) Variance

L
2
------------------------------------------------
w
i
x
i
x
w
( )
3
N

w
i
x
i
x
w
( )
2
N

3 2
---------------------------------------------------------
w
i
x
i
x
w
( )
4
N

w
i
x
i
x
w
( )
2
N

2
---------------------------------------------------- 3
WinNonlin
Users Guide
212
8
Units
When summary statistics are calculated on a variable with units, certain of the
calculations will have units. Assuming that the variable summarized is x and
has x-units specified, the units for the summary statistics are:
Weighted summary statistics
Summary statistics can be weighted, using a column in the data set to provide
weights. If a weight is non-numeric, missing, or excluded, it is set to zero.
To create weighted summary statistics:
1. Make all specifications as for un-weighted summary statistics. See Comput-
ing summary statistics on page 207.
2. Drag the variable containing weights to the Weight Variable box (or high-
light the variable to be used as the weight and press Shift+W).
Units
Units are displayed as for summary statistics. See Units on page 212.
Output and computational formulae
The output for weighted summary statistics contains a column indicating the
summary variable(s), one for each sort variable, and the statistics below.
Statistic Units
N, Nmiss, Nobs No units
CV%, CV% Geometric Mean No units
Skewness No units
Kurtosis No units
Mean log, SD log No units
Variance
x-unit
2
CI Lower Var, CI Upper Var
x-unit
2
Everything else x-unit
Descriptive Statistics
Weighted summary statistics
213
8
Table 8-2. Weighted summary statistics output
Statistic Description
N Number of non-missing observations (including those with weights = 0)
Nmiss Number of observations with missing data
Nobs Number of observations (including observations with weights of 0)
Mean Weighted Arithmetic average:
SD Weighted Standard Deviation:
SE Weighted Standard Error:
Variance Weighted Variance:
where is the weighted mean.
CV% Weighted Coefficient of variation: (Weighted SD/Weighted Mean)*100
CI X% Lower Mean Lower limit of an X% confidence interval, using weighted mean and SD
CI X% Upper Mean Upper limit of an X% confidence interval, using weighted mean and SD
CI X% Lower Var Lower limit of an X% confidence interval, using weighted variance
CI X% Upper Var Upper limit of an X% confidence interval, using weighted variance
Skewness Weighted coefficient of skewness:
Kurtosis Weighted coefficient of excess (kurtosis):
w
i

x
i

w
i

-----------------------
Weighted Variance
Weighted SD
N
-------------------------------
w
i

x
i
x
w
( )
2
N 1
------------------------------------
x
w
w
i

x
i
x
w
( )
3
n
w
i

x
i
x
w
( )
2
n
3 2
--------------------------------------------------------
w
i

x
i
x
w
( )
4
n
w
i

x
i
x
w
( )
2
n
2
--------------------------------------------------- 3
WinNonlin
Users Guide
214
8
215
Chapter 9
Noncompartmental
Analysis
WinNonlin's noncompartmental analysis engine computes derived pharmaco-
kinetic parameters from raw time-concentration data, including:
WinNonlin provides six noncompartmental models to support extravascular,
intravascular (IV) infusion or IV bolus dosing, for concentration data from
blood/plasma data (single dose and steady state) or urine (single dose only).
Additional available calculations include:
The general steps to set up noncompartmental analysis (NCA) include:
1. NCA model selection
2. Model variables
3. Lambda z estimation settings
4. Partial areas
Area under the curve (AUC)
Cmax, peak observed concentration
Tmax, time of peak concentration
Terminal elimination rate (beta)
Terminal half-life
Urinary excretion rate
AUC: Linear trapezoidal or Linear/
Logarithmic rule
Partial Areas under the curve
Derived parameters for parent drug
and metabolites, IV infusion and
bolus dosing, and other formulations
Dose adjustments (AUC/D)
Baseline response
Ratios or percent change from
baseline
Handling of endogenous data
WinNonlin
Users Guide
216
9
5. Dosing regimen
6. Model options
NCA model selection
To load a noncompartmental analysis model:
1. Open the worksheet containing data to be modeled, and select it as the active
worksheet (click on that worksheet to bring it to the front).
2. Start the PK/PD/NCA Analysis Wizard by clicking on that tool bar button or
selecting the command from the Tools menu.
3. Select the Noncompartmental radio button and click Next.
4. Select the appropriate NCA model for the data.
The plasma models can be used for either single-dose or steady-state data.
When using these models (200-202) with steady-state data, the computation
assumes equal dosing intervals (Tau) for each profile, and that the data are
from a final dose given at steady-state. Models 210-212 (urine concentra-
tions) assume single-dose data.
See Computational rules for WinNonlins noncompartmental analysis
engine on page 234 for details on the noncompartmental analysis calcula-
tions.
Table 9-1. Noncompartmental analysis models
Model Type of data Input Constants required
Model 200 Plasma or blood Extravascular Dose, Time of last dose, (Tau)
Model 201 Plasma or blood Bolus IV Dose, Time of last dose, (Tau)
Model 202 Plasma or blood Constant infusion Dose, Length of infusion, Time of last
dose, (Tau)
Model 210 Urine Extravascular Dose, Time of last dose
Model 211 Urine Bolus IV Dose, Time of last dose
Model 212 Urine Constant infusion Dose, Time of last dose
Noncompartmental Analysis
Model variables
217
9
5. Click Next.
6. Confirm that the correct model is selected, and click Finish to load the model.
The model window will open with a sample graph.
Model variables
To specify data columns for each model variable in a noncompartmental analysis:
1. After NCA model selection, open the Data Variables dialog (Model>Data
Variables).
2. For plasma models, drag and drop columns to assign variables to be modeled:
X: the independent variable, generally time.
Y: the dependent variable, i.e., observed values of interest, such as plasma
concentration of drug.
3. For urine models, drag and drop columns to assign variables to be modeled:
Concentration: the dependent variable, drug concentration in urine.
Volume: the volume of urine collected per time interval.
Lower times: the starting times for individual collection intervals
WinNonlin
Users Guide
218
9
Upper times: the ending times for individual collection intervals
Note: WinNonlin computes the midpoint of each collection interval and the excre-
tion rate for each (amount eliminated per unit of time) for urine models.
4. Drag and drop to specify the following (optional):
Sort Variable(s): categorical variable(s) identifying individual data pro-
files, e.g., subject ID, or treatment in a crossover study. A separate analy-
sis is done for each unique combination of sort variable values.
Carry Along Variables: data to be copied into the analysis output work-
book.
Note: The output data set will automatically include, in addition to the output vari-
ables, the original values of the Sort variable(s) and variables being modeled
(X and Y for plasma models or midpoint and rate for urine models).
5. Click OK.
Lambda z estimation settings are the next step in setup of a noncompartmental
analysis.
Lambda z estimation settings
WinNonlin will attempt to estimate the rate constant,
z
, associated with the
terminal elimination phase. Noncompartmental parameters will be estimated
using linear or linear/log trapezoidal rule, as selected in the Model Options
(see Model options on page 225). If
z
can be estimated, the calculated
parameters will be extrapolated to infinity.
Lambda z range selection
The user may specify the data points to be included in the calculation of
z
or
choose that
z
not be estimated (See Setting Lambda z ranges on page 220).
If neither of these options is selected, WinNonlin determines the data points to
be included, as follows. During the analysis, WinNonlin repeats regressions
using the last three points with non-zero concentrations, then the last four
points, last five, etc. Points prior to Cmax or prior to the end of infusion are
not used unless the user specifically requests that time range. Points with a
Noncompartmental Analysis
Lambda z estimation settings
219
9
value of zero for the dependent variable are excluded. For each regression, an
adjusted R
2
is computed:
where n is the number of data points in the regression and R
2
is the square of
the correlation coefficient.
The regression with the largest adjusted R
2
is selected to estimate
z
, with
these caveats:
If the adjusted R
2
does not improve, but is within 0.0001 of the largest
adjusted R
2
value, the regression with the larger number of points is used.

z
must be positive, and calculated from at least three data points.
Calculation of Lambda z
Once the time points being used in the regression have been determined, Win-
Nonlin can estimate
z
by performing a regression of the natural logarithm of
the concentration values in this range on sampling time.
z
is defined as:

z
= -1 (estimated slope)
Note: Using this methodology, WinNonlin will almost always compute an estimate
for
z
. It is the users responsibility to evaluate the appropriateness of the esti-
mated value.
Limitations of Lambda z estimation
There are a number of instances in which it is not possible for WinNonlin to
estimate
z
(see below). In these instances, parameters that do not depend on

z
(i.e. Cmax, Tmax, AUClast, etc.) will still be reported. In these instances,
the software will issue a warning in the text output, indicating that
z
was not
estimable:
There are only two observations after eliminating missing values and the
user requested automatic range selection for
z
.
The user has supplied bounds, but the lower bound was greater than the
last non-missing data point.
Adjusted R
2
1
1 R
2
( ) n 1 ( )
n 2 ( )
------------------------------------------- =
WinNonlin
Users Guide
220
9
Automatic range selection is activated, but there are fewer than 3 positive
concentration values at or after the Cmax of the profile.
For infusion data, automatic range selection is activated, and there are
fewer than 3 points at or after the infusion stop time.
The time difference between the first and last data points in the estimation
range used is approximately < 1e-10.
Setting Lambda z ranges
To set the
z
range for each profile:
1. Open the Lambda z Ranges tab of the Model Properties dialog
(Model>Lambda z Ranges).
A plot is available for each data profile. Individual profiles are defined by the
Sort variable(s) specified in Model variables on page 217.
2. Select the axis scale for the graphical representation: Linear or Log Linear.
3. To move between profiles, use the arrow buttons directly below the plot.
4. Define the terminal elimination phase for each profile (optional) as follows. If
these are not set, WinNonlin will determine the data points to be used as
described under Lambda z range selection on page 218.
Noncompartmental Analysis
Partial areas
221
9
a. Select the first data point to be included: left-click on a data point or enter
a time value under Start time.
b. Select the last data point to be included: hold down the Shift key while
left-clicking on a data point or enter a time value under End time.
Note: The units for Start and End time are those of observation times in the data set.
5. Exclusions (optional): to exclude a data point from the
z
calculations, hold
down the Ctrl key and left-click on that point. Repeat to reverse an exclusion.
6. Curve stripping can be disabled for all profiles by checking Disable Curve
Stripping at the bottom left. With this option checked:

z
will not be estimated.
Parameters that are extrapolated to infinity will not be calculated.
Note: To disable curve stripping for one or more individual profiles, rather than for
all profiles, enter a start time that is greater than the last time point in the pro-
file, and an end time greater than the start time.
7. When done, click Apply to save the settings and move to another tab of the
Model Properties dialog. To save the settings and close the dialog, click OK.
Loading Lambda z Ranges from an ASCII file
The Load and Save buttons make it possible to store Lambda z time ranges to
an external ASCII data file, and reload those settings for reuse.
Partial areas
Up to 126 partial areas can be computed per profile. Partial areas are included
by setting start and end times for each desired time interval. The start and end
times need not appear on the data set, and can be later than the last observed
time, if
z
is estimable. See Partial areas on page 236 for further informa-
tion on partial area computations.
To specify the partial areas to be calculated:
1. Select Model>Partial Areas from the menus or click on the Partial Areas
tool bar button.
WinNonlin
Users Guide
222
9
2. Enter the start time in the cell labeled AUC1 Lower, and the end time in the
cell labeled AUC1 Upper.
3. For another partial area (AUC2L, AUC2U, etc.), repeat this step.
4. Repeat steps 2 and 3 for other profiles or use the fill-down method (drag bot-
tom right corner of selected cells) to copy from one profile to those below.
Note: Different partial areas can be computed for each profile.
5. To compute time spent within a therapeutic concentration range, and AUCs
for said time periods, check Therapeutic Response Window. Enter the upper
(optional) and lower concentrations delimiting the therapeutic range. See
Therapeutic response window below for calculation details.
6. Click OK.
The Save button stores the Lambda z settings to an external ASCII file.
Therapeutic response window
The therapeutic response window specifies the lower and upper concentra-
tions for therapeutic range (response window). When this option is checked,
WinNonlin computes additional parameters to be included in the Final Param-
eters table of the NCA output. The parameters computed differ depending
Noncompartmental Analysis
Dosing regimen
223
9
whether the user enters values for both the lower concentration field (lower)
and upper concentration field (upper), or only for the lower concentration.
If both values are entered, the output includes the parameters listed in the top
two rows of Table 9-2 below. If only one concentration value is specified, the
therapeutic response window function reports output below and above this
value. WinNonlin sets the upper concentration field to twice Cmax (maximum
concentration) so that the calculated output is that reported in the third row of
Table 9-2. See Therapeutic windows on page 237 for further details on ther-
apeutic response window computations.
Dosing regimen
Models 200 to 202 (Plasma) in the WinNonlin library assume that data were
taken after a single dose, or after a final dose given at steady state. For steady
Table 9-2. Therapeutic window output
Input
values
Time range for
computation
Parameter Description
Lower and
upper
from dosing time
to last observation
TimeLow
TimeDuring
TimeHigh
AUCLow
AUCDuring
AUCHigh
total time below lower limit
total time between lower limit and upper limit
total time above upper limit
AUC for time below lower limit
AUC for time between lower limit and upper limit
AUC for time above upper limit
Lower and
upper
from dosing time
to infinity using
z

(if
z
exists)
TimeInfDuring
TimeInfHigh
AUCInfLow
AUCInfDuring
AUCInfHigh
total time between lower limit and upper limit
total time above upper limit
AUC for time below lower limit
AUC for time between lower limit and upper limit
AUC for time above upper limit
Lower only from dosing time
to last observation
TimeLow
TimeHigh
AUCLow
AUCHigh
total time below lower limit
total time above lower limit
AUC for time below lower limit
AUC for time above lower limit
Lower only from dosing time
to infinity using
z

(if
z
exists)
TimeInfHigh
AUCInfLow
AUCInfHigh
total time (extrapolated to infinity) above lower limit
AUC for time (extrapolated to infinity) below lower limit
AUC for time (extrapolated to infinity) above lower limit
WinNonlin
Users Guide
224
9
state data, WinNonlin also assumes equal dosing intervals. Models 210 to 212
(urine) assume single-dose data.
To enter the dosing information:
1. Choose Model>Dosing Regimen from menus or click the Dosing Regimen
tool bar button. The Dosing Regimen tab of the Model Properties dialog
opens.
It is possible to save dosing information to an external ASCII file for reuse,
using the Save button. The Load button reloads this file.
To enter single dose information:
1. Enter the dosing constant(s) requested, in the column labeled Value.
2. Enter dosing constants for each level of the sort variable(s), if applicable.
3. Set the dosing units. See Dosing units on page 122 for details.
4. Click Apply or OK.
To enter steady state information (plasma data only):
1. In the Dosing Regimen tab of the Model Properties dialog click the Steady
State check box. The list of constants in the spreadsheet changes.
Noncompartmental Analysis
Model options
225
9
2. Enter the dose.
3. If the last dose was given at a time other than 0, enter the time of the last dose
in the Time of Last Dose entry box.
4. Enter the dosing interval (Tau).
5. Set the dosing units. See Dosing units on page 122 for details.
6. Click Apply or OK.
Rules for handling of steady-state data
When using steady-state data, WinNonlin computes AUC0-tau based on the
tau that the user specifies. However, in most studies, there will be sampling
time deviations. That is, if tau=24, the last sample might be at 23.975 or
24.083 hours. In this instance, the program will estimate the AUC based on
the estimated concentration at 24 hours, and not the actual concentration at
the time deviation.
For steady state data, Cmax, Tmax, Cmin and Tmin are found from points at
or after the dosing time, but no later than dosing time+tau, where tau is the
dosing interval.
Model options
Options for NCA model output are divided into the following groups:
Table 9-3. NCA model options
Category Options
Output options Workbook, chart, and/or ASCII text formats for modeling results
Weight Uniform or weighted least squares
Title Text title for workbook, ASCII and chart output
NCA settings Method for computing area under the curve, and format of final
parameters worksheet
Units Default units for output parameters
Parameter names Option to set the variable names for final model parameters
WinNonlin
Users Guide
226
9
To set NCA model options:
1. Select Model>Model Options from the WinNonlin menus or click on the
Model Options tool bar button. The Model Options dialog box appears.
Figure 9-1. The Model Options dialog, output options for NCA
2. Click on a tab to select and adjust a group of options from those in Table 9-3.
3. Click Apply (to set options and keep the dialog open) or OK.
Output options
After noncompartmental analysis is run, one or more new windows is gener-
ated, with content as selected in the following NCA Model options.
Note: The default output options are set via Tools>Options in the WinNonlin menus.
Exclude profiles with insufficient data
If this option is checked, profiles with all or many missing parameter esti-
mates are excluded from the results. If it is not checked, profiles with insuffi-
cient data will generate output with missing parameter values. The cases in
which parameters are reported as missing are also discussed under Data defi-
ciencies that will result in missing values for PK parameters on page 235.
The following cases will be excluded:
Noncompartmental Analysis
Model options
227
9
Workbook
This option selects whether to generate a workbook containing the output.
The NCA workbook contains several worksheets summarizing the results.
These worksheets present the same information as the ASCII output, but in a
more convenient form for use in further analyses.
Chart
If workbook output is selected, output charts are available. The NCA Chart
window provides a plot of observed versus predicted data for each profile.
Profile issue(s) Parameters reported as missing
Profile includes only one or no observations all final parameters
Blood/plasma data with no non-zero observation values All final parameters except Cmax,
AUClast, AUCall, AUMClast
Blood/plasma data with all zero values except one non-
zero value at dosing time
all final parameters
Urine data with urine volumes equal to zero all final parameters
Urine data with concentration values equal to zero All final parameters except
Max_Rate, Amount_Recovered,
Percent_Recovered
Table 9-4. Summary of NCA worksheets
Sheet name Contents
Final Parameters Estimates of the final parameters for each level of the sort variable
Dosing The dosing regimen for the analysis
Summary Table The sort variables, X, points included in the regression for
z
,Y, pre-
dicted Y for the regression, residual for the regression, AUC, AUMC
and weight used for the regression
Partial Areas See Partial areas on page 221.
User Settings User defined settings
WinNonlin
Users Guide
228
9
Text
This option provides an ASCII text version of the output, containing the same
information as the workbook output. It is often used for reporting and
archiving analyses. Modeling errors are also reported in this file. This output
can be used for reporting, and is also very useful for archiving analyses. The
NCA text window contains an ASCII form of the analysis results. The text
output contains the same information as the workbook output. This window
will only appear if Text output was selected on the Output Options tab in the
Modeling Options dialog, or if an error occurs in the calculations.
Page Breaks
This check box turns page breaks in the ASCII output on or off.
Output intermediate calculations
If this option is checked, the text output for the next analysis only will include
values for iterations during estimation of
z
, and for each of the sub-areas
from partial area computations, as shown below.
Noncompartmental Analysis
Model options
229
9
Weight
For noncompartmental analysis, the selections made on the Weight tab of the
Model options dialog apply to the regression used to estimate
z
.
Note that it is not the weights themselves that are important; rather it is the
relative proportions of the weights. See Weighting on page 325 for discus-
sion of weighting schemes.
CAUTION: When a log-linear fit is done, it already uses weighting implicitly, approxi-
mately equal to 1/Yhat
2
.
To use uniform weighting:
1. Select the Pre-selected Scheme radio button.
2. Select Uniform Weighting from the pull-down list.
To use weighted least squares:
1. Select Observed to the Power n button.
2. Enter the value of n in the entry box provided.
3. Use the Pre-selected scheme button to select the most common weighted
least square options: 1/Y and 1/Y
2
.
WinNonlin
Users Guide
230
9
Note: When weighting by 1/Y and using the Linear/Log trapezoidal rule, one could
argue that the weights should be 1/LogY, rather than 1/Y. However, if this
were the case, concentrations between 0 and 1 would have negative weights,
and therefore could not be included.
Title
A title can be displayed at the top of each printed page in ASCII text output.
The title is also included on the User Settings worksheet in the workbook out-
put, at the top of each chart in chart output.
To include a title:
1. Make sure that Title Text is checked on the Title tab of the Model options dia-
log. If it is not, the title will not display even if text is entered below.
2. Enter the title text below. To include a line break use Shift + Enter. The title
will be centered on the page.
NCA settings
Calculation methods for AUC
Four methods are available for the calculation of area under the curve, in the
NCA Settings tab of the Model options dialog. The method chosen applies to
all AUC, AUMC, and partial area computations. All methods reduce to the
Noncompartmental Analysis
Model options
231
9
log trapezoidal rule and/or linear trapezoidal rule, but differ with regard to
when these rules are applied.
Linear Trapezoidal rule (Linear Interpolation) [default]. This method
(method 2 in Command Files) uses the linear trapezoidal rule, given
below, applied to each pair of consecutive points in the data set that have
non-missing values, and sums up these areas. If a partial area is selected
that has an endpoint that is not in the data set, then the linear interpolation
rule, given below, is used to inject a concentration value for that endpoint.
Linear Trapezoidal Method with Linear/Log Interpolation (method 4). As
above except that if a partial area is selected that has an endpoint that is
not in the data set: the linear interpolation rule is used to inject a concen-
tration value for that endpoint if the endpoint is before Cmax; the loga-
rithmic interpolation is used after Cmax. If Cmax is not unique, then the
first occurrence of Cmax is used.
Linear/Log Trapezoidal Method (method 1). Uses the linear trapezoidal
rule up to Cmax and then the log trapezoidal rule for the remainder of the
curve. If Cmax is not unique, then the first occurrence of Cmax is used.
Linear interpolation is used up to Cmax for injecting points for partial
areas, and logarithmic interpolation is used after Cmax.
Linear Up/Log Down Method (method 3). The linear trapezoidal rule is
used any time that the concentration data is increasing, and the logarith-
mic trapezoidal rule is used any time that the concentration data is
decreasing. Points for partial areas are injected using the linear interpola-
tion rule if the surrounding points show that concentration is increasing,
and the logarithmic interpolation rule if the concentration is decreasing.
See AUC calculation and interpolation formulas on page 235 for equations
applied in these computations.
Note: Both the Linear/Log Trapezoidal and the Linear Up/Log Down method have
the same exceptions with regard to the area calculation method used: If a con-
centration is less than or equal to zero, the program defaults to the linear trap-
ezoidal method for that point. If the concentration values are equal to each
other, then program also defaults to the linear trapezoidal rule.
Transpose Final Parameter Table
Transpose Final Parameter Table, if checked, will create a Final Parameters
worksheet with one column for each statistic of each parameter. A second
WinNonlin
Users Guide
232
9
worksheet called Non-transposed Final Parameters will present one row for
each parameter and one column for each type of statistic. If the Transpose
Final Parameters option is not checked, the Final Parameters worksheet will
present the untransposed format, and the second worksheet, entitled Trans-
posed Final Parameters, will present the transposed version. This option is
provided primarily for WinNonlin scripts that depend on one format or the
other in the Final Parameters worksheet. See Transpose final parameter
table on page 262 for example output compartmental modeling.
Units
Select the preferred units for the output. The Units dialog lists default units for
output parameters. When preferred units are specified on the Units tab of the
Model options dialog (below), WinNonlin makes the necessary conversions to
display the output in the preferred units.
Note: Before preferred units can be entered, units must be set for the X-variable, Y-
variable, and, for plasma models, the Dosing Regimen. The units for the X-
variable and Y-variable are read in from the data set.
To set a preferred unit:
1. Enter the unit under Preferred for the appropriate row. The units cannot con-
tain space characters. WinNonlin will convert output values to use this unit.
2. Click Apply or OK.
Noncompartmental Analysis
Model options
233
9
Note: Preferred Units can be set only if the units are already set for the X-variable,
Y-variable, and, for plasma models, dosing.
Preferred units can be saved as a template for units (an ASCII data file) then
loaded back for later modeling using the Save and Load buttons.
Parameter names
For noncompartmental analyses (NCA) only, WinNonlin provides the option
to set the variable names for the final model parameters. These names cannot
contain space characters.
Preferred parameter names can be saved to an external file for reuse. As the
parameters vary by model and depending whether the dosing is at steady state,
save parameter names for specific models to different files, for example:
model200.nam model200SS.nam
model201.nam model201SS.nam
model202.nam model202SS.nam modelurine.nam
WinNonlin also provides the option to include only a subset of final parame-
ters in NCA workbook output. Click on a cell under Include in Workbook to
toggle between Yes (include parameter in that row) and No (exclude).
WinNonlin
Users Guide
234
9
Computational rules for WinNonlins noncompartmental analysis engine
Data checking and pre-treatment
Prior to calculation of pharmacokinetic parameters, WinNonlin institutes a
number of data-checking and pre-treatment procedures as follows.
Sorting
Prior to analysis, each pharmacokinetic profile is sorted in ascending order
with regard to time. (A profile is identified by each unique value or combina-
tion of values for the sort variable(s).)
Insertion of initial time points
If a PK profile does not contain an observation for the dosing time, WinNon-
lin automatically inserts such a point based on the following rules:
For extra-vascular and infusion models, the value of the inserted point
will depend upon whether the data is from a single dose profile, or was
sampled at steady-state. For single dose data, a concentration value of
zero will be used. In the case of steady-state the minimum value observed
during the dosing interval will be used.
For IV bolus data, the same rule will be used for both single-dose and
steady-state data. Generally, the program will perform a log-linear regres-
sion of first two data points to back-extrapolate C0. However, in the
instance that the regression yields a slope >= 0 or at least one of the first
two y-values is 0, then the first observed positive y-value will be used as
an estimate for C0.
Data exclusions
WinNonlin will automatically exclude unusable points from NCA analysis.
Missing values: For plasma models, if either the X-value or the Y-value is
missing, then the associated record is excluded from the NCA analysis.
For urine models, records with missing values for any of the following
will be similarly excluded: collection interval start time; collection inter-
val stop time; drug concentration; or collection volume.
Data points preceding the dose time: If the time value for a data point is
earlier than the dosing time, then the point is excluded from the NCA
Noncompartmental Analysis
Computational rules for WinNonlins noncompartmental analysis engine
235
9
computations. For urine models, the lower time point is checked. Note
that the dosing time must be non-negative.
Data points for urine models: In addition to the rules described above, for
urine models if the lower time is greater than or equal to the upper time,
or if the concentration or volume is negative, then the user will be
required to correct the data before NCA computations can be done.
Data deficiencies that will result in missing values for PK parameters
There are a number of cases in which WinNonlin will report missing values
for most PK parameters:
The number of non-missing data points is <=1. For definitions of what
constitutes a Missing Value, please see the relevant section above.
A urine profile has values for collection volumes or concentration values
that are all zero.
A plasma concentration profile has either concentration values that are all
zero, or only one non-zero concentration at the dosing time.
Multiple observations at the same time point
For noncompartmental analysis, WinNonlin only permits one observation at
each time point within a profile. If the software detects more than one such
point, the NCA analysis is halted, and an error message is issued. No PK out-
put is generated in this instance.
AUC calculation and interpolation formulas
The computational formulas for area under the curve calculations and interpo-
lation follow.
Linear trapezoidal rule

AUC
t
1
t
2
t
C
1
C
2
+
2
------------------- =
AUMC
t
1
t
2
t
t
1
C
1
t
2
C
2
+
2
--------------------------------------- =
WinNonlin
Users Guide
236
9
Logarithmic trapezoidal rule
where t is (t
2
-t
1
).
Linear interpolation rule (to find C* at time t*)
Logarithmic interpolation rule
Partial areas
Rules for interpolation and extrapolation
Generally speaking partial areas are calculated using the rules described under
AUC calculation and interpolation formulas on page 235 and Calculation
methods for AUC on page 230. However, there are several rules for handling
cases in which some portion of the partial area falls after the last positive con-
centration value:
If a starting or ending time occurs before the first data observation, the
corresponding Y value is interpolated between the first data point and the
value used as C0. C0=0 except in IV bolus models (model 201), where C0
is the dosing time intercept estimated by the program, and except for
models 200 and 202 at steady state, where C0 is the minimum value
between dosing time and tau.
AUC
t
1
t
2
t
C
2
C
1

ln
C
2
C
1
------
\ .
| |
------------------
=
AUMC
t
1
t
2
t
t
2
C
2
t
1
C
1

ln
C
2
C
1
------
\ .
| |
--------------------------------------- t
2

C
2
C
1

ln
C
2
C
1
------
\ .
| |
2
------------------- =
C* C
1
t* t
1

t
2
t
1

---------------
C
2
C
1
( ) + =
C* C
1
( )
t* t
1

t
2
t
1

---------------
C
2
( ) ln C
1
( ) ln ( ) + ln
\ .
| |
exp =
Noncompartmental Analysis
Computational rules for WinNonlins noncompartmental analysis engine
237
9
If a starting or ending time occurs within the range of the data but does
not coincide with an observed data point, then a linear or logarithmic
interpolation is done to estimate the corresponding Y, according to
whether the linear trapezoidal rule, the linear/log trapezoidal rule, or the
Linear up/Log down trapezoidal rule was selected in the Model Options
dialog box.
If a starting or ending time occurs after the last observation (Tlast) and
lambda z is estimable, lambda z is used to estimate the corresponding Y:
Y = exp(alpha Lambda-Z * t)
= exp(alpha Lambda-Z * tlast) * exp(Lambda-Z * (t-tlast))
= (predicted concentration at tlast) * exp(Lambda-Z * (t-tlast))
If a starting or ending time occurs after the last data observation and
lambda z is not estimable, the partial area will not be calculated.
If both the start and end times for a partial area occur after the last data
observation, then the log trapezoidal rule will be used regardless of the
selection made, because a logarithmic decline must be assumed in order
to obtain the predicted values.
If the start time for a partial area is before the last data observation and the
end time is after the last data observation, then the log trapezoidal rule
will be used for the area from the last data observation time to the end
time for the partial area, regardless of the selection made.
Partial area boundaries
There are limitations regarding partial area boundaries that will evoke an error
message from the software: The end time for the partial area must be greater
than the start time. Both the start and end time for the partial area must be at or
after the dosing time.
Therapeutic windows
For therapeutic windows, one or two boundaries for concentration values can
be given, and the program computes the time spent in each window deter-
mined by the boundaries and computes the area under the curve contained in
each window. To compute these values, for each pair of consecutive data
points, including the inserted point at dosing time if there is one, it is deter-
WinNonlin
Users Guide
238
9
mined if a boundary crossing occurred in that interval. Call the pair of time
values from the data set (t
i
, t
i+1
) and called the boundaries y
lower
and y
upper
.
If no boundary crossing occurred, the difference t
i+1
t
i
is added to the appro-
priate parameter TimeLow, TimeDur, or TimeHgh, depending on which win-
dow the concentration values are in. The AUC for (t
i
, t
i+1
) is computed
following the users specified AUC calculation method as described above in
section 3. Call this AUC*. The parts of this AUC* are added to the appropri-
ate parameters AUCLow, AUCDur, or AUCHgh. For example, if the concen-
tration values for this interval occur above the upper boundary, the rectangle
that is under the lower boundary is added to AUCLow, the rectangle that is
between the two boundaries is added to AUCDur and the piece that is left is
added to AUCHgh. This is equivalent to these formulae:
AUCLow = AUCLow + y
lower
* (t
i+1
t
i
)
AUCDur = AUCDur + (y
upper
y
lower
) * (t
i+1
t
i
)
AUCHgh = AUCHgh + AUC* y
upper
* (t
i+1
t
i
)
If there was one boundary crossing, an interpolation is done to get the time
value where the crossing occurred; call this t*. The interpolation is done by
either the linear rule or the log rule following the users AUC calculation
method as described above in section 3, i.e., the same rule is used as when
inserting a point for partial areas. To interpolate to get time t* in the interval
(t
i
, t
i+1
) at which the concentration value is y
w
:
Linear interpolation rule for time:
t* = t
i
+ [ (y
w
y
i
) / (y
i+1
y
i
) ] * (t
i+1
t
i
)
Log interpolation rule for time:
t* = t
i
+ [ (ln(y
w
) ln(y
i
) ) / ( ln(y
i+1
) ln(y
i
) ) ] * (t
i+1
t
i
)
The AUC for (t
i
, t*) is computed following the users specified AUC calcula-
tion method. The difference t* t
i
is added to the appropriate time parameter
and the parts of the AUC are added to the appropriate AUC parameters. Then
the process is repeated for the interval (t*, t
i+1
).
If there were two boundary crossings, an interpolation is done to get t* as
above for the first boundary crossing, and the time and parts of AUC are
added in for the interval (t
i
, t*) as above. Then another interpolation is done
from t
i
to t
i+1
to get the time of the second crossing t** between (t*, t
i+1
), and
Noncompartmental Analysis
Computational rules for WinNonlins noncompartmental analysis engine
239
9
the time and parts of AUC are added in for the interval (t*, t**). Then the
times and parts of AUC are added in for the interval (t**, t
i+1
).
The extrapolated times and areas after the last data point are now considered
for the therapeutic window parameters that are extrapolated to infinity. For
any of the AUC calculation methods, the AUC rule after tlast is the log rule,
unless an endpoint for the interval is negative or zero in which case the linear
rule must be used. The extrapolation rule for finding the time t* at which the
extrapolated curve would cross the boundary concentration y
w
is:
t* = (1/lambdaZ) * (alpha ln(y
w
)).
If the last concentration value in the data set is zero, the zero value was used
in the above computation for the last interval, but now ylast is replaced with
the following if Lambda z is estimable:
ylast = exp(alpha lambdaZ * tlast). (only if the last concentration was zero)
If ylast is in the lower window: InfDur and InfHgh values are the same as Dur
and Hgh values. If lambdaZ is not estimable, AUCInfLow is missing. Other-
wise, AUCInfLow = AUCLow + ylast / lambdaZ.
If ylast is in the middle window for two boundaries: InfHgh values are the
same as Hgh values. If lambdaZ is not estimable, InfLow and InfDur parame-
ters are missing. Otherwise: Use the extrapolation rule to get t* at the lower
boundary concentration. Add time from tlast to t* into TimeInfDur. Compute
AUC* from tlast to t*, add the rectangle that is under the lower boundary into
AUCInfLow, and add the piece that is left into AUCInfDur. Add the extrapo-
lated area in the lower window into AUCInfLow. This is equivalent to:
t* = (1/lambdaZ) * (alpha ln(y
lower
))
TimeInfDur = TimeDur + (t* tlast)
AUCInfDur = AUCDur + AUC* y
lower
* (t* tlast)
AUCInfLow = AUCLow + y
lower
* (t* tlast) + y
lower
/ lambdaZ
If y
last
is in the top window when only one boundary is given, the above pro-
cedure is followed and the InfDur parameters become the InfHgh parameters.
If there are two boundaries and ylast is in the top window: If lambdaZ is not
estimable, all extrapolated parameters are missing; otherwise:
Use the extrapolation rule to get t* at the upper boundary concentration value.
Add time from tlast to t* into TimeInfHgh. Compute AUC* for tlast to t*, add
WinNonlin
Users Guide
240
9
the rectangle that is under the lower boundary into AUCInfLow, add the rect-
angle that is in the middle window into AUCInfDur, and add the piece that is
left into AUCInfHgh. Use the extrapolation rule to get t** at the lower bound-
ary concentration value. Add time from t* to t** into TimeInfDur. Compute
AUC** from t* to t**, add the rectangle that is under the lower boundary into
AUCInfLow, and add the piece that is left into AUCInfDur. Add the extrapo-
lated area in the lower window into AUCInfLow. This is equivalent to:
t* = (1/lambdaZ) * (alpha ln(y
upper
))
t** = (1/lambdaZ) * (alpha ln(y
lower
))
TimeInfHgh = TimeHgh + (t* tlast)
TimeInfDur = TimeDur + (t** t*)
AUCInfHgh = AUCHgh + AUC* y
upper
* (t* tlast)
AUCInfDur = AUCDur + (y
upper
y
lower
) * (t* tlast) + AUC** y
lower
* (t** t*)
AUCInfLow = AUCLow + y
lower
* (t* tlast) + y
lower
* (t** t*) + y
lower
/ lambdaZ
Computational details for pharmacokinetic parameters
Plasma data
Parameters that are estimated regardless of
z
estimation
C0 Initial concentration. Given only for bolus IV models. It is equal to the first observed con-
centration value if that value occurs at the dose time. Otherwise, it is estimated by back-
extrapolating from the first two concentration values according to the rules given under
Insertion of initial time points on page 234.
Dosing_time Time of last administered dose. This is assumed to be zero unless otherwise specified.
This is mainly used with steady-state data, which may code time as the time elapsed
since the first dose, or the elapsed time since the time of the first dose.
Tlag Tlag is the time prior to the time corresponding to the first measurable (non-zero) con-
centration. This is computed for plasma extravascular models and all urine models.
Tmax Time of maximum observed concentration. For non-steady-state data, the entire curve is
considered. For steady-state data, Tmax corresponds to points collected during a dosing
interval.
Cmax Maximum observed concentration, occurring at Tmax.
Tlast Time of last measurable (non-zero) concentration.
Noncompartmental Analysis
Computational rules for WinNonlins noncompartmental analysis engine
241
9
Parameters that are estimated when
z
is estimated
Parameters that are extrapolated to infinity are computed two ways. One
extrapolation is based on the last observed concentration, while the second
extrapolation is based on the last predicted concentration, where the predicted
value is based on the linear regression performed to estimate
z
.
Clast Concentration corresponding to Tlast.
AUClast Area under the curve from the time of dosing (Dosing_time) to the last measurable con-
centration.
AUCall Area under the curve from the time of dosing (Dosing_time) to the time of the last obser-
vation. If the last concentration is non-zero AUClast=AUCall. Otherwise, AUCall will be
greater than AUClast as it includes the additional area from the last measurable concen-
tration down to zero.
AUMClast Area under the moment curve from the time of dosing (Dosing_time) to the last measur-
able concentration.
MRTlast Mean residence time from the time of dosing (Dosing_time) to the time of the last mea-
surable concentration. For non-infusion models: MRTlast = AUMClast/AUClast. For infu-
sion models: MRTlast = (AUMClast/AUClast) - TI/2.
No_points_
Lambda_z
Number of points used in the computation of
z
. If
z
cannot be estimated, zero.
AUC_%Back_
Ext
Computed for Bolus IV models: the percentage of AUCINF that was due to back extrapo-
lation to estimate C(0). If C2<C1, the C(0) is estimated by log-linear regression of the first
two time points; otherwise, C(0) is set to C1.
Rsq Goodness of fit statistic for the terminal elimination phase.
Rsq_adjusted Goodness of fit statistic for the terminal elimination phase, adjusted for the number of
points used in the estimation of
z
.
Corr_XY Correlation between time (X) and log concentration (Y) for the points used in the esti-
mation of
z
.
Lambda_z First order rate constant associated with the terminal (log-linear) portion of the curve.
This is estimated via linear regression of time vs. log concentration.
Lambda_z_lower Lower limit on Time for values to be included in the calculation of
z
.
WinNonlin
Users Guide
242
9
Lambda_z_upper Upper limit on Time for values to be included in the calculation of
z
.
HL_Lambda_z
Terminal half-life
AUCINF AUC from the time of dosing (Dosing_time) extrapolated to infinity.

AUCINF/D AUCINF divided by the administered dose.
AUC_%Extrap Percentage of AUCINF that is due to extrapolation from Tlast to infinity =
AUMC_%Extrap Percent of AUMCINF that is extrapolated.
=
Vz, Vz/F**
(see note below)
Volume of distribution based on the terminal phase.
Cl, Cl/F **
(see note below)
Total body clearance for extravascular administration.
=Dose/AUCINF
AUMCINF Area under the first moment curve (AUMC) extrapolated to infinity.
MRTINF Mean residence time (MRT) extrapolated to infinity for non-infusion models.
MRTINF Mean residence time (MRT) extrapolated to infinity for infusion models.
Steady-state
Tau The (assumed equal) dosing interval for steady-state data.
( )
=
ln 2

Z
= + AUClast
Clast
Z

AUCINF AUClast
AUCINF
100

AUMCINF AUMClast
AUMCINF
100

Dose
AUCINF
Z

=
AUMCINF
AUCINF
( ) =
AUMCINF
AUCINF
TI
2
Noncompartmental Analysis
Computational rules for WinNonlins noncompartmental analysis engine
243
9
Tmin For steady-state data: time of minimum concentration based on samples collected dur-
ing a dosing interval.
Cmin For steady-state data: the minimum concentration between 0 and Tau (at Tmin).
Cavg For steady-state data: computed as AUC(0-Tau) divided by Tau.
%_Fluctuation For steady-state data: computed as 100*(Cmax-Cmin)/Cavg, where Cmin and Cmax
were obtained between 0 and Tau.
V
SS
For non steady-state or steady-state data: an estimate of the volume of distribution at
steady state (not computed for model 200), equal to: MRTINF*Cl.
Accumulation
Index
Clss, Clss/F For steady-state data: an estimate of the total body clearance.
Cmax For steady-state data: the maximum observed concentration between 0 and Tau.
MRTINF Mean residence time (MRT) extrapolated to infinity. For steady-state data, non-infusion
models:
=
MRTINF Mean residence time (MRT) extrapolated to infinity. For steady-state data, infusion
models:
=
V
z
, V
z
/F For steady-state data:
=
Dose
AUC
0

|
AUMC
0

AUCINF AUC
0

( ) +
AUC
0

-----------------------------------------------------------------------------------
AUMC
0

AUCINF AUC
0

( ) +
AUC
0

-----------------------------------------------------------------------------------
T1
2
------
=

Dose
AUC
Z


0
WinNonlin
Users Guide
244
9
Note: For extravascular models the fraction of dose absorbed cannot be estimated,
therefore Volume and Clearance for these models are actually Volume/F or
Clearance/F where F is the fraction of dose absorbed.
Urine data
Data structure
Noncompartmental analysis for urine data requires the following input:
Starting and ending time of each urine collection interval
Urine concentrations
Urine volumes
From this data WinNonlin computes the following variables for the analysis:
Midpoint of each collection interval
Excretion rate for each interval (amount eliminated per unit of time) =
(Concentration * Volume) / (Ending time - Starting time)
Parameters that are estimated regardless of Lambda-Z estimation
Dosing_time Time of the last administered dose. This is assumed to be zero
unless otherwise specified.
Tlag Time prior to the time corresponding to the first measurable (non-
zero) concentration. This is computed for all urine models.
Tmax_Rate Midpoint of collection interval associated with the maximum
observed excretion rate.
Max_Rate Maximum observed excretion rate.
Mid_Pt_last Midpoint of collection interval associated with last measurable
rate.
Rate_last Last measurable rate.
AURC_last Area under the urinary excretion rate curve from time 0 to the last
measurable rate.
Amount_Recovered Cumulative amount eliminated.
(Concentration * Volume)
Noncompartmental Analysis
Computational rules for WinNonlins noncompartmental analysis engine
245
9
Parameters that are estimated when
z
is estimated.
The following parameters are calculated only when
z
is estimated. All asso-
ciated extrapolations are done two ways: 1) based on the last observed con-
centration, and 2) based on the last predicted concentration.
Vol_UR Sum of Urine Volumes
Percent_Recovered 100*Amount_Recovered/Dose
AURC_all Area under the urinary excretion rate curve from time 0 to the last
rate. This equals AURC_last if the last rate is measurable.
No_points_lambda_z Number of points used in the computation of
z
.
Rsq Goodness of fit statistic for the terminal elimination phase.
Rsq_adjusted Goodness of fit statistic for the terminal elimination phase, adjusted
for the number of points used in the estimation of
z
.
Corr_XY Correlation between time (X) and log concentration (Y) for the points
used in the estimation of
z
.
Lambda_z Lambda z. First order rate constant associated with the terminal (log-
linear) portion of the curve. This is estimated via linear regression of
time vs. log concentration.
Lambda_z_lower Lower limit on Time for values to be included in the calculation of
z
.
Lambda_z_upper Upper limit on Time for values to be included in the calculation of
z
.
HL_Lambda_z
Terminal half-life
AURC_INF Area under the urinary excretion rate curve extrapolated to infinity.
AURC_%Extrap Percent of AURC_INF that is extrapolated.
( )
=
ln 2

Z
WinNonlin
Users Guide
246
9
247
Chapter 10
Compartmental Modeling
Using WinNonlins library of compiled and ASCII
models
Compartmental modeling setup in WinNonlin involves:
1. Loading the model
2. Model properties
3. Output
See WinNonlin Model Libraries on page 573 for details on each compart-
mental model.
Loading the model
The WinNonlin mode library contains two types of models: one is compiled
into machine language; the other is stored in ASCII text.
To load a model:
1. Open the data set to which the model will be fit.
2. Click on the PK/PD/NCA Analysis Wizard button on the tool bar, or choose
Tools>PK/PD/NCA Analysis Wizard from the WinNonlin menus.
3. If there is more than one workbook open in WinNonlin, make sure that the
input data set is selected in the data set field at the top of the dialog.
Note: Hidden data sets do not show in the list box. Therefore, if the data set to be
used for modeling has been hidden, it must first be unhidden.
WinNonlin
Users Guide
248
10
4. Select the type of model to load from among the following.
Table 10-1. WinNonlin model types
Model type Description
Models for Noncom-
partmental Analysis
Support for blood (plasma) or urine data for IV infusion, IV bolus, and
first-order inputs.
Pharmacokinetic
models
WinNonlin includes nineteen pharmacokinetic (PK) models, including
1 to 3 compartment models with 0
th
or 1
st
order absorption, with or
without a lag time to the start of absorption.
Pharmacodynamic
models
WinNonlin includes eight pharmacodynamic (PD) models, including
variations on Emax and Sigmoid Emax models.
PK/PD link models WinNonlin's pharmacokinetic/pharmacodynamic (PK/PD) link mod-
els can use any combination of compiled PK and PD models. They
treat the pharmacokinetic parameters as fixed and generate concen-
trations at the effect sites to be used by the PD models.
Indirect response
models
WinNonlin provides four indirect response models, based on mea-
sured drug effect (inhibition or stimulation of response) and parame-
ters defining either the build-up or dissipation of that effect. These
models can be based on any WinNonlin PK model, and are available
only as compiled models.
Michaelis-Menten
models
WinNonlin provides four Michaelis-Menten (saturable elimination)
models, which are stored as ASCII library files in WIN-
NONLN\LIB\MM.LIB.
Compartmental Modeling
Model properties
249
10
Note: Only one model may be loaded in WinNonlin at a time.
5. If Pharmacokinetic or Pharmacodynamic modeling is selected, specify
whether to use an ASCII or a Compiled model. Compiled models run faster.
6. Click Next.
7. Select the specific model or, for ASCII models, model file and number, and
any associated settings. See also Loading an existing ASCII user model on
page 300 and Using compiled user models in a command file on page 307.
8. Click Next.
9. For compiled user models, it is necessary to enter the number of algebraic and
differential equations (if any; else, un-check this option) in the model, and
enter each estimated and secondary parameter. To ascertain this information,
look at the code from which the user model .DLL was compiled.
10. The Selection Summary dialog appears, with a description of the model. Click
Finish to load the selected model.
Model properties
Once the model has been loaded as described under Loading the model on
page 247, some or all of the following information must be supplied:
Data variables
Model parameters and initial parameter estimates
Dosing regimen (when appropriate)
Simultaneous PK/PD
link models
WinNonlin provides a library of link models that simultaneously fit PK
and PD data. Each includes a different PK model combined with PD
model 105. These models are stored as ASCII library models in
WINNONLN\LIB.
User Models Custom models can be written and saved to an ASCII text file, or
compiled using C++ or FORTRAN, then loaded into WinNonlin using
this option.
Command Files Command files can load ASCII or compiled user models.
Table 10-1. WinNonlin model types (continued)
Model type Description
WinNonlin
Users Guide
250
10
Model options to set the output types, computational algorithms and pre-
ferred units
Data variables
Compartmental Modeling requires that the data variables be selected before
any other settings are made.
To specify the roles of data columns in the model:
1. Select the X (or independent) variable in the Variables list and drag it to the
X-Variable field.
2. Select the Y variable (or dependent), and drag it to the Y-Variable field.
3. Simulations: No Y-variable is needed for simulations; instead check the Sim-
ulate Data check box.
4. Select Sort Variable(s) (optional) that identify individual data profiles, for
example, Subject and Treatment for a crossover study. A separate analysis
will be done for each level of the sort variables.
5. Select Carry Along Variables (optional) to include additional variables in the
analysis output. For example, Study Number or Gender might be included as a
carry-along variable to make it available for post-modeling analyses.
6. Select a Function Variable (optional). When fitting multiple functions, the
function variable tells WinNonlin which data observations go with which
function. For example, the data set may include data on two compartments
for example, plasma and urine. The function variable might have the value 1
for observations belonging to the plasma data, and a value of 2 for the data
observations belonging to the urine data.
Note: The data observations corresponding to the first (sorted) value of the function
variable will be used with the first function; those corresponding to the second
value are used with the second function, etc.
Model parameters
All iterative estimation procedures require initial estimates of the parameters.
For some types of models WinNonlin is capable of producing these initial
estimates; for others, initial estimates are required.
Compartmental Modeling
Model properties
251
10
For single-dose compiled PK models, PD models, or PK/PD link models,
WinNonlin can compute initial estimates using curve stripping. For all other
situations, the user must supply initial estimates or provide boundaries to be
used by WinNonlin to create initial estimates via grid search.
Initial estimates and parameter boundaries are specified through the Model
Parameter tab of the Model properties dialog.
To set up the initial parameter estimates:
1. Select Model>Model Parameters from the menus or click on the Model
Parameters tool bar button. The Model Parameter tab of the Model Proper-
ties dialog appears.
2. Specify the type of Parameter Calculation. The options are:
User Supplied Initial Parameter Values. Enter the initial estimates in
the column labeled Initial.
WinNonlin Generated Initial Parameter Values. When WinNonlin
Generated Initial Parameter Values has been selected in the Parameter
Calculation group box, and WinNonlin Bounds in the Parameter Bound-
aries group box, WinNonlin will curve strip for initial estimates then pro-
duce boundaries on the model parameters for model fitting. In this case, if
curve stripping fails, the program will terminate, as WinNonlin will be
unable to grid search for initial estimates.
For WinNonlin Generated Initial Parameter Values and User-Sup-
plied Bounds WinNonlin will do curve stripping then grid search
if that fails.
Propagate Final Estimates. The Propagate Final Estimates option is
available when sort keys are being used. When Propagate Final Estimates
is chosen, initial estimates are input, or calculated only for the first sort
level. The final estimates from each sort level are used as the initial esti-
mates for each successive level. Initial estimates and boundaries entered
for profiles other than the first profile will be ignored.
3. Specify the Parameter Boundaries. Parameter boundaries are used not only as
a basis for grid searching but also during modeling. The values input for
Lower and Upper limit the range of values that the parameters can take on
during the model-fitting process. This can be very valuable if the parameter
values become unrealistic or the model won't converge. It is generally recom-
mended that boundaries be routinely used. When they are used, every param-
WinNonlin
Users Guide
252
10
eter must be given bounds and both Upper and Lower must be specified. The
options are:
User Supplied Bounds. Enter the bounds in the columns labeled Lower
and Upper.
WinNonlin Bounds. WinNonlin establishes bounds for the parameters.
Do Not Use Bounds. No bounds are specified for the modeling.
4. When all values have been set, click Apply (to leave the dialog open and Pro-
ceed to the Dosing regimen) or OK (to close the dialog).
5. The Save and Load buttons can be used to store the parameter settings in an
external ASCII text file for future re-use.
Multiple sort levels
If the data has one or more sort variables, initial estimates for each level of the
sort variable(s) must be provided unless Propagate Final Estimates has been
selected.
The same method of parameter calculation and type of parameter boundaries
must be used for all sort levels.
To copy cells within the Model Parameters data grid:
1. Select (highlight) the cells to copy.
2. Click Copy.
3. Highlight the first cell of the destination.
4. Click Paste.
To copy model parameter information from the first profile to the remaining profiles:
1. Select (highlight) the cells for the first profile with the mouse. Note that the
cursor becomes a small black cross when held in the lower right-hand corner
of this selection. This is called the handle.
2. Press and hold down the left mouse button when this black cross appears.
3. Drag the handle over the target cells (to the bottom of the grid).
4. Release the mouse button.
Compartmental Modeling
Model properties
253
10
To copy data from outside the Model Parameters data grid:
1. Copy data to the clipboard prior to opening the Model Parameters dialog box.
2. Open the Model Parameters dialog box.
3. Select the first cell of the destination.
4. Click on the Paste button.
Note: The Load and Save buttons in the dialog can be used to save the parameter
values and settings to an external ASCII file and to reload settings for a model
fitting. The structure of this file (.ParmFile) is described in the chapter on
Scripting. See Special file formats on page 502.
Recommendations for initial parameter estimates
The use of boundaries (either User supplied or WinNonlin supplied) is
recommended.
When the WinNonlin Parameters option is selected for any model other
than a compiled WinNonlin model (i.e., grid searching is requested),
boundaries, either user supplied or WinNonlin supplied, are required.
WinNonlin only utilizes curve stripping if the data corresponds to admin-
istration of a single dose of drug. If multiple dose data is being fit to a
model in WinNonlin's library of models, and WinNonlin Parameters is
selected, a grid search is performed to obtain initial estimates. In this case,
boundaries are required.
For linear regressions, Method 3 (Gauss-Newton (Hartley)) and Do not
use bounds are recommended.
The grid used in grid searching includes three values for each parameter.
Thus, if four parameters are to be estimated, the grid will be comprised of
3
4
= 81 possible points. The point on the grid associated with the smallest
sum of squares is used as an initial estimate for the estimation algorithm.
Note that this option has been added for convenience, but it may dramati-
cally slow down the parameter estimation process if the model is defined
in terms of differential equations.
If the data are to be fit to a micro constant model, WinNonlin will perform
curve stripping for the corresponding macro constant model then use the
macro constants to compute the micro constants. It is still recommended
WinNonlin
Users Guide
254
10
that the lower and upper boundaries be specified, even when WinNonlin
is computing the initial estimates.
When the Gauss-Newton method is used to estimate the parameters
(METHODS 2 and 3), the boundaries are incorporated by applying a nor-
mit transform to the parameter space. With the Nelder-Mead option
(METHOD 1), the residual sum of squares is set to a large number if any
of the parameter estimates go outside the specified constraints at any iter-
ation, which forces the parameters back within the specified bounds.
Unlike the linearization methods, the use of bounds does not affect
numerical stability when using the Nelder-Mead simplex option. The use
of bounds with Nelder-Mead will, however, keep the parameters within
the bounds. The use of bounds (either user-supplied or WinNonlin sup-
plied) is always recommended with the Gauss-Newton methods.
Unless No Bounds is specified, and initial estimates have been entered by
the user or derived by WinNonlin, WinNonlin will automatically compute
bounds.
Dosing regimen
WinNonlin uses constants to store dosing information, including the number
of doses, amount of the dose(s), and dosing time(s). These are input as con-
stants. Each model requires specific information described below. For some
models the number of constants depends upon the number of doses adminis-
tered.
Model Number
Constant 1, 3-7, 11, 12 2, 9, 10, 19 8, 13, 14, 18
1 # of doses # of doses stripping dose
2 dose 1 dose 1 # doses
3 time of dose 1 start time 1 dose 1
4 dose 2 end time 1 time of dose 1
5 time of dose 2 dose 2 dose 2
6 (etc.) start time 2 time of dose 2
7 end time 2 (etc.)
8 (etc.)
9
Compartmental Modeling
Model properties
255
10
Where: NCON = the total number of constants to be specified by the user, and
nd = number of administered doses.
Note: Note that WinNonlin assumes that the time of the first dose is zero.
To enter dosing data:
1. Select Model>Dosing Regimen from the Model menu. The Dosing Regimen
tab of the Model properties dialog appears.
NCON (2*nd)+1 (3*nd)+1 (2*nd)+2
Model Number:
Constant 15, 16 17
1 bolus dose stripping dose
2 IV dose bolus dose
3 length of infusion IV dose
4 length of infusion
NCON 3 4
Model Number
Constant 1, 3-7, 11, 12 2, 9, 10, 19 8, 13, 14, 18
WinNonlin
Users Guide
256
10
Compiled models
Figure 10-1. The Dosing Regimen for compiled models
If a sort variable has been specified, the grid that appears in this dialog box
accommodates the constants required for all levels of the sort variable(s). The
same number of doses must be entered for each level of the sort variable.
Note: If a different number of doses for different levels of the sort variable is
needed, enter the largest number required, and enter doses of 0 for the extra
doses. Be sure to include time values in the data set beyond the actual time of
dose for these phantom doses.
ASCII models
When an ASCII model has been selected the Constant column contains the
names of elements of the constants array. Check the ASCII text in the Model
window to see how many and what constants to enter. See the Examples
Guide for an example using an ASCII model.
To enter dosing data for ASCII models:
1. Use the Insert Row, Add Row, and Delete Row buttons, if needed, to size the
grid appropriately for the number of constants required by the model.
Compartmental Modeling
Model options
257
10
2. If the data set includes multiple profiles, a row will be added for each profile.
3. Enter each constant value for each profile in the column labeled Value.
Figure 10-2. The Dosing Regimen tab for ASCII models
Copy, paste and fill-down in the Dosing Regimen data grid
Copy data (using the Windows clipboard) into the Dosing grid as well as from
the Dosing grid. Data from one profile can also be copied to others (using
copy down). All of these operations function the same on each tab of the
Model Properties dialog. See Model parameters on page 250.
Note: The Load and Save buttons in the dialog can be used to save the dosing values
and units to an external ASCII file and to reload settings for re-use. The struc-
ture of this file is described below in the chapter on Scripting. See Special
file formats on page 502.
Model options
The options for model output and computational algorithm appear on five tabs
in the Model Options dialog.
WinNonlin
Users Guide
258
10
To open the Modeling Options dialog:
1. Select Model Options from the Model menu or click on the Model Options
tool bar button. The Model Options dialog appears. This dialog has five
tabbed pages.
2. Select the desired options using the following tabs.
3. Click OK or Apply.
Output options
The defaults for output options are set via the Options command in the Tools
menu. The settings on the Output Options tab of the Model options dialog,
shown below, override the defaults only during the current WinNonlin model-
ing session.
Tab Description
Output options Select text, chart (plots) and/or workbook output forms
Weight Weighting of observation data. See also Weighting on page 325.
Title Text title to appear at the top of modeling output (text and charts)
PK settings Model fitting algorithm
Units Default output units for parameter estimates
Compartmental Modeling
Model options
259
10
Workbook
Tabular output in a workbook. For the contents of the workbook output, see
Output on page 265.
Chart
This option generates plots showing predicted values versus observed values
for each level of the ID variable.
Text
WinNonlin provides an ASCII (text) version of the output. This output con-
tains all modeling settings and output in one file. Modeling errors are also
reported in this file. This output is useful for reporting, and may also be very
useful for archiving analyses.
Page Breaks
Checking this box generates page breaks in the ASCII output.
Note: When a difficult model fit is to be attempted, enable the ASCII output and
check the output for modeling errors.
Weight
Compartmental modeling, there are four ways of assigning weights, other
than uniform weighting:
1. Weighted least squares weights by a power of the observed Y.
2. Iterative reweighting sets weights as the predicted value of Y to a speci-
fied power.
3. Include Weight as a variable on the data file allows specific weight val-
ues to be applied to each observed value.
4. Programming statements can be used to define weights as part of a user
defined model. See User Models on page 273.
See Weighting on page 325 for a detailed discussion of weighting schemes.
WinNonlin
Users Guide
260
10
To set the weighting scheme for a modeling session:
1. Open the Weight tab of the Model options dialog (Model>Model Options).
2. Select from the options discussed below, and click OK.
Weights on File in Column to read weights from a column on the data file.
Pre-Selected Scheme to select from among the most common schemes:
weight by 1/observed Y
weight by 1/observed Y2
weight by 1/predicted Y (iterative reweighting)
weight by 1/predicted Y2 (iterative reweighting)
Observed to the Power n (Weighted Least Squares) to specify weighted least
squares. Input the value of n in the box provided.
Predicted to the Power n (Iterative Reweighting) to specify iterative reweight-
ing. Input the value of n in the box provided.
Scaling of Weights
When weights are read from the data file or when weighted least squares is
used, the weights for the individual data values are scaled so that the sum of
the weights for each function is equal to the number of data values (with non-
zero weights). This scaling of the weights has no effect on the model fitting,
as the weights of the observations are proportionally the same. However, scal-
ing of the weights provides increased numerical stability. See Scaling of
weights on page 326 for further discussion.
Compartmental Modeling
Model options
261
10
To to turn off scaling of weights, check the No Scaling of Weights check box.
Title
Titles can be displayed at the top of each printed page. Unchecking the Title
check box suppresses the use of the titles without deleting the title text from
the Model options dialog.
Enter titles with multiple lines by using either CTRL + ENTER or SHIFT +
ENTER to move to the next line. The titles will be displayed on the screen for
graphical output generated by modeling. These titles appear on the workbook
output only when it is printed.
PK settings
The PK Settings tab of the Model options dialog (Model>Model Options)
provides control over the model fitting algorithm and related settings.
Minimization
Select among the 3 minimization methods:
Method 1: Nelder-Mead simplex
Method 2: Gauss-Newton with Levenberg and Hartley modification
Method 3: Gauss-Newton with Hartley modification
These methods are described in Model fitting algorithms and features of
WinNonlin on page 5. The use of bounds is especially recommended with
WinNonlin
Users Guide
262
10
Methods 2 and 3. When doing linear regression, use Method 3 and do not use
bounds.
Transpose final parameter table
If transposed output is selected (i.e., this option is checked), the Final Parame-
ters output table will show each parameter statistic in a separate column, as
shown in the upper window of Figure 10-3. A second worksheet, called Non-
transposed Final Parameters, will present each parameter in a separate row,
with one column per statistic. If the Transpose Final Parameters Table option
is not checked, the two worksheets will be reversed, with the Final Parameters
worksheet displaying non-transposed data, as shown in the lower window of
Figure 10-3. The second worksheet, called Transposed Final Parameters will
display the transposed version.
Figure 10-3. Example modeling output: transposed (upper) and non-transposed
(lower) Final Parameters.
The transposed form is particularly useful when creating final report tables.
This format may also be useful when summarizing a subset of the final
parameters using descriptive statistics.
Increment for partial derivatives
Nonlinear algorithms require derivatives of the models with respect to the
parameters. The program estimates these derivatives using a difference equa-
tion. For example:
Compartmental Modeling
Model options
263
10
where = the Increment multiplied by the parameter value.
Number of predicted values
This setting determines the number of points in the Predicted Data file. Use
this option to create a data set used to plot a smooth curve. The minimum
allowable value is 10 and the maximum is 10,000.
If the number of derivatives is greater than 0 (i.e., differential equations are
used), this command is ignored and the number of points is equal to the num-
ber of points in the data set.
For compiled models without differential equations the default value is 1000.
The default for user models is the number of data points in the original data
set. This value may be increased only if the model has only one independent
variable.
Note: To better reflect peaks (for IV dosing) and troughs (for extravascular, IV infu-
sion and IV bolus dosing), the Predicted Data file for the built-in PK models
includes dosing times, in addition to the concentrations automatically gener-
ated. For all three types of concentrations are generated at dosing times; in
addition, for infusion models, times are generated for the end of infusion.
When fitting or simulating multiple dose data the predicted value data curves
may be much improved by increasing the Number of Predicted Values.
Convergence criteria
Use this option to set the convergence criterion. The default is 0.0001. Con-
vergence is achieved when the relative change in the residual sum of squares
is less than the convergence criterion.
Mean square
The variance is normally a function of the weighted residual SS/df, or the
Mean Square. For certain types of problems, when computing the variance,
the mean square needs to be set to a fixed value.
F
P 1 ( )
--------------
F P 1 ( ) + ( ) F P 1 ( ) ( )

--------------------------------------------------------- =
WinNonlin
Users Guide
264
10
Iterations
Use this option to change the maximum number of iterations. For Methods 2
and 3, the default is 50. For Method 1, the default is 500.
For Method 1, each iteration is really a reflection of the simplex.
Model size
Use this option to alter the default memory requirements. Model size may
range from 1 to 64; the default size is 4.
Units
Specify the preferred units for output of modeling or simulation. The input
data (X-variable, Y-variable, dosing) must contain units to use this option.
WinNonlin performs appropriate conversions as needed.
To specify preferred units:
1. Select the Units tab of the Model options dialog.
2. Select the row with the appropriate parameter name. The default units are dis-
played in the Default column.
3. Enter the units in the Preferred column for that row. Alternately, click the
Units Builder button to construct and specify units in the Units Builder.
Compartmental Modeling
Running the model
265
10
4. In case of an error the parameters can be reset to their original setting by
clicking on the Reset to Defaults button.
5. The preferred units can be saved to a (*.TXT) file for later re-use, using the
Save and Load buttons.
Running the model
To start modeling:
1. Select Model>Start Modeling from the menus or click the Start Modeling
tool bar button.
Note: At some point during modeling, the Select Data for Modeling dialog box may
appear. This can occur when the original data set selected for modeling
becomes un-associated with the model. In this case, select the data set to be
used for the modeling, and click OK.
Stop modeling
To stop modeling:
1. Click on the Stop Modeling tool bar button.
Output
One of the examples from the Examples Guide is used here to discuss the
modeling output provided by WinNonlin. This example uses a pharmacoki-
netic (PK) model.
Note: This section is not intended as a statistical or PK text. It is meant to provide
guidance and references to aid in the interpretation of modeling output.
After Example 1 is run, up to three new child windows appear in the WinNon-
lin window. They are labeled:
PK Text
WinNonlin
Users Guide
266
10
PK Workbook
PK Chart
The Text Output window contains an ASCII form of the output. All of the
data in the PK Workbook is included in this ASCII output. This window will
only appear if ASCII output is selected on the Output Options tab in the Mod-
eling Options dialog box, or if there is an error in the model.
Note that these windows are named PK... because this was a pharmacoki-
netic model. Other analyses will, naturally, produce appropriately-named win-
dows.
Text (ASCII) output
The text output window contains a complete summary of the modeling for
this PK example.
Model Commands
The first page is a copy of the input commands created to run the model. If the
menus were used to define the model specifications, commands will appear
here that indicate that. If the model is defined in a user library, then the state-
ments that define the model are also printed. Those statements are equivalent
to a WinNonlin command file.
Minimization Process
The second page varies, depending on which method is used for minimiza-
tion. If a Gauss-Newton method is used (Methods 2 or 3), this page shows the
values of the parameters and the computed weighted sum of squared residuals
at each iteration. In addition, the following two values are printed for each
iteration:
RANK - Rank of the matrix of partial derivatives of the model parame-
ters. If the matrix is of full rank, RANK = # of parameters. If the RANK is
less than the number of parameters, then the problem is ill-conditioned.
That is, there is not enough information contained in the data to precisely
estimate all of the parameters in the model.
COND - Condition number of the matrix of partial derivatives. COND is
the square root of the ratio of the largest to the smallest eigenvalue of the
matrix of partial derivatives. If the condition number gets to be very large,
Compartmental Modeling
Output
267
10
say greater than 10e6, then the estimation problem is very ill-conditioned.
When using Methods 2 and 3, using bounds (LOWER and UPPER con-
straints) often helps reduce the condition number.
If the simplex algorithm is used, the second page only shows the parameter
values and the weighted sum of squares for the initial, final (best, or smallest,
sum of squares) point, and the next-to-best point.
Final Parameters
The third page of the output lists the parameter estimates, the asymptotic esti-
mated standard error of each estimate, and two confidence intervals based on
this estimated standard error. The confidence interval labeled UNIVARIATE
is the parameter estimate plus and minus the product of the estimated standard
error and the appropriate value of the t-statistic. The confidence interval
labeled PLANAR is obtained from the tangent planes to the joint confidence
ellipsoid of all the parameter estimates. For a complete discussion of the
UNIVARIATE and PLANAR confidence intervals see page 95 of Draper and
Smith (1981). The UNIVARIATE confidence intervals ignore the other
parameters being estimated, while the PLANAR confidence intervals take
into account the correlations among the parameter estimates. Only in the very
rare event that the estimates are completely independent (uncorrelated) will
the two confidence intervals be equal; usually the PLANAR intervals will be
wider than the UNIVARIATE intervals. Both are 95% confidence intervals.
The estimated standard errors and confidence intervals are only approximate,
as they are based on a linearization of the nonlinear model. The nearer the
model is to being linear, the better is the approximation. See Chapter 10 of
Draper and Smith (1981) for a complete discussion of the true confidence
intervals for parameter estimates in nonlinear models.
The estimated standard errors are valuable for indicating how much informa-
tion about the parameters is contained in the data. Many times a model will
provide a good fit to the data in the sense that all of the deviations between
observed and predicted values are small, but one or more parameter estimates
will have standard errors that are large relative to the estimate.
Variance-Covariance Matrix, Correlation Matrix, and Eigenvalues
Page four of the output shows the correlation matrix of the estimates and the
eigenvalues of the linearized form of the model. High correlations among one
or more pairs of the estimates indicate that the UNIVARIATE confidence lim-
its are underestimates of the uncertainty in the parameter estimates and,
WinNonlin
Users Guide
268
10
although the data may be well fit by the model, the estimates may not be very
reliable. Also, data sets that result in highly correlated estimates are often dif-
ficult to fit, in the sense that the Gauss-Newton algorithm will have trouble
finding the minimum residual sum of squares.
The eigenvalues are another indication of how well the data define the param-
eters. If the parameter estimates are completely uncorrelated, then the eigen-
values will all be equal. A large ratio between the largest and smallest
eigenvalue may indicate that there are too many parameters in the model.
Unfortunately, it is usually not possible to drop one parameter from a nonlin-
ear model. For discussion of the use of eigenvalues in the modeling process
see Belsley, et. al. (1980).
Residuals
Page five of the output lists the observed data, calculated predicted values of
the model function, residuals, weights, the standard deviations (S) of the cal-
culated function values and standardized residuals. Runs of positive or nega-
tive deviations indicate non-random deviations from the model and are
indicators of an incorrect model and/or choice of weights.
Also on page five are the sum of squared residuals, the sum of weighted
squared residuals, an estimate of the error standard deviation, and the correla-
tion between observed and calculated function values. Unlike the linear model
case, the correlation is not a particularly good measure of fit; for most prob-
lems it will be greater than 0.9, and anything less than 0.8 probably indicates
serious problems with the data and/or model. Two measures which have been
proposed for comparing competing models, AIC (Akaike, 1978) and SBC
(Schwarz, 1978), are also printed on page five.
If the data have been fit to any of the models in the built-in library with
extravascular or constant infusion input, area under the curve (AUC) is
printed at the end of page five. The AUC is computed by the linear trapezoidal
rule. If the first time value is not zero, then a pseudo time value of zero is gen-
erated, with an associated concentration of zero, in order that AUC is com-
puted from zero to the last time.
Note: Note that the AUC values may not be meaningful if the data were obtained
after multiple dosing or IV dosing (due to time 0 extrapolation problems).
Compartmental Modeling
Output
269
10
Secondary Parameters
If there are any secondary parameters, they, along with their estimated asymp-
totic standard errors, are printed on page six. The secondary parameters are
functions of the primary parameters whose estimates are given on page three
of the output. The standard errors of the secondary parameters are obtained by
computing the linear term of a Taylor series expansion of the secondary
parameters. As such, they represent about the third level of approximation and
must be regarded with caution.
Workbook output
A PK Workbook window contains summary tables of the modeling data, a
summary of the information in the ASCII output. These worksheets present
the output in a form that can be used for reporting and further analyses.
.
Table 10-2. Summary of PK worksheets
Item Contents
Initial Parameters Parameter names, initial values, and lower and upper bounds
for each level of the sort variables.
Minimization Process Iteration number, weighted sum of squares, and value for
each parameter, for each level of the sort variables.
Final Parameters Parameter names, units, estimates, standard error of the esti-
mates, CV%, univariate confidence intervals, and planar con-
fidence intervals for each level of the sort variables.
Dosing The dosing regimen specified for the modeling.
Correlation Matrix A correlation matrix for the parameters, for each value of the
sort variables.
Eigenvalues Eigenvalues for each level of the sort variables.
Condition Numbers Iteration number, rank and condition number for each value
of the sort variables.
Variance-Covariance Matrix A variance-covariance matrix for the parameters, for each
value of the sort variables.
Summary Table
a

The sort variables, X, Y, transformed X, transformed Y, pre-
dicted Y, residual, weight used, standard error of predicted Y,
standardized residuals, for each value of the sort variables.
For link models the Summary table also includes C
P
and C
e
.
For indirect response models, it also includes C
P
.
WinNonlin
Users Guide
270
10
Note: Note that the worksheets produced will depend on the type of analysis and the
model settings.
These output worksheets are presented together in one workbook window.
Use the tabs at the bottom of the window to select the worksheet to use. An
example is given below.
Diagnostics For each function and for the total, the following diagnostics
are provided: corrected sum of squared observations,
weighted corrected sum of squared observations, sum of
squared residuals, weighted sum of squared residuals, S
(estimate of residual standard deviation) and df, correlation
between observed Y and predicted Y, AIC and SC.
Differential Equations Values of the differential equations at each time on the data
set.
Partial Derivatives The value of the partial derivatives for each parameter at
each time point for each value of the sort variables.
Predicted Data Time and predicted Y for multiple time points, for each value
of the sort variables.
Secondary Parameters Secondary parameter name, units, estimate, standard error
of the estimate, and CV% for each value of the sort variables.
User Settings Title, model number, weighting used, minimization method
used, convergence criterion used, and the maximum number
of iterations allowed.
a. If there are no statements to transform the data, then X and Y will equal
X(obs) and Y(obs).
Table 10-2. Summary of PK worksheets (continued)
Compartmental Modeling
Output
271
10
Figure 10-4. Workbook output
Chart output
This PK analysis produces a chart window with five graphs for each level of
the sort variable:
X vs. Observed Y and Predicted Y plots the predicted curves as a function
of X, with the Observed Y overlaid on the plot. Used for assessing the model
fit.
Observed Y vs. Weighted Predicted Y plots weighted predicted Y against
observed Y. Scatter should lie close to the 45 degree line.
Weighted Predicted Y vs. Weighted Residual Y used to assess whether
error distribution is appropriately modeled throughout the range of the data.
X vs. Weighted Residual Y used to assess whether error distribution is
appropriately modeled across the range of the X variable.
Partial Derivatives plots the partial derivative of the model with respect to
each parameter as a function of the x variable. If f(x; a, b, c) is the model as a
function of x, based on parameters a, b, and c, then
df(x; a, b, c)/da, df(x; a, b, c)/db, df(x; a, b, c)/dc
are plotted versus x. Each derivative is evaluated at the final parameter esti-
mates. Data taken at larger partial derivatives are more influential than those
taken at smaller partial derivatives for the parameter of interest.
WinNonlin
Users Guide
272
10
Select a graph type using the tabs at the bottom of the window.
Figure 10-5. A sample PK Chart
273
Chapter 11
User Models
Creating custom models using WinNonlin
command language, FORTRAN, or C++
WinNonlin includes a library of standard PK and PK/PD models, detailed
under WinNonlin Model Libraries on page 573. In addition, WinNonlin
provides a flexible command language for creating more complex and custom
models. The commands can be saved in a user model. WinNonlin supports
two types of user models, ASCII user models and compiled user models.
ASCII models are created in a text window or a separate text file, then
loaded in WinNonlin. WinNonlin must parse the ASCII file to run the
model, so ASCII models do not run as quickly as compiled models.
Compiled user models are created and compiled using a Fortran or C++
compiler. As a result, WinNonlin need not parse the file; it simply calls
the compiled .DLL file.
A command file is made up of blocks of text, including a model block, and
other blocks specifying all or most of the information required to run the
model. The model can be an ASCII user model, a WinNonlin library model,
or a user compiled model.
Information that is fixed across modeling sessions, such as the number and
names of the model parameters, should be included with the model statements
to reduce the amount of information that must be supplied at run time. In gen-
eral, however, use variables to represent model quantities that may vary
across uses, to make each command file as general as possible.
Templates
Two user model templates are provided with WinNonlin: one for models that
include only algebraic equations and one for models that include differential
equations. Examples are also provided in the Examples Guide. All ASCII
WinNonlin
Users Guide
274
11
models in WinNonlins libraries, in the WinNonlin LIB directory, may be used
as examples and starting templates. For additional examples, see Pharmacok-
inetic and Pharmacodynamic Data Analysis: Concepts and Applications, sec-
ond edition, by Gabrielsson and Weiner.
Model structure
The following questions need to be considered for custom models:
1. Is the model(s) expressible as an algebraic nonlinear function, a system of
differential equations, or a combination of algebraic functions and differ-
ential equations?
2. Does the data set contain all the necessary information, or will new vari-
ables which are functions of the input data need to be created?
3. Does the model change according to values of the data or estimated
parameters?
4. How many parameters and constants will be needed to define the model?
5. If the model uses differential equations, what are the initial values?
Each user model must begin with the key word MODEL. It can be followed by
a number to identify the model, such as MODEL 5. The model ends with the
command EOM which indicates the end of the model definition.
Examples of algebraic nonlinear models
Examples of differential equations
Y a *t ( ) exp =
( ) ( )
Y a t b t = + cos sin
dz dt k t =
1
dz dt k w k y =
1 2
User Models
Model structure
275
11
The minimum information needed to define a model is a MODEL statement, a
FUNCTION block, and an EOM statement. If a model is stored in a user
library it must also have a model number.
Any of the above seven groups of commands can be specified with only the
first four characters of the group name. However using the entire name will
also work. For example, either
FUNCTION 1
or FUNC 1
could be used to signify that Function 1 is being defined.
Table 11-1. Model structure
Example:
MODEL
TRANSFORM
statements
END
Statements to alter data values before the functions or differential
equations are fit go here.
COMMAND
statements
END
This block contains the WinNonlin commands which load the model.
TEMPORARY state-
ments
END
Commands to create variables that will be used in more than one
block (i.e. global variables), go here.
FUNCTION
statements
END
A function block must be included for each different model or equa-
tion for which corresponding data are available.
START
statements
END
Initial conditions for the system of the differential equations are placed
in this section.
DIFFERENTIAL
statements
END
If the model is a function of one or more differential equations, state-
ments defining the differential equations are included in this section.
SECONDARY state-
ments
END
All secondary parameters, which are parameters defined as functions
of the model parameters, are specified here.
EOM
WinNonlin
Users Guide
276
11
Note: Each of the seven groups of commands (or blocks) must end with an END
statement. In addition, an EOM (end of model) statement must follow the last
group of commands. These blocks may appear in any order.
The model file can be created in any of three ways:
1. Select File>New, and then select Text and click OK. This creates the
model in a text file within WinNonlin.
2. Type the model statements into a text file outside of WinNonlin and load
it from an external file.
3. Select the PK/PD/NCA Analysis Wizard and choose User Model. Then
specify Create a New ASCII Model. This method utilizes one of the
built-in templates for creating models.
Model components
Each block except the COMMAND block can include WinNonlin program-
ming language statements in addition to the special variables WinNonlin
makes available to access data and parameter estimates. These are explained
at the end of this chapter.
Transform block
This group of statements is called once for each observation, prior to starting
the estimation procedure. This allows defining the dependent variable (Y) or
the weight (WT) as a function of other variables on the input data set. Inde-
pendent variables can also be derived or transformed here. See the files
EXP3.CMD, EXP4.CMD, and EXP9.CMD, stored in the \EXAMPLES directory for
examples of the use of the TRANSFORM block.
Note: When the variable WT is specified in a model file, this specification will over-
ride any weighting specified via the Data Variables dialog box.
If an existing variable is transformed in the transform block, both the original
values and the transformed values will be included in the output grids. New
variables created in the transform block will not be included. For example, if a
data set has the variables X8 and Y, and the following statements are included:
User Models
Model components
277
11
X8 = SQRT(X8)
Y=log(Y)
then the output worksheet will include the variables X8 and Y (the trans-
formed values), and X8(Obs) and Y(Obs), (the original values). However, if
the statement included:
LOGY = log(Y)
then the variable LOGY will not be included in the output worksheet.
Command block
The WinNonlin commands which are also used in command files and dis-
cussed in chapter 4 of this manual can be used in the COMMANDS block of a
user model. This group of commands is included in the library along with the
model to define such values as NPAR (the number of parameters) and NSEC
(the number of secondary parameters). Specifying commands in this block
can reduce the amount of information that must be specified at run time.
The COMMAND - END block allows WinNonlin commands to be associated
with a model. Following the COMMANDS statement, any WinNonlin com-
mand such as NPARAMETERS, NCONSTANTS, PNAME, etc. may be
given.
A
The COMMAND section concludes with an END statement.
The following WinNonlin commands are related to model definition. They
can be placed in the COMMAND block of the model or in a WinNonlin com-
mand file.
Note: Any command that is fixed should be placed in the COMMAND block, other-
wise the command should be specified at run time using the menu commands
or tool bar buttons, or it may be included in a WinNonlin command file.
The NPARAMETERS command specifies the number of parameters that will
be estimated. The INITIAL, LOWER and UPPER commands must have as
many values specified as indicated by the NPARAMETER command.
A. See the list of commands given in chapter 4 of this manual.
WinNonlin
Users Guide
278
11
Note: The NCONSTANTS command specifies the number of constants to be used
in the model. Each constant must be initialized either using the CONSTANTS
command or via the WinNonlin interface.
Some models, such as the multiple dosing models in WinNonlin's library, use
a variable number of constants. In this case, the NCONSTANTS and the
CONSTANTS commands should not go in the MODEL file, but should be
specified at run time using the menu commands or tool bar buttons, or they
may be included in a WinNonlin command file.
The NDERIVATIVES command tells WinNonlin the number of differential
equations in the model.
The NFUNCTIONS command specifies the number of different equations
that have observations associated with them. These functions can share some
of the same parameters. The data are organized so that the first function's data
come first, followed by the next function's data and so on. The NFUNC-
TIONS command must have an argument that is the number of different mod-
els or equations with corresponding data, or the number of FUNCTION
blocks.
When more than one function is defined (NFUN>1) it is important to delin-
eate for WinNonlin which data observations belong to each function. This is
most easily done by using a FUNCTION variable through the Data Variables
dialog box. To indicate a FUNCTION variable when writing a command file,
use the FNUMBER command. An example is shown below.
Example - Command block
COMM
NPARAMETER 5
PNAMES K01 K10 K12 K20 VOLUME
NFUNCTIONS 1
NCONSTANTS 2
END
User Models
Model components
279
11
In this example, the data set has data for two different functions, for example,
plasma and urine data. The observations which belong to the first function
have a type of 1, and the observations which belong to the second function
have a type of 2. The variable TYPE will be specified as the FUNCTION
variable in the Data Variables dialog box.
Note: The NOBSERVATIONS command provides a means to specify the number of
observations that belong to each function. In the example shown above, it is
possible to include the statement:
NOBSERVATIONS 6 5
However, this method is not recommended. The NOBSERVATIONS com-
mand is included for compatibility with PCNonlin. Note that using this state-
ment requires accurately counting the number of observations for each
function, and updating this statement if the number of observations changes.
It is recommended using a FUNCTION variable rather than the NOBS com-
mand.
The NSECONDARY command indicates the number of secondary parame-
ters to be computed. A secondary parameter is estimated using the values of
the estimated model parameters in a function that defines the secondary
parameters.
WinNonlin
Users Guide
280
11
The PNAMES, and SNAMES, commands are used to name the primary and
secondary parameters. These names are used as labels in the output, and may
be used in programming statements. The command is followed by the names
in single quotes separated by blanks or commas.
The DNAMES command may be used to define names for the columns in the
data file. These names can then be used in the model definition statements to
refer to input data columns.
The PUNIT and SUNIT commands may be used to supply units for the pri-
mary and secondary parameters. For user models, units are not manipulated
but are carried along to the output.
Temporary variables block
Variables defined in the temporary block are global variables; that is, they
may be used in any block. This optional group of statements can be used to
Example of a secondary parameter: Clearance
COMMANDS
NSEC 1
END
SECO
S(1)=0.693/K10
END
Example of PNAMES, DNAMES, PUNITS, SUNITS and
SNAMES Commands
COMM
DNAMES SUBJECT, FORM, TIME, CONC
NPARM 3
PNAMES 'K10', 'VOLUME', 'K1E'
PUNIT 1/hr, ml,1/hr
NSEC 1
SNAMES 'CL'
SUNIT ml/hr
END
SECO
CL =0.693/K10
END
User Models
Model components
281
11
define global variables, which may make it easier to define the functions, dif-
ferential equations and secondary parameters.
For example, it may be better to provide input for a given model as micro con-
stants but use macro constants in the model definition statements and report
these macro constants as secondary parameters. If these macro constants are
defined in the Temporary block, they will only need to be defined once, and
used in both the FUNCTION and SECONDARY blocks, rather than being
defined in both the FUNCTION and SECONDARY blocks.
Temporary variable names can be eight (8) characters long. They may contain
letters, numbers, or underscores, but must start with a letter.
Note: Temporary variables that are only used within a given group of statements can
be defined within that group of statements. Temporary variables that are used
in more than one block of statements must be placed in the TEMPORARY
VARIABLES group.
Function block
When the model is fitting multiple functions that share a parameter or param-
eters it may be more efficient statistically to model the functions simulta-
neously. For example, when modeling both plasma and urine data for a one
compartment IV bolus model it would be more efficient to model these simul-
taneously, since the equations for the plasma and urine compartments both
involve K10. Usage:
FUNCTION N
statements
END
This group of statements defines the model to be fit to a set of data. The letter
N denotes the function number. A function block must appear for each of the
NFUN functions. The variable F should be assigned the function value. The
function may be:
an algebraic function (e.g.: F= (D/V) * exp(-K10 * t)), or
a function of a differential equation or differential equations defined in
one or more differential blocks (e.g.: F=Z(1), or F= Z(1) + 3*Z(2)).
WinNonlin
Users Guide
282
11
The number of function blocks is equal to the number of simultaneous func-
tions to be fit, that is, the number of functions that have data associated with
them.
It is important to delineate which observations in the data file belong to which
functions. This is generally most easily done using a variable on the data file
whose values correspond to the function numbers. This would be referred to
as a Function variable. (See Model initialization commands on page 312. )
Weights can also be defined in this section by setting WT equal to the weight
associated with the observation.
Starting values block
When a model is defined by a system of one or more differential equations
(i.e., NDER > 0), the starting values corresponding to each differential equa-
tion in the system must be specified. In most instances, this will be the value
of the dependent variable when X = 0. If the initial values do not occur at X =
0, then X should also be assigned accordingly. The actual starting values
should be assigned to elements of the Z array. Note that the initial conditions
could be estimated as parameters, such as C0 below.
Example - Function Blocks
FUNC 1 <--An algebraic function
F=A*EXP(-ALPHA*T)
END
FUNC 2 <--A differential equation
F=Z(1)
END
Example - Starting Values
START
Z(1)=C0
Z(2)=0
END
User Models
Model components
283
11
Differential equation block
This set of statements is used (when NDER > 0) to define a system of differ-
ential equations which define a model. DZ(1), DZ(2), etc. should be used to
define the set of differential equations.
Secondary parameters block
In many instances, interest is not in the model parameters per se, but in func-
tions of the model parameters. For example, the model may be defined in
terms of the micro constants, but what really is of interest is clearance. This is
easily handled by defining clearance as a function of the model parameters in
the secondary block.
When secondary parameters are to be estimated (NSEC > 0), they are defined
using this group of statements.
S(1) denotes the first secondary parameter, S(2) the second, etc. If an SNAME
command has been included, these aliases may be used in the definition of
these parameters in the secondary block.
Example - Differential Equation Block
DIFF
DZ(1)=-K12*Z(1)
DZ(2)=K12*Z(1) - K20*Z(2)
END
Example - Secondary Block
SECO
REMARK Note that D and AUC must be defined
S(1) = D/AUC
END
WinNonlin
Users Guide
284
11
Note: REMARKS can be placed within or between any of the above groups of state-
ments. These lines must begin with REMA (or REMARK). Individual lines
are marked as remarks. It is not possible to begin a line with REMA and then
enter comments that wrap around to more lines. The other lines would also
need to begin with REMA or REMARK.
WinNonlin variables
WinNonlin provides access to both input data and parameter estimates during
the model-fitting process. This allows creating adaptive modelsthat is,
models which can be altered based on the current data observation or value of
the parameter estimates.
The data and parameters can be accessed by using the variable names
described below. Examples of their use in defining models will be shown later
in this chapter.
Example - Secondary Block, using SNAME
COMM
NSEC 1
SNAME CL
END
SECO
CL = D/AUC
END
DTA(N) This array contains values of all variables (columns) on the input
data file (in the same order) corresponding to the current observa-
tion. Thus, for a given data observation,
DTA(1) = value of 1st variable (column)
DTA(2) = value of 2nd variable (column) etc.
These variables can also be accessed using DNAMES.
F The value of the function evaluated at the current observation, and
current values of the parameters to be estimated, P(1), P(2), etc.
User Models
WinNonlin variables
285
11
Note: When the variable WT is specified in a model file, this specification will over-
ride any weighting specified via the Data Variables dialog box.
Variable names
It may be advantageous to create other variables to define the model or
parameters. These may be created as global variables in the Temporary block
or as temporary variables within any block.
Variable names can be 1-8 letters, numbers and/or underscores in length but
must start with a letter. None of the variables can be subscripted (e.g.,
TIME(2) is invalid).
Reserved variable names
Any additional variables which are defined must not have names beginning
with any WinNonlin keyword (e.g., TRAN, TEMP, FUNC, SECO, STAR,
DIFF, COMM, OBJF, END, or EOM) or with any WinNonlin command or
data array (e.g., CARR, CON, DTA, DTAARRAY(i,j), DTIM, F, NCAR,
X Value of the independent variable at which the functions or differen-
tial equations are to be evaluated. This value is identical to
DTA(XNUM) (See the XNUM command, p. 56.) If the model is a
function of more than one independent variable, the independent
variables can be accessed via the DTA( ) array, or using DNAMES.
P(N) This array contains the current values of the parameters to be esti-
mated. These variables can also be accessed using PNAMES.
CON(N) This array contains the constants which have been input by the
user (e.g., dose).
Z(N) This array contains the current integrated values corresponding to
a system of differential equations. These values are computed by
WinNonlin (except when starting values for the system of differen-
tial equations are defined by the user).
DZ(N) This array contains the current values of the differential equations
evaluated at X, P( ) and Z( ).
S(N) This array contains the values of the estimated secondary parame-
ters. These variables can also be accessed using SNAMES.
WT This value corresponds to the weight assigned to the current obser-
vation.
WinNonlin
Users Guide
286
11
NDER, NCON, NOBS, NPARM, NPAU, NSEC, NTOT, NVAR, OBJFN,
OBSN, P, PAUC, STEA, X, XARRAY(j), YARRAY(j), WTARRAY(j), Z).
See also Commands, Arrays and Functions on page 621.
PNAMES, SNAMES, and DNAMES
The commands PNAMES, SNAMES, and DNAMES may be used in code to
define aliases for parameter names, secondary parameter names, constant
names, and columns on the data file.
The WinNonlin programming language
WinNonlin provides a flexible programming language to define models. It
provides control statements, mathematical functions and loop control. It is
possible to define new variables for easier programming.
The following pages describe the elements of the WinNonlin language.
Valid mathematical operators are +, -, *, **, and /. Expressions are evaluated
using standard operator precedence. Note that ** denotes exponentiation.
WinNonlin statements
GOTO
Action Transfers processing to a labeled statement.
Syntax GOTO label
Where label is the statement label of an executable statement in
the model file.
Remarks There should not be any blank spaces between GO and TO.
Example GOTO GREEN
LABEL
Action Denotes a label. Control is transferred here via a GOTO state-
ment.
Syntax The label must end with a colon (:).
Example GREEN:
IF THEN ELSE
User Models
The WinNonlin programming language
287
11
Action If expression is true, statements in the IF block are executed; if
expression is false, control is transferred to the next ELSE, ELSE
IF, or ENDIF statement at the same IF level.
Syntax IF expression THEN
Where expression is a logical expression.
Example IF I>4 THEN
GOTO GREEN
ELSE
GOTO BLUE
ENDIF
Remarks IF statements can be nested up to 10 deep with the default model
size (2), and up to 30 for model sizes 3 or greater.
ELSE
Action Marks the beginning of an ELSE block.
Syntax ELSE
This statement is optional.
Remarks An ELSE block consists of any executable statements between
the ELSE statement and the next ENDIF statement at the same
IF level.
Example See IF - THEN.
ENDIF
Action Terminates an IF block.
Syntax
Remarks Each block of statements corresponding to each IF or ELSEIF
statement must end with an ENDIF.
Example See IF - THEN.
DO
Action Repeatedly executes the statements following the DO statement,
through the statement which ends the loop.
WinNonlin
Users Guide
288
11
WinNonlin comparison operators
Syntax DO var=exp1 TO exp2 [STEP exp3]
Where var is a variable to be incremented during the looping.
exp1 is an expression whose value is the initial value of var.
exp2 is an expression whose value is the limit for the loop.
STEP exp3 is optional. If omitted, exp3 is assumed to be 1.
exp3 is an expression whose value is the incrementor for the
loop.
Remarks If exp3 is positive, exp2 is an upper limit for the loop.
If exp3 is negative, exp2 is a lower limit for the loop.
Var is always initialized to exp1, even if the loop is not executed
(because the value of exp1 is beyond the limit placed by exp2).
After executing the last round through the loop, var has the value
which caused the loop to exit (i.e., it is beyond the limit set by
exp2).
IF statements can be nested up to 10 deep with the default
model size (2), and up to 30 for model sizes 3 or greater.
Example DO I=1 TO 3
DO J=1 TO 5
statements
NEXT
NEXT
NEXT
Action Marks the end of a DO loop.
Syntax DO .......
NEXT
Example See DO.
Operator Definition
AND and
OR or
GT > greater than
LT < less than
EQ = equal to
GE >= greater than or equal to
User Models
The WinNonlin programming language
289
11
Functions
Function names which are grouped together are interchangeable. For exam-
ple, both EXP(X) and DEXP(X) will produce the same result, namely, e
x
.
LE <= less than or equal to
Function Name Result
LAG(var) This function will return the value of var at the last
execution. Var can be X, Y, WT, or any temporary
variable.
INT(var) This function will truncate var to an integer value.
E.G.: INT(3.9) = 3
EXP (X), DEXP (X)
e
x
ALOG (X),
DLOG (X), LOGE (X)
natural log of X: ln(X)
ALOG10 (X), DLOG10 (X) LOG10 (X) log base 10 of X: log
10
(X)
SQRT (X), DSQRT (X)

SIN (X), DSIN (X) sine (X)
COS (X), DCOS (X) cosine (X)
MAX (X, Y), DMAX1 (X, Y) returns the maximum of X and Y
MIN (X, Y), DMIN1 (X, Y) returns the minimum of X and Y
ABS (X), DABS (X) returns the absolute value of X
ATAN (X), DATAN (X)
tan
-1
(X)
ATAN2 (X, Y),
DATAN2 (X, Y)
tan
-1
(X/Y)
Operator Definition
X
WinNonlin
Users Guide
290
11
Bioassay functions
ASCII models
User Models can be created as ASCII text files, or Compiled user models.
User libraries
Several user models can be stored in an ASCII text file, with each model iden-
tified by a unique model number. Individual ASCII models may be up to 24 K
in size. An ASCII library, containing one or more ASCII models, cannot be
more than 30 K in size.
Table 11-2. Bioassay functions
Function name Result
NORMIT (R,N) Let p denote R/N. This function returns the normit of p.
That is, it returns the value NOR such that
Note: If R=0, then p is set to 1/2N.
If R=N, then p is set to 1-1/2N
WTNORM (NOR,N) This function returns the wt, WTNOR, associated with the
normit (NOR) and a sample size N.
LOGIT(P)

( ) p Z dz
NOR
=

1
2
2
2

exp
( ) ( )
WTNOR
N Z
p p
=


2
1
( ) Z NOR =
1
2
2
2

exp
( ) p X dx
NOR
=

1
2
2
2

exp
where
and
( )
ln
P
P 1
LOGIT =
User Models
ASCII models
291
11
WinNonlin provides a library of ASCII models in its \LIB directory. To use
one of these WinNonlin library files as a template, copy the library file and
modify the copy, thereby maintaining the original library unaltered.
Within the ASCII file, each model begins with a MODEL n statement, identi-
fying the model by number, n, and ends with an end-of-model (EOM) state-
ment. Note that the model number must be greater than 0.
For example: three models are written and stored in a file called MYMOD-
ELS.LIB, in a subdirectory called USERMODS. The structure of this file is:
The model statements are further described under Model structure on
page 274 and Model components on page 276.
Examples
The following examples demonstrate how to use the above groups of state-
ments in order to define a model. Examples demonstrating how to fit a user
model to a set of data can be found in the Examples Guide.
Example 1
To fit a set of data to the following model:
A, and are parameters to be estimated, t denotes time and C(0) is con-
strained to be zero (i.e., A + B = 0). In addition, suppose it is desired to esti-
mate the half lives of and , namely
MODEL 1
model statements
EOM
MODEL 2
model statements
EOM
MODEL 3
model statements
EOM
( ) ( ) ( ) C t A t B t = + exp
WinNonlin
Users Guide
292
11
Note: For this model, there are three parameters to be estimated: A, and . B is not
a parameter to be estimated since C(0) = 0. This constraint implies that B is
equal to -A.
To define this model and secondary parameters in WinNonlin the following
statements can be used:
The FUNCTION statement specifies that function one is being defined (in
this example there was only one function). F denotes the concentration pre-
dicted by the model, and is a function of X (which is time for this example)
and three parameters A, a, and b, which are to be estimated. The first END
statement signifies the end of the statements which define function one.
SECONDARY specifies that the next set of statements will be defining sec-
ondary parameters (functions of the model parameters) to be estimated. The
second END statement signifies the end of the statements which defines the
secondary parameters.
EOM signifies that the model specification is complete.
The above set of statements will work fine. However, the model definition
statements can be more easily interpreted by using parameter and secondary
parameter names, and remarks. For example, the following set of statements
is functionally equivalent to the previous set.
( ) LN .5
( ) LN .5
and
MODEL
FUNCTION 1
F=P(1)*EXP(-P(2)*X)-P(1)*EXP(-P(3)*X)
END
SECONDARY
S(1)=-LOGE(.5)/P(2)
S(2)=-LOGE(.5)/P(3)
END
EOM
User Models
ASCII models
293
11
COMMAND specifies that the next set of statements will be model com-
mands. The PNAMES and SNAMES statements defined the parameter names
and secondary names that are used in the programming statements and in the
output. The first END statement signifies the end of the COMMAND block.
Note: The use of remarks helps describe the model. In addition, note the use of
SNAMES and PNAMES to assign meaningful variable names to the parame-
ters (such as alpha and beta) and to facilitate defining the model. The vari-
ables A, B, TIME, E1 and E2 were not needed in defining the secondary
parameters, and consequently were only defined as (local) temporary vari-
ables within the statements which defined FUNC 1. However, equivalent
results would have been obtained if A, B, TIME, E1 and E2 had been defined
as (global) temporary variables within a TEMP block.
The MODEL statement without a number and file name instructs WinNonlin
that the statements immediately following the MODEL statements are model
definition statements and not commands.
MODEL
remark: Example problem
COMMAND
NPARM 3
NSEC 2
PNAMES A, ALPHA, BETA
SNAMES ALPHA_HL, BETA_HL
END
FUNC 1
B=-A
remark: Model is constrained so that C(0)=0
TIME=X
E1=EXP(-ALPHA*TIME)
E2=EXP(-BETA*TIME)
F=A*E1 + B*E2
END
remark: Secondary parameters
SECO
ALPHA_HL=-LOGE(.5)/ALPHA
BETA_HL=-LOGE(.5)/BETA
END
EOM
WinNonlin
Users Guide
294
11
If these commands were stored in a disk file as part of a library, the first state-
ment should be MODEL n, where n is the model number.
In a command file, a model stored in an external library file could be recalled
by specifying the following command:
MODEL n, filename
where n is the associated model number and filename is the name of the disk
file containing the library. This is equivalent to selecting Existing ASCII
Model from the User Model group box in the Libraries of Models dialog box.
If the statements were to be stored in a library, it would be appropriate to also
store the commands that pertain directly to the model. For example, to store
NSEC and NPAR with the model, include the following set of statements:
Normally, this block of commands would be placed immediately after the
MODEL statement.
Note: Print out the WinNonlin library files to study as additional examples of how to
define models. It is recommended, however, that these files not be modified.
Instead, make copies of these files for modification, leaving the library files
intact.
Example 2
Consider a model characterized by the following system of differential equa-
tions.
COMMANDS
NPAR 2
NSEC 2
END
dZ
dt
K Z
( )
( )
1
12 1 =
dZ
dt
K Z K Z
( )
( ) ( )
2
12 1 20 2 =
User Models
ASCII models
295
11
with initial conditions Z
1
(0) = D and Z
2
(0) = 0. The parameters to be esti-
mated are K12, K20 and D.
As in the previous example, first use a PNAMES statement to assign mean-
ingful names to the parameters and facilitate defining the model.
Next, define the initial values for the differential equations.
A FUNCTION block is required when modeling differential equations. In this
case model only Z(2) - the plasma compartment.
The next set of statements completes the specification of the model.
One could have also defined secondary parameters to be estimated. As dis-
cussed previously, if the above statements were to be stored in a user library,
the first statement would be: MODEL n where n denotes the assigned model
number.
MODEL
COMMAND
NPARM 3
PNAMES K12, K20, D
END
START
Z(1) = D
Z(2) = 0
END
FUNC 1
F=Z(2)
END
DIFF
DZ(1) = -K12 * Z(1)
DZ(2) = K12 * Z(1) - K20 * Z(2)
END
EOM
WinNonlin
Users Guide
296
11
Example 3
This example shows how to use the predefined variables to alter a model
based on the current observation. Suppose there are two sets of data to fit
simultaneously. Both data sets have the same model and parameters except
that the second set needs a time lag in order to be fit properly.
Assume that the data look like this:
The first column is time and the second is concentration. The third column is
an indicator variable. Its value indicates to which set of data the observations
belong. To access its value during the model-fitting process, use the DTA( )
variable. Since the third column contains the indicator values, the statement:
I = DTA(3)
assigns the variable I the current value of the indicator variable. Now write the
model as follows:
0.5 0.03 1
1.0 0.7 1
2.0 0.9 1
... ....
0.5 0 2
1.0 0 2
2.0 0 2
3.0 0.02 2
User Models
ASCII models
297
11
When I equals 1 the function without the time lag is fit. When I is not 1, that
is, I = 2, the function with the time lag is fit.
There is another way to fit these data. The two functions can be separately
defined. Using the FNUMBER command, the data are partitioned between
the two functions.
MODEL
COMM
NPAR 5
PNAMES A, B, ALPHA, BETA, LAG
END
FUNC 1
I = DTA(3)
IF I = 1 THEN :First Set of Data
T = X
F = A*EXP(-ALPHA*T) + B*EXP(-BETA*T)
ELSE :Second Set of Data
T = X-LAG
F = A*EXP(-ALPHA*T) + B*EXP(-BETA*T)
ENDIF
END
EOM
WinNonlin
Users Guide
298
11
These two approaches will produce the same final parameter estimates but
different summary output. In the first case a single summary table is created.
In the second case, two summary tables will be created, one for each function.
Creating a new ASCII model
To create a new ASCII model:
1. Launch the PK/PD/NCA ANalysis Wizard by clicking on the PK/PD/NCA
Analysis Wizard tool bar button or choosing Tools>PK/PD/NCA Analysis
Wizard from the WinNonlin menus.
1. Select User Model in the Model Types dialog.
2. Click Next. The ASCII Model Selection dialog appears.
3. Select Create New ASCII Model.
4. Click Next. The Model Parameters dialog appears.
5. Enter the number of algebraic functions in the model.
MODEL
COMM
NPAR 5
PNAMES A, B, ALPHA, BETA, LAG
END
FUNC 1
T = X
F = A*EXP(-ALPHA*T) + B*EXP(-BETA*T)
END
FUNC 2
T = X-LAG
F = A*EXP(-ALPHA*T) + B*EXP(-BETA*T)
END
EOM
.
.
NFUNC 2 : Number of Functions
FNUM 3 : Column number representing the function variable
.
User Models
ASCII models
299
11
6. If the model includes differential equations, check the Include differential
equations check box and enter the number of differential equations.
7. Assign the model a positive number between 1 and 32767, as its model num-
ber. This number will be needed to save and re-use the model.
8. Enter the Primary Parameters and Secondary Parameters in the grid. Parame-
ter names may include up to 8 alphanumeric characters.
9. Click Next. The Selection Summary dialog appears.
10. When everything is correct click Finish. Click Back to change any setting.
Note: The system must know if the model includes differential equations in order to
provide the correct template.
11. Edit the model as needed, using the syntax and guidelines provided under:
Model structure on page 274
Model components on page 276
WinNonlin variables on page 284
12. To save this model, save it as an ASCII file (.LIB). The default model library
file name is USERASCI.LIB. It is often convenient to save under a new file
name that describes the model. Several models can be saved to one .LIB file,
so long as each uses a unique model number. To do this, open the library file
in a text editor, and copy and paste the new model text into the existing file.
Undo for ASCII model development
Some operations can be reversed in the ASCII model window. Only the most
recent operation can be undone. Undo is available for the following:
Table 11-3. Undo operations
Operation Undo effect
Cut Restore cut text string.
Paste Remove newly pasted text string.
Clear Restore cleared text string.
Replace Restore original string.
WinNonlin
Users Guide
300
11
Loading an existing ASCII user model
To use a user-defined ASCII model:
1. Open the data set to be modeled.
2. Click on the PK/PD/NCA Analysis Wizard button on the tool bar or choose
Tools>PK/PD/NCA Analysis Wizard from the menus.
3. Select User Model from the Model Types dialog.
4. Click Next.
5. In the next dialog select Load Existing ASCII Model.
6. Click Next.
7. Enter the model number in the field provided for Model Number. Each
ASCII model in a library file (.LIB) must have a unique model number.
8. Type in or click ... to enter the absolute path and file name of model library.
9. Click Next, then Finish to load the model.
WinNonlin will look for a model of the appropriate number and load it into a
model window.The model may be edited from within that window. See
ASCII models on page 290 for further detail.
User Models
Compiled user models
301
11
Compiled user models
For User Models defined in terms of several differential equations, the model
fitting process can be greatly accelerated by compiling the model into a 32-bit
Windows dynamic link library (DLL) using either Compaq Visual FORTRAN
6.0 or Microsoft Visual C++ 6.0.
Creating a DLL requires the following steps:
1. Create a source file.
2. Compile the source file.
3. Link the source file with the language libraries to build a DLL.
The source code file contains one subroutine specifying the model. This sub-
routine must be named USRMOD( ). Note, however, that the project should
not be named USRMOD; USRMOD.DLL is a reserved name in WinNonlin.
Compiled user models can be called in command files (see Command Files
on page 309) or loaded using WinNonlins PK/PD/NCA Analysis Wizard (see
Loading the model on page 247).
Using FORTRAN
Creating a source file
The format of this file is very similar to a WinNonlin ASCII model file. The
same blocks are included, with a slightly different implementation. A tem-
plate for this file is provided for FORTRAN 6.0.
The files required to build a DLL in FORTRAN have been installed to the
\USERCOMP subdirectory of the WinNonlin installation directory. Two sets of
files have been provided. Either of these f90 files can be used as a template.
These files include:
File Purpose
F_UEXP6.F90 FORTRAN source file for Example 6.
F_UEXP6.DLL Compiled .DLL for Example 6.
F_UEXP15.F90 FORTRAN source file for Example 15.
F_UEXP15.DLL Compiled .DLL for Example 15.
WinNonlin
Users Guide
302
11
Note: To demonstrate the benefits of compiling models, run Example 15 in both the
ASCII form and in the compiled form.
Example using Compaq Visual FORTRAN 6.0
To compile a user model:
1. Open Compaq Visual Fortran.
2. Choose File>New from the menus.
3. Select Fortran Dynamic Link Library as the kind of product to create.
4. Enter a project name at the top left.
5. Click OK.
6. In the next dialog select Empty dll application.
User Models
Compiled user models
303
11
7. Click Finish.
8. Click OK.
9. Choose Project>Add to Project>New from the menus.
10. Select Fortran Free format source file.
11. Enter a file name. This example uses modelname.f90.
This opens a frame for the Fortran file.
12. Enter the code using the templates provided (see the table above).
WinNonlin
Users Guide
304
11
13. Select from the Build menu Set Active Configuration Win32 Release.
This minimizes the size of the file.
14. Select from the Build menu Build mymodel.dll. The .DLL is built in the spec-
ified directory (D:\MYPROJECTS\MYMODEL\RELEASE\MYMODEL.DLL).
Note: Statements in the FORTRAN source file with a ! in the first column are
comments.
To alter the example templates for a custom model:
1. FORTRAN will assume that any variables beginning with the letters I through
N are integer, and any others are real. If there are any variables to explicitly
declare as integer, add these in an INTEGER statement. Any variables to
explicitly declare as real should be specified via the REAL*8 statement. No
other changes need to be made to this section of the template.
2. Replace k12 = p(1) ... etc. with the parameters for the model as they would
be stated in a Temporary block.
3. For each block other than the Command block that appears in the model
include the corresponding block from the template file:
4. Include any information from the Command block in the associated .CMD
file. This command file is the file which calls the compiled model in the DLL.
The source file stored on disk can be assigned any name, but the subroutine
must be named USRMOD( ).
Transform block Set Transformations
Temporary block Set Temporary variables
Function block Set Functions
Starting values block Set Starting values
Differential block Set Differential equations
Secondary block Set Secondary parameters
User Models
Compiled user models
305
11
Using C++
Creating a source file
The format of this file is very similar to a WinNonlin model file. The same
blocks are included, with a slightly different implementation. An example of
this file is provided for Microsoft Visual C++ 6.0.
The files required to build a DLL in Visual C++ have been installed to the
\USERCOMP subdirectory. Two sets of files have been provided. Either of these
files can be used as a template. These files include:
Note: To demonstrate the benefits of compiling models, run Example 15 in both the
ASCII form and in the compiled form.
Example using Microsoft Visual C++ 6.0
To compile a user model:
1. Open Microsoft Visual C++ v. 6.0.
2. Select New from the File menu.
3. Select Win32 Dynamic Link Library.
4. Enter a project name.
5. Press OK.
6. In the next dialog select An empty dll project.
7. Click Finish.
8. Click OK.
File Purpose
C_UEXP6.C C source file for Example 6.
C_UEXP6.DLL Compiled .DLL file for Example 6.
C_UEXP15.C C source file for Example 15.
C_UEXP15.DLL Compiled .DLL file for Example 15.
WinNonlin
Users Guide
306
11
9. On the Project menu select Add to ProjectNew.
10. Select C++ Source File.
11. Enter a file name. This example uses modelname.c.
Note: It is important to use the .c file extension rather than the .cpp extension.
12. A frame opens for the program. Enter the code for the model. Use the tem-
plates provided (see table above).
13. Select from the Build menu Set Active ConfigurationWin32 Release.
This is not essential, but it builds a smaller DLL file.
14. Select from the Build menu Build mymodel.dll. The DLL is built in the spec-
ified directory (D:\MYPROJECTS\MYMODEL\RELEASE\MYMODEL.DLL)
Note: Statements in the Visual C++ source file with // starting in the first column are
comments. A comment line begins with /* and ends with */.
To alter this example for another model:
1. C++ makes no assumptions about types of variables. All integers should be
declared as INT and all real numbers should be declared as DOUBLE.
2. Replace k12 = p[0]; ... etc. with the parameters for the model as they would
be stated in a Temporary block.
3. For each block, other than the Command block, that appears in this model
include the corresponding block from the template file:
4. Include any information from the Command block in the associated .CMD
file.
Transform block Set Transformations
Temporary block Set Temporary variables
Function block Set Functions
Starting values block Set Starting values
Differential block Set Differential equations
Secondary block Set Secondary parameters
User Models
Compiled user models
307
11
The source file stored on disk can be assigned any name, but the subroutine
must be called USRMOD( ).
Using compiled user models in a command file
Compiled user models may be loaded into WinNonlin through a command
file to communicate any of the following model information. The format of
this file is the same regardless of the language used to compile the model.
NPARAMETERS
PNAMES
NDERIVATIVES
NFUNCTIONS
NSECONDARY
SNAMES
CNAMES
PUNIT
SUNIT
Although the following information may also be included in the command
file, it may also be specified via the interface once the model is loaded.
Data set to be modeled
Data Variables and Weighting
Model Parameter information
Dosing information/Constants
Model Options
To load a user compiled model in a command file:
1. Include the command MODEL 1000 C:\MYPATH\MYDLL.DLL in a com-
mand file. If no path is given, WinNonlin will expect to find MYDLL.DLL in
the directory containing the command file.
Note: Do not store a file named USRMOD.DLL in the installation directory. This is a
reserved name in WinNonlin.
WinNonlin
Users Guide
308
11
Code in boldface is
required in the
command file. All
else may be
specified via the
interface rather
than included in the
command file.
title
Fitting a system of two differential equations - data available on both
model 1000, 'c_uexp6.dll'
npar 3
pnames 'K12', 'K20', 'C0'
nder 2 <--- 2 diff. equations in the system
nfun 2 <--- data available on both equations
init .1, .05, 100
lower 0 0 0
upper 1 1 200
reweight -1 <--- iteratively reweight by 1/(pred. conc.)
nvar 3
fnum 3
data
0 100 1
1 85.34 1
2 79.44 1
3 79.13 1
4 71.18 1
5 56.2 1
10 29.66 1
15 17.47 1
20 10.8 1
25 5.81 1
30 3.23 1
40 .93 1
50 .32 1
60 .1 1
0 0 2
1 10.86 2
2 21.1 2
3 27.01 2
4 34.45 2
5 36.41 2
10 46.27 2
15 48.73 2
20 48.17 2
25 41.76 2
30 27.32 2
40 20.70 2
50 11.18 2
60 5.76 2
begin
finish
309
Chapter 12
Command Files
Storing and running models through WinNonlin
commands
A command file can store and run compartmental and noncompartmental
models. Command files do have some limitation in functionality: model ini-
tial parameter specification, Lambda Z range specification, dosing, and partial
areas can not be specified separately for each sort level in a command file.
Pharsight Model Objects (.PMOs) can also be used to store all information
required to run a compartmental or noncompartmental model. LinMix com-
mand (*.LML) files can be used to store linear mixed effects models.
Command file structure
A WinNonlin command file has three main components: Model definition,
Commands and Data.
WinNonlin
Users Guide
310
12
Model definition
The model definition section is a set of WinNonlin statements that define the
function(s) to be used to fit data. It may be as simple as calling up a pre-
defined model (either a WinNonlin model or a user model) or involve compli-
cated sequences of commands. Models which will be used more than once
should be stored in a user library and called using the model statement. See
User Models on page 273 for further information.
Commands
Commands that wont vary across sessions should be included in the model
file. When running WinNonlin using the WinNonlin interface, modeling
instructions are specified via dialog boxes. WinNonlin uses this input to create
commands which deliver this information. When a command file is used,
these commands are specified directly. The commands are placed after the
model definition and before the data set is specified.
WinNonlin commands are described in this chapter. They fall into two main
categories: model initialization and model options. The model initialization
commands provide WinNonlin with information to start the fitting process.
This includes initial values of parameters, constants (such as dosing informa-
tion), specification of variables, weighting and bounds on the parameters.
Model option statements determine the type of algorithm to use, appearance
of the output, etc.
Data
The data section indicates the data to be used by WinNonlin. This section may
simply be a reference to a data set, or the data itself may be included in the
command file.
It is generally best to store models in libraries and the data in Pharsight work-
books so that the models may be used with other data and the data may be
used with different models.
WinNonlin commands: basics
Each line in a WinNonlin command file begins with a WinNonlin command
followed by its arguments, if any. All commands can be abbreviated to the
first four letters of the command and can be in upper or lower case. After
Command Files
WinNonlin commands: basics
311
12
WinNonlin identifies the first four characters it then looks for the arguments,
if any, the command requires. All other characters are ignored.
Although commands may be up to 250 characters in length, it is possible to
split commands into multiple lines. This is done by adding an ampersand (&)
to the end of each line to be continued. The '&' must be preceded by at least
one space.
Commands which take two (2) or more numeric arguments may have the
arguments separated by spaces or commas.
A WinNonlin command file can be commented in two different ways. If a line
begins with the command REMARK, the entire line is considered to be a
comment. See the first line of the example below.
Alternatively, any text following the last argument is considered a comment.
In the example above, in lines 3 and 5, the references to Nelder-Mead consti-
tute comments following the Method statement.
Example
(The following are equivalent)
NVARIABLES, NVAR, nvariables, nvar
Example
INITIAL ARE.05 &
1.D-3 &
100
is equivalent to
INIT.05, 1D-3, 100
Examples of Comments
REMARK - USING NELDER-MEAD
or
METHOD 1: NELDER-MEAD
or
METHOD 1 NELDER-MEAD
WinNonlin
Users Guide
312
12
Model definition commands
The following commands are used to define functions. Details on each are
provided under Commands, Arrays and Functions on page 621. With one
exception noted below, predefined models do not require these commands.
NPARAMETERS NCONSTANTS
NSECONDARY NFUNCTIONS
NDERIVATIVES PNAMES
SNAMES PUNITS
DNAMES SUNITS
Note: All of these commands except NCONSTANTS are generally defined in the
Model block. In models with a fixed number of constants, NCONSTANTS
should also be defined in the Model block.
Loading ASCII models
To load an ASCII library model, include the following command in the com-
mand file:
MODEL n FILENAME
where n is the model number, and FILENAME is the appropriate library file
name.
Model initialization commands
Model initialization includes initial values of parameters, constants (such as
dosing information), specification of variables and bounds on the parameters.
Variables
WinNonlin must know what variables from the data worksheet are to be used
in the model fitting. The grid below is used in the descriptions that follow.
Command Files
Model initialization commands
313
12
The XNUMBER and YNUMBER commands tell WinNonlin which variables
or columns on the data grid to use as X and Y. The XNUMBER and YNUM-
BER commands have as their arguments the column number of the X and Y
variable, respectively. These commands must precede DATA. The following
example selects Time as the X variable, and Conc as the Y variable.
The SIMULATE command indicates that a simulation is to be performed.
This command should appear before the data command. Note that if SIMU-
LATE is used no Y variable is needed. If a YNUM statement is included it
will be ignored.
The SORT command has as its arguments the number 1, followed by the vari-
able(s) selected as sort variables. Although the number 1 included with this
command each time serves no purpose in the modeling for this version, it is
included to provide compatibility with PCNonlin Version 4. The following
example tells WinNonlin to use Study and Subject as sort variables.
Study Subject Time Conc Weight Type
1 1 0 3.8 1.9 1
1 1 .5 4.8 2.2 1
1 1 1 5.1 2.3 1
. . . . . .
Example - XNUMBER and YNUMBER
XNUMBER is 2
YNUM 3
Example - Simulate
XNUM 2
SIMULATE
Example - Sort variables
SORT 1, 1, 2
WinNonlin
Users Guide
314
12
When modeling two functions simultaneously there must be some way to
delineate which data observations belong with each function. This is most
easily done by including a dummy variable whose values are equal to the
number of the function (i.e. FUNC 1, FUNC 2, etc.). This variable is called a
Function variable.
The FNUMBER command has as its argument the number of a column to be
used as the Function variable. The following example tells WinNonlin to use
Type as the function variable.
The URINE command is used to specify variables when doing noncompart-
mental analysis for urine data (Models 210-212). These models require:
the beginning time of the urine collection interval,
the ending time of the urine collection interval,
the volume of urine collected, and
the concentration in the urine.
These are specified using a keyword and a column number as shown below.
where # is replaced with the appropriate column numbers on the data file.
Weighting
There are four ways of assigning weights, other than uniform weighting, for
compartmental modeling in WinNonlin
A
:
Example - Function variable
FNUM 6
Example - URINE command
URINE LOWER = # UPPER = # VOLUME = # CONCENTRATION = #
URINE CONC # VOLU # LOWE # UPPE #
A. Note that for Noncompartmental models, only option 1 is allowed.
Command Files
Model initialization commands
315
12
1. Instruct WinNonlin to weight by a power of the observed Y
(Weighted least squares).
2. Specify weights as the predicted value of Y to a specified power
(Iterative reweighting).
3. Include Weight as a variable in the data file.
4. Use programming statements to define weights as part of a user defined
model.
The command WEIGHT [W] specifies that weighted least squares computa-
tions are to be used. The optional argument indicates that the weight to use is
Y
W
. If W is not specified, one of the columns in the data set is used as the
weights. The default column is column 3. This may be overridden using the
WTNUMBER command.
Similarly, the REWEIGHT [W] command specifies that iterative reweighting
is to be done. The optional argument indicates that the weight to use is F
W
,
where F is the predicted response (also denoted as Yhat).
Note: If W and Y or Yhat are less than 0, then the corresponding weight is set to 0.
When weights are read from the data file or when weighted least squares is
used, the weights for the individual data values are scaled so that the sum of
the weights for each function is equal to the number of data values (with non-
zero weights). The scaling provides numerical stability but does not alter the
Example - Weighted Least Squares
WEIGHT -2
uses 1/Y
2
as the weight
WEIGHT
WTNUM 7 uses the values in Column 7 as the weights
WEIGHT uses the values in Column 3 as the weights
Example - Iterative Reweighting
REWEIGHT -.5 uses 1/sqrt(Yhat) as the weight
REWEIGHT 2 uses Yhat
2
as the weight
WinNonlin
Users Guide
316
12
final estimates of the parameters. The NOSCALE tells WinNonlin not to scale
the weights.
When writing a user model, the user may use programming statements to
define weights. When doing so, use the variable name WT. When using this
option, make sure the WT is always defined. For example, setting WT = 1/
(F*F) will generate an error if F ever takes on the value of zero.
Note: When the variable WT is specified in a model file, this specification will over-
ride any weighting specified via the Data Variables dialog box.
Note: When using the Windows interface, Variables and Weighting are specified
through the Data Variables Dialog Box
Model parameters
The NPARAMETERS command has as its argument the number of parame-
ters that are required for the model. The NPARAMETERS command must
precede the INITIAL, LOWER, and UPPER commands, if they are used.
The INITIAL command takes as its arguments the initial values of the param-
eters defined in the model. When doing a simulation, these are the parameter
values. If the initial command is not included, WinNonlin will attempt to
compute initial estimates. In most cases, boundaries will need to be included
to allow the computation of initial estimates.
The LOWER and UPPER commands have as their arguments the user-sup-
plied lower and upper boundaries. If bounds are not to be used, include the
NOBOUNDS command. If NOBOUNDS is not specified, and LOWER and
UPPER are not used, WinNonlin will calculate boundaries (providing that an
INITIAL command is given.)
Example - Defining weights with programming statements
WT = 1/(F*F) equivalent to using REWEIGHT -2
IF X > 10 THEN
WT=1/Y
ELSE
WT=1/(Y*Y)
ENDIF
sets the weight of the observation equal to 1/Y if the value of X is greater
than 10, or equal to 1/Y
2
if X is less than or equal to 10
Command Files
Model initialization commands
317
12
Names may be assigned to the parameters using the PNAMES command.
These names will be used in the output as labels, and may also be used in the
modeling code. See many of the example files provided with WinNonlin in
the Examples subdirectory; in particular, see BG2.CMD or EXP10.CMD.
When using a library model which includes a PNAMES command and enter-
ing parameter information through the WinNonlin interface, the parameter
names will be displayed when the Model parameters dialog box opens.
Note: If the INITIAL statement is included in a command file, rather than being
input via the WinNonlin interface, then the NPARAMETERS must proceed
the INITIAL statement. However, the NPARAMETERS statement is not nec-
essary when fitting models in WinNonlin's library of models, as NPAR is
stored as part of the model or definition commands in the library.
Dosing regimen
WinNonlin uses constants to communicate dosing information. See the Win-
Nonlin library models for examples of the use of constants.
The NCONSTANTS command has as its arguments the number of constants
required for the model. For a given model this may be fixed, or it may vary.
For example, for models with multiple dosing, this number will vary. If the
number of constants is fixed it is generally easiest to include this statement in
a COMMANDS block in the model file.
The CONSTANTS command has as its arguments any constants defined in
the model. There must be a value for each constant specified in the model.
Example
NPAR 3
INIT .1, .05, 10
LOWER 0, 0, 0
UPPER 1, .5, 100
User supplied boundaries
NPAR 3
INIT .1, .05, 10
WinNonlin will compute bounds on the parameters
NPAR 3
INIT .1, .05, 10
NOBO
No boundaries will be used
WinNonlin
Users Guide
318
12
Note: Remember that the NCONSTANTS command must be specified prior to the
CONSTANTS command.
Model options
Headers
The TIME and DATE commands tell WinNonlin to include the current time
and date, respectively, on the output.
The TITLE [N] command indicates that the following line contains a title to
be printed on each page of the output. Up to five titles may be included. To
specify any title other than the first, a value N must be included with the
TITLE command. N may take on the values 1 through 5.
Example
NCON 3
REMARK # Doses, Dose 1, Time of Dose 1
CONSTANTS 1 50 0
NCON 5
CONS 2, 50, 0, 25, 6
Example
TIME
DATE
Example
TITLE
Experiment A-4115
TITLE
Experiment A-4115
TITLE 2
Subject #1
Command Files
Model initialization commands
319
12
Output options
The NOPLOTS command tells WinNonlin not to include plots in the output.
The NOPAGE command excludes page breaks in the ASCII output.
Settings
When modeling, the METHOD command specifies the type or fitting algo-
rithm WinNonlin is to use. The argument N takes on the following values:
1. Nelder-Mead Simplex
2. Levenberg and Hartley modification of Gauss-Newton algorithm
3. Hartley modification of Gauss-Newton algorithm
When doing noncompartmental analysis, the METHOD command specifies
the method to be used to compute area under the curve. The argument N takes
on the following values:
1. Lin/Log - Linear trapezoidal rule up to Tmax, and log trapezoidal rule for
the remainder of the curve.
2. Linear Trapezoidal rule (Linear Interpolation)
3. Linear Up/Log Down
4. Linear Trapezoidal (Linear/Log Interpolation)
Method 2 is the default method in each case.
The DINCREMENT command has as its argument the increment for partial
derivatives. The default is 0.001. This default should generally not be altered.
The NPOINTS command has as its argument the number of predicted values
to be produced for the plots. The default is 1000
A
.
The CONVERGENCE command has as its argument the value for Conver-
gence Criteria. The default is 0.0001.
The MEANSQUARE has as its argument the value to be used for Mean-
square.
A. For WinNonlin library models, the defaults are as follows:
IV bolus or extravascular administration: 1000 + the number of administered doses
IV infusion: 1000 + the number of doses times 2.
WinNonlin
Users Guide
320
12
The ITERATIONS command has as its argument the number of iterations to
be performed. (The default is 500 for Method 1 and 50 for Methods 2 and 3.)
The SIZE command has as its argument the model size. Model size sets
default memory requirements. It may range from 1 to 65, the default size is 4.
Model size is only applicable when using ASCII models.
Data commands
Generally data are stored in WinNonlin worksheets so that the data may be
used with different models and/or processed further (plots, descriptive statis-
tics, etc.). This section describes both how to indicate the WinNonlin grids to
be used, and how to include data and information about the data in a com-
mand file.
The name of the file the data are stored in may be specified by the DATA
command. If the file name is omitted, the program assumes that the data begin
immediately following the DATA command.
When creating a command file with an ASCII model with NFUNCTIONS
greater than 1, and a FNUMBER variable to tell WinNonlin which variable is
the Function variable has not been specified, a NOBSERVATIONS command
must be included. The arguments for this command are the number of obser-
vations to be used for each function. If used, the NOBS command must be
placed prior to the DATA command.
Examples
DATA are in 'MYDATA.FIL
DATA 'B:TEST.DTA
DATA
.5 1.3
.75 1.7
Examples
One function: NOBSERVATIONS ARE 15
(Optional)
Two functions: NOBS 15, 18
Command Files
Data commands
321
12
Note: Note that the ability to use the NOBS statement in this way is provided for
compatibility with PCNonlin. The recommended method for indicating which
observations are to be used with each function, is the use of a FUNCTION
variable. An example of the use of a function variable is shown below.
Values in the data file can be accessed via the DTA( ) array. For a given obser-
vation, the value in column one of the input data file is stored in DTA(1), the
value in column two is stored in DTA(2), etc. This permits models to be func-
tions of more than one independent variable. Statements such as
X3 = DTA(3) and X34 = DTA(3) * DTA(4)
are permissible when defining the model.
The SORT command may be used to fit data subsets from a large database,
one at a time. Multiple SORT variables, e.g. subject, and formulation may be
used to define unique profiles for processing.
Three functions: NOBS 15, 18, 12
Examples
Example: FNUM
REMA Using a FUNCTION variable to indicate to which func-
tion data belongs.
NFUN 2
FNUM 3
DATA
0 0
.25
.50
1.0
2.0
4.0
0
.3
.5
.4
.25
.15
1
1
1
1
1
1
start of data for function 1
0
.25
.50
1.0
2.0
4.0
0
.28
.45
.43
.30
.30
2
2
2
2
2
2
start of data for function 2
WinNonlin
Users Guide
322
12
The model that is to be fit can be a function of several independent variables.
XNUMBER specifies the variable that will be plotted on the horizontal axis in
plots 1 and 4 (see NOPLOTS on page 632). In addition, if the model is
defined by a system of one or more differential equations (NDERIVA-
TIVES>0), then XNUM is used to signify which variable the differential
equations are with respect to (e.g., time).
If XNUM is omitted, the program assumes that the primary independent vari-
able corresponds to the first column in the data file.
The column in the data file that corresponds to the dependent variable (e.g.,
concentration) is specified via the YNUMBER command.
If YNUM is omitted, the program assumes that the dependent variable corre-
sponds to the second column in the data file.
If the user has specified that weights are to be read in from the data file (via
the WEIGHT command), the program assumes that the weights are in the
third column on the data file. If this is not the case, the column number must
be specified by using the WTNUMBER command.
Note: See Model definition commands on page 312.
Execution control statements
The BEGIN statement indicates that the commands for a problem have ended
and that processing can begin.
The FINISH statement tells WinNonlin that no more commands will follow.
This command is included to ensure compatibility with PCNonlin Version 4.
It should immediately follow the BEGIN command.
Example
YNUM is 4
XNUM is 3
Command Files
Execution control statements
323
12
Example - using BEGIN and FINISH
.
DATA
1 .05
2 1.0
3 2.0
6 1.0
8 .05
BEGIN
FINISH
WinNonlin
Users Guide
324
12
325
Chapter 13
Weighting
Weighted nonlinear regression
WinNonlin provides flexibility in performing weighted nonlinear regression
and using weighted regression. Weights are assigned after loading a model,
via the Model Options dialog box (Model>Model Options).
There are three ways of assigning weights, other than uniform weighting,
through the WinNonlin user interface:
1. Weighted least squares: weight by a power of the observed value of Y
2. Iterative reweighting: weight by a power of the predicted value of Y
3. Reading weights from the data file: include weight as a column in the data
For a user ASCII model, programming statements may also be used to define
weights as part of the model.
Weighted least squares
When using weighted least squares, WinNonlin weights each observation by
the value of the dependent variable raised to the power of n, i.e., WEIGHT =
Y
n
. For example, selecting this option, and setting n = -0.5 instructs WinNon-
lin to weight the data by the square root of the reciprocal of observed Y, i.e.,
.
If n has a negative value, and one or more of the Y values are less than or
equal to zero, then the corresponding weights are set to zero.
The program scales the weights such that the sum of the weights for each
function equals the number of observations with non-zero weights. See Scal-
ing of weights on page 326.
1 Y ( )
WinNonlin
Users Guide
326
13
Iterative reweighting
Iterative Reweighting redefines the weights for each observation to be F
n
,

where F is the predicted response. For example, selecting this option, and set-
ting n = -0.5 instructs WinNonlin to weight the data by the square root of
reciprocal of the predicted value of Y, i.e.,
.
As with Weighted least squares, if N is negative, and one or more of the pre-
dicted Y values are less than or equal to zero, then the corresponding weights
are set to zero.
Iterative reweighting differs from weighted least squares in that for weighted
least squares the weights are fixed. For iteratively reweighted least squares the
parameters change at each iteration, and therefore the predicted values and the
weights change at each iteration.
For certain types of models, iterative reweighting can be used to obtain maxi-
mum likelihood estimates (see the article by Jennrich and Moore in the Refer-
ences).
Reading weights from the data file
It is also possible to have a variable in the data file which has as its values the
weights to use. The weights should be the reciprocal of the variance of the
observations. As with Weighted Least Squares, the program will scale the
weights such that the sum of the weights for each function equals the number
of observations with non-zero weights (see Scaling of weights).
Scaling of weights
When weights are read from the data file or when weighted least squares is
used, the weights for the individual data values are scaled so that the sum of
the weights for each function is equal to the number of data values (with non-
zero weights).
The scaling of the weights has no effect on the model fitting as the weights of
the observations are proportionally the same. However, scaling of the weights
provides increased numerical stability.
Consider the following example:
1 Y

( )
Weighting
Weights in ASCII models
327
13
Suppose weighted least squares with the power -2 was specified (i.e., weight-
ing by 1/Y*Y). The corresponding values are as shown in the third column.
Each value of Y
-2
is divided by the sum of the values in the third column, and
then multiplied by the number of observations, e.g.,
(0.0277778/.0452254) * 3 = 1.8426238, or 1.843 after rounding.
Note that 0.0278/0.0051 is the same proportion as 1.843/0.338.
Note: Scaling can be turned off by selecting the No Scaling of Weights option on
the Weight tab of the Model Options dialog or by using the NOSCALE com-
mand in a command file.
Weights in ASCII models
When writing a custom ASCII model, it is possible to define the weights
using programming statements at the same time the model is defined. WT is a
special variable name in WinNonlin. If the variable WT is defined with pro-
gramming statements, this variable overrides any weighting specified in the
WinNonlin Model Options dialog. Consider the following example:
X Y Y
-2
Weight assigned
by WinNonlin
1 6 0.0278 1.843
10 9 0.0123 0.819
100 14 0.0051 0.338
Sum 0.0452 3.000
MODEL
TRANSFORM
IF X > 10 THEN
WT = 1/Y
ELSE
WT = 1/(Y*Y)
ENDIF
END
(additional statements here)
WinNonlin
Users Guide
328
13
The above statements would set the weight of the observation equal to 1/Y if
the value of X is greater than 10, and 1/Y
2
if X is less than or equal to 10. As
the values of Y are constant across iterations, the corresponding weights are
also constant. However, it is also possible to use programming statements to
iteratively reweight the observations, as shown in the following example:
This is equivalent to specifying Predicted to power n = -2. (See Iterative
reweighting on page 326.)
Each function to be fit can use a different weighting scheme. For example:
MODEL
FUNC 1
F = A*EXP(-ALPHA*X) - A*EXP(-BETA*X)
WT = 1/(F*F)
END
(additional statements here)
MODEL
TEMP
(additional statements here)
END
FUNC 1
(additional statements here)
WT = (some function)
END
FUNC 2
(additional statements here)
WT = (a different function)
END
(additional statements here)
329
Chapter 14
The WinNonlin Toolbox
Nonparametric Superposition, Semicompartmental
Modeling, Crossover Design, and Deconvolution
The WinNonlin toolbox includes the following four tools:
Nonparametric superposition: used to predict drug concentrations after
multiple dosing at steady state.
Semicompartmental modeling: estimates effect-site concentration given
plasma concentration and a value for Ke0.
Crossover design: performs nonparametric statistical tests; calculates con-
fidence intervals for treatment median and median difference between
treatments, and estimates relevance of direct, residual, and period effects.
Deconvolution: used to evaluate in vivo drug release and delivery based
on data for a known drug input.
Example are provided in the Examples Guide.
Nonparametric superposition
In pharmacokinetics it is often desirable to predict the drug concentration in
blood or plasma after multiple doses, based on concentration data from a sin-
gle dose. This can be done by fitting the data to a compartmental model with
some assumptions about the absorption rate of the drug. An alternative
method is based on the principle of superposition, which does not assume any
pharmacokinetic (PK) model.
WinNonlins nonparametric superposition function is used to predict drug
concentrations after multiple dosing at steady state, and is based on noncom-
partmental results describing single dose data. The predictions are based upon
an accumulation ratio computed from the terminal slope (lambda z). The fea-
ture allows predictions from simple (the same dose given in a constant inter-
WinNonlin
Users Guide
330
14
val) or complicated dosing schedules. The results can be used to help design
experiments or to predict outcomes of clinical trials when used in conjunction
with the semicompartmental modeling function.
Noncompartmental Superposition assumes that each dose of a drug acts inde-
pendently of every other dose; that the rate and extent of absorption and aver-
age systemic clearance are the same for each dosing interval; and that linear
pharmacokinetics apply, so that a change in dose during the multiple dosing
regimen can be accommodated.
Data and assumptions
In order to predict the drug concentration resulting from multiple doses, one
must have a complete characterization of the concentration-time profile after
a single dose. That is, it is necessary to know C(t
i
) at sufficient time points t
i
,
(i=1,2,,n), to characterize the drug absorption and elimination process. Two
assumptions about the data are required: independence of each dose effect,
and linearity of the underlying pharmacokinetics. The former assumes that the
effect of each dose can be separated from the effects of other doses. The latter,
linear pharmacokinetics, assumes that changes in drug concentration will vary
linearly with dose amount.
The required input data are the time, dosing, and drug concentration. The drug
concentration at any particular time during multiple dosing is then predicted
by simply adding all the concentration values in a row.
Note: User-defined terminal phases apply to all sort keys. In addition, dosing sched-
ules and doses are the same for all sort keys.
Computation method
Given the concentration data points C(t
i
) at times t
i
, (i=1,2,,n), after a single
dose D, one may obtain the concentration C(t) at any time t through interpola-
tion if t
1
< t <t
n
, or extrapolation if t > t
n
. The extrapolation assumes a log-lin-
ear elimination process; that is, the terminal phase in the plot of log(C(t))
versus t is approximately a straight line. If the absolute value of that lines
slope is
z
and the intercept is ln(), then C(t) = exp(-
z
t) for t > t
n
.
The slope
z
and the intercept are estimated by least squares from the terminal
phase; the time range included in the terminal phase is specified by the user. If
the user does not specify the terminal phase, estimates from the best linear fit
The WinNonlin Toolbox
Nonparametric superposition
331
14
(based on adjusted R-square as in noncompartmental analysis) will be used.
The half life is ln(2)/
z
.
Suppose there are m additional doses D
j
, j = 1,,m, and each dose is adminis-
tered after
j
time units from the first dose. The concentration due to dose D
j

will be C
j
(t) = (D
j
/ D)C(t-
j
), where t is time since the first dose and
C(t-
j
) = 0 for t
j
. The total predicted concentration at time t will be:
Conc(t) =
j
C
j
(t), j=1,2,,m
If the same dose is given at constant dosing intervals , and is sufficiently
large that drug concentrations reflect the post-absorptive and post-distributive
phase of the concentration-time profile, then steady state can be reached after
sufficient time intervals. Let the concentration of the first dose be C
1
(t) for
0 < t < . The concentration at time t after n
th
dose will be:
C
n
(t) = C
1
(t) + exp[-(t+)] + exp[-(t+2)]
++ exp[-(t+(n-1))]
= C
1
(t) + exp[-(t+)]{1-exp[-(n-1)]} / [1-exp(-)]
As n, the steady state (ss) is reached:
C
ss
(t) = C
1
(t) + exp[-(t+)]/[1-exp(-)]
To display the concentration curve at steady state, WinNonlin assumes steady
state is at ten times the half life.
For interpolation, WinNonlin offers two methods: linear interpolation and
log-interpolation. Linear interpolation is appropriate for log-transformed con-
centration data and is calculated by:
C(t) = C(t
i-1
) + [C(t
i
)-C(t
i-1
)]*[t- t
i-1
]/[t
i
- t
i-1
],
t
i-1
< t < t
i
Log-interpolation is appropriate for original concentration data, and is evalu-
ated by:
C(t) = exp{log(C(t
i-1
))+[log(C(t
i
))-log(C(t
i-1
))]*(t-t
i-1
)/(t
i
-t
i-1
)}, t
i-1
< t < t
i
For more information see Appendix E of Gibaldi and Perrier (1982).
WinNonlin
Users Guide
332
14
Performing nonparametric superposition
To perform nonparametric superposition:
1. Make sure that the data set to use is open and active.
2. Select Nonparametric Superposition from the Tools menu. The Nonpara-
metric Superposition dialog appears. The data set name appears in the list box
at the top of the dialog and the variables in the data set appear in the Variables
list.
3. Drag the Time variable to the Time for First Dose field.
4. Drag the Concentration variable to the Concentration for First Dose field.
5. If using sort variables, drag them to the Sort Variables field.
A separate analysis is performed for each unique combination of sort variable
values. During the processing, WinNonlin checks for duplicate time values
and prompts if sort variables have not been specified.
6. Select the number of output data points. The default is 100.
7. Select the method for computationslinear or logarithmic.
8. If the dosing is regular, enter the initial dose in the Initial Dose field.
Enter the maintenance dose.
Enter the value for Tau, the dosing interval, in time units matching
those of the time variable in the data set.
Select whether to display the chart at steady state or at a particular
dose.
The WinNonlin Toolbox
Nonparametric superposition
333
14
or
If the dosing is variable, enter all times and doses. If necessary, copy an entry
by dragging the handle of a cell down in the grid.
If the dosing repeats, click the Repeat every x time units box and
enter the number for the time units.
Enter the values for the output time range.
9. (Optional) Select the Define Terminal Phase check box and enter the start
and end times for the terminal phase.
10. Click Calculate. WinNonlin performs the calculations and generates two new
windows, a Nonparametric Superposition Workbook and a Nonparametric
Superposition Chart.
Output
Nonparametric Superposition generates two products: a workbook containing
predicted concentrations and lambda z values, and a graph of predicted con-
centration over time.
Workbook
The workbook contains two worksheets, Concentrations and Lambda z. The
Concentrations worksheet contains the times and concentrations for each
level of the sort variables. If a regular dosing schedule is selected, this output
represents the times and concentrations between two doses at steady state. If a
variable dosing schedule is selected, the output is the times and concentrations
within the supplied output range. The Lambda z worksheet contains the
lambda z value and the half-life for each sort key.
WinNonlin
Users Guide
334
14
Figure 14-1. The Concentrations worksheet of the NonParametric Superposition
workbook
Figure 14-2. The Lambda z worksheet of the Nonparametric Superposition workbook.
The WinNonlin Toolbox
Semicompartmental modeling
335
14
Chart
The chart generated by Nonparametric Superposition plots Time versus Pre-
dicted Concentration.
Figure 14-3. The Nonparametric Superposition output chart
More information on superposition can be found in Appendix E of Gibaldi
and Perrier (1982).
Units
When the X-variable and Y-variable have units specified, those units are used
and carried through in nonparametric superposition. The output workbook
displays units: Time (in X-units) and Concentration (in Y-units). The output
chart carries units in the axis labels automatically.
There is no ability to enter units or perform conversions with units. As a
result, the dosing interval should be in the same units (X-units) as the input
data.
Semicompartmental modeling
Semicompartmental modeling was proposed by Kowalski and Karim (1995)
for modeling the temporal aspects of the pharmacokinetic-pharmacodynamic
WinNonlin
Users Guide
336
14
relationship of drugs. This model was based on the effect-site link model of
Sheiner et al (1979) to estimate effect-site concentration C
e
by using a piece-
wise linear model for plasma concentration C
p
rather than specifying a PK
model for C
p
. The potential advantage of this approach is reducing the effect
of model misspecification for C
p
when the underlying PK model is unknown.
WinNonlins semicompartmental modeling estimates effect-site concentra-
tions for given times and plasma concentrations and an appropriate value of
keo. This function should be used when a counterclockwise hysteresis is
observed in the graph of effect versus plasma concentrations. The hysteresis
loop collapses with the graph of effect versus effect-site concentrations.
A scientist developing a PK/PD link model based upon simple IV bolus data
can use this function to compute effect site concentrations from observed
plasma concentrations following more complicated administration regimen
without first modeling the data. The results can then be compared to the origi-
nal data sets to determine if the model suitably describes pharmacodynamic
action after the more complicated regimen.
Data and assumptions
Drug concentration in plasma C
p
for each subject is measured at multiple time
points after the drug is administrated. To minimize the bias in estimating C
e
,
the time points need to be adequately sampled such that accurate estimation of
the AUC by noncompartmental methods can be obtained. Effect-site link
model is used and the value of the equilibration rate constant k
eo
that accounts
for the lag between the C
p
and the C
e
curves is required. A piecewise log-lin-
ear model is assumed for C
p
.
Computation method
In the effect-site link model (Sheiner et al 1979), a hypothetical effect com-
partment was proposed to model the time lag between the PK and PD
responses. The effect site concentration C
e
is related to C
p
by first-order dis-
position kinetics and can be obtained by solving the differential equation
where k
eo
is a known constant. In order to solve this equation, one needs to
know C
p
as a function of time, which is usually given by compartmental PK
models.
) (
e p eo
e
C C k
dt
dC
=
The WinNonlin Toolbox
Semicompartmental modeling
337
14
Here, use a piecewise linear model for C
p
C
p
(t) = + (t-t
j-1
) t
j-1
< t < t
j
where = ( )/( t
j
t
j-1
) and .
Using the above two equations can lead to a recursive equation for C
e

The initial condition is C
p
(0) = C
e
(0) =0.
One can also assume a log-linear piecewise PK model for C
p
C
p
(t) = exp[ - (t-t
j-1
)] t
j-1
< t < t
j
where = (ln - ln )/( t
j
- t
j-1
), and
The and are estimated by a linear method, assuming:
C
e
(0) =C
p
(0) = 0.
WinNonlin provides three methods. The linear method uses linear piecewise
PK model; the log method uses log-linear piecewise PK model; the default
log/linear method uses linear to Tmax and then log-linear after Tmax. Effect
field is not used for the calculation of C
e
but when it is provided, the E-C
p
and
E-C
e
plot will be plotted.
Performing semicompartmental modeling
To perform semicompartmental modeling:
1. Make sure that the data set to use is open and active.
2. Select Semicompartmental modeling from the Tools menu. The Semicom-
partmental Modeling dialog appears with the variables from the data set
listed.
3. Drag the appropriate variable to the Time field.
C
p
j 1

j
C
p
j
C
p
j 1
C
p
j 1
C
p
t
j 1
( ) =
) ( ] 1 )[ (
1
) ( ) (
1
1
1
1


+ + =

j j j
t t k
eo
j
p
t t k
e e
t t e
k
C e C C
j j eo
j
j j eo
j j

C
p
j 1

j
C
p
j 1
C
p
j
] [
) ( ) ( ) (
1 1
1
1
1

+ =
j j eo j j j
j
j j eo
j j
t t k t t
j eo
eo
p
t t k
e e
e e
k
k
C e C C

1
C
e
1
WinNonlin
Users Guide
338
14
4. Drag the appropriate variable to the Plasma Concentration field.
5. If effect data are in the data set, drag it to the Effect field.
6. Enter the value for Keo, the equilibration rate constant.
7. (Optional) Drag the appropriate variables to the Sort Variables list.
8. Select the method for computation.
9. Click Calculate. WinNonlin performs the computations and generates a new
workbook and a new chart window.
Output
Workbook
WinNonlin creates a new worksheet with the following data: any sort keys,
Time, Conc, Ce, and Effect (if supplied).
The WinNonlin Toolbox
Semicompartmental modeling
339
14
Figure 14-4. The Semicompartmental Modeling output workbook.
Chart
The chart window contains charts plotting Cp versus Time (figure 14-5) and
Ce versus Time (figure 14-6). If Effect is included in the data set, plots of
Effect versus Cp (figure 14-7) and Effect versus Ce (figure 14-8) are also cre-
ated. The plots are displayed on separate tabs within the chart window.
WinNonlin
Users Guide
340
14
Figure 14-5. Cp vs. Time plot
Figure 14-6. Ce vs. Time plot
The WinNonlin Toolbox
Semicompartmental modeling
341
14

Figure 14-7. E vs. Cp plot
Figure 14-8. E vs. Ce plot
Units
When the input data set has units associated with the X-variable (X-units) and
Y-variable (Y-units), those units are carried through in the calculations in
WinNonlin
Users Guide
342
14
semicompartmental modeling. The workbook output automatically displays
units in the column headers for Time (X-units), Concentration (Y-units),
plasma concentration (Cp) (Y-units), and effect site concentration (Ce) (Y-
units).
When the data set has multiple sort levels, each plot is labeled with the profile
information.
Crossover design
The two-period crossover design is common for clinical trials in which each
subject serves as his or her own control. In many situations the assumptions of
variance homogeneity and normality, relied upon in parametric analyses, may
not be justified due to small sample size, among other reasons. The nonpara-
metric methods proposed by Koch (1972) can be used to analyze such data.
WinNonlins Crossover Design tool performs statistical analysis of data aris-
ing from subjects when variance homogeneity and normality may not neces-
sarily apply. This tool performs nonparametric statistical tests on variables
such as Tmax and provides two categories of results. First, it calculates confi-
dence intervals for each treatment median. It then calculates the median dif-
ference between treatments and the corresponding confidence intervals.
Finally, it estimates the relevance of direct, residual, and period effects.
Data and assumptions
Consider a trial testing the relative effects of two treatments, Test (T) and Ref-
erence (R). Suppose that n subjects are randomly assigned to the TR
sequence, in which subjects are given treatment T first, then treatment R fol-
lowing an adequate washout period. Similarly, m subjects are assigned to the
RT sequence. Y represents the outcome of the trial (for example Cmax or
Tmax) and y
ijk
is the value observed on sequence i (i=1,2), subject j
(j = 1,2,,n, n+1,n+m) and period k (k = 1,2). Treatment is implied by
sequence i and period k, for example i=1 and k=1 is treatment T; i=1 and k=2
is treatment R. The data are listed in columns 1 through 4 of the following
table.
The WinNonlin Toolbox
Crossover design
343
14
Column 5 gives the sum (S) of columns 3 and 4; it is the within-subject sum
of Y for the two periods. Similarly D in column 6 is the within-subject differ-
ence in Y between the two periods.
s
ij
= y
ij1
+ y
ij2
;
d
ij
= y
ij1
- y
ij2
;
C in Column 7 represents the within-subject crossover difference, defined as:
c
ij
= y
ij1
- y
ij2
, if i=1
= y
ij2
- y
ij1
, if i=2
Descriptive analysis
The median response and its confidence interval are calculated for Y of each
treatment and the crossover difference between treatments, C. Let X
(1)
,
X
(2)
,, X
(N)
be the order statistic of samples X
1
, X
2
,, X
N
. The median Xm
is defined as:
Xm = [X
(N/2)
+X
(N/2+1)
]/2, if N is even
= X
[(N+1)/2]
, if N is odd
The 100p% confidence interval (CI) of Xm is defined as follows.
For N <= 20, the exact probability for a binomial distribution is used:
Table 14-1. Representation of the data
Sequence (i) Subject (j) Y
ij1
Y
ij2
S
ij
D
ij
C
ij
TR 1 y
111
y
112
s
11
d
11
c
11
..
TR n y
1n1
y
1n2
s
1n
d
1n
c
1n
RT n+1 y
2(n+1)1
y
2(n+1)2
s
2(n+1)
d
2(n+1)
c
2(n+1)

RT n+m y
2(n+m)1
y
2(n+m)2
s
2(n+m)
d
2(n+1)
c
2(n+1)
WinNonlin
Users Guide
344
14
X
l
= X
(L)
, where L = max
X
u
= X
(U)
, where U = min
The exact probability is .
For N > 20, normal approximation is used:
X
l
= X
(L)
, where L =
X
u
= X
(U)
, where U =
where int(X) returns the largest integer less than or equal to X.
Hypothesis testing
Four hypotheses are of interest:
1. no sequence effect (or drug residual effect);
2. no treatment effect given no sequence effect;
3. no period effect given no sequence effect; and
4. no treatment and no sequence effect.
Hypothesis 1, above, can be tested using the Wilcoxon statistic on the sum S.
If R(S
l
) is the rank of S
ij
in the whole sample, l = 1,.., n+m. The test statistic
is:
i:
N
i
\ .
| |
2
N
i 1 =
N

1 p ( ) 2 <
\ .
|
|
| |
1 +
i:
N
i
\ .
| |
2
N
i 1 =
N

1 p + ( ) 2 >
\ .
|
|
| |
1
N
i
\ .
| |
2
N
i L =
U

int
N
2
---- z
1 p +
2
------------
N
2
--------

\ .
|
| |
1 +
N int
N
2
---- z
1 p +
2
------------
N
2
--------

\ .
|
| |

The WinNonlin Toolbox


Crossover design
345
14
T = min ( , )
The p-value is evaluated by using normal approximation (Conover, 1980):
[T - n(n+m+1)/2] / ~N(0,1)
Similarly, hypothesis 2 can be tested using the Wilcoxon statistic on the dif-
ference D; hypothesis 3 can be tested using the Wilcoxon statistic on the
crossover difference C. The statistics are in the form described above.
Hypothesis 4 can be tested using the bivariate Wilcoxon statistic on (Y
ij1
,
Y
ij2
). For each period k, let R
ijk
equal:
rank { y
ijk
: y
11k
, , y
1nk
, y
2(n+1)k
, , y
2(n+m)k
}
The average rank for each sequence is
= , where j=1,, n
i
, n
i
=n for i=1, and n
i
=m for i=2.
Thus, the statistic to be used for testing hypothesis 4 is:
L = (n+m-1)[nU
1
T
*S
-1
*U
1
+ mU
2
T
*S
-1
*U
2
]
Where U
i
is a 2x1 vector:
[ -M, -M]
T
, M= (n+m+1)/2
S is the 2x2 covariance matrix:
S =

and L ~ chi-square(2), so the p-value can be evaluated.
R
l
l 1 =
n

R
l
l n 1 + =
n m +

nm n m 1 + + ( ) 12
R
ik
R
i j k
n
i

j 1 =
n
i

R
i 1
R
i 2

j
R
i j 1
M ( )
2
R
i j1
M ( ) R
i j2
M ( )
R
i j1
M ( ) R
i j 2
M ( ) R
i j2
M ( )
2
WinNonlin
Users Guide
346
14
Using the Crossover Design tool
To utilize crossover design:
1. Make sure that the data set to use is open and active.
2. Select Crossover Design from the Tools menu. The Crossover Design dialog
appears.
3. Select whether the treatment data are in separate columns or stacked in the
same column. For this illustration it is assumed that the treatment data are
stacked in the same column.
4. Drag the subject variable from the Variables list box to the Subject field.
5. Drag the sequence variable from the Variables list to the Sequence field.
6. Drag the treatment variable from the Variables list to the Treatment field.
7. Drag the response variable from the Variables list to the Response field.
8. (Optional) If using Sort variables, to identify individual data profiles, drag
them to that field.
9. Click Calculate. WinNonlin performs the calculations and generates a new
workbook as output.
Output
Crossover Design creates only one form of output, a new workbook with mul-
tiple worksheets. See figures 14-9 and 14-10.
The WinNonlin Toolbox
Crossover design
347
14
Figure 14-9. The Crossover Design output workbook.
The first sheet lists the confidence intervals (at 80%, 90%, and 95%) for the
treatment medians in the crossover data and the treatment difference median.
Figure 14-10. The Effects tab of the Crossover Design workbook.
WinNonlin
Users Guide
348
14
The second sheet is labeled Effects. It lists the test statistic and p-value associ-
ated with each of four tests.
Units
When the input data set has units associated with the X-variable (X-units) and
Y-variable (Y-units), those units are carried through in the calculations in
crossover design. The output workbooks display units in the median, lower,
and upper value parameters. Only the X- and Y-variables carry units.
Deconvolution
Deconvolution is used to evaluate in vivo drug release and delivery when data
from a known drug input are available. Depending upon the type of reference
input information available, the drug transport evaluated will either be a sim-
ple in vivo drug release (e.g., gastro-intestinal release) or it will be a compos-
ite form, typically consisting of an in vivo release followed by a drug delivery
to the general systemic circulation. See Using deconvolution on page 356
for instructions on performing deconvolution.
Perhaps the most common application of deconvolution is in the evaluation of
drug release and drug absorption from orally administered drug formulations.
In this case, the bioavailability is evaluated if the reference input is a vascular
drug input. Similarly, gastro-intestinal release is evaluated if the reference is
an oral solution (oral bolus input).
The Deconvolution feature is not limited in scope to drug delivery via the oral
route. It considers other types of delivery, including transdermal release and
delivery, drug delivery from implanted devices, etc.
Deconvolution provides automatic calculation of the drug input. It also allows
the user to direct the analysis to investigate issues of special interest through
different parameter settings and program input.
Deconvolution methodology
The methodology is based on linear system analysis with linearity defined in
the general sense of the linear superposition principle. It is well recognized
that classical linear compartmental kinetic models exhibit superposition lin-
earity due to their origin in linear differential equations. However, all kinetic
models defined in terms of linear combinations of linear mathematical opera-
The WinNonlin Toolbox
Deconvolution
349
14
tors (e.g. differentiation, integration, convolution, deconvolution, etc.) consti-
tute linear systems adhering to the superposition principle. The scope and
generality of the linear system approach thus ranges far beyond linear com-
partmental models. To fully appreciate the power and generality of the linear
system approach, it is best to depart from the typical, physically structured
modeling view of pharmacokinetics. To cut through all the complexity and
objectively deal with the present problems, it is best to consider the kinetics of
drug transport in a non-parametric manner and simply use stochastic transport
principles in the analysis.
Convolution/deconvolution - stochastic background
The convolution/deconvolution principles applied to evaluate drug release
and drug input (absorption) can be explained in terms of point A to point B
stochastic transport principles. For example, consider the entry of a single
drug molecule at point A at time 0. Let B be a sampling point (a given sam-
pling space or volume) anywhere in the body (e.g. a blood sampling) that can
be reached by the drug molecule entering at A. The possible presence of the
molecule at B at time t is a random variable due to the stochastic transport
principles involved. Imagine repeating this one molecule experiment an infi-
nite number of times and observing the fraction of times that the molecule is
at B at time t. That fraction represents the probability that a molecule is at
point B given that it entered point A at time 0. Denote this probability by the
function g(t).
Next, consider a simultaneous entry a very large number (N) of drug mole-
cules at time 0, e.g., a bolus injection. Let it be assumed that there is no signif-
icant interaction between the drug molecules, such that the probability of a
drug molecule's possible arrival at sampling site B is not significantly affected
by any other drug molecule. Then the transport to sampling site B is both ran-
dom and independent. In addition the probability of being at B at time t is the
same and equals g(t) for all of the molecules. It is this combination of inde-
pendence and equal probability that leads to the superposition property that in
its most simple form reveals itself in terms of dose-proportionality. For exam-
ple, in the present case the expected number of drug molecules to be found at
sampling site B at time t (N
B
(t)) is equal to Ng(t). It can be seen from this that
the concentration of drug at the sampling site B at the arbitrary time t is pro-
portional to the dose (N is proportional to the dose and g(t) does not depend
on the dose due to the independence in the transport).
Now let's further assume that the processes influencing transport from A to B
are constant over time. The result is that the probability of being at point B at
time t depends on the elapsed time since entry at A, but is otherwise indepen-
WinNonlin
Users Guide
350
14
dent of the entry time. Thus the probability of being at B for a molecule that
enters A at time t
A
is g(t-t
A
). This assumed property is called time-invariance.
Consider again the simultaneous entry of N molecules, but now at time t
A

instead of 0. Combining this property with those of independent and equal
probabilities, i.e., superposition, results in an expected number of molecules
at B at time t given by N
B
(t) = Ng(t-t
A
).
Suppose that the actual time at which the molecule enters point A is unknown.
It is instead a random quantity t
A
distributed according to some probability
density function h(t), i.e.,

The probability that such a molecule is at point B at time t is the average or
expected value of g(t-t
A
) where the average is taken over the possible values
of t
A
according to
Causality dictates that g(t) must be 0 for any negative times, i.e., a molecule
can't get to B before it enters A. For typical applications drug input is
restricted to non-negative times so that h(t) = 0 for t < 0. As a result
is nonzero only over the range from 0 to t and the equation
becomes
Suppose again that N molecules enter at point A but this time they enter at
random times distributed according to h(t). This is equivalent to saying that
the expected rate of entry at A is given by . As argued
before, the expected number of molecules at B at time t is the product of N
and the probability of being at B at time t, i.e.,
Converting from number of molecules to mass units:
Pr t
A
t ( ) h u ( ) u d
0
t


=
A A A
dt t h t t g t g ) ( ) ( ) (
g t t
A
( )h t
A
( )

=
t
A A A
dt t h t t g t g
0
) ( ) ( ) (
N
A
t ( ) Nh t ( ) =

= = =
t
A A A A
t
A A A B
dt t N t t g dt t h t t g N t g N t N
0 0
) ( ) ( ) ( ) ( ) ( ) (
The WinNonlin Toolbox
Deconvolution
351
14
where M
B
(t) is the mass of drug at point B at time t and f(t) is the rate of entry
in mass per unit time into point A at time t.
Let V
s
denote the volume of the sampling space (point B). Then the concen-
tration, c(t), of drug at B is
where * is used to denote the convolution operation and
The above equation is the key convolution equation that forms the basis for
the evaluation of the drug input rate, f(t). The function is denoted the
unit impulse response (a.k.a. characteristic response or disposition function).
The process of determining the input function f(t) is called deconvolution
because it is required to deconvolve the convolution integral in order to
extract the input function that is embedded in the convolution integral.
The unit impulse response ( ) function provides the exact linkage between
drug level response c(t) and the input rate function f(t). is simply equal to
the probability that a molecule entering point A at t = 0 is present in the sam-
pling space at time t divided by the volume of that sample space.
The function representation
WinNonlin models the input function as a piecewise linear precursor func-
tion f
p
(t) convolved with an exponential dispersion function f
d
(t). The
former provides substantial flexibility whereas the latter provides smoothness.
The piecewise linear component is parameterized in terms of a sum of hat-
type wavelet basis functions, h
j
(t):

=
t
A A A B
dt t f t t g t M
0
) ( ) ( ) (

=
t
t c t f du u c u t f t c
0
) ( ) ( ) ( ) ( ) (

c

t ( ) g t ( ) V
s
=
c

t ( )
c

0 ) ( ) ( =
j j
j
p
x t h x t f
WinNonlin
Users Guide
352
14
where T
j
are the wavelet support points. The hat-type wavelet representation
enables discontinuous, finite duration drug releases to be considered together
with other factors that result in discontinuous delivery, such as stomach emp-
tying, absorption window, pH changes, etc. The dispersion function provides
the smoothing of the input function that is expected from the stochastic trans-
port principles governing the transport of the drug molecules from the site of
release to subsequent entry to and mixing in the general systemic circulation.
The wavelet support points (T
j
) are constrained to coincide with the observa-
tion times, with the exception of the very first support point that is used to
define the lag-time, if any, for the input function. Furthermore, one support
point is injected halfway between the lag-time and the first observation. This
point is simply included to create enough capacity for drug input prior to the
first sampling. Having just one support point prior to the first observation
would limit this capacity. The extra support point is well suited to accommo-
date an initial burst release commonly encountered for many formulations.
The dispersion function f
d
(t) is defined as an exponential function:
where is denoted the dispersion or smoothing parameter. The dispersion
function is normalized to have a total integral ( ) equal one, which
explains the scaling with the parameter. The input function, f(t), is the con-
volution of the precursor function and the dispersion function:
The general convolution form of the input function above is consistent with
stochastic as well as deterministic transport principles. The drug level profile,
c(t), resulting from the above input function is, according to the linear disposi-
tion assumption, given by:
otherwise , 0
), /( ) (
), /( ) ( ) (
2 1
1
1 2 2
1
+ +
+
+ + +
+
<
< <
=
=
=
j j
j j
j j j
j j j j
T t T
T t T
T T t T
T T T t t h

/
) (
t
d
e
t f

=
t 0 to =

=
t
d p d p
du u f u t f t f t f t f
0
) ( ) ( ) ( ) ( ) (
The WinNonlin Toolbox
Deconvolution
353
14
where * is used to denote the convolution operation.
Convolution methodology
WinNonlin deconvolution uses the basic principle of deconvolution through
convolution (DTC) to determine the input function. The DTC method is an
iterative procedure consisting of three steps. First, the input function is
adjusted by changing its parameter values. Second, the new input function is
convolved with to produce a calculated drug level response. Third, the
agreement between the observed data and the calculated drug level data is
quantitatively evaluated according to some objective function. The three steps
are repeated until the objective function is optimized. DTC methods differ
basically in the way the input function is specified and the way the objective
function is defined. The objective function may be based solely on weighted
or unweighted residual values (observedcalculated drug levels). The purely
residual-based DTC methods ignore any behavior of the calculated drug level
response between the observations.
The more modern DTC methods, including WinNonlins approach, consider
both the residuals and other properties such as smoothness of the total fitted
curve in the definition of the objective function. The deconvolution method
implemented in WinNonlin is novel in the way the regularization (smoothing)
is implemented. Regularization methods in some other deconvolution meth-
ods are done through a penalty function approach that involves a measure-
ment of the smoothness of the predicted drug level curve (e.g. integral of
squared second derivative). The WinNonlin deconvolution method instead
introduces the regularization directly into the input function through a convo-
lution operation with the dispersion function, f
d
(t). In essence, a convolution
operation acts like a washout of details, i.e. a smoothing due to the mixing
operation inherent in the convolution operation. Consider, for example, the
convolution operation that leads to the drug level response c(t). Due to the sto-
chastic transport principles involved, the drug level at time t is made up of a
mixture of drug molecules that started their journey to the sampling site at dif-
ferent times and took different lengths of time to arrive there. Thus, the drug
level response at time t depends on a mixture of prior input. It is exactly this
mixing in the convolution operation that provides the smoothing. The convo-
lution operation acts essentially as a low pass filter with respect to the filtering
of the input information. The finer details (higher frequencies) are attenuated
relative to the more slowly varying components (low frequency components).
) ( ) ( ) ( ) ( t c t f t f t c
d p
=
c

t ( )
WinNonlin
Users Guide
354
14
Thus, the convolution of the precursor function with the dispersion function
results in an input function, f(t), that is smoother than the precursor function.
WinNonlin allows the user to control the smoothing through the use of the
smoothing parameter . Decreasing the value of the dispersion function
parameter results in a decreasing degree of smoothing of the input function.
Similarly, larger values of provide more smoothing. As approaches 0, the
dispersion function becomes equal to the so-called Dirac delta function,
resulting in no change in the precursor function.
The smoothing of the input function, f(t), provided by the dispersion function,
f
d
(t), is carried forward to the drug level response in the subsequent convolu-
tion operation with the unit impulse response function ( ). Smoothing and
fitting flexibility are inversely related. Too little smoothing (too small a
value) will result in too much fitting flexibility that results in a fitting to the
error in the data. In the most extreme case, the result is an exact fitting to the
data. Conversely, too much smoothing (too large a value) results in too little
flexibility so that the calculated response curve becomes too stiff or
stretched out to follow the underlying true drug level response.
Cross validation principles
WinNonlin's deconvolution function determines the optimal smoothing with-
out actually measuring the degree of smoothing. The degree of smoothing is
not quantified but is controlled through the dispersion function to optimize the
consistency between the data and the estimated drug level curve. Consis-
tency is defined here according to the cross validation principles. Let r
j
denote
the differences between the predicted and observed concentration at the j-th
observation time when that observation is excluded from the data set. The
optimal cross validation principle applied is defined as the condition that
leads to the minimal predicted residual sum of squares (PRESS) value, where
PRESS is defined as:
For a given value of the smoothing parameter , PRESS is a quadratic func-
tion of the wavelet scaling parameters x. Thus, with the non-negativity con-
straint x > 0, the minimization of PRESS for a given value is a quadratic
programming problem which has a unique solution that can be determined
numerically. Let PRESS () denote such a solution. The optimal smoothing is
then determined by finding the value of the smoothing parameter that mini-
c

=
=
m
j
j
r PRESS
1
2
The WinNonlin Toolbox
Deconvolution
355
14
mizes PRESS (). This is a one variable optimization problem with an embed-
ded quadratic-programming problem.
User control over execution
WinNonlin's deconvolution function permits the user to override the auto-
matic smoothing by manual setting of the smoothing parameter. The user may
also specify that no smoothing should be performed. In this case the input rate
function consists of the precursor function alone.
Besides controlling the degree of smoothing, the user may also influence the
initial behavior of the estimated input time course. In particular the user may
choose to constrain the initial input rate to 0 ( ) and/or constrain the
initial change in the input rate to 0 ( ). By default WinNonlin does
not constrain either initial condition. Leaving unconstrained permits bet-
ter characterization of formulations with rapid initial burst release, e.g.,
extended release dosage forms with an immediate release shell. This is done
by optionally introducing a bolus component (or integral boundary condi-
tion) for the precursor function so the input function becomes:
where the * is defined as before. The difference here is the superpo-
sition of the extra term that represents a particularly smooth compo-
nent of the input. The magnitude of this component is determined by the
scaling parameter , which is determined in the same way as the other wave-
let scaling parameters previously described.
The estimation procedure is not constrained with respect to the relative mag-
nitude of the two terms of the composite input function given above. Accord-
ingly, the input can collapse to the bolus component and thus
accommodate the simple first order input commonly experienced when deal-
ing with drug solutions or rapid release dosage forms. A drug suspension in
which a significant fraction of the drug may exist in solution should be well
described by the composite input function option given above. The same may
be the case for dual release formulations designed to rapidly release a portion
of the drug initially and then release the remaining drug in a prolonged fash-
ion. The prolonged release component will probably be more erratic and
would be described better by the more flexible wavelet-based component
f
p
(t)*f
d
(t) of the above dual input function.
f 0 ( ) 0 =
f 0 ( ) 0 =
f 0 ( )
) ( ) ( ) (
) ( )) ( ) ( ( ) (
t f x t f t f
t f t x t f t f
d d p
d p

+ =
+ =
f
p
t ( ) f
d
t ( )
x

f
d
t ( )
x

f
d
t ( )
WinNonlin
Users Guide
356
14
Constraining the initial rate of change to 0 ( ) introduces an initial
lag in the increase of the input rate that is more continuous in behavior than
the usual abrupt lag time. This constraint is obtained by constraining the ini-
tial value of the precursor function to 0 ( ). When such a con-
strained precursor is convolved with the dispersion function, the resulting
input function has the desired constraint.
The extent of drug input
The extent of drug input in the Deconvolution module is presented in two
ways. First, the amount of drug input is calculated as:
Second, the extent of drug input is given in terms of fraction input, where the
fraction is defined in a non-extrapolated way as the fraction of drug input at
time t relative to the amount input at the last sample time, t
end
:
The above fraction input will by definition have a value of 1 at the last obser-
vation time, t
end
. This value should not be confused with the fraction input
relative to either the dose or the total amount absorbed from a reference dos-
age form.
Using deconvolution
Deconvolution is available from the Tools menu when a data set is loaded in
the active window.
To use Deconvolution with a data set,
1. Select Deconvolution from the Tools menu. The Deconvolution dialog
appears with two tabs.
2. On the Variables tab, be sure that the appropriate data set appears in the drop-
down list box. Then drag the appropriate variables to the Time and Concen-
tration fields.
f 0 ( ) 0 =
f
p
0 ( ) 0 =

=
t
dt t f
0
) ( input Amount

=
t
t
end
dt t f dt t f
0 0
) ( / ) ( input Fraction
The WinNonlin Toolbox
Deconvolution
357
14
3. If using sort variables, drag one or more to the Sort Variable field. A separate
analysis is done for every unique combination of sort variable values.
4. (Optional) Enter the dosing units in the Dose units field. The dosing units are
utilized only when the input data set has units associated with the Time and
Concentration data.
5. Select the Settings tab.
6. The unit impulse response function is assumed to have the form:
Select the number of exponential terms (N) in the unit impulse response. This
number must be from 1 to 9. The default is 1.

=
N
j
t alpha
j
i
e A t c
1
) (

WinNonlin
Users Guide
358
14
Note: When a value greater than 1 is entered, the grid for the values of A and alpha
automatically expands so that those values can be entered.
7. Enter the values for A and alpha in the unit impulse response function. If
these values are not available but time and concentration data that describe the
unit impulse response function are available, then WinNonlin can be run using
this data with models 1, 8, or 18 (for N=1, 2, or 3) to find the parameters that
best fit the data.
8. Select the setting for Smoothing to use. The choices are explained below.
Automatic should be selected if the user wants the program to find the
optimal value for the dispersion parameter delta. This is the default.
None should be selected if the user wants to disable the smoothing that
comes from use of the dispersion function. If checked, the input function
is just the piecewise linear precursor function.
User-Specified should be selected if the user wants to specify the value of
the dispersion parameter delta to be used. Increasing delta increases the
amount of smoothing. Decreasing delta decreases the smoothing; how-
ever delta must be greater than 0.
Note: When either Automatic or User-Specified smoothing is selected, Initial Rate
is 0 is unchecked and Initial Change in Rate is 0 is grayed out. If Initial Rate is
0 is selected, then Initial Change in Rate is 0 becomes available.
When None is selected, Initial Rate is 0 is unchecked and Initial Change in
Rate is 0 is grayed out. If Initial Rate is 0 is checked, Initial Change in Rate is
0 remains unavailable.
9. Select the Initial Rate is Zero check box to constrain the estimated input rate
to be zero at the initial time (lag time).
10. Select the Initial Change in Rate is Zero check box to constrain the deriva-
tive of the estimated input rate to be zero at the initial time (lag time).
11. Accept or change the Number of output data points. The default is 101. The
maximum is 1001.
12. The default setting is Workbook output from 0 to last time point. Leave
this checked to have the output grid start with time zero and end with the last
time point in the input data set.
The WinNonlin Toolbox
Deconvolution
359
14
13. (Optionally) Select Workbook output from [ ] to [ ] to have the output grid
start and end with the times entered in the fields.
14. Click Calculate. Deconvolution generates a new chart and workbook.
Deconvolution output
Workbook
The deconvolution workbook contains one workbook with three worksheets.
The Values worksheet includes values for Time, Input Rate, Cumulative Input
and Fraction Input for each sort key. The Parameters worksheet lists the
smoothing parameter delta, absorption lag time, first output time point, and
last output time point for each profile. This allows the user to use the auto-
matic smoothing function of data sets with multiple profiles then manually
revise the settings for further estimation. The Settings worksheet includes data
about input settings (for A, alpha, the smoothing setting, and the number of
output points).
Figure 14-11. The Values worksheet of a Deconvolution workbook
WinNonlin
Users Guide
360
14
Note: If the input variables and dosing use units, they are displayed in the output
headers. If any header is missing units, no units are displayed for any column.
Chart
Deconvolution generates three charts for each sort key.
The WinNonlin Toolbox
Deconvolution
361
14
The Fitted Curve output plot depicts concentration data from the input data set
plotted against time.
The Input Rate plot depicts rate of drug input against time for each profile.
WinNonlin
Users Guide
362
14
The Cumulative Input plot displays cumulative drug input against time for
each profile.
363
Chapter 15
Linear Mixed Effects
Modeling
ANOVA, ANCOVA, and regression models
The Linear Mixed Effects function (LinMix) performs analyses using linear
mixed effects models. It is a statistical analysis system for analysis of variance
for crossover and parallel studies, including unbalanced designs. It can ana-
lyze regression models and covariance models, and can calculate both sequen-
tial tests and partial tests.
Since linear mixed effects modeling is most easily introduced using an exam-
ple, this section will start by creating a statistical model for a common experi-
mental design that utilizes several error terms, as well as classical ANOVA
modeling terms (An example below). The general theory will then be dis-
cussed more fully in The linear mixed effects model on page 366.
An example
The following example is used as a framework for discussing the functions
and computations of the Linear Mixed Effects Modeling wizard.
An investigator wants to estimate the difference between two treatments for
blood pressure, labeled A and B. Because the responses are fairly heteroge-
neous among different people, the investigator has decided that each study
subject will be their own control, which should increase the power of the
study. Therefore, each subject will be exposed to both treatments A and B.
Since the order of the treatments might affect the outcome, half the subjects
will receive A first, and the other half will receive B first.
For the analysis, note that this crossover study has two periods, 1 and 2, and
two sequence groups AB and BA. The model will be of the form:
y
ijkm
= +
i
+
j
+
q
+ S
k(j)
+
ijkm
(1)
WinNonlin
Users Guide
364
15
where:
i = period index (1 or 2)
j = sequence index (AB or BA)
k = subject within sequence group index (1 n
j
)
m = observation within subject index (1, 2)
q = treatment index (1, 2)
= intercept

i
= effect due to period

j
= effect due to sequence grouping

q
= effect due to treatment, the purpose of the study
S
k(j)
= effect due to subject

ijkm
= random variation
Typically,
ijkm
is assumed to be normally distributed with mean 0 and vari-
ance
2
> 0. The purpose of the study is to estimate
1
-
2
in all people with
similar inclusion criteria as the study subjects. Study subjects are assumed to
be randomly selected from the population at large. Therefore, it is desirable to
treat subject as a random effect. Hence, assume that subject effect is normally
distributed with mean 0 and variance Var(S
k(j)
) 0.
This mixing of the regression model and the random effects is known as a
mixed effect model. The mixed effect model allows one to model the mean of
the response as well as the variance of the response. Note that in model (1),
the mean of the response is:
and the variance is given by:
The part represented by E{y
ijkm
}is known as the fixed effects of the model,
while S
k(j)
+
ijkm
constitutes the random effects of the model, since these
terms represent random variables whose variances are to be estimated. A
model with only the residual variance is known as a fixed effect model. A
model without the fixed effects is known as a random effect model. A model
with both is a mixed effect model.
E{y
ijkm
} = +
i
+
j
+
q
(2)
Var{y
ijkm
} = Var{S
k(j)
}+
2
.
(3)
Linear Mixed Effects Modeling
An example
365
15
The data are shown in Table 15-1. The LinMix wizard is used to analyze these
data. The fixed and random effects of the model are entered on different pages
of the wizard. This is appropriate since the fixed effects model the mean of the
response, while the random effects model the variance of the response.
Table 15-1. Data for the example
Subject Sequence Period Treatment Response
1 AB 1 A 9.70
2 AB 1 A 10.24
3 AB 1 A 11.2
4 AB 1 A 7.82
5 AB 1 A 11.1
6 AB 1 A 9.31
7 BA 2 A 9.02
8 BA 2 A 7.88
9 BA 2 A 9.6
10 BA 2 A 9.63
11 BA 2 A 9.63
12 BA 2 A 9.91
7 BA 1 B 8.15
8 BA 1 B 9.23
9 BA 1 B 9.43
10 BA 1 B 10.13
11 BA 1 B 9.67
12 BA 1 B 11.34
1 AB 2 B 8.72
2 AB 2 B 11.28
3 AB 2 B 11.73
4 AB 2 B 9.77
5 AB 2 B 8.91
6 AB 2 B 8.31
WinNonlin
Users Guide
366
15
LinMix can fit linear models to Gaussian data. The mean and variance struc-
tures can be simple or complex, as the need arises. Independent variables can
be either continuous or discrete, and no distributional assumption is made
about the independent variables.
This model provides a context for The linear mixed effects model.
The linear mixed effects model
WinNonlins Linear Mixed Effects Modeling feature is based on the general
linear mixed effects model, which can be represented in matrix notation as:
y = X + Z +
where:
X is a matrix of known constants and the design matrix for ,
is a vector of unknown (fixed effect) parameters,
is a random unobserved vector (the vector of random-effects
parameters), normally distributed with mean 0 and variance G,
Z is a matrix of known constants, the design matrix for ,
and is a random vector, normally distributed with mean 0 and
variance R.
Linear Mixed Effects Modeling
The linear mixed effects model
367
15
and are uncorrelated. In the LinMix wizard, the fixed effects dialog speci-
fies the model terms for constructing X; the random effects tabs in the Vari-
ance Structure dialog specifies the model terms for constructing Z and the
structure of G; and the repeated tab specifies the structure of R.
The LinMix wizard breaks the model into the following areas:
Note: In the linear mixed effects model, if R =
2
I and Z = 0, then the LinMix
model reduces to the ANOVA model. Using the assumptions for the linear
mixed effects model, one can show that the variance of y is:
If , i.e., if the model includes one or more random effects, the G matrix
is determined by the variance structures specified for the random models. If
the model includes a repeated specification, then the R matrix is determined
by the variance structure specified for the repeated model. If the model does
not include a repeated specification, then R is the residual variancethat is,
R =
2
I.
It is instructive to see how a specific example (An example on page 363)
fits into this framework. The fixed effects model is shown in equation 2
above. Listing all the parameters in a vector, one obtains:

T
= [,
1
,
2
,
1
,
2
,
1
,
2
]
For each element of , there is a corresponding column in the X matrix. In this
model, the X matrix is composed entirely of 1s and 0s. The exact method of
constructing the X matrix is discussed in the section Construction of X matrix,
below.
For each subject, there is one S
k(j)
. The collection can be directly entered into
. The Z matrix will consist of 1s and 0s. Element (i, j) will be 1 when obser-
vation i is from subject j, and 0 otherwise. The variance of is of the form
G Var() = Var{S
k(j)
} I
n(1)+n(2)
Fixed effects Contrasts
Variance structure Estimates
Least squares means
V ZGZ
T
R + =
Z 0
WinNonlin
Users Guide
368
15
where I
b
represents a bb identity matrix. The parameter to be estimated for G
is Var{S
k(j)
}. The residual variance is
R = Var{
ijkm
} =
2
I
2[n(1)+n(2)]
The parameter to be estimated for R is
2
.
A summary of the wizard pages and the part of the model they generate is
listed below. The details will be discussed later.
Construction of the X matrix
A term is a variable or a product of variables. A user specifies a model by giv-
ing a sum of terms. For example, if A and B are variables in the data set, the
user might specify:
A + B + A*B.
LinMix takes this sum of terms and constructs the X matrix. The way this is
done depends upon the nature of the variables A and B.
The No Intercept
option
By default, the first column of X contains all ones. This column is referenced
as the intercept in the wizard. The column of ones may be left out by checking
the No Intercept box in the Fixed Effects dialog of the LinMix wizard. The
rules for translating terms to columns of the X matrix depend upon the vari-
able types, regressor/covariate or classification. This will be demonstrated
using two classification variables, Drug and Form, and two continuous vari-
ables, Age and Weight, given in Table 15-2. A term consisting of a single con-
tinuous variable causes a single column to be placed in the X matrix.
An integer value is associated with every level of a classification variable.
The association between levels and codes is determined by the numerical
order for converted numerical variables and by the character collating
sequence for converted character variables. When a single classification vari-
able is specified for a model, an indicator variable is placed in the X matrix for
each level of the variable. Table 15-3 demonstrates this for the variable Drug.
Wizard Page Specifies Tabs on page Creates
Fixed Effects Page Specifies X matrix Generates
Variance
Structure Page
Specifies Z matrix Random tabs (1 or more) Generates G = var()
Repeated tab (exactly 1) Generates R = var()
Linear Mixed Effects Modeling
The linear mixed effects model
369
15
The model specification allows for products of variables. The product of two
continuous variables is the ordinary product within each row. The product of a
classification variable with a continuous variable is obtained by taking the
product of the continuous value with each column of the set of indicator vari-
ables in each row. For example, the product of Drug and Age is displayed in
Table 15-3. Two classification variables and their indicator variables are dis-
played in Table 15-4. Their product is shown in Table 15-5.
The product operations described in the preceding paragraph can be suc-
cinctly defined using the Kronecker product
A
. For example, consider the fifth
row of Table 15-3. The product of Drug and Age is:
[0 1 0] [45] = [ 0 45 0].
Now consider the fifth row of Table 15-4. The product of Drug and Form is:
[0 1 0] [1 0 0 0] = [0 0 0 0 1 0 0 0 0 0 0 0]
The result is the fifth row of Table 15-5.
A. Let A = (a
ij
) be a mn matrix and let B = (b
ij
) be a pq matrix. Then the Kronecker product
A B = (a
ij
B)
is an mp nq matrix expressible as a partitioned matrix with a
ij
B as the (i, j)th partition, i=1,
, m and j=1,,n.
Table 15-2. Variables in sample data set
Drug Form Age Weight
name value name value
DrugA 0 capsule 0 48 120
DrugA 0 drops 1 34 124
DrugA 0 syrup 2 27 123
DrugA 0 tablet 3 23 172
DrugB 1 capsule 0 45 200
DrugB 1 drops 1 26 150
DrugB 1 syrup 2 41 120
DrugB 1 tablet 3 32 130
DrugC 2 capsule 0 38 190
DrugC 2 drops 1 17 125
WinNonlin
Users Guide
370
15

DrugC 2 syrup 2 32 175
DrugC 2 tablet 3 23 150
Table 15-2. Variables in sample data set (continued)
Drug Form Age Weight
name value name value
Table 15-3. Indicator variables and a product of a classification variable with a continuous
variable
Drug Indicator variables Age Drug* Age
Name value DrugA DrugB DrugC DrugA DrugB DrugC
DrugA 0 1 0 0 48 48 0 0
DrugA 0 1 0 0 34 34 0 0
DrugA 0 1 0 0 27 27 0 0
DrugA 0 1 0 0 23 23 0 0
DrugB 1 0 1 0 45 0 45 0
DrugB 1 0 1 0 26 0 26 0
DrugB 1 0 1 0 41 0 41 0
DrugB 1 0 1 0 32 0 32 0
DrugC 2 0 0 1 38 0 0 38
DrugC 2 0 0 1 17 0 0 17
DrugC 2 0 0 1 32 0 0 32
DrugC 2 0 0 1 23 0 0 23
Table 15-4. Two classification variables and their indicator variables
Drug Indicators Form Indicators
name value DrugA DrugB DrugC name value capsule drops syrup tablet
DrugA 0 1 0 0 capsule 0 1 0 0 0
DrugA 0 1 0 0 drops 1 0 1 0 0
DrugA 0 1 0 0 syrup 2 0 0 1 0
DrugA 0 1 0 0 tablet 3 0 0 0 1
Linear Mixed Effects Modeling
The linear mixed effects model
371
15

Linear combinations of elements of
Most of the inference done by LinMix is done with respect to linear combina-
tions of elements of . Consider, as an example, the model where the expected
value of the response of the j
th
subject on the i
th
treatment is:
DrugB 1 0 1 0 capsule 0 1 0 0 0
DrugB 1 0 1 0 drops 1 0 1 0 0
DrugB 1 0 1 0 syrup 2 0 0 1 0
DrugB 1 0 1 0 tablet 3 0 0 0 1
DrugC 2 0 0 1 capsule 0 1 0 0 0
DrugC 2 0 0 1 drops 1 0 1 0 0
DrugC 2 0 0 1 syrup 2 0 0 1 0
DrugC 2 0 0 1 tablet 3 0 0 0 1
Table 15-4. Two classification variables and their indicator variables (continued)
Drug Indicators Form Indicators
name value DrugA DrugB DrugC name value capsule drops syrup tablet
Table 15-5. Product of the two classification variables
Drug Form Indicator
DrugA capsule 1 0 0 0 0 0 0 0 0 0 0 0
DrugA drops 0 1 0 0 0 0 0 0 0 0 0 0
DrugA syrup 0 0 1 0 0 0 0 0 0 0 0 0
DrugA tablet 0 0 0 1 0 0 0 0 0 0 0 0
DrugB capsule 0 0 0 0 1 0 0 0 0 0 0 0
DrugB drops 0 0 0 0 0 1 0 0 0 0 0 0
DrugB syrup 0 0 0 0 0 0 1 0 0 0 0 0
DrugB tablet 0 0 0 0 0 0 0 1 0 0 0 0
DrugC capsule 0 0 0 0 0 0 0 0 1 0 0 0
DrugC drops 0 0 0 0 0 0 0 0 0 1 0 0
DrugC syrup 0 0 0 0 0 0 0 0 0 0 1 0
DrugC tablet 0 0 0 0 0 0 0 0 0 0 0 1
WinNonlin
Users Guide
372
15
where is a common parameter and +
i
is the expected value of the i
th
treat-
ment. Suppose there are three treatments. The X matrix has a column of ones
in the first position followed by three treatment indicator variables. The vec-
tor is:
= [
0

1

2

3
]
= [
1

2

3
]
The first form is for the general representation of a model. The second form is
specific to model (4) above.
The expression:
with the l
j
constant, is called a linear combination of the elements of . The
range of the subscript j starts with 0 if the intercept is in the model and starts
with 1 otherwise. Most common functions of the parameters, such as +
1
,

1
-
3
, and
2
, can be generated by choosing appropriate values of the l
j
. Lin-
ear combinations of are entered in LinMix through the estimate and contrast
pages of the wizard. A linear combination of is said to be estimable if it can
be expressed as a linear combination of expected responses. In the context of
model 4, a linear combination of the elements of is estimable if it can be
generated by choosing c
1
, c
2
, and c
3
.
Note that c
1
=1, c
2
=0, and c
3
=0 generates +
1
, so +
1
is estimable. A
rearrangement of expression (6) is:
The form in (7) makes some things more obvious. For example, l
j
= c
j
for
j=1,2,3. Also, any linear combination involving only s is estimable if, and
+
i
(4)
(5)
c
1
( +
1
) + c
2
( +
2
) + c
3
( +
3
). (6)
(c
1
+ c
2
+ c
3
) + c
1

1
+ c
2

2
+ c
3

3
. (7)
l
j

j
j

Linear Mixed Effects Modeling


The linear mixed effects model
373
15
only if, l
1
+ l
2
+ l
3
= 0. A linear combination of effects, where the sum of the
coefficients is zero, is called a contrast. The linear combination
1
-
3
is a
contrast of the s and thus is estimable. The linear combination
2
is not a
contrast of the s and thus is not estimable.
Determining estimability numerically
The X matrix for the model in equation (4) has three distinct rows, and these
are shown in Table 15-6. Also shown in Table 15-6 is a vector (call it z) that is
a basis of the space orthogonal to the rows of X. Let l be a vector whose ele-
ments are the l
j
of expression (5). The linear combination 5 in vector notation
is l
T
b and is estimable if l
T
= 0. Allow for some rounding error in the com-
putation of z. The linear combination is estimable if:
where || ||

is the largest absolute value of the vector, and tol is the Estima-
bility Tolerance.
In general, the number of rows in the basis of the space orthogonal to the rows
of X is equal the number of linear dependencies among the columns of X. If
there is more than one z, then (8) must be satisfied for each z.
Substitution of estimable functions for non-estimable functions
It is not always easy for a user to determine if a linear combination is estima-
ble or not. LinMix tries to be helpful, and if a user attempts to estimate an
non-estimable function, LinMix will substitute a nearby function that is
estimable. Notice is given in the text output when the substitution is made,
(8)
Table 15-6. The basis of the space orthogonal to the rows of X
Elements of
1

2

3
Distinct rows of X 1 1 0 0
1 0 1 0
1 0 0 1
Basis of orthogonal space -1 1 1 1
l
T
Z
l

Z
T
Z
--------------------------
tol <
WinNonlin
Users Guide
374
15
and it is the user's responsibility to check the coefficients to see if they are rea-
sonable. This section is to describe how the substitution is made.
The most common incidence of attempting to estimate a non-estimable func-
tion of the parameters is probably trying to estimate a contrast of main effects
in a model with interaction, so this will be used as an example. Consider the
model:
where is the over-all mean;
i
is the effect of the i-th level of a factor A,
i = 1, 2; j is the effect of the j-th level of a factor B, j = 1, 2; ()
ij
is the effect
of the interaction of the i-th level of A with the j-th level of B; and the
ijk
are
independently distributed N(0,
2
). The canonical form of the QR factoriza-
tion of X is displayed in rows 0 through 8 of Table 15-7. The coefficients to
generate
1
-
2
are shown in row 9. The process is a sequence of regressions
followed by residual computations. In the column, row 9 is already 0 so no
operation is done. Within the columns, regress row 9 on row 3. (Row 4 is all
zeros and is ignored.) The regression coefficient is 1. Now calculate residuals:
(row 9) - 1 (row 3). This operation goes across the entire matrix, i.e., not just
the columns. The result is shown in row 10, and the next operation applies
to row 10. The numbers in the columns of row 10 are zero, so skip to the
columns. Within the columns, regress row 10 on row 5. (Rows 6 through 8
are all zeros and are ignored.). The regression coefficient is 0, so there is no
need to compute residuals. At this point, row 10 is a deviation of row 9 from
an estimable function. Subtract the deviation (row 10) from the original (row
9) to get the estimable function displayed in the last row. The result is the
expected value of the difference between the marginal A means. This is likely
what the user had in mind.
This section provides a general description of the process just demonstrated
on a specific model and linear combination of elements of . Partition the QR
factorization of X vertically and horizontally corresponding to the terms in X.
Put the coefficients of a linear combination in a work row. For each vertical
partition, from left to right, do the following:
1. Regress (i.e., do a least squares fit) the work row on the rows in the diag-
onal block of the QR factorization.
2. Calculate the residuals from this fit across the entire matrix. Overwrite the
work row with these residuals.
y
ijk
= +
i
+
j
+ ()
ij
+
ijk
(9)
Linear Mixed Effects Modeling
Fixed effects
375
15
3. Subtract the final values in the work row from the original coefficients to
obtain coefficients of an estimable linear combination.
Fixed effects
The specification of the fixed effects (as defined in The linear mixed effects
model on page 366) can contain both classification variables and continuous
regressors. In addition, interaction and nested terms can also be included in
the model.
Output parameterization
Suppose X is np, where n is the number of observations, and p is the number
of columns. If X has rank p, denoted rank(X), then each parameter can be
uniquely estimated. If rank(X) < p, then there are infinitely many solutions. To
solve this problem, one then must impose additional constraints on the estima-
tor of .
Suppose column j is in the span of columns 0, 1, , j-1. Then column j pro-
vides no additional information about the response y beyond that of the col-
Table 15-7. The QR factorization of X scaled to canonical form

1

2

1

2
()
11
()
12
()
21
()
22
0 1 0.5 0.5 0.5 0.5 0.25 0.25 0.25 0.25
1 1 -1 0 0 0.5 0.5 -0.5 -0.5
2 0 0 0 0 0 0 0
3 1 -1 0.5 -0.5 0.5 -0.5
4 0 0 0 0 0
5 1 -1 -1 1
6 0 0 0
7 0 0
8 0
9 0 1 -1 0 0 0 0 0 0
10 0 0 0 0 0 -0.5 -0.5 0.5 0.5
Final result 0 1 -1 0 0 0.5 0.5 -0.5 -0.5
WinNonlin
Users Guide
376
15
umns that come before. In this case, it seems sensible to not use the column in
the model fitting. When this happens, its parameter estimate is set to 0.
As an example, consider a simple one-way ANOVA model, with three levels.
The design matrix is
X
0
is the intercept column. X
1
, X
2
, and X
3
correspond to the three levels of the
treatment effect. X
0
and X
1
are clearly linearly independent, as is X
2
linearly
independent of X
0
and X
1
. But X
3
is not linearly independent of X
0
, X
1
, and
X
2
, since X
3
= X
0
- X
1
-X
2
. Hence
3
would be set to zero. The degrees of free-
dom for an effect is the number of columns remaining after this process. In
this example, treatment effect has 2 degrees of freedom, the number typically
assigned in ANOVA.
See Predicted values and residuals on page 405 for details of the computa-
tion.
Singularity tolerance
If intercept is in the model, then center the data. Perform a Gram-Schmidt
orthogonalization process. If the norm of the vector after GS divided by the
norm of the original vector is less than , then the vector is called singular.
Transformation of the response
The transformation pull-down menu provides three options: No transforma-
tion, ln transformation (log
e
), or log transformation (log
10
). Transformations
are applied to the response before model fitting. Note that all estimates using
log will be the same estimates found using ln, only scaled by ln 10, since
log(x) = ln(x)/ln(10).
X
0
X
1
X
2
X
3
1 1 0 0
1 0 1 0
1 0 0 1
1 1 0 0
1 0 1 0
1 0 0 1
Linear Mixed Effects Modeling
Fixed effects
377
15
If the standard deviation is proportional to the mean, taking the logarithm
often stabilizes the variance, resulting in better model fitting. This is implic-
itly an assumption that the error structure is multiplicative with lognormal dis-
tribution.
Crossover example continued
The fixed effects are given in equation (5). Using that model, the design
matrix X would be expanded into that presented in Table 15-8. The vector of
fixed effects corresponding to that design matrix would be
= (
0
,
1
,
2
,
3
,
4
,
5
,
6
).
Notice that X
2
= X
0
- X
1
. Hence set
2
= 0. Similarly, X
4
= X
0
- X
3
and X
6
= X
0

- X
5
, and hence set
4
= 0 and
6
= 0.
Table 15-8. Design matrix expanded for fixed effects model Sequence
+ Period + Treatment
Intercept Sequence Period Treatment
X0 AB [X1] BA [X2] 1 [X3] 2 [X4] A [X5] B [X6]
1 1 0 1 0 1 0
1 1 0 1 0 1 0
1 1 0 1 0 1 0
1 1 0 1 0 1 0
1 1 0 1 0 1 0
1 1 0 1 0 1 0
1 0 1 0 1 1 0
1 0 1 0 1 1 0
1 0 1 0 1 1 0
1 0 1 0 1 1 0
1 0 1 0 1 1 0
1 0 1 0 1 1 0
1 0 1 1 0 0 1
1 0 1 1 0 0 1
1 0 1 1 0 0 1
1 0 1 1 0 0 1
WinNonlin
Users Guide
378
15
Variance structure
The LinMix Variance Structure page specifies the Z, G, and R matrices
defined in The linear mixed effects model on page 366. The user may have
0, 1, or more random effects specified. Only 1 repeated effect may be speci-
fied. The Repeated effect specifies the R = Var(). The Random effects spec-
ify Z and the corresponding elements of G = Var().
Repeated effect
The repeated effect is used to model a correlation structure on the residuals.
Specifying the repeated effect is optional. If no repeated effect is specified,
then R =
2

N
is used, where N denotes the number of observations, and
N
is
the N N identity matrix.
All variables used on this page must be classification variables.
To specify a particular repeated effect, one must have a classification model
term that uniquely identifies each individual observation. Put the model term
in the Repeated Specification box. Note that a model term can be a variable
name, an interaction term (e.g., Time*Subject), or a nested term (e.g.,
Time(Subject)).
The variance blocking model term creates a block diagonal R matrix. Suppose
the variance blocking model term has b levels, and further suppose that the
1 0 1 1 0 0 1
1 0 1 1 0 0 1
1 1 0 0 1 0 1
1 1 0 0 1 0 1
1 1 0 0 1 0 1
1 1 0 0 1 0 1
1 1 0 0 1 0 1
1 1 0 0 1 0 1
Table 15-8. Design matrix expanded for fixed effects model Sequence
+ Period + Treatment (continued)
Intercept Sequence Period Treatment
X0 AB [X1] BA [X2] 1 [X3] 2 [X4] A [X5] B [X6]
Linear Mixed Effects Modeling
Variance structure
379
15
data are sorted according to the variance blocking variable. Then R would
have the form
R =
b

where is the variance structure specified.
The variance is specified using the Type pull-down menu. Several variance
structures are possible, including unstructured, autoregressive, heterogeneous
compound symmetry, and no-diagonal factor analytic. See the Help file for
the details of the variance structures. The autoregressive is a first-order
autoregressive model.
To model heterogeneity of variances, use the Group variable. Group will
accept any model term. The effect is to create additional parameters of the
same variance structure. If a group variable has levels g = 1, 2, , n
g
, then the
variance for observations within group g will be
g
.
An example will make this easier to understand. Suppose 5 subjects are ran-
domly assigned to each of 3 treatment groups; call the treatment groups T
1
,
T
2
, and T
3
. Suppose further that each subject is measured in periods t = 0, 1, 2,
3, and that serial correlations among the measurements are likely. Suppose
further that this correlation is affected by the treatment itself, so the correla-
tion structure will differ among T
1
, T
2
, and T
3
. Without loss of generality, one
may assume that the data are sorted by treatment group, then subject within
treatment group.
First consider the effect of the group. It produces a variance structure that
looks like
where each element of R is a 1515 block. Each R
g
has the same form.
Because the variance blocking variable is specified, the form of each R
g
is
I
5

g
.
I
5
is used because there are five subjects within each treatment group. Within
each subject, the variance structured specified is
R
R
1
0 0
0 R
2
0
0 0 R
3
=
WinNonlin
Users Guide
380
15
This structure is the autoregressive variance type. Other variance types are
also possible. Often compound symmetry will effectively mimic autoregres-
sive in cases where autoregressive models fail to converge.
The output will consist of six parameters:
2
and for each of the three treat-
ment groups.
Random effects
Unlike the (single) repeated effect, it is possible to specify up to 10 random
effects. Additional random effects can be added by clicking the Add Random
button. To delete a previously specified random effect, click the Delete Ran-
dom button. It is not possible to delete all random effects; however, if no
entries are made in the random effect, then it will be ignored.
Model terms entered into the Random Effects Model produce columns in the
Z matrix, constructed in the same way that columns are produced in the X
matrix. It is possible to put more than one model term in the Random Effects
Model, but each random page will correspond to a single variance type. The

g
2
1
g

g
2

g
3

g
1
g

g
2

g
2

g
1
g

g
3

g
2

g
1
Linear Mixed Effects Modeling
Variance structure
381
15
variance matrix appropriate for that type is sized according to the number of
columns produced in that random effect.
The random intercept check box puts an intercept column (i.e., all 1s) into the
Z matrix.
The Variance Blocking Variables has the effect of inducing independence
among the levels of the Variance Blocking Variables. Mathematically, it
expands the Z matrix by taking the Kronecker product of the Variance Block-
ing Variables with the columns produced by the intercept check box and the
Random Effects Model terms.
The Group model term is used to model heterogeneity of the variances among
the levels of the Group model term, similarly to Repeated Effects.
Multiple random effects vs. multiple effects on one random effect
Suppose one has two random effect variables, R1 and R2. Suppose further that
R1 has three levels, A, B, and C, while R2 has two levels, Y and Z. The hypo-
thetical data are shown as follows.
Specifying a random effect of R1+R2 will produce different results than spec-
ifying R1 on Random 1 and R2 on Random 2 pages. This example models the
variance using the compound symmetry variance type. To illustrate this, build
the resulting Z and G matrices.
For R1+R2 on Random 1 page, put the columns of each variable in the Z
matrix to get the following.
R1 R2
A Y
B Y
C Y
A Z
B Z
C Z
WinNonlin
Users Guide
382
15
The random effects can be placed in a vector = (
1
,
2
,
3
,
4
,
5
). R1 and R2
share the same variance matrix G where:
Now, consider the case where R1 is placed on Random 1 page, and R2 is
placed on Random 2 page. For R1, the Z matrix columns are:
R1 R2
A B C Y Z
1 0 0 1 0
0 1 0 1 0
0 0 1 1 0
1 0 0 0 1
0 1 0 0 1
0 0 1 0 1
R1
A B C
1 0 0
0 1 0
0 0 1
1 0 0

=
2
1
2
2
2
3
2
4
2
5
2
2
2
1
2
2
2
3
2
4
2
3
2
2
2
1
2
2
2
3
2
4
2
3
2
2
2
1
2
2
2
5
2
4
2
3
2
2
2
1





G
Linear Mixed Effects Modeling
Least squares means
383
15
For R2, the columns in the Z matrix and the corresponding G is:
In this case:
Least squares means
Sometimes one would like to see the mean response for each level of a classi-
fication variable or for each combination of levels for two or more classifica-
tion variables. If there are covariables with unequal means for the different
levels, or if there are unbalanced data, the subsample means are not estimates
that can be validly compared. This section describes least squares means, sta-
tistics that make proper adjustments for unequal covariable means and unbal-
anced data in the linear mixed effects model.
Consider a completely randomized design with a covariable. The model is:
R1
A B C
1 0 0
0 1 0
0 0 1
1 0 0
0 1 0
0 0 1
R2
Y Z
1 0
1 0
1 0
0 1
0 1
0 1

=
2
1
2
2
2
3
2
2
2
1
2
2
2
3
2
2
2
1
1



G

=
2
4
2
5
2
5
2
4
2


G
1
2
G
G
G

=


0
0
WinNonlin
Users Guide
384
15
y
ij
=
i
+ x
ij
+
ij
where y
ij
is the observed response on the j
th
individual on the i
th
treatment;
i

is the intercept for the i
th
treatment; x
ij
is the value of the covariable for the j
th

individual in the i
th
treatment; is the slope with respect to x; and
ij
is a ran-
dom error with zero expected value. Suppose there are two treatments; the
average of the x
1j
is 5; and the average of the x
2j
is 15. The respective
expected values of the sample means are
1
+ 5 and
2
+ 15. These are not
comparable because of the different coefficients of . Instead, one can esti-
mate
1
+ 10 and
2
+ 10 where the overall mean of the covariable is used
in each linear combination.
Now consider a 2 2 factorial design. The model is:
y
ijk
= +
i
+
j
+
ijk
where y
ijk
is the observed response on the k
th
individual on the i
th
level of fac-
tor A and the j
th
level of factor B; is the over-all mean;
i
is the effect of the
i
th
level of factor A;
j
is the effect of the j
th
level of factor B; and
ijk
is a ran-
dom error with zero expected value. Suppose there are six observations for the
combinations where i = j and four observations for the combinations where i
j. The respective expected values of the averages of all values on level 1 of A
and the averages of all values on level 2 of A are +(0.6
1
+0.4
2
) +
1
and
+(0.4
1
+0.6
2
)+
2
. Thus, sample means cannot be used to compare levels
of A because they contain different functions of
1
and
2
. Instead, one com-
pares the linear combinations + (
1
+
2
)/2 +
1
and + (
1
+
2
)/2 +
2
.
The preceding examples constructed linear combinations of parameters, in the
presence of unbalanced data, that represent the expected values of sample
means in balanced data. This is the idea behind least squares means. Least
squares means are given in the context of a defining term, though the process
can be repeated for different defining terms for the same model. The defining
term must contain only classification variables and it must be one of the terms
in the model. Treatment is the defining term in the first example, and factor A
is the defining term in the second example. When the user requests least
squares means, LinMix automatically generates the coefficients l
j
of expres-
sion (5) and processes them almost as it would process the coefficients speci-
fied in an estimate statement. This chapter describes generation of linear
combinations of elements of that represent least squares means. A set of
coefficients are created for each of all combinations of levels of the classifica-
tion variables in the defining term. For all variables in the model, but not in
the defining term, average values of the variables are the coefficients. The
average value of a numeric variable (covariable) is the average for all cases
Linear Mixed Effects Modeling
Least squares means
385
15
used in the model fitting. For a classification variable with k levels, assume
the average of each indicator variable is 1/k. The value 1/k would be the actual
average if the data were balanced. The values of all variables in the model
have now been defined. If some terms in the model are products, the products
are formed using the same rules used for constructing rows of the X matrix as
described in the section on Fixed Effects, above. It is possible that some least
squares means will not be estimable.
For example, suppose the fixed portion of the model is:
Drug + Form + Age + Drug * Form.
To get means for each level of Drug, the defining term is Drug. Since Drug
has three levels, three sets of coefficients are created. Build the coefficients
associated the first level of Drug, DrugA. The first coefficient is 1 for the
implied intercept. The next three coefficients are 1, 0, and 0, the indicator
variables associated with DrugA. Form is not in the defining term, so average
values are used. The next four coefficients are all 0.25, the average of a four
factor indicator variable with balanced data. The next coefficient is 32.17, the
average of Age. The next twelve elements are:
[ 1 0 0 ] [0.25 0.25 0.25 0.25 ] = [0.25 0.25 0.25 0.25 0 0 0 0 0 0 0 0]
The final result is shown in the DrugA column of Table 15-9. The results for
DrugB and DrugC are also shown in Table 15-9. No new principles would be
illustrated by finding the coefficients for the Form least squares means. The
coefficients for the Drug*Form least squares means would be like representa-
tive rows of X except that Age would be replaced by average of Age.
Table 15-9. Coefficients of least squares means
l
j
Column of X
j
DrugA DrugB DrugC
Intercept
0
1 1 1
Drug DrugA
1
1 0 0
DrugB
2
0 1 0
DrugC
3
0 0 1
Form capsule
4
0.25 0.25 0.25
drops
5
0.25 0.25 0.25
syrup
6
0.25 0.25 0.25
tablet
7
0.25 0.25 0.25
WinNonlin
Users Guide
386
15
Contrasts
A contrast is a linear combination of the parameters associated with a term
where the coefficients sum to 0. Contrasts facilitate the testing of linear com-
binations of parameters. For example, consider a completely randomized
design with four treatment groups: Placebo, Low Dose, Medium Dose, and
High Dose. The user may wish to test the hypothesis that the average of the
dosed groups is the same as the average of the placebo group. One could write
this hypothesis as:
H
0
:
Placebo
- (
Low
+
Medium
+
High
)/3 = 0
or equivalently:
H
0
: 3
Placebo
- (
Low
+
Medium
+
High
) = 0.
Both of these are contrasts since the sum of the coefficients is 0. Note that
both contrasts make the same statement. This is true generally: contrasts are
invariant under changes in scaling.
Contrasts are tested using the Wald (1943) test statistic:
Age
8
32.17 32.17 32.17
Drug*Form DrugA*capsule
9
0.25 0 0
DrugA*drops
10
0.25 0 0
DrugA*syrup
11
0.25 0 0
DrugA*tablet
12
0.25 0 0
DrugB*capsule
13
0 0.25 0
DrugB*drops
14
0 0.25 0
DrugB*syrup
15
0 0.25 0
DrugB*tablet
16
0 0.25 0
DrugC*capsule
17
0 0 0.25
DrugC*drops
18
0 0 0.25
DrugC*syrup
19
0 0 0.25
DrugC*tablet
20
0 0 0.25
Table 15-9. Coefficients of least squares means (continued)
l
j
Column of X
j
DrugA DrugB DrugC
Linear Mixed Effects Modeling
Contrasts
387
15
where and are estimators of and V. L must be a matrix such that each
row is in the row space of X. This requirement is enforced in the wizard. The
Wald statistic is compared to an F distribution with rank(L) numerator degrees
of freedom and denominator degrees of freedom estimated by the program or
supplied by the user.
Joint versus single contrasts
Joint contrasts are constructed when the number of columns for contrast is
changed from the default value of 1 to a number larger than 1. Note that this
number must be no more than one less than the number of distinct levels for
the model term of interest. This tests both hypotheses jointly, i.e., in a single
test with a predetermined level of the test.
A second approach would be to put the same term in the neighboring contrast,
both of which have one column. This approach will produce two independent
tests, each of which is at the specified level.
To see the difference, suppose one wants to compare Placebo to Low Dose
and Placebo to Medium Dose. Using the first approach, enter the coefficients
as follows.
This will produce one test, testing the following hypothesis.
H
0
:
Contrast #1
Title Joint tests
Effect Treatment
Contrast Treatment
#1 Placebo -1 -1
#2 Low Dose 1 0
#3 Medium Dose 0 1
#4 High Dose 0 0
L

( )
T
L X
T
V

X ( )
1
L
T
( )
1
L

( )

1 1 0 0
1 0 1 0

0
0
=
WinNonlin
Users Guide
388
15
Now compare this with putting the second contrast in its own contrast.
This produces two tests.
H
01
: [-1 1 0 0] = [0] H
02
: [-1 0 1 0] = [0]
Note that this method inflates the overall Type I error rate to approximately
2, whereas the joint test maintains the overall Type I error rate to , at the
possible expense of some power.
Nonestimability of contrasts
If a contrast is not estimable, then an estimable function will be substituted for
the nonestimable function. See Substitution of estimable functions for non-
estimable functions on page 373 for the details.
Degrees of freedom
The degrees of freedom check box allows the user to control the denominator
degrees of freedom in the F approximation. The numerator degrees of free-
dom is always calculated as rank(L). If the check box is not checked, then the
default denominator degrees of freedom will be used which is the Satterth-
waite degrees of freedom. This can be changed to residual degrees of free-
dom.
Note: For purely fixed effects model, Satterthwaite and residual degrees of freedom
yield the same number. For details of the Satterthwaite approximation, see the
section Satterthwaites Approximation for Degrees of Freedom.
Contrast #1 Contrast #2
Title Low vs. Placebo Medium vs. Placebo
Effect Treatment Treatment
Contrast Treatment Treatment
#1 Placebo -1 Placebo -1
#2 Low Dose 1 Low Dose 0
#3 Medium Dose 0 Medium Dose 1
#4 High Dose 0 High Dose 0
Linear Mixed Effects Modeling
Estimates
389
15
To override the default degrees of freedom, check the box, and enter an appro-
priate number. The degrees of freedom must greater than 0.
Other options
To control the estimability tolerance, enter an appropriate tolerance in the
Estimability Tolerance text box (see Substitution of estimable functions for
non-estimable functions on page 373).
The Show Coefficients check box will produce extra output, including the
coefficients used to construct the tolerance. If the contrast entered is estima-
ble, then it will repeat the contrasts entered. If the contrasts are not estimable,
it will enter the estimable function used instead of the nonestimable function.
Estimates
The estimates page produces estimates output instead of contrasts. As such,
the coefficients need not sum to zero. Additionally, multiple model terms may
be included in a single estimate.
Unlike contrasts, estimates do not support joint estimates. The confidence
intervals are marginal. The confidence level must be between 0 and 100. Note
that it is entered as a percent: Entering 0.95 will yield a very narrow confi-
dence interval with coverage just less than 1%.
All other options act similarly to the corresponding option in the Contrasts.
LinMix Wizard
The general steps to create a linear mixed effects model are outlined below.
Some steps are optional, depending which calculations are included. Refer to
An example on page 363 for an in-depth discussion of linear mixed effects
modeling in the context of an example study. See the Examples Guide for fur-
ther linear mixed effects modeling and bioequivalence examples.
Note: To reuse the model last run in LinMix (during the same WinNonlin session),
click the Previous Model button. To reload a previously-saved model, click
the Load... button and specify the name of the LinMix Command file (.LML).
ANOVA command files (.ANV) can also be loaded into LinMix so long as
bioequivalence is not included.
WinNonlin
Users Guide
390
15
To set up a linear mixed effects model:
1. Open the data file to be analyzed. This can be any worksheet, including mod-
eling results.
2. Select Tools>Linear Mixed Effects Wizard from the WinNonlin menus or
click on the Linear Mixed Effects Wizard tool bar button.
3. Define the model in the Fixed Effects dialog, as described under Fixed
effects on page 391.
4. Set up any other optional calculations and options as described under:
Variance structure on page 393
Contrasts on page 397
Estimates on page 398
Least squares means on page 399
LinMix general options on page 400
5. At any point in the LinMix wizard, the user can save the model to a LinMix
Command file (.LML) for future re-use, by clicking the Save Model button.
6. Click Calculate to start the calculations and close the LinMix wizard.
LinMix limits and constraints
Cell data may not include question marks (?) or either single (') or double (")
quotation marks.
Variable names must begin with a letter. After the first character, valid charac-
ters include numbers and underscore (my_file_2). They cannot include spaces
or the following operational symbols: +, - *, /, =. They also cannot include
parentheses (), question marks (?) or semicolons (;). Finally, variable names
may not have single or double quotes in them.
Titles (in Contrasts, Estimates, or ASCII) can have single or double quotation
marksbut not both.
The following are maximum counts for LinMix variables and other objects.
Table 15-10. LinMix item limits
Item Maximum
model terms 30
Linear Mixed Effects Modeling
LinMix Wizard
391
15
Fixed effects
To define the model:
1. Drag and drop variables to categorize those needed in the LinMix model:
Dependent variables contain the values to which the model will be fit,
e.g., drug concentration.
Classification variables or factors are categorical independent variables,
e.g., formulation, treatment, and gender.
Regressor variables or covariates are continuous independent variables,
e.g., temperature or body weight.
Sort variables define subsets of data to be processed separately, that is, a
separate analysis will be done for each level of the sort variables. If the
factors in a model term 10
sort keys 16
dependent variables 128
covariate/regressor variables 255
variables in the data set 256
random and repeated statements 10
variables 256
contrast statements 100
estimate statements 100
combined length of all variance parameter names (total characters) 10,000
combined length of all level names (total characters) 10,000
levels per variable 1,000
path and file name (total characters) 256
number of records passed from WinNonlin to other programs 65,535
characters per data cell 128
column name length (characters) 128
titles (e.g., output title or chart title) 5 lines
Table 15-10. LinMix item limits (continued)
Item Maximum
WinNonlin
Users Guide
392
15
Sort variable has missing values, the analysis will be performed for the
missing level and MISSING will be printed as the current value of the
Sort variable.
A weight variable can be included if weights for each record are included
in a separate data column. The weights are used to compensate for obser-
vations having different variances. When a weight variable is specified,
each row of data is multiplied by the square root of the corresponding
weight. Weight variable values should be proportional to the reciprocals
of the variances. In the most common situation, the data are averages and
weights are sample sizes associated with the averages. See also Weight-
ing on page 325.
The Weight Variable cannot be a classification variable. It must
have been declared as a regressor/covariate before it can be used
as a weight variable. It can also be used in the model.
2. In the box labeled Model Specification, enter the fixed effects model:
a. type the model, or
b. drag variable names and click on the operators to be used in the model.
For discussion of the model, using an example to illustrate, see The linear
mixed effects model on page 366.
Note: Parentheses in the model definition represent nesting of model terms. Hence:
Seq+Subject(Seq)+Period+Form
is a valid use of parentheses and indicates that Subject is nested within Seq.
Drug + Disease + (Drug*Disease)
is not a valid use of parentheses in the model definition.
3. Accept the default setting for Fixed Effects Confidence Level or enter the
confidence interval for calculations of the fixed effects model.
4. Check the Dependent Variables Transformation check box if the dependent
variable values should be log-transformed before analysis. Select the transfor-
mation from the pull-down list for Dependent Variables Transformation.
Linear Mixed Effects Modeling
LinMix Wizard
393
15
CAUTION: If the dependent variable data in the workbook are already log transformed,
do not select a log transformation from the pull-down list, as this will trans-
form the data a second time.
5. Select the No Intercept option to eliminate the intercept in the model. Note
that this will change the parameterization of the classification variables. See
Construction of the X matrix on page 368 for discussion.
6. At any time in the LinMix wizard, it is possible to save the model to a LinMix
Command file (.LML) for future re-use, by clicking the Save Model button.
7. Click Next (to move to the Variance structure) or Calculate (if all settings are
complete).
Variance structure
The Variance Structure dialog follows the Fixed effects dialog in the LinMix
wizard. (See LinMix Wizard on page 389.) It provides a variety of covari-
ance structures. The variances of the random-effects parameters become the
covariance parameters for this model. Mixed linear models contain both fixed
effects and random effect parameters. See Variance structure on page 378
for discussion of variance in linear mixed effects models.
The choices for variance structures are shown in Table 15-11.
WinNonlin
Users Guide
394
15
Table 15-11 uses the following notation:
n = number of groups, (n = 1 if the group option is not used)
t = number of time points in the repeated context
b = dimension parameter: for some variance structures, the num-
ber of bands; for others, the number of factors
1(expression) = 1 if expression is true, 0 otherwise
Table 15-11. Variance structure types
Description Number of Parameters i
th
, j
th
element
Variance Components
and i corresponds to
k
th
effect
Unstructured
Banded Unstructured (b)
if ; otherwise, same as Unstructured.
Toeplitz
Banded Toeplitz
if ; otherwise, same as Toeplitz
Compound Symmetry
Heterogeneous
Compound Symmetry
No-Diagonal
Factor Analytic
Banded
No-Diagonal
Factor Analytic (b)

if ; otherwise,
same as No-Diagonal Factor
Analytic
Autoregressive (1)
Heterogeneous
Autoregressive (1)
n

k
2
1 i j = ( )
n t t 1 + ( ) 2
ij
n b 2 2t b 1 + ( )
b t <

ij
i j n < ( )
n t
i j 1 +
n b b t <
i j 1 +
1 i j n < ( )
n 2

1
2

2
1 i j = ( ) +
n t 1 + ( )
i

j
1 i j ( ) 1 i j = ( ) + [ ]
n t t 1 + ( ) 2

i k

j k
k 1 =
mi n i j n , , ( )

n b 2 2t b 1 + ( )
b t <
n 2

i j
n t 1 + ( )

i j
Linear Mixed Effects Modeling
LinMix Wizard
395
15
The Random tab
The Random tab provides a means to incorporate random effects in a
model.Other Random models (tabs) can be added by clicking the Add Ran-
dom button. It can be used to specify traditional variance components and/or
to specify random coefficients. The random effects can be either classification
or continuous. The Repeated tab is used to specify covariance structures for
repeated measurements on subjects.
To specify random effects:
1. In the box labeled Random Effects Model, either enter the model by typing
or by dragging the variable names and operators to be used in the model from
the appropriate boxes to the Random Effects Model box using the mouse.
The model can be built from classification variables and/or regressors and the
operators at the top of the dialog.
Note: The same variable cannot be in both the fixedeffects specification and the
random effects specification unless it is used differentlyas part of a product,
for instance. The same term (single variables, products, or nested variables)
should not appear in both.
2. (Optional) Drag the appropriate variable to the Variance Blocking Variables
(Subject) field. The variable must be a classification model term. This Sub-
ject field identifies the subjects in a data set. Complete independence is
assumed among subjects. Thus, Subject produces a block diagonal structure
with identical blocks.
3. (Optional) Drag the appropriate variable to the Group field. The variable
must be a classification model term. This variable defines an effect specifying
heterogeneity in the covariance structure. All observations having the same
level of the group effect have the same covariance parameters. Each new level
of the group effect produces a new set of covariance parameters with the same
structure as the original group.
4. Select the type of covariance structure in the Type list. The options are
explained in Table 15-11, Variance structure types, on page 394.
5. Select the Random Intercept check box to indicate that the intercept is ran-
dom. This is most commonly employed when a subject is specified in the
Variance Blocking field. The default is off-no random intercept.
WinNonlin
Users Guide
396
15
Note: Additional random effects models can be added via the Add Random button.
The Repeated tab
The Repeated tab provides the means to specify the R matrix in the mixed
model. If no Repeated statement is specified, R is assumed to be equal to .
The repeated effect must contain only classification variables.
To specify the repeated variance structure:
1. In the box labeled Repeated Specification, either enter the model by typing
or by dragging the variable names and operators in the model from the appro-
priate boxes to the Repeated Specification box using the mouse.
The model can be built from classification variable terms and the operators at
the top of the dialog. Syntax rules for the repeated specification are the same
as those for the fixedeffects model.
2. (Optional) Drag the appropriate variable to the Variance Blocking Variables
(Subject) field. This must be a classification variable. This Subject field iden-
tifies the subjects in a data set. Complete independence is assumed among
subjects; Subject produces a block diagonal structure with identical blocks.
3. (Optional) Drag the appropriate variable to the Group field. This must be a
classification variable with no regressors or operators. It defines an effect
specifying heterogeneity in the covariance structure. All observations having

2
I
Linear Mixed Effects Modeling
LinMix Wizard
397
15
the same level of the group effect have the same covariance parameters. Each
new level of the group effect produces a new set of covariance parameters
with the same structure as the original group.
4. Select the type of covariance structure in the Type list. The options are
explained in Table 15-11, Variance structure types, on page 394.
5. Click Next to proceed to the Contrasts or Calculate to run the analysis.
Contrasts
The Contrasts dialog is next in the LinMix wizard after the Variance structure.
Contrasts provide a mechanism for creating custom hypothesis tests. Con-
trasts can be computed only for classification variables. (See Fixed effects
on page 391 to select classification variables.) Further discussion of contrasts
is provided in Contrasts on page 386.
Note: Interactions can be used as contrasts only if the interaction is a model term;
the same is true for nested terms.
To specify contrasts:
1. Enter a descriptive label for the contrast in the Title cell.
2. Drag the appropriate Model term to the cell labeled Effect.
3. Enter the appropriate contrast coefficients in the empty cells associated with
Contrasts.
Note: The coefficients for single contrasts must sum to zero.
The settings for contrast #1 are disabled until a term has been dragged to the
Effect field. Once contrast #1 has been specified, the settings for the contrast
can be specified. They are specific to that contrast.
Once Contrast #1 has been specified, the grid automatically expands to allow
for Contrast #2. This grid will allow additional contrasts, up to the maximum
number of contrasts (100).
WinNonlin
Users Guide
398
15
Note: If all values of the dependent variable are missing or excluded for a given
level of the effect variable, then this level of the effect variable will not appear
in the Contrast vector.
Effect variables may be either numeric or alphabetic, but they may not be
both. If a column contains both numeric and alphabetic data, the column can-
not be used as an effect variable when building contrasts.
4. Specify the Settings for the contrast entered. These settings are specific to the
active contrast.
a. The Number of columns for contrast check box tests multiple linearly
independent combinations simultaneously. These columns are tested
jointly.
b. If the algorithm doesnt seem to be using appropriate choices for the
degrees of freedom, select the User-specified [denominator] degrees of
freedom check box and enter an integer for df greater than 1.
c. The Show Coefficients of Contrasts check box ensures that the contrast
is estimable. This shows the actual coefficients used in the output. If the
contrast is not estimable, a nearby estimable function will be used instead.
d. The Estimability tolerance indicates the closeness of the zero vector
before invoking the algorithm to make it estimable.
Each contrast is tested independently of other contrasts.
5. Click Next to proceed to the Estimates, or Calculate to run the analysis.
Estimates
The LinMix Estimates dialog is similar to the Contrasts dialogexcept that
multiple effects can be used in each estimate statement. Interaction terms and
nested terms can be used if they appear in the model. If the fixedeffects
model includes an intercept (the default), then the term Intercept is included
with the model terms. If the Intercept term is used as an effect for the estimate,
it works like a regressor; only one number will be entered in the grid.
Note: The marginal confidence interval is generated for each estimate.
See also Estimates on page 389 and The linear mixed effects model on
page 366.
Linear Mixed Effects Modeling
LinMix Wizard
399
15
To enter estimates:
1. Enter a descriptive label for the estimate in the cell labeled Title.
2. Drag the appropriate Model term to the cell labeled Effect. The grid expands
to display every unique level of that term.
3. Enter the appropriate coefficients in the empty cells associated with Effects.
Note: Coefficients for estimates are not bound by the same limits as are those for
Contrasts.
4. (Optional) To create compound estimates, drag another model term below the
existing estimate. The grid expands to include the new term and its levels.
5. Enter the appropriate coefficients in the cells associated with the new term.
6. Repeat as necessary for other terms within any one estimate.
7. Repeat as necessary for other estimates. The grid automatically expands up to
the maximum number of estimates.
8. Specify the Settings for the Estimate:
a. Set the Confidence Level for confidence interval calculations.
b. If the algorithm doesnt seem to be using appropriate choices for the
degrees of freedom, select the User-specified [denominator] degrees of
freedom check box and enter an integer for df greater than 1.
c. Checking Show Coefficients of Estimates displays in the output the
actual coefficients used and, if the estimate is not estimable, applies a
nearby, estimable function.
d. The Estimability tolerance indicates the closeness of the zero vector
before invoking the algorithm to make it estimable.
9. Click Next to proceed to the Least squares means, or Calculate to run the
LinMix model.
Least squares means
Least squares means are generalized least-squares means of the fixed effects.
They are estimates of what the mean values would have been had the data
been balanced. That is, these are the means predicted by the ANOVA model.
WinNonlin
Users Guide
400
15
If a data set is balanced, the least squares means will be identical to the raw
(observed) means. See also Least squares means on page 383.
Least Squares Means can be computed for any classification model term. See
Fixed effects on page 375 to set classification variables.
To specify Least Squares Means:
1. The Least Squares Means dialog follows the Estimates dialog in the LinMix
wizard. (See LinMix Wizard on page 389.)
2. The linear mixed effects model terms are provided in the Model Classifiable
Terms field. Drag each model term for which the least square means are to be
calculated up to the Least Squares Means box.
3. (Optional) Select the Settings for the Least Squares Means. The settings
selected are applied to all terms.
a. Set the Confidence Level for confidence interval calculations.
b. If the algorithm doesnt seem to be using appropriate choices for the
degrees of freedom, select the User-specified [denominator] degrees of
freedom check box and enter an integer for df greater than 1.
c. Checking Show Coefficients of LSMs ensures that the contrast is esti-
mable. If the hypothesis is estimable, no change is made. If the test is not
estimable, this option will apply a nearby, estimable function.
d. The Estimability tolerance indicates the closeness of the zero vector
before invoking the algorithm to make it estimable.
e. The Compute Pairwise differences of LSMs check box provides addi-
tional output with the differences of confidence intervals and LSMs. This
function tests .
4. Click Next to proceed to the LinMix general options or Calculate to run the
LinMix analysis.
LinMix general options
To specify LinMix general options:
1. Click on the ASCII output check box to select ASCII text output in addition to
the grid output.

1

2
=
Linear Mixed Effects Modeling
LinMix output
401
15
2. Enter a title for the ASCII output (optional). The title can include up to 5
lines. When entering a multi-line title, press ENTER to move to the next line.
3. (Optional) Select the Degrees of freedom calculation form: Residual is the
same as in a purely fixed effects model. Satterthwaite computes the df base
on approximation to distribution of variance.
4. (Optional) Enter the number of Maximum iterations. This is the number of
iterations in the Newton fitting algorithm.
5. (Optional) If the model has random effects, select the Initial Variance
Parameters button to edit a grid of the parameters. If these are not specified,
the application uses the method of moments estimates. Click OK.
6. (Optional) Set the Singularity Tolerance level. The columns in X and Z are
eliminated if their norm this number.
7. (Optional) Specify the Convergence Criterion. For more details on the com-
putations, see Convergence criterion on page 410.
8. (Optional) Select Intermediate Calculations to include the design matrix,
reduced data matrix, asymptotic covariance matrix of variance parameters,
Hessian, and final variance matrix in the ASCII output.
9. To save the model to a LinMix command file (.LML) for later re-use, use the
Save Model button.
10. Click Calculate to run the LinMix analysis, or Back to return to the Least
squares means and other previous settings.
For more detail on ASCII and data grid output, See LinMix output on
page 401.
LinMix output
When LinMix calculations have completed (see LinMix Wizard on
page 389 and Computational details on page 407), the output is displayed in
one or both of the following windows.
Linear mixed effects text
This is the optional ASCII output selected in the LinMix general options. It
contains a complete summary of the analysis.

2
WinNonlin
Users Guide
402
15
Figure 15-1. LinMix text (ASCII) output
Linear mixed effects workbook
The Linear Mixed Effects Workbook contains summary tables of the output.
Depending which model options have been set up, workbook may contain the
items listed in Table 15-12.
Table 15-12. Linear mixed effects worksheets
Item Contents
Diagnostics Model-fitting information
Sequential Tests Tests of fixed effects, performed sequentially
Partial Tests Tests of fixed effects, but each term is tested last
Final Fixed
Parameters
Estimates, standard error, t-statistic, p-value, and confidence intervals
Final Variance
Parameters
Estimates and units of the final variance parameters
Parameter Key Information about the variance structure
Contrasts Hypothesis, df, F-statistic, and p-value
Estimates Estimate, standard error, t-statistic, pvalue, and confidence interval
Linear Mixed Effects Modeling
LinMix output
403
15
Details for specific output follow.
Tests of hypotheses
The tests of hypotheses are the mixed model analog to the analysis of variance
in the fixed model case. The tests are performed by finding appropriate L
matrices and testing the hypotheses H0: L = 0 for each model term.
Sequential tests
The sequential tests test each model term sequentially. First it is tested
whether the first model term should enter the model. Then it is tested whether
the second model term should enter the model, given that the first term is in
the model. Then it is tested whether the third model term should enter the
model, given that the first two terms are in the model. This continues until all
the model terms are exhausted.
This is computed using a QR factorization of the XY matrix. The QR factoriza-
tion is segmented to match the number of columns that each model term con-
tributes to the X matrix.
Partial tests
Partial tests test each model term given every other model term. Unlike
sequential tests, partial tests are invariant under the order in which model
terms are listed on the Fixed Effects page of the wizard. It does this by factor-
ing out of each model term the contribution attributable to the remaining
model terms.
Least Squares
Means
Least squares means, standard error, df, t-statistic, p-value, and confi-
dence interval
Residuals Dependent variable(s), units, observed and predicted values, standard
error and residuals
User Settings Information about model settings
Initial Variance
Parameters
Initial values for variance parameters
Iteration History Data on the variable estimation in each iteration
Table 15-12. Linear mixed effects worksheets (continued)
Item Contents
WinNonlin
Users Guide
404
15
This is computed by modifying the basis created by the QR factorization to
yield a basis that more closely resembles that found in balanced data.
Discussion
For fixed effects models, certain properties can be stated for the two types of
ANOVA. For the sequential ANOVA, the sums of squares are statistically
independent. Also, the sum of the individual sums of squares is equal to the
model sum of squares; i.e., the ANOVA represents a partitioning of the model
sum of squares. However, some terms in ANOVA may be contaminated with
undesired effects. The partial ANOVA is designed to eliminate the contamina-
tion problem, but the sums of squares are correlated and do not add up to the
model sums of squares. The mixed effects tests have similar properties.
Akaikes Information Criterion (AIC)
The Linear Mixed Effects module uses the smaller-is-better form of Akaikes
Information Criterion:
AIC = 2L
R
+ 2s
where L
R
is the restricted log-likelihood function evaluated at final fixed
parameter estimates and the final variance parameter estimates , and s
is the rank of the fixed effects design matrix X plus the number of parameters
in (i.e., s = rank(X) + dim()).
Schwarzs Bayesian Criterion (SBC)
The Linear Mixed Effects module uses the smaller-is-better form of
Schwarzs Bayesian Criterion:
where L
R
is the restricted log-likelihood function evaluated at the final esti-
mates and ,
N is the number of observations used,
r is the rank of the fixed effects design matrix X, and
s is the rank of the fixed effects design matrix X plus the number of
parameters in
(i.e., s = rank(X) + dim() ).

SBC 2L
R
s N r ( ) log + =

Linear Mixed Effects Modeling


LinMix output
405
15
Hessian eigenvalues
The eigenvalues are formed from the Hessian of the restricted log likelihood.
There is one eigenvalue per variance parameter. Positive eigenvalues indicate
that the final parameter estimates are found at a maximum.
Predicted values and residuals
In the Linear Mixed Effects module, predicted values for the dependent vari-
ables are computed at all of the input data points. To obtain predicted values
for data points other than the observed values, the user should supply the
desired points in the input data set with missing dependent variables. Pre-
dicted values are estimated by using the rows of the fixed effects design
matrix X as the L matrices for estimation, and therefore the predicted values
for the input data are equal to , where are the final fixed parame-
ters estimates. Note that if the user requested a log-transform, then the pre-
dicted values are also transformed. The residuals are then the observed values
minus the predicted values, or in the case of transforms, the residuals are the
transformed values minus the predicted values. The variance of the prediction
is as follows.
The standard errors are the square root of the diagonal of the matrix above.
T-type confidence intervals for the predicted values are also computed.
The Lower_CI and Upper_CI are the confidence bounds on the predicted
response
1
. The confidence level is given in Conf_Level. This is controlled
on the Fixed Effects page of the wizard.
Fixed effects parameter estimates
In the Linear Mixed Effects module, the final fixed effects parameter esti-
mates are computed by solving
T
00
= y
0
where T
00
and y
0
are elements of the reduced data matrix as defined in the
section on Restricted Maximum Likelihood Estimation, and are the final
fixed parameters estimates.
y

Var y

( ) X X
T
V

X ( )
1
X
T
=

i
y

WinNonlin
Users Guide
406
15
When there are multiple solutions, a convention is followed such that if any
column of T
00
is a linear combination of preceding columns, then the corre-
sponding element of is set to zero.
Coefficients
If the Display Coefficients check box is checked on any of the page of the
LinMix wizard, the coefficients of the parameters used to construct the linear
combination will be displayed. If the linear combination is estimable, then the
coefficients will be the same as those entered. If the linear combination is not
estimable, then the estimable replacement will be displayed. This gives the
user the opportunity to inspect what combination is actually used to see if it
represents the intentions.
Iteration history
This worksheet displays the results of the fitting algorithm. If the initial esti-
mates are the restricted maximum likelihood estimates, then zero iterations
will be displayed.
Parameter key
If the model included random or repeated effects, the Parameter column of
this grid contains the variance parameter names assigned by LinMix. If the
Group option is not used in the model or if there is only one random or
repeated model, then indices are not used in the parameter names.
Otherwise, two indices are appended to the variance parameter names in order
to clarify which random or repeated model, or group, the variance parameter
addresses. The first index indicates the random model or repeated model to
which the parameter applies. An index of 1 indicates the model on the Ran-
dom 1 tab in the user interface, etc. The highest index indicates the repeated
model if there was one. The second index is the group index indicating that
the parameters with the same group index are for the same group level.
Source Random if the parameter is from a random model
Repeated if the parameter is from a repeated specification
Assumed if the variance parameter is the residual
Type Variance type specified by the user, or Identity, if the residual variance
Bands Number of bands or factors if appropriate for the variance type

Linear Mixed Effects Modeling


Computational details
407
15
Computational details
Restricted maximum likelihood
For linear mixed effects models that contain random effects, the first step in
analyzing the models is determining the maximum likelihood estimates of the
variance parameters associated with the random effects. This is accomplished
in the Linear Mixed Effects module through the use of Restricted Maximum
Likelihood (REML) Estimation.
The linear mixed effects model described in the section, Description of Statis-
tical Model, is:
y = X + Z + ,
V = Variance(y) = ZGZ
T
+ R.
Let be a vector consisting of the variance parameters in G and R. The full
maximum likelihood procedure (ML) would simultaneously estimate both the
fixed effects parameters and the variance parameters by maximizing the
likelihood of the observations y with respect to these parameters. In contrast,
restricted maximum likelihood estimation (REML) maximizes a likelihood
that is only a function of the variance parameters and the observations y, and
not a function of the fixed effects parameters. Hence for models that do not
contain any fixed effects, REML would be the same as ML.
To obtain the restricted likelihood function in a form which is computationally
efficient to solve, the data matrix [X | Z | y] is reduced by a QR factorization to
an upper triangular matrix. Let [R
0
| R1 | R2] be an orthogonal matrix such
that the multiplication with [X | Z | y] results in an upper triangular matrix:
Subject_Term Subject term for this variance structure, if there was a subject
Group_Term Group term for this variance structure, if there was a group
Group_Level Level of the group that this parameter goes with, if there was a group
R
0
T
R
1
T
R
2
T
X Z y [ ]
T
00
T
01
y
0
0 T
11
y
r
0 0 y
e
=
WinNonlin
Users Guide
408
15
REML estimation maximizes the likelihood of based on y
r
and y
e
of the
reduced data matrix, and ignores y
0
. Since y
e
has a distribution that depends
only on the residual variance, and since y
r
and y
e
are independent, the nega-
tive of the log of the restricted likelihood function is the sum of the separate
negative log-likelihood functions:
log(L(; y
r
, y
e
)) = log(L(; y
r
)) + log(L(; y
e
)) (Nrank(X))/2 log(2)
where:
log(L(; y
r
)) = log (|V
r
|) y
r
T
V
r

1
y
r
log(L(; y
e
)) = n
e
/2 log(
e
) (y
e
T
y
e
/
e
)
V
r
= Variance(y
r
)

e
= residual variance
n
e
= residual degrees of freedom, and
N = number of observations used.
For some balanced problems, y
e
is treated as a multivariate residual,
, in order to increase the speed of the program and then the
log-likelihood can be computed by the equivalent form:

where V is the dispersion matrix for the multivariate normal distribution.
For more information on REML, see Corbeil and Searle (1976).
Newtons Algorithm for maximization of restricted likelihood
As a general review, Newtons algorithm is an iterative algorithm used for
finding the minimum of an objective function. The algorithm needs a starting
point, and then at each iteration, it finds the next point using:

i+1
=
i
H
1
(
i
) g(
i
),
y
e1
y
e2
y
en
[ ]
L y
e
; ( ) ( ) log
n
2
--- V
1
( ) log
1
2
--- y
ei
T
V
1
y
ei
i 1 =
n

=
Linear Mixed Effects Modeling
Computational details
409
15
where H
1
is the inverse of the Hessian of the objective function, and g is the
gradient of the objective function. The algorithm stops when a convergence
criterion is met, or when it is unable to continue.
In the Linear Mixed Effects module, a modification of Newtons algorithm is
used to minimize the negative restricted log-likelihood function with respect
to the variance parameters , hence yielding the variance parameters that
maximize the restricted likelihood. Since a constant term does not affect the
minimization, the objective function used in the algorithm is the negative of
the restricted log-likelihood without the constant term:
objective function = log(L(; y
r
)) log(L(; y
e
))
Newtons algorithm is modified by adding a diagonal matrix to the Hessian
when determining the direction vector for Newtons algorithm so that the
diagonal matrix plus the Hessian matrix is positive definite, ensuring a direc-
tion of descent:

i+1
=
i
( H
i
+ D
i
)
1
g
i
The appropriate D
i
matrix is found by a modified Cholesky factorization as
described in Gill, Murray, and Wright. Another modification to Newtons
algorithm is that, once the direction vector
d = ( H
i
+ D
i
)
1
g
i
has been determined, a line search is done as described in Fletcher (1980) to
find an approximate minimum along the direction vector.
Note from the discussion on REML estimation that the restricted log-likeli-
hood is a function of the variance matrix V
r
and the residual variance, which
are in turn functions of the parameters . The gradient and Hessian of the
objective function with respect to are therefore functions of first and second
derivatives of the variances with respect to . Since the variances can be
determined through the types specified for G and R (e.g., Variance Compo-
nents, Unstructured, etc.), the first and second derivatives of the variance can
be evaluated in closed-form, and hence the gradient and Hessian are evaluated
in closed-form in the optimization algorithm.
Starting values
Newtons algorithm requires initial starting values for the variance parameter
. If the user has some knowledge of these values, the user can supply these
WinNonlin
Users Guide
410
15
values in the Linear Mixed Effects interface. On the General Options page,
click Initial Variance Parameters button. More often, the user will want the
Linear Mixed Effects module to determine initial values. For variance struc-
tures that are linear in (Variance Components, Unstructured, Compound
Symmetry, and Toeplitz), the initial values are determined by the method of
moments. If the variance structure is nonlinear, then the program will calcu-
late a sample variance by solving for random effects and taking sums of
squares and cross-products of the random effects. The sample variance will
then be equated with the parametric variance, and the system of equations will
be solved to obtain initial parameter estimates. If either of these methods fail,
the program will use starting values that should yield a reasonable variance
matrix such as 1.0 for variance components and standard deviations, and 0.01
for correlations.
Sometimes the method of moments will yield estimates of that are REML
estimates. In this case the program will not need to iterate.
Convergence criterion
The convergence criterion used in the Linear Mixed Effects module is that the
algorithm has converged if:
g
T
() H
1
() g() < ,
where is the convergence criterion specified on the General Options page of
the wizard. The default value is 110
10
.
The possible convergence outcomes from Newtons algorithm are:
Newton's algorithm converged with a final Hessian that is positive defi-
nite. This indicates successful convergence at a local minimum and hope-
fully at a global minimum.
Newton's algorithm converged with modified Hessian. This indicates that
the output is suspect, and the model may be over-specified. The algorithm
has converged but is not at a local minimum. It may be in a trough, at a
saddle point, or on a flat surface.
Initial variance matrix is not positive definite. This indicates an invalid
starting point for the algorithm.
Intermediate variance matrix is not positive definite. The algorithm is
unable to continue.
Failed to converge in allocated number of iterations.
Linear Mixed Effects Modeling
Computational details
411
15
Satterthwaites approximation for degrees of freedom
The linear model used in linear mixed effects modeling is:
where X is a matrix of fixed known constants, b is an unknown vector of con-
stants, and V is the variance matrix that depends on other unknown parame-
ters. Wald (1943) developed a methodology for testing hypotheses in a rather
general class of models. To test the hypothesis H
0
: Lb = 0 in (10), the Wald
statistic is:
where and are estimators of and V. L must be a matrix such that each
row is in the row space of X. The Wald statistic is asymptotically distributed
under the null hypothesis as a chi-squared random variable with q = rank(L)
degrees of freedom.
In common variance component models with balanced data, the Wald statistic
has an exact F-distribution. Using the chi-squared approximation results in a
testing procedure that is too liberal. LinMix uses a method due to Allen
(2001) for finding an F distribution to approximate the distribution of the
Wald statistic.
Giesbrecht and Burns (1985) suggested a procedure to determine denominator
degrees of freedom when there is one numerator degree of freedom. Their
methodology applies to variance component models with unbalanced data.
Allen derived an extension of their technique to the general mixed model.
A one degree of freedom (df) test is synonymous with L having one row in
(11). When L has a single row, the Wald statistic can be re-expressed as:
Consider the right hand side of (12). The distribution of the numerator is
approximated by chi-squared random variable with 1 df. The objective is to
Y ~ N(Xb, V) (10)
(11)
(12)
L

( )
T
L X
T
V

1
X ( )
1
L
T
[ ]
1
L

( )

( )
2
L X
T
V

1
X ( )
1
L
T
--------------------------------------
L

( )
2
L X
T
V
1
X ( )
1
L
T
--------------------------------------
L X
T
V

1
X ( )
1
L
T
L X
T
V
1
X ( )
1
L
-------------------------------------- =
WinNonlin
Users Guide
412
15
find a such that the denominator is approximately distributed as a chi-
squared variable with df. If:
is true, then:
The approach is to use (13) to solve for .
Find an orthogonal matrix R and a diagonal matrix such that:
The Wald statistic (11) can be re-expressed as:
where r
u
is the u-th column of R, and
u
is the u-th diagonal of . Each term
in (14) is similar in form to (12). Assuming that the u-th term is distributed
F(1,
u
), the expected value of W is:
Assuming W is distributed F(q, ), its expected value is q/(-2). Equating
expected values and solving for , one obtains:
= 2 E{W} / (E{W} q)
(13)
(14)
L X
T
V

1
X ( )
1
L
T
L X
T
V
1
X ( )
1
L
--------------------------------------

2

---------

Var
L X
T
V

1
X ( )
1
L
T
L X
T
V
1
X ( )
1
L
--------------------------------------
2

--- =
L X
T
V

1
X ( )
1
L
T
RR
T
=
W R
T
L

( )
T

1
R
T
L

( )
r
u
L

( )
2

u
-------------------
u 1 =
q

= =
E W ( )

u

u
2
--------------
u 1
q

=
Linear Mixed Effects Modeling
Comparing LinMix to ANOVA and SASs PROC MIXED
413
15
Comparing LinMix to ANOVA and SASs PROC MIXED
This section outlines differences between LinMix and the WinNonlin
ANOVA module (deprecated), and between LinMix and PROC MIXED from
SAS

.
Feature LinMix ANOVA PROC MIXED
Degrees of
freedom
Uses Satterthwaite approximation for
all degrees of freedom, by default. User
can also select Residual.
Uses only
Residual.
PROC MIXED chooses different defaults
depending on the model, random, and
repeated statements. In order for LinMix
and SAS to be consistent, the ddfm=sat-
terth option in SAS should be set.
Multiple
factors on
the same
random
command
In LinMix, effects associated with the
columns of the matrix specified in a sin-
gle random statement are assumed to
be correlated according to the variance
specified. The rule in LinMix is simple
regardless of the variance structure: If
the random effects are correlated, put
them on the same random tab. If the
random effects are independent, put
them on separate random tabs.
N/A SAS behaves similarly, except that it does
not follow this rule in the case of Variance
Components, so LinMix and SAS will differ
for models with multiple terms on a random
statement using the VC structure.
REML REML (Restricted Maximum Likeli-
hood) estimation, as defined in Corbeil
and Searle (1976), does maximum like-
lihood estimation on the residual vector.
This is how it is done in LinMix.
N/A By default, SAS modifies the REML
approach by profiling out the residual vari-
ance. In order for LinMix and SAS to be
consistent, the noprofile option should be
set in SAS on the proc mixed statement. In
particular, LinMixs log(likelihood) may not
be equal to twice SASs 2 Res Log Like if
the noprofile option is not set.
Akaike and
Schwarzs
criteria
LinMix uses the smaller-is-better form
of AIC and SBC in order to match Win-
Nonlin and WinNonMix.
N/A SAS uses the bigger-is-better form. In addi-
tion, AIC and SBC are functions of the likeli-
hood, and the likelihood calculation method
in LinMix also differs from SAS.
Saturated
variance
structure
In models where the random statement
saturates the variance part of the
model, the residual is not estimable.
LinMix sets the residual variance to
zero. The user-specified variance
structure takes priority over that sup-
plied by LinMix.
N/A SAS sets the residual to some other num-
ber. The SAS residual needs to be added to
the other SAS variance parameter esti-
mates in order to match the LinMix output.
WinNonlin
Users Guide
414
15
Conver-
gence cri-
teria
The convergence criterion in LinMix is
g
T
H
1
g < tolerance with H positive def-
inite, where g is the gradient and H is
the Hessian of the negative log-like-
hood. This would be equivalent to SAS
if the convh and absolute options
were set in SAS.
N/A The default convergence criterion options in
SAS are convh and relative.
Modified
likelihood
LinMix always tries to keep the final
Hessian (and hence the variance
matrix) positive definite. LinMix will
determine when the variance is over-
specified, and set some of the parame-
ters to zero.
N/A SAS will let the final Hessian be not positive
definite, and hence will get different final
parameter estimates. This situation often
occurs when the variance is over-specified
(i.e., there are too many parameters in the
model).
Keeping
VC positive
For VC structure, LinMix will keep the
final variance matrix positive definite,
but it will not force the individual vari-
ances to be positive.
N/A If SAS estimates a negative variance com-
ponent, it outputs 0.
Partial
tests of
model
effects
The partial tests in LinMix are not
equivalent to the Type III method in
SAS though they coincide in most situ-
ations. See Partial tests on page 403.
As SASs
PROC
GLM Type
III
The Type III results can change depending
on how one specifies the model. For
details, consult the SAS manual or contact
support@pharsight.com.
Not estima-
ble param-
eters on
output
If a variable is not estimable, LinMix
prints Not estimable in the output, and
also gives the user the option to write
out 0 instead.
Prints Not
estimable
SAS writes the value of 0.
ARH, CSH
variance
structures
LinMix uses the standard deviations for
the parameters, and prints the standard
deviations in the output.
N/A SAS prints the variances in the output for
final parameters, though the model is
expressed in terms of standard deviations.
Repeated
without any
time vari-
able
LinMix requires an explicit repeated
model. To run some SAS examples, a
time variable would need to be added
to the data.
N/A SAS allows the repeated model specifica-
tion to be unspecified. In this case, SAS
creates an implicit time variable, and
assumes the data are appropriately sorted.
Group as
classifica-
tion vari-
able
LinMix requires variables used for the
subject and group options to be
declared as classification variables.
N/A SAS allows regressors, but requires the
data to be sorted and considers each
change in the value of the regressor to indi-
cate a new subject or group. This is also
how classification variables are treated.
Feature LinMix ANOVA PROC MIXED
Linear Mixed Effects Modeling
Comparing LinMix to ANOVA and SASs PROC MIXED
415
15
Singularity
tolerance
Define d
ii
as the i-th diagonal element
of the QR factorization of X, and D
ii
the
sum of squares of the i-th column of the
QR factorization. The i-th column of X
is deemed linearly dependent on the
proceeding columns if d
ii
2
< (singularity
tolerance)D
ii
. If intercept is present,
the first row of D
ii
is omitted.
Define d
ii
as the diagonal element of the
X
T
X matrix during the sweeping process. If
the absolute diagonal element |d
ii
| < (singu-
larity tolerance)D
ii
, where D
ii
is the original
diagonal of X
T
X, then the parameter asso-
ciated with the column is set to 0, and the
parameter estimates are flagged as biased.
Feature LinMix ANOVA PROC MIXED
WinNonlin
Users Guide
416
15
417
Chapter 16
Bioequivalence
Calculating average, individual, and population
bioequivalence
WinNonlin includes a Bioequivalence Wizard that calculates average or popu-
lation/individual bioequivalence. Defined as relative bioavailability, bioequiv-
alence involves comparison between test and reference drug products, where
the test and reference products can vary, depending upon the comparison to be
performed. Although bioavailability and bioequivalence are closely related,
bioequivalence comparisons rely on a criterion, a predetermined bioequiva-
lence limit, and calculation of a confidence interval for that criterion.
Introduction to bioequivalence
Basic terms
Bioequivalence is said to exist when a test formulation has a bioavailability
that is similar to that of the reference. There are three types of bioequivalence:
Average, Individual, and Population.
The July 1992 guidance on Statistical Procedures for Bioequivalence Studies
Using a Standard Two-Treatment Crossover Design recommended that a stan-
dard in vivo bioequivalence study design be based on the administration of
either single or multiple doses of the test and reference products to healthy
subjects on separate occasions, with random assignment to the two possible
sequences of drug product administration. Further, the 1992 guidance recom-
mended that statistical analysis for pharmacokinetic parameters, such as area
under the curve (AUC) and peak concentration (Cmax) be based on a test pro-
cedure termed the two one-sided tests procedure to determine whether the
average values for pharmacokinetic parameters were comparable for test and
reference formulations. This approach is termed average bioequivalence and
involves the calculation of a 90% confidence interval for the ratio of the aver-
WinNonlin
Users Guide
418
16
ages of the test and reference products. To establish bioequivalence, the calcu-
lated confidence interval should fall within a bioequivalence limit, usually 80-
125% for the ratio of the product averages. In addition to specifying this gen-
eral approach, the 1992 guidance also provided specific recommendations for
(1) logarithmic transformations of pharmacokinetic data, (2) methods to eval-
uate sequence effects, and (3) methods to evaluate outlier data.
The 2001 FDA Guidance Statistical Approaches to Establishing Bioequiva-
lence recommends that average bioequivalence be supplemented by two new
approaches, population and individual bioequivalence. Population and indi-
vidual bioequivalence include comparisons of both the averages and variances
of the study measure. Population bioequivalence assesses the total variability
of the measure in the population. Individual bioequivalence assesses within-
subject variability for the test and reference products as well as the subject-
by-formulation interaction.
Bioequivalence
Bioequivalence between two formulations of a drug product, sometimes
referred to as relative bioavailability, indicates that the two formulations are
therapeutically equivalent and will provide the same therapeutic effect. The
objective of a bioequivalence study is to determine whether bioequivalence
exists between a test formulation and reference formulation and to hence
identify whether the two formulations are pharmaceutical alternatives that can
be used interchangeably to achieve the same effect.
Bioequivalence studies are important because establishing bioequivalence
with an already approved drug product is a cost-efficient way of obtaining
drug approval. For example, to get approval to market a generic drug product,
the Food and Drug Administration (FDA) usually does not require a new drug
application submission if the generic drug company can provide evidence of
bioequivalence between the generic drug product and the innovator product.
Bioequivalence studies are also useful for testing new formulations of a drug
product, new routes of administration of a drug product, and for a drug prod-
uct that has changed after approval.
Three different types of bioequivalence have been established by the FDA.
These are average bioequivalence, population bioequivalence, and individual
bioequivalence. All types of bioequivalence comparisons are based on the cal-
culation of a criterion (or point estimate), on the calculation of a confidence
interval for the criterion, and on a predetermined acceptability limit for the
confidence interval.
Bioequivalence
Introduction to bioequivalence
419
16
A procedure for establishing average bioequivalence was recommended by
the FDA in the 1992 guidance on Statistical Procedures for Bioequivalence
Studies Using a Standard Two-Treatment Crossover Design. The FDA rec-
ommended administration of either single or multiple doses of the test and
reference formulations to subjects, with random assignment to the possible
sequences of drug administration. The guidance then recommended that a sta-
tistical analysis of pharmacokinetic parameters such as AUC and Cmax be
done on a log-transformed scale to determine the difference in the average
values of these parameters between the test and reference data, and to deter-
mine the confidence interval for the difference. To establish bioequivalence,
the confidence interval, usually calculated at the 90% confidence level,
should fall within a predetermined acceptability limit, usually within 20% of
the reference average. The FDA also recommended an equivalent approach
using two, one-sided t-tests. Both the confidence interval approach and the
two one-sided t-tests are described further below.
The January 2001 guidance Statistical Approaches to Establishing Bioequiv-
alence recommends that average bioequivalence be supplemented by two
new approaches, population and individual bioequivalence. These added
approaches are needed because average bioequivalence uses only a compari-
son of averages, and not the variances, of the bioequivalence measures. In
contrast, population and individual bioequivalence approaches include com-
parisons of both the averages and variances of the study measure. The popula-
tion bioequivalence approach assesses the total variability of the study
measure in the population. The individual bioequivalence approach assesses
within-subject variability for the test and reference products as well as the
subject-by-formulation interaction.
The concepts of population and individual bioequivalence are related to two
types of drug interchangeabilityprescribability and switchability. Drug pre-
scribability refers to when a physician prescribes a drug product to a patient
for the first time, and must choose from a number of bioequivalent drug prod-
ucts. Drug prescribability is usually assessed by population bioequivalence.
Drug switchability refers to when a physician switches a patient from one
drug product to a bioequivalent product, such as when switching from an
innovator drug product to a generic substitute within the same patient. Drug
switchability is usually assessed by individual bioequivalence.
WinNonlin
Users Guide
420
16
The model
Linear model
As in the Linear Mixed Effects Modeling wizard, the Bioequivalence Wizard
is based upon a mixed effects model. See The linear mixed effects model on
page 366. For more details on the models required for different kinds of
bioequivalence, see Average, Population, and Individual Approaches to
Establishing Bioequivalence. FDA Guidance for Industry. August 1999.
Variance structures
The variance structures available in the Bioequivalence Wizard are the same
as those available in the Linear Mixed Effects Modeling wizard. See Vari-
ance structure on page 393.
Average bioequivalence
Study designs
The most common study designs used in bioequivalence studies are replicated
crossover, nonreplicated crossover, and parallel. In a parallel design, each
subject receives only one formulation in random fashion, whereas in a cross-
over design each subject receives more than one formulation at different time
periods. Crossover designs are further broken down into designs that are repli-
cated and nonreplicated, where nonreplicated designs are those in which the
subjects receive only one dose of the test formulation and only one dose of the
reference formulation, whereas replicated designs involve multiple doses. The
FDA recommends that a bioequivalence study should use a crossover design
unless a parallel or other design can be demonstrated to be more appropriate
for valid scientific reasons. Replicated crossover designs need be used for
individual bioequivalence studies, and can be used for average or population
bioequivalence analysis.
In the Bioequivalence Wizard, if the reference formulation and all of the test
formulations have at least one subject with more than one dose of that formu-
lation, then this is considered a replicated design. As an example, for the two
formulations T and R, a 23 crossover design as described in the table below
is a replicated crossover design.
Bioequivalence
Average bioequivalence
421
16
An example of a nonreplicated crossover design is the standard 2x2 crossover
design described in the 1992 FDA guidance and in the table below.
Recommended models for average bioequivalence
The recommended model to be used in average bioequivalence studies
depends on the type of study design that was used parallel, nonreplicated
crossover, or replicated crossover.
Replicated crossover designs
For replicated crossover designs, the default model used in the Bioequiva-
lence Wizard is the example model given for replicated designs in Appendix
E of the FDA guidance:
Fixed effects model is:
DependentVariable = Intercept + Sequence + Formulation + Period
Random effects model is:
Treatment
Variance Blocking Variable set to Subject
Type set to Banded No-Diagonal Factor Analytic with 2 factors
Repeated specification is:
Period
Variance Blocking Variables set to Subject
Period 1 Period 2 Period 3
Sequence 1 T R T
Sequence 2 R T R
Period 1 Period 2
Sequence 1 T R
Sequence 2 R T
WinNonlin
Users Guide
422
16
Group set to Treatment
Type set to Variance Components
Rather than using the implicit repeated model as in Appendix E, the time vari-
able is made explicit as Period.
Nonreplicated crossover designs
For nonreplicated crossover designs, the default model used in the Bioequiva-
lence Wizard is as follows.
Fixed effects model is:
DependentVariable = Intercept + Sequence + Formulation + Period
Random effects model is the nested term:
Subject(Sequence)
There is no repeated specification, so the default error model ~ N(0,
2
I)
will be used. This is equivalent to the classical analysis method, but using
maximum likelihood instead of method of moments to estimate inter-subject
variance. Using Subject as a random effect this way, the correct standard
errors will be computed for sequence means and tests of sequence effects.
Using a fixed effect model, one must construct pseudo-F tests by hand to
accomplish the same task.
Parallel designs
For parallel designs, the default model used in the Bioequivalence Wizard is
as follows.
Fixed effects model is:
Formulation
There is no random model and no repeated specification, so the residual error
term is included in the model.
Note: In each case, the user may supplement or modify the model to suit the analysis
needs of the data set in consideration.
Bioequivalence
Average bioequivalence
423
16
Least squares means
In determining the bioequivalence of a test formulation and a reference for-
mulation, the first step is the computation of the least squares means and stan-
dard errors of the test and reference formulations and the standard error of the
difference of the test and reference least squares means. These quantities are
computed by the same process that is used for the Linear Mixed Effects mod-
ule. See Least squares means on page 383.
To simplify the notation for this section, let:
RefLSM = reference least squares mean (computed by LinMix),
TestLSM = test least squares mean (computed by LinMix),
fractionToDetect = (user-specified percent of reference to detect) / 100,
DiffSE = standard error of the difference in least squares means (com-
puted by LinMix),
RatioSE = standard error of the ratio of the least squares means.
The geometric least squares means are computed if the user specified that the
data was to be transformed or was already transformed. For ln-transform or
data already ln-transformed,
For log10-transform or data already log10-transformed,
The difference is the test least squares mean minus the reference least squares
mean,
Calculation of the ratio depends on the transformation of the data. For data
that is not transformed,
RefGeoLSM = exp(RefLSM)
TestGeoLSM = exp(TestLSM)
RefGeoLSM = 10
RefLSM
TestGeoLSM = 10
TestLSM
Difference = TestLSM RefLSM
WinNonlin
Users Guide
424
16
For ln-transform or data already ln-transformed, the ratio is obtained on arith-
metic scale by exponentiating,
Similarly for log10-transform or data already log10-transformed, the ratio is
Classical and Westlake confidence intervals
Output from the Bioequivalence module includes the classical confidence
intervals and Westlake confidence intervals for confidence levels equal to 80,
90, 95, and for the confidence level that the user gave on the bioequivalence
tab if that value is different than 80, 90, or 95. To compute the classical confi-
dence intervals, first the following values are computed using the students-t
distribution, where alpha = (100 confidenceLevel) / 100
These values are then transformed if necessary to be on the arithmetic scale,
and translated to percentages. For ln-transform or data already ln-transformed,
For log10-transform or data already log10-transformed,
Ratio(%Ref) = 100 TestLSM / RefLSM
Ratio(%Ref) = 100 exp(Difference)
Ratio(%Ref) = 100 10
Difference
lower = Difference t
(1-alpha/2),df
DiffSE
upper = Difference + t
(1-alpha/2),df
DiffSE
CI_Lower = 100 exp(lower)
CI_Upper = 100 exp(upper)
CI_Lower = 100 10
lower
CI_Upper = 100 10
upper
Bioequivalence
Average bioequivalence
425
16
For no transform,
where the approximation RatioSE = DiffSE / RefLSM is used. Similarly,
The procedure for computing the Westlake confidence intervals is given in
many statistical references. See, for example, Chow and Liu (2000), page 86.
Computing these intervals is an iterative procedure for which the Nelder-
Mead simplex algorithm is used. It is possible that there will not be conver-
gence, in which case the Bioequivalence module will print Not Estimable.
The bioequivalence conclusion that appears in the text output depends on the
user-specified values for the confidence level and for the percent of reference
to detect; these options are entered on the bioequivalence options tab of the
Bioequivalence wizard. To conclude whether bioequivalence has been
achieved, the CI_Lower and CI_Upper for the user-specified value of the con-
fidence level are compared to the following lower and upper bounds. Note
that the upper bound for log10 or ln-transforms or for data already trans-
formed is adjusted so that the bounds are symmetric on a logarithmic scale.
If the interval (CI_Lower, CI_Upper) is contained within LowerBound and
UpperBound, then average bioequivalence has been shown. If the interval
(CI_Lower, CI_Upper) is completely outside the interval (LowerBound,
UpperBound), then average bioinequivalence has been shown. Otherwise, the
CI_Lower = 100(1+lower/RefLSM)
= 100(1+(TestLSMRefLSM)/RefLSMt
(1-alpha/2),df
*DiffSE/RefLSM)
= 100(TestLSM/RefLSMt
(1alpha/2),df
RatioSE)
CI_Upper = 100 (1 + upper / RefLSM)
LowerBound = 100 (percent of reference to detect)
UpperBound (ln-transforms) = 100 exp( ln(1 fractionToDetect) )
= 100 (1 / (1 fractionToDetect))
UpperBound (log10-transforms) = 100 10 ^ ( log10(1.0 fractionToDe-
tect))
= 100 (1 / (1 fractionToDetect))
UpperBound (no transform) = 100 + (percent of reference to detect)
WinNonlin
Users Guide
426
16
bioequivalence module has failed to show bioequivalence or bioinequiva-
lence.
Two one-sided T-tests
For ln-transform or data already ln-transformed, the first t-test is a left-tail test
of the hypotheses:
The test statistic for performing this test is:
The p-value is determined using the t-distribution for this t-value and the
degrees of freedom. If the p-value is <0.05, then the user can reject H
0
at the
5% level, i.e. have less than a 5% chance of rejecting H
0
when it was actually
true.
For log10-transform or data already log10-transformed, the first test is done
similarly using log10 instead of ln.
For data with no transformation, the first test is (where Ratio here refers to
Ratio(%Ref) / 100 ):
The test statistic for performing this test is:
where the approximation RatioSE = DiffSE / RefLSM is used.
The second t-test is a right-tail test which is a symmetric test to the first. How-
ever for log
10
or ln-transforms, the test will be symmetric on a logarithmic
H
0
: Difference < ln(1 fractionToDetect) (bioinequivalence for left
test)
H
1
: Difference ln(1 fractionToDetect) (bioequivalence for left test)
t
1
= ( (TestLSM RefLSM) ln(1 fractionToDetect) ) / DiffSE
H
0
: Ratio < 1 fractionToDetect
H
1
: Ratio 1 fractionToDetect
t
1
= [ (TestLSM / RefLSM) (1 fractionToDetect) ] / RatioSE
Bioequivalence
Average bioequivalence
427
16
scale. For example, if the percent of reference to detect is 20%, then the left-
tail test is Pr(<80%), but for ln-transformed data, the right-tail test is
Prob(>125%), since ln(0.8) = ln(1.25).
For ln-transform or data already ln-transformed, the second test is a right-tail
test of the hypotheses:
The test statistic for performing this test is:
For log10-transform or data already log10-transformed, the second test is
done similarly using log
10
instead of ln.
For data with no transformation, the second test is:
The test statistic for performing this test is:
where the approximation RatioSE = DiffSE / RefLSM is used.
The output for the two one-sided t-tests includes the p-value for the first test
described above, the p-value for the second test above, the maximum of these
p-values, and total of these p-values. The two one-sided t-tests procedure is
operationally equivalent to the classical confidence interval approach. That is,
if the classical (1-2alpha) 100% confidence interval for difference or ratio
is within LowerBound and UpperBound, then both the H
0
s given above for
the two tests are also rejected at the alpha level by the two one-sided t-tests
procedure.
H
0
: Difference > ln(1 fractionToDetect) (bioinequivalence for right
test)
H
1
: Difference ln(1 fractionToDetect) (bioequivalence for right
test)
t
2
= ( (TestLSM RefLSM) + ln(1 fractionToDetect) ) / DiffSE
H
0
: Ratio > 1 + fractionToDetect
H
1
: Ratio 1 + fractionToDetect
t
2
= ( (TestLSM / RefLSM) (1 + fractionToDetect) ) / RatioSE
WinNonlin
Users Guide
428
16
Anderson-Hauck test
See Anderson and Hauck (1983), or page 99 of Chow and Liu (2000). Briefly,
the Anderson-Hauck test is based on the hypotheses:
H
01
:
T
-
R
<
L
vs. H
A1
:
T
-
R
>
L

H
02
:
T
-
R
>
U
vs. H
A2
:
T
-
R
<
U

where
L
and
U
are the lower and upper Anderson-Hauck limits; these limits
are entered on the bioequivalence options tab. Rejection of both null hypothe-
ses implies bioequivalence. The Anderson-Hauck test statistic is t
AH
given by
where Diff SE is the standard error of the difference in means. Under the null
hypothesis, this test statistic has a noncentral t-distribution.
Power
Next in the output is the Power. This is the post-hoc probability of detecting a
difference greater than or equal to a specified percentage of the reference least
squares mean. In general,
In the bioequivalence calculations, the hypotheses being tested are:
For the no-transform case, the power is the probability of rejecting H
0
given
that:
Power = 1 (probability of a type II error)
= probability of rejecting H
0
when H
1
is true.
H
0
: RefLSM = TestLSM
H
1
: RefLSM TestLSM
|TestLSM RefLSM | fractionToDetect RefLSM
t
AH
Y
T
Y
R

L

U
+ ( ) 2
Diff SE
------------------------------------------------------- =
Bioequivalence
Average bioequivalence
429
16
For ln-transform, and data already ln-transformed, this changes to:
and similarly for log10-transform and data already log10-transformed.
For the sake of illustration, assume fractionToDetect = 0.2, RefLSM>0, and
no transform was done on the data. Also note that the maximum probability of
rejecting H
0
occurs in the case of equality, |TestLSM RefLSM| =
0.2RefLSM. So:
Let:
Then:
Note that t
stat
is T-distributed. Let p
1
be the p-value associated with t
1
(the
area in the tail), and let p
2
be the p-value associated with t
2
(the area in the
tail; note that p
2
may be negligible). Then:
|TestLSM RefLSM | ln (1 fractionToDetect),
Power = Pr (rejecting H
0
at the alpha level given |Difference| = 0.2RefLSM
= Pr (|Difference/DiffSE | > t
(1-alpha/2), df
given |Difference| = 0.2RefLSM
= Pr (Difference/DiffSE > t
(1-alpha/2),df
given |Difference| = 0.2RefLSM
+ Pr (Difference/DiffSE < t (
1-alpha/2),df
given |Difference| = 0.2RefLSM
t
1
= t
(1-alpha/2),df
0.2RefLSM / DiffSE
t
2
= t
(1-alpha/2),df
0.2RefLSM / DiffSE
t
stat
= (Difference 0.2RefLSM / DiffSE
Power = Pr(t
stat
> t
1
given |Difference| = 0.2RefLSM)
+ Pr(t
stat
< t
2
given |Difference| = 0.2RefLSM)
Power = 1 (p
1
p
2
)
WinNonlin
Users Guide
430
16
Individual and population bioequivalence
Introduction
Individual and population bioequivalence are used to assess switchability and
prescribability. Because individual bioequivalence relies on estimates of
within-subject, within-formulation variation, replicated crossover designs are
required. This algorithm was developed by Francis Hsuan. Designs that can
be appropriately analyzed include, but are not limited to,
The algorithm works for both balanced and unbalanced data.
Note: Each sequence must contain the same number of periods. For each period,
each subject must have one measurement.
Bioequivalence criterion
The FDAproposed population bioequivalence (PBE) criteria are
if
Sequence Period Design
2 4 TRTR/RTRT
4 4 TRTR/RTRT/TRRT/RTTR
4 2 TT/RR/TR/RT
4 3 TRT/RTR/TRR/RTT
2 5 TRRTT/RTTRR
3 3 TRR/RTR/RRT
2 3 RTR/TRT
6 3 TRR/RTT/TRT/RTR/TTR/RRT
2 4 TRRR/RTTT
6 4 TTRR/RRTT/TRRT/RTTR/TRRR/RTTT
E Y
jT
Y
j' R
( )
2
E Y
jR
Y
j' R
( )
2

1
2
---
E Y
jR
Y
j' R
( )
2
-------------------------------------------------------------------------
P
<
R

P
>
Bioequivalence
Individual and population bioequivalence
431
16
if
where
P
defaults to 0.2 and
P
= (ln(1 - PercentReference) +
P
) /
P
2
. The
default value for PercentReference is 0.20. In the wizard,
P
is called the
Total SD standard.
R
2
is computed by the program and is the total variance of
the reference formulation, i.e., the sum of within- and between-subject vari-
ance. The criteria take the linearized form
The FDAproposed individual bioequivalence (IBE) criteria are
f
where
I
defaults to 0.2 and
I
= (ln(1 PercentReference) +
I
) /
I
2
. The
default value for Percent Reference is 0.20, and the default value for
I
is 0.05.
In the wizard,

is called the within-subject SD standard.


WR
2
is computed
by the program and is the within-subject variance of the reference formula-
tion. The IBE criteria take the linearized form
if
if
if
if
if and
E Y
jT
Y
j' R
( )
2
E Y
jR
Y
j' R
( )
2
1
2
---
P
2
-------------------------------------------------------------------------

P
<
R

P

P1
E
T

R
( )
2

T
2
1
P
+ ( )
R
2
+ 0 < =

R

P
>

P2
E
T

R
( )
2

T
2

R
2

P

P
2
+ 0 < =

R

P

E Y
jT
Y
j R
( )
2
E Y
jR
Y
j' R
( )
2

1
2
---
E Y
jR
Y
j' R
( )
2
------------------------------------------------------------------------
I
<
WR

I
>
E Y
jT
Y
j R
( )
2
E Y
jR
Y
j' R
( )
2

1
2
-- -
I
2
------------------------------------------------------------------------

I
<
WR

I

I1
E
T

R
( )
2

D
*

WT
2
1
I
+ ( )
WR
2
+ + 0 < =

WR

I
>

I2
E
T

R
( )
2

D
*

WT
2

WR
2

I

I
2
+ + 0 < =
WinNonlin
Users Guide
432
16
where will be defined below.
For reference scaling, use
P1
or
I1
. For constant scaling, use
P2
or
I2
. For
mixed scaling, use one of the following.
If the upper confidence bound on the appropriate is less than 0, then the
product is bioequivalent in the chosen sense. The coverage of the confidence
interval is set on the Bioequivalence Options page. The method of calculating
that upper confidence bound follows.
Details of computations
Let Y
ijkt
be the response of subject j in sequence i at time t with treatment k,
and be a vector of responses for subject j in sequence i. The components
of Y are arranged in the ascending order of time. Let and be the
design vector for treatment T and R respectively in sequence i, n
i
> 1, be the
number of subjects in sequence i.
Assume the mean responses of , follow a linear model

where
T
,
R
are the population mean responses of Y with treatments T and R
respectively, and X
i
are design/model matrices.
Let p
iT
:= sum( ) and p
iR
:= sum( ) be the number of occasions T and R
respectively be assigned to the subjects in sequence i,
,
if
Population If
R
>
P
use
P1
If
R

P
use
P2
Individual If
WR
>
I
use
I1
If
WR

I
use
I2
(1a)

WR

I

D
*
Y

i j
'
Z

i T
Z

i R
Y

i j

i
Z

iT

T
Z

i R

R
+ =
Z

i T
Z

i R
u

i T
: p
i T
1
Z

i T
=
Bioequivalence
Individual and population bioequivalence
433
16
,
,
and .
Assume that the covariances follow the model

where the parameters
are defined as follows:
and are var and var
respectively,
is the intra-subject correlation coefficient corr ,
is the intra-subject correlation coefficient corr,
,
is the intra-subject coefficient corr ,
, , and are the intra-
subject covariances,
is the intra-subject variance , and
is the intra-subject variance .
For PBE and IBE investigations, it is useful to define several additional
parameters:
(1b)
u

i R
: p
i R
1
Z

iR
=
u

i I
: u

i T
u

i R
( ) =
d

i
: s
T
1
u

i T
s
R
1
u

iR
=
Y

i jkt
Y

ij k' t'
( , )

i

WT
2
diag Z

iT
( )
WR
2
diag Z

iR
( )
TT
Z

i T
Z'

i T

RR
Z

iR
Z'

i R

TR
Z

iT
Z'

iR
Z

i R
Z'

iT
+ { }
+ +
+ +
=

WT
2

WR
2

TT

RR

TR
, , , { , } =

T
2

TT

WT
2
+ =
R
2

RR

WR
2
+ = Y
i j Tt
( )
Y
i j Rt
( )

TT

TT

T
2
= Y
T
Y
T'
( , )
1
TT
0 > >

RR

RR

R
2
=
Y
R
Y
R'
( , ) 1
RR
0 > >

TR

TR

T

R
( ) = Y
T
Y
R
( , )
1
TR
1 > >

TT

TT

T
2
=
RR

RR

R
2
=
TR

TR

R
=

WT
2

T
2

TT
= Y
T
Y
T'
( ) 2

WR
2

R
2

RR
= Y
R
Y
R'
( ) 2
WinNonlin
Users Guide
434
16
Except for (2a), all the quantities above are non-negative when they exist. The
quantity is similar, but not identical, to the subject-by-formulation variance
component proposed in the mixed model discussed in FDA draft guidance
Section III. It satisfies the equation
In general, this may be negative, while FDAs is always non-nega-
tive. The FDA mixed model is a special case of the multivariate model above,
and the quantity is identical to whenever the former is nonnegative.
This method for PBE/IBE is based on the multivariate model. It yields identi-
cal results to those described in the FDA draft guidance Appendices F & H
when the design is TRTR/RTRT. This method is applicable to a variety of
higher-order two-treatment crossover designs including TR/RT/TT/RR (the
Balaam Design), TRT/RTR, or TxRR/xRTT/RTxx/TRxx/xTRR/RxTT (Table 5.7
of Jones and Kenward, page 205).
Given the ith sequence, let
, ,
(2a)
(2b)
(2c)
(2d)

D
*

TT

RR
2
TR
+ =

i T
*2

T
2
1 p
iT
1
( )
WT
2
( ) =

i R
*2

R
2
1 p
i R
1
( )
WR
2
( ) =

i I
*2

D
*
p
i T
1

WT
2
p
iR
1

WR
2
+ + ( ) =
var Y
i jT
Y
i j R
( )
D
*

WT
2

WR
2
+ + =

D
*

D
2

D
*

D
2

d'

i
Y
i
i

=
S
i T
u'

i T
V
i
u

i T
= S
i R
u'

iR
V
i
u

i R
= S
i I
u'

i I
V
i
u

i I
=
S
iWT
1 p
iT
1
( )
1
tr diag u

i T
( )V
i
{ } u'

i T
V
i
u

iT
( ) =
S
iWR
1 p
iR
1
( )
1
tr diag u

iR
( )V
i
{ } u'

i R
V
i
u

iR
( ) =
Bioequivalence
Individual and population bioequivalence
435
16
where is the sample mean of the ith sequence, and V
i
is the within-
sequence sample covariance matrix.
It can be shown that
Furthermore, it can be shown that {S
iT
, S
iR
} (for PBE) are statistically inde-
pendent from {} and {S
iWT
, S
iWR
}, and that the four statistics , S
iI
, S
iWT
,
S
iWR
(for IBE) are statistically independent.
Let
i
s be sets of normalized weights, chosen to yield the method of
moments estimates of the s. Then define the estimators of the components
of the linearized criterion by
(4a)
(4b)
(4c)
(4d)
(4e)
(4f)
,
,
,
,
,
Y
i

N
T

R
n
i
1
d'

i
d

i
i

( , )
S
i T

iT
*2
n
i
1 ( )
1

2
n
i
1

S
i R

i R
*2
n
i
1 ( )
1

2
n
i
1

S
i I

i I
*2
n
i
1 ( )
1

2
n
i
1

S
i WT

WT
2
p
iT
1 ( )
1
n
i
1 ( )
1

2
p
iT
1 ( ) n
i
1 ( )

S
i WR

WR
2
p
i R
1 ( )
1
n
i
1 ( )
1

2
p
iT
1 ( ) n
i
1 ( )

E
0

2
=
E
P1

iT
S
i T
i

=
E
P2
1
i T
p
i T
1
i

\ .
|
| |

iWT
S
iWT
i

=
E
P3

i R
S
i R
i

=
E
P4
1
i R
p
i R
1
i

\ .
|
| |

iWR
S
i WR
i

=
WinNonlin
Users Guide
436
16
Using the above notation, one may define unbiased moment estimators for the
PBE criteria:
and for the IBE criteria:
The FDA Guidance specifies a procedure to construct a 95% upper bound for
based on the TRTR/RTRT design using Howes approximation I and a mod-
ification proposed by Hyslop, Hsuan and Holder (2000). This can be gener-
alized to compute the following sets of n
q
, H and U statistics:
,
,
,
,
E
I1

i I
S
iI
i

=
E
I2
1
i I
p
i T
1
i

\ .
|
| |

i WT
S
i WT
i

=
E
I3a
1
I

i I
p
i R
1
i

+ +
\ .
|
| |

i WR
S
i WR
i

=
E
I3b
1
i I
p
i R
1
i

+
\ .
|
| |

i WR
S
i WR
i

P1

2

E
P1
E
P2
1
P
+ ( )E
P3
1
P
+ ( )E
P4
+ + =

P2

2
E
P1
E
P2
E
P3
E
P4

P

P
2
+ + =

I1

2
E
I1
E
I2
E
I3a
+ + =

I2

2
E
I1
E
I2
E
I3b

I

I
2
+ + =

H
0

t
.95, n
0
var

( ) ( )
1 2
+
\ .
| |
2
=
Bioequivalence
Bioequivalence Wizard
437
16
where the degrees of freedom n
q
are computed using Satterthwaites approxi-
mation. Then, the 95% upper bound for each is
,
where for q = P3, P4, and = U
q
for all other q. If H
q

< 0, that indicates bioequivalence; H
q
> 0 fails to show bioequivalence.
Bioequivalence Wizard
To set up and run a bioequivalence analysis:
1. Open the data set to be analyzed.
2. Start the Bioequivalence Wizard by choosing Tools>Bioequivalence Wizard
or by clicking on the Bioequivalence Wizard tool bar button.
for q = P1, P2, I1 and I2.
for q = P3, P4, I3a and I3b.
for all q
H
q
n
q
E
q

.05, n
q
2
=
H
q
n
q
E
q

.95,
2

n
q
=
U
q
H
q
E
q
( )
2
=
H

U
q
*

\ .
| |
1 2
+ =
U
q
*
1
P
+ ( )
2
U
q
= U
q
*
WinNonlin
Users Guide
438
16
3. The Bioequivalence Wizard provides two options for using prior model set-
tings (optional), as follows. To create a new analysis, proceed to step 4 below.
To load a previously-saved bioequivalence model, click the Load button.
To reload the most recently run model, click the Previous Model button.
Click Calculate to run the model.
4. Type of Bioequivalence: Select individual/population or average bioequiva-
lence using the radio buttons at the upper right. For a discussion of the analy-
sis types, see Average bioequivalence on page 420 and Individual and
population bioequivalence on page 430.
5. For average bioequivalence, select the study type at the top left.
Based on the analysis and study types, WinNonlin will try to match the vari-
able names from the active data set with the Subject, Sequence, Period, and
Formulation fields.
6. If WinNonlin has not already selected the appropriate variables, select the
variables that identify the Subject, Sequence, Period, and Formulation.
7. Select the reference formulation, against which to test for bioequivalence,
from the pull down list labeled Reference Value.
Note: For Average bioequivalence with a parallel study type, only Formulation and
its reference value need to be specified.
8. Click Next to proceed with the analysis:
Using average bioequivalence on page 438
Using population/individual bioequivalence on page 444
Using average bioequivalence
See the Examples Guide for an example using average bioequivalence.
Average bioequivalence analysis settings fall under the following headings:
Fixed effects for average bioequivalence on page 439
Variance structure on page 440
Bioequivalence options on page 443
Bioequivalence
Bioequivalence Wizard
439
16
Bioequivalence general options on page 443
Fixed effects for average bioequivalence
The dependent variable(s), regressor(s)/covariate(s), and sort variable(s) must
be specified. For Average bioequivalence other classification variables can be
added by dragging them from the Variable Collection to the Classification
Variable field. The Bioequivalence Wizard Fixed Effects dialog works very
much like the LinMix Fixed Effects dialog. See Fixed effects on page 391.
To define the fixed effects model:
1. Drag and drop variables to categorize those needed in the LinMix model:
Dependent variables contain the values to which the model will be fit,
e.g., drug concentration.
Classification variables or factors are categorical independent variables,
e.g., formulation, treatment, and gender.
Regressor variables or covariates are continuous independent variables,
e.g., temperature or body weight.
Sort variables define subsets of data to be processed separately, that is, a
separate analysis will be done for each level of the sort variables. If the
Sort variable has missing values, the analysis will be performed for the
missing level and MISSING will be printed as the current value of the
Sort variable.
A weight variable can be included if weights for each record are included
in a separate data column. The weights are used to compensate for obser-
vations having different variances. When a weight variable is specified,
each row of data is multiplied by the square root of the corresponding
weight. Weight variable values should be proportional to the reciprocals
of the variances. In the most common situation, the data are averages and
weights are sample sizes associated with the averages. See also Weight-
ing on page 325.
The Weight Variable cannot be a classification variable. It must
have been declared as a regressor/covariate before it can be used
as a weight variable. It can also be used in the model.
WinNonlin
Users Guide
440
16
For Average bioequivalence the Model Specification field automatically dis-
plays an appropriate fixed effects model for study type. Edit the model as
needed For discussion of the model, see The model on page 420.
Note: To reuse a model in a command file (*.LML), click the Load Model button. To
reuse the most recently run model, click the Previous Model button.
2. Accept the default setting [95] or enter the Fixed Effects Confidence Level.
This is the confidence level for the parameter estimates. The confidence level
for the bioequivalence test is specified later.
3. (Optional) Select a log transformation from the pull down list for Dependent
Variables Transformation. Select Ln(x) or Log(x) to transform the values
before analysis. If the input data are already transformed, select Already Ln-
transformed or Already Log10-transformed.
4. Click Calculate to run the model with default settings, or Next to proceed to
the Variance structure.
Variance structure
The Bioequivalence Wizard Variance Structure dialog operates exactly as it
does in the LinMix wizard. See also Variance structure on page 393.
Bioequivalence
Bioequivalence Wizard
441
16
The Random tab
1. The classification variables and regressors are displayed in the fields at the
top of the dialog. Drag and drop them (or type them) to edit the random
effects model(s) as needed.
2. (Optional) Drag the appropriate variable to the Variance Blocking Variables
(Subject) field. The variable here must be a classification model term. This
field identifies the subjects in a data set. Complete independence is assumed
among subjects. Thus, Subject produces a block diagonal structure with iden-
tical blocks.
3. (Optional) Drag the appropriate variable to the Group field. This variable
must be a classification model term. It defines an effect specifying heteroge-
neity in the covariance structure. All observations having the same level of the
group effect have the same covariance parameters. Each new level of the
group effect produces a new set of covariance parameters with the same struc-
ture as the original group.
4. If a random effects model is specified, select the type of covariance structure
in the Type list. See Variance structure on page 393 for details on each type.
5. Check Random Intercept to indicate that the intercept is random. This is
most commonly employed when a subject is specified in the Variance Block-
ing field. The default is offno random intercept.
WinNonlin
Users Guide
442
16
Note: Multiple variance models can be specified by clicking the Add Random but-
ton.
The Repeated tab
Select the Repeated tab to specify the R matrix in the mixed model. If no
Repeated statement is specified, R is assumed to be equal to . The
repeated effect must contain only classification variables. See The Repeated
tab on page 396.
To specify the repeated variance settings:
1. In the box labeled Repeated Specification, either enter the model by typing it
or by dragging the variable names and clicking on the operators to be used in
the model. For Average bioequivalence a default model is preset.
The model can be built from the classification variables and the operators at
the top of the dialog. Syntax rules for the repeated specification are the same
as those for the fixedeffects model terms.
2. (Optional) Drag the appropriate variable to the Variance Blocking Variables
(Subject) field. The variable here must be a classification model term. This
Subject field identifies the subjects in a data set. Complete independence is
assumed across subjects. Thus, Subject produces a block diagonal structure
with identical blocks.
3. (Optional) Drag the appropriate variable to the Group field. The variable here
must be a classification variable with no regressors or operators. This variable
defines an effect specifying heterogeneity in the covariance structure. All
observations having the same level of the group effect have the same covari-
ance parameters. Each new level of the group effect produces a new set of
covariance parameters with the same structure as the original group.
4. If a Repeated Specification has been included, select the type of covariance
structure from the Type list. Variance structure on page 393 for types.
Note: The default Repeated model depends upon whether the crossover study is rep-
licated or not. The default model follows the FDA guidance.
5. Click Calculate to run the analysis, or Next to proceed to the Bioequivalence
options.

2
I
Bioequivalence
Bioequivalence Wizard
443
16
Bioequivalence options
This dialog of the Bioequivalence Wizard sets the range for the bioequiva-
lence.
To set the bioequivalence options:
1. Set the following options (default settings for Average bioequivalence):
Confidence Level (90%)
Percent of Reference to Detect (20%)
Anderson-Hauck Lower Limit (0.8)
Anderson-Hauck Upper Limit (1.25 for log-transformed; 1.2 for not
transformed)
2. Click Calculate to run the analysis, or Next to proceed to the Bioequivalence
general options.
Bioequivalence general options
This dialog of the Bioequivalence Wizard sets the following operations:
ASCII output can be selected as an additional output form.
A title can be assigned as a header for the ASCII output. Press
Ctrl+Enter to move to the next line, up to a maximum of five lines.
The kind of degrees of freedom can be stipulated.
The maximum number of iterations can be set.
How output that is not estimable is to be represented may be set.
The advanced user options include:
Initial estimates for the Variance Parameters
Change defaults for Singularity Tolerance, Convergence Criterion,
and Intermediate Calculations.
When all the appropriate settings have been made, click the Calculate button
to run the model. The average bioequivalence calculations begin and the out-
put appears in a new workbook (and, depending upon the settings, an ASCII
text window as well).
WinNonlin
Users Guide
444
16
Using population/individual bioequivalence
Following is an overview of the basic steps in using the Bioequivalence Wiz-
ard for population/individual bioequivalence (see also Individual and popu-
lation bioequivalence on page 430). Depending upon the calculations
selected, some steps may be optional.
See the Examples Guide for an example using population/individual
bioequivalence.
To specify population/individual bioequivalence information:
1. Launch the Bioequivalence Wizard and set up the variables for the analysis as
described under Bioequivalence Wizard on page 437.
Note: Population/Individual bioequivalence can only use replicated crossover study
data. Each sequence must contain the same number of periods. For each
period each subject must have one measurement.
2. Click Calculate to run the model with the default settings, or Next to proceed
to the Fixed effects for population/individual bioequivalence.
Note: Use the Load Model button to load a previously-saved model. Use the Previ-
ous Model... button to reload the last-run model.
Fixed effects for population/individual bioequivalence
The Fixed effects model is prebuilt following FDA guidelines. The Bioequiv-
alence Wizard Fixed Effects dialog for population/individual bioequivalence
works very much like the LinMix Fixed Effects dialog. See Fixed effects on
page 391.
To complete the model:
1. Drag the appropriate term(s), e.g., concentration, from the Variable Collection
to the Dependent Variables field.
Appropriate terms for the kind of study are specified automatically as classifi-
cation variables. For Population bioequivalence the classification variables,
regressors, and fixed effects model are disabled because they are preset to
FDA guidelines.
Bioequivalence
Bioequivalence command files
445
16
2. (Optional) Select a log transformation from the pull down list for Dependent
Variables Transformation. Select Ln(x) or Log(x) to transform the values
before analysis. If the input data are already transformed, select Already Ln-
transformed or Already Log10-transformed.
3. Click Calculate to run the model, or Next to proceed to the Bioequivalence
options for population/individual bioequivalence.
Bioequivalence options for population/individual bioequivalence
To set the bioequivalence options:
1. The options (and their default settings for Population/Individual bioequiva-
lence) include:
Confidence Level (95%)
Percent of Reference to Detect (20%)
Population Limits
Total SD Standard (0.2)
Epsilon (0.02)
Individual Limits
Within Subject SD Standard (0.2)
Epsilon (0.05)
2. To start calculating Population/Individual bioequivalence, click Calculate.
Bioequivalence command files
Any data set and bioequivalence model can be saved as a bioequivalence
command file. This command file has a file type of .LML.
To save a bioequivalence command file:
1. With a data set open and the bioequivalence model specified in the Bioequiv-
alence Wizard, click the Save Model button. The Save Command File dialog
appears.
2. Enter the file name for the command file. Notice that the file type is already
specified as *.LML.
WinNonlin
Users Guide
446
16
3. Click Save. The command file has been saved.
To load a bioequivalence command file:
1. Select File>Open from the menus or click the Open tool bar button.
2. In the Open File dialog select LinMix Command Files (*.lml) in the Files of
type field.
3. Select the appropriate file.
Bioequivalence output
The Bioequivalence Wizard generates a new bioequivalence workbook. Popu-
lation/individual bioequivalence always generates text output as well. Aver-
age bioequivalence can produce text output as an option.
Average bioequivalence
The average bioequivalence output workbook contains the information in
Table 16-1.
Table 16-1. Average bioequivalence output worksheets
Worksheet Contents
Average Bioequivalence Output from the bioequivalence analysis
Ratio Tests Ratios of reference to test mean computed for each subject
Diagnostics Number of observations, number of observations used, residual
sums of squares, residual degrees of freedom, residual variance,
restricted log likelihood, AIC, SBC, and the Hessian eigenvalues
Sequential Tests Sort Variable(s), Dependent Variable(s), Units, Hypothesis,
Hypothesis degrees of freedom, Denominator degrees of free-
dom, F statistic, and p-value
Partial Tests Sort Variable(s), Dependent Variable(s), Units, Hypothesis,
Hypothesis degrees of freedom, Denominator degrees of free-
dom, F statistic, and p-value
Final Fixed Parameters Sort variables, dependent variable(s), units, effect level, parame-
ter estimate, t-statistic, p-value, confidence intervals, etc.
Bioequivalence
Bioequivalence output
447
16
To determine average bioequivalence of a test formulation and a reference
formulation the first step is the computation of the least squares means of the
test formulation and the reference formulation and their standard errors, and
computation of the standard error of the difference of the test and reference
least squares means and degrees of freedom for the difference. These quanti-
ties are computed by the same program that is used for the Linear Mixed
Effects module, LinMix. Therefore the output for average bioequivalence
includes all the output that was obtained by running LinMix. This output is
described in LinMix output on page 401. The output also contains the Aver-
age Bioequivalence Statistics; these are described in detail in Introduction to
bioequivalence on page 417. For crossover designs, the output also contains
the ratios table, described under Ratio tables on page 449.
Population/Individual bioequivalence
Final Variance Parame-
ters
Final estimates of the variance parameters
Parameter Key Variance parameter names assigned by WinNonlin
Least Squares Means Sort Variable(s), Dependent Variable(s), Units, and the least
squares means for the test formulation
LSM Differences Difference in least squares means
Residuals Sort Variable(s), Dependent Variable(s), Units, and information
on residual effects vs. predicted and observed effects
User Settings User-specified settings
Initial Variance Parame-
ters
Parameter and estimates for variance parameters
Iteration History Iteration, Obj_function, and column for each variance parameter
Table 16-2. Population/individual output worksheets
Worksheet Contents
Population/Individual
Bioequivalence
Output from the bioequivalence analysis
Ratio Tests Ratios of reference to test mean
User Settings User-specified settings
Table 16-1. Average bioequivalence output worksheets (continued)
Worksheet Contents
WinNonlin
Users Guide
448
16
Depending upon what settings have been specified in the wizard, the output
may not have all of these worksheets.
Errors and warnings in the computations are recorded in the ASCII output as
well as in the application log or data history.
The population/individual bioequivalence statistics are described further in
Introduction to bioequivalence on page 417. They include:
Difference (Delta) = difference in sample means between the test and refer-
ence formulations.
Ratio(%Ref) = ratio of the test to reference means expressed as a percent. This
is compared with the percent of reference to detect that was specified by the
user, to determine if bioequivalence has been shown. For example, if the user
specified a percent of reference to detect of 20%, and also specified a ln-trans-
form, then Ratio(%Ref) needs to be in the interval (80%, 125%) to show
bioequivalence for the ratio test.
Note: The FDA guidance suggests that both the ratio test and the tests listed below
need to be passed to indicate bioequivalence.
SigmaR - value that is compared with sigmaP, the Total SD Standard, to deter-
mine whether mixed scaling for population bioequivalence will use the con-
stant-scaling values or the reference-scaling values.
SigmaWR - value that is compared with sigmaI, the Within Subject SD Stan-
dard, to determine whether mixed scaling for individual bioequivalence will
use the constant-scaling values or the reference-scaling values.
Each of the following is given along with its upper confidence bound and a
conclusion about bioequivalence. Bioequivalence has been shown if the upper
confidence bound is less than 0.
Table 16-3. Population/Individual Bioequivalence Calculations
Statistic Indication
Const_Pop_eta Test statistic for population bioequivalence with constant scaling
Ref_Pop_eta Test statistic for population bioequivalence with reference scaling
Mixed_Pop_eta Test statistic for population bioequivalence with mixed scaling
Const_Indiv_eta Test statistic for individual bioequivalence with constant scaling
Bioequivalence
Bioequivalence output
449
16
For crossover designs, the output also contains the ratio tables, below.
Ratio tables
For any bioequivalence study done on a crossover design, the output also
includes for each test formulation a table of differences and ratios of the orig-
inal data computed individually for each subject. This is in response to the
FDA guidance Measures for each individual should be displayed in parallel
for the formulations tested. In particular, for each BE measure the ratio of the
individual geometric mean of the T product to the individual geometric mean
of the R product should be tabulated side by side for each subject.
Let test be the value of the dependent variable measured after administration
of the test formulation for one subject. Let ref be the corresponding value for
the reference formulation, for the case in which only one dependent variable
measurement is made. If multiple test or reference values exist for the same
subject, then let test be the mean of the values of the dependent variable mea-
sured after administration of the test formulation, and similarly for ref, except
for the cases of ln-transform and log10-transform where the geometric
mean should be used:
ln-transform:
log10-transform:
where X
i
are the measurements after administration of the test formulation,
and similarly for ref.
For each subject, for the cases of no transform, ln-transform, or log10-trans-
form, the ratios table contains:
Difference = test ref.
Ratio(%Ref) = 100 test / ref.
For data that was specified to be already ln-transformed, these values are
back-transformed to be in terms of the original data:
Ref_Indiv_eta Test statistic for individual bioequivalence with reference scaling
Mixed_Indiv_eta Test statistic for individual bioequivalence with mixed scaling
Table 16-3. Population/Individual Bioequivalence Calculations
Statistic Indication
test X
i
( ) ln N
i

\ .
|
| |
exp =
test 10
N
1
log
10
X
i
i

=
WinNonlin
Users Guide
450
16
Difference = exp(test) exp(ref).
Ratio(%Ref) = 100exp(test ref) = 100exp(test)/exp(ref)
Similarly, for data that was specified to be already log10-transformed:
Difference = 10
test
10
ref
Ratio(%Ref) = 10010
test ref
= 10010
test
/10
ref
Note: For data that was already transformed, if the mean of the values is used for
test or ref, and the antilog of test or ref is taken in the equations above, then
this is equal to the geometric mean.
Missing data
For population and individual bioequivalence, the program assumes complete
data and does not allow missing observations.
If a subject has a missing observation, then that subject is not included in the
analysis. If the data have a lot of missing observations, then one should con-
sider imputing estimated values to produce complete records per subject. This
program does not impute missing values.
451
Chapter 17
Simulation
Generating response values based on a model, a
set of time (X variable) values, and doses
WinNonlin simulations can use library models or user defined models to cal-
culate response values. This capability is especially useful, for example, in
simulating steady state responses from single dose data, comparing drug con-
centrations for different dosing regimens or for different values of model
parameters (such as absorption or elimination rates). Simulations are also use-
ful when writing custom models. Running a simulation of a model can
quickly uncover errors in the model specification.
Simulating responses
Simulation of output values requires a set of time or other X-variable values, a
model, parameter values for that model, and dosing constants (for some mod-
els). Simulations can use any compiled or ASCII model, including a user
model. The model, data variables, and dosing are set up as for model fitting,
as detailed under Compartmental Modeling on page 247, except that no Y
variable is specified, and the Simulate check box, in the Data Variables dialog,
must be checked. An example is provided below, to illustrate.
See the Examples Guide for an example using simulation to evaluate compet-
ing sampling schedules, and an example of simulation using a user-defined
ASCII model.
Simulation of a compiled library model
This example uses a compiled WinNonlin library model to illustrate the use of
simulation to generate multiple-dose concentrations based on parameters from
fitting single-dose data. Note that a compiled or ASCII model could be used.
WinNonlin
Users Guide
452
17
Creating the input data
Simulation requires a data set with X values defining the time points over
which to simulate Y variable values. This example uses a data set with times
ranging from 0 to 36 hours, in increments of 0.18 hours.
To create the time value data:
1. Select File>New from the WinNonlin menus.
2. In the resulting dialog box, select the Work-
book radio button and click OK. A new work-
book appears with two worksheets: the first, for
data, the second, an automatic record of the
data history.
3. Enter time values in the first column. To enter all of the times quickly; enter 0
in the first row, and =A1+.18 in cell A2. Next, highlight cell A2 and position
the cursor over the lower right hand corner of the cell until the cursor changes
into a small black cross. Hold the left mouse button down, and drag down to
Row 201 before releasing the mouse button. The formula will be copied to all
of these cells, incrementing the time value by 0.18 in each row.
4. Use Data>Column Properties in the menus, or double-click on the column
header, to name Column A: Time.
Simulation
Simulation of a compiled library model
453
17
Setting up the model
The kinetics will be modeled by a two-compartment open model with first-
order input, Model 11 from WinNonlin's compiled pharmacokinetic library.
When simulating, the process of selecting the model (a compiled model or an
ASCII model) is exactly the same as it would be when modeling.
To select the PK model:
1. Choose Tools>PK/PD/NCA Analysis Wizard from the menus or click the
PK/PD/NCA Analysis Wizard tool bar button.
2. Select Pharmacokinetic in the Model Types dialog, and confirm that the
Compiled check box is selected.
WinNonlin
Users Guide
454
17
3. Click Next.
4. Select Model 11.
5. Click Next.
6. Click Finish to load the model.
Data variables
The Simulate Data check box in the Data Variables dialog selects simulation
rather than model fitting. The time variable must be identified.
To set model variables:
1. Choose Model>Data Variables from the menus.
2. Drag Time to the X Variable box.
3. Check the Simulate Data check box.
Simulation
Simulation of a compiled library model
455
17
4. Click OK.
Model parameters
The simulation requires parameter values for the model. The will be treated as
constants in order to calculate output values.
To enter parameter values:
1. Select Model>Model Parameters from the menus.
2. Enter the parameter values into the grid as shown below.
V_F: 10 K01: 5
WinNonlin
Users Guide
456
17
3. Click OK.
Dosing regimen
This example will dose 150 mg every 24 hours.
To enter the dosing information:
1. Choose Model>Dosing Regimen from the menus.
2. Enter the values shown in the table below.
3. Enter mg in the Current Units field.
K10: 0.2 K12: 1.5
K21: 1
Dosing Constant Value
Number of doses 2
Dose #1 150
Time of dose #1 0
Dose #2 150
Time of dose #2 24
Simulation
Simulation of a compiled library model
457
17
4. Click OK.
Model options
To specify model options:
1. Click the Model Options tool bar button or choose Model>Model Options
from the menus.
2. Select the PK Settings tab, and uncheck the Transpose Final Parameter
Table check box.
WinNonlin
Users Guide
458
17
3. Click OK.
Running the simulation
To start the simulation:
1. Click the Start Modeling button or choose Model>Start Modeling from the
menus. The simulated data appear in new output windows. The simulated
response data appear in the Summary Table worksheet of the PK Workbook,
and in the PK Chart output.
Figure 17-1. The PK workbook, Summary Table
The Variation Inflation Factor (VIF) is useful in determining optimal sam-
pling schedules for parameter estimation. Lower VIF values indicate better
estimates. See the Examples Guide for an example using WinNonlin simula-
tions for study design.
Figure 17-2. The PK chart output
Simulation
Comparing dosing schemes
459
17
Comparing dosing schemes
Simulations provide an easy and powerful means for modifying a scenario to
see the impact on drug concentrations or effects. For example, modify the pre-
vious simulation, keeping the total daily dose of 150, but this time administer-
ing 75 mg every 12 hours.
After the previous simulation (Simulation of a compiled library model on
page 451) is run, WinNonlin remembers the values input for the Data Vari-
ables, Model Parameters, and Dosing Regimen. Only the Dosing Regimen
needs to be edited.
Dosing regimen
For this new simulation, use doses of 75 mg at hour 0, hour 12, and hour 24.
To enter dosing information:
1. Select Model>Dosing Regimen from the menus.
2. Enter the new doses.
3. Click OK.
4. Choose Model>Start Modeling to re-run the simulation. The plot of the sim-
ulated data for the is shown here:
WinNonlin
Users Guide
460
17
Figure 17-3. The output plot from the revised simulation
461
Chapter 18
Using the Pharsight
Knowledgebase Server
Data access in a secure environment
The Pharsight Knowledgebase Server (PKS) is a database system for the stor-
age of pharmacokinetic and pharmacodynamic data. The PKS provides a
secure data management system with complete auditing capabilities. The
combination of the PKS and WinNonlin Enterprise provides an effective
means to share source data, models, and results among the members of a drug
development team. The combination also supports compliance with the U.S.
Food and Drug Administrationss 21 CFR Part 11 regulation.
This chapter covers the use of WinNonlin as a PKS client: loading PKS data
to WinNonlin and saving data from WinNonlin as PKS studies and scenarios.
The PKS can also be accessed by way of a web interface, which provides
means for additional operations, and an XML API. These functions and oper-
ations are covered in the Pharsight Knowledgebase Servers documentation.
See also Scripting the Pharsight Knowledgebase Server on page 512 and
Automating Pharsight Knowledgebase Server functions on page 545.
The PKS information structure
WinNonlin is an object (text, chart, model, data) based application. Those
objects fit into specific niches in the PKS data structure. PKS saves observa-
tions and related data as a PKS Study. Analysis settings and output are added
to the study as Scenarios. Non-WinNonlin documents, such as reports and
graphics that are related to the study, can be loaded into the PKS and associ-
ated with a scenario using the Other documents feature.
Study
The basic unit of information in the PKS is a study. A study starts with a col-
lection of raw data that must include longitudinal observations, observation
WinNonlin
Users Guide
462
18
times and subject identifiers, and may include dosing and subject demograph-
ics. As analyses are performed on these data, the analyses, including model
settings and results, can be added as Scenario(s) within the study.
A PKS study requires specific fields. First, a study must include at least one
column containing subject identifiers. A collection of fields taken together
can be used for subject identification (e.g., first name, last name).
A study may include (but is not required to have) multiple columns of subject
datatime-invariant, subject-specific information such as body weight or
gender, i.e., baseline covariates.
A study may include time-dependent observation and dosing data. Observa-
tion data may include records of concentration, measurements of blood pres-
sure, heart rate, etc. As the PKS manuals explain, each data collection point
can have multiple observations. In this case, a sampling variable is used to
differentiate the samples.
If the observation data include multiple, concurrent measurements for any
subject (e.g., multiple assays performed on a given sample or multiple sam-
ples during a given visit), the data set must include a variable that differenti-
ates the measurements (e.g., values 1, 2, 3 for the 1
st
, 2
nd
and 3
rd
samples).
Time fields
Because a study generally includes time-dependent observation data, a study
must include relative nominal time, indicating the times at which observations
(and doses, if included) were scheduled in the protocol. This is in contrast to
relative actual time, representing the times that observations or doses really
happened. (Relative time is time elapsed since the start of the study, period or
phase.) If the data uses infusion dosing, the relative nominal end time must be
identified as well. If only the Relative Nominal Time is defined in the data set,
a duplicate column will be created for the actual times.
Note: To create a study that does include longitudinal observation data, include a
dummy time column, with values for each row (as placeholders), in the study.
Study metadata
When a study is created, information about the study can be entered in the
Study Definition dialog (see below). This dialog includes information about
the study: Study Name, Portfolio, Project, Indication, Study Type, Study
Using the Pharsight Knowledgebase Server
PKS sessions
463
18
Design, Compound, etc. This metadata provides ways to search and filter the
data within the database. The metadata are saved with the study. See Creat-
ing a study or scenario on page 467 and Loading a study or scenario on
page 475.
Scenario
When WinNonlin analysis is performed on a PKS study, the combination of
data, model, and (optional) results data can then be saved in the PKS as a sce-
nario of the original study. A scenario can include a structural model, initial
parameters, and/or statistical tests to be applied to a particular data set for fit-
ting or analysis, as well as any derived output from those tests or analysis.
Scenarios are roughly comparable to the WinNonlin concept of a workspace
in that it is possible to save, in one place and under one name, related work
the data source, a model with model parameters, dosing, other model settings,
and the analytical output. Scenarios are naturally associated with (i.e., are
children of) a particular data set (study), although it is possible to create fur-
ther scenarios from the study (more children) or from an existing scenario
(grandchildren, etc.). See also Creating scenarios on page 477.
Other documents
The PKS can store documents that are not related to WinNonlin, such as study
reports, or a graphic created by saving a WinNonlin chart to a JPEG file.
These documents are associated with a specific study scenario. See Adding
non-WinNonlin documents to a scenario on page 479 for instructions.
PKS sessions
The Enterprise edition of WinNonlin has a concept of a PKS session. A PKS
session begins whenever WinNonlin retrieves and uses data from the PKS.
While the link between WinNonlin and the PKS is not constant, WinNonlin
knows the data came from the PKS and tracks all changes to the source data
so that if data are saved to PKS (whether to an existing study or scenario or to
a new one), the changes can be completely tracked and documented.
Accessing the PKS from WinNonlin
Access to the Pharsight Knowledgebase Server occurs via the PKS menu in
WinNonlin Enterprise. The menu items include:
WinNonlin
Users Guide
464
18
Note: A system administrator should set up and configure the PKS connection. See
the documentation set for the PKS for information.
Dosing
Dosing information can be, but need not be, saved as part of a PKS study.
Dose data can be added as part of study creation, using a separate worksheet
containing the dose data; appended after study creation; or entered as part of a
modeling scenario, using the WinNonlin Dosing dialog. If multiple scenarios
are included in a study, each may use different dose data. See Dosing infor-
mation on page 483 for details.
Table 18-1. PKS menu
Menu item Used when Function
Load Always Creates a PKS session and loads study/sce-
nario data
Save A PKS session is open
(study is loaded)
Saves changes to the study and creates a
new version of the current scenario, if any
Save As A PKS study and scenario
are loaded
Saves changes and creates a new scenario
under the specified name
Create
Study
No PKS session is open
and a workbook is loaded
in WinNonlin
Opens the mapping wizard, to set up a new
PKS study based on the current workbook
Append/
Update
Study
No PKS session is open
and a workbook is loaded
in WinNonlin
Opens the mapping wizard, so that new data
columns can be added to a PKS study
Dosing A PKS session is open
(study is loaded)
Sets dosing worksheet columns to be used
in the current model or analysis (scenario)
Other
documents
A PKS session is open
(study is loaded)
Saves a non-WinNonlin document or file to
the PKS, with the current scenario
Information A PKS session is open Displays the PKS study identifier and sce-
nario identifier, if one is loaded
Using the Pharsight Knowledgebase Server
Connecting to the PKS
465
18
Dosing workbook
It is possible to include dosing data when creating a study in the PKS. The
dosing information must appear in a different worksheet from that containing
the study observation data. That worksheet is selected as the dose source dur-
ing study creation, and its variables are assigned as part of mapping the study
variables (see Creating a study or scenario on page 467). It must contain, at
minimum, subject identifiers, dose amounts, and relative nominal dose times.
The columns representing subject identifiers and nominal time must be named
exactly as the corresponding columns are in the workbook containing the
observation data. The PKS will use those columns to match observation data
to dose data for given subject(s).
Dosing dialog
When a PKS study or scenario with no dosing data is loaded in WinNonlin,
and a model is selected, then dosing data can be entered via the WinNonlin
dosing dialog. This dosing information is transferred to the study Dosing
worksheet, inside the study data workbook, after the scenario is saved to the
PKS with model, model parameters and dosing information. Once the Dosing
information appears on the Dosing worksheet, the dosing information also
appears in the Dosing tab of the Model Properties dialog in WinNonlin, but it
is disabled (and colored blue). Thereafter, any changes to the dosing then
must be done on the Dosing worksheet rather than through the WinNonlin
dosing tab. The WinNonlin dosing dialog can still be used for simulations and
for user models.
Connecting to the PKS
Configuration
The PKS configuration must be set up before WinNonlin can contact the PKS.
The configuration settings are accessed from the PKS Logon dialog. This
information needs to be entered once only; WinNonlin will save it.
To configure the PKS connection:
1. Select any available item in the PKS menu to open the PKS Logon dialog. For
example, choose PKS>Load...
WinNonlin
Users Guide
466
18
2. Click the Configure button.
3. Enter a name describing the PKS database under PKS Alias. This will be used
to select a specific PKS database instance when logging in, as more than one
PKS database may be available on the local network. For example, many sites
have one production database and one example database, used to run exam-
ples from Pharsight Examples Guide.
4. Enter the PKS server machine name under Server. Similarly, enter the port
number under Port, and root directory for the PKS database under Root.
Note: The system administrator who set up the PKS database should provide the
values for the server, port and root.
5. Click OK.
Logging in
User name and password
Each time data are loaded to or from the PKS, the user must log in and pro-
vide a password. The log in user name and password are provided by the PKS
system administrator, who must set up an account for each individual user
before that user can access the PKS (see the PKS System Administrators
Guide for details).
Using the Pharsight Knowledgebase Server
Creating a study or scenario
467
18
Creating a study or scenario
Studies are the fundamental unit for the PKS. See Study on page 461.
Note: If a model is loaded, dose data are loaded directly from the model, and neednt
be specified by hand.
To create a study:
1. Load the desired observation data into a WinNonlin workbook window. If
dosing and/or demographics worksheets are to be loaded, open those work-
books as well. Note that dosing must be in a separate workbook, but demo-
graphic data can be loaded from the same workbook as the observations.
2. Choose PKS>Create Study from the WinNonlin menus.
If logging in for the first time, set up the PKS configuration. See Configura-
tion on page 465.
3. Enter the user name and password supplied by the system administrator. Note
that these are not necessarily the same user name and password used to log
onto the Windows operating system.
4. Select the desired PKS database under PKS Alias.
5. Click OK.
WinNonlin will contact the PKS and open the Study Definition dialog.
WinNonlin
Users Guide
468
18
6. Enter the following information.
Name: Study names must be unique in the PKS database. Since the con-
nection to the database is not persistent, the interface can only check a
study name that exists at the time any individual logs on to the PKS.
Start and End Time: enter the study start and end dates in one of the fol-
lowing formats:
Month day, year, for example: May 5, 2002
mm/dd/yyyy, for example: 05/05/2002
Description: any important information about the study.
Portfolio, Project, etc.: These attributes (study metadata) take values from
controlled lists created by the database administrator. They are useful in
searches of the database for studies on a given compound, indication, etc.
See your database administrator for local rules for setting study metadata.
7. Click OK.
The Study Creation Wizard appears.
Using the Pharsight Knowledgebase Server
Creating a study or scenario
469
18
8. Select the worksheet for the observation data under Observation Worksheet.
9. Select worksheets for dosing and demographics (optional). The dosing data
must be in a separate worksheet from the observation data. It must contain the
same subject identifiers, time fields, and indicators of period, phase,
sequence, etc. (data collection point identifiers), as the observations data set.
Note: The Save button saves all study creation settings, including file paths/names
and variable mappings, as an XML file with a *.PKS file extension. The Load
button reloads the settings from that file.
10. Click Next.
11. Drag the variable(s) that identify subjects to the PK Fields box. The identifier
can include one (e.g., subject ID) or more (e.g., first, last name) columns.
12. Use the Attributes button to set units for the subject ID variable(s), if needed.
WinNonlin
Users Guide
470
18
Note: If dosing and/or demographics worksheets are used, only columns that appear
in all worksheets, named identically, will appear in the Subject identifiers list.
13. Click Next to proceed to the Map Subject Data step.
14. Drag columns that contain subject demographics (baseline covariates) to the
PKS Fields box. These must have time-invariant, subject-specific values.
Note: Improper variable mappings can negatively impact the speed of operations in
the PKS. In particular, mapping subject-specific data as observations slows
performance, as observations include one record for every data collection
point in the study, rather than one record per subject. See Performance Tips
in the PKS System Administrators Guide. See also Optimizing PKS/WNL
performance on page 480.
15. To enter a different name for a column, to be used in the PKS study, select that
column under PKS Fields and click the Rename button. The name may
include up to 50 characters, and must follow WinNonlin column name limits.
16. If units already exist for a given column in the WinNonlin worksheet, those
units are loaded to the PKS.To view them, or to assign units to a column:
a. Select the variable under PKS Fields and click the Attributes button.
b. To load units for each record from a column in the data set, drag that col-
umn to the Unit field.
c. To set one unit for an entire column, check Static and enter or select the
unit under Unit. Time units must come from a fixed, controlled list. Other
Using the Pharsight Knowledgebase Server
Creating a study or scenario
471
18
units can be any string, although if the unit is not defined in the PKS, unit
conversions will not be available for it.
d. Click the Hide button to exit the Attributes dialog.
17. Click Next.
18. In the Map Time Data section, drag the variable containing scheduled times to
the Relative Nominal Time field.
19. Set other time variables (optional). Note that infusion dosing requires Relative
Actual End Time. See Time fields on page 462 for a discussion of the PKS
time variables. All time variables must exist in both the observations work-
sheet and the dosing worksheet, if included. The time fields must have identi-
cal names.
20. Set the time units: either choose a column containing the units for each record
under Time Unit, or check Static and enter the unit under Time Unit. See your
system administrator for a list of allowed units.
21. Click Next to proceed to the observation data mapping.
WinNonlin
Users Guide
472
18
22. Drag each column containing sample data to the PKS Fields box.
23. If the data include multiple, concurrent measurements for any given subject,
drag the variable that differentiates the measurements to the Sample Number
box. See Study on page 461 for further detail.
24. Select a variable under PKS Fields and click the Attributes button to edit the
information about that observation.
a. The following attributes can be associated with observation data. Each
can take one value for an entire column, or a unique value for each cell
(from a column in the data set).
Unit: units of measurement.
Status: indicates whether the data are (or a datum is) below a limit of
quantification (BQL), or missing for a specific reason, e.g., dropout
or non-adherence. Valid observation values are finite.
Using the Pharsight Knowledgebase Server
Creating a study or scenario
473
18
Analytical Methods: assay or technique used to obtain the sample
data.
Sample Description: further information about the sample.
LLOQ: lower limit of quantification for the assay. A number value.
ULOQ: upper limit of quantification for the assay. A number value.
b. If units already exist for a given column in the WinNonlin worksheet,
those units are loaded to the PKS.
c. To load unit (or another attributes) values, for each record from a column
in the data set, drag that column to the appropriate field.
d. To set one attribute value for an entire column, check Static and enter or
select the value in the appropriate list. Status values are defined in the
PKS using the web administrators tool.
e. Click the Hide button to exit the Attributes dialog.
25. Click Next to proceed.
26. If a dosing worksheet is used, the Map Dosing Data screen appears. Drag the
columns containing dose amounts to the PKS Fields box.
27. Select a dose variable under PKS Fields and click the Attributes button to set
units and other dose attributes, as needed. Check Static if one attribute value
applies to the whole column.
WinNonlin
Users Guide
474
18
Note: Additional information on data types, required fields, and attribute values can
be found in the PKS documentation set.
28. Click Next to continue to the Data Collection Point (DCP) screen.
29. Drag variables representing the study period (required for crossover designs
only), phase (optional) and treatment (e.g., placebo versus 10 mg BID) to
those boxes.
30. Use the DCP Description (Data Collection Point description) field for vari-
ables that distinguish different measurements stored a single observation col-
umn, for example, an indicator variable noting whether a given record
contains a measurement of plasma concentration or pain score.
Using the Pharsight Knowledgebase Server
Loading a study or scenario
475
18
31. Use the Preview button to review the variable mappings, and the Back button
to make any adjustments.
32. Click Finish when the variable mappings are complete.
33. The Study Creation dialog appears, providing an opportunity to document the
reason for creating the named study. The study name cannot be changed in
this dialog. If the study does not need to be reloaded from the PKS back to
WinNonlin for modeling or other further work, uncheck the Reload Study
check box.
34. When all necessary data has been entered, click Next to save the PKS study.
35. Once all data are successfully loaded to the PKS, a confirmation of the study
creation will display. Click OK.
Loading a study or scenario
To load a PKS study into WinNonlin:
1. Launch WinNonlin, if needed. Do not leave any windows open in WinNonlin;
the PKS will close them before loading any study.
2. Choose PKS>Load... from the WinNonlin menus.
If logging in for the first time, set up the PKS configuration. See Configura-
tion on page 465.
WinNonlin
Users Guide
476
18
3. Enter the user name and password supplied by the system administrator under
User Name and Password. Note that these are not necessarily the same user
name and password used to log onto the Windows operating system.
4. Select the desired PKS database under PKS Alias.
5. Click OK.
WinNonlin will contact the PKS and load a tree view of available studies and
scenarios. The list is determined by the user access rights assigned by the sys-
tem administrator.
Note: A red scenario icon indicates that at least one derived output object is out of
sync with its source. A green scenario icon means that the study data have
changed since the scenario last loaded the study data.
6. Un-check the Read Only check box if any alterations or additions are to be
made to the study or scenario (as opposed to creating a new scenario).
7. Use the Search button to search by study attributes. See Scenario search
below.
8. Use the Preferences button to organize the study tree by study name, indica-
tion, compound, and/or portfolio. In addition, the preferences select whether
Using the Pharsight Knowledgebase Server
Creating scenarios
477
18
all scenarios will be displayed (All), or only the most-recent (Latest), that
is, the final leaf on each scenario branch in the study tree.
9. Select the study or scenario to load, and click OK. Other options in this dialog
are discussed below.
To display only the tree view pane in the dialog, select the Hide Description
check box. The right pane is then hidden.
The Read Only option at the bottom right corner allows users with write-
access to load unlocked studies in a read-only mode. This improves perfor-
mance significantly. Read Only is the default selection, since study data
updates are not the principal function of WinNonlin. Users can create scenar-
ios and perform analyses with read-only studies.
Scenario search
The Search button available while Loading a study or scenario allows a search
of available studies by study name, scenario name, and/or value of study
metadata, including portfolio, compound, and indication.
Creating scenarios
Scenarios can be derived from an existing study or another scenario.
To create a new scenario based on a specific model or analysis:
1. Load the study on which the analysis will be based into WinNonlin.
2. Load the model or analysis, including any related settings. This can include
dosing for models, if the study does not already contain dose data.
WinNonlin
Users Guide
478
18
3. If analysis results will be saved in the scenario, run the model or analysis.
4. Once the analysis is complete, choose PKS>Save from the menus.
5. Enter a scenario name and reason for the study (scenario) update. Both are
required.
6. Enter a scenario description (optional).
7. Click OK to create the new scenario. It will be saved with the original study.
To create a new scenario without loading a model or analysis:
1. Choose PKS>Load from the WinNonlin menus, and log in to the system.
2. Select (but do not load) a study or scenario in the Load dialog.
3. Click the New button. The Scenario Field Selection dialog appears.
4. Select the fields from the data set to use in the new scenario. Those already in
the Selected Fields list are required and cannot be removed.
5. Click OK.
Using the Pharsight Knowledgebase Server
Adding non-WinNonlin documents to a scenario
479
18
Adding non-WinNonlin documents to a scenario
Non-WinNonlin documents can be saved to the PKS as part of a scenario.
Other documents may include data sets from other analysis programs, such as
SAS, Microsoft Word reports created with the PKS Reporter, or graphics cre-
ated from WinNonlin charts, among others. Any file on the computer can be
attached to a scenario. PKS can display JPG files in the Web Administrator
interface. The PKS Client for Word and the PKS Client for Excel can view
XL and Word documents. Other documents can be attached, but may not be
viewable until extracted from the PKS, saved to disk, and viewed in an appro-
priate software program.
To load or save a non-WinNonlin document:
1. Load the scenario. See Loading a study or scenario on page 475.
2. Choose PKS>Other Documents from the WinNonlin menus to open the
Document Manager.
3. Use the Add button to save a file to the PKS, attached to the current scenario.
4. Select a document in the list and click the Extract button to save it to a hard
drive or network location.
5. Select a document and click the Delete button to remove it from the scenario.
6. Click OK when finished.
7. To commit modifications of the document manager list to the scenario in the
PKS, choose PKS>Save in the menus.
WinNonlin
Users Guide
480
18
Optimizing PKS/WNL performance
A number of issues impact the performance of operations between WinNonlin
and the PKS.
Read-only access
When loading data, WinNonlin and the PKS must do a significant amount of
work to track any changes to the study data. If the study data are loaded as
read-onlyallowing the user to analyze them in WinNonlin but not change
data values in the source datathe loading can be done much more quickly.
Note: The read-only check box on the PKS Load dialog applies to the study data and
not the scenario. All scenarios are, by their very nature, read-only. Only new
versions of scenarios can be created. Users must have system level rights and
right to the original study in order to create a new scenario.
Appropriate field mappings
Study data fields must be mapped to an appropriate data type when initially
loaded from the WinNonlin client into the PKS. The basic data types are (1)
Subject identifier, (2) Subject data, (3) Time (actual, nominal, and combina-
tions), or (4) Observation. Some data types (such as subject identifiers and
subject data) are constant across time, while others (observation data) vary.
When studies are loaded, the observation data are checked for any changes.
Thus, the more that data are mapped as observation data, the more they must
be checked when loaded and the slower the loading is.
Subject identifiers (up to five fields) uniquely identify a subject. While they
can be changed (corrected), they are not normally modified in the course of a
study and its analysis. Changes are captured in an audit.
Subject data (unlimited number of fields) are data related to a subject that
does not change over time. This data may also be called baseline covariates or
demographics.
Time data identify the nominal and actual time points for the observed data.
Nominal times are the dose and observation times designated in the study pro-
tocol. Actual time differs from nominal time when subject adherence to the
protocol schedule is imperfect.
Observation data (unlimited) include sample or dose data that change over
time for a given subject.
Using the Pharsight Knowledgebase Server
Optimizing PKS/WNL performance
481
18
In creating a study or scenario and loading/reloading, WinNonlin and the PKS
track any changes to the data. Make sure data that varies over time are
mapped as observation data while demographic data are mapped as subject
data. If baseline covariates are mapped as observations rather than subject
data, the loading/reloading process becomes much slower because those data
cells must be checked for changes.
Note: Mapping fields in the creation of a study is particularly important. Selecting
the correct data types can ensure performance is optimized. It is not possible
to change the data types in a study once it has been created.
Creation of a base scenario for a study
Loading a scenario is faster than loading a study. Therefore, to save time on
subsequent operations, create a base scenario that contains all the columns
that will be used for a set of scenarios on a study. All subsequent scenarios
should be derived from this base scenario. This allows WinNonlin to load the
study data in a more condensed format if read-only study data access is
selected.
Example:
1. Load the study from the PKS into WinNonlin. See Loading a study or
scenario on page 475.
2. Once the study is loaded, create a text object describing the base scenario
(File>New then Text).
3. Name the Text object by right clicking on it, and selecting Object
Name. Highlight the Text object in the list box and press F2. Give the
object a name (i.e., Scenario Description). Click OK.
4. Save the base scenario via PKS>Save.
5. An Update Reason dialog is displayed. Enter a scenario name for the base
scenario (i.e., Base Scenario). Enter a reason (i.e., Base Sce-
nario). Click Save.
6. The logon dialog appears. Enter the password and click OK.
7. File>Close All (it may take some time to close all since a bit of memory
is being freed up).
WinNonlin
Users Guide
482
18
8. Now all work can be done by loading the base scenario with read-only
access to the study; this will be much faster than loading the source study.
Modeling and other analysis can be done and saved as new scenarios
using PKS>Save As.
Note: Make sure that all dosing data are loaded into the study. Dosing data are con-
sidered part of the study and cannot be added after studies are loaded in read-
only mode.
Change tracking and audit information
If any changes are made to source data loaded from a PKS study or scenario,
and the new data are saved back to the PKS, the PKS will display an Audit
Information dialog and an Update Reason dialog so that all changes to data
can be documented completely. A change reason must be entered for every
changed value.
See your system administrator to inquire about standard change reason mes-
sages in your organization. Once a reason for the change has been provided,
the PKS also requires a reason for updating the scenario.
The reason for the change is required. This data are captured and preserved
with the scenario data. It is available via the PKS web clients audit trail.
Using the Pharsight Knowledgebase Server
Dosing information
483
18
The Update Reason dialog also has Objects and Format buttons. Clicking the
Objects button opens the PKS Save All dialog, to set which objects loaded in
WinNonlin are to be saved.
Clicking on the Format button opens the PKS Save Native Format dialog,
which allows provides a means to save the worksheets as binary data or
ASCII data that can be read by other applications.
Dosing information
Dose data are added to PKS studies either through a separate dose worksheet
at study creation, or as part of a modeling scenario (via the WinNonlin Dosing
Regimen dialog, after loading the model). See Dosing on page 464 for dis-
cussion.
WinNonlin
Users Guide
484
18
When a study or scenario is loaded from the PKS into WinNonlin, the work-
book loaded has three worksheets: one of observation data (Observations),
one containing dosing data (Dosing), and one that records the data history
(History).
Only data loaded via the PKS will appear in the Dosing worksheet. If the
study has no dosing data, once a model has been selected in WinNonlin the
dosing data can be added via the WinNonlin dosing dialog. This dosing infor-
mation will appear in the Dosing worksheet after the scenario is saved to the
PKS with (model, model parameters and) dosing information. At that time,
the dosing data are associated with the study.
Once the Dosing information appears on the Dosing worksheet, the WinNon-
lin dosing dialog is disabled (and shaded blue), and changes to the dosing
must be made on the Dosing worksheet rather than through the Dosing dialog.
The WinNonlin dosing dialog must still be used to specify the dosing data for
simulations, and for user models. Dosing entered for a simulation, and subse-
quently saved to a scenario, resides with the scenario information, and does
not become the study dosing data.
Changing the dose regimen
When the dosing data exists on the Dosing worksheet, it is possible to indicate
which fields from the study or scenario to apply to the current scenario. Thus
different dosing schedules can be set up within a study or scenario simply by
including different data columns [Dose_A, Dose_B, etc.] for each regimen.
To choose a different dose regimen:
1. Load a study or scenario containing multiple dose regimens, each using a sep-
arate set of dosing data columns (i.e., for time and amount).
1. Select PKS>Dosing. The Dosing Field Selection dialog appears.
2. Drag the dosing fields for the regimen to be used in the current analysis to the
Dosing Columns box. Variables listed in the Non-Dosing Columns box will
not be used in the current scenario.
3. Click OK.
Using the Pharsight Knowledgebase Server
Appending or updating a study
485
18
Appending or updating a study
After a study is created in the PKS, additional data can be added to the study,
or existing data can be updated, from a workbook.
Note: Append/Update is a convenient way to add dosing information to the study or
scenario. This method can also be used to add subject data to the study.
To append/update a study:
1. Close any PKS study or scenario that is open in WinNonlin.
2. Open the data to be added in a WinNonlin workbook window.
3. Choose PKS>Append/Update Study... from the menus.
4. Log in. (See Logging in on page 466 for details.)
5. In the Pharsight Knowledgebase Server Load dialog, select the study to which
to append data, or in which to update data.
6. Click OK. The Study Creation Wizard appears, to map the variables in the
data set to the selected study.
7. Drag variables from the workbook and drop them on or under the correspond-
ing study variables. The column(s) containing the subject identifiers must be
identified. If there are new data variables, such as extra subject data or other
observations, add them beneath the existing study variables.
8. Click OK.
Note: The PKS documentation set covers a number of other operations that affect
studies and scenarios in the PKS. For example, it is possible to specify or con-
vert units in the PKS without loading the data in WinNonlin. It is also possible
to load data into WinNonlin then specify units or convert unitsthen save
them back to the PKS. Whenever there are significant differences between the
actions in WinNonlin and those in PKS, the documentation systems point
them out.
WinNonlin
Users Guide
486
18
WinNonlin and PKS differences
WinNonlin and the Pharsight Knowledgebase Server have been tightly inte-
grated. And yet, because they are also designed to work with other tools as
well, there are some differences which are important to note.
Units
Units are handled in both WinNonlin and PKS. Indeed, for some fields in
the PKS units are required. While they are useful in WinNonlin, they are
never required.
New units can be added and defined in the PKS. New units cannot be
added in WinNonlin. (A unit that WinNonlin does not recognize can be
entered; in this case WinNonlin marks it with surrounding braces {}, but
WinNonlin also wont attempt to utilize the units in calculations.)
Unit conversions can be done in both WinNonlin and the PKS. Conver-
sion factors for units must be entered in the PKS, whereas units are under-
stood naturally by WinNonlin. PKS comes with all of WinNonlin units
available.
Units are combined into categories in the PKS: mass, time, and volume.
There is not a directly analogous concept in WinNonlin except in the
Units Builder.
Units can be handled at the cellular level in the PKS. That is, each row of
a particular column can have different units (and the units would be stored
in an adjacent column). WinNonlin cannot handle units at the cellular
level. Units in WinNonlin are associated with an entire column. Thus
there are situations when valid data from a PKS data set cannot load cor-
rectly in WinNonlin until the differences in units has been resolved. The
PKS provides the means to convert the units in a column (which may
have mixed units) to one unit. This format then is valid in WinNonlin.
Data sets with time-dependent data in WinNonlin have no specific
requirements. To use them with the PKS, however, all time-dependent
data (Relative Actual Time, Relative Nominal Time, etc.) must have the
same time unit.
Using the Pharsight Knowledgebase Server
WinNonlin and PKS differences
487
18
Studies and scenarios
The fundamental unit for the PKS is the study. Scenarios are used to store
and rerun PK and NCA analyses, including models, model parameters,
dosing, etc. Scenarios are roughly analogous to workspaces in WinNonlin
(in that they could include a data set, a model, and some derived data
charts, worksheets, a model, tables, etc.).
Saving scenarios to PKS is analogous to saving a workspace in WinNon-
lin, except that workspaces require all child windows to have filenames
prior to being saved. PKS requires the child windows to have object
names.
Time and subject data must be present to save and import data from Win-
Nonlin to the PKS. If data does not have this, a dummy column can be
created so that the data set shows it.
The PKS can handle multiple drugs within one study. WinNonlin can han-
dle only one drug at a time in a scenario.
WinNonlin
Users Guide
488
18
489
Chapter 19
Scripting
Automating analyses through WinNonlins object-
oriented scripting language
The WinNonlin scripting language is an object-based programming language
that allows users to automate tasks and analyses. Using the scripting lan-
guage, users can devise script files, which are in essence computer programs,
to customize WinNonlin to their needs and run a number of WinNonlin opera-
tions in batch mode.
This section includes:
Terminology on page 489: object-based programming terminology
Writing and editing a script on page 490
Executing a script on page 492
Scripting object properties and methods on page 493: a quick reference
guide to the scripting properties and methods for each WinNonlin object
and engine
Script file components on page 498
Processing multiple profiles in script files on page 501
Scripting the Pharsight Knowledgebase Server on page 512
Examples of individual scripting operations on page 520
See Scripting Commands on page 645 for details on each scripting method
and property. See the Examples Guide for complete example scripts.
Terminology
Object-oriented programming terms used in WinNonlin scripting follow.
WinNonlin
Users Guide
490
19
Writing and editing a script
This section discusses the steps in writing and editing a script. Script files are
ASCII text files. They have the default extension of .PSC.
Note: Scripts written with earlier versions of WinNonlin have the extension .WSC.
They can be opened in this version of WinNonlin, but cannot be saved back to
this file type. New script files use the .PSC file type.
Older script files will run but may require minor modifications to file types.
For example, output must be saved to an appropriate file typea .PWO for a
workbook rather than a .WDO.
Table 19-1. Scripting terminology
Objects
Object-oriented programming languages deal with objects. In WinNonlin, each type of child
window that appears in the main WinNonlin parent window is an object. There are five types
of objects in WinNonlin: Data objects, Text objects, Model objects, Graph objects, and Win-
Nonlin itself.
Engines
Engines, like modules, execute tasks in WinNonlin. The ten WinNonlin engines are: PK,
DESC, LINMIX,BIOEQ, ANOVA
a
, PLOT, TABLE, TRANSFORM, MERGE,TOOL-
BOX.
Method
A method is a set of computer code that performs functionality on a specific object or engine.
In short, it invokes an action. For example, the Method LOAD causes an associated data file
(an Object) to be loaded. The Method RUN causes an associated PK Model (Engine) to run
the model.
Property
Every object has properties that define how the object should appear and interact. Properties
also set values for objects or engines. In short, properties are attributes or characteristics of
an object.
For example, a property of an output data object could contain a file name to identify that
object. Another property could be the file type to be used when loading the object. A third
property would define whether or not the named data file contains data headers (column
names) as the first row.
Script File
A WinNonlin script file is an ASCII file that contains WinNonlin scripting code. Within a script,
there could be many Objects of each type and several Engines. Only one Engine may be in
use at any one time.
a. ANOVA is available for backward compatibility with older versions of WinNonlin. LinMix
or Bioequivalence Wizards provide newer and more powerful options than ANOVA.
Scripting
Writing and editing a script
491
19
To write a script:
1. From the File menu, select New (Alt+F, N). The New dialog appears.
2. Select the radio button for Text.
3. Click OK. A text window appears.
4. Type the content of the script.
5. When the script is complete, select Save As from the File menu (Alt+F, A).
The File Save dialog box appears.
6. Select the appropriate drive and directory.
7. Select Script Files (*.PSC) from the pull-down menu in the Save as
type box.
8. In the File name box, type the desired file name, using the file extension .PSC.
9. Click Save.
Comments may be added to the Script file by adding lines to the script that
begin with REMA, or REMARK.
Case does not matter for any of the Properties or Methods.
To edit a script:
1. Select Open from the File menu (Alt+F, O).
or
Click the Open button on the tool bar. The File Open dialog appears.
2. Select the appropriate drive and directory if necessary.
3. Select Script Files (*.PSC) in the List Files of Type box. All script
files in the selected directory will be listed.
4. Double click on the name of the script file to be edited. The script file will
appear in a text window.
5. In the text window, click the text line where changes are needed, then type in
the changes.
6. When done, click Save.
WinNonlin
Users Guide
492
19
Executing a script
Once a script is created, the following steps are used to run it. Script files may
be executed either from within WinNonlin or from a Windows command line.
When running a script from within WinNonlin, no WinNonlin windows may
be open. When executing from the Windows command line, WinNonlin must
be closed.
Within WinNonlin
To execute a script while in WinNonlin:
1. Close all WinNonlin windows, including the text window containing the
script.
2. From the File menu, select Run Script (Alt+F, R). The Run Script dialog
appears.
Figure 19-1. The Run Script dialog.
3. Select the appropriate drive and directory.
4. Double click on the script file name.
or
Click on the script file name and click Open. The script file executes and the
output appears in a WinNonlin output window.
Scripting
Scripting object properties and methods
493
19
From the command line
To execute a script from the command line in Windows NT or Windows 98/2000:
1. Exit WinNonlin if it is already running.
2. Click the Windows Start button.
3. Select Run. A Windows dialog box will appear.
4. In the Open box, type WINNONLN, or WINNONLN.EXE along with the appro-
priate path, followed by the script file name, again including the full file path.
For example:
C:\WINNONLN\WINNONLN C:\WINNONLN\EXAMPLES\EXMPL_1.PSC
5. Click OK.
Note: When a script file cannot be successfully executed because of an error or
errors in the file, a log file is created. A text window will appear showing the
contents of that log file. If no errors occur during a script file execution, a log
file will not be created. The Pharsight application log will contain appropriate
entries for actions taken during the script file execution (exclusions, etc.).
From file manager or explorer
To execute scripts from Windows File Manager or from Explorer:
Script files can be run simply by double clicking on their names in Windows
Explorer (Windows 98/2000 or Windows NT).
To do so, the file extension .PSC must be associated with WINNONLN.EXE.
Scripting object properties and methods
This section lists all properties and methods that are applicable to each Win-
Nonlin object and engine. Refer to this Quick Reference Guide to see which
properties and methods are used for each operation. Detail on each command
is provided under Scripting Commands on page 645. See also Examples of
individual scripting operations on page 520.
WinNonlin
Users Guide
494
19
Objects
There are five WinNonlin objects. A quick reference table of applicable prop-
erties and methods is given below for each Object.
Table 19-2. WinNonlin object properties and methods
Arrange Load Save
Cascade MsgBox TileHorizontal
CloseAll PrintAll TileVertical
DeleteFiles PrintData Unload
ExportAll PrintGraph WorkingDir
FileMask PrintModel WindowState
Halt PrintText
Table 19-3. Data object properties and methods
Append FileType RenameCol
AppendFilename Find Replace
AppendFileType Font Save
AppendSheet FontSize SearchArea
AutoFileOptions Headers Sort
CaseSensitive Include SortVar( )
Column Load SortVars
ConseqDelim Missing StartCol
Copy MultiGrid StartRow
Cut Operation Tab
Delimiter Paste Tolerance
EndCol Print Unload
EndRow Remove Unit
Exclude RemoveCol WindowState
Filename RemoveRow With
Scripting
Scripting object properties and methods
495
19
Engines
There are ten WinNonlin engines. A quick reference of the applicable proper-
ties and methods is given below for each Engine.
Table 19-4. Text object properties and methods
Filename Print WindowState
FileType Save
Load Unload
Table 19-5. Model object properties and methods
DoseUnit LinkFile Print
Filename Load Save
FileType ParmFile Unload
LamzFile PartFile WindowState
Table 19-6. Graph object properties and methods
Filename MultiGraph Unload
FileType Print WindowState
FootnoteFont PrintMulti XLabelsFont
FootnoteFontSize