Wnl Users Guide

WinNonlin®

User’s Guide

Version 4.1

Pharsight Corporation800 West El Camino Real, Suite 200, Mountain View, California 94040

Voice +1-650-314-3800 • Fax +1-650-314-3810http://www.pharsight.com • [email protected]

WinNonlin® Version 4.1WinNonlin 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 StatementAll 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 RightsThe 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1WinNonlin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

WinNonlin editions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1WinNonlin user documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Modeling and nonlinear regression. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Model fitting algorithms and features of WinNonlin . . . . . . . . . . . . . . . . 5Summary of regression methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Pharsight Corporation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Scientific and consulting services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Training . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Pharsight contact information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Chapter 2 Data Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13WinNonlin windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Workbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Text windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Chart windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Hidden windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Data files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19File types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Pharsight object files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20File type limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21WinNonlin and WinNonMix file compatibility . . . . . . . . . . . . . . . . . . . 22

Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Print all . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

WinNonlinUser’s Guide

iv

Page setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27WinNonlin options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Workbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Dependencies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Saving dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Refreshing results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Unlocking derived data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Data history worksheets and log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40History worksheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40WinNonlin Log Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Data export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Microsoft Word export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44SAS Transport file export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47NONMEM export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Chapter 3 ODBC Data Sharing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53ODBC import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Import settings file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Connecting to the data source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Loading a saved connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Building a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Loading a saved query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Loading an import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Refreshing a data set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Importing data with the custom query builder . . . . . . . . . . . . . . . . . . . . 64

ODBC export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Export settings file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Defining an export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Loading a saved export definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Loading an export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

The Enterprise Software Development Kit . . . . . . . . . . . . . . . . . . . . . . . . . . 75Import file format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Export file format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Custom query builder interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77VB example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Contents

v

Chapter 4 Worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85Editing data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Using formulas and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Filling adjacent cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Clearing cell values and formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Inserting and deleting rows, columns or cells . . . . . . . . . . . . . . . . . . . . 90Inserting or deleting worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Find, find next and replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Undo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Go to . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Formatting cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Setting column names and units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Data manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Freezing rows and columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Sorting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Merge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Data exclusion and inclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Status code transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Rule sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Chapter 5 Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119Units display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Units options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Unit types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Dosing units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Dose normalization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Preferred units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Worksheet units. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Entering units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Clearing units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Converting units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Chapter 6 Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129Chart Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

X-Y variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Sort and group variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Error bars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Chart titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136


vi

Axis options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Chart Designer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Starting the chart designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Selecting the plot type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Specifying chart backdrops. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Selecting a location for the plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Formatting the walls of a plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146Formatting a series on the plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147Formatting series data point labels and axis labels . . . . . . . . . . . . . . . . 157Formatting an axis. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164Formatting axis titles, footnotes, legends, and chart titles . . . . . . . . . . 171

Frequently used graph formatting options. . . . . . . . . . . . . . . . . . . . . . . . . . 178Changing line style and markers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Changing the axis scaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180Creating a semi-log plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180Removing grid lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Removing walls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Chart templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182Preview and page setup for charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182Copy and paste. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Save options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Chapter 7 Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187Table Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Missing table values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188Table templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Templates 1-3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Templates 4-8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Template 9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

Table template variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192ID variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192Group variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192Variables (or regular variables). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Cross, or X-Cross variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Aggregate variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194Mapping variables to the template . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Joining data sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195Summary statistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

Significant digits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Contents

vii

Table formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200Reformatting data sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202Data-only tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Table export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203Exporting to Microsoft Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203Exporting to Microsoft Excel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

Table definition files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204Creating a table definition file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Loading a table definition file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Chapter 8 Descriptive Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .207Computing summary statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

Output and computational formulae. . . . . . . . . . . . . . . . . . . . . . . . . . . 208Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Weighted summary statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212Output and computational formulae. . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Chapter 9 Noncompartmental Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . .215NCA model selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216Model variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217Lambda z estimation settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

Lambda z range selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Calculation of Lambda z . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219Setting Lambda z ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

Partial areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221Therapeutic response window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222Dosing regimen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223Rules for handling of steady-state data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225Model options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

Output options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226Weight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230NCA settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232Parameter names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233


viii

Computational rules for WinNonlin’s noncompartmental analysis engine. 234Data checking and pre-treatment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234AUC calculation and interpolation formulas . . . . . . . . . . . . . . . . . . . . 235Partial areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236Computational details for pharmacokinetic parameters . . . . . . . . . . . . 240

Chapter 10 Compartmental Modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .247Loading the model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247Model properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

Data variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250Model parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250Dosing regimen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

Model options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257Output options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258Weight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261PK settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

Running the model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265Stop modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265Text (ASCII) output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266Workbook output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269Chart output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Chapter 11 User Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273Templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273Model structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274Model components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

Transform block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276Command block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277Temporary variables block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280Function block. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281Starting values block. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282Differential equation block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283Secondary parameters block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

WinNonlin variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284Variable names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285PNAMES, SNAMES, and DNAMES. . . . . . . . . . . . . . . . . . . . . . . . . . 286

Contents

ix

The WinNonlin programming language . . . . . . . . . . . . . . . . . . . . . . . . . . . 286WinNonlin statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286WinNonlin comparison operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289Bioassay functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

ASCII models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290User libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291Example 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291Example 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294Example 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296Creating a new ASCII model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298Loading an existing ASCII user model . . . . . . . . . . . . . . . . . . . . . . . . 300

Compiled user models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301Using FORTRAN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301Example using Compaq Visual FORTRAN 6.0. . . . . . . . . . . . . . . . . . 302Using C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305Example using Microsoft Visual C++ 6.0 . . . . . . . . . . . . . . . . . . . . . . 305Using compiled user models in a command file . . . . . . . . . . . . . . . . . 307

Chapter 12 Command Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .309Command file structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

Model definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

WinNonlin commands: basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310Model definition commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

Loading ASCII models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312Model initialization commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312Weighting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314Model parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316Dosing regimen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317Model options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

Data commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320Execution control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

Chapter 13 Weighting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .325Weighted least squares . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325Iterative reweighting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326


x

Reading weights from the data file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326Scaling of weights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326Weights in ASCII models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

Chapter 14 The WinNonlin Toolbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .329Nonparametric superposition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Data and assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330Computation method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330Performing nonparametric superposition . . . . . . . . . . . . . . . . . . . . . . . 332Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

Semicompartmental modeling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335Data and assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336Computation method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336Performing semicompartmental modeling . . . . . . . . . . . . . . . . . . . . . . 337Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

Crossover design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342Data and assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342Descriptive analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343Hypothesis testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344Using the Crossover Design tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

Deconvolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348Deconvolution methodology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348Convolution methodology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353Using deconvolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356Deconvolution output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

Chapter 15 Linear Mixed Effects Modeling . . . . . . . . . . . . . . . . . . . . . . . . . .363An example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363The linear mixed effects model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366

Construction of the X matrix. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368Linear combinations of elements of β. . . . . . . . . . . . . . . . . . . . . . . . . . 371Determining estimability numerically . . . . . . . . . . . . . . . . . . . . . . . . . 373Substitution of estimable functions for non-estimable functions . . . . . 373

Fixed effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375Output parameterization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375

Contents

xi

Variance structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378Repeated effect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378Random effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380

Least squares means . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383Contrasts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

Joint versus single contrasts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387Nonestimability of contrasts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388Degrees of freedom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388Other options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389

Estimates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389LinMix Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389

LinMix limits and constraints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390Fixed effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391Variance structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393Contrasts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397Estimates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398Least squares means . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399LinMix general options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400

LinMix output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401Linear mixed effects text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401Linear mixed effects workbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402Tests of hypotheses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403Akaike’s Information Criterion (AIC) . . . . . . . . . . . . . . . . . . . . . . . . . 404Schwarz’s Bayesian Criterion (SBC) . . . . . . . . . . . . . . . . . . . . . . . . . . 404Hessian eigenvalues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405Predicted values and residuals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405Fixed effects parameter estimates . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405Coefficients. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406Iteration history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406Parameter key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

Computational details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407Restricted maximum likelihood . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407Newton’s Algorithm for maximization of restricted likelihood. . . . . . 408Starting values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409Convergence criterion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410Satterthwaite’s approximation for degrees of freedom . . . . . . . . . . . . 411

Comparing LinMix to ANOVA and SAS’s PROC MIXED . . . . . . . . . . . 413


xii

Chapter 16 Bioequivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .417Introduction to bioequivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417

Basic terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417Bioequivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418

The model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420Linear model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420Variance structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420

Average bioequivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420Study designs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420Recommended models for average bioequivalence . . . . . . . . . . . . . . . 421Least squares means . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423Classical and Westlake confidence intervals . . . . . . . . . . . . . . . . . . . . 424Two one-sided T-tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426Anderson-Hauck test. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428Power . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428

Individual and population bioequivalence. . . . . . . . . . . . . . . . . . . . . . . . . . 430Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430Bioequivalence criterion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430Details of computations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432

Bioequivalence Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437Using average bioequivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438Using population/individual bioequivalence . . . . . . . . . . . . . . . . . . . . 444

Bioequivalence command files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445Bioequivalence output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446

Average bioequivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446Population/Individual bioequivalence. . . . . . . . . . . . . . . . . . . . . . . . . . 447Ratio tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449

Missing data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450

Chapter 17 Simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .451Simulating responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451Simulation of a compiled library model . . . . . . . . . . . . . . . . . . . . . . . . . . . 451

Creating the input data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452Setting up the model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453Data variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454Model parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455Dosing regimen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456Model options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457Running the simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458

Comparing dosing schemes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459Dosing regimen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459

Contents

xiii

Chapter 18 Using the Pharsight Knowledgebase Server . . . . . . . . . . . . . . .461The PKS information structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461

Study. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463Other documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463

PKS sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463Accessing the PKS from WinNonlin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463Dosing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464

Dosing workbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465Dosing dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

Connecting to the PKS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465Logging in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466

Creating a study or scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467Loading a study or scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475Creating scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477Adding non-WinNonlin documents to a scenario. . . . . . . . . . . . . . . . . . . . 479Optimizing PKS/WNL performance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480Change tracking and audit information. . . . . . . . . . . . . . . . . . . . . . . . . . . . 482Dosing information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483

Changing the dose regimen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484Appending or updating a study . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485WinNonlin and PKS differences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486

Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486Studies and scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487

Chapter 19 Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .489Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489Writing and editing a script. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490Executing a script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492

Within WinNonlin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492From the command line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493From file manager or explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493

Scripting object properties and methods. . . . . . . . . . . . . . . . . . . . . . . . . . . 493Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494Engines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495

Script file components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498Note on saving files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500

Processing multiple profiles in script files . . . . . . . . . . . . . . . . . . . . . . . . . 501Special file formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502


xiv

Scripting the Pharsight Knowledgebase Server. . . . . . . . . . . . . . . . . . . . . . 512Example PKS scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516

Examples of individual scripting operations . . . . . . . . . . . . . . . . . . . . . . . . 520Data manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521Plots. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526Data transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529Descriptive statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533Modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533WinNonlin Model Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534ANOVA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537Word export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537

Chapter 20 Scripting WinNonlin Using Visual Basic . . . . . . . . . . . . . . . . . . .539Summary of properties and methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539Automating Pharsight Knowledgebase Server functions . . . . . . . . . . . . . . 545Visual Basic scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546

Creating a script using Microsoft Word 2000. . . . . . . . . . . . . . . . . . . . 546Running a script using Microsoft Word 2000. . . . . . . . . . . . . . . . . . . . 548

Appendix A Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .549

Appendix B WinNonlin Model Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .573Notation and conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574Pharmacokinetic models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575

ASCII models and files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576PK models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577

Pharmacodynamic models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596ASCII library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596Models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597

PK/PD link models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602Notation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602Linking PK and PD models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602Output parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604

Indirect response models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605Models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606Running an indirect response model. . . . . . . . . . . . . . . . . . . . . . . . . . . 608

Michaelis-Menten models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609

Contents

xv

Simultaneous PK/PD link models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612ASCII 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 . . . . . . . . . . . . . . . . . . . . . . . . . .707Compartmental modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707

Troubleshooting modeling problems . . . . . . . . . . . . . . . . . . . . . . . . . . 718LinMix and Bioequivalence wizards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719Table Wizard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721Descriptive statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721Noncompartmental analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722

Error messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722Warnings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722

Scripting language. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723

Appendix G Visual Basic Automation Reference . . . . . . . . . . . . . . . . . . . . . .725Chart module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725Charts module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734Crossover module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734Deconvolution module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736DescStats module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740LinMix module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743Merge module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 744Model module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746PK module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749Plot module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751PrintExportAll module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755Rule module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759Semicompartmental module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760StatusCodes module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762Superposition module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763Table module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 769


xvi

TextEditor module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771TextEditors module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778Variable module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778Variables module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780Wnl4 module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783Workbook module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 784Workbooks module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802Workspace module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803

Appendix H References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .813Deconvolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813Pharmacokinetics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 814Regression and modeling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 815Statistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817Bioequivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 818

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 819

1

Chapter 1

Introduction

WinNonlin editions, user documentation, and Pharsight contact information

WinNonlinWinNonlin 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 Administration’s (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


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 regressionThe 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 data—that 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 DescriptionGetting 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.

User’s 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 WinNonlin’s computational engines.

Release notes

...\WinNonlin\User Docs Known issues and work-arounds in the current version of WinNonlin.

IntroductionModeling 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: WinNonlin’s 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

ε++= BXAY

ε++++= 34

2321 XAXAXAAY

ε++++= 3423121 XAXAXAAY

( )BXYY −= exp0

CKCVV

m += max

( ) ( )XBAXBAY 2211 expexp −+−=


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


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-


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.


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


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 WinNonlin’s 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-

IntroductionPharsight 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 CorporationPharsight 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.

http://www.pharsight.com

http://www.pharsight.com


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 Pharsight’s 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: [email protected]

Mail: Pharsight Corporation5520 Dillard Road, Suite 210Cary, 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:


Telephone: 1-888-708-7444 (from US only)

Fax: +1-650-314-3811

mailto:[email protected]


http://www.pharsight.com/training/

IntroductionPharsight Corporation

11

1

Assistance with Pharsight software licensing is available by telephone and e-mail:

Telephone: 01-919-852-4620.


Customer feedback

Please submit requests for product enhancements and defect corrections by e-mail, fax, or through Pharsight’s customer support web site, as follows.

e-mail: [email protected]

Web: http://support.pharsight.com

Fax: 01-919-859-6871



http://support.pharsight.com


12

1

13

Chapter 2

Data Management

Data files, import, export, and formatting

WinNonlin windowsWinNonlin 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.


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 WinNonlin’s native format for tabu-lar data. In addition, WinNonlin can read (import) data from other file types:

Data ManagementWinNonlin 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.


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 ManagementWinNonlin 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.


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 ManagementData 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/exportTabular data (Workbooks)

Subject dataModeling outputDosing dataModel 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)


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 WinNonlin’s 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 modelsScripts

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 ManagementData 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


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:DataText

GraphModel

*.wdo*.wto*.wgo*.wmo

IdenticalIdenticalIdentical

Not available

*.wdo*.wto*.wgo

Pharsight files:DataText

ChartModel

*.pwo*.pto*.pco*.pmo

IdenticalIdenticalIdentical

Not compatible

*.pwo*.pto*.pco*.pmo

SAS Transport files

*.xpt, *.stx Not compatible Not available

ANOVA com-mand filesa

*.anv Identical *.anv

LinMix com-mand files

*.lml Not compatible Not available

Bioequivalence command files

*.lml Not compatible Not available

Model object filesb

*.pmo Not compatible *.pmo

Data ManagementWorkspaces

23

2

WorkspacesA 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


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 ManagementPrinting

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.

PrintingCustomize 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.


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.


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


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.


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.


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.


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).


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 ManagementWinNonlin options

33

2

WinNonlin optionsWinNonlin 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 OptionsDirectories • default directory for WinNonlin Library and User Library filesWorkbooks • 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 analysesTables • treatment of group variables in the table generator

• default use of page breaks in tablesUnits • display of units with column headers in worksheets, chart labels and

tables


34

2

Workbooks

To set or change workbook options:


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.


Models

To set model options:


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 ManagementWinNonlin 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.


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.


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.


Units

To specify units options:


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.


Data ManagementDependencies

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.

DependenciesWhen 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


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 ManagementDependencies

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.


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 filesWinNonlin provides multiple means of tracking the data operations in Win-Nonlin. Each workbook loaded in WinNonlin includes a data history work-sheet. Almost all operationsA 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 ManagementData 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 loggedPK 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


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 ManagementData 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


44

2

Data exportA 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.

WinNonlin’s 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 WinNonlin’s 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 ManagementData 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.


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.


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:


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 EVIDIn 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 = 2Thus, 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 Description1 ID Always provided. Subject identifier.2 TIME Usually required. Nominal or actual time.3 independent

variablesOptional. 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 variable’s values. The name DV is a fixed name for NONMEM.


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 DV1: 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 event2: An other-type event3: A reset event4: A reset-and-dose event

Position Column name Presence Description


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 file’s location or use the Browse button to locate it.

Tab name DescriptionFiles Export file path and name, header information, comment identifierDependent Variables Dependent variables and dependent variable ID columnOther Data Items Independent variablesDose 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


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


52

2

NONMEM NM–TRAN 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 importUse 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.


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 SharingODBC 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 (DSN’s) 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.


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.


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


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.


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.


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.


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.


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.


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.


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.


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.


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-


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.


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 SharingODBC 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 exportWinNonlin Enterprise edition can export data to any ODBC-compliant data-base. Like the ODBC import, the export operation requires a connection


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.


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.


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.


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.


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 SharingThe 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 KitThe 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)


76

3

1 Connect string2 Query3 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


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 FILE1 Connect String2 Table Name (Table that data is exported to)3 Worksheet Column for definition 14 Table Field for definition 15 Fixed Field Flag for definition 16 Worksheet Column for definition 27 Table Field for definition 28 Fixed Field Flag for definition 2

…2+3*n-2) Worksheet Column for definition 12+3*n-1) Table Field for definition 12+3*n) Fixed Field Flag for definition 1END 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


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 FunctionConnectString 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.


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 FunctionGetQuery 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


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 FunctionCell (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


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:


82

3

Figure 3-3. Interfaces

IQueryBuilderProperties:ConnectStringQueryStringQueryBuilderDescriptionQueryBuilderVersionQueryBuilerExtQueryBuilderListNameAppHelpFileMethods:GetQueryGetErrorConfigCutsomQueryBuilderImportDataViaImportFileWorkSheetPopulateWorkSheet

IConsumer

Properties:CellColumnHeaderUnits


83

3

Figure 3-4. Flow Chart of Custom Query builder usage

Create objectim plem entingIConsum er:

IW rkSht

Create an Instance of theCustom Q uery Builder(CQ B) with interface

IQ ueryBuilder

Set Q ueryString,AppHelpfile,

ConnectStringproperties of the

CQ B

Call W orkSheetm ethod of CQ Bwith the IW krSht

as param eter

Canceled, no dataloaded

Show errorMessage, no data

loaded

Canceled, no dataloaded

Show errorMessage, no data

loaded

rc>0

rc>0

rc=0

rc=0

rc<0

rc<0

Call G etQ ueryon the CQB

CallPopulateW orksheetm ethod of the CQ B

Return toW inNonlin

m ain processing


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 dataWinNonlin 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


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

WorksheetsEditing 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.

orType 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


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.


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.orPress the Delete key.

To clear formatting, such as font face and borders, from cells:


2. Select Edit>Clear>Formats from the menus.

To clear data values and formats from cells:


2. Select Edit>Clear>All from the menus.

This will delete the information from the cells, but will not remove the cells.


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)orSelect 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).orSelect 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.


91

4

To insert a cell:

1. Select a cell with the mouse.

2. Select Insert from the Edit menu (Alt+E, I)orRight-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).orRight-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).orRight-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).


92

4


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.


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.


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 (<>).


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


Remove Row Matching Criteria

To remove the row where the search string is found, check this check box.


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.orClick 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).orUse the keyboard shortcut Ctrl+Z.


96

4

orRight 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 EffectCut Restore cut value(s)

Paste Remove newly pasted value(s)Clear Restore cleared value(s)

Fill Restore original value(s) or clear new onesInsert 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 settingInclude Restore original status of selected cell(s)Exclude Restore original status of selected cell(s)

Sort Restore previous sort orderTransform Remove column containing transformation


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.


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:


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.


Font face and format

Use this tab to assign a font face and formatting to the selected cell or cells.

To assign a font:



3. Select the Font tab of the Format Cells dialog.


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.


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).


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.


Fill color and pattern

Use this tab to assign color and fill pattern to the selected cell or cells.

To assign a pattern:



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.


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.orDouble 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 manipulationWinNonlin worksheet operations include the following:

• “Freezing rows and columns” on page 101

• “Sorting” on page 101

WorksheetsData 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.


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

• ex, 1/X, Xn, X*n, X/n, X+n, X-n


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.


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.


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.


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).


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 ArcheryB BasketballB BadmintonC Cricket


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 BackgammaonC CardsC ChessD Dominoes

Table 4-5. Carry along data for like sort levels = Yes

A ArcheryB Basketball BackgammonB Badminton BackgammonC Cricket CardsC Cricket ChessD Dominoes

Table 4-6. Carry along data for like sort levels = No

A ArcheryB Basketball BackgammonB BadmintonC Cricket CardsC ChessD Dominoes


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.


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


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.


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


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


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


Before Tmax After Tmax First of consecutive after Tmax

After first of conse-cutive after Tmax

BQL 0 Missing LLOQ/2 MissingNS MissingISV MissingNA Missing… …


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.


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.


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 code’s 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.


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.


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.


118

4

119

Chapter 5

Units

WinNonlin supports the use of units throughout all operations—modeling 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 level–that 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 days1 1 hr 2.1 g/ml 245 days1 2 hr 1.1 g/ml 245 days2 0 hr 1.4 g/l 1 year2 1 hr 1.8 g/l 1 year


120

5

Units displayUnits 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 units—units enclosed in braces—will 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.

UnitsUnits options

121

5

Units optionsWinNonlin 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 typesWinNonlin 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 dayhour hrminute minsecond smillisecond msmicrosecond usnanosecond ns


122

5

Prefixes

Prefixes can be used for units of mass and volume.

Note: Units are not case-sensitive.

Dosing unitsDosing 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 gmole molpound lbIU 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

UnitsDosing 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.


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.

UnitsPreferred units

125

5

Note: If the data set’s 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 unitsPreferred 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 unitsWinNonlin 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.


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.

UnitsWorksheet 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.


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 WizardUse 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.


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.

ChartsChart 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


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.


ChartsChart 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.


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:


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.

ChartsChart 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


0123456

0 1 2 3 4 5 6

Mean = 3

Standard Error = 1

UP variable = Standard Error

Down variable = Standard Error

Relative Error Bars

0123456

0 1 2 3 4 5 6

Mean = 3

Minimum = 1

Up variable = blank

Down variable = Minimum

Absolute Error Bars


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.

ChartsAxis options

137

6

Axis optionsOnce 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 DesignerWinNonlin 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


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 window—but 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.

ChartsChart 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 view—all 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.


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.


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:


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.


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.


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.


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


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.


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.orUse the right mouse button to display the shortcut menu and select Chart Designer. Click on Plot in the tree view.orSelect 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.


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.


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


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.


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.


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


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:


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.


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.


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. 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.


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:


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.


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:


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.


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:


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.



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.


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:


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.


157

6

5. From the Style list select a marker type to identify the data points in the cur-rent series.


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.


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


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:


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.


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.


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


161

6

Formatting the data point label text

A data point’s 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.


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.orSelect 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.


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.


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.orSelect 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.


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.


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.


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.


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.


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.


167

6


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.


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.orOpen 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.


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.


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.orOpen 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.


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.


To specify when tick marks are displayed:

1. Uncheck the Automatic check box in the Scale section of the Date Scale tab.


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.


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.


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.orOpen 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.



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.



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.


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.


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.


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


2. Select Axis Title in the tree view pane.orDouble click on the axis title to be formatted.

3. Select the Layout tab.


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.


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.


2. Select Axis Title in the tree view pane.orDouble click on the axis title to be formatted.

3. Select the Picture tab.

4. Select the commands and options. These can include:


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.


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. orSelect 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.


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.


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.orSelect 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.


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.orSelect 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 optionsThis section highlights some of the formatting options that are used most fre-quently.

This section covers:

• Changing Line Styles and Markers (Symbols)

ChartsFrequently 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.orWith 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.


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.orSelect 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.

ChartsFrequently 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:


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:


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.


182

6

Chart templatesWinNonlin 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 chartsWinNonlin 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.

ChartsPreview 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.


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 pasteWinNonlin 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).

ChartsSave options

185

6

Save optionsCharts 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.


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 WizardFollowing 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:


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 templatesNine table templates are provided in the Table Wizard. Templates 1 through 8 use a single data set, while Template 9 combines data from two.

TablesTable 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-


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.

TablesTable 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.


192

7

Table template variablesThe 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.

TablesTable 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 ConcCapsule 1 0.00 0.00

1 5.00 340.321 10.00 1914.001 15.00 2069.171 20.00 1470.92

Form= Capsule

Subject Time Conc1 0.00 0.001 5.00 340.321 10.00 1914.001 15.00 2069.171 20.00 1470.92


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 FormulationID Variable Subject

Cross Variable TimeVariable Concentration

Variable = Conc

TimeForm Subject 0.00 0.50 ... 24.00

Capsule 1.00 0.00 340.32 ... 19.322.00 0.00 887.67 ... 38.913.00 0.00 2164.60 ... 24.004.00 0.00 628.87 ... 93.855.00 0.00 384.63 ... 25.706.00 0.00 678.22 ... 46.55

Tablet 1.00 0.00 1474.20 ... 15.202.00 0.00 2609.83 ... 29.493.00 0.00 968.88 ... 55.224.00 0.00 1566.80 ... 32.005.00 0.00 1200.04 ... 12.546.00 0.00 1815.80 ... 36.20

TablesJoining 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 setsTemplate 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.


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.

TablesSummary statistics

197

7

7. Repeat the steps above until all appropriate pairs have been specified.

8. Click Done to return to the Tables.

Summary statisticsThe 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.


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.

TablesSummary 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.


200

7

Table formattingThe 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.

TablesTable formatting

201

7


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.


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.


6. To change the alignment of the footer text, select the appropriate radio button in the Alignment group box.


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

TablesTable 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.


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 filesA 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

TablesTable 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.


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.


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 StatisticsComputing summary statistics

209

8

Table 8-1. Descriptive statistics output

Statistic DescriptionN Number of observations with non-missing data

Nmiss Number of observations with missing dataNobs Number of observationsMean Arithmetic Average

SD Standard Deviation:

SE Standard Error:

Variance Unbiased sample variance:

Min Minimum valueMedian Median value

Max Maximum valueRange 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 observationsHarmonic Mean Reciprocal of the arithmetic mean of the reciprocals of the observations

Variance

SDN

--------

Xi X–( )2

i 1=

N

∑N 1–

-------------------------------


210

8

Pseudo SD Jackknife estimate of the standard deviation of the harmonic mean. For n points, x1, .... xn the pseudo standard deviation is:

where:

and:

Mean log Arithmetic average of the natural logs of the observationsSD 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–( ) Hi H–( )2

i 1=

n

∑=

H 1n--- Hi

i 1=

n

∑=

Hin 1–( )

1x1----- 1

x2----- … 1

xi 1–---------- 1

xx 1+----------- … 1

xn-----+ + + + + +

----------------------------------------------------------------------------------------------=

n 1–( )

1xj----

j 1=

n

∑

1xi----–

-----------------------------=

SD_log( )2( )exp 1– 100×

Mean tα 2⁄SD

N--------–

Descriptive StatisticsComputing 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 χL2 and χU

2 are from the χ2-distribution with N-1 degrees of freedom. χL

2 cuts off a lower tail, and χU2 cuts off an upper tail, of area

α/2 where (1 - α)*100 is the percentage for the confidence interval.P(ercentiles) The pth percentile divides the distribution at a point such that p percent

of the distribution are below this pointSkewness 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------------------------------------------------

wi xi xw–( )3 N⁄∑wi xi xw–( )2 N⁄∑

3 2⁄---------------------------------------------------------

wi xi xw–( )4 N⁄∑wi xi xw–( )2 N⁄∑

2---------------------------------------------------- 3–


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 statisticsSummary 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 UnitsN, Nmiss, Nobs No units

CV%, CV% Geometric Mean No unitsSkewness No unitsKurtosis No units

Mean log, SD log No unitsVariance x-unit2

CI Lower Var, CI Upper Var x-unit2

Everything else x-unit

Descriptive StatisticsWeighted summary statistics

213

8

Table 8-2. Weighted summary statistics output

Statistic DescriptionN Number of non-missing observations (including those with weights = 0)

Nmiss Number of observations with missing dataNobs 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 varianceCI X% Upper Var Upper limit of an X% confidence interval, using weighted variance

Skewness Weighted coefficient of skewness:

Kurtosis Weighted coefficient of excess (kurtosis):

wi∑ xi×

wi∑-----------------------

Weighted Variance

Weighted SDN

-------------------------------

wi∑ xi xw–( )2

N 1–------------------------------------ xw

wi∑ xi xw–( )3 n⁄

wi∑ xi xw–( )2 n⁄3 2⁄

--------------------------------------------------------

wi∑ xi xw–( )4 n⁄

wi∑ xi xw–( )2 n⁄2

--------------------------------------------------- 3–


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


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 WinNonlin’s 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 requiredModel 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 doseModel 211 Urine Bolus IV Dose, Time of last doseModel 212 Urine Constant infusion Dose, Time of last dose

Noncompartmental AnalysisModel 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


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 settingsWinNonlin 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 AnalysisLambda z estimation settings

219

9

value of zero for the dependent variable are excluded. For each regression, an adjusted R2 is computed:

where n is the number of data points in the regression and R2 is the square of the correlation coefficient.

The regression with the largest adjusted R2 is selected to estimate λz, with these caveats:

• If the adjusted R2 does not improve, but is within 0.0001 of the largest adjusted R2 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 user’s 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 R2 1 1 R2–( ) n 1–( )×n 2–( )

-------------------------------------------–=


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 AnalysisPartial 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 areasUp 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.


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 AUC’s 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 windowThe 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 AnalysisDosing 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 regimenModels 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

TimeLowTimeDuringTimeHighAUCLowAUCDuringAUCHigh

total time below lower limittotal time between lower limit and upper limittotal time above upper limitAUC for time below lower limitAUC for time between lower limit and upper limitAUC for time above upper limit

Lower and upper

from dosing time to infinity using λz (if λz exists)

TimeInfDuringTimeInfHighAUCInfLowAUCInfDuringAUCInfHigh

total time between lower limit and upper limittotal time above upper limitAUC for time below lower limitAUC for time between lower limit and upper limitAUC for time above upper limit

Lower only from dosing time to last observation

TimeLowTimeHighAUCLowAUCHigh

total time below lower limittotal time above lower limitAUC for time below lower limitAUC for time above lower limit

Lower only from dosing time to infinity using λz (if λz exists)

TimeInfHighAUCInfLowAUCInfHigh

total time (extrapolated to infinity) above lower limitAUC for time (extrapolated to infinity) below lower limitAUC for time (extrapolated to infinity) above lower limit


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 AnalysisModel 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.


Rules for handling of steady-state dataWhen 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 optionsOptions for NCA model output are divided into the following groups:

Table 9-3. NCA model options

Category OptionsOutput options • Workbook, chart, and/or ASCII text formats for modeling resultsWeight • Uniform or weighted least squaresTitle • Text title for workbook, ASCII and chart outputNCA settings • Method for computing area under the curve, and format of final

parameters worksheetUnits • Default units for output parametersParameter names • Option to set the variable names for final model parameters


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:


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 missingProfile includes only one or no observations all final parametersBlood/plasma data with no non-zero observation values All final parameters except Cmax,

AUClast, AUCall, AUMClastBlood/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 parametersUrine 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


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.


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/Yhat2.

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/Y2.


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


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


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.



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.nammodel201.nam model201SS.nammodel202.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).


234

9

Computational rules for WinNonlin’s 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 AnalysisComputational rules for WinNonlin’s 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 t1

t2 tδC1 C2+

2-------------------×=

AUMC t1

t2 tδt1 C1× t2 C2×+

2---------------------------------------×=


236

9

Logarithmic trapezoidal rule

where δt is (t2-t1).

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 t1

t2 tδC2 C1–

lnC2C1------

------------------×=

AUMC t1

t2 tδt2 C2× t1 C1×–

lnC2C1------

---------------------------------------× t2δC2 C1–

lnC2C1------

2-------------------×–=

C* C1t* t1–t2 t1–--------------- C2 C1–( )+=

C* C1( ) t* t1–t2 t1–--------------- C2( )ln C1( )ln–( )×+ln

exp=


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-


238

9

mined if a boundary crossing occurred in that interval. Call the pair of time values from the data set (ti, ti+1) and called the boundaries ylower and yupper.

If no boundary crossing occurred, the difference ti+1– ti is added to the appro-priate parameter TimeLow, TimeDur, or TimeHgh, depending on which win-dow the concentration values are in. The AUC for (ti, ti+1) is computed following the user’s 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 + ylower * (ti+1 – ti)

AUCDur = AUCDur + (yupper – ylower) * (ti+1 – ti)

AUCHgh = AUCHgh + AUC* – yupper * (ti+1 – ti)

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 user’s 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 (ti, ti+1) at which the concentration value is yw:

Linear interpolation rule for time:

t* = ti + [ (yw – yi) / (yi+1 – yi) ] * (ti+1 – ti)

Log interpolation rule for time:

t* = ti + [ (ln(yw) – ln(yi) ) / ( ln(yi+1) – ln(yi) ) ] * (ti+1 – ti)

The AUC for (ti, t*) is computed following the user’s specified AUC calcula-tion method. The difference t* – ti 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*, ti+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 (ti, t*) as above. Then another interpolation is done from ti to ti+1 to get the time of the second crossing t** between (t*, ti+1), and


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**, ti+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 yw is:

t* = (1/lambdaZ) * (alpha – ln(yw)).

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(ylower))

TimeInfDur = TimeDur + (t* – tlast)

AUCInfDur = AUCDur + AUC* – ylower * (t* – tlast)

AUCInfLow = AUCLow + ylower * (t* – tlast) + ylower / lambdaZ

If ylast 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


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(yupper))

t** = (1/lambdaZ) * (alpha – ln(ylower))

TimeInfHgh = TimeHgh + (t* – tlast)TimeInfDur = TimeDur + (t** – t*)

AUCInfHgh = AUCHgh + AUC* – yupper * (t* – tlast)

AUCInfDur = AUCDur + (yupper – ylower) * (t* – tlast) + AUC** – ylower * (t** – t*)

AUCInfLow = AUCLow + ylower * (t* – tlast) + ylower * (t** – t*) + ylower / 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.


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.


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

= +AUClastClast

Zλ

AUCINF AUClastAUCINF

100− ∗

AUMCINF AUMClastAUMCINF

100− ∗

=∗

DoseAUCINFZλ

= AUMCINFAUCINF

( )= −AUMCINFAUCINF

TI2


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.

VSS 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:

=

Vz, Vz/F For steady-state data:

=Dose

AUC 0τ|

AUMC 0τ τ AUCINF AUC 0

τ–( )+

AUC 0τ

-----------------------------------------------------------------------------------

AUMC 0τ τ AUCINF AUC 0

τ–( )+

AUC 0τ

----------------------------------------------------------------------------------- T12

------–

=∗

DoseAUCZλ τ

0


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)


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


246

9

247

Chapter 10

Compartmental Modeling

Using WinNonlin’s 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 modelThe 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.


248

10

4. Select the type of model to load from among the following.

Table 10-1. WinNonlin model types

Model type DescriptionModels 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 0th or 1st 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 ModelingModel 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 propertiesOnce 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


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.


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 searchif 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-


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.


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 34 = 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


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, 181 # of doses # of doses stripping dose2 dose 1 dose 1 # doses3 time of dose 1 start time 1 dose 14 dose 2 end time 1 time of dose 15 time of dose 2 dose 2 dose 26 (etc.) start time 2 time of dose 27 end time 2 (etc.)8 (etc.)9


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 171 bolus dose stripping dose2 IV dose bolus dose3 length of infusion IV dose4 length of infusion

NCON 3 4

Model Number

Constant 1, 3-7, 11, 12 2, 9, 10, 19 8, 13, 14, 18


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 ModelingModel 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 optionsThe options for model output and computational algorithm appear on five tabs in the Model Options dialog.


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 DescriptionOutput options Select text, chart (plots) and/or workbook output formsWeight 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 algorithmUnits Default output units for parameter estimates


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.


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.


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


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:


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( )( )–∆

---------------------------------------------------------=


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 ModelingRunning 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.

OutputOne 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


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 ModelingOutput

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,


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).


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 ContentsInitial 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 Tablea 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 CP and Ce. For indirect response models, it also includes CP.


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)


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.


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.

TemplatesTwo 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


274

11

models in WinNonlin’s 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 structureThe 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= − ∗1dz dt k w k y= ∗ − ∗1 2

User ModelsModel 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:MODELTRANSFORM statementsEND

Statements to alter data values before the functions or differential equations are fit go here.

COMMANDstatementsEND

This block contains the WinNonlin commands which load the model.

TEMPORARY state-mentsEND

Commands to create variables that will be used in more than one block (i.e. global variables), go here.

FUNCTION statementsEND

A function block must be included for each different model or equa-tion for which corresponding data are available.

START statementsEND

Initial conditions for the system of the differential equations are placed in this section.

DIFFERENTIAL statementsEND

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-mentsEND

All secondary parameters, which are parameters defined as functions of the model parameters, are specified here.

EOM


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 componentsEach 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 ModelsModel 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.


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 blockCOMMNPARAMETER 5PNAMES ‘K01’ ‘K10’ ‘K12’ ‘K20’ ‘VOLUME’NFUNCTIONS 1NCONSTANTS 2END


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.


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: ClearanceCOMMANDSNSEC 1ENDSECOS(1)=0.693/K10 END

Example of PNAMES, DNAMES, PUNITS, SUNITS and SNAMES CommandsCOMMDNAMES ‘SUBJECT’, ‘FORM’, ‘TIME’, ‘CONC’NPARM 3PNAMES 'K10', 'VOLUME', 'K1E'PUNIT ‘1/hr’, ‘ml’,’1/hr’NSEC 1SNAMES 'CL'SUNIT ‘ml/hr’ENDSECOCL =0.693/K10END


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)).


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 BlocksFUNC 1 <--An algebraic functionF=A*EXP(-ALPHA*T)ENDFUNC 2 <--A differential equationF=Z(1)END

Example - Starting ValuesSTARTZ(1)=C0Z(2)=0END


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 BlockDIFFDZ(1)=-K12*Z(1)DZ(2)=K12*Z(1) - K20*Z(2)END

Example - Secondary BlockSECOREMARK Note that D and AUC must be definedS(1) = D/AUCEND


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 variablesWinNonlin provides access to both input data and parameter estimates during the model-fitting process. This allows creating “adaptive” models—that 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 SNAMECOMMNSEC 1SNAME ‘CL’ENDSECOCL = D/AUCEND

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 ModelsWinNonlin variables

285

11


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.


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 languageWinNonlin 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

GOTOAction 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

LABELAction 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 ModelsThe 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 THENWhere expression is a logical expression.

Example IF I>4 THENGOTO GREENELSEGOTO BLUEENDIF

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.

ELSEAction 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.

ENDIFAction Terminates an IF block.SyntaxRemarks 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.


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 3DO J=1 TO 5statementsNEXTNEXT

NEXTAction Marks the end of a DO loop.

Syntax DO .......NEXT

Example See DO.

Operator DefinitionAND andOR orGT > greater thanLT < less thanEQ = equal toGE >= greater than or equal to

User ModelsThe 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, ex.

LE <= less than or equal to

Function Name ResultLAG(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) ex

ALOG (X), DLOG (X), LOGE (X)

natural log of X: ln(X)

ALOG10 (X), DLOG10 (X) LOG10 (X) log base 10 of X: log10 (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 YMIN (X, Y), DMIN1 (X, Y) returns the minimum of X and YABS (X), DABS (X) returns the absolute value of XATAN (X), DATAN (X) tan-1(X)ATAN2 (X, Y), DATAN2 (X, Y)

tan-1(X/Y)

Operator Definition

X


290

11

Bioassay functions

ASCII modelsUser 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 ResultNORMIT (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 dzNOR

= −−∞∫ 1

222

πexp

( )( )WTNOR N Zp p= ∗∗ −

2

1

( )Z NOR= −12

22

πexp

( )p X dxNOR

= −−∞∫ 1

222

πexp

where

and

( )ln PP1 −

LOGIT =

User ModelsASCII 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 1model statementsEOMMODEL 2model statementsEOMMODEL 3model statementsEOM

( ) ( ) ( )C t A t B t= ∗ − ∗ + − ∗exp α β


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

MODELFUNCTION 1F=P(1)*EXP(-P(2)*X)-P(1)*EXP(-P(3)*X)ENDSECONDARYS(1)=-LOGE(.5)/P(2)S(2)=-LOGE(.5)/P(3)ENDEOM


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.

MODELremark: Example problemCOMMANDNPARM 3NSEC 2PNAMES ‘A’, ‘ALPHA’, ‘BETA’SNAMES ‘ALPHA_HL’, ‘BETA_HL’ENDFUNC 1B=-Aremark: Model is constrained so that C(0)=0TIME=XE1=EXP(-ALPHA*TIME)E2=EXP(-BETA*TIME)F=A*E1 + B*E2ENDremark: Secondary parametersSECOALPHA_HL=-LOGE(.5)/ALPHABETA_HL=-LOGE(.5)/BETAENDEOM


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.

COMMANDSNPAR 2NSEC 2END

dZdt

K Z( ) ( )1 12 1= − ∗

dZdt

K Z K Z( ) ( ) ( )2 12 1 20 2= ∗ − ∗


295

11

with initial conditions Z1(0) = D and Z2(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.

MODELCOMMANDNPARM 3PNAMES ‘K12’, ‘K20’, ‘D’END

STARTZ(1) = DZ(2) = 0END

FUNC 1F=Z(2)END

DIFFDZ(1) = -K12 * Z(1)DZ(2) = K12 * Z(1) - K20 * Z(2)ENDEOM


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 11.0 0.7 12.0 0.9 1... ....0.5 0 21.0 0 22.0 0 23.0 0.02 2


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.

MODELCOMMNPAR 5PNAMES ‘A’, ‘B’, ‘ALPHA’, ‘BETA’, ‘LAG’ENDFUNC 1I = 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)ENDIFENDEOM


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.

MODELCOMMNPAR 5PNAMES ‘A’, ‘B’, ‘ALPHA’, ‘BETA’, ‘LAG’ENDFUNC 1 T = X F = A*EXP(-ALPHA*T) + B*EXP(-BETA*T)ENDFUNC 2 T = X-LAG F = A*EXP(-ALPHA*T) + B*EXP(-BETA*T)ENDEOM . .NFUNC 2 : Number of FunctionsFNUM 3 : Column number representing the function variable .


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 effectCut Restore cut text string.

Paste Remove newly pasted text string.Clear Restore cleared text string.

Replace Restore original string.


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 ModelsCompiled user models

301

11

Compiled user modelsFor 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 WinNonlin’s 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 PurposeF_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.


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.


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).


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 TransformationsTemporary block Set Temporary variablesFunction block Set FunctionsStarting values block Set Starting valuesDifferential block Set Differential equationsSecondary block Set Secondary parameters


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 PurposeC_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.


306

11

9. On the Project menu select Add to Project…New.

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 Configuration…Win32 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 TransformationsTemporary block Set Temporary variablesFunction block Set FunctionsStarting values block Set Starting valuesDifferential block Set Differential equationsSecondary block Set Secondary parameters


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.


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.

titleFitting a system of two differential equations - data available on both model 1000, 'c_uexp6.dll'npar 3pnames 'K12', 'K20', 'C0'nder 2 <--- 2 diff. equations in the systemnfun 2 <--- data available on both equationsinit .1, .05, 100lower 0 0 0upper 1 1 200reweight -1 <--- iteratively reweight by 1/(pred. conc.) nvar 3fnum 3data0 100 11 85.34 12 79.44 13 79.13 14 71.18 15 56.2 110 29.66 115 17.47 120 10.8 125 5.81 130 3.23 140 .93 150 .32 160 .1 10 0 21 10.86 22 21.1 23 27.01 24 34.45 25 36.41 210 46.27 215 48.73 220 48.17 225 41.76 230 27.32 240 20.70 250 11.18 260 5.76 2beginfinish

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 structureA WinNonlin command file has three main components: Model definition, Commands and Data.


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 won’t 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: basicsEach 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 FilesWinNonlin 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

ExampleINITIAL ARE.05 &1.D-3 &100

is equivalent to

INIT.05, 1D-3, 100

Examples of CommentsREMARK - USING NELDER-MEADorMETHOD 1: NELDER-MEADorMETHOD 1 NELDER-MEAD


312

12

Model definition commandsThe 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 commandsModel 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 FilesModel 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 Type1 1 0 3.8 1.9 11 1 .5 4.8 2.2 11 1 1 5.1 2.3 1. . . . . .

Example - XNUMBER and YNUMBERXNUMBER is 2YNUM 3

Example - SimulateXNUM 2SIMULATE

Example - Sort variablesSORT 1, 1, 2


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 WinNonlinA:

Example - Function variableFNUM 6

Example - URINE commandURINE LOWER = # UPPER = # VOLUME = # CONCENTRATION = #

URINE CONC # VOLU # LOWE # UPPE #

A. Note that for Noncompartmental models, only option 1 is allowed.


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 YW. 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 FW, 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 SquaresWEIGHT -2 ← uses 1/Y2 as the weightWEIGHTWTNUM 7 ← uses the values in Column 7 as the weightsWEIGHT ← uses the values in Column 3 as the weights

Example - Iterative ReweightingREWEIGHT -.5← uses 1/sqrt(Yhat) as the weight

REWEIGHT 2← uses Yhat2 as the weight


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 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 statementsWT = 1/(F*F) equivalent to using REWEIGHT -2IF X > 10 THEN WT=1/YELSEWT=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/Y2 if X is less than or equal to 10


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.

ExampleNPAR 3INIT .1, .05, 10LOWER 0, 0, 0UPPER 1, .5, 100

User supplied boundaries

NPAR 3INIT .1, .05, 10

WinNonlin will compute bounds on the parameters

NPAR 3INIT .1, .05, 10NOBO

No boundaries will be used


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 3REMARK # Doses, Dose 1, Time of Dose 1CONSTANTS 1 50 0

NCON 5CONS 2, 50, 0, 25, 6

ExampleTIMEDATE

ExampleTITLEExperiment A-4115

TITLEExperiment A-4115TITLE 2Subject #1


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 1000A.

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 dosesIV infusion: 1000 + the number of doses times 2.


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 commandsGenerally 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.

ExamplesDATA are in 'MYDATA.FIL’

DATA 'B:TEST.DTA’

DATA.5 1.3.75 1.7

ExamplesOne function: NOBSERVATIONS ARE 15

(Optional)Two functions: NOBS 15, 18

Command FilesData 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, 12Examples

Example: FNUMREMA Using a FUNCTION variable to indicate to which func-tion data belongs.NFUN 2FNUM 3DATA0 0.25.501.02.04.0

0.3.5.4.25.15

111111

← start of data for function 1

0.25.501.02.04.0

0.28.45.43.30.30

222222

← start of data for function 2


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 statementsThe 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.

ExampleYNUM is 4XNUM is 3

Command FilesExecution control statements

323

12

Example - using BEGIN and FINISH .DATA1 .052 1.03 2.06 1.08 .05BEGINFINISH


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 squaresWhen using weighted least squares, WinNonlin weights each observation by the value of the dependent variable raised to the power of n, i.e., WEIGHT = Yn. 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( )⁄


326

13

Iterative reweightingIterative Reweighting redefines the weights for each observation to be Fn, 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 fileIt 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 weightsWhen 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( )⁄

WeightingWeights 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 modelsWhen 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.84310 9 0.0123 0.819

100 14 0.0051 0.338Sum 0.0452 3.000

MODELTRANSFORMIF X > 10 THENWT = 1/YELSEWT = 1/(Y*Y)ENDIFEND(additional statements here)


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/Y2 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:

MODELFUNC 1F = A*EXP(-ALPHA*X) - A*EXP(-BETA*X)WT = 1/(F*F)END(additional statements here)

MODELTEMP(additional statements here)ENDFUNC 1(additional statements here)WT = (some function)ENDFUNC 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 superpositionIn 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.

WinNonlin’s 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-


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(ti) at sufficient time points ti, (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(ti) at times ti, (i=1,2,…,n), after a single dose D, one may obtain the concentration C(t) at any time t through interpola-tion if t1 < t <tn, or extrapolation if t > tn. 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 line’s slope is λz and the intercept is ln(β), then C(t) = β exp(-λzt) for t > tn.

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 ToolboxNonparametric 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 Dj, j = 1,…,m, and each dose is adminis-tered after τ j time units from the first dose. The concentration due to dose Dj will be Cj(t) = (Dj / 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 Cj(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 C1(t) for 0 < t < τ. The concentration at time t after nth dose will be:

Cn(t) = C1(t) + β exp[-λ(t+τ)] + β exp[-λ(t+2τ)]

+…+ β exp[-λ(t+(n-1)τ)]

= C1(t) + β exp[-λ(t+τ)]{1-exp[-λ(n-1)τ]} / [1-exp(-λτ)]

As n→∞, the steady state (ss) is reached:

Css(t) = C1(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(ti-1) + [C(ti)-C(ti-1)]*[t- ti-1]/[ti- ti-1],

ti-1 < t < ti

Log-interpolation is appropriate for original concentration data, and is evalu-ated by:

C(t) = exp{log(C(ti-1))+[log(C(ti))-log(C(ti-1))]*(t-ti-1)/(ti-ti-1)}, ti-1 < t < ti

For more information see Appendix E of Gibaldi and Perrier (1982).


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 computations—linear 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 ToolboxNonparametric superposition

333

14

orIf 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.


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 ToolboxSemicompartmental 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 modelingSemicompartmental modeling was proposed by Kowalski and Karim (1995) for modeling the temporal aspects of the pharmacokinetic-pharmacodynamic


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 Ce by using a piece-wise linear model for plasma concentration Cp rather than specifying a PK model for Cp. The potential advantage of this approach is reducing the effect of model misspecification for Cp when the underlying PK model is unknown.

WinNonlin’s 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.


Drug concentration in plasma Cp for each subject is measured at multiple time points after the drug is administrated. To minimize the bias in estimating Ce, 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 keo that accounts for the lag between the Cp and the Ce curves is required. A piecewise log-lin-ear model is assumed for Cp.

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 Ce is related to Cp by first-order dis-position kinetics and can be obtained by solving the differential equation

where keo is a known constant. In order to solve this equation, one needs to know Cp as a function of time, which is usually given by compartmental PK models.

)( epeoe CCk

dtdC

−=


337

14

Here, use a piecewise linear model for Cp

Cp (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 Ce

The initial condition is Cp(0) = Ce(0) =0.

One can also assume a log-linear piecewise PK model for Cp

Cp (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:

Ce (0) =Cp(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 Ce but when it is provided, the E-Cp and E-Ce plot will be plotted.

Performing semicompartmental modeling

To perform semicompartmental modeling:


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.

Cpj 1–λj

λj CpjCpj 1–

Cpj 1–Cp tj 1–( )=

)(]1)[( 1)()( 1

1

1

1 −−−−− −+−−+= −

−

−

− jjjttk

eo

jp

ttkee tte

kCeCC jjeo

j

jjeo

jjλ

λ

Cpj 1–λj

λj Cpj 1–Cpj ][ )()()( 11

1

1

1

−−

−

−

−

−−−−−− −−

+= jjeojjj

j

jjeo

jj

ttktt

jeo

eop

ttkee ee

kk

CeCC λ

λ

λ1 Ce1


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).


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.


340

14

Figure 14-5. Cp vs. Time plot

Figure 14-6. Ce vs. Time plot


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


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 designThe 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.

WinNonlin’s 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.


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 yijk 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 ToolboxCrossover 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.

sij = yij1 + yij2 ;

dij = yij1 - yij2;

C in Column 7 represents the within-subject crossover difference, defined as:

cij = yij1 - yij2, if i=1

= yij2 - yij1, 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 X1, X2,…, XN. 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) Yij1 Yij2 Sij Dij Cij

TR 1 y111 y112 s11 d11 c11

.. … … …TR n y1n1 y1n2 s1n d1n c1n

RT n+1 y2(n+1)1 y2(n+1)2 s2(n+1) d2(n+1) c2(n+1)

… … … …RT n+m y2(n+m)1 y2(n+m)2 s2(n+m) d2(n+1) c2(n+1)


344

14

Xl = X(L), where L = max

Xu = X(U), where U = min

The exact probability is .

• For N > 20, normal approximation is used:

Xl = X(L), where L =

Xu = 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(Sl) is the rank of Sij in the whole sample, l = 1,.., n+m. The test statistic is:

i: Ni

2 N–

i 1=

N

∑ 1 p–( ) 2⁄<

1+

i: Ni

2 N–

i 1=

N

∑ 1 p+( ) 2⁄>

1–

Ni

2 N–

i L=

U

∑

int N2---- z1 p+

2------------

N2

--------–

1+

N int N2---- z1 p+

2------------

N2

--------–

–


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 (Yij1, Yij2). For each period k, let Rijk equal:

rank { yijk: y11k, …, y1nk, y2(n+1)k, …, y2(n+m)k }

The average rank for each sequence is

= , where j=1,…, ni, ni=n for i=1, and ni=m for i=2.

Thus, the statistic to be used for testing hypothesis 4 is:

L = (n+m-1)[nU1T*S-1*U1 + mU2

T*S-1*U2]

Where Ui 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.

Rl

l 1=

n

∑ Rl

l n 1+=

n m+

∑

nm n m 1+ +( ) 12⁄

Rik Rijk ni⁄

j 1=

ni

∑

Ri1 Ri2

ΣiΣjRij1 M–( )2 Rij1 M–( ) Rij2 M–( )

Rij1 M–( ) Rij2 M–( ) Rij2 M–( )2


346

14

Using the Crossover Design tool

To utilize crossover design:


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.


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.


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.

DeconvolutionDeconvolution 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 ToolboxDeconvolution

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 (NB(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-


350

14

dent of the entry time. Thus the probability of being at B for a molecule that enters A at time tA is g(t-tA). This assumed property is called time-invariance. Consider again the simultaneous entry of N molecules, but now at time tA 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 NB(t) = Ng(t-tA).

Suppose that the actual time at which the molecule enters point A is unknown. It is instead a random quantity tA 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-tA) where the average is taken over the possible values of tA 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 tA t≥( ) h u( ) ud0

t

∫=

∫∞

∞−−= AAA dtthttgtg )()()(

g t tA–( )h tA( )

∫ −=t

AAA dtthttgtg0

)()()(

N′A t( ) Nh t( )=

∫∫ ′−=−==t

AAAA

t

AAAB dttNttgdtthttgNtgNtN00

)()()()()()(


351

14

where MB(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 Vs 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 fp(t) convolved with an exponential “dispersion” function fd(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, hj(t):

∫ −=t

AAAB dttfttgtM0

)()()(

∫ ∗≡−=t

tctfduucutftc0

)()()()()( δδ

cδ t( ) g t( ) Vs⁄=

cδ t( )

cδcδ

0)()( ≥=∑ jjjp xthxtf


352

14

where Tj 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 (Tj) 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 fd(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

),/()(),/()()(

21

1

122

1

++

+

+++

+

<≤

<<

=

−−=

−−=

jj

jj

jjj

jjjj

TtTTtT

TTtTTTTtth

δ

δ/

)(t

detf

−

=

t 0 to ∞=

∫ −≡∗=t

dpdp duufutftftftf0

)()()()()(


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 (observed–calculated 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 WinNonlin’s 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, fd(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).

)()()()( tctftftc dp δ∗∗=

cδ t( )


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, fd(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 rj 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

jjrPRESS

1

2


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 fp(t)*fd(t) of the above dual input function.

f 0( ) 0=f′ 0( ) 0=

f 0( )

)()()()())()(()(

tfxtftftftxtftf

ddp

dp

δ

δ δ+∗=

∗+=

fp t( ) fd t( )xδfd t( )

xδ

xδfd t( )


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, tend:

The above fraction input will by definition have a value of 1 at the last obser-vation time, tend. 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=

fp 0( ) 0=

∫=t

dttf0

)(inputAmount

∫ ∫=t t end

dttfdttf0 0

)(/)(inputFraction


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

talphaj

ieAtc1

)(δ


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.


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


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.


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.


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:

yijkm = µ + πi + δj + τq + Sk(j) + εijkm (1)


364

15

where:i = period index (1 or 2)j = sequence index (AB or BA)k = subject within sequence group index (1 … nj)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 studySk(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(Sk(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{yijkm}is known as the fixed effects of the model, while Sk(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{yijkm} = µ + πi + δj + τq (2)

Var{yijkm} = Var{Sk(j)}+ σ2. (3)

Linear Mixed Effects ModelingAn 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 Response1 AB 1 A 9.702 AB 1 A 10.243 AB 1 A 11.24 AB 1 A 7.825 AB 1 A 11.16 AB 1 A 9.317 BA 2 A 9.028 BA 2 A 7.889 BA 2 A 9.610 BA 2 A 9.6311 BA 2 A 9.6312 BA 2 A 9.917 BA 1 B 8.158 BA 1 B 9.239 BA 1 B 9.4310 BA 1 B 10.1311 BA 1 B 9.6712 BA 1 B 11.341 AB 2 B 8.722 AB 2 B 11.283 AB 2 B 11.734 AB 2 B 9.775 AB 2 B 8.916 AB 2 B 8.31


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 modelWinNonlin’s 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-effectsparameters), 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 andvariance R.

Linear Mixed Effects ModelingThe 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 = σ2I 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 variance—that is, R = σ2I.

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 1’s and 0’s. The exact method of constructing the X matrix is discussed in the section Construction of X matrix, below.

For each subject, there is one Sk(j). The collection can be directly entered into γ. The Z matrix will consist of 1’s and 0’s. 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{Sk(j)} In(1)+n(2)

• Fixed effects • Contrasts• Variance structure • Estimates• Least squares means

V ZGZT R+=

Z 0≠


368

15

where Ib represents a b×b identity matrix. The parameter to be estimated for G is Var{Sk(j)}. The residual variance is

R = Var{εijkm} = σ2 I2[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 CreatesFixed 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(ε)


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 productA. 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 = (aij) be a m×n matrix and let B = (bij) be a p×q matrix. Then the Kronecker product

A ⊗ B = (aij B)is an mp × nq matrix expressible as a partitioned matrix with aij 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 valueDrugA 0 capsule 0 48 120DrugA 0 drops 1 34 124DrugA 0 syrup 2 27 123DrugA 0 tablet 3 23 172DrugB 1 capsule 0 45 200DrugB 1 drops 1 26 150DrugB 1 syrup 2 41 120DrugB 1 tablet 3 32 130DrugC 2 capsule 0 38 190DrugC 2 drops 1 17 125


370

15

DrugC 2 syrup 2 32 175DrugC 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 DrugCDrugA 0 1 0 0 48 48 0 0DrugA 0 1 0 0 34 34 0 0DrugA 0 1 0 0 27 27 0 0DrugA 0 1 0 0 23 23 0 0DrugB 1 0 1 0 45 0 45 0DrugB 1 0 1 0 26 0 26 0DrugB 1 0 1 0 41 0 41 0DrugB 1 0 1 0 32 0 32 0DrugC 2 0 0 1 38 0 0 38DrugC 2 0 0 1 17 0 0 17DrugC 2 0 0 1 32 0 0 32DrugC 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 tabletDrugA 0 1 0 0 capsule 0 1 0 0 0DrugA 0 1 0 0 drops 1 0 1 0 0DrugA 0 1 0 0 syrup 2 0 0 1 0DrugA 0 1 0 0 tablet 3 0 0 0 1


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 jth subject on the ith treatment is:

DrugB 1 0 1 0 capsule 0 1 0 0 0DrugB 1 0 1 0 drops 1 0 1 0 0DrugB 1 0 1 0 syrup 2 0 0 1 0DrugB 1 0 1 0 tablet 3 0 0 0 1DrugC 2 0 0 1 capsule 0 1 0 0 0DrugC 2 0 0 1 drops 1 0 1 0 0DrugC 2 0 0 1 syrup 2 0 0 1 0DrugC 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 IndicatorDrugA capsule 1 0 0 0 0 0 0 0 0 0 0 0DrugA drops 0 1 0 0 0 0 0 0 0 0 0 0DrugA syrup 0 0 1 0 0 0 0 0 0 0 0 0DrugA tablet 0 0 0 1 0 0 0 0 0 0 0 0DrugB capsule 0 0 0 0 1 0 0 0 0 0 0 0DrugB drops 0 0 0 0 0 1 0 0 0 0 0 0DrugB syrup 0 0 0 0 0 0 1 0 0 0 0 0DrugB tablet 0 0 0 0 0 0 0 1 0 0 0 0DrugC capsule 0 0 0 0 0 0 0 0 1 0 0 0DrugC drops 0 0 0 0 0 0 0 0 0 1 0 0DrugC syrup 0 0 0 0 0 0 0 0 0 0 1 0DrugC tablet 0 0 0 0 0 0 0 0 0 0 0 1


372

15

where µ is a common parameter and µ+τi is the expected value of the ith 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 lj 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 lj. 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 c1, c2, and c3.

Note that c1=1, c2=0, and c3=0 generates µ + τ1, so µ + τ1 is estimable. A rearrangement of expression (6) is:

The form in (7) makes some things more obvious. For example, lj = cj for j=1,2,3. Also, any linear combination involving only τs is estimable if, and

µ + τi (4)

(5)

c1(µ + τ1) + c2(µ + τ2) + c3(µ + τ3). (6)

(c1 + c2 + c3)µ + c1τ1 + c2τ2 + c3τ3. (7)

lj βjj∑


373

15

only if, l1 + l2 + l3 = 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 lj of expression (5). The linear combination 5 in vector notation is lTb and is estimable if lTΖ = 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 01 0 0 1

Basis of orthogonal space -1 1 1 1

lTZ

l ∞ ZTZ-------------------------- tol<


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.

yijk = µ + αi + βj + (αβ)ij + εijk (9)

Linear Mixed Effects ModelingFixed 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 effectsThe 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 n×p, 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.251 1 -1 0 0 0.5 0.5 -0.5 -0.52 0 0 0 0 0 0 03 1 -1 0.5 -0.5 0.5 -0.54 0 0 0 0 05 1 -1 -1 16 0 0 07 0 08 09 0 1 -1 0 0 0 0 0 010 0 0 0 0 0 -0.5 -0.5 0.5 0.5Final result 0 1 -1 0 0 0.5 0.5 -0.5 -0.5


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

X0 is the intercept column. X1, X2, and X3 correspond to the three levels of the treatment effect. X0 and X1 are clearly linearly independent, as is X2 linearly independent of X0 and X1. But X3 is not linearly independent of X0, X1, and X2, since X3 = X0 - X1 -X2. 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 (loge), or log transformation (log10). 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).

X0 X1 X2 X3

1 1 0 01 0 1 01 0 0 11 1 0 01 0 1 01 0 0 1

Linear Mixed Effects ModelingFixed 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 X2 = X0 - X1. Hence set β2 = 0. Similarly, X4 = X0 - X3 and X6 = X0 - X5, 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 01 1 0 1 0 1 01 1 0 1 0 1 01 1 0 1 0 1 01 1 0 1 0 1 01 1 0 1 0 1 01 0 1 0 1 1 01 0 1 0 1 1 01 0 1 0 1 1 01 0 1 0 1 1 01 0 1 0 1 1 01 0 1 0 1 1 01 0 1 1 0 0 11 0 1 1 0 0 11 0 1 1 0 0 11 0 1 1 0 0 1


378

15

Variance structureThe 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 11 0 1 1 0 0 11 1 0 0 1 0 11 1 0 0 1 0 11 1 0 0 1 0 11 1 0 0 1 0 11 1 0 0 1 0 11 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 ModelingVariance 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, …, ng, 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 T1, T2, and T3. 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 T1, T2, and T3. 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 15×15 block. Each Rg has the same form. Because the variance blocking variable is specified, the form of each Rg is

I5 ⊗ Σg.

I5 is used because there are five subjects within each treatment group. Within each subject, the variance structured specified is

RR1 0 00 R2 00 0 R3

=


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

σg2

1 ρg ρg2 ρg

3

ρg 1 ρg ρg2

ρg2 ρg 1 ρg

ρg3 ρg

2 ρg 1

Linear Mixed Effects ModelingVariance 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 1’s) 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 R2A YB YC YA Z

B Z

C Z


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 R2A B C Y Z1 0 0 1 00 1 0 1 00 0 1 1 01 0 0 0 10 1 0 0 10 0 1 0 1

R1A B C1 0 00 1 00 0 11 0 0

=

21

22

23

24

25

22

21

22

23

24

23

22

21

22

23

24

23

22

21

22

25

24

23

22

21

σσσσσσσσσσσσσσσσσσσσσσσσσ

G

Linear Mixed Effects ModelingLeast squares means

383

15

For R2, the columns in the Z matrix and the corresponding G is:

In this case:

Least squares meansSometimes 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:

R1A B C1 0 00 1 00 0 11 0 00 1 00 0 1

R2Y Z

1 01 01 00 10 10 1

=21

22

23

22

21

22

23

22

21

1

σσσσσσσσσ

G

=

24

25

25

24

2 σσσσG

1

2

GG

G

=

00


384

15

yij = αi + xij β + εij

where yij is the observed response on the jth individual on the ith treatment; αi is the intercept for the ith treatment; xij is the value of the covariable for the jth individual in the ith 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 x1j is 5; and the average of the x2j 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:

yijk = µ + αi + βj + εijk

where yijk is the observed response on the kth individual on the ith level of fac-tor A and the jth level of factor B; µ is the over-all mean; αi is the effect of the ith level of factor A; βj is the effect of the jth 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 lj 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 ModelingLeast 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

ljColumn of X βj DrugA DrugB DrugC

Intercept β0 1 1 1Drug DrugA β1 1 0 0

DrugB β2 0 1 0DrugC β3 0 0 1

Form capsule β4 0.25 0.25 0.25drops β5 0.25 0.25 0.25syrup β6 0.25 0.25 0.25tablet β7 0.25 0.25 0.25


386

15

ContrastsA 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:

H0: µPlacebo - (µLow + µMedium + µHigh)/3 = 0

or equivalently:

H0: 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.17Drug*Form DrugA*capsule β9 0.25 0 0

DrugA*drops β10 0.25 0 0DrugA*syrup β11 0.25 0 0DrugA*tablet β12 0.25 0 0DrugB*capsule β13 0 0.25 0DrugB*drops β14 0 0.25 0DrugB*syrup β15 0 0.25 0DrugB*tablet β16 0 0.25 0DrugC*capsule β17 0 0 0.25DrugC*drops β18 0 0 0.25DrugC*syrup β19 0 0 0.25DrugC*tablet β20 0 0 0.25

Table 15-9. Coefficients of least squares means (continued)

ljColumn of X βj DrugA DrugB DrugC

Linear Mixed Effects ModelingContrasts

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.

H0:

Contrast #1Title Joint testsEffect TreatmentContrast Treatment#1 Placebo -1 -1#2 Low Dose 1 0#3 Medium Dose 0 1#4 High Dose 0 0

Lβ( )T

L XTVX( )1–LT( )

1–Lβ( )

β V

1– 1 0 01– 0 1 0

β 00

=


388

15

Now compare this with putting the second contrast in its own contrast.

This produces two tests.

H01: [-1 1 0 0] β = [0] H02: [-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 “Satterthwaite’s Approximation for Degrees of Freedom”.

Contrast #1 Contrast #2Title Low vs. Placebo Medium vs. PlaceboEffect Treatment TreatmentContrast 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 ModelingEstimates

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.

EstimatesThe 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 WizardThe 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.


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 marks—but not both.

The following are maximum counts for LinMix variables and other objects.

Table 15-10. LinMix item limits

Item Maximummodel terms 30

Linear Mixed Effects ModelingLinMix 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 10sort keys 16dependent variables 128covariate/regressor variables 255variables in the data set 256random and repeated statements 10variables 256contrast statements 100estimate statements 100combined length of all variance parameter names (total characters) 10,000combined length of all level names (total characters) 10,000levels per variable 1,000path and file name (total characters) 256number of records passed from WinNonlin to other programs 65,535characters per data cell 128column name length (characters) 128titles (e.g., output title or chart title) 5 lines

Table 15-10. LinMix item limits (continued)

Item Maximum


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 musthave been declared as a regressor/covariate before it can be usedas 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.


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.


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 contextb = dimension parameter: for some variance structures, the num-ber of bands; for others, the number of factors1(expression) = 1 if expression is true, 0 otherwise

Table 15-11. Variance structure types

Description Number of Parameters ith, jth elementVariance Components and i corresponds to

kth effectUnstructured

Banded Unstructured (b)

if ; otherwise, same as Unstructured.

Toeplitz

Banded Toeplitz if ; otherwise, same as Toeplitz

Compound Symmetry

Heterogeneous Compound Symmetry

No-DiagonalFactor Analytic

Banded No-Diagonal

Factor Analytic (b)

if ; otherwise,

same as No-Diagonal Factor Analytic

Autoregressive (1)

HeterogeneousAutoregressive (1)

n σk21 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× σ12 σ21 i j=( )+

n t 1+( )× σiσj ρ1 i j≠( ) 1 i j=( )+[ ]

n t t 1+( )× 2⁄

λikλjk

k 1=

min i j n, ,( )

∑

n b 2⁄× 2t b– 1+( )b t<

n 2× σ2ρ i j–

n t 1+( )× σiσjρi j–


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 fixed–effects specification and the random effects specification unless it is used differently—as 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.


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 fixed–effects 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

σ2I


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).


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 doesn’t 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 dialog—except 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 fixed–effects 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.


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 doesn’t 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.


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.


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 doesn’t 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 LSM’s 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.


e. The Compute Pairwise differences of LSM’s check box provides addi-tional output with the differences of confidence intervals and LSM’s. 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 ModelingLinMix 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 outputWhen 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


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 ContentsDiagnostics Model-fitting informationSequential Tests Tests of fixed effects, performed sequentiallyPartial Tests Tests of fixed effects, but each term is tested lastFinal 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 structureContrasts Hypothesis, df, F-statistic, and p-valueEstimates Estimate, standard error, t-statistic, pvalue, and confidence interval


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 settingsInitial 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


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.

Akaike’s Information Criterion (AIC)

The Linear Mixed Effects module uses the smaller-is-better form of Akaike’s Information Criterion:

AIC = –2LR + 2s

where LR 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(θ)).

Schwarz’s Bayesian Criterion (SBC)

The Linear Mixed Effects module uses the smaller-is-better form of Schwarz’s Bayesian Criterion:

where LR 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, ands is the rank of the fixed effects design matrix X plus the number of parameters in θ(i.e., s = rank(X) + dim(θ) ).

β θ

SBC 2LR– s N r–( )log+=

β θ


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

T00 = y0

where T00 and y0 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 Xβ= β

Var y( ) X XTVX( )1–XT=

iy

β

β

β


406

15

When there are multiple solutions, a convention is followed such that if any column of T00 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 modelRepeated if the parameter is from a repeated specificationAssumed if the variance parameter is the residual

Type Variance type specified by the user, or Identity, if the residual varianceBands Number of bands or factors if appropriate for the variance type

β

Linear Mixed Effects ModelingComputational 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) = ZGZT + 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 [R0 | 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 subjectGroup_Term Group term for this variance structure, if there was a groupGroup_Level Level of the group that this parameter goes with, if there was a group

R0T

R1T

R2T

X Z y[ ]T00 T01 y0

0 T11 yr

0 0 ye

=


408

15

REML estimation maximizes the likelihood of θ based on yr and ye of the reduced data matrix, and ignores y0. Since ye has a distribution that depends only on the residual variance, and since yr and ye 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(θ; yr, ye)) = log(L(θ; yr)) + log(L(θ; ye)) – (N–rank(X))/2 log(2π)

where:

log(L(θ; yr)) = –½ log (|Vr |) – ½ yr T Vr

–1 yr

log(L(θ; ye)) = –ne/2 log(θe) – ½ (yeTye / θe)

Vr = Variance(yr)

θe = residual variance

ne = residual degrees of freedom, and

N = number of observations used.

For some balanced problems, ye 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).

Newton’s Algorithm for maximization of restricted likelihood

As a general review, Newton’s 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),

ye1 ye2 … yen[ ]

L θ ye;( )( )log n2--- V 1–( )log 1

2--- yei

T V 1– yei

i 1=

n

∑–=


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 Newton’s 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(θ; yr)) – log(L(θ; ye))

Newton’s algorithm is modified by adding a diagonal matrix to the Hessian when determining the direction vector for Newton’s algorithm so that the diagonal matrix plus the Hessian matrix is positive definite, ensuring a direc-tion of descent:

θi+1 = θi – ( Hi + Di )–1 gi

The appropriate Di matrix is found by a modified Cholesky factorization as described in Gill, Murray, and Wright. Another modification to Newton’s algorithm is that, once the direction vector

d = – ( Hi + Di )–1 gi

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 Vr 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

Newton’s algorithm requires initial starting values for the variance parameter θ. If the user has some knowledge of these values, the user can supply these


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:

gT (θ) H–1(θ) g(θ) < ι,

where ι is the convergence criterion specified on the General Options page of the wizard. The default value is 1×10–10.

The possible convergence outcomes from Newton’s 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.


411

15

Satterthwaite’s 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 H0: 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 XTV 1– X( )

1–LT[ ]

1–Lβ( )

β V

Lβ( )2

L XTV 1– X( )1–LT

-------------------------------------- Lβ( )2


-------------------------------------- L XTV 1– X( )1–LT

L XTV 1– X( )1–L

--------------------------------------⁄=


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 ru 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 XTV 1– X( )1–L

-------------------------------------- χ2νν

---------∼

Var L XTV 1– X( )1–LT

L XTV 1– X( )1–L

-------------------------------------- 2ν---=

L XTV 1– X( )1–LT RΛRT=

W RTLβ( )TΛ 1– RTLβ( )

ruLβ( )2

λu-------------------

u 1=

q

∑= =

E W( )νu

νu 2–--------------

u 1–

q

∑=

Linear Mixed Effects ModelingComparing LinMix to ANOVA and SAS’s PROC MIXED

413

15

Comparing LinMix to ANOVA and SAS’s PROC MIXEDThis section outlines differences between LinMix and the WinNonlin ANOVA module (deprecated), and between LinMix and PROC MIXED from SAS®.

Feature LinMix ANOVA PROC MIXEDDegrees 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, LinMix’s –log(likelihood) may not be equal to twice SAS’s ‘–2 Res Log Like’ if the noprofile option is not set.

Akaike and Schwarz’s 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.


414

15

Conver-gence cri-teria

The convergence criterion in LinMix is gT H–1g < 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 SAS’s 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 [email protected].

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 ModelingComparing LinMix to ANOVA and SAS’s PROC MIXED

415

15

Singularity tolerance

Define dii as the i-th diagonal element of the QR factorization of X, and Dii 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 dii

2 < (singularity tolerance)×Dii. If intercept is present, the first row of Dii is omitted.

Define dii as the diagonal element of the XTX matrix during the sweeping process. If the absolute diagonal element |dii| < (singu-larity tolerance)×Dii, where Dii is the original diagonal of XTX, 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


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-


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.

BioequivalenceIntroduction 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 interchangeability—prescribability 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.


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 2×3 crossover design as described in the table below is a replicated crossover design.

BioequivalenceAverage 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 3Sequence 1 T R TSequence 2 R T R

Period 1 Period 2Sequence 1 T RSequence 2 R T


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.


• 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.


• 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.


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 = 10RefLSM

TestGeoLSM = 10TestLSM

Difference = TestLSM – RefLSM


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 × 10Difference

lower = Difference – t (1-alpha/2),df × DiffSEupper = Difference + t (1-alpha/2),df × DiffSE

CI_Lower = 100 × exp(lower)CI_Upper = 100 × exp(upper)

CI_Lower = 100 × 10lower

CI_Upper = 100 × 10upper


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+(TestLSM–RefLSM)/RefLSM–t (1-alpha/2),df *DiffSE/RefLSM)= 100×(TestLSM/RefLSM–t (1–alpha/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)


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 H0 at the 5% level, i.e. have less than a 5% chance of rejecting H0 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 ):


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 log10 or ln-transforms, the test will be symmetric on a logarithmic

H0: Difference < ln(1 – fractionToDetect) (bioinequivalence for left test)

H1: Difference ≥ ln(1 – fractionToDetect) (bioequivalence for left test)

t1 = ( (TestLSM – RefLSM) – ln(1 – fractionToDetect) ) / DiffSE

H0: Ratio < 1 – fractionToDetectH1: Ratio ≥ 1 – fractionToDetect

t1 = [ (TestLSM / RefLSM) – (1 – fractionToDetect) ] / RatioSE


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:


For log10-transform or data already log10-transformed, the second test is done similarly using log10 instead of ln.

For data with no transformation, the second 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-2×alpha) ×100% confidence interval for difference or ratio is within LowerBound and UpperBound, then both the H0’s given above for the two tests are also rejected at the alpha level by the two one-sided t-tests procedure.

H0: Difference > – ln(1 – fractionToDetect) (bioinequivalence for right test)

H1: Difference ≤ – ln(1 – fractionToDetect) (bioequivalence for right test)

t2 = ( (TestLSM – RefLSM) + ln(1 – fractionToDetect) ) / DiffSE

H0: Ratio > 1 + fractionToDetectH1: Ratio ≤ 1 + fractionToDetect

t2 = ( (TestLSM / RefLSM) – (1 + fractionToDetect) ) / RatioSE


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:

H01: µT - µR < θL vs. HA1: µT - µR > θL

H02: µT - µR > θU vs. HA2: µ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 tAH 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 H0 given that:

Power = 1 – (probability of a type II error) = probability of rejecting H0 when H1 is true.

H0: RefLSM = TestLSMH1: RefLSM ≠ TestLSM

|TestLSM – RefLSM | ≥ fractionToDetect × RefLSM

tAHYT YR– θL θU+( )– 2⁄

Diff SE-------------------------------------------------------=


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 H0 occurs in the case of equality, |TestLSM – RefLSM| = 0.2×RefLSM. So:

Let:

Then:

Note that tstat is T-distributed. Let p1 be the p-value associated with t1 (the area in the tail), and let p2 be the p-value associated with t2 (the area in the tail; note that p2 may be negligible). Then:

|TestLSM – RefLSM | ≥ – ln (1 – fractionToDetect),

Power = Pr (rejecting H0 at the alpha level given |Difference| = 0.2×RefLSM= Pr (|Difference/DiffSE | > t (1-alpha/2), df given |Difference| = 0.2×RefLSM= Pr (Difference/DiffSE > t (1-alpha/2),df given |Difference| = 0.2×RefLSM+ Pr (Difference/DiffSE < – t (1-alpha/2),df given |Difference| = 0.2×RefLSM

t1 = t (1-alpha/2),df – 0.2×RefLSM / DiffSEt2 = – t (1-alpha/2),df – 0.2×RefLSM / DiffSEtstat = (Difference – 0.2×RefLSM / DiffSE

Power = Pr(tstat > t1 given |Difference| = 0.2×RefLSM)+ Pr(tstat < t2 given |Difference| = 0.2×RefLSM)

Power = 1 – (p1 – p2)


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 FDA–proposed population bioequivalence (PBE) criteria are

if

Sequence Period Design2 4 TRTR/RTRT4 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/RRT2 3 RTR/TRT6 3 TRR/RTT/TRT/RTR/TTR/RRT2 4 TRRR/RTTT6 4 TTRR/RRTT/TRRT/RTTR/TRRR/RTTT

E YjT Yj'R–( )2 E YjR Yj'R–( )2–12---E YjR Yj'R–( )2

------------------------------------------------------------------------- θP< σR σP>

BioequivalenceIndividual and population bioequivalence

431

16

if

where σP defaults to 0.2 and θP = (ln(1 - PercentReference) + εP) /σP2. 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 FDA–proposed individual bioequivalence (IBE) criteria aref

where σI defaults to 0.2 and θI = (ln(1 – PercentReference) + εI) /σI2. 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 YjT Yj'R–( )2 E– YjR Yj'R–( )2

12---σP

2------------------------------------------------------------------------- θP< σR σP≤

ηP1 E µT µR–( )2 σT2 1 θP+( )σR

2–+ 0<= σR σP>

ηP2 E µT µR–( )2 σT2 σR

2 θP– σP2–+ 0<= σR σP≤

E YjT YjR–( )2 E YjR Yj'R–( )2–12---E YjR Yj'R–( )2

------------------------------------------------------------------------ θI< σWR σI>

E YjT YjR–( )2 E YjR Yj'R–( )2–12---σI

2------------------------------------------------------------------------ θI< σWR σI≤

ηI1 E µT µR–( )2 σD* σWT

2 1 θI+( )σWR2–+ + 0<=

σWR σI>

ηI2 E µT µR–( )2 σD* σWT

2 σWR2 θI– σI

2–+ + 0<=


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 Yijkt 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, ni > 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 Xi are design/model matrices.

Let piT:= sum( ) and piR:= 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˜ iT Z

˜ iR

Y˜ i j µ

˜ i

µ˜ i Z

˜ iTµT Z˜ iRµR+=

Z˜ iT Z

˜ iR

u˜ iT: piT

1– Z˜ iT=


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˜ iR: piR

1– Z˜ iR=

u˜ iI: u

˜ iT u˜ iR–( )=

d˜ i: sT

1– u˜ iT sR

1– u˜ iR–=

Y˜ i jkt Y

˜ ijk't'( , )

Σi σWT2diag Z

˜ iT( ) σWR2diag Z

˜ iR( ) σTTZ˜ iTZ'

˜ iT

σRRZ˜ iRZ'

˜ iR σTR Z˜ iTZ'

˜ iR Z˜ iRZ'

˜ iT+{ }+ +

+ +=

σ˜

σWT2 σWR

2 σTT σRR σTR,,,{ , }=

σT2 σTT σWT

2+= σR2 σRR σWR

2+= YijTt( )YijRt( )

ρTT σTT σT2⁄= YT YT'( , )

1 ρTT 0> >

ρRR σRR σR2⁄=

YR YR'( , ) 1 ρRR 0> >

ρTR σTR σTσR( )⁄= YT YR( , )1 ρTR 1–> >

σTT ρTTσT2= σRR ρRRσR

2= σTR ρTRσTσR=

σWT2 σT

2 σTT–= YT YT'–( ) 2⁄

σWR2 σR

2 σRR–= YR YR'–( ) 2⁄


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 FDA’s 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–+=

σiT*2 σT

2 1 piT1––( )σWT

2–( )=

σiR*2 σR

2 1 piR1––( )σWR

2–( )=

σiI*2 σD

* piT1– σWT

2 piR1– σWR

2+ +( )=

var YijT YijR–( ) σD* σWT

2 σWR2+ +=

σD* σD

2

σD* σD

2

∆ˆ

d'˜ iYi•

i∑=

SiT u'˜ iTViu˜ iT= SiR u'

˜ iRViu˜ iR= SiI u'˜ iIViu˜ iI=

SiWT 1 piT1––( )

1–tr diag u

˜ iT( )Vi{ } u'˜ iTViu˜ iT–( )=

SiWR 1 piR1––( )

1–tr diag u

˜ iR( )Vi{ } u'˜ iRViu˜ iR–( )=


435

16

where is the sample mean of the ith sequence, and Vi is the within-sequence sample covariance matrix.

It can be shown that

Furthermore, it can be shown that {SiT, SiR} (for PBE) are statistically inde-pendent from {∆} and {SiWT, SiWR}, and that the four statistics ∆, SiI, SiWT, SiWR (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)

,

,

,

,

,

Yi•

∆ˆ

N µT µR– ni1– d'

˜ i d˜ i

i∑

i∑( , )∼

SiT σiT*2 ni 1–( ) 1– χ2

ni 1–∼

SiR σiR*2 ni 1–( ) 1– χ2

ni 1–∼

SiI σiI*2 ni 1–( ) 1– χ2

ni 1–∼

SiWT σWT2 piT 1–( ) 1– ni 1–( ) 1– χ2

piT 1–( ) ni 1–( )∼

SiWR σWR2 piR 1–( ) 1– ni 1–( ) 1– χ2

piT 1–( ) ni 1–( )∼

E0 ∆ˆ 2

=

EP1 αiTSiTi∑=

EP2 1 αiTpiT1–

i∑–

αiWTSiWTi∑=

EP3 αiRSiRi∑=

EP4 1 αiRpiR1–

i∑–

αiWRSiWRi∑=


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 Howe’s approximation I and a mod-

ification proposed by Hyslop, Hsuan and Holder (2000). This can be gener-alized to compute the following sets of nq, H and U statistics:

,

,

,

,

EI1 αiISiIi∑=

EI2 1 αiIpiT1–

i∑–

αiWTSiWTi∑=

EI3a 1 θI αiIpiR1–

i∑+ +

αiWRSiWRi∑=

EI3b 1 αiIpiR1–

i∑+

αiWRSiWRi∑=

ηP1 ∆2ˆ EP1 EP2 1 θP+( )EP3 1 θP+( )EP4––+ +=

ηP2 ∆ˆ 2

EP1 EP2 EP3– EP4– θPσP2–+ +=

ηI1 ∆ˆ 2

EI1 EI2 EI3a–+ +=

ηI2 ∆ˆ 2

EI1 EI2 EI3b– θIσI2–+ +=

η

H0 ∆ˆ

t.95,n0varˆ ∆

ˆ( )( )

1 2⁄+

2

=

BioequivalenceBioequivalence Wizard

437

16

where the degrees of freedom nq are computed using Satterthwaite’s approxi-mation. Then, the 95% upper bound for each η is,

where for q = P3, P4, and = Uq for all other q. If Hq < 0, that indicates bioequivalence; Hq > 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

Hq nqEq χ.05,nq

2⁄=

Hq nqEq χ.95,2⁄ nq

=

Uq Hq Eq–( )2=

Hη η Uq*∑

1 2⁄+=

Uq* 1 θP+( )2Uq= Uq

*


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


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 musthave been declared as a regressor/covariate before it can be usedas a weight variable. It can also be used in the model.


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.


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 off—no random intercept.


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 fixed–effects 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.

σ2I


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).


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.

BioequivalenceBioequivalence 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 filesAny 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.


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 outputThe 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 ContentsAverage Bioequivalence Output from the bioequivalence analysisRatio Tests Ratios of reference to test mean computed for each subjectDiagnostics 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.

BioequivalenceBioequivalence 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 WinNonlinLeast Squares Means Sort Variable(s), Dependent Variable(s), Units, and the least

squares means for the test formulationLSM Differences Difference in least squares meansResiduals Sort Variable(s), Dependent Variable(s), Units, and information

on residual effects vs. predicted and observed effectsUser Settings User-specified settingsInitial 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 ContentsPopulation/Individual Bioequivalence

Output from the bioequivalence analysis

Ratio Tests Ratios of reference to test meanUser Settings User-specified settings

Table 16-1. Average bioequivalence output worksheets (continued)

Worksheet Contents


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 IndicationConst_Pop_eta Test statistic for population bioequivalence with constant scalingRef_Pop_eta Test statistic for population bioequivalence with reference scalingMixed_Pop_eta Test statistic for population bioequivalence with mixed scalingConst_Indiv_eta Test statistic for individual bioequivalence with constant scaling

BioequivalenceBioequivalence 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 Xi 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 scalingMixed_Indiv_eta Test statistic for individual bioequivalence with mixed scaling

Table 16-3. Population/Individual Bioequivalence Calculations

Statistic Indication

test Xi( )ln N⁄i∑

exp=

test 10

N 1– log10Xi

i∑

=


450

16

Difference = exp(test) – exp(ref).Ratio(%Ref) = 100×exp(test – ref) = 100×exp(test)/exp(ref)

Similarly, for data that was specified to be ‘already log10-transformed’:

Difference = 10test – 10ref

Ratio(%Ref) = 100×10test – ref = 100×10test/10ref

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 dataFor 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 responsesSimulation 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 modelThis 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.


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.

SimulationSimulation 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.


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.


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


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.5K21: 1

Dosing Constant ValueNumber of doses 2Dose #1 150Time of dose #1 0Dose #2 150Time of dose #2 24


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.


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

SimulationComparing dosing schemes

459

17

Comparing dosing schemesSimulations 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:


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 Administrations’s 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 Server’s documentation. See also “Scripting the Pharsight Knowledgebase Server” on page 512 and “Automating Pharsight Knowledgebase Server functions” on page 545.

The PKS information structureWinNonlin 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


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 data—time-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 1st, 2nd and 3rd 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 ServerPKS 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 sessionsThe 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 WinNonlinAccess to the Pharsight Knowledgebase Server occurs via the PKS menu in WinNonlin Enterprise. The menu items include:


464

18

Note: A system administrator should set up and configure the PKS connection. See the documentation set for the PKS for information.

DosingDosing 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 ServerConnecting 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...


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 Administrator’s Guide for details).

Using the Pharsight Knowledgebase ServerCreating a study or scenario

467

18

Creating a study or scenarioStudies 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 needn’t 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.


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.


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.


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 Administrator’s 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


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.


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.”


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 attribute’s) 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 administrator’s 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.


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 ServerLoading 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.


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 ServerCreating 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 scenariosScenarios 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.


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 ServerAdding non-WinNonlin documents to a scenario

479

18

Adding non-WinNonlin documents to a scenarioNon-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.


480

18

Optimizing PKS/WNL performanceA 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-only–allowing the user to analyze them in WinNonlin but not change data values in the source data–the 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 ServerOptimizing 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).


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 informationIf 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 client’s audit trail.

Using the Pharsight Knowledgebase ServerDosing 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 informationDose 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.


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 ServerAppending or updating a study

485

18

Appending or updating a studyAfter 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 units—then 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.


486

18

WinNonlin and PKS differencesWinNonlin 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 won’t 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 ServerWinNonlin 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.


488

18

489

Chapter 19

Scripting

Automating analyses through WinNonlin’s 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.

TerminologyObject-oriented programming terms used in WinNonlin scripting follow.


490

19

Writing and editing a scriptThis 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 type—a .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, ANOVAa, 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.

ScriptingWriting 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).orClick 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.


492

19

Executing a scriptOnce 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.orClick on the script file name and click Open. The script file executes and the output appears in a WinNonlin output window.

ScriptingScripting 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 methodsThis 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.


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 SaveCascade MsgBox TileHorizontalCloseAll PrintAll TileVerticalDeleteFiles PrintData UnloadExportAll PrintGraph WorkingDirFileMask PrintModel WindowStateHalt PrintText

Table 19-3. Data object properties and methods

Append FileType RenameColAppendFilename Find ReplaceAppendFileType Font SaveAppendSheet FontSize SearchAreaAutoFileOptions Headers SortCaseSensitive Include SortVar( )Column Load SortVarsConseqDelim Missing StartColCopy MultiGrid StartRowCut Operation TabDelimiter Paste ToleranceEndCol Print UnloadEndRow Remove UnitExclude RemoveCol WindowStateFilename RemoveRow With


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 WindowStateFileType SaveLoad Unload

Table 19-5. Model object properties and methods

DoseUnit LinkFile PrintFilename Load SaveFileType ParmFile UnloadLamzFile PartFile WindowState

Table 19-6. Graph object properties and methods

Filename MultiGraph UnloadFileType Print WindowStateFootnoteFont PrintMulti XLabelsFontFootnoteFontSize PrintMultiAcross XLabelsFontSizeLegendFont PrintMultiDown XTitleFontLegendFontSize Save XTitleFontSizeLoad SaveAll XUnitsLoadTemplate SaveAllPrefix YLabelsFontMoveFirst SaveTemplate YLabelsFontSizeMoveLast SortLevel YTitleFontMoveNext TitleFont YTitleFontSizeMovePrevious TitleFontSize YUnits

Uniform


496

19

Table 19-7. PK engine properties and methods

OutData OutText RunWordExportOutGraph Run WordExportFilename

Table 19-8. Descriptive statistics engine properties and methods

Confidence OutData SortVarsInData Percentiles SummaryVar( )Interval Run SummaryVars

SortVar( ) Weight

Table 19-9. ANOVA engine properties and methodsa

a. The former ANOVA functions are now handled by the Linear Mixed Ef-fects Modeling engine. Scripts using the ANOVA engine will continue to work, but it is best that new scripts use the LinMix engine.

Filename OutData RunFileType OutText

Table 19-10. Plot engine properties and methods

AutoSort OutGraph UpErr( )DnErr( ) Run XTitleErrType SameErrCol( ) XUnitsGroupVar( , ) ShowUnits XVar( )GroupVars( ) SortVar( , ) YTitleInData( ) SortVars( ) YUnitsLegend( ) Title YVarNumData


497

19

Table 19-11. Table engine properties and methods

AggregateVar IDVars OutDataCrossVar( ) InData( ) PageFooterCrossVars JoinCrossVar( , ) PageHeaderDefinitionFile JoinCrossVars RegVar( )Filename JoinGroupVar( , ) RegVarsGroupVar( ) JoinGroupVars RunGroupVarBreak( ) JoinIDVar( , ) StatsGroupVars JoinIDVars TableNumIDVar( ) NumData

Table 19-12. Transform engine properties and methods

DestArea Function SourceColDestCol InDataExtra Run

Table 19-13. Merge engine properties and methods

CarryData InData( ) RunIncludeVar( , ) NumDataa

a. Must be equal to 2.

SortVar( , )

IncludeVars( ) OutData SortVars

Table 19-14. LinMix and Bioequivalence engine properties and methods

Filename OutData RunFileType OutText


498

19

Script file componentsWhile some operations are specified in Script files completely through the use of the scripting language commands described in this chapter, other, more

Table 19-15. Toolbox engine properties and methodsa

a. The set of properties available to the Toolbox engine depends on the value assigned to the Function property. Function can be assigned one of four values (above) to select the analysis tool. Valid properties are listed for each Function property assignment.

Toolbox.function assignments Applicable properties and methodsToolbox.Function=Crossover InData

OutDataRunResponseSortVar( )

SortVarsShowUnitsSubjectTreatmentATreatmentBStacked

Toolbox.Function=Semicompartmental ConcColEcolInDataKeoOutData

OutGraphRunSortVar( )SortVarsTimeCol

Toolbox.Function=Superposition ConcColDoseUnitInDataInitialDoseMaintenanceDoseNpointsOutDataOutGraph

RunSortVar( )SortVarsTauTerminalLowerTerminalPhaseTerminalUpperTimeColTimeRepeat

Toolbox.Function=Deconvolution AlphaTerms()Aterms()BolusConcColDoseUnitDeltaInputLag

NpointsNumTermsRunSmoothingSortVar( )SortVarsTimeCol

ScriptingScript file components

499

19

complex, operations are specified via files that are prepared in advance. This section describes how each engine is implemented in the scripting language.

Table 19-16. Script file operations and methods of implementation

Engine Method of implementation

Charts Charts are specified in scripts via scripting language commands.

Tables Tables may be specified in Script files in two different ways: through the use of scripting lan-guage commands, or using a table definition file (.TDF).Scripting language commands can specify:The Input data set(s)Table template numberVariable mappingsSummary Statistics (all or none)Page Break optionsUsing only the Scripting Language commands some flexibility is lost. Summary statistics can be included, but it is not possible to select a subset. Also, default formatting is used; the font, alignment, page numbers, etc., cannot be set unless a table definition file is used.A table definition file contains all of the information needed to create the table except the input data set(s) to be used. A script can call any existing table definition file to set up the table structure and formatting. For more information on table definition files, see “Chart tem-plates” on page 182

Compartmental Models

Compartmental models are specified in scripts via Command files (.CMD) or Pharsight Model Objects (.PMO). To use Command files with different levels of input for model parame-ters, etc., for each sort level, see “Special file formats” on page 502.Note that although a workbook will be loaded and used for the modeling as a result of either the Command file or Pharsight Model Object, that data file will not be available for any other processing. To use that data set for any other purpose within the script, it will be necessary to load it separately.

Noncompartmental Analysisa

Noncompartmental models are specified in scripts via Command files (.CMD) or Pharsight Model Objects (.PMO). To use Command files with different levels of input for Lambda z ranges, etc., for each sort level, see “Special file formats” on page 502 Note that although a workbook will be loaded and used for the modeling as a result of either the Command file or Pharsight Model Object, that data file will not be available for any other processing because it will not have an alias assigned to it. To use that data set for any other purpose within the script, it will be necessary to load it separately.

ANOVA Analysis of Variance, Analysis of Covariance, and Linear Regression models are all specified in Scripts via ANOVA command files (.ANV).Note that although a data grid will be loaded and used for the modeling as a result of loading the ANOVA command file (.ANV), that data file is not available for any other processing because it does not have an alias assigned to it. To use that data set for any other purpose within the script, it will be necessary to load it separately.


500

19

Note on saving files

CAUTION: When saving files with the Scripting Language, WinNonlin does not check to see if that file name already exists. It is possible to overwrite existing files in this way.

LinMIx Linear mixed effects modeling, including analysis of variance, analysis of covariance, and lin-ear regression can all be specified in scripts using a linear mixed effects command file (.LML).

Bioequivalence Bioequivalence analysis, including average, population, and individual bioequivalence mod-els, can be specified in scripts using a bioequivalence command file (.LML).

Descriptive statistics

Descriptive Statistics are specified in Scripts via scripting language commands which address the descriptive statistics engine. The user specifies which columns are summary variables and a new output data grid is generated.

Transformations Data transformations are specified in Scripts via scripting language commands which access properties and methods of the transform engine.

Merging data sets

The merging of data sets are specified in Scripts via scripting language commands which use the merge engine properties and methods. Any combination of data from two data sets can be merged and saved as one data set.

Scripting PKS Access to data in the Pharsight Knowledgebase Server (PKS) is possible using scripting in WinNonlin. Scripting the PKS is done by adding an additional FileType property to the Win-Nonlin Data Object. The Load and Save operations on this Data Object then rely on a PKS file pointed to by the Data Object. The PKS file is the same format as the files generated by the Study Definition and Study Mappings dialogs used in the creation of a study in the PKS. The file format is XML and is defined by an embedded DTD.

a. When writing scripts that will use the NCA Data output, it is important to be aware of the form in which this output will appear. The NCA Data output can appear with the variables (columns) Parameter and Estimate (in addition to the sort and carry-along variables), or, with a separate variable for each of the Final Parameters in the transposed output.

The Final Parameters worksheet will be transposed if NCATRANS is included in the NCA specification or if the user has set up “transposed output” as the WinNonlin default. Both transposed and non-transposed worksheets are always produced; this option simply deter-mines which format will appear in the worksheet entitled Final Parameters. See “Transpose final parameter table” on page 262.

Table 19-16. Script file operations and methods of implementation (continued)

Engine Method of implementation

ScriptingProcessing multiple profiles in script files

501

19

Processing multiple profiles in script filesTwo options are available to process compartmental models and noncompart-mental analyses in the Scripting Language:

• Loading a Pharsight model object (.PMO)

• Loading a Command file (.CMD)

When using a Pharsight model object, different values may be used for dos-ing, parameter values, partial areas or lambda_z range for each sort level auto-matically. Command files, however, store only one set of values to be used for all sort levels.

It is possible, however, to load a command file, then load ASCII files which contain this information uniquely for each sort level. These ASCII files can be created and saved within WinNonlin or a text editor.

The information contained in the files specified by these properties is expected to be in a very specific format. The next section discusses the ASCII file formats that are expected when using the following methods with Model Objects.

– .LAMZFILE for specifying lambda_z range information– .DOSEFILE for specifying dosing information– .PARMFILE for specifying parameter values– .LINKFILE for specifying PK/PD models that require two sets of

parameter values– .PARTFILE for specifying partial area information

The following example script files shows how a command file could be loaded, and the methods used.

Set MYMODEL = Model

MYMODEL.Filetype="ASCII”

MYMODEL.File Name=”C:\WINNONLN\EXAMPLES\PRO-FILES.CMD”

MYMODEL.Load

MYMODEL.Dosefile=”C:\WINNONLN\EXAM-PLES\DOSEINFO.DAT”


502

19

MYMODEL.PartFile=”C:\WINNONLN\EXAM-PLES\PARTINFO.DAT”

Pk.OutData=”MYOUTDATA”

REMA Text and graphics output objects may also be named at this time

Pk.Run

Special file formats

This section discusses the required ASCII file formats when using the follow-ing methods with Model Objects.

.LAMZFILE for lambda_z range information (start and end times for computa-tion of lambda z in noncompartmental analysis)

.DOSEFILE for dosing information

.PARMFILE for initial parameter values and bounds (optional)

.LINKFILE for PK/PD models that require two sets of parameter values

.PARTFILE for partial area information (start and end times for computation of partial areas under the curve)

The general structure for all of the ASCII files is given, followed by annotated examples for each type of file. These files may be created and saved from within WinNonlin, or using a text editor.

General structure

Order in file Contents Comments1st “CheckSum or

Identifier”Must be included on the first line of file.

2nd nType nType is between 1 to 5 as follows:1 lamdbaz range information2 dosing information3 model parameter values4 link parameter values5 partial areas


503

19

Note: When ntype = 1 or 5, nRow = nProfiles (no. of profiles). When ntype = 2 or 3 or 4, nRow = NCON (no. of constants) or NPAR (no. of parameters).

Lambda z range information (nType=1)

Data Grid with Lambda z Range Information for three profiles. Model used: NCA Model 200.

ASCII File with Lambda_z Range information of the above three profiles.

3rd nProfiles nProfiles is a value < 32767 that indicates how many pro-files or subsets of values are included.

4th nRows, nCols nRows & nCols are integers that indicate how many rows and columns of data are in the file.

5th-(nColns+4)t

h record

n, Char For each column, these values indicate the number of dec-imal places and data type (“A” or “N”) of the data, respec-tively.

Remaining records

Data values of each profile

Data values of column 1, 2, 3, etc. Set(s) of values for each nRow.

Order in file Contents Comments

Subject Start time End time Exclusions1 3 18 4 52 3 18 33 3 18

Table 19-17. Lambda z file structure

Record Contents Comments

1st CheckSum or Identifier

Required

2nd 1 nType = 1, as 1 represents lambda_z range information.

3rd 3 nProfiles = 3, as the number of profiles (Subjects) used is 3.


504

19

Note: Values that are in the excluded part of the data grid but are not valid exclu-sions have a value of 0. This does place the restriction that Time=0 may not be an excluded data point.

Dosing information (nType = 2)

Data Grid with Dosing Information for three profiles. Model used: NCA Model 200.

4th 3, 4 When nType is 1, the number of rows equals nProfiles (the number of profiles), so nRows = 3. When nType is 1, the number of col-umns equals 2 + the maximum number of exclusions, so nCols = 4.

5th 4, N n = 4, as the number of decimal places, if any, is 4. Char = N as the data type is numeric for the 1st column.

6th 4, N n = 4, as the number of decimal places, if any, is 4. Char = N as the data type is numeric for the 2nd column.

7th 4, N n = 4, as the number of decimal places, if any, is 4. Char = N as the data type is numeric for the 3rd column.

8th 3 Numeric data in the 1st column (Start Time), 1st profile.

9th 18 Numeric data in the 2nd column (EndTime), 1st profile.

10th 4 Numeric data in the 3rd column (Exclusions), 1st profile.

11th 5 Numeric data in the 4th column (Exclusions), 1st profile.

12th 3 Numeric data in the 1st column (Start Time), 2nd profile.

13th 18 Numeric data in the 2nd column (EndTime), 2nd profile.

14th 3 Numeric data in the 3rd column (Exclusions), 2nd profile.

15th 0 Invalid exclusions in the 4th column, 2nd profile. (See Note below).

16th 3 Numeric data in the 1st column (Start Time), 3rd profile.

17th 18 Numeric data in the 2nd column (EndTime), 3rd profile.

18th -1e150 Invalid exclusions in the 3rd column, 3rd profile. (See Note below).

19th 0 Invalid exclusions in the 4th column, 3rd profile. (See Note below).

Table 19-17. Lambda z file structure (continued)



505

19

ASCII File with dosing information of the above three profiles.

Subject Constant Value1 Dose 1001 Time of Last Dose 02 Dose 1002 Time of Last Dose 03 Dose 1003 Time of Last Dose 0

Table 19-18. Dosing file structure



Was not used before WinNonlin version 3.2. Can be used to save dosing units. See note belowa.

2nd 2 nType = 2, as 2 represents dosing information.


4th 3, 1 When nType is 2, the number of rows equals NCON (the number of constants), so nRows = 3. When nType is 2, the number of col-umns equals 1, so nCols = 1. (See Note below on nRows).

5th 4, N n = 4, as the number of decimal places, if any, is 4. Char = N as the data type is numeric for the column.

6th 100 Numeric data in the 1st column (Value), 1st profile.

7th 0 Null data in the 2nd column, 1st profile.

8th 0 Null data in the 3rd column, 1st profile.

9th 100 Numeric data in the 1st column (Value), 2nd profile.

10th 0 Null data in the 2nd column, 2nd profile.

11th 0 Null data in the 3rd column, 2nd profile.

12th 100 Numeric data in the 1st column (Value), 3rd profile.

13th 0 Null data in the 2nd column, 3rd profile.

14th 0 Null data in the 3rd column, 3rd profile.


506

19

Note: When using the Model.DoseFile method with NCA models, nRows is equal to NCON+1 in order to accommodate the Time of Last Dose values. When steady state is being calculated, nRows is equal to NCON+2 to accommodate the Tau values. If steady state is not being calculated, these values should be set to 0.

Model parameter values (nType = 3)

Data grid with parameter values on two profiles. Model used: PK Model 3

ASCII File with parameter values of the above two profiles.

a. It is possible to save dosing units and dose normalization information to ASCII *.DAT files. To do so, the format for the first line becomes V32, sdoseunit, sdosenormalization. The commas must be includ-ed, even without the units [hence it could be V32,, ].

Subject Parameter Initial value Lower Upper1 Volume_F 0.2 0 01 K01 20 0 01 K10 2 0 02 Volume_F 0.15 0 02 K01 33 0 02 K10 1.5 0 0

Table 19-19. Model parameter file structure



Unused

2nd 3 nType = 3, as 3 represents parameter values.


4th 3, 3 When nType is 3, the number of rows equals NPAR (the number of parameters), so nRows = 3. When nType is 3, the number of col-umns equals 3, so nCols = 3. (See Note below on nCol).


507

19

5th 4, N n = 4, as the number of decimal places, if any, is 4. Char = N as the data type is numeric for the 1st column (Initial Value).

6th 4, N n = 4, as the number of decimal places, if any, is 4. Char = N as the data type is numeric for the 2nd column (Lower Limit).

7th 4, N n = 4, as the number of decimal places, if any, is 4. Char = N as the data type is numeric for the 3rd column (Upper Limit).

8th 0.2 Numeric data of the Volume/F parameter in the 1st column (Initial Value), 1st profile.

9th 0 Null data of the Volume/F parameter in the 2nd column (Lower Limit), 1st profile.

10th 0 Null data of the Volume/F parameter in the 3rd column (Upper Limit), 1st profile.

11th 20 Numeric data of the K01 parameter in the 1st column, 1st profile.

12th 0 Null data of the K01 parameter in the 2nd column, 1st profile.

13th 0 Null data of the K01 parameter in the 3rd column, 1st profile.

14th 2 Numeric data of the K10 parameter in the 1st column, 1st profile.

15th 0 Null data of the K10 parameter in the 2nd column, 1st profile.

16th 0 Null data of the K10 parameter in the 3rd column, 1st profile.

17th .15 Numeric data of the Volume/F parameter in the 1st column (Initial Value), 2nd profile.

18th 0 Null data of the Volume/F parameter in the 2nd column (Lower Limit), 2nd profile.

19th 0 Null data of the Volume/F parameter in the 3rd column (Upper Limit), 2nd profile.

20th 33 Numeric data of the K01 parameter in the 1st column (Initial Value), 2nd profile.

21st 0 Null data of the K01 parameter in the 2nd column (Lower Limit), 2nd profile.

22nd 0 Null data of the K01 parameter in the 3rd column (Upper Limit), 2nd profile.

23rd 1.5 Numeric data of the K10 parameter in the 1st column (Initial Value), 2nd profile.

Table 19-19. Model parameter file structure (continued)



508

19

Note: The three columns: nCol1 = Initial Value, nCol2 = Lower Limit, nCol3 = Upper Limit, are not always used, but must still be part of the file.

Link parameter values (nType = 4)

Since a PK/PD model actually requires two sets of parameter values, the Linkfile is included.

Data grids with link parameter values on two profiles. Models used: PK Model 3/PD Model 105

The following data grid is applied to the PK Model:


24th 0 Null data of the K10 parameter in the 2nd column (Lower Limit), 2nd profile.

25th 0 Null data of the K10 parameter in the 3rd column (Upper Limit), 2nd profile.

Table 19-19. Model parameter file structure (continued)


Subject Parameter Initial Value Lower Upper1 Volume_F 0.2 0 01 K01 20 0 01 K10 2 0 02 Volume_F 0.15 0 02 K01 33 0 02 K10 1.5 0 0

Table 19-20. Link PK parameter values



Was not used before WinNonlin version 3.2. Can be used to save PK concentration units. See note belowa.

2nd 4 nType = 4, as 4 represents Link parameter values.


509

19

The remainder of the file structure is the same as the file shown in Example 3.

The following data grid is applied to the PD Model:



4th 3, 3 When nType is 4, the number of rows equals NPAR (the number of parameters), so nRows = 3. When nType is 4, the number of columns equals 3, so nCols = 3. (See Note below on nCol).




8th 0.2 Numeric data of the Volume/F parameter in the 1st column (Ini-tial Value), 1st profile.

9th 0 Null data of the Volume/F parameter in the 2nd column (Lower Limit), 1st profile.

10th 0 Null data of the Volume/F parameter in the 3rd column (Upper Limit), 1st profile.

a. It is possible to save PK concentration units for the PK tab of PK/PD mod-els to ASCII .DAT files. To do so, the format for the first line becomes V32,PKconcentrationunit. The comma must be included, even without the units (hence it could be V32,).

Subject Parameter Initial value Lower Upper1 Emax 5 0 01 Ece50 6 0 01 Gamma 7 0 02 Emax 1 0 02 Ece50 2 0 02 Gamma 3 0 0

Table 19-20. Link PK parameter values (continued)



510

19

Table 19-21. PD parameter values



Unused

2nd 4 nType = 4, as 4 represents Link parameter values.


4th 3, 3 When nType is 4, the number of rows equals NPAR (the number of parameters), so nRows = 3. When nType is 4, the number of col-umns equals 3, so nCols = 3. (See Note below on nCol.)




8th 5 Numeric data, Emax parameter in the 1st column (Initial Value), 1st profile.

9th 0 Null data, Emax parameter in the 2nd column (Lower Limit), 1st profile.

10th 0 Null data, Emax parameter in the 3rd column (Upper Limit), 1st profile.

11th 6 Numeric data, Ece50 parameter in the 1st column, 1st profile.

12th 0 Null data, Ece50 parameter in the 2nd column, 1st profile.

13th 0 Null data, Ece50 parameter in the 3rd column, 1st profile.

14th 7 Numeric data, Gamma parameter in the 1st column, 1st profile.

15th 0 Null data, Gamma parameter in the 2nd column, 1st profile.

16th 0 Null data, Gamma parameter in the 3rd column, 1st profile.

17th 1 Numeric data, Emax parameter in the 1st column (Initial Value), 2nd profile.

18th 0 Null data, Emax parameter in the 2nd column (Lower Limit), 2nd profile.

19th 0 Null data, Emax parameter in the 3rd column(Upper Limit), 2nd profile.


511

19

Note: The three columns: nCol1 = Initial Value, nCol2 = Lower Limit, nCol3 = Upper Limit, are not always used, but must still be part of the file.

Partial areas (nType = 5)

Data grid with partial area information for three profiles. Model used: NCA Model 200

ASCII File with partial areas information of the above three profiles.

20th 2 Numeric data, Ece50 parameter in the 1st column, 2nd profile.

21st 0 Null data, Ece50 parameter in the 2nd column, 2nd profile.

22nd 0 Null data, Ece50 parameter in the 3rd column, 2nd profile.

23rd 3 Numeric data, Gamma parameter in the 1st column, 2nd profile.

24th 0 Null data, Gamma parameter in the 2nd column, 2nd profile.

25th 0 Null data, Gamma parameter in the 3rd column, 2nd profile.

Table 19-21. PD parameter values (continued)


Subject Min Time Max Time AUC1 Lower AUC1 Upper1 .25 48 5 62 .25 48 8 123 .25 48 2 3

Table 19-22. Partial areas file format



Unused

2nd 5 nType = 5, as 5 represents Partial Areas.



512

19

Note: Values that are in the partial area portion of the data grid, but are not valid par-tial areas, should be given lower and upper values of 0.

Scripting the Pharsight Knowledgebase ServerThe Pharsight Knowledgebase Server (PKS), and the files stored as studies and scenarios in it, can be accessed by scripting from WinNonlin. Scripting the PKS is done by adding an additional FileType property to the Data Object. The Load and Save operations on this Data Object will rely on a PKS file pointed to by the Data Object. This PKS file is the same format as the files generated by the Study Definition and Study Mappings dialogs used in the creation of a study in the PKS. The file format is XML and is defined by an embedded DTD. See “PKS file format” on page 513 for details.

The workflow rules associated with the manipulation of PKS data via Script-ing can be encapsulated based on the method being invoked (i.e. Load or Save).

4th 3, 2 When nType is 5, the number of rows equals nProfiles, so nRows = 3. When nType is 5, the number of columns equals the maxi-mum number of partial areas multiplied by 2, so nCols = 2.

5th 4, N n = 4, as the number of decimal places, if any, is 4. Char = N as the data type is numeric for the 1st column (AUC1 Lower).

6th 4, N n = 4, as the number of decimal places, if any, is 4. Char = N as the data type is numeric for the 2nd column (AUC1 Upper).

7th 5 Numeric data of the column AUC1 Lower of the 1st profile.

8th 6 Numeric data of the column AUC1 Upper of the 1st profile.

9th 8 Numeric data of the column AUC1 Lower of the 2nd profile.

10th 12 Numeric data of the column AUC1 Upper of the 2nd profile.

11th 2 Numeric data of the column AUC1 Lower of the 3rd profile.

12th 3 Numeric data of the column AUC1 Upper of the 3rd profile.

Table 19-22. Partial areas file format (continued)


ScriptingScripting the Pharsight Knowledgebase Server

513

19

Load

Note: Rules follow the user interface.

1. If the PKS file pointed to by the Data Object has only a study name, then only a study will be loaded.

2. If the PKS file pointed to by the Data Object has a study name and a sce-nario name, then both the study and latest version of the scenario will be loaded. Scripting will not load previous versions of a scenario.

Save

Note: A more involved set of rules based on the state of the application.

1. If no PKS session has been created (i.e. no connection has been made to the PKS), then the Save Method will create a study in the PKS based on the information in the PKS file pointed to by the File Name Property of the Data Object.

2. If a PKS session has been created via loading a study only and no other Objects (i.e. charts, texts, workbooks) are present in WinNonlin, then the Save Method will update the Study only.

3. If a PKS session has been created via loading a study and scenario or a study only and other Objects (i.e. charts, texts, workbooks) are present in WinNonlin, then the Save Method will update the Study (if it changed) and Save the scenario to a new version or an entirely new scenario. A new version will be created if and only if the scenario name being saved is the same as the scenario that was loaded.

PKS file format

The PKS file contains XML that describes load and/or save operations to and/or from the PKS. It is saved as an XML file with the following format.

<?xml version="1.0"?><!DOCTYPE PWRImport[<!ELEMENT PWRImport (StudyInformation?, Scenario? ,Mappings?)>


514

19

<!ATTLIST PWRImport UserID CDATA #IMPLIED Password CDATA #IMPLIED Server CDATA #IMPLIED Port CDATA #IMPLIED Root CDATA #IMPLIED>

<!ELEMENT StudyInformation EMPTY><!ATTLIST StudyInformation BlindingType CDATA #IMPLIED Compound CDATA #IMPLIED Description CDATA #IMPLIED Design CDATA #IMPLIED EndTime CDATA #IMPLIED Indication CDATA #IMPLIED Name CDATA #IMPLIED Portfolio CDATA #IMPLIED Project CDATA #IMPLIED StartTime CDATA #IMPLIED State CDATA #IMPLIED Type CDATA #IMPLIED Reason CDATA #IMPLIED>

<!ELEMENT Scenario EMPTY><!ATTLIST Scenario Name CDATA #IMPLIED Reason CDATA #IMPLIED GetLatest (TRUE|FALSE) #IMPLIED>

<!ELEMENT Mappings (Sources?, Mapping*)><!ATTLIST Mappings Type (SAMPLE|DOSE|BOTH) #IMPLIED>

<!ELEMENT Sources EMPTY><!ATTLIST Sources


515

19

Observation CDATA #IMPLIED Dose CDATA #IMPLIED Demographics CDATA #IMPLIED>

<!ELEMENT Mapping (FromFields*, FieldOption*)><!ATTLIST Mapping FromField CDATA #IMPLIED ToField CDATA #IMPLIED FieldType (Subject_ID|Subject_Data|Observa-tion|DCP_Description|Actual_Clock_Time|Relative_Nominal_Time|Sample_Number|Relative_Actual_Time|Relative_Actual_End_Time|Treatment|Period|Phase|Undefined|Dose) #IMPLIED TreatAsDCP (TRUE|FALSE) #IMPLIED>

<!ELEMENT FromFields EMPTY><!ATTLIST FromFields Name CDATA #IMPLIED>

<!ELEMENT FieldOption EMPTY><!ATTLIST FieldOption OptionName (Unit|Sample_Description|Sample_Matrix|Analytical_Method|Status|LLOQ|ULOQ) #IMPLIED IsColumn (TRUE|FALSE) #IMPLIED Value CDATA #IMPLIED>

]>


516

19

Example PKS scripts

Creating a study

In this example a study is created from a file. It could also have been created from a Watson LIMS system via the WinNonlin enterprise ODBC interface (i.e. WinNonlin loads data from an external system via an ODBC connection or Custom Query Builder, then executes the last four lines of the script on the Data Object created by importing the data).

Script file

Set MYRAWDAT1=Data MYRAWDAT1.Filename="bg1.pwo"MYRAWDAT1.FileType="PWO"MYRAWDAT1.LoadMYRAWDAT1.Filename="CreateStudy.pks"MYRAWDAT1.FileType="PKS"MYRAWDAT1.Save


517

19

Updating a study

This example refreshes a study with the latest information from the PKS.

Step 1: The study is loaded from the PKS into WinNonlin.

Step 2: The new data is loaded into another worksheet (in the script it is a file, but it could have come from an ODBC import).

CREATESTUDY.PKS

…<PWRImport UserID="***" Password="***" Server="server.com" Port="8080" Root="pks"><StudyInformation Name="bg1" StartTime="1/1/2000" State="Normal" Compound="Drug 1" Design="N/A" Type="N/A" BlindingType="N/A" Indication="NA" Project="NA" Portfolio="Script-ing Test" Description="Script creation of a study" EndTime="2/2/2001"/><Mappings Type="SAMPLE"><Mapping FromField="Subject" ToField="SUBJECT" FieldType="Subject_ID" TreatAs-DCP="FALSE"><FieldOption IsColumn="FALSE" Value="" OptionName="Unit"/><FieldOption IsColumn="FALSE" Value="" OptionName="Status"/><FieldOption IsColumn="FALSE" Value="" OptionName="Analytical_Method"/><FieldOption IsColumn="FALSE" Value="" OptionName="Sample_Matrix"/><FieldOption IsColumn="FALSE" Value="" OptionName="Sample_Description"/></Mapping><Mapping FromField="Time" ToField="Relative Actual Time" FieldType="Relative_Actual_Time" TreatAsDCP="FALSE"><FieldOption IsColumn="FALSE" Value="hr" OptionName="Unit"/><FieldOption IsColumn="FALSE" Value="" OptionName="Status"/><FieldOption IsColumn="FALSE" Value="" OptionName="Analytical_Method"/><FieldOption IsColumn="FALSE" Value="" OptionName="Sample_Matrix"/><FieldOption IsColumn="FALSE" Value="" OptionName="Sample_Description"/></Mapping><Mapping FromField="Conc" ToField="concentration" FieldType="Observation" TreatAs-DCP="FALSE"><FieldOption IsColumn="FALSE" Value="ug/mL" OptionName="Unit"/><FieldOption IsColumn="FALSE" Value="" OptionName="Status"/><FieldOption IsColumn="FALSE" Value="" OptionName="Analytical_Method"/><FieldOption IsColumn="FALSE" Value="" OptionName="Sample_Matrix"/><FieldOption IsColumn="FALSE" Value="" OptionName="Sample_Description"/></Mapping></Mappings></PWRImport>…


518

19

Step 3: The worksheet containing the Study data is overwritten by the new data via a copy/paste operation.

Step 4: The study is then saved, at which point WinNonlin determines what has changed, applies the reason for change in the PKS file, and saves the change information to the PKS (i.e. observation updates, deletions, additions).

Note the reason for change in the LOADSTUDY.PKS file, below.

Script file

Rema Step1: Load studySet MYRAWDAT1=Data MYRAWDAT1.Filename="LoadStudy.pks"MYRAWDAT1.FileType="PKS"MYRAWDAT1.Load

Rema Step2: Load latest study dataSet MYRAWDAT2=Data MYRAWDAT2.Filename="bg1-dxg-9.pwo"MYRAWDAT2.FileType="PWO"MYRAWDAT2.Load

Rema Step3: Refresh study data with new study data Rema via copy/pasteMYRAWDAT2.StartRow=1MYRAWDAT2.EndRow=16MYRAWDAT2.StartCol="subject"MYRAWDAT2.EndCol="concentration"MYRAWDAT2.CopyMYRAWDAT1.StartRow=1MYRAWDAT1.EndRow=16MYRAWDAT1.StartCol="subject"MYRAWDAT1.EndCol="concentration"MYRAWDAT1.PasteMYRAWDAT2.Unload

Rema Step4: Update studyMYRAWDAT1.Save


519

19

Creating a scenario

This example creates a scenario by running statistics on the loaded study and saving it.

Note the reason for change in the CREATESCENARIO.PKS file, below.

LOADSTUDY.PKS

…<StudyInformation Name="bg1" Reason="Scripting Study update"/>…

Script file

rema Load studySet MYRAWDAT1=Data MYRAWDAT1.Filename="LoadStudy.pks"MYRAWDAT1.FileType="PKS"MYRAWDAT1.Load

rema Do descriptive statsDesc.InData="MYRAWDAT1"Desc.SortVars=1Desc.SortVar(1)="Subject"Desc.SummaryVars=1Desc.SummaryVar(1)="Concentration"Desc.OutData="MYDESCDATA"Desc.RunMYDESCDATA.Filename="Scripted Stats"

rema Save scenarioMYRAWDAT1.Filename="CreateScenario.pks"MYRAWDAT1.Save

CREATESCENARIO.PKS

…<Scenario Name="Scripted Scenario 1" Reason="Testing Scripting"/>…


520

19

Re-running a scenario

In this example, a scenario is loaded with the latest changes to the study. It is re-run and saved.

Note the reason for change in the LOADSCENARIO.PKS file below, and the Get-Latest flag, indicating get latest study data.

Examples of individual scripting operationsThis section provides examples of scripting single WinNonlin operations. Each example is a complete script, though real scripts would generally include multiple operations. See the Examples Guide for examples of com-plete scripts.

Script file

rema Load studySet MYRAWDAT1=Data MYRAWDAT1.Filename="LoadScenario.pks"MYRAWDAT1.FileType="PKS"MYRAWDAT1.Load

rema Run modelPK.Run

rema Save scenario MYRAWDAT1.Save

LOADSCENARIO.PKS

…<StudyInformation Name="bg1" Reason="Scripting study update"/><Scenario Name="script re-run" Reason="Scripting sce-nario re-run" GetLatest="TRUE"/>…

ScriptingExamples of individual scripting operations

521

19

Data manipulation

Loading files

rema ***************************************************rema * Importing an ASCII file and an Excel file, and rema * loading a WinNonlin Data Object rema ***************************************************

Set MYDATA1=DataMYDATA1.Filename="c:\winnonln\examples\bguide1.dat”MYDATA1.FileType="ASCII”MYDATA1.Delimiter= “ “MYDATA1.Headers=TrueMYDATA1.Conseqdelim=TrueMYDATA1.Missing="."MYDATA1.Load

Set MYDATA2=DataMYDATA2.Filename="c:\winnonln\examples\rawdata.xls"MYDATA2.FileType="EXCEL"MYDATA2.Headers=TrueMYDATA2.Missing="."MYDATA2.Load

Set MYDATA3=DataMYDATA3.Filename="c:\winnonln\examples\clayton.pwo"MYDATA3.FileType="PWO"MYDATA3.Load

Copying and pasting data

Remark *************************************************Remark * This example copies 10 rows of data from two columnsRemark * and pastes them to a new location (Columns E and F). Remark *************************************************set MYDATA = DataMYDATA.Filename = <file name>


522

19

MYDATA.StartRow=1MYDATA.StartCol=AMYDATA.EndRow=10MYDATA.EndCol=BMYDATA.CopyMYDATA.StartRow=1MYDATA.StartCol=EMYDATA.PasteThe same script could be used to cut and paste data, by replacing MYDATA.Copy with: MYDATA.Cut.

Renaming a column

Remark *************************************************Remark * Method: RenameCol Remark * This script renames column 'a' to 'Other'. Remark *************************************************set MYDATA = DataMYDATA.Filename = "c:\winnonln\examples\testdata.xls"MYDATA.Filetype = "EXCEL"MYDATA.Headers = FalseMYDATA.LoadMYDATA.Column = "a"MYDATA.With = "Other"MYDATA.RenameCol

Replacing values in a worksheetRemark **************************************************Remark * Method: ReplaceRemark * This script searches for data values equal to '3' inRemark * the column 'CONC' and replaces them with 'Missing'.Remark **************************************************set MYDATA=DataMYDATA.Filename="c:\winnonln\examples\testdata.xls"MYDATA.Filetype="EXCEL"MYDATA.Headers=TrueMYDATA.LoadMYDATA.SearchArea="CONC"MYDATA.Find="3"


523

19

MYDATA.Operation="="MYDATA.Tolerance="0"MYDATA.CaseSensitive=FalseMYDATA.With="Missing"MYDATA.Replace

Removing rows based on a data value

Remark **************************************************Remark * Method: RemoveRemark * This script tests the Remove function. The script searchesRemark * for data values equal to '3' in the column 'TIME' and Remark * removes the entire row.Remark **************************************************set MYDATA=DataMYDATA.Filename="c:\winnonln\examples\testdata.xls"MYDATA.Filetype="EXCEL"MYDATA.Headers=TrueMYDATA.LoadMYDATA.SearchArea="TIME"MYDATA.Find="3"MYDATA.Operation="="MYDATA.Tolerance="0"MYDATA.CaseSensitive=FalseMYDATA.Remove

Removing a range of rows

Remark *************************************************Remark * Method: RemoveRowRemark * This script deletes a range of rows (2-15) fromRemark * a data set.Remark *************************************************set MYDATA=DataMYDATA.Filename="c:\winnonln\examples\testdata.xls"MYDATA.Filetype="EXCEL"MYDATA.Headers=FalseMYDATA.Load


524

19

MYDATA.StartRow=2MYDATA.EndRow=15MYDATA.RemoveRow

Removing a column

Remark *************************************************Remark * Method: RemoveColRemark * This script deletes a specified column from the data set.Remark * Note: If the Headers property is 'False' the script will notRemark * fail. This is because even if headers are not loaded a columnRemark * can still be removed by specifying the column letter, forRemark * example 'A', 'B', etc.Remark *************************************************set MYDATA=DataMYDATA.Filename="c:\winnonln\examples\testdata.xls"MYDATA.Filetype="EXCEL"MYDATA.Headers=FalseMYDATA.LoadMYDATA.Column="a"MYDATA.RemoveCol

Excluding and including data

Remark *************************************************Remark * Method: Exclude, Include Remark * This script demonstrates the Include and Exclude functions. Remark * The script first excludes everything with a value of greater Remark * than 1 from the entire data set, then goes back and includes Remark * everything with a value equal to 3. Finally, everything with Remark * a value equal to 4.3 is included in a specific column Remark * (in this case 'CONC'). Remark *************************************************set MYDATA=DataMYDATA.Filename="c:\winnonln\examples\testdata.xls"MYDATA.Filetype="EXCEL"MYDATA.Headers=TrueMYDATA.Load


525

19

MYDATA.SearchArea="entire data set"MYDATA.Find="1"MYDATA.EntireRow=TrueMYDATA.Operation=">"MYDATA.Tolerance="0"MYDATA.CaseSensitive=FalseMYDATA.ExcludeMYDATA.SearchArea="entire data set"MYDATA.Operation="="MYDATA.Find="3"MYDATA.IncludeMYDATA.SearchArea="conc"MYDATA.Find="4.3"MYDATA.Include

Appending data

Remark *************************************************Remark * Method: Append (intelligent)Remark * This script appends one EXCEL data file to another EXCELRemark * data file. Both data sets have headers. Remark *************************************************set MYDATA=DataMYDATA.Filename = "c:\winnonln\examples\testapp1.xls"MYDATA.Filetype = "EXCEL"MYDATA.Headers = TrueMYDATA.LoadMYDATA.AppendFilename = "c:\winnonln\examples\testapp2.xls"MYDATA.AppendFileType = "EXCEL"MYDATA.Append

Merging data sets

rema ***************************************************rema A simple example merging two data setsrema ********************************************************Set ANIMAL=Data ANIMAL.Filename="c:\testpk\animal2.pwo"


526

19

ANIMAL.FileType="PWO"ANIMAL.Load

Set PLANT=Data PLANT.Filename="c:\testpk\plant2.pwo"PLANT.FileType="PWO"PLANT.Load

merge.numdata=2merge.indata(1)=ANIMALmerge.indata(2)=PLANTmerge.sortvars=1merge.sortvar(1,1)="Common"merge.sortvar(2,1)="Common"merge.includevars(1)=1merge.includevar(1,1)="Animal"merge.includevars(2)=1merge.includevar(2,1)="Plant"merge.run

Plots

Specifying uniform axes

Set MYDATA=DataMYDATA.FileName="c:\winnonln\examples\profiles.pwo"MYDATA.FileType="PWO"MYDATA.Load

Plot.NumData=1Plot.InData(1,1)="MYDATA"Plot.SortVars(1)=1Plot.SortVar(1,1)="Subject"Plot.GroupVars(1)=1Plot.GroupVar(1,1)="Form"Plot.XVar(1)="Time"Plot.YVar(1)="Conc"Plot.OutGraph="MYOUTGRAPH"


527

19

Plot.Run

MYOUTGRAPH.UNIFORM=TrueMYOUTGRAPH.FileName="c:\winnonln\examples\exmpl_y.pco"MYOUTGRAPH.FileType="PCO"MYOUTGRAPH.Save

Saving multiple charts to separate metafiles

Rema ***************************************************Rema This script runs the command file bg1.cmd. This file createsRema an output graph for only one profile, but has multipleRema diagnostic graphs.Rema When complete, five .WMF files will be stored to the defaultRema directory: Plot001a.wmf, Plot001b.wmf, Plot001c.wmf.Rema Plot001d.wmf and Plot001e.wmfRema ***************************************************

Set MYMODEL=Model

rema Load and Run bg1.cmdMYMODEL.Filename="c:\winnonln\examples\bg1.cmd"MYMODEL.FileType="ASCII"MYMODEL.Load

rema Run the command filePk.OutData="MYOUTDATA"Pk.OutGraph="MYOUTGRAPH"Pk.Run

rema Save all plots as separate .WMF flesMYOUTGRAPH.SaveAllPrefix="plot"MYOUTGRAPH.filetype="wmf"MYOUTGRAPH.SaveAll

Saving multiple charts to bitmap files

Rema ***************************************************


528

19

Rema This script saves graphs created using a Sort variable to Rema separate bitmap files. When finished, six files will beRema created - one for each level of the sort variables. Rema These files are GRAF001a.bmp, GRAF002a.bmp, Rema GRAF003a.bmp, Rema GRAF004a.bmp,Rema and GRAF005a.bmp and GRAF006a.bmp.Rema ***************************************************

Set MYDATA=DataMYDATA.FileName="c:\winnonln\examples\profiles.pwo"MYDATA.FileType="PWO"MYDATA.Load

Plot.NumData=1Plot.InData(1,1)="MYDATA"Plot.SortVars(1)=1Plot.SortVar(1,1)="Subject"Plot.GroupVars(1)=1Plot.GroupVar(1,1)="Form"Plot.XVar(1)="Time"Plot.YVar(1)="Conc"Plot.OutGraph="MYOUTGRAPH"Plot.Run

rema Save all plotsMYOUTGRAPH.SaveAllPrefix="graf"Rema to create Windows Meta Files instead, use the filetype WMF.MYoutgraph.filetype="BMP"MYOUTGRAPH.SaveAll

Overlay plot

rema ***************************************************rema * A simple plotting example, with Overlayrema ***************************************************

Set IV=Data IV.Filename="c:\WinNonln\examples\iv.pwo"IV.FileType="PWO"


529

19

IV.Load

Set ORAL=Data ORAL.Filename="c:\WinNonln\examples\oral.pwo"ORAL.FileType="PWO"ORAL.Load

plot.numdata=2plot.indata(1)=IVplot.indata(2)=ORALplot.Xvar(1)="Subject"plot.Yvar(1)="AUC"plot.Xvar(2)="Subject"plot.Yvar(2)="AUC"plot.legend(1)="IV"plot.legend(2)="Oral"plot.run

Data transformations

Change from baseline

rema ***************************************************rema * Change from baseline transformationsrema ***************************************************

Set MYRAWDATA=DataMYRAWDATA.Filename="c:\temp\mydata.pwo"MYRAWDATA.FileType="PWO"MYRAWDATA.Load

TRANS.InData = MYRAWDATATRANS.function=trans_changebasetrans.sourcecol=conctrans.extra="time"trans.destcol="Change"trans.destarea="Append"MYRAWDATA.sortvars=2


530

19

MYRAWDATA.sortvar(1)="Subject"MYRAWDATA.sortvar(2)="Form"trans.run

TRANS.InData = MYRAWDATATRANS.function=trans_pctchangetrans.sourcecol=conctrans.extra="time"trans.destcol="PctChg"trans.destarea="Append"MYRAWDATA.sortvars=2MYRAWDATA.sortvar(1)="Subject"MYRAWDATA.sortvar(2)="Form"trans.run

TRANS.InData = MYRAWDATATRANS.function=trans_ratiobasetrans.sourcecol=conctrans.extra="time"trans.destcol="ratio"trans.destarea="Append"MYRAWDATA.sortvars=2MYRAWDATA.sortvar(1)="Subject"MYRAWDATA.sortvar(2)="Form"trans.run

Other transformations

rema ***************************************************rema * All transformations, except change from baselinerema * transformationsrema ***************************************************

Set MYRAWDATA=DataMYRAWDATA.Filename="c:\winnonln\examples\bguide1.dat"MYRAWDATA.FileType="ASCII"MYRAWDATA.Headers=TrueMYRAWDATA.Delimiter=" "MYRAWDATA.Load


531

19

TRANS.InData = MYRAWDATATRANS.function=trans_lntrans.sourcecol="conc"trans.destcol="LnConc"trans.destarea="Append"trans.run

TRANS.InData = MYRAWDATATRANS.function=trans_log10trans.sourcecol=conctrans.destcol="LogConc"trans.destarea="Append"trans.run

TRANS.InData = MYRAWDATATRANS.function=trans_sqrttrans.sourcecol=conctrans.destcol="SQRTconc"trans.destarea="Append"trans.run

TRANS.InData = MYRAWDATATRANS.function=trans_abstrans.sourcecol=conctrans.destcol="ABSConc"trans.destarea="Append"trans.run

TRANS.InData = MYRAWDATATRANS.function=trans_metabolitetrans.sourcecol=conctrans.extra=timetrans.destcol="Metabolite"trans.destarea="Append"trans.run

TRANS.InData = MYRAWDATATRANS.function=trans_E


532

19

trans.sourcecol=conctrans.destcol="E_conc"trans.destarea="Append"trans.run

TRANS.InData = MYRAWDATATRANS.function=trans_invtrans.sourcecol=conctrans.destcol="INVconc"trans.destarea="Append"trans.run

TRANS.InData = MYRAWDATATRANS.function=trans_powertrans.sourcecol=conctrans.extra=2 trans.destcol="PowerConc"trans.destarea="Append"trans.run

TRANS.InData = MYRAWDATATRANS.function=trans_multtrans.sourcecol=conctrans.extra=2 trans.destcol="MULTConc"trans.destarea="Append"trans.run

TRANS.InData = MYRAWDATATRANS.function=trans_divtrans.sourcecol=conctrans.extra=2 trans.destcol="DIVConc"trans.destarea="Append"trans.run

TRANS.InData = MYRAWDATATRANS.function=trans_addtrans.sourcecol=conc


533

19

trans.extra=2 trans.destcol="ADDConc"trans.destarea="Append"trans.run

TRANS.InData = MYRAWDATATRANS.function=trans_subtracttrans.sourcecol=conctrans.extra=2 trans.destcol="SubtractConc"trans.destarea="Append"trans.run

WinNonlin.msgbox = 'Script finished'

Descriptive statistics

Desc.InData="MYRAWDATA"Desc.SortVars=1Desc.SortVar(1)="Subject"Desc.SummaryVars=1Desc.SummaryVar(1)="Conc"Desc.OutData="MYDESCDATA"Desc.Run

Modeling

Phamacokinetic or non-compartmental analysis using a command file

rema ******************************************************rema * This is a sample WinNonlin Professional Script file thatrema * demonstrates a batch run that loads and processes arema * command file.rema ******************************************************

Set MYMODEL=Model

rema Load and Run nca_sort.cmd


534

19

MYMODEL.Filename="c:\wnlbeta\examples\nca_sort.cmd"MYMODEL.FileType="ASCII"MYMODEL.LoadPk.OutData="NCADATA"Pk.OutText="NCATEXT"Pk.OutGraph="NCAGRAPH"Pk.Run

WinNonlin Model Object

Prior to writing the script, develop the model specifications including differ-ing profile-by-profile information on dosing, initial parameters, lambda_z range specifications and partial area calculation. Save the model to a Phar-sight Model Object file (.pmo).

Set MYMODEL = ModelMYMODEL.Filetype="pmo"MYMODEL.Filename="c:\winnonln\examples\ncamodel.pmo"MYMODEL.LoadPk.OutData="MYOUTDATA"rema text and graphics output objects, if any, may be named herePk.Run

ANOVA

rema ***************************************************rema * Running an ANOVArema ***************************************************

ANOVA.Filename="c:\winnonln\examples\threeper.anv"ANOVA.run

Tables

Using the Table Wizard

rema ***************************************************rema * Creating a simple table using the Table Wizard.


535

19

rema * File references below expect C:\WINNONLN\EXAMPLESrema * to contain CLAYTON.PWO rema ***************************************************

Set MYRAWDATA=DataMYRAWDATA.Filename="c:\winnonln\examples\clayton.pwo"MYRAWDATA.FileType="PWO"MYRAWDATA.Load

TABLE.TableNum=3TABLE.NumData=1TABLE.GroupVars=1TABLE.GroupVar(1)="Form"TABLE.IDVars=4TABLE.IDVar(1)="Subject"TABLE.IDVar(2)="Period"TABLE.IDVar(3)="Seq"TABLE.IDVar(4)="Hour"TABLE.RegVars=1TABLE.RegVar(1)="Conc"TABLE.Stats=TrueTABLE.OutData=MYDATATABLE.RUN

MYDATA.Filename="c:\winnonln\examples\table1.pwo"MYDATA.FileType="PWO"MYDATA.SAVE

Using a table definition file

rema ***************************************************rema * Creating a formatted table using the Table Wizard.rema * File references below expect C:\WINNONLN\EXAMPLESrema * to contain CLAYTON.PWO. rema ***************************************************

Set MYRAWDATA=DataMYRAWDATA.Filename="c:\winnonln\examples\clayton.pwo"MYRAWDATA.FileType="PWO"


536

19

MYRAWDATA.Load

TABLE.NUMDATA=1TABLE.InData(1)=MYRAWDATATABLE.OutData=MYDATATABLE.DefinitionFile="C:\winnonln\examples\mytable.tdf"TABLE.RUN

MYDATA.Filename="c:\winnonln\examples\table2.pwo"MYDATA.FileType="PWO"MYDATA.Save

Workspaces

Loading

rema *******************************************************rema * Loading a workspacerema *******************************************************

WinNonlin.Filename="c:\testpk\ncaoral.wsp"WinNonlin.Load

Saving

rema ********************************************************rema * Running an ANOVA and saving the files as a workspacerema ******************************************************** ANOVA.Filename="c:\winnonln\examples\threeper.anv"ANOVA.OutData="OUTDATA"ANOVA.OutText="OUTTEXT"ANOVA.run

OUTDATA.Filename="c:\winnonln\examples\AOVDATA.pwo"OUTDATA.FileType="PWO"OUTDATA.Save


537

19

OUTTEXT.Filename="c:\winnonln\examples\AOVTEXT.PTO"OUTTEXT.FileType="PTO"OUTTEXT.Save

WinNonlin.FILENAME = "c:\winnonln\examples\mydata.wsp"WinNonlin.SAVE

Units

The script command is pk.units=text file, where text file is a file containing one unit per line. For example:

Remark WinNonlin.WindowState=MinimizedSet MYDATA1=DataSet MYMODEL=ModelMYMODEL.Filename="MODEL.CMD"MYMODEL.FileType="ASCII"MYMODEL.LoadMYMODEL.DoseFile="DOSES.DAT"MYMODEL.LamzFile="LAMBDAZ.DAT"Pk.OutData=OUTDATA1Pk.OutText=OUTTEXT1Pk.Units="units.txt"Pk.Run

Word export

The Word Export, ExportAll, is a method on the WinNonlin system object with the same options as PrintAll. It sets which type of object to export. For example, the following code would export all charts:

WinNonlin.PrintData = FalseWinNonlin.PrintText = False WinNonlin.PrintGraph = True WinNonlin.PrintModel = FalseWinNonlin.ExportAll


538

19

539

Chapter 20

Scripting WinNonlin Using Visual Basic

Automating WinNonlin features through VB

WinNonlin analysis and data handling functions can be scripted through Visual Basic. COM-enabled applications, such as Microsoft Word or Excel, can be used to develop Visual Basic scripts as “macros.” WinNonlin-specific elements are covered here. See the Visual Basic or other Microsoft documen-tation for details on Visual Basic (VB) programming. See the WinNonlin Examples Guide for example VB scripts.

Summary of properties and methodsThe following tables list object properties and methods applicable to each WinNonlin software module. Syntax, arguments, and usage examples for the individual properties and methods are available in the “Visual Basic Automa-tion Reference” on page 725.


540

20

Table 20-1. Summary of properties and methods for each module

Module Properties MethodsChart AxisLabelsFont

AxisLabelsFontSizeAxisTitleAxisTitleFontAxisTitleFontSizeAxisUnitsCaptionPrefixChangedChartCountForTabChartTitleCurrentChartForTabFile NameFileTypeFootnoteFontFootnoteFontSizeFormCaptionID

ImageLegendFontLegendFontSizeNamePrintMultiPrintMultiAcrossPrintMultiDownReadOnlySaveAllPrefixSourceTagTitleFontTitleFontSizeUniformUUIDWindowState

EditCopyLoadTemplateMoveFirstMoveLastMoveNextMovePreviousPrintAllPrintOutSaveSaveAllChartsSaveTemplateSheetSortLevel

Charts Count Item (none)Crossover InBook

OutBookResponseVarSequenceVarSortVars

SubjectVarTreatmentAVarTreatmentBVarTreatmentDataTreatmentVar

Run

Deconvolution AlphaTermATermBolusConcVarDeltaDoseUnitsInBookInputLagNumPoints

NumTermsOutBookOutChartOutputFromOutputRangeOutputToSmoothingSortVarsTimeVar

Run

DescStats BoxWhiskerPlotConfidenceConfidenceValueInBookMultiSheetOutBook

OutTextPercentilesSortVarsSummaryVarsWeightVar

Run

Scripting WinNonlin Using Visual BasicSummary of properties and methods

541

20

LinMix File NameOutBook

OutText Run

Merge CarryAlongInBook1InBook2IncludeVars1IncludeVars2

MissingOutBookSortVars1SortVars2

Run

Model ChangedIDModelWindowModelWorkbook

NameSourceTagUUID

LoadDoseFileLoadLambdazFileLoadLinkFileLoadNamesFile

LoadParamFileLoadPartialAreasFileLoadUnitsFile

PK OutBookOutChart

OutTextWordExportFilename

RunRunWordExport

Plot AutoSortChartTypeDownVarErrTypeGroupVarsInBookIntervalsLegendNumBookOutChartShowUnits

SortVarsTitleUpVarUseGroupHeadersUsePatternsXTitleXUnitsXVarsYTitleYUnitsYVars

Run

PrintExportAll ChartFormatFigureNumFigureNumStartIncludeChartsIncludeModelsIncludeTextEditorsIncludeWorkbooksLockOutputLogChartsMultipleChartsPerPage

MultipleChartsPer-PageAcrossMultipleChartsPer-PageDownOrientationPreserveTableFormatsSourceLineTableNumTableNumStart

ExportAllPrintAll

Rule curRuleStateName

NonNumericCode GetValueIsUnConditional

LetValue

Table 20-1. Summary of properties and methods for each module (continued)

Module Properties Methods


542

20

Semicompart-mental

ConcVarEffectVarInBookKeoMethod

OutBookOutChartSortVarsTimeVar

Run

StatusCodes bLLOQDefinedCarryAlongsConcColInBookLLOQColOutBookRSets

RuleSetsRuleSetsDestRuSetSortKeysStatusColTimeCol

Run

Superposition ConcVarDisplayDoseDoseDoseTimeDosingTypeInBookInitialDoseMaintenanceDoseMethodNumDosesNumPoints

OutBookOutChartRangeStartRangeStopSortVarsTauTermLowerTermPhaseTermUpperTimeRepeatTimeVar

LoadDoseFileRun

Table AggregateVarCrossVarsDataOnlyDefinitionFileDescStatsGroupVarBreakGroupVarsIDVarsInBookJoinCrossVars

JoinGroupVarsJoinIDVarsNumBookOutBookPageFooterPageHeaderRegVarsShowUnitsTableNumUnitsFormat

Run



Scripting WinNonlin Using Visual BasicSummary of properties and methods

543

20

TextEditor BottomMarginCaptionPrefixChangedEditorTextEditorTextLengthEditorTextRTFFile NameFileTypeFindNextPosFindStringFormCaptionIDIsModelLeftMargin

NamePageHeightPageWidthReadOnlyRightMarginSelectionLengthSelectionStartSelectionTextSelectionTextRTFSourceTagTopMarginUUIDWindowState

EditCopyEditCutEditDeleteEditPasteFindPrintOutSaveSelectAll

TextEditors Count Item (none)Wnl4 Copyright

DescriptionVersionWorkspace

(none)

Workspace ActiveChartActiveFormTypeActiveModelActiveTextEditorActiveWorkbookChangedChartChartCountChartsFile Name

ModelModelCountSilentModeTextEditorTextEditorCountTextEditorsWindowStateWorkbookWorkbookCountWorkbooks

ArrangeCloseAllCloseChartCloseModelCloseTextEditorCloseWorkbookLoadNewChartNewModelNewTextEditor

NewWorkbookNewWorkspaceOpenChartOpenModelOpenTextEditorOpenWorkbookRunScriptSaveShowMsgUnloadAppWorkingDir




544

20

Workbook ActiveColActiveRowActiveSheetAppendFileNameAppendFileTypeAppendSheetAutoFileOptionsCaptionPrefixCellFormulaCellFormulaRCCellValueCellValueRCChangedClipColNameColUnitConsecutiveDelimitersDelimiterFile NameFileTypeFormCaptionHeadersIDIsExcludedIsExcludedRCIsMissingValIsMissingValRCLastCol

LastRowMissingNamenumSheetsNumSortKeysNumSortKeysExReadOnlySearchAreaSearchCaseSensitiveSearchCompareSearchReplaceValueSearchRowModeSearchToleranceSearchValueSelectionSelEndColSelEndRowSelStartColSelStartRowSheetNameShowUnitsSortedSortKeySortKeyExSourceTagUseFormatsUUIDWindowState

AppendConvertUnitsEditCopyEditCutEditDeleteEditPasteEditPasteValuesExcludeSelGetActiveCellGetColNumGetLastRowColIncludeSelInsertColInsertRowLastRowForColPrintAllPrintOutResetExclusionsSaveSearchSearchExcludeSearchIncludeSearchReplaceAllSetActiveCellSortTransform

Workbooks Count Item (none)Variable Column

DataTypeIDkeyMapping

NameSortIndexSortOrderVarType

(none)

Variables (none) AddAddExCountExists

ItemItemsByTypeRemoveRemoveAll



Scripting WinNonlin Using Visual BasicAutomating Pharsight Knowledgebase Server functions

545

20

Automating Pharsight Knowledgebase Server functionsVisual Basic automation can be used to operate PKS/WinNonlin data opera-tions. The properties and methods used to work with data from files stored locally (e.g., load, save, etc.) can be applied, using the same syntax, to PKS studies and scenarios. This requires that:

1. The user run the program PASSWORD.EXE, which is shipped with Win-Nonlin, to encrypt and store the PKS password. The user ID is used to encrypt the password. The user must copy and paste the password into the pks file. See “PKS file format” on page 513.

2. Replace file names in the relevant operations (load, save, etc.) with the PKS study name, followed by the extension .PKS.

3. Use the file type: FilePKS for those objects.

For Example, to load a PKS study called “TestStudy” into WinNonlin:

1. Get the file name: sFile = sUnitTestFolder & "BG1_Dose.pwo"

2. Open the workbook:Set objWorkbook1 = objWkspace.OpenWorkbook(sFile, FileFWBook, nHeaders)

sFile = sUnitTestFolder & "Scenario.pmo"

3. Change the file to save back to, by pointing to a pks file with the study name:sFile = sUnitTestFolder & "TestStudy.pks"

objWorkbook2.FileType = FilePKS

objWorkbook2.file name = sFile

4. Save to PKS:objWorkbook2.save

To create a scenario, use the same method, using the scenario name:sFile = sUnitTestFolder & "TestScenario.pks"

sStudyName = FixStudyName(sFile, sStudyName)

wrkBk.FileType = FilePKS

wrkBk.file name = sFile

wrkBk.save


546

20

See also “Scripting the Pharsight Knowledgebase Server” on page 512 for similar functions using the WinNonlin scripting language.

Visual Basic scriptingAny COM-enabled application can be used to create Visual Basic (VB) scripts to run WinNonlin functionality. The instructions below use Microsoft Word 2000, as an example of how this is done.

Creating a script using Microsoft Word 2000

To create a WinNonlin Visual Basic script using Microsoft Word 2000:

1. Start Microsoft Word.

2. Choose Tools>Macro>Macros... from the Word menus.

3. In the Macro name text box, type the script name.

4. Click the Create button.

Word will open a new macro in Visual Basic.

Scripting WinNonlin Using Visual BasicVisual Basic scripting

547

20

5. A reference to the WinNonlin object model must be added. In the VBA win-dow, choose Tools>References... from the menus. A dialog box will open showing a list of references that may be added to the project.

6. Scroll down the list to find WinNonlin4 and check that entry.

7. Click OK.

8. After the reference is added, enter the desired Visual Basic code in the space provided for the new macro.


548

20

9. After entering the code, choose File>Close and Return to Microsoft Word from the menus. At this point the macro is available to run at any time.

Running a script using Microsoft Word 2000

To run a WinNonlin VB macro from Microsoft Word 2000:

1. In Word, choose Tools>Macro>Macros... from the menus.

Any macros previously created should appear in the list. See “Creating a script using Microsoft Word 2000” on page 546 for instructions.

2. Select the desired macro and click Run.

The macro can launch WinNonlin (if not already running), and run commands specified in the new script. See the WinNonlin Examples Guide for examples of WinNonlin automation using Visual Basic and Microsoft Word.

549

Appendix A

Glossary

The following terms and definitions pertain specifically to objects and opera-tions in WinNonlin and its operations with Pharsight Workbench Repository. Italics indicate terms that are defined elsewhere in the glossary.

A

A In Modeling, the zero time intercept associated with the Alpha phase. In Deconvolution A and alpha refer to the parameters of a polyexponential unit impulse response function of the form:

UIR(t) = sum[A(j) * exp(-alpha(j) * t)], j = 1 …. N.

absolute error bars

Information that indicates the degree of precision associated with a parameter estimate. It is displayed as an absolute quantity, not as a percentage of the esti-mate.

actual time The time that a study dose or observation actually happened; this time may differ from the nominal time.

absorption rate

The rate at which the drug is absorbed into the central compartment. It is often denoted as Ka or K01.

accumulation index

actual clock time

(PKS) A placeholder, available for the research data. It is not automatically used in any WinNonlin calculations.

1

1 eλz τ×( )–

–[ ]--------------------------------=


550

A

actual end time

(PKS) A field that is used specifically for dose information. The duration of infusions can be specified here.

Akaike Information Criteria (AIC)

A measure of goodness of fit based on maximum likelihood. When comparing several models for a given set of data, the model associated with the smallest value of AIC is regarded as giving the best fit out of that set of models. AIC is only appropriate for use when comparing models using the same weighting scheme.

for modeling in WinNonlin. N is the number of observations with positive weight. WRSS is the weighted residual sum of squares. P is the number of parameters.

In LinMix, it is defined as: where is the restricted likelihood evaluated at converged estimates, and s is the rank of the fixed–effects design matrix plus the number of variance parameters, and variance components for linear mixed–effects modeling calculations.

Alpha In modeling, the macro rate constant associated with the distribution phase.

In Deconvolution, A and alpha refer to the parameters of a polyexponential unit impulse response function of the form:

UIR(t) = sum[A(j) * exp(-alpha(j) * t)], j = 1 …. N.

Alpha half-life The half life associated with the macro constant Alpha. Sometimes denoted ALPHA_HL.

Anderson-Hauck pval

The p-value of the Anderson-Hauck test statistic. This is derived from a non-central t distribution.

Anderson-Hauck statistic

Test statistic applicable for testing equality of means in a bioequivalence study. The test statistic t is:

where the 's are the respective sample means, and are the group sam-ple sizes, and S is the estimate of the residual standard deviation. A and B are the lower and upper limits.

AIC N WRSS( )log× 2P+=

AIC 2– LR 2S+= LR

tXE XS– 1

2--- A B+( )–

S 1 nE⁄ 1 nS⁄+----------------------------------------------=

X nE nS

GlossaryA

551

A

ANOVA command file (.anv)

An ANOVA command file (.ANV) contains all of the information required to recall and reproduce a given ANOVA model, including the data set used. These files are used in the Scripting Language to specify ANOVAs to be run. See also command file and table definition file.

application log An application log file is produced by WinNonlin and viewed using the Log Viewer application. The log file records many of the activities performed in WinNonlin, including loading/creating of a data set; cutting and pasting of regions; setting, clearing and converting units; PK/PD/NCA modeling results and error messages; sorting, exclusions, inclusions, replacements, and other revisions to data sets.

Controls for the application log are limited. Users can specify the size for the log file (before it is purged) and can purge it manually.

AUC Area under a concentration of analyte vs. time curve. Theoretically, if C(t) denotes the concentration of analyte at time t, then:

AUCINF AUC (area under a curve) extrapolated to infinity:

AUClast AUC (area under a curve) computed to the last observation:

AUMC Area under the moment curve:

AUMCINF Area under the moment curve when the time concentration curve is extrapo-lated to infinity.

AUMClast Area under the moment curve computed to the last observation.

AUCba

c t( ) tda

b

∫=

AUC∞0

AUCtlast

0

AUMCba

c t( )t tda

b

∫=

AUMCINF AUMC∞0

=

AUMClast AUMCtlast

0=


552

A

B

B The zero time intercept associated with the beta phase.

balanced design

An experimental design set is said to be balanced if the number of observa-tions is the same for every combination of the experimental effects. For exam-ple, for a crossover design with effects for formulation and period, each with two levels, if each of the four combinations of formulation by period treat-ment groups has the same number of observations, then the design is bal-anced. If a subject drops out of one sequence, the design is no longer balanced.

Beta “Macro” rate constant associated with the elimination phase.

Beta half-life The half life associated with the macro constant Beta. Sometimes denoted BETA_HL.

bioequiva-lence

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. Average bioequivalence states that aver-age bioavailability for test formulation is the same as for the reference formu-lation. Population bioequivalence is meant to assess equivalence in prescribability and takes into account both differences in mean bioavailability and in variability of bioavailability. Individual bioequivalence is meant to assess switchability of products, and is similar to population bioequivalence.

bounds Upper and lower constraints on the initial parameter estimates for compart-mental modeling.

The lower and upper values bound the range of values the parameters can take on during the model fitting process. This can be very valuable if the parameter values become unrealistic or the model will not converge. Although bounds are not always required, it is recommended that Lower and Upper bounds be used routinely. If they are used, every parameter must be given lower and upper bounds.

The WinNonlin default bounds are 0 for one bound and 10 times the initial estimate for the other bound. For models with parameters that may be either positive or negative, user-defined bounds are preferred.

GlossaryC

553

A

box and whiskers plot

The box and whiskers plot is designed to show the amount of distribution of values. To include a box and whiskers plot as output, select the Box and Whiskers check box. The plot appears in a separate text window.

Each profile will display an axis from the Min to the Max including their mid-point. The box hinges are the 25th and 75th percentiles. The whiskers will end at the Max and Min points unless there are outliers that are outside 1.5 times the H-spread [the distance between the hinges] from the hinges. The median is plotted as well.

If there are fewer than five data points, no plot is produced; the points are sim-ply graphed.

BQL Below the lower limit of quantification (LLOQ) for a given assay.

C

C The zero–time intercept associated with the absorption phase for an extravas-cular model or the zero time intercept associated with the gamma phase for a 3 compartment IV bolus model.

carry along variables

Variables that are not required for the current analysis, but will be copied and included in the output data set.

Cavg For steady-state data: computed as AUC(0- ) divided by .

CL Total body clearance. CL= Dose/AUC

classification variables

Classification variables are the variables that have discrete sets of values such as formulation, treatment and gender.

clock time Time expressed as a date and/or time, rather than relative to the first dose or the start of a study.

CLR Renal Clearance.

τ τ


554

A

Clss, Clss/F For steady-state data: an estimate of the total body clearance. For extravascu-lar models the fraction of dose absorbed cannot be estimated, therefore Clear-ance for these models is actually Clearance/F where F is the fraction of dose absorbed.

Cmax The peak or maximum concentration.

Cmin For steady-state data: the minimum concentration between 0 and (corre-sponding to Tmin).

command file A Command file (.CMD) contains all of the information required to recall and reproduce a given compartmental model or noncompartmental model, includ-ing the data set used. Command files or WinNonlin model objects can be used in the Scripting Language to include models to be run. See also ANOVA com-mand file (.anv) and table definition file.

compound A drug molecule under study. It may include one or more formulations of that drug. The concept is used especially in the PWR to group studies that are investigating the same molecule.

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 par-tial derivatives.

constant Dosing information such as number of doses, magnitude of each dose, and dosing times are input as constants. Each library model requires specific dos-ing information.

contrasts In LinMix, contrasts are linear combinations of levels of an effect, such that the sum of the coefficients add to 0. For example, suppose that effect Trt has three levels: Placebo, 10mg, and 20mg. To compare the two dose groups against the placebo group, construct the contrast (Placebo=1, 10mg=-0.5, 20mg=-0.5). Note that 1-0.5-0.5=0, so this is a valid contrast. This contrast compares the average of the 10mg and 20mg groups versus the placebo group.

convergence criterion

The convergence criterion determines when WinNonlin can stop with a suc-cessful fit. Convergence is achieved when the relative change in the residual objective function is less than the convergence criteria.

Dose

AUCτ0

----------------=

τ

GlossaryD

555

A

covariates Independent variables in a LinMix model. Generally, some subject character-istic of interest, such as age, blood pressure, or body weight. Covariates are continuous measurements.

crossed factors

In a LinMix crossed–classification model every level of every factor could be used in combination with every level of every other factor. In this way, the factors “cross” each other. It is not required that data be available at every intersection of the factors. See also nested factors.

cross variable In the Table Wizard, cross variables divide data into separate columns, according to the value of the Cross variable(s).

curve stripping A graphical method for estimating parameters associated with models that can be written as a sum of exponentials. This method can be used to determine ini-tial estimates required as a prelude to nonlinear least-squares regression.

D

data history A data history worksheet is maintained as part of every workbook. This data history tracks the history of that data set, including the source, sorting, data changes, and analyses.

If a data set was generated by the system, e.g., descriptive statistics or com-partmental modeling, the date and time stamp will be followed by the name of the source data set from which it was generated, followed by a listing of any missing or excluded values that were in the source data set.

After the initial loading/creating of a data set, the data history will contain information about cutting and pasting regions; setting, clearing, and convert-ing units; and PK/PD/NCA modeling errors. The data history worksheet will also show any sorting that takes place, exclusions, inclusions, replacements, added rows/columns, deleted rows/columns and transformations. It applies only to the worksheets in the current workbook.

dependent variable

Dependent variables have some functional relationship, possibly unknown, to the independent variables. A variable such as “drug concentration” is usually a dependent variable because it depends on factors like “formulation,” “period,” or “time of sample.”

descriptive statistics

Summary statistics of variables in data grids. The output from Descriptive Statistics includes: N, Nmiss, Nobs, Mean, Standard Deviation, Standard Error, Variance, Minimum, Median, Maximum, Range, CV%, Geometric


556

A

Mean, Harmonic Mean, Mean of the logs, Standard Deviation of the logs, skewness, kurtosis, and pseudo standard deviation. Percentiles and Confi-dence Intervals may also be included.

dosing regimens

The schedule of dosing. This information normally includes the designated dose and the time of the dose. It may also include the dose cycle, the sched-uled times for observations, etc., depending on the particular model's require-ments.

down variable This option appears on the Error Bars tab of the Chart Wizard. It specifies a variable to be used as down error bar values. If a group variable exists, error bars will be placed at each of the subsetted data points.

E

E Used to denote Effect.

EC50 Concentration that causes 50% of the effect.

eigenvalue An eigenvalue of matrix A is a number , such that for some vector x, x is the eigenvector. Eigenvalues and their associated eigenvectors can be thought of as building blocks for matrices.

The eigenvalues included in WinNonlin's modeling output are associated with the variance - covariance matrix. For compartmental modeling, WinNonlin prints a condition number which is equal to the square root of the ratio of the largest to the smallest eigenvalue. Very large values of the condition number may be indicative of instability in the model fitting process.

elimination rate

The rate at which the drug is eliminated from a compartment.

E0 Effect at time 0.

Emax Maximum effect.

engine Scripting Language Engines, also known as modules, execute tasks in Win-Nonlin. WinNonlin engines are: PK, DESC, ANOVA, PLOT, TABLE, TRANSFORM, MERGE, LINMIX, BIOEQUIVALENCE.

error bars Graphical elements on a plot that depict ranges of variability from a specific data point. Error bars may be placed above and/or below the actual data value,

λ Ax λx=

GlossaryF

557

A

and can be drawn as relative (e.g., standard error) or absolute variances (e.g., min/max).

exponential curve stripping

A graphical method for estimating parameters associated with models that can be written as a sum of exponentials. This method can be used to determine ini-tial estimates required as a prelude to nonlinear least-squares regression.

extravascular Denotes drug administration via routes other than directly into the blood stream. Oral, intramuscular and topical are examples of extravascular admin-istration.

F

first-order Used to denote rate constants when the transfer rates are proportional to the amount in the source compartment.

first row headers

An option on the File Open dialog for ASCII and Excel files which allows specification of column headers in the first row of data. WinNonlin will trans-form the headers located in the first row of data to column headings.

fixed effects generally associated with explanatory variables, as in a standard linear model. The variables can be either qualitative, as in traditional ANOVA, or quantita-tive, as in standard linear regression.

% fluctuation For steady-state data: % fluctuation is computed as 100*(Cmax-Cmin)/Cavg, where Cmin and Cmax were obtained between 0 and Tau.

formulation The point of dose input into a structural (PK/PD) model.

FORTRAN notation

Syntax used in the FORTRAN programming language. For example, EXP(-K01*t) is the constant e with an exponent of the negative product of time, t and the rate constant K01.

function variable

A variable in the data set that indicates which observations belong with which functions. This allows fitting multiple functions to one data set. Function vari-ables are required for simultaneous link models.

G

Gamma The terminal elimination rate associated with a three compartment, first-order model. Sometimes denoted GAMMA_HL.


558

A

Gamma half-life

The half–life associated with the macro constant Gamma.

Gauss-Newton algorithm

A model fitting algorithm. Modifications of the Gauss-Newton algorithm include the Hartley and Levenberg modifications. Hartley Modification: This method is not as robust as others but is very fast. Levenberg Modification: A model fitting algorithm that performs well on a wide class of problems, including ill-conditioned data sets. This method requires the estimated vari-ance - covariance matrix of the parameters, however the Levenberg modifica-tion suppresses the magnitude of the change in parameter values from iteration to iteration to a reasonable amount. This method is used as the default in WinNonlin.

geometric mean

The geometric mean is the nth root of the product of the n Y's: GM = . This requires that each Y > 0.

group variables

In the Chart Wizard, a group variable is used to break the data into separately plotted data lines.

For the Table Wizard, Group variables are much like ID variables, with the exception that only unique values of Group variables are printed. That is, they are only printed when their value changes. The value of the Group variables is also printed if values from a group go over a page break. Multiple group vari-ables may be used. Note that Group variables may appear as a column in the body of the table, or as an information line above the column titles. Use the Options command from the Tools menu to make this selection.

In LinMix, group variables allow for heterogeneity of variances while retain-ing the same mean model.

H

harmonic mean

The harmonic mean is the reciprocal of the arithmetic mean of the reciprocals of the Ys (Y > 0).

Y1Y2Y3…Ynn

HM 1n--- 1

Y---∑

1–=

GlossaryI

559

A

I

ID variables These variables are used by the Table Wizard to identify data in adjacent “Data” variable columns. When summary statistics are selected these vari-ables are not considered. Note that multiple ID variables may be used, and that this may be a convenient way to include units.

increment for partial derivatives

Nonlinear algorithms require derivatives of the models with respect to the parameters. The program estimates these derivatives using a forward differ-ence. For example:

where ∆ = Increment times the parameter value. The default is 0.001.

independent variable

The independent variables are controlled by the experimenter (e.g., formula-tion) or do not depend on other factors.

indirect response models

The measured response, R, to a drug may be produced by an indirect mecha-nism. Factors controlling the input or production, kin, of a response variable may be either inhibited or stimulated, or determinants of loss, kout, of the response variable may be inhibited or stimulated.

initial parameter estimates

Initial values for the parameters. All iterative estimation procedures require initial estimates of the parameters.

interaction Interaction is the degree to which the effect of one factor is different with varying values of another factor. For example, if a treatment has a different effect in one period than it does in another period, then Treatment and Period are said to interact.

Interaction terms would be included in a LinMix or Bioequivalence model using the “*” symbol: Treatment*Period.

intercept For LinMix ANOVA and regression models, the value of the response when all effects are zero.

IPR Indirect Pharmacodynamic Response Model.

iterations An option on the Settings tab of the Model Options dialog box that may be used to limit the maximum number of times WinNonlin will update the esti-mates. The default for Gauss-Newton type method is 50 and the Nelder-Mead

FdP 1( )d

-------------- F P 1( ) ∆+( ) F P 1( )( )–∆

---------------------------------------------------------≅


560

A

simplex method is 500. Usually these are adequate for most problems. If the number of iterations is set to zero, all output will be based on using the initial estimates as the final parameters.

iterative reweighting

A weighting scheme where weights associated with the individual observa-tions are functions of the predicted values.

J

K

K half-life The half–life associated with the rate constant K. Sometimes denoted K_HL.

K01 The rate at which the drug enters the central compartment from outside the system. It is sometimes denoted as Ka.

K10 The rate at which the drug leaves the system from the central compartment. The elimination rate.

K10 half-life The half–life associated with the rate constant K10. Sometimes denoted K10_HL.

Kij For first-order rate constants; the rate from Compartment i to Compartment j.

K0 Zero-order input or infusion rate constant.

KM Michaelis constant for models involving nonlinear kinetics.

L

lag time (LT) Lag time is a time delay between drug administration and the onset of drug absorption. An example of such a process is the stomach–emptying time, fol-lowing oral administration of a drug which is not absorbed from the stomach. When a drug is administered by bolus intravenous injection there is no lag phase.

Lambda Z (λ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.

GlossaryM

561

A

least squares fitting

In least squares fitting, the estimates are those which minimize the sum of the squares of the deviations between the observed values and the values pre-dicted by the model.

least squares means

Least squares means are estimates of what the mean values would have been had the data been balanced. That is, least squares means are the means pre-dicted by the fixed–effects model. If a data set is balanced, the least square means will be identical to the raw (observed) means.

linear kinetics A model in which the transfer rates are first order.

linear regression

A model relating an independent variable to dependent variables such that the unknown parameters enter into the model linearly.

In the simplest case of regression, a straight line is fit to the data. The inter-cept and slope are determined by the method of least squares. The slope and intercept are called coefficients, or parameters, of the model.

LLOQ Lower limit of quantification, the concentration whose lower bound (of vari-ability in the assay) includes zero. Analyte may be detectable below this con-centration even though it is not quantifiable.

lower constraint

Lower boundary on possible values of a model parameter.

M

macro rate constants

Compartmental models involving first order kinetics can be written as a sum of exponentials. The parameters associated with the sum of exponentials are called macro rate constants and are functions of the underlying micro rate constants.

max The maximum value.

mean The arithmetic average.

mean of the logs

Arithmetic average of the logs of the Ys.

mean square The variance is normally a function of 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.


562

A

It is possible to use a specified value other than the residual mean square in the estimates of the variances and standard deviations. The value specified here replaces the residual sum of squares in the estimates of variances and standard deviations.

method In compartmental modeling using a command file, the METHOD command specifies the type of fitting algorithm WinNonlin is to use in fitting a model. The argument N takes the values in table A-1.

In noncompartmental analysis, the METHOD command specifies the method to be used to compute area under the curve (AUC). The argument N takes on the values shown in table A-2.

method (scripting)

A method in the Scripting Language is a set of computer code that performs functionality on a particular object or engine. In short, it invokes an action. For example, the Method 'LOAD' causes an associated data files (an Object) to be loaded. The Method 'RUN' causes an associated PK Model (Engine) to run the model.

Table A-1. Compartmental modeling methods

1 Nelder-Mead Simplex

2 (default) Levenberg and Hartley modification of Gauss-Newton

3 Hartley modification of Gauss-Newton

Table A-2. Noncompartmental analysis methods

1 Linear/Log Trapezoidal Method–Linear trapezoidal rule up to Tmax, and log trapezoidal rule for the remainder of the curve

2 (default) Linear trapezoidal Method with linear interpolation

3 Linear Up/Log Down Method–Linear trapezoidal rule any time that the concentration data is increasing and the logarithmic trapezoidal rule when the concentra-tion data is decreasing

4 Linear trapezoidal method with linear/log interpolation

GlossaryN

563

A

Michaelis-Menten

A type of model often employed for models involving nonlinear kinetics. The Michaelis-Menten equation is:

micro rate constants

Transfer rates associated with a compartmental model.

min The minimum value.

minimization The Minimization field on the Model Options dialog box allows the user to specify the minimization method to be used when doing modeling. See Method.

MM.LIB The ASCII library file containing the Michaelis-Menten models. To use a model from this library, select ASCII Model from the WinNonlin Models sec-tion of the Library of Models dialog box, and indicate the model number (301-304). This file is provided in the WinNonlin installation in the \LIB directory.

model size Model size may range from 1 to 64. The default size is 4. Model size is only applicable when using ASCII models. Model size sets default memory requirements.

MRT Mean Residence Time is the average amount of time a particle remains in a compartment or system.

MRTINF Mean Residence Time when the drug concentration profile is extrapolated to infinity. This can be estimated from single dose data or steady state data.

MRTlast Mean Residence Time when the drug concentration profile is not extrapolated to infinity, but rather is based on values up to and including the last measured concentration.

MRTlast = AUMClast / AUClast

N

N The number of observations with non-missing data.

Nmiss The number of observations with missing data.

V Vmax C× Km C+( )⁄=

MRT AUMC AUC⁄=


564

A

Nelder-Mead Simplex algorithm

A model fitting algorithm that does not require the estimated variance—cova-riance matrix as part of its algorithm. It often performs very well on ill-condi-tioned data sets (data sets that do not contain enough information to precisely estimate all of the parameters in the model). When used to fit a system of dif-ferential equations, it can be extremely slow unless the model has been com-piled.

nested factors In a nested classification, unlike a crossed classification, the levels of the nested factor are unrelated to one another and are nested within a level of another factor.

For example, in a crossover study, Subjects are assigned to Treatment Sequences. Subjects are not crossed with Sequences, because the subjects within one sequence are unrelated to the subjects within another sequence.

Nested factors are included in a LinMix or bioequivalence model using paren-theses:

Subject(Sequence)

See also crossed factors.

Nobs The number of observations.

nominal time The time specified in the protocol for a dose or observation—which may dif-fer from the actual time that a dose or observation was taken.

noncompart-mental analy-sis

Noncompartmental, or Model Independent Analysis describes the concentra-tion-time curve by estimating noncompartmental parameters such as: area under the curve (AUC), Tmax, Cmax, and Lambda z (the rate constant associ-ated with the terminal elimination phase), among others.

Noncompartmental parameters are estimated using the Linear or Linear/Log trapezoidal rule. If lambda z can be estimated, then the noncompartmental parameters will be extrapolated to infinity.

nonlinear kinetics

Kinetics that can be modeled by nonlinear differential equations, for example,

V cdtd

----- VmaxCKm C+-----------------=

GlossaryO

565

A

nonlinear model

In nonlinear models, at least one of the parameters appears as other than a coefficient of an independent variable. One such model is the sum of two or more exponentials, such as Y = A1*exp(-B1*X) + A2*exp(-B2*X).

A nonlinear model is one for which one or more of the partial derivatives with respect to the model parameters involve model parameters. Note that nonlin-ear models may arise from compartmental models having either linear or non-linear kinetics.

nonlinear regression

The process of fitting nonlinear models to data.

number of predicted values

An option of the PK Settings tab in the Model Options dialog box which allows the specification of the number of points in the Predicted Data file. Use this option to create a data set to be used to plot a smooth curve. The mini-mum allowable value is 10 and the maximum is 20,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 equa-tions the default value is 1000.

The default for user models is the number of data points. This value may be increased only if the model has only one independent variable.

O

ODBC Open Database Connectivity. A standard for data exchange, in common use on Microsoft Windows platforms. It is an application programming interface (API) for database access that uses Structured Query Language (SQL) as its database access language.

object In object-oriented programming languages, objects are described by Proper-ties, and acted upon by Methods. In WinNonlin, there are five objects: Data objects, Text objects, Model objects, Graph objects, and WinNonlin itself.

P

partial tests LinMix tests of whether each model term contributes to the fit after all other model terms have been included. Partial tests are invariant to the model speci-fication order.


566

A

percentiles The pth percentile divides the distribution at a point where p percent of the distribution are below this point.

pharmacody-namic (PD) models

Models that are used to model effect as a function of a drug concentration.

pharmacoki-netic (PK) models

Models that are used to model drug concentrations as a function of time.

PK / PD Link A PK/PD Link model uses the pharmacokinetic concentration data to estimate concentrations at an effect site which are then used to model the pharmacody-namics.

planar confidence interval

A confidence interval obtained from the tangent planes to the joint confidence ellipsoid of all the parameter estimates.

power As employed in WinNonlin's Bioequivalence Wizard, this is the probability of detecting a difference greater than or equal to a specified percentage of the reference mean.

profile A set of observed data to be fit at one time, producing one set of individual model parameters. A profile is identified as data records with a given, unique set of values for all sort variables.

profile header A Header that appears at the top of the first page of every profile in the ASCII output. The Profile Header may contain the processing time and/or sort infor-mation.

propagate final estimates

When this option is selected, the final estimates from each sort level are used as the initial estimates for the next sort level. This option may be used with each of the three parameter calculation methods.

property Every object in the Scripting Language has properties that define how the object should appear and interact with the user. It also sets a value for an object or engine. In short, properties are attributes or characteristics of an object.

GlossaryQ

567

A

Q

R

random effect also known as covariance parameters, distinguish a linear mixed effects model from a standard linear model. In general, random effects parameters are additional unknown random variables assumed to impact the variability of the data. The variances of the random effects parameters, commonly known as variance components, become the covariance parameters for this structure.

range The maximum minus the minimum value.

rank Rank of the matrix of partial derivatives. If the matrix is of full rank, Rank= # of parameters. If the Rank is less than the number of parameters, then there is not enough information contained in the data to estimate all of the parameters in the model.

regressors In a LinMix model, regressor variables or covariates are independent vari-ables that employ values from a continuous set (e.g. temperature, body weight), rather than categories.

relative actual time

(PKS) The time that observations or doses really happened, as opposed to rel-ative nominal time. See also relative nominal end time.

relative actual end time

(PKS) Times when infusion doses actually ended, as opposed to relative nom-inal end time. See also relative nominal end time.

relative error bars

Relative error information is plotted as an offset from the original data value.

relative nominal time

(PKS) Scheduled dose and observation times, as set in the study protocol. Compare with relative actual time. See also relative nominal end time.

relative nominal end time

(PKS) Times when infusion doses were scheduled to end, as set in the study protocol. Compare with relative actual end time. See also relative nominal end time.

relative time Elapsed time since the first dose or the beginning of the study, period or phase.

residuals Observed minus predicted values, where the predicted values come from fit-ting the specified model.


568

A

route of administration

The dose administration as Extravascular, Bolus Injection or Constant Infu-sion.

S

S Standard error of the weighted residuals: where WRSS is the weighted residual sums of squares, and DF is the number of observa-tions minus the number of zero weights and the rank of the variance/covari-ance matrix.

sampling times

The actual times at which the concentration or effects are observed.

scenario (PKS) A structural model, initial parameters, and/or statistical tests to be applied to a data set for fitting or analysis. See also study.

SBC Schwartz Bayesian Criteria. A measure of goodness of fit based on maximum likelihood. When comparing several models for a given set of data, the model associated with the smallest value of SBC is regarded as giving the best fit out of that set of models. Schwartz Criteria is only appropriate for use when com-paring models using the same weighting scheme.

For LinMix, the SBC calculation is:

where is the restricted log-likelihood function evaluated at final esti-mates and ; r is dim(x); s is the number of parameters; and N is the num-ber of observations.

script file A script file (*.psc, *.wsc) is an ASCII file that contains WinNonlin scripting code.

SD The standard deviation.

SD of the Logs

Standard deviation of the logs of the Ys.

SE The standard error.

S WRSS( ) DF( )⁄=

SBC NOBS WRSS( )log× NOBS( )log NPARM×+=

SBC 2– LR s N r–( )log+=

LRβ θ

GlossaryS

569

A

secondary parameters

Parameters that are functions of the primary model parameters. For example, AUC and half lives are secondary parameters.

The standard errors of the secondary parameters are obtained by computing the linear term of a Taylor series expansion of the estimates. As such, they represent about the third level of approximation and must be regarded with caution.

SE - Yhat Standard error of Predicted Y.

sequential tests

Tests each model term for significant improvement in fit, in sequence. Depends upon the order that model terms are written.

sigmoid Denotes the “S” shaped nature of certain models.

simulations Given a model and time points, requesting WinNonlin to perform a simulation causes predicted values to be generated. These simulations can be used to: view the shape of the model being simulated, predict concentration as a func-tion of varying doses or regimens, or aid in determining optimal sampling times.

sort variables A separate analysis or plot is done for each level of the sort variable(s). If gen-der and smoking are sort variables, a separate set of analysis results or plots will be created for each of female non-smokers, male non-smokers, female smokers and male smokers.

stripping dose Dose associated with initial parameter estimates for macro constant models. For models that can be written as a sum of exponentials, dose does not explic-itly appear in the model. Rather, the macro constants are themselves a func-tion of dose. Thus, when fitting macro constant models where the user specifies the initial estimates, the user must specify the dose associated with the macro constants. For single dose macro constant models, where WinNon-lin is requested to determine initial parameter estimates by curve stripping, the stripping dose is identical to the administered dose.

structural model

The set of functions defining the shape of a model, i.e., a structural PK, PD, or PK/PD model. It does not include parameter distributions.

study (PKS) A study consists of a collection of data that can include observations, dosing, and protocols and one or more scenarios.

summary variables

The variable(s) for which descriptive statistics will be calculated.


570

A

T

table definition file

A table definition file contains information used to format a table. A table def-inition file (.TDF) stores a user-defined table format that can be used repeat-edly. See also “Table definition files” on page 204.

Tau (τ) The (assumed equal) dosing interval for steady-state data.

TI The length of infusion.

Tmax The time of peak concentration.

Tmin For steady-state data: time of minimum concentration based on samples col-lected during a dosing interval.

transform Performs a mathematical operation on the data. The transformations available in WinNonlin include: 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, eX, 1/X, Xn, X*n, X/n, X+n, X-n. Some of these require only the column that is to be transformed, while others require the input of a con-stant, and still others require that a second column be specified.

treatment A combination of one or more drugs given at specific doses and time(s).

treatment contrasts

See contrasts.

U

univariate confidence interval

A confidence interval based on standard error. The univariate confidence interval does not take into account correlations with other parameters.

up variable This option appears on the Error Bar tab of the Chart Wizard. It allows the specification of a variable to be used as up error bar values. This data will appear as error bars in the upward direction of the X/Y data points. If a group variable exists, error bars will be placed at each of the subsetted data points.

upper constraint

Upper boundary on possible values of a model parameter.

user libraries Libraries of models defined by the user.

GlossaryV

571

A

V

V Volume of distribution of the central compartment. This is also denoted VC.

variance The variance, v, in descriptive statistics is defined by the expression:

Note: .

vars These are variables that go into the body of the table. When summary statis-tics are requested, they will be computed for these variables.

VIF Variation Inflation Factor. VIF is the multiplier of the residual mean square that is used in deriving the asymptotic variance of the parameter estimates. The VIF is useful when performing simulations, to determine optimal experi-mental designs. A smaller value is better.

Vmax Theoretical maximum rate of process described by Michaelis-Menten kinet-ics.

Vss Volume of distribution at steady state: Vss = MRT * CL, where MRT = Mean Residence Time and CL= total body clearance.

Vss For steady-state data: an estimate of the volume of distribution at steady-state. (Not computed for Model 200). Vss = MRT * CL

VZ, VZ/F Volume of distribution based on the terminal phase. For extravascular models, the fraction of dose absorbed cannot be estimated. Therefore, Volume for these models is actually Volume/F, where F is the fraction of dose absorbed.

W

weight variable (LinMix)

A variable from the Variable Collection can serve as the Weight Variable. The Weight Variable must be a column with numeric data. The Weight Variable should not be a classification variable. It can be a regressor. It can also be used in the model. It is used to compensate for observations having different vari-ances. The weight variable should have values that are proportional to recip-rocals of variances. When using a weight variable, the whole row of data gets multiplied by the square root of the corresponding weight.

v Yi Y–( )2 n 1–( )⁄

i 1=

n

∑=

SD v=


572

A

weighted computed Y

Square root of the weight times Y Predicted.

weighted predicted Y

Predicted Y times the square root of the weight.

weighted residual Y

Residual Y times the square root of the weight.

weighted - SS Weighted Sum of Squared Residuals. See also WRSS.

weighting Scheme

Allows weighting such as Uniform weighting, 1/Y, 1/(Y*Y), 1/SQRT(Y) or Weights with Data.

Westlake confidence interval

Confidence intervals that are constrained to be symmetric about 100%.

workspace A workspace can contain all of the child windows (and files represented in them) for a WinNonlin project. The entire project can be saved with a single command and later reopened, again with a single command. When the work-space file is opened, all of the child windows are opened and positioned as they had been.

WRSS Weighted residual sums of squares, an estimate of the variance of the residu-als. This is the quantity WNL minimizes during modeling.

X

X variable The independent variable to be used in PK modeling or Noncompartmental analysis. Normally this variable is a measure of time.

Y

Y variable The dependent variable to be used PK modeling or Noncompartmental analy-sis. Normally this variable is Concentration.

573

Appendix B

WinNonlin Model Libraries

Parameterization and equations for WinNonlin compiled and ASCII models

WinNonlin is distributed with an extensive library of models, including mod-els for most of the commonly used one, two and three compartment pharma-cokinetic (PK), pharmacodynamic (PD), link, indirect responseA, Michaelis-Menten, and noncompartmental analyses. The following models are included in the library of compiled models and detailed in the sections below, follow-ing the syntax noted under “Notation and conventions” on page 574.

Some of the libraries are provided as ASCII (text) models; others are com-piled into machine language. Each PK and PD model is included in both ASCII and compiled forms. Compiled models run faster. The ASCII versions provide the user with examples and starting templates for custom models.

Note: When using the ASCII models, be sure to examine the ASCII code to ascer-tain what dosing constants need to be created.

A. Dayneka NL, Garg V, Jusko W (1993); Jusko W (1990); Nagashima R, O’Reilly RA, Levy G (1969).

Table B-1. Model libraries

Model Compiled ASCII“Pharmacokinetic models” on page 575 Yes Yes“Pharmacodynamic models” on page 596 Yes Yes“PK/PD link models” on page 602 Yes No“Indirect response models” on page 605 Yes No“Michaelis-Menten models” on page 609 No Yes“Simultaneous PK/PD link models” on page 612 No Yes


574

B

Although WinNonlin can be used to estimate the parameters in any system of nonlinear equations, these libraries contain classical PK and PD models. Note that it is possible to create custom libraries of models. The means of doing this is described under “User Models” on page 273.

Notation and conventionsWinNonlin Model Libraries number the central compartment 1, and the exte-rior to the compartments, zero. First-order rate constants are expressed as Kij, meaning the rate from Compartment i to Compartment j. Thus, K01 is the rate at which drug enters the central compartment from outside the system, and K10 is the rate at which drug leaves the system from the central compartment.

For some models there are secondary parameters such as half-lives and areas that are computed from the estimates of the primary parameters of the model. WinNonlin computes estimates and estimated standard errors of these second-ary parameters. For the two and three-compartment models some pharmacok-ineticists prefer to estimate the micro rate constants (Kij) as primary parameters; others prefer to estimate the macro rate constants (alpha and beta) as the primary parameters of the models. The WinNonlin libraries contain both forms of these models. Thus, Model 11, for example, is the two-compart-ment model with first-order input and alpha and beta as secondary parameters and Model 13 is the same model with alpha and beta as primary parameters and the rate constants K01, K12, and K21 as secondary parameters.

Since these models are normally used to model concentration as a function of time, t is the independent variable, and C(t) is the mathematical equation being fit to the observations. All of the models require the dose(s) and time(s) of dosing to be input as a constant(s). In addition, for those models defined in terms of the macro constants, the dose associated with the initial parameter estimates (this dose is hereafter referred to as the stripping dose) must also be input. The reason for this is as follows. Such models can be written as:

Note that the dose, D, does not appear directly in the expression for C(t). Instead, the intercepts, {Ai}, are functions of D (as well as the micro con-stants). In order for WinNonlin to be able to fit multiple dose data to macro constant models, the stripping dose (D) must be input. WinNonlin actually defines the macro constants model as:

C t( ) Ai αi– t×( )exp×∑=

WinNonlin Model LibrariesPharmacokinetic models

575

B

where Dj denotes the jth administered dose. Writing the model in this way enables WinNonlin to fit multiple dose data for the macro constant models.

With the exception of the Noncompartmental Analysis “models” WinNonlin models assume that the Time variable has been coded such that the time of the first dose is 0. This applies whether using WinNonlin for modeling or simula-tion.

The factor that changes amount to concentration is denoted as V, volume. In absorption models there is no way to estimate both volume and fraction of dose absorbed, so both of these are included in V (thus V/F is estimated where F is the fraction of the dose that was absorbed).

The presentation of the mathematical equations of the models follows FOR-TRAN notation. For example, EXP(-K01*t) is the constant e with an expo-nent of the negative product of time, t and the rate constant K01.

The models with first-order input are presented with and without a lag time. Since this amounts only to a shift on the time axis, the lag time is not explic-itly shown in the expression for C(t), and the estimated Tmax should have the lag time added to it for those models which include a lag time.

Note: For discussion of one and two-compartment models with first-order exchange see Gibaldi and Perrier (1982).

Pharmacokinetic modelsThe WinNonlin Model Libraries include 19 pharmacokinetic (PK) models. Each is available in both compiled and ASCII text forms.

C t( ) DjAiD----- αi t×( )exp××

j∑=

Model Input Number of compartments

Parameterization Lag time

Elimination rate

Model 1 IV-bolus 1 - no 1st orderModel 2 IV-infusion 1 - no 1st orderModel 3 1st order 1 - no 1st orderModel 4 1st order 1 - yes 1st orderModel 5 1st order 1 K10 = K01 no 1st order

n


576

B

Note: All models except models 15-17 accept multiple dose data.

The models shown in this section give equations for compartment 1 (central).

ASCII models and files

WinNonlin PK models are available as compiled models, and also in the ASCII library files PK1.LIB - PK10.LIB, as follows.

Model 6 1st order 1 K10 = K01 yes 1st orderModel 7 IV-bolus 2 micro no 1st orderModel 8 IV-bolus 2 macro no 1st orderModel 9 IV-infusion 2 micro no 1st orderModel 10 IV-infusion 2 macro no 1st orderModel 11 1st order 2 micro no 1st orderModel 12 1st order 2 micro yes 1st orderModel 13 1st order 2 macro no 1st orderModel 14 1st order 2 macro yes 1st orderModel 15 IV-bolus plus

IV-infusion1 micro no 1st order

Model 16 IV-bolus plus IV-infusion

2 micro no 1st order

Model 17 IV-bolus plus IV-infusion

2 macro no 1st order

Model 18 IV-bolus 3 macro no 1st orderModel 19 IV-infusion 3 macro no 1st order

Model Input Number of compartments

Parameterization Lag time

Elimination rate

Model # File name1, 2 PK1.LIB3, 4 PK2.LIB5, 6 PK3.LIB7, 8 PK4.LIB9, 10 PK5.LIB11, 12 PK6.LIB13, 14 PK7.LIB15, 16 PK8.LIB17, 18 PK9.LIB19 PK10.LIB


577

B

PK models

Model 1 One compartment with bolus input and first-order output

Estimated parameters: (1) V = Volume(2) K10 = elimination rate

Constants in input: (1) # doses(2) dose 1(3) time of dose 1(Repeat 2-3 for additional doses)

Secondary parameters: (1) AUC = D/V/K10(2) K10 half-life(3) Cmax = D/V(4) CL(5) AUMC(6) MRT(7) Vss

Clearance primary parameters: (1) V(2) CL

Secondary Parameters: (1) AUC(2) K10 half-life(3) Cmax(4) K10(5) AUMC(6) MRT(7) VSS

( ) ( )C T DV K T= ∗ − ∗exp 10


578

B

Model 2 One-compartment with constant IV input and first-order absorption

where TI = Length of infusion, TSTAR = T-TI for T>TI, and TSTAR = 0 for T≤TI

Estimated parameters: (1) V = Volume(2) K10 = elimination rate

Constants in input: (1) # doses(2) dose 1(3) start time 1(4) end time 1(Repeat 2-4 for additional doses)

Secondary parameters: (1) AUC = D/V/K10(2) K10 half-life(3) Cmax = C(TI)(4) CL(5) AUMC(6) MRT(7) Vss


Secondary Parameters: (1) AUC(2) K10 half-life(3) Cmax(4) K10(5) AUMC(6) MRT

( ) ( ) ( ) ( )( )C T DTI V K

K TSTAR K T= ∗∗

∗ − ∗ − − ∗1

1010 10exp exp


579

B

Model 3 One-compartment with first-order input, first-order output, and no lag time

(7) Vss

Estimated parameters: (1) V_F(2) K01 = absorption rate(3) K10 = elimination rate


Secondary parameters: (1) AUC = D/V/K10(2) K01 half-life(3) K10 half-life(4) CL_F (5) Tmax = time of maximum concentration

(6) Cmax = maximum concentration = C(Tmax)

Clearance Primary parameters: (1) V_F(2) K01(3) CL_F

Secondary Parameters: (1) AUC(2) K01 half-life(3) K10 half-life

( ) ( ) ( ) ( )( )C T D KV K K

K T K T=∗

∗ −∗ − ∗ − − ∗

0101 10

10 01exp exp

ln K01 K10⁄( )K01 K10–( )

----------------------------------=


580

B

Model 4 One-compartment with first-order input, first-order output, and a lag time

Everything as in Model 3, with an additional estimated parameter.

Estimated parameter: (4) Tlag = lag time

Clearance parameters the same as in Model 3.

Model 5 One-compartment with equal first-order input and output, no lag time

(4) K10(5) Tmax(6) Cmax

Estimated parameters: (1) V_F(2) K= absorption rate, K01 = elimination rate, K10


Secondary parameters: (1) AUC = D/V/K(2) K half-life(3) CL_F (4) Tmax = time of maximum concentration = 1/K (5) Cmax = maximum concentration= C(Tmax)

Clearance Primary Parameters: (1) V_F(2) CL_F

( ) ( )C T DV K T K T= ∗ ∗ ∗ − ∗exp


581

B

Model 6 One-compartment with equal first-order input and first-order output and a lag time



Clearance parameters the same as in Model 5.

Model 7 Two-compartment with bolus input and first-order output; micro-constants as primary parameters

where

and -ALPHA and -BETA (ALPHA > BETA) are the roots of the quadratic equation: (r*r + (K12 + K21 + K10)*r + K21*K10 = 0).

Secondary Parameters: (1) AUC(2) K half-life(3) K(4) Tmax(5) Cmax

Estimated parameters: (1) V1 = Volume1(2) K10 = elimination rate(3) K12 = transfer rate, 1 to 2

( ) ( ) ( )C T A ALPHA T B BETA T= ∗ − ∗ + ∗ − ∗exp exp

( ) ( )A DV ALPHA K ALPHA BETA= ∗ − −21

( ) ( )B DV BETA K ALPHA BETA= − ∗ − −21


582

B

Model 8 Two-compartment with bolus input and first-order output; macro-constants as primary parameters

(4) K21 = transfer rate, 2 to 1


Secondary parameters: (1) AUC = D/V/K10 (9) Cmax = D/V(2) K10 half-life (10) CL(3) ALPHA (11) AUMC(4) BETA (12) MRT(5) ALPHA half-life (13) Vss(6) BETA half-life (14) V2(7) A (15) CLD2(8) B

Clearance Primary Parameters: (1) V1(2) CL(3) V2(4) CLD2

Secondary Parameters (1) AUC (9) Cmax(2) K10 half-life (10) K10(3) ALPHA (11) AUMC(4) BETA (12) MRT(5) ALPHA half-life (13) Vss(6) BETA half-life (14) K12(7) A (15) K21(8) B


583

B

Clearance parameters are not available on Model 8.

Model 9 Two-compartment with constant IV input and first-order output; micro-constants as primary parameters

Estimated parameters: (1) A(2) B(3) ALPHA(4) BETA

Constants in input: (1) stripping dose(2) # doses(3) dose 1(4) time of dose 1(Repeat 3-4 for additional doses)

Secondary parameters: (1) AUC = A/ALPHA + B/BETA (9) V1(2) K10 half-life (10) CL(3) ALPHA half-life (11) AUMC(4) BETA half-life (12) MRT(5) K10 (13) Vss(6) K12 (14) V2(7) K21 (15) CLD2(8) Cmax

( ) ( ) ( )C T A ALPHA T B BETA T= ∗ − ∗ + ∗ − ∗exp exp

( ) ( ) ( )( )( ) ( )( )

C T A ALPHA T ALPHA TSTAR

B BETA T BETA TSTAR

= − ∗ − − ∗

+ − ∗ − − ∗1

1

exp exp

exp exp


584

B


and -ALPHA and -BETA (ALPHA > BETA) are the roots of the quadratic equation: r*r + (K12 + K21 + K10)*r + K21*K10 = 0.

Note: A, B are the zero time intercepts following an IV injection

Estimated parameters: (1) V1 = Volume1(2) K10 = elimination rate(3) K12 = transfer rate, 1 to 2(4) K21 = transfer rate, 2 to 1

Constants in input: (1) # doses(2) dose 1(3) start time 1(4) end time 1(Repeat 2-4 for additional doses)

Secondary parameters: (1) AUC = D/V/K10 (9) Cmax = C(TI)(2) K10 half-life (10) CL(3) ALPHA (11) AUMC(4) BETA (12) MRT(5) ALPHA half-life (13) Vss(6) BETA half-life (14) V2(7) A (15) CLD2(8) B

( )( )

( )( )

A DTI V

K ALPHAALPHA BETA ALPHA

B DTI V

K BETAALPHA BETA BETA

1

1

21

21

=∗

−− ∗

= −∗

−− ∗

Clearance Primary Parameters: (1) V1(2) CL(3) V2


585

B

Model 10 Two-compartment with constant IV input and first-order output; macro-constants as primary parameters


(4) CLD2

Secondary Parameters: (1) AUC (9) Cmax(2) K10 half-life (10) K10(3) ALPHA (11) AUMC(4) BETA (12) MRT(5) ALPHA half-life (13) Vss(6) BETA half-life (14) K12(7) A (15) K21(8) B

Estimated parameters: (1) V1(2) K21

( ) ( ) ( )( )( ) ( )( )


B BETA T BETA TSTAR

= − ∗ − − ∗

+ − ∗ − − ∗1

1

exp exp

exp exp

( )( )

( )( )

A DTI V

K ALPHAALPHA BETA ALPHA

B DTI V

K BETAALPHA BETA BETA

1

1

21

21

=∗

−− ∗

= −∗

−− ∗


586

B

Note: NOTE: A, B are the zero time intercepts following an IV injection.

Clearance parameters are not available in Model 10.

Model 11 Two-compartment with first-order input, first-order output, no lag time and micro-constants as primary parameters

(3) ALPHA(4) BETA

Constants in input: (1) # doses(2) dose 1(3) start time of dose 1(4) end time of dose 1(Repeat 2-4 for additional doses)

Secondary parameters: (1) K10 (9) Cmax(2) K12 (10) CL(3) K10 half-life (11) AUMC(4) AUC (12) MRT(5) ALPHA half-life (13) Vss(6) BETA half-life (14) V2(7) A (15) CLD2(8) B


587

B

and -ALPHA and -BETA (ALPHA > BETA) are the roots of the quadratic equation: r*r + (K12 + K21 + K10)*r + K21*K10 = 0.

Estimated parameters: (1) V1_F(2) K01 = absorption rate(3) K10 = elimination rate(4) K12 = transfer rate, 1 to 2(5) K21 = transfer rate, 2 to 1

Constants in input: (1) # doses(2) dose #1(3) time of dose #1(Repeat 2-3 for additional doses)

Secondary parameters: (1) AUC = D/V/K10 (8) A(2) K01 half-life (9) B(3) K10 half-life (10) CL_F (4) ALPHA (11) V2_F (5) BETA (12) CLD2_F(6) ALPHA half-life (13) Tmaxa

(7) BETA half-life (14) Cmaxb

Clearance Primary Parameters: (1) V1_F(2) K01(3) CL_F(4) V2_F

( ) ( ) ( ) ( )C T A ALPHA T B BETA T C K T= ∗ − ∗ + ∗ − ∗ + ∗ − ∗exp exp exp 01

AD

V K K ALPHA

ALPHA BETA ALPHA K=

∗ ∗ −

− ∗ −

01 21

01

( )

( ) ( )

BD

V K K BETA

ALPHA BETA BETA K=

− ∗ ∗ −

− ∗ −

01 21

01

( )

( ) ( )

CD

V K K K

BETA K ALPHA K=

∗ ∗ −

− ∗ −

01 21 01

01 01

( )

( ) ( )

where


588

B

Model 12 Two-compartment with first-order input, first-order output, lag time and micro-constants as primary parameters



Model 13 Two-compartment with first-order input, first-order output, no lag time and macro-constants as primary parameters

(5) CLD2_F

Secondary Parameters: (1) AUC (8) A(2) K01 half-life (9) B(3) K10 half-life (10) K10(4) ALPHA (11) K12(5) BETA (12) K21(6) ALPHA half-life (13) Tmax(7) BETA half-life (14) Cmax

a. Estimated for the compiled (internal) library only.

b. Estimated for the compiled (internal) library only.

Estimated parameters: (1) A(2) B(3) K01 = absorption rate(4) ALPHA(5) BETA(Note: C = -(A + B))

Constants in input: (1) stripping dose

C T A ALPHA T B BETA T C K T( ) exp( ) exp( ) exp( )= ∗ − ∗ + ∗ − ∗ + ∗ − ∗01


589

B

Clearance parameters are not available for Model 13.

Model 14 Two-compartment with first-order input, first-order output, lag time and macro-constants as primary parameters


Estimated parameter: (6) TLAG = lag time

Clearance parameters are not available for model 14.

Model 15 One compartment with simultaneous bolus IV and constant IV infusion

(2) # doses(3) dose 1(4) time of dose 1(Repeat 3-4 for additional doses)

Secondary parameters: (1) K10 (8) BETA half-life(2) K12 (9) V1_F(3) K21 (10) CL_F (4) AUC = D/V/K10 (11) V2_F (5) K01 half-life (12) CLD2_F(6) K10 half-life (13) Tmaxa

(7) ALPHA half-life (14) Cmaxb

a. Estimated for the compiled (internal) library only.

b. Estimated for the compiled (internal) library only.


590

B

where TSTAR = T-TI for T>TI and TSTAR = 0 for T≤TI

Model 16 Two compartment with simultaneous bolus IV and constant infusion input, micro constants as primary parameters

Estimated parameters: (1) V = Volume(2) K10

Constants in input: (1) bolus dose(2) IV dose(3) length of infusion = TI

Secondary parameters: (1) CL (2) K10 half-life


Secondary parameters: (1) K10(2) K10 half-life

C T DV K TB

B( ) exp( )= ∗ − ∗10

C T DTI V K

K TSTAR K TIVIV( ) (exp( ) exp( ))= ∗

∗∗ − ∗ − − ∗

110

10 10

C T C T C TB IV( ) ( ) ( )= +


591

B


Estimated parameters: (1) V1(2) K10(3) K12(4) K21

Constants in input: (1) bolus dose(2) IV dose(3) length of infusion (= TI)

Secondary parameters: (1) K10 half-life (6) A(2) ALPHA (7) B(3) BETA (8) CL(4) ALPHA half-life (9) V2(5) BETA half-life (10) CLD2

C T A ALPHA T B BETA TB ( ) exp( ) exp( )= ∗ − ∗ + ∗ − ∗1 1

A DV

ALPHA KALPHA BETA

B1

21= −

−* ( )

( )

B DV

BETA KALPHA BETA

B1

21= − −

−( )

( )

where

( ) ( ) ( )( )( ) ( )( )


B BETA T BETA TSTARIV = ∗ − ∗ − − ∗

+ ∗ − ∗ − − ∗2

2

exp exp

exp exp

( )( )A D

TI VK ALPHA

ALPHA BETA ALPHAIV

2

21=

∗−

− ∗where

( )( )B D

TI VK BETA

ALPHA BETA BETAIV

2

21=

−∗

−− ∗

( ) ( ) ( )C T C T C TB IV= +


592

B

Model 17 Two compartment with simultaneous bolus IV and constant infusion input and macro constants as primary parameters

CB (T) = A*exp(-ALPHA*T) + B*exp(-BETA*T)

CIV (T) = (A / ALPHA) * (exp(–ALPHA*TSTAR) – exp(–ALPHA*T) )

+ (B / BETA) * (exp(–BETA*TSTAR) – exp(–BETA*T) )


Clearance primary parameters: (1) V1(2) CL(3) V2(4) CLD2

Secondary parameters: (1) K10 half-life (6) A(2) ALPHA (7) B(3) BETA (8) K10(4) ALPHA half-life (9) K12(5) BETA half-life (10) K21

Estimated parameters: (1) A(2) B(3) ALPHA(4) BETA

( ) ( ) ( )C T C T C TB IV= +


593

B


Model 18 Three-compartment with bolus input, first-order output and macro constants as primary parameters

Constants in input: (1) stripping dose(2) bolus dose(3) IV dose(4) length of infusion (= TI)

Secondary parameters: (1) K10 (6) BETA half-life(2) K12 (7) V1(3) K21 (8) CL(4) K10 half-life (9) V2(5) ALPHA half-life (10) CLD2

Estimated parameters: (1) A(2) B(3) C(4) ALPHA(5) BETA(6) GAMMA

Constants in input: (1) stripping dose(2) # doses(3) dose 1(4) start time of dose 1

( ) ( ) ( ) ( )C T A ALPHA T B BETA T C GAMMA T= ∗ − ∗ + ∗ − ∗ + ∗ − ∗exp exp exp


594

B


Model 19 Three compartment model with constant IV infusion; macro constants as primary parameters

(Repeat 3-4 for additional doses)

Secondary parameters: (1) Cmax (11) GAMMA half-life(2) V1 (12) AUC(3) K21 (13) CL(4) K31 (14) AUMC(5) K10 (15) MRT(6) K12 (16) Vss(7) K13 (17) V2(8) K10 half-life (18) CLD2(9) ALPHA half-life (19) V3(10) BETA half-life (20) CLD3


595

B


Estimated parameters: (1) V1(2) K21(3) K31(4) ALPHA(5) BETA(6) GAMMA

Constants in input: (1) # doses(2) dose 1(3) start time of dose 1(4) end time of dose 1(Repeat 2-4 for additional doses)

Secondary parameters: (1) Cmax (11) GAMMA half-life(2) K10 (12) AUC(3) K12 (13) CL(4) K13 (14) AUMC(5) A (15) MRT(6) B (16) Vss(7) C (17) V2(8) K10 half-life (18) CLD2(9) ALPHA half-life (19) V3

( ) ( ) ( )( )( ) ( )( )( ) ( )( )

C T A ALPHA TSTAR ALPHA T

B BETA TSTAR BETA T

C GAMMA TSTAR GAMMA T

= − ∗ − − ∗

+ − ∗ − − ∗

+ − ∗ − − ∗

1

1

1

exp exp

exp exp

exp exp

( ) ( ) ( )( ) ( )

( ) ( ) ( )( ) ( )

( ) ( ) ( )( ) ( )

AD TI K ALPHA K ALPHA

V ALPHA GAMMA ALPHA BETA ALPHA

BD TI K BETA K BETA

V BETA GAMMA BETA ALPHA BETA

CD TI K GAMMA K GAMMA

V GAMMA ALPHA GAMMA BETA GAMMA

1

1

1

21 31

21 31

21 31

=∗ − ∗ −

∗ ∗ − ∗ −

=∗ − ∗ −

∗ ∗ − ∗ −

=∗ − ∗ −

∗ ∗ − ∗ −


596

B


Note: NOTE: A, B, C are the zero time intercepts following an IV injection.

Pharmacodynamic modelsLoad and set up pharmacodynamic (PD) models as described under “Loading the model” on page 247 and “Model properties” on page 249. Available PD models in the WinNonlin Model Libraries include the following.

ASCII library

These models are available as compiled models and also as ASCII library files. The ASCII library files are stored in the WINNONLN\LIB subdirectory.

(10) BETA half-life (20) CLD3

Model Description C=0 C=infinityModel 101 Simple Emax Model 0 EmaxModel 102 Simple Emax Model E0 EmaxModel 103 Inhibitory Effect Emax Model Emax 0Model 104 Inhibitory Effect Emax Model Emax E0Model 105 Sigmoid Emax Model 0 EmaxModel 106 Sigmoid Emax Model E0 EmaxModel 107 Inhibitory Effect Sigmoid Emax Model Emax 0Model 108 Inhibitory Effect Sigmoid Emax Model Emax E0

Model # File name101, 102 PK51.LIB103, 104 PK52.LIB105, 106 PK53.LIB107, 108 PK54.LIB

WinNonlin Model LibrariesPharmacodynamic models

597

B

Models

Notation

Model 101 Simple Emax model

Term DefinitionEmax Maximum effectE0 Baseline effectEC50 Drug concentration required to produce 50% of the drug-induced maximal

effect (Emax- E0)Emax- E0 Drug-induced maximal effectGamma Shape parameter

Estimated parameters: (1) Emax(2) EC50

( )( )E E CC EC= ∗

+max

50


598

B

Model 102 Simple Emax model with a baseline effect parameter

Model 103 Inhibitory effect model

Estimated parameters: (1) Emax(2) EC50(3) E0

Secondary Parameters: (1) Emax-E0

Estimated parameters: (1) Emax

( ) ( )E E E E C C EC= + − ∗ +0 0 50max ( )

( )( )E E C C EC= ∗ − +max ( )1 50


599

B

Model 104 Inhibitory effect model with a baseline effect parameter

Model 105 Sigmoid Emax model

(2) EC50

Estimated parameters: (1) Emax(2) EC50(3) E0


( ) ( )( )E E E E C C EC= − − ∗ +max max 0 50


600

B

Model 106 Sigmoid Emax model with a baseline effect parameter

Estimated parameters: (1) Emax(2) EC50(3) Gamma

Estimated parameters: (1) Emax(2) EC50(3) E0(4) Gamma


( )( )E

E CC EC

=∗

+max γ

γ γ50

( ) ( )( )E E E E C C EC= + − ∗ +0 0 50max γ γ γ


601

B

Model 107 Sigmoid inhibitory effect model

Model 108 Sigmoid inhibitory effect model with a baseline effect parameter

Estimated parameters: (1) Emax (2) EC50 (3) Gamma

Estimated parameters: (1) Emax(2) EC50(3) E0(4) Gamma

( )( )( )E E C C EC= ∗ − +max 1 50γ γ γ

( ) ( )( )E E E E C C EC= − − ∗ +max max 0 50γ γ γ


602

B

PK/PD link modelsWhen pharmacological effects are seen immediately and are directly related to the drug concentration, a pharmacodynamic model is applied to character-ize the relationship between drug concentrations and effect. When the phar-macologic response takes time to develop and the observed response is not directly related to plasma concentrations of the drug a link model is usually applied to relate the pharmacokinetics of the drug to its pharmacodynamics.

The PK/PD Link models can use any combination of WinNonlin compiled Pharmacokinetic models and Pharmacodynamic models. The PK model is used to predict concentrations, and these concentrations are then used as input to the PD model. Thus, the PK data are not modeled; the PK/PD Link models treat the pharmacokinetic parameters as fixed, and generate concentrations at the effect site to be used by the PD model. Model parameter information will be required for the PK model in order to simulate the concentration data.

Note: To model PK and PD data simultaneously, see “Simultaneous PK/PD link models” on page 612.

Notation

Linking PK and PD models

WinNonlin can generate concentrations at effect sites using any PK model in the compiled library, and using these concentrations in any PD model.


Term DefinitionEmax Maximum effectECe50 Concentration required to produce one-half of

the drug induced maximal effect.E0 Effect at time 0

Ke0 Rate of drug loss from the effect compartment. The Ke0 T1/2 is the half life of the amount of time required to collapse the hysteresis curve.

Emax- E0 Drug induced maximal effectGamma Shape parameter

WinNonlin Model LibrariesPK/PD link models

603

B

To link any PK and PD models:

1. Click on the PK/PD/NCA Analysis Wizard button on the tool bar or choose Tools>PK/PD/NCA Analysis Wizard from the menus.

2. Select PK/PD Link in the Model Types dialog.

3. Select a PK model from those detailed under “Pharmacokinetic models” on page 575.

4. Click Next.

5. Select a PD model from those detailed under “Pharmacodynamic models” on page 596.

6. Click Next. The Selection Summary dialog appears.

7. Click Finish.

To assign parameter values for the PK model:

1. Enter the Data Variables, Model Parameters, Dosing Regimen/ Constants, and model options as for other compartmental models, as described under “Model properties” on page 249.

2. Click the Model Parameters button or choose Model>Model Parameters from the menus. Notice that the Model Parameters dialog now has a two tabs, one for the PK Model and one for the PD Model.

3. Select the PK Model tab.

4. Enter the parameter values. The initial parameter values must be entered.


Note: The units for PK concentration can be entered in the PK Concentration Unit field or set using the Units Builder button.

To assign initial estimates and bounds for the PD model:

1. Select the PD Model tab.

2. Enter initial estimates and bounds.

3. Click OK. The model parameters are set and the dialog closes.


604

B

Output parameters

The output parameters for the PD models differ from the parameters for these models when they are not linked. The primary and secondary parameters for the PD models are listed here.

Link model 101 Simple Emax model

Link model 102 Simple Emax model with a baseline effect parameter

Link model 103 Inhibitory effect model

Link model 104 Inhibitory effect model with a baseline effect parameter

Link model 105 Sigmoid Emax model

Primary parameters: (1) Emax(2) ECe50(3) KEO

Estimated parameters: (1) Emax(2) ECe50(3) E0(4) KEO

Secondary parameters: (1) Emax-E0

Estimated parameters: (1) Emax(2) ECe50(3) KEO

Estimated parameters: (1) Emax(2) ECe50(3) E0(4) KEO


Estimated parameters: (1) Emax

WinNonlin Model LibrariesIndirect response models

605

B

Link model 106 Sigmoid Emax model with a baseline effect parameter

Link model 107 Sigmoid inhibitory effect model

Link model 108 Sigmoid inhibitory effect model with a baseline effect parameter

Indirect response modelsWhen pharmacological effects are seen immediately and are directly related to the drug concentration, a pharmacodynamic model is applied to character-ize the relationship between drug concentrations and effect. When the phar-macologic response takes time to develop and the observed response is not

(2) ECe50(3) Gamma(4) KEO

Estimated parameters: (1) Emax(2) ECe50(3) E0(4) Gamma(5) KEO


Estimated parameters: (1) Emax(2) ECe50(3) Gamma(4) KEO

Estimated parameters: (1) Emax(2) ECe50(3) E0(4) Gamma(5) KEO



606

B

directly related to plasma concentrations of the drug a link model is usually applied to relate the pharmacokinetics of the drug to its pharmacodynamics.

One kind of link model available in WinNonlin is the family of indirect phar-macodynamic response (IPR) models proposed by Jusko and co-workers Jusko (1990) and Dayneka, Garg, and Jusko (1993).

The indirect response models differ from other models in the WinNonlin Model Libraries in that they use a PK model to predict concentrations, and then use these concentrations as input to the indirect response model.

Four basic models have been developed for characterizing indirect pharmaco-dynamic responses after drug administration. These models are based on drug effects (inhibition or stimulation) on the factors controlling either the input or the dissipation of drug response.

Note: These models are available only as compiled models

Models

Notation

Model 51 Inhibition of input

Term DefinitionR Measured response to a drugkin The zero order constant for the production of responsekout The first order rate constant for loss of responseCp Plasma concentration of a drugCe Drug concentration at the effect siteIC50 The drug concentration which produces 50% of maximum inhibitionEmax Maximum effectEC50 The drug concentration which produces 50% of maximum stimulation

Estimated parameters: (1) Kin

dRdt

kC

C ICk Rin

p

pout= ∗ −

+

− ∗1

50

WinNonlin Model LibrariesIndirect response models

607

B

Model 52 Inhibition of output

Model 53 Stimulation of input

Model 54 Stimulation of output

(2) Kout(3) IC50

Estimated parameters: (1) Kin(2) Kout(3) IC50

Estimated parameters: (1) Kin(2) Kout(3) EC50(4) Emax

Estimated parameters: (1) Kin(2) Kout(3) EC50(4) Emax

dRdt

k kC

C ICRin out

p

p

= − ∗ −+

∗1

50

dRdt

kE CEC C

k Rinp

pout= ∗ +

∗+

− ∗1

50

max

dRdt

k kE CEC C

Rin outp

p

= − ∗ +∗

+

∗1

50

max


608

B

Running an indirect response model

To select an Indirect Response model:

1. Click on the PK/PD/NCA Analysis Wizard button on the tool bar or select the PK/PD/NCA Analysis Wizard from the Tools menu. The PK/PD Analy-sis Wizard appears, displaying the Model Types dialog.

2. Select Indirect Response from the selections in the Compartmental Models group box. The WinNonlin Compiled Models dialog appears.

3. Select a PK model.

4. Click Next. The list of Indirect Response Models appears.

5. Select an Indirect Response model.

6. Click Next. The Selection Summary box appears.

7. If everything described in this summary box is correct, click Finish. (Other-wise, click Back and return to correct the mistake.) The modeling window appears.

Note: Enter the Data Variables, Dosing Regimen/Constants, and Model Options pre-cisely as for other models.

To assign parameter values for the PK model:

1. Enter the Data Variables, Model Parameters, Dosing Regimen/ Constants, and model options as for other compartmental models, as described under “Model properties” on page 249.

2. Click the Model Parameters button or choose Model>Model Parameters from the menus. Notice that this dialog now has tabs for both the PK Model and the indirect response model.It is possible to choose to have WinNonlin generate the initial parameter val-ues or to specify user-supplied initial values.

3. Select the PK Model tab located under the parameters table.

4. Enter the parameter values for the PK model.

Note: Initial parameter values for the PK model must be specified.

WinNonlin Model LibrariesMichaelis-Menten models

609

B

5. (Optional) Enter the PK units in the PK Concentration Unit field.

6. Click Apply.

Initial estimates and bounds can be specified for the IPR model.

To assign initial estimates and bounds for the IPR model:

1. Select the IPR Model tab in the Model Properties dialog.

2. Enter initial estimates and bounds.

3. Click Apply or OK to specify the settings and close the dialog.

Michaelis-Menten modelsThe WinNonlin library contains four Michaelis-Menten models:

These models are stored as ASCII library files in \LIB\MM.LIB. As with all WinNonlin ASCII models, be sure to examine the ASCII code to determine which dosing constants need to be created.

When these models are being used, the times on the data set must correspond to the dosing times, even if these observations contain no other information. In this case, include a column for Weight on the data set, and weight these observations as 0.

WinNonlin assumes that the time of the first dose is zero.

For these models Vmax is parameterized in terms of concentration per unit time.

For discussion of difficulties inherent in fitting the Michaelis-Menten models see Tong and Metzler (1980) and Metzler and Tong (1981).

Model DescriptionModel 301 One compartment with bolus input and Michaelis-Menten outputModel 302 One compartment with constant IV input and Michaelis-Menten outputModel 303 One compartment with first order input, Michaelis-Menten output and no time lagModel 304 One compartment with first order input, Michaelis-Menten output and a lag time


610

B

Model 301 One-compartment with bolus input and Michaelis-Menten output

C(T) is the solution to the following differential equation:

dC/dt = - VMAX*C/( KM + C ),

with initial condition C(0) = D/V.

Model 302 One-compartment with constant IV input and Michaelis-Menten output

C(T) is the solution to the following differential equations:

dC/dt = (D/TI/V) - VMAX*C/( KM + C ), for T <= TI,dC/dt = - VMAX*C/( KM + C ), for T > TI,

with initial condition C(0) = 0.1) # doses

Estimated parameters: (1) V = Volume(2) VM = maximum rate of elimination(3) KM = Michaelis constant


Secondary parameters: (1) AUC = (D/V)*(D/V/2 + KM)/ VMAX

Estimated parameters: (1) V = Volume(2) VM = maximum rate of elimination(3) KM = Michaelis constant

WinNonlin Model LibrariesMichaelis-Menten models

611

B

Model 303 One-compartment with first-order input and Michaelis-Menten output and no lag time

C(T) is the solution to the following differential equation:

dC/dt = K01*(D/V)*EXP(-K01*T) - VM*C/( KM + C ),

with initial condition C(0) = 0.

Model 304 One-compartment with first-order input and Michaelis-Menten output and a lag time

Everything as in Model 303, with one additional estimated parameter.


Constants in input: (1) number of doses(2) dose 1(3) start time for dose 1(4) end time for dose 1(repeat 2-4 for additional doses)

Secondary parameters: None

Estimated parameters: (1) V_F(2) K01 = absorption rate(3) VM = maximum rate of elimination

(4) KM = Michaelis constant


Secondary parameters: (1) K01 half-life


612

B

Simultaneous PK/PD link modelsWinNonlin has a library of link models which simultaneously fit PK and PD data. As it is difficult to rewrite these models for changes in the PK model, but easy to rewrite them for a different PD model, this library includes each PK models with PD Model 105. These models are described below.

Data

The data for these models must contain the concentration and effect data in the same column, with a function variable in a separate column to distinguish the two. Function 1 should include the time and concentration data, Function 2 should include the time and effect data. An example is shown below.

ASCII library

These models are stored as ASCII library files in the \LIB subdirectory.As with all of the WinNonlin ASCII models, be sure to examine the ASCII code to see what dosing constants need to be created.

Time Response Function0 0 10.5 5 11 15 1. . . . . . . . .36 1 10 148 20.5 145 21 123 2. . . . . . . . .36 121 2

Model File PK model PK model description401 KEO1.LIB Model 1 1 compartment - bolus input402 KEO1.LIB Model 2 1 compartment - constant IV input403 KEO2.LIB Model 3 1 compartment - extravascular input404 KEO2.LIB Model 4 1 compartment - extravascular input, with a lag time405 KEO3.LIB Model 5 1 compartment - extravascular input, equal input and out-

put rates406 KEO3.LIB Model 6 1 compartment - extravascular input, equal input and out-

put with a lag time

WinNonlin Model LibrariesSimultaneous PK/PD link models

613

B

407 KEO4.LIB Model 7 2 compartment - bolus input, defined in microconstants408 KEO4.LIB Model 8 2 compartment - bolus input, defined in macroconstants409 KEO5.LIB Model 9 2 compartment - constant IV input, defined in microcon-

stants410 KEO5.LIB Model 10 2 compartment - constant IV input, defined in macrocon-

stants411 KEO6.LIB Model 11 2 compartment - 1st order input, defined in microconstants412 KEO6.LIB Model 12 2 compartment - 1st order input, defined in macrocon-

stants, includes a lag time413 KEO7.LIB Model 13 2 compartment - 1st order input, defined in macroconstants414 KEO7.LIB Model 14 2 compartment - 1st order input, defined in macrocon-

stants, includes a lag time415 KEO8.LIB Model 15 1 compartment - bolus input + constant infusion416 KEO8.LIB Model 16 2 compartment - bolus input + constant infusion, defined in

microconstants417 KEO9.LIB Model 17 2 compartment - bolus input + constant infusion, defined in

macroconstants418 KEO10.LIB Model 18 3 compartment - bolus input, defined in macroconstants419 KEO10.LIB Model 19 3 compartment - constant infusion, defined in macrocon-

stants

Model File PK model PK model description


614

B

615

Appendix C

Worksheet Functions

Syntax, arguments, and examples for functions in WinNonlin worksheets

WinNonlin worksheets support an extensive set of functions. Complete syntax and examples of these functions follow. In the following functions:

number is a number or reference to a cell that contains a number.

number list is a comma-separated list of up to 30 numbers or cell references.

serial number refers to the stored value for the date or time entered in a cell.

value list is a list of up to 30 values or cell references, separated by commas.

expression list is a list of up to 30 expressions.

significance is the multiple to which to round.

precision is the number of decimal places allowed.

[ ] denotes optional arguments.

Table C-1. Worksheet functions

Function(arguments) DescriptionABS(number) Absolute value of a numberACOS(number) Returns the arc cosine of a number.ACOSH(number) Returns the inverse hyperbolic cosine of a number.ADDRESS(row, column, ref_type[,a1] [,sheet] )

Creates a cell address as text.

AND(logical_list) Returns True if all arguments are true; False if at least one argument is false.ASC(text) In DBCS systems this function returns a copy of text in which the double-byte

characters are converted to single-byte characters, if possible. Characters that cannot be converted are left unchanged.


616

C

ASIN(number) Returns the arcsine of a number. ASINH(number) Returns the inverse hyperbolic sine of a number.ATAN(number) Returns the arctangent of a number.ATAN2(x, y) Returns the arctangent of the specified coordinates.ATANH(number) Returns the inverse hyperbolic tangent of a number.AVERAGE(number list) Returns the arithmetic mean of the supplied numbers.CEILING(number, signifi-cance)

Rounds a number up to the nearest multiple of a specified significance.

CHAR(number) Returns a character that corresponds to the supplied ASCII code.CHOOSE(index, item_list) Returns a value from a list of numbers based on the index number supplied.CLEAN(text) Removes all nonprintable characters from the supplied text.CODE(text) Returns a numeric code representing the first character of the supplied string.COLUMN(reference) Returns the column number of the supplied reference.COLUMNS(range) Returns the number of columns in a range reference.CONCATENATE(text1, text2,…)

Joins several text items into one item.

COS(number) Returns the cosine of an angle.COSH(number) Returns the hyperbolic cosine of a number.COUNT(value list) Returns the number of values in the supplied list. COUNTA(expression list) Returns the number of non-blank values in the supplied list.COUNTIF(range, criteria) Returns the number of cells within a range which meet the given criteria.DATE(year, month, day) Returns the serial number of the supplied date.DATEVALUE(text) Returns the serial number of a date supplied as a text string. Example DAT-

EVALUE (“3/6/94”) returns 34399.DAY(text) Returns the day of the month that corresponds to the given date. Example:

DAY(34399) returns 6; DAY(6-21-94) returns 21.DB(cost, salvage, life, period [,months] )

Returns the real depreciation of an asset for a specific period of time using the fixed-declining balance method.

DDB(cost, salvage, life, period [, factor] )

Returns the depreciation of an asset for a specific period of time using the dou-ble-declining balance method or a declining balance factor.

DOLLAR(number [, precision] )

Returns the specified number as text, using the local currency format and the supplied precision.

Table C-1. Worksheet functions (continued)

Function(arguments) Description

Worksheet Functions

617

C

EVEN(number) Rounds the specified number up to the nearest even integer.EXACT(expression1, expression2)

Compares two expressions for identical, case-sensitive matches. True is returned if the expressions are identical; False is returned if they are not.

EXP(number) Returns e raised to the specified power.FACT(number) Returns the factorial of the specified number.FIND(search_text, text [, start_position] )

Searches for a string of text within another text string and returns the character position at which the search string first occurs.

FINDB(search_text, text [, start_position] )

Searches for a string of text within another text string and returns the byte posi-tion at which the search string first occurs.

FIXED(number [,preci-sion][,no_commas] )

Rounds a number to the supplied precision, formats the number in decimal for-mat, and returns the result as text. Example: FIXED(2000.5, 3) returns 2,000.500. FIXED(2009.5, -1, 1) returns 2010.

FLOOR(number, significance) Rounds a number down to the nearest multiple of specified significance.FV(interest, nper, payment [, pv] [, type] )

Returns the future value of an annuity based on regular payments and a fixed interest rate.

HLOOKUP(search_item, search_range, row_index )

Searches the top row of a table for a value and returns the contents of a cell in that table that corresponds to the location of the search value.

HOUR(serial_number) Returns the hour component of the specified time in 24-hour format.IF(condition, true_value, false_value)

Tests the condition and returns the specified value.

INDEX(reference [, row] [, col-umn] [, range_number] )

Returns the contents of a cell from a specified range.

INDIRECT(ref_text [, a1] ) Returns the contents of the cell referenced by the specified cell.INT(number) Rounds the supplied number down to the nearest integer.IPMT(interest, per, nper, pv, [fv], [type] )

Returns the interest payment of an annuity for a given period, based on regular payments and a fixed periodic interest rate.

IRR(cash_flow [, guess] ) Returns internal rate of return for a series of periodic cash flows.ISBLANK(reference) Determines if the specified cell is blank.ISLOGICAL(expression) Determines if the specified expression returns a logical value.ISNONTEXT(expression) Determines if the specified expression is not text.ISNUMBER(expression) Determines if the specified expression is a number.ISREF(expression) Determines if the specified expression is a range reference.ISTEXT(expression) Determines if the specified expression is text.




618

C

LEFT(text [, num_chars]) Returns the left-most characters from the specified text string. Examples: LEFT(“2nd Quarter”) returns 2; LEFT(“2nd Quarter”, 3) returns 2nd.

LEFTB(text [,num_bytes] ) Returns the left-most byte from the specified text string.LEN(text) Returns the number of characters in the supplied text string. Examples: LEN(“3rd

Quarter”) returns 11; LEN(“1-3”) returns 3.LENB(text) Returns the number of bytes in the supplied text string.LN(number) Returns the natural logarithm of a number.LOG(number, [,base]) Returns the logarithm of a number to the specified base, omitting the base

assumes a base of 10.LOG10(number) Returns the base 10 logarithm of a number.LOWER(text) Changes alphabetic characters in the specified string to lower case.MAX(number list) Returns the largest value in the specified list of numbers.MID(text, start_position, num_chars)

Returns the specified number of characters from a text string, beginning with the specified starting position. Example: MID(“07/04/96”, 4, 2) returns 04.

MIDB(text, start_position, num_bytes)

Returns the specified number of bytes from a text string, beginning with the spec-ified starting position.

MIN(number list) Returns the smallest value in the specified list of numbers.MINUTE(number list) Returns the minute that corresponds to the supplied date. MIRR(cash_flows, finance_rate, reinvest_rate)

Returns the modified internal rate of return for a series of periodic cash flows.

MOD(number, divisor) Returns the remainder after dividing a number by a specified divisor.MONTH(serial_number) Returns the month that corresponds to the supplied date.N(value) Tests the supplied value and returns the value if it is a number.NOW() Returns the current date and time as a serial number.NPER(interest, pmt, pf [, fv] [, type] )

Returns the number of periods of an investment based on regular periodic pay-ments and a fixed interest rate.

NPV(discount_rate, value_list)

Returns the net present value of an investment based on a series of periodic payments and a discount rate.

ODD(number) Rounds the specified number up to the nearest odd integer.OR(logical_list) Returns True if at least one of a series of logical arguments is true.PI() Returns the value of p. (Empty parentheses are required).



Worksheet Functions

619

C

PMT(interest, nper, pv [, fv] [, type] )

Returns the periodic payment of an annuity, based on regular payments and a fixed periodic interest rate.

PPMT(interest, per, nper, pv, [fv], [type] )

Returns the principle paid on an annuity for a given period.

PRODUCT(number list) Multiplies a list of numbers and returns the result.PV(interest, nper, pmt [, fv] [, type] )

Returns the present value of an annuity, considering a series of constant pay-ments made over a regular payment period.

RAND() Returns a number selected randomly from a uniform distribution greater than or equal to 0 and less than 1. (Empty parentheses are required).

RATE(nper, pmt, pv [, fv] [, type] [, guess] )

Returns the interest rate per period of an annuity, given a series of constant cash payments made over a regular payment period.

REPLACE(orig_text, start_position, num_chars, repl_text)

Replaces part of a text string with another text string. Example: REPLACE(“For the year: 1996", 18, 1, “7”) returns “For the year: 1997".

REPLACEB(orig_text, start_position, num_bytes, repl_text)

Replaces part of a text string with another text string.

REPT(text, number) Repeats a text string the specified number of times.RIGHT(text [, num_chars] ) Returns the right-most characters from the given text string.RIGHTB(text [, num_chars] ) Returns the right-most bytes from the given text string.ROUND(number, precision) Rounds the given number to the supplied number of decimal places.ROUNDDOWN(number, num-berOfDigits)

Rounds a number down.

ROUNDUP(number, number-OfDigits)

Rounds the given number up to the supplied number of decimal places.

ROWS(range) Returns the number of rows in a range reference.SEARCH(search_text, text [, start position])

Locates the position of the first character of a specified text string within another text string. Example: SEARCH(“/”, “07/04/96”) returns 3.

SEARCHB(search_text, text [, start_position] )

Locates the position of the first byte of a specified text string within another text string.

SECOND(serial_number) Returns the second that corresponds to the supplied date.SIGN(number) Returns the sign of the specified number.SIN(number) Returns the sine of the supplied angle.




620

C

SINH(number) Returns the hyperbolic sine of the specified number.SLN(cost, salvage, life) Returns the depreciation of an asset for a specific period of time using the

straight-line balance method.SQRT(number) Returns the square root of the specified number.STDEV(number list) Returns the standard deviation of a list of as many as 30 numbers.SUBSTITUTE(text, old_text, new_text [, instance])

Replaces a specified part of a text string with another text string. Example: SUB-STITUTE(“07-04-97”, “-”, “/”) returns 07/04/97.

SUM(number list) Returns the sum of the specified numbers.SUMIF(range, criteria, sum_range)

Returns the sum of the specified cells based on the given criteria.

SUMPRODUCT(range_list) Multiplies the cells in the given ranges, then returns the sum of those products.SUMSQ(number list) Squares each of the supplied numbers and returns the sum of the squares.SYD(cost, salvage, life, period)

Returns the depreciation of an asset for a specified period using the sum-of-years method.

TAN(number) Returns the tangent of the specified angle.TANH(number) Returns the hyperbolic tangent of a number.TEXT(number,format) Returns the given number as text, using the specified formatting.TIME(hour, minute, second) Returns a serial number for the supplied time.TIMEVALUE(text) Returns a serial number for the supplied text representation of time.TODAY() Returns the current date as a serial number.TRIM(text) Removes all spaces from text except single spaces between words.TRUNC(number [,precision]) Truncates the given number to an integer.TYPE(expression) Returns the argument type of the given expression.UPPER(text) Changes the characters in the specified string to uppercase characters.VAR(number list) Returns the variance of a population based on a sample of up to 30 values.VDB(cost, salvage, life, start_period, end_period [, factor] [, method] )

Returns the depreciation of an asset for a specified period using a variable method of depreciation.

VLOOKUP(search_item, search_range, column_index)

Searches the first column of a table for a value and returns the contents of a cell in that table that corresponds to the location of the search value.

WEEKDAY(serial_number) Returns the day of the week that corresponds to the supplied date.YEAR(serial_number) Returns the year that corresponds to the supplied date.



621

Appendix D

Commands, Arrays and FunctionsCommands and syntax for the WinNonlin command language

NotationItems enclosed in brackets, i.e., [ ], are optional.The symbol “|” means “or”.

B

BEGIN COMMAND

BTIME COMMAND

Usage BEGINDescription Indicates that all commands have been specified and processing can start.Example BEGIN

Usage BTIME lower_val, upper_val, numexcl, #, #, etc.Description The user can select points within the Lambda z time range to be excluded

from computations of Lambda z. In the following example, Lambda z is to be computed using times in the range of 12 to 24. However, the concentrations at 16 and 20 hours will not be used in the computation of Lambda z. These “excluded” points will, however, still be used in the computation of the phar-macokinetic parameters.

Example BTIME 12, 24, 2, 16, 20

Notes If there are no times to be excluded, enter a zero for the number of times, or leave it blank. Do not mark a point for exclusion by setting the case weight to 0 as that will also exclude this data point from the calculation of the PK parameters.


622

D

C

CARRYA-LONG

COMMAND

COMMANDS MODEL BLOCK

Usage CARRY #, etc.Description The user can specify variables from the input data grid to be copied into the

output. These variables are not required for the analysis, but are included in each of the output worksheets.

Examples CARRY 3CARR 1CARRYALONG 2

Notes See the NCARRY command.

How Carry Along Data is Migrated to Output MultigridsThe data for carry along columns is moved to all output multigrids from PK (PK/PD) or NCA analyses, with the exception of the last multigrid, named “Settings.” This final multigrid does not receive any carry along data.For all output multigrids other than the “Summary Table,” the carry along col-umns will be located at the end (right-most) of the multigrid. The first cell of data for any given profile within a carry along column will be copied over the entire profile range of output data for a given multigrid. This technique must be used as there will almost always be a differing number of observations on the raw data set than there will be for any generated multigrid.The exception is in the generation of the “Summary Table” multigrids. The carry along columns will be the first columns of data on the multigrid, pre-ceded only by any sort key columns that may have been specified. Also, as there is almost the same number of observations in the raw data set as in the “Summary Table,” all the cells of data within a profile of a carry along column are copied over to the “Summary Table,” not just the first value. There is one special case here as well, that being when doing an NCA analysis without a first data point of t=0, c=0. When such a data point does not exist on the raw data set, depending on which NCA model is selected, the core program may generate a pseudo-point of t=0, c=0 to be able to perform all necessary calcu-lations. In this event, the first cell of data within a carry along column is copied 'up' to the core-generated data value of 0,0.

Usage COMMANDSStatementsEND

Commands, Arrays and FunctionsC

623

D

CON ARRAY

CONSTANTS COMMAND

CONVER-GENCE

COMMAND

Description The COMMAND - END block allows WinNonlin commands to be permanently inserted into a model. Following the COMMANDS statement, any WinNonlin command such as NPARAMETERS, NCONSTANTS, PNAME, etc., may be given. To end the COMMAND section use the END statement.

Example COMMANDSNCON 2NPARM 4PNAME 'A', 'B', 'Alpha', 'Beta'END

Usage CON(N)Description The array CON contains the values of the constants, such as dosing informa-

tion, used to define the model. The index N specifies the Nth constant.Example CON(3)

Note The values specified by the CONSTANT command, described below, corre-spond to CON(1), CON(2), etc. respectively.

Usage CONSTANTS [are | =] C1, C2, ..., CNDescription The CONSTANTS command specifies the values of the constants (such as

dosing information) required by the model being used. The arguments C1, C2, ..., CN are the values of the constants.

Examples CONSTANTS 20, 2.06, -1CONS are 5, 2

Note The NCONSTANTS command must appear before CONSTANTS.

Usage CONVERGENCE [is | =] CDescription The CONVERGENCE command specifies the convergence criterion for the

algorithms. The argument C is the value of the convergence criterion.Values for CONVERGENCE must be greater than 0 and less than 0.1. The default value is 10-4.

Examples CONVERGENCE = 1.e-6CONV .001


624

D

D

DATA COMMAND

DATE COMMAND

DHEADERS COMMAND

Note The test for convergence is

where SS is the residual sum of squares.When 0 is specified as the CONVERGENCE criterion, convergence checks and halvings are turned off. This option is useful when obtaining maximum likelihood estimates.

SSnew SSold–SSold

-------------------------------------- C<

Usage DATA [[are in,] 'path']Description The DATA command begins data input and optionally specifies an external

data file. If arguments are omitted the data are expected to follow the DATA statement. If the arguments are used, path is the full path of the data set and must be 64 characters or less in length.

Examples DATADATA 'C:\MYLIB\MYFILE.DAT'

Usage DATEDescription The DATE command places the current date in the upper right corner of each

page in the ASCII output.Example DATE

Usage DHEADERSDescription Statement in a .CMD file which specifies that data included in the command

file have variable names as the first row.Example DHEADERS

Note If a DNAMES command is also included in the .CMD file, these names will override the names included with the data file.

Commands, Arrays and FunctionsD

625

D

DIFFEREN-TIAL

MODEL BLOCK

DINCRE-MENT

COMMAND

DNAMES COMMAND

Usage DIFFERENTIALStatementsEND

Description Statements in the DIFFERENTIAL - END block define the system of differen-tial equations to fit. The values of the differential equations are assigned to the DZ array.

Example DIFFERENTIALDZ(1) = -(K1+KE)*Z(1) + K2*Z(2)DZ(2) = K1*Z(1) - K2*Z(2)END

Note The NDERIVATIVES statement must be used to specify the number of differ-ential equations to fit. The NFUNCTIONS command specifies the number of differential equations and/or other functions with associated data.

Usage DINCREMENT [is | =] DDescription The DINCREMENT command specifies the increment to use in the estimation

of the partial derivatives. The argument D is the increment to use in the partial derivative estimation.Values for DINCREMENT must be greater than 0 and less than 0.1. The default value is 0.0001

Examples DINCREMENT is 0.001DINC 0.005

Usage DNAMES [are | =] 'name1' , 'name2' , . . . , 'nameN'Description The DNAMES command assigns names to the columns on the data set. The

arguments 'name1', 'name2', . . . ,'nameN' are names of the variables and may be up to eight letters, numbers or underscores in length, and must begin with a letter. They may be separated by commas or spaces.

Example DNAMES 'Subject', 'Time', 'Conc'

Note These names are used in the output and may also be used in the modeling code.If both DNAMES and DHEADERS commands are included in a command file, DNAMES will take precedence.


626

D

DTA ARRAY

DTIME COMMAND

DZ ARRAY

F

F VARIABLE

FINISH COMMAND

Usage DTA(N)Description DTA(N) returns the value of the Nth column for the current observation.Example T = DTA(1)

W = DTA(3)

Usage DTIME #Description DTIME specifies the time of the last administered dose. This value will be

printed out on the Final Parameters table as Dosing_time. Computation of the final parameters will be adjusted for this dosing time.

Example DTIME 48

Usage DZ(N)Description The array DZ contains the current values of the differential equations. The

index N specifies the particular differential equation in the order listed in the DERIVATIVE command.

Example DZ(3) = -P(3)*Z(3)

Note The maximum value of N is specified by the NDERIVATIVES command.

Usage FDescription F returns the value of the function for the current observation.Example F = A * exp(-B*X)

Usage FINISH

Commands, Arrays and FunctionsF

627

D

FNUMBER COMMAND

FUNCTION MODEL BLOCK

Description The FINISH command is retained in WinNonlin to provide compatibility with PCNonlin Version 4. It should immediately follow the BEGIN command.

Example BEGINFINISH

Usage FNUMBER [is | =] NDescription The FNUMBER command indicates the variable (column) in the data set to

be used to delineate data for the individual functions when NFUN > 1.Examples FNUMBER is 3

FNUM 3

Note The FNUMBER command should be specified prior to the DATA command.

Usage FUNCTION NStatementsEND

Description The FUNCTION - END block contains statements to define the function to be fit to the data. The argument N indicates the function number.

Examples FUNC 1F=A*EXP(B) + C*EXP(D)ENDFUNC 1F=A*EXP(B) + C*EXP(D)ENDFUNC 2F=Z(1)END

Note A function block must be used for every data set to be fit. The NFUNCTIONS command specifies the number of function blocks.The variable F must be assigned the function value. WT can be assigned a value to use as the weight for the current observation.


628

D

I

INITIAL COMMAND

ITERATIONS COMMAND

L

LOWER COMMAND

Usage INITIAL [ARE | =] I1, I2, I3, . . . , INDescription The INITIAL command specifies the initial values for the estimated parame-

ters. The arguments I1, I2, I3, . . . , IN are the initial values. They may be sep-arated by commas or blanks.

Examples INITIAL = 0.01, 5.e2, -2.0INIT are 0.02, 10, 1.3e-5INIT 0.1 .05 100

Note The INITIAL command must be preceded by an NPARAMETERS command.

Usage ITERATIONS [are | =] NDescription The ITERATIONS command specifies the maximum number of iterations to

be executed. The argument N is the maximum number of iterations.Examples ITERATIONS are 30

ITER 20

Note If ITERATIONS is set to 0, the usual output is produced using the initial esti-mates as the final values of the parameters.

Usage LOWER [are |=] L1, L2, L3, . . . , LNDescription The LOWER command specifies lower bounds for the estimated parameters.

The arguments L1, L2, L3, . . . , LN are the lower bounds. They may be sepa-rated by commas or blanks.

Example LOWER 0 0 10

Note If the LOWER command is used, a lower bound must be provided for each parameter, and the UPPER command must also be specified. The LOWER command must be preceded by the NPARAMETERS command.

Commands, Arrays and FunctionsM

629

D

M

MEAN-SQUARE

COMMAND

METHOD COMMAND

MODEL COMMAND

Usage MEANSQUARE [is | =] MDescription The MEANSQUARE command allows a specified value other than the resid-

ual mean square to be used in the estimates of the variances and standard deviations. The argument M replaces the residual sum of squares in the esti-mates of variances and standard deviations.If given, MEANSQUARE must be greater than 0.

Examples MEANSQUARE = 100MEAN=1.0

Usage METHOD [is =] NDescription When modeling, the METHOD command specifies the type of fitting algorithm

WinNonlin is to use. The argument N takes on the following values:1. Nelder-Mead Simplex2. Levenberg and Hartley modification of Gauss-Newton (default)3. Hartley modification of Gauss-NewtonWhen doing noncompartmental analysis, METHOD specifies the method 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 curve2. Linear trapezoidal rule (Linear interpolation) (default)3. Linear up/Log down rule – Uses the linear trapezoidal rule any time the concentration data is increasing and the logarithmic trapezoidal rule any time that the concentration data is decreasing.4. Linear Trapezoidal (Linear/log Interpolation)

Example METHOD is 2METH 3

Usage MODEL [N[[,] 'path']]Description In a command file, MODEL specifies the compiled or source model to use. If

“MODEL N” is specified, model N is used from the built-in library. If “MODEL N, PATH” is used, model N from the source file path is used.Valid values for MODEL are 1 to 64. The default value is 2.


630

D

MODEL LINK COMMAND

N

NCARRY COMMAND

NCATRANS COMMAND

Examples MODEL 5MODEL 7, 'PK'MODEL 3 'D:\MY.LIB'

Usage MODEL LINK M1 [,] M2Description The MODEL command with the option LINK specifies that compiled models

are to be used to perform PK/PD or Indirect Response modeling. The argu-ments M1 and M2 are model numbers where:M1 is the PK model number, andM2 is the model number of the PD model or Indirect Response model.When this option is used a PKVAL command must also be used.

Examples MODEL LINK 4 101PKVAL 10 1.5 1.0 1.0MODE LINK 1, 53PKVA 10, 2.5

Note See also PKVAL command.

Usage NCARRY [are | =] NDescription The NCARRY command specifies the number of carry-over variables speci-

fied. The argument N is the number of carry-over variables.Examples NCAR are 3

NCAR 1

Note The NCARRY command must be specified before the CARRY command.See the CARRY command.

Usage NCATRANSDescription When using Noncompartmental Analysis the NCATRANS command specifies

that the Final Parameters will present each final parameter value in a sepa-rate column, rather than row. See “Transpose Final Parameter Table” on page 231.

Commands, Arrays and FunctionsN

631

D

NCON-STANTS

COMMAND

NDERIVA-TIVES

COMMAND

NFUNC-TIONS

COMMAND

Examples NCATRANSNCAT

Usage NCONSTANTS [are | =] NDescription The NCONSTANTS command specifies the number of constants, N, required

by the model. If used, NCONSTANTS must precede CONSTANTS.Examples NCONSTANTS are 3

NCON 1

Note The NCONSTANTS command must be specified before the CONSTANTS command.

Usage NDERIVATIVES [are | =] NDescription The NDERIVATIVES command indicates the number, N, of differential equa-

tions in the system that WinNonlin is fitting. Examples NDERIVATIVES are 2

NDER 5

Usage NFUNCTIONS [are | =] NDescription The NFUNCTIONS command indicates the number of functions to be fit.

There must be data available for each function. The argument N is the num-ber of functions (default = 1). If used, NFUNCTIONS must precede DATA.

Examples NFUNCTIONS are 2NFUN 3

Note The functions can contain the same parameters so that different data sets can contribute to the parameter estimates.When fitting multiple functions one must in some way delineate which obser-vations belong to which functions. To do this, include a FUNCTION variable on the data set or use the NOBSERVATIONS command. See the FNUMBER command or the NOBSERVATIONS command.


632

D

NOBOUNDS COMMAND

NOBSERVA-TIONS

COMMAND

NOPAGE COMMAND

NOPLOTS COMMAND

Usage NOBOUNDSDescription The NOBOUNDS command tells WinNonlin not to compute bounds during

parameter estimation.Examples NOBOUNDS

NOBO

Note Unless a NOBOUNDS command is supplied WinNonlin will either use bounds that the user has supplied, or compute bounds.

Usage NOBSERVATIONS [are | =] N1, N2, N3, . . . , NF

Description When more than one function is fit simultaneously, NOBSERVATIONS may be used to indicate which observations are to be used for each function. The arguments N1, N2, N3, . . . , NF are the number of observations to be used with each of the functions. If used, NOBSERVATIONS must precede DATA.

Example NOBS 10, 15, 12

Note An alternate approach is to include a FUNCTION variable whose values indi-cate the number of the function to which the observations belong. (See FNUMBER.)

Usage NOPAGEDescription The NOPAGE command tells WinNonlin to omit page breaks on the ASCII

output file.Examples NOPAGE

NOPAGE BREAKS ON OUTPUT

Usage NOPLOTSDescription The NOPLOTS command specifies that no plots are to be produced.Example NOPLOTS

Note This command affects both the high resolution plots and the ASCII output.

Commands, Arrays and FunctionsN

633

D

NOSCALE COMMAND

NOSTRIP COMMAND

NPAUC COMMAND

NPARAME-TERS

COMMAND

NPOINTS COMMAND

Usage NOSCALEDescription The NOSCALE command turns off the automatic scaling of weights when the

WEIGHT command is used. By default, the weights are scaled such that the sum of the weights equals the number of observations with non-zero weights.

Example NOSCALE

Note This command will have no effect unless the WEIGHT command is used.

Usage NOSTRIPDescription The NOSTRIP command turns off curve stripping for all profiles.Example NOSTRIP

Usage NPAUC #Description The NPAUC command specifies the number of partial area under the curve

computations requested.Examples NPAUC 3Note See the PAUC command.

Usage NPARAMETERS [are | =] NDescription NPARAMETERS specifies the number of parameters to be estimated. The

argument N is the number of parameters. NPARAMETERS must precede INI-TIAL, LOWER or UPPER. Note that LOWER and UPPER are optional.

Examples NPARAMETERS 5NPAR 3

Note See the PNAMES command.

Usage NPOINTS [is | =] N


634

D

NSECOND-ARY

COMMAND

NVARIABLES COMMAND

P

P ARRAY

Description This determines the number of points in the Predicted Data file. Use this option to create a data set to be used to plot a smooth curve. The minimum allowable value is 10 and the maximum is 20,000.

Example NPOINTS 200

Notes For compiled models without differential equations the default value is 1000.If NDER> 0 (i.e., differential equations are used) this command is ignored and the number of points is equal to the number of points in the data set.The default for user models is the number of data points. This value may be increased only if the model has only one independent variable.

Usage NSECONDARY [are | =] NDescription The NSECONDARY command specifies the number of secondary parame-

ters to be estimated. The argument N indicates the number of secondary parameters to be estimated.

Examples NSECONDARY 2NSEC = 3

Note See the SNAMES command.

Usage NVARIABLES [are | =] NDescription The NVARIABLES command specifies the number of columns of data in the

data grid. The argument N is the number of columns (default = 2). If used, NVARIABLES must precede the DATA command.

Examples NVARIABLES 5NVAR 3

Usage P(N)

Commands, Arrays and FunctionsP

635

D

PAUC COMMAND

PKVALUE COMMAND

PNAMES COMMAND

Description The array P contains the values of the estimated parameters for the current iteration. The index N specifies the Nth estimated parameter.

Examples P(1)T=P(3) - A

Note The values on the INITIAL command correspond to P(1), P(2), etc., respec-tively. The NPARAMETERS command specifies the value of N.The PNAMES command can be used to assign aliases for P(1), P(2), etc.

Usage PAUC #, # etc.Description Lower, upper values for the partial AUC computations. If a specified time

interval does not match times on the data set, then WinNonlin will generate concentrations corresponding to those times.

Examples PAUC 0, 5, 17, 24

Note See the NPAUC command.

Usage PKVALUE N1, N2,. . . ,NPKDescription The PKVALUE command is used to assign parameter values to the PK model

when using the MODEL LINK command.Examples MODEL LINK 4 101

PKVAL 10 1.5 1.0 1.0MODE LINK 1, 53PKVA 10, 2.5

Usage PNAMES [are | =] 'name1', 'name2', . . . , 'nameN'Description The PNAMES command specifies the names associated with the estimated

parameters. The arguments 'name1', 'name2', . . . ,'nameN' are names of the parameters and may be up to eight letters, numbers, or underscores in length, and must begin with a letter. These names are used in the output and may also be used in the modeling code.

Examples PNAMES are 'ALPHA', 'BETA', 'GAMMA'PNAM 'K01', 'K10', 'VOLUME'

Note The number of names specified must equal that for NPARAMETERS.


636

D

PUNITS COMMAND

R

REMARK COMMAND

REWEIGHT COMMAND

Usage PUNITS [are | =] 'unit1', 'unit2', . . . , 'unitN'Description The PUNITS command specifies the units associated with the estimated

parameters. The arguments 'unit1', 'unit2', . . . ,'unitN' are units of the parame-ters and may be up to eight letters, numbers, operators or underscores in length. These units are used in the output.

Examples PUNITS are 'hr', 'ng/mL', 'L/hr'PUNI 'hr'

Note The number of units specified must equal that for NPARAMETERS.

Usage REMARK [comment]Description The REMARK statement allows comments to be placed in a command file.Examples REMARK Y transformed to log(y)

REMA GAUSS-NEWTON

Note If a command takes no arguments or a fixed number of arguments, comments may be placed on the same line as a command after any required arguments.For Example -MODEL 1: Nelder-Mead

Usage REWEIGHT WDescription In the PK modeling module, the REWEIGHT command specifies that itera-

tively reweighted least squares estimates of the parameters are to be com-puted. The weights have the form WT = FW where W is the argument of the REWEIGHT command and F is the current value of the estimated functions.If W < 0 and F < 0 then the weight is set to 0.

Examples REWEIGHT 2REWE -.5

Commands, Arrays and FunctionsS

637

D

S

S ARRAY

SECONDARY MODEL BLOCK

Note The REWEIGHT command is useful for computing maximum likelihood esti-mates of the estimated parameters.The following statement in a model is equivalent to the REWEIGHT com-mand:WT = exp(W log(F)), orWT = F**WThis command is not used with noncompartmental analysis.

Usage S(N)Description The array S contains the estimated secondary parameters. The index N spec-

ifies the Nth secondary parameter.Example S(1) = -P(1)/P(2)

Note The value of N is specified by the NSECONDARY command. Aliases may be assigned for S(1), S(2), etc. using the SNAMES command.The secondary parameters are defined in the SECONDARY section of the model definitions.

Usage SECONDARYStatementsEND

Description The secondary parameters are defined in the SECONDARY - END block. Assignments are made to the array S.

Examples SECONDARYS(1)=0.693/K10ENDOr, if the command SNAMES 'K10_HL' and a PNAMES command with the alias K10 have been included:SECONDARYK10_HL=0.693/K10END

Note The NSECONDARY command must be used to specify the number of sec-ondary parameters.


638

D

SIMULATE COMMAND

SIZE COMMAND

SNAMES COMMAND

SORT COMMAND

Usage SIMULATEDescription The SIMULATE command causes the specified model to be estimated using

only the time values in the data set and the initial values. It must precede the DATA statement, if one is included.

Example SIMULATE

Note The SIMULATE command may be placed in any set of WinNonlin commands. When encountered, no data fitting is performed, only the estimated parame-ters and predicted values from the initial estimates are computed. All other output such as plots and secondary parameters are also produced.

Usage SIZE NDescription The SIZE command has as its argument the model size. Model size sets

default memory requirements. Model size may range from 1 to 64; the default size is 2.

Example SIZE 3

Note Model size is only applicable when using ASCII models.

Usage SNAMES [are | =] 'name1', 'name2', . . . , 'nameN'Description The SNAMES command specifies the names associated with the secondary

parameters. The arguments 'name1', 'name2', . . , 'nameN' are names of the secondary parameters and may be up to eight letters, numbers or under-scores in length, and must begin with a letter. These names are aliases for S(1), S(2), etc. They are used in the output and may also be used in the pro-gramming statements.

Examples SNAMES are 'AUC', 'Cmax', 'Tmax'SNAM 'K10_HL' 'K01_HL'

Usage SORT 1 [,] s1 [,] s2 . . .

Commands, Arrays and FunctionsS

639

D

STARTING MODEL BLOCK

STEADY STATE

COMMAND

SUNITS COMMAND

Description The SORT command causes WinNonlin to segment a large data file into smaller subsets. Each subset will be run through the modeling separately. Arguments s1 and the options s2, s3, etc. are the column numbers of the sort keys that may be specified. The 1 that follows the command SORT has no function. It is included to pro-vide compatibility with PCNonlin version 4.

Examples SORT 1, 1SORT 1 3 2SORT 1, 1, 2

Note The SORT command must be on one line only, i.e., it can not use the line con-tinuation symbol, '&.’

Usage STARTINGStatementsEND

Description Statements in the STARTING - END block specify the starting values of the differential equations. Values are placed in the Z array. Parameters can be used as starting values.

Example STARTZ(1) = CON(1)Z(2) = 0END

Usage STEADY STATE #Description This command informs WinNonlin that data were obtained at steady state. In

this instance, a different set of PK parameters is computed. # is Tau, the (assumed equal) dosing interval. In the following example, dosing was admin-istered every 12 hours, and data were obtained at steady state.

Examples STEADY STATE 12STEA 12

Usage SUNITS [are | =] 'unit1', 'unit2', . . . , 'unitN'


640

D

T

TEMPORARY MODEL BLOCK

TIME COMMAND

TITLE COMMAND

Description The SUNITS command specifies the units associated with the secondary parameters. The arguments 'unit1', 'unit2', . . . ,'unitN' are units of the second-ary parameters and may be up to eight letters, numbers, operators or under-scores in length. These units are used in the output.

Examples SUNITS are 'ml', 'mL/hr'SUNI '1/hr'

Note The number of units specified must equal that for NSECONDARY.

Usage TEMPORARYStatementsEND

Description Statements placed on the TEMPORARY - END block define global temporary variables that can be used in the MODEL statements.

Example TEMPT=XDOSE1 = CON(1)TI=CON(2)K21=(A*BETA + B*ALPHA)/(A+B)K10=ALPHA*BETA/K21K12=ALPHA+BETA-K21-K10END

Usage TIMEDescription The TIME command places the current time in the upper right hand corner of

each output page.Example TIME

Usage TITLE [N]

Commands, Arrays and FunctionsU

641

D

TRANSFORM MODEL BLOCK

U

UPPER COMMAND

URINE COMMAND

Description The TITLE command indicates that the following line contains a title to be printed on each page of the output.Up to five titles may be allowed per run. To specify any title other than the first, a value N must be included with the TITLE command. N may take on the val-ues 1 through 5.

Examples TITLEExperiment EXP-4115

TITLE 1Experiment EXP-4115TITLE 2Subject #1

Usage TRANSFORMStatementsEND

Description Statements placed in the TRANSFORM - END block are executed for each observation before the estimation begins.

Example TRANSFORMY = exp(Y)END

Usage UPPER [are |=] U1, U2, U3, . . . , UN

Description The UPPER command specifies upper bounds for the estimated parameters. The arguments U1, U2, U3, . . . , UN are the upper bounds. They may be sep-arated by commas or blanks.

Example UPPER 1, 1, 200

Note If the UPPER command is used, an upper bound must be provided for each parameter, and the LOWER command must also be specified. The UPPER command must be preceded by the NPARAMETERS command.

Usage URINE LOWER [is | =] C1 UPPER [is | =] C2 VOLUME [is | =] C3 [is | =] CON-CENTRATION [is | =] C4


642

D

W

WEIGHT COMMAND

WT VARIABLE

Description The URINE command is used to specify variables when doing noncompart-mental analysis for urine data (Models 210-212). The user must supply:• the beginning time of the urine collection interval, • the ending times of the urine collection interval,• the volume of urine collected, and • the concentration in the urine.

The four keywords LOWER UPPER VOLUME, and CONCENTRATION spec-ify which column number is being indicated. The arguments C1 - C4 are the column numbers for these variables.

Examples URINE LOWER=C1 UPPER=C2 VOLUME=C3 CONC=C4URINE CONC C1 VOLU C2 LOWE C3 UPPE C4

Note The keywords may appear in any order, and only the first four letters of each keyword is required. Variables must be specified for all four keywords.

Usage WEIGHT [W]Description WEIGHT activates weighted least squares computations. The argument W

sets the weight value: YW. If W is not specified, a column in the data set pro-vides weights, by default, the third column. Another column may be specified using WTNUMBER.

Examples WEIGHT Uses the values in Column 3 as the weightsWEIGHT -.5 Uses as the weight 1/Sqrt(Y)WEIGHTWTNUM 7 Uses the values in Column 7 as the weights

Note The weights are scaled so that the sum of the weights is equal to the number of observations with non-zero weights.See also WTNUMBER, WT, REWEIGHT and NOSCALE.

Usage WTDescription In the PK modeling module, the variable WT contains the weight to be used

for the current observation.Example WT = 1/(F*F)

Commands, Arrays and FunctionsX

643

D

WTNUMBER COMMAND

X

X VARIABLE

XNUMBER COMMAND

Note If the variable WT is included in a model, then any weighting indicated via the Variables and Weighting dialog box will be ignored.

Usage WTNUMBER [is | =] NDescription The WTNUMBER command specifies from which column of the data set that

the weights are to be read.Examples WTNUMBER 4

WTNU is 7

Note If WEIGHT is specified and WTNUMBER is not, the default column for the weights is 3. See “WEIGHT” on page 642.This command is not used with noncompartmental analysis.

Usage XDescription X contains the current value of the independent variable.Example F = exp(-X)

Note By default, when used in a command file, the values of X are taken from the first column of the data set unless the XNUMBER command has been used.

Usage XNUMBER [is | =] NDescription XNUMBER sets the column number, N, of the independent variable. If differ-

ential equations are being fit, XNUMBER indicates the column number that the differential equations are integrated with respect to. The default value is 1.

Examples XNUMBER is 3XNUM 1

Note The XNUMBER command should precede the DATA command.


644

D

Y

Y VARIABLE

YNUMBER COMMAND

Z

Z ARRAY

Usage YDescription Y is the current value of the dependent variable.Example Y = log(Y)

Note By default, Y is assumed to be in the 2nd column unless YNUMBER is used.

Usage YNUMBER [is | =] NDescription The YNUMBER command specifies the column number, N, of the dependent

variable. When running Version 4 command files, the default value is 2.Examples YNUMBER is 4

YNUM 3

Note The YNUMBER command should precede the DATA command.

Usage Z(N)Description The array Z contains the current values of the solutions of the differential

equations. The index N specifies the Nth differential equation.Example B = A*Z(2)

Note The maximum value of N is specified by the NDERIVATIVES command.

645

Appendix E

Scripting Commands

WinNonlin scripting language commands, syntax and usage

For instructions on writing and executing WinNonlin scripts, refer to “Script-ing” on page 489. See the Examples Guide and “Examples of individual scripting operations” on page 520 for example scripts.

A

AggregateVar Property

Applies To TableDescription Defines the variable from Data Set 1 that composes the body of the table.Syntax Table.AggregateVar = VariableNameRemarks Applies to Tables 9 and 10. The Aggregate Variable is much like a Variable

in Tables 4-8. In Tables 9 and 10 the Aggregate Variable is divided into sep-arate columns based on the values of the Cross Variable(s). Note that only one Aggregate Variable may be used.

Example Table.AggregateVar = “Conc”

AlphaTerms() Property

Applies To ToolboxSyntax Toolbox.AlphaTerms(n)=numberRemarks (n) corresponds to the number set by NumTermsSee Also NumTermsExample Toolbox.AlphaTerms(1)=.229

Toolbox.AlphaTerms(2)=3.84


646

E

Append Method

Applies To DataDescription Add or attach a file to another file.Syntax Objectname.AppendRemarks Note that data can be appended to a Pharsight workbook object (.PWO), but it

is not possible to append a .PWO to another file.When using Append:• If different missing value codes are used in the two data sets WinNonlin will not update

these automatically. Use Find/Replace to standardize the missing value codes.• Formulas: Formulas from Excel files will be lost in the process. Only the values them-

selves are appended to the original data set.• The ReadOnly status is not recalled for the appended file. The ReadOnly status of the

original file will be maintained.• All load options are in effect as usual. When using the Data.Append method, if the file

type is ASCII, it will use the .Headers, .Delimiter, etc. properties when appending the file, just as the Data.Load method would.

See Also AppendFilename, AppendFileType, Headers, Delimiter, MissingExample MYDATA.AppendFilename = “C:\MYDIR\newdata.xls”

MYDATA.AppendFileType = EXCELMYDATA.Append

AppendFilename Property

Applies To DataDescription Specifies a file to be appended to an existing data object.Syntax objectname.AppendFilename = stringSee Also Append, AppendFileType

AppendFileType Property

Applies To DataDescription Specifies the file format of the file to be appended to an existing data object.Syntax objectname.AppendFileType = {ASCII | EXCEL}Remarks .PWO file types are not supported with this property.See Also Append, AppendFilename

Scripting CommandsA

647

E

Example MYDATA.AppendFilename = “C:\MYDIR\newdata.xls”MYDATA.AppendFileType = EXCELMYDATA.Append

AppendFileType (continued) Property

AppendSheet Property

Applies To DataDescription Selects the sheet of a multisheet workbook to be used for an append opera-

tion (similar to the Multigrid Property). Only used with the Append method.Syntax MYDATA.AppendSheet=”Final Parameters”Remarks Used with the Append method of the Data property.Example MYDATA1.Filename=”Test1”

MYDATA1.LoadMYDATA1Multigrid=”Sheet 3”MYDATA1.AppendFilename=”Test2”MYDATA1.AppendSheet=”Sheet 1” <-selected sheet to appendMYDATA1.Append

Arrange Method

Applies To WinNonlinDescription Arranges the icons representing any minimized windows in WinNonlin.Syntax WinNonlin Arrange

Aterms() Property

Applies To ToolboxSyntax Toolbox.Aterms(n)=numberRemarks (n) corresponds to the number set by NumTermsSee Also NumTermsExample Toolbox.Aterms(1)=12.3

Toolbox.Aterms(2)=8.1


648

E

B

C

AutoFileOptions Property

Applies To DataDescription Turns on automatic file options when loading a data file.Syntax DataObject.AutoFileOptions = True/False

AutoSort Property

Applies To PlotDescription If AutoSort is set to “True” (default), then the column defined for the X vari-

able will automatically be sorted before the plot is generated.Syntax Plot.AutoSort = {True | False}Example Plot.AutoSort = False

Bolus Property

Applies To ToolboxDescription Selects whether the program will constrain the estimated input rate to be

zero at the initial time (lag time)Syntax Toolbox.Bolus={True|False}Example Toolbox.Bolus=True

CarryData Property

Applies To MergeDescription Indicates whether or not the “Carry along data for like sort levels” check box

will be checked.Syntax Merge.CarryData = {True | False}Remarks The default is True.

Scripting CommandsC

649

E

Cascade Property

Applies To WinNonlinDescription Causes the open objects to be cascaded in the WinNonlin window.Syntax WinNonlin.CascadeSee Also TileHorizontal and TileVerticalExample WinNonlin.Cascade

CaseSensitive Property

Applies To DataDescription Specifies whether a search is case sensitive or not.Syntax Objectname.CaseSensitive = {True | False}Remarks Use with Include, Exclude, Remove, RemoveCol, RenameCol and ReplaceExample MYDATA.SearchArea=”CONC”

MYDATA.Find=”3”MYDATA.Operation=”=”MYDATA.Tolerance=”0”MYDATA.CaseSensitive=FalseMYDATA.With=”Missing”MYDATA.Replace

CloseAll Method

Applies To WinNonlinDescription Closes all window objects within WinNonlin.Syntax WinNonlin.CloseAllRemarks Any information that had not been previously saved will be lost.See Also Unload

Column Property

Applies To DataDescription Specifies the name of a column to be renamed or removed.


650

E

Syntax Objectname.Column = stringRemarks Use with RemoveCol and RenameCol.Example MYDATA.Column=”a”

MYDATA.With=”Subject”MYDATA.RenameCol

Column (continued) Property

ConcCol Property

Applies To ToolboxDescription Specifies input data set column for ConcentrationSyntax Toolbox.ConcCol=column nameExample Toolbox.ConcCol=”Concentration”

Confidence Property

Applies To DescDescription When Confidence is set to “True,” it specifies that confidence intervals are

to be calculated when doing descriptive statistics.Syntax Desc.Confidence = {True | False}Remarks The default is False.See Also Interval, PercentilesExample Desc.Confidence = True

ConseqDelim Property

Applies To DataDescription When ConseqDelim is set to “True,” it causes the Load method to treat con-

secutive delimiters as one while reading a file.Syntax objectname.ConseqDelim = {True | False}Remarks ConseqDelim is used only when loading ASCII data. If this value is not set,

the system will use the value specified on the most-recent Load method.See Also Delimiter, Missing, Headers

Scripting CommandsC

651

E

Copy Method

Applies To DataDescription Copies a specified range of data and stores it for use with the Paste function.Syntax Objectname.Copy = stringRemarks Use with the Paste method.

Optionally, specify a selection of cells for copying using the StartCol, End-Col, StartRow and EndRow properties. To specify an entire column (or entire columns) use just the StartCol and EndCol properties. To specify an entire row (or entire rows) use just the StartRow and EndRow properties.

See Also StartCol, StartRow, EndCol, EndRowExample MYDATA.Filename = <file name>

MYDATA.StartCol=aMYDATA.StartRow=1MYDATA.EndCol=bMYDATA.EndRow=20MYDATA.CopyMYDATA.StartCol=e MYDATA.StartRow=1MYDATA.Paste

CrossVar( ) Property

Applies To TableDescription Defines the Cross Variable for the Table engine. Cross variables are used to

define the columns when breaking a variable into separate columns for dis-play in the table.

Syntax Table.CrossVar(Variable no.) = Variable NameRemarks Applies to Table numbers 4, 5, 6, 7, 8, 9. The example shown below speci-

fies that the CrossVars are Subject and Form. For Table 9, the Cross Vari-ables must come from Data Set 1.

See Also GroupVar( ), IDVar( ), RegVar( )Example Table.CrossVar(1) = “Subject”

Table.CrossVar(2) = “Form”


652

E

CrossVars Property

Applies To TableDescription Defines the number of Cross variables for the Table engine.Syntax Table.CrossVars = integerRemarks Applies to Table no. 4, 5, 6, 7, 8, 9.

The following example specifies that there are 2 Cross variables used in the table.

See Also GroupVars, IDVars, RegVarsExample Table.CrossVars = 2

Cut Method

Applies To DataDescription Cuts a specified range of data from a data set and stores it for use with the

Paste function.Syntax Objectname.Cut = <string>Remarks Use with the Paste method. To specify a selection of cells to be cut, use the

StartCol, EndCol, StartRow and EndRow properties. To specify an entire column (or entire columns) use only the StartCol and EndCol properties. To specify an entire row (or entire rows) use only the StartRow and EndRow properties.

See Also StartCol, StartRow, EndCol, EndRowExample MYDATA.Filename = <file name>

MYDATA.StartCol=A MYDATA.StartRow=1MYDATA.EndCol=JMYDATA.EndRow=10MYDATA.CutMYDATA.StartRow=5MYDATA.StartCol=AMYDATA.Paste

Scripting CommandsD

653

E

D

DefinitionFile Property

Applies To TableDescription Loads a definition file that contains all of the specifications for a table,

except the data file(s) to be used.Syntax Table.DefinitionFile = stringRemarks A table definition file contains all of the information about the table, except

the input data set to be used. Note that any input data file that includes the variables used in the table definition (with the exact same variable names) may be used with this definition file.Note that it may sometimes be necessary to turn a table definition file “off.” If one script will use a table definition file, and then subsequently create another table using Scripting Language commands, include the command:

TABLE.DefintionFile=“ ”to nullify the definition file before using the commands.Similar to graphics template files, a definition file is machine readable only. It must be created by the Table Generator and saved there.

Example Table.DefinitionFile=“c:\winnonln\mytable.tdf”

DeleteFiles Method

Applies To WinNonlinDescription Deletes all files selected using the FileMask property.Syntax WinNonlin.DeleteFilesRemarks Directory names and *.* are not allowed in file specifications.See Also FileMaskExample WinNonlin.FileMask = “c:\winnonln\examples\*.xls”

WinNonlin.DeleteFiles

Delimiter Property

Applies To DataDescription Specifies the field delimiter to use when the Load method is used.


654

E

Syntax objectname.Delimiter = characterRemarks This property is only used while loading ASCII data files. If this value is not

specified, the system will use the value specified for the most-recent Load method.

See Also ConseqDelim, Missing, HeadersExample MYDATA.Delimiter = “,”

MYDATA.Delimiter = “ ”

Delimiter (continued) Property

Delta Property

Applies To ToolboxDescription User supplied smoothing parameterSyntax Toolbox.Delta=numberExample Toolbox.Delta=2

DestArea Property

Applies To TransDescription If DestCol (see DestCol listed below) is defined as a new column name, then

DestArea determines the location of the new column. It can be either inserted adjacent to the SourceCol or appended to the end of the data set.

Syntax Trans.DestArea = {Adjacent | Append}Remarks If DestCol is defined as an existing column, then DestArea is ignored.See Also DestColExample Trans.DestArea = Append

DestCol Property

Applies To TransDescription This property defines the destination column for the transform function.Syntax Trans.DestCol = stringRemarks Spaces are not allowed in the new column name.

Scripting CommandsD

655

E

See Also DestAreaExample Trans.DestCol = “LnConc”

DestCol (continued) Property

DnErr( ) Property

Applies To PlotDescription Defines the down error column of data for a plot.Syntax Plot.DnErr(Data Set no.) = stringRemarks This property must always contain a value even if there is only one data

source for the plot.See Also UpErr( ), ErrTypeExample Plot.DnErr(1) = “SE”

Plot.DnErr(1) = “Minimum”

DoseFile Method

Applies To ModelDescription Loads an ASCII data file containing model dosing informationSyntax Model.DoseFile=stringRemarks See “Special file formats” on page 502See Also LamzFile, LinkFile, ParmFile, PartFileExample Model.DoseFile = “c:\dosedata.dat”

DoseUnit Property

Applies To ToolboxDescription Specifies unit for dosingSyntax Toolbox.DoseUnit={unit}Example Toolbox.DoseUnit=”ng/ml”


656

E

E

Ecol Property

Applies To ToolboxDescription Specifies input data set column for EffectSyntax Toolbox.Ecol=column nameRemarks Not used in calculationsExample Toolbox.Ecol=”Effect”

EndCol Property

Applies To DataDescription Specifies last column in a range.Syntax Objectname.EndCol = string | <number>Remarks Use with the RemoveRow, Cut and Copy methods or the Font and FontSize

properties. StartCol must be less than or equal to EndCol. The value for EndCol can be a string identifying the column by name or it can be a number identifying the column by position.

See Also StartRow, StartCol, EndRowExamples MyData.StartRow = 1

MyData.StartCol = “Time”MyData.EndRow = 12MyData.EndCol = “Time”MyData.Copy

MyData.StartRow = 1MyData.StartCol = 1MyData.EndRow = 12MyData.EndCol = 3MyData.Copy

EndRow Property

Applies To DataDescription Specifies last row in a range.Syntax Objectname.EndRow = number

Scripting CommandsE

657

E

Remarks Use with the RemoveRow, Cut and Copy methods. StartRow must be less than or equal to EndRow.If StartRow is given, and is not –1, a value of –1 for EndRow indicates that the rest of the rows will be selected. The following example will remove all rows after row 4.

Example MYDATA.StartRow=5MYDATA.EndRow=-1MYDATA.RemoveRow

EndRow (continued) Property

EntireRow Property

Applies To DataDescription Specifies that the entire row, as opposed to an individual value, is to be

included or excluded.Syntax Objectname.EntireRow = {True | False}Remarks Use with Include and Exclude.Example MYDATA.SearchArea=”entire data set”

MYDATA.Find=”1”MYDATA.EntireRow=TrueMYDATA.Operation=”>”MYDATA.Tolerance=”0”MYDATA.CaseSensitive=FalseMYDATA.Exclude

ErrType Property

Applies To PlotDescription Determines how the error data will be handled by the Plot engine. Error data

can be either absolute or relative.Syntax Plot.ErrType = {Absolute | Relative}Remarks Default is Relative.See Also UpErr( ), DnErr( )Example Plot.ErrType = Absolute


658

E

Exclude Method

Applies To DataDescription Excludes a range of data from a grid.Syntax objectname.ExcludeSee Also Find, EntireRow, Tolerance, SearchArea, Operation, CaseSensitiveExample MYDATA.SearchArea=”entire data set”

MYDATA.Find=”1”MYDATA.EntireRow=TrueMYDATA.Operation=”>”MYDATA.Tolerance=”0”MYDATA.CaseSensitive=FalseMYDATA.Exclude

ExportAll Method

Applies To WinNonlinDescription Exports all open objects to Microsoft Word. Word Export works very much

like PrintAll. It is a method on the WinNonlin system object and has the same options as PrintAll. The user can set which type of object to export.

Syntax WinNonlin.ExportAllSee Also PrintAllExample The following code would export all charts:

WinNonlin.PrintData=FalseWinNonlin.PrintText=FalseWinNonlin.PrintGraph=TrueWinNonlin.PrintModel=FalseWinNonlin.ExportAll

Extra Property

Applies To TransDescription Contains the additional information that is required for some built in trans-

formations. Different information is required for each transformation. See Remarks below for the type of information required for each.

Syntax Trans.Extra = {string | number}

Scripting CommandsF

659

E

F

Remarks Function usedTRANS_LNTRANS_LOG10TRANS_SQRTTRANS_ABSTRANS_CHANGEBASETRANS_PCTCHANGETRANS_RATIOBASETRANS_MULTCOLTRANS_METABOLITETRANS_ADDCOLTRANS_SUBTRACTCOLTRANS_ETRANS_INVTRANS_POWERTRANS_MULTTRANS_DIVTRANS_ADDTRANS_SUBTRACT

UseNot usedNot usedNot usedNot usedVariable Name - specifies Time columnVariable Name - specifies Time columnVariable Name - specifies Time columnString - defines Column YString - defines the denominator, Column YString - defines Column YString - defines Column YNot usedNot usednumbernumbernumbernumbernumber

See Also InData, SourceCol, Extra, DestCol, DestAreaExample TRANS_CHANGEBASE: Trans.Extra = “Hour”

TRANS_POWER: Trans.Extra = 2

Extra (continued) Property

FileMask Property

Applies To WinNonlinDescription Specifies a file or group of files in a folder.Syntax WinNonlin.FileMask =stringRemarks Use with DeleteFiles. As for that property, do not use directory names or *.*

for specifications.The example below demonstrates how to “mask” or select a group of files in a folder, then demonstrates how to delete those files.

Example WinNonlin.FileMask=“c:\winnonln\examples\bguide3.dat”WinNonlin.DeleteFiles


660

E

Filename Property

Applies To WinNonlinDescription When used with the WinNonlin object, the Filename property is used to

specify a workspace to be loaded.Syntax WinNonlin.filename =stringRemarks No FileType property is required, since the file type must be .WSP. Example WinNonlin.filename = ”c:\winnonln\examples\pro-

files.wsp”WinNonlin.load

FileType Property

Applies To ANOVA, Data, Graph, Model, TextDescription Sets the file format for the Load and Save methods.Syntax objectname.FileType = {ASCII | ANV | EXCEL | EXCEL95 | EXCEL97 |

PWO | BMP | WMF | PCO | PMO | RTF | PTO | LML | SAS | ODBC | PKS}a

Remarks When loading graph objects, the FileType must be set to PCO. When the File-Type is set to anything other than PCO, Save is equivalent to export. EXCEL is the file type for Excel 4.0 files. Excel 5.0/95 files are set as EXCEL95. Excel 97 files are set as EXCEL97. WinNonlin can load WDO, WTO, WMO, WGO, and EXCEL file types but cannot save back to them.

See Also Filename, Load, SaveExample MyData.FileType = EXCEL

a. Use Excel97 to load Excel2000 files.

Find Property

Applies To DataDescription Specifies data to search for.Syntax objectname.Find = stringRemarks Use with Exclude, Include, Remove and Replace.

Scripting CommandsF

661

E

Example MYDATA.SearchArea=”CONC”MYDATA.Find=”3”MYDATA.Operation=”=”MYDATA.Tolerance=”0”MYDATA.CaseSensitive=FalseMYDATA.With=”Missing”MYDATA.Replace

Find (continued) Property

Font Property

Applies To DataDescription Sets the font based on the current selection as defined by the StartRow, Start-

Col, EndRow, and EndCol properties.Syntax ObjectName.Font = stringRemarks The value of -1 can be used in the StartRow or StartCol properties to select

either the entire row or column. If -1 is used, then EndRow and/or EndCol will be ignored.

See Also FontSize, StartRow, StartCol, EndRow, EndColExample MyData.StartRow=1

MyData.StartCol=1MyData.EndRow=1MyData.EndCol=10MyData.Font=”Arial”

FontSize Property

Applies To DataDescription Sets the font size based on the current selection as defined by the StartRow,

StartCol, EndRow and EndCol properties.Syntax ObjectName.FontSize = <number>Remarks The value of -1 can be used in the StartRow or StartCol properties to select

either the entire row or column. If -1 is used, then EndRow and/or EndCol will be ignored.

See Also Font, StartRow, StartCol, EndRow, EndCol


662

E

Example MyData.StartRow=1MyData.StartCol=1MyData.EndRow=1MyData.EndCol=10MyData.FontSize=12

FootnoteFont Property

Applies To GraphDescription Sets the font for the chart footnoteSyntax ObjectName.FootnoteFont=stringSee Also FootnoteFontSizeExample MyGraph.FootnoteFont = “Arial”

FootnoteFontSize Property

Applies To GraphDescription Sets the font size for the chart footnoteSyntax ObjectName.FootnoteFontSize=<number>See Also FootnoteFontExample MyGraph.FootnoteFontSize = 12

Function Property

Applies To TransformDescription Defines the function to be used by the transform engine.

FontSize (continued) Property

Scripting CommandsG

663

E

G

Syntax Trans.Function = {TRANS_LN |TRANS_LOG10 | TRANS_SQRT |TRANS_ABS | TRANS_CHANGEBASE |TRANS_PCTCHANGE |TRANS_RATIOBASE | TRANS_MULTCOL|TRANS_METABOLITE |TRANS_ADDCOL|TRANS_SUBTRACTCOL|TRANS_E | TRANS_INV |TRANS_POWER |TRANS_MULT |TRANS_DIV |TRANS_ADD |TRANS_SUBTRACT}

LN(x)Log10(x)Square Root(x)Absolute Value(x)Change from Baseline%Change from BaselineRatio from Baselinex*yx/yx+yx-ye^x1/xx^nx*nx/nx+nx-n

Remarks The given string must match exactly (with the exception of character cases) one of the strings listed above.

See Also InData, SourceCol, Extra, DestCol, DestAreaExample Trans.Function = TRANS_LN

Function (continued) Property

GroupVar( ) Property

Applies To TableDescription Defines the group variables for the Table engine.

See GroupVar(,) when specifying Group variable(s) for the Plot engine.Syntax Table.GroupVar(Variable no.) = stringRemarks This property must be specified after the GroupVars property. GroupVar

applies to all tables except Tables 9 and 10. When using Table 9 or 10, see JoinGroupVar(,). The example given below specifies that the first GroupVar is Subject.


664

E

See Also CrossVar( ), IDVar( ), RegVar( )See GroupVar( , ) when using the Plot engine.

Example Table.GroupVar(1) = “Subject”

GroupVar( ) (continued) Property

GroupVar( , ) Property

Applies To PlotDescription Defines the group variables for each data set for the Plot engine.Syntax Plot.GroupVar(Variable no.) = stringRemarks This property must be specified after the GroupVars( ) property.

The example given below specifies that the first GroupVar for Data Set 1 is Subject and for Data Set 2 is Patno.

See Also CrossVar( ), IDVar( ), RegVar( )Example Plot.GroupVar(1,1) = “Subject”

Plot.GroupVar(2,1) = “Patno”

GroupVars Property

Applies To TableDescription Defines the number of group variables for the Table engine.Syntax Table.GroupVars = integerRemarks Applies to all tables except Tables 9 and 10.

When using Table 9 or 10, see JoinGroupVars.See Also CrossVars, IDVars, RegVarsExample Table.GroupVars = 1

GroupVars( ) Property

Applies To PlotDescription Defines the number of group variables for the Plot engine.Syntax Plot.GroupVars(Data Set no.) = integer

Scripting CommandsH

665

E

H

Remarks Since the Plot engine can involve more than one data set, it is necessary to specify to which data set the command refers.

Example Plot.GroupVars(1) = 2

GroupVars( ) (continued) Property

GroupVarBreak( ) Property

Applies To TableDescription Specifies whether a page break is made in the text output when the value of

the group variables changes.Syntax Table.GroupVarBreak (Variable no.) = {True|False}See Also GroupVar( ), GroupVarsExample Table.GroupVarBreak(1) = True

Halt Method

Applies To WinNonlinDescription Stops a script at the point the command is encountered and presents a dialog

asking “Do You Want to Continue?” with Yes/No buttons. Selecting Yes allows the script to continue from that point. Selecting No stops the script and leaves the system in interactive mode; no window is closed.

Syntax WinNonlin.Halt= stringRemarks This method is extremely useful in debugging scripts under development.

Halt works just like MsgBox, but it shows Yes/No buttons and a string “Do You Want to Continue?” rather than an OK button.

Example WinNonlin.Halt=”See the output”

See Also MsgBox

Headers Property

Applies To Data


666

E

I

Description When Headers is set to “True,” it indicates that the first row of a data file contains variable names rather than data.

Syntax objectname.Headers = {True | False}Remarks This property is not used when loading PWO files. If this value is not set, the

system will set the default value to that specified in the last Load operation.See Also Missing, Delimiter, ConseqDelim

Headers (continued) Property

IDVar( ) Property

Applies To TableDescription Defines the ID Variables for a table.Syntax Table.IDVar(Variable no.) = stringRemarks Applies to Table no. 2, 3, 5, 6, 7, 8, 10.

When using Table 9, see JoinIDVar(,).See Also CrossVar( ), GroupVar( ), RegVar( )Example Table.IDVar(1) = “Subject”

Table.IDVar(2) = “Time”

IDVars Property

Applies To TableDescription Defines the number of ID Variables for the Table engine.Syntax Table.IDVars = integerRemarks Applies to Table no. 2, 3, 5, 6, 7, 8, 10.

When using Table 9, see JoinIDVars.See Also CrossVars, GroupVars, RegVarsExample Table.IDVars = 2

Include Method

Applies To Data

Scripting CommandsI

667

E

Description Includes a range of data in a grid.Syntax objectname.IncludeSee Also Find, EntireRow, Tolerance, SearchArea, Operation, CaseSensitiveExample MYDATA.SearchArea="conc"

MYDATA.Find="4.3"MYDATA.Include

Include (continued) Method

IncludeVar( , ) Property

Applies To MergeDescription Defines the “Included” columns for each data set for the Merge engine.Syntax Merge.IncludeVar(Data Set no.,Variable no.) = string

This property must be specified after the IncludeVars( ) property.See Also IncludeVars( )Example Merge.IncludeVar(1,1) = “AUC_PO”

Merge.IncludeVar(1,2) = “Cmax_PO”Merge.IncludeVar(1,3) = “Tmax_PO”Merge.IncludeVar(2,1) = “AUC_IV”Merge.IncludeVar(2,2) = “Cmax_IV”

IncludeVars( ) Property

Applies To MergeDescription Defines the number of variables to be included from each data set in a merge

operation.Syntax Merge.IncludeVars(Data Set no.) = integerSee Also IncludeVar( , )Example Merge.IncludeVars(1) = 3

Merge.IncludeVars(2) = 2

InData Property

Applies To Desc, Trans


668

E

Description Defines the data source for the above engines.Syntax engine.InData = string

This property must be specified after the NumData property.Remarks The value supplied must be a valid Data object in the script file.See Also NumData, InData( )Example Trans.InData = MYDATA

InData (continued) Property

InData( ) Property

Applies To Table, Merge, PlotDescription Defines the data source for the above engines.Syntax engine.InData( ) = stringRemarks The value supplied must be a valid Data object in the script file.See Also NumData, InDataExample Merge.InData(1) = MyOral

Merge.InData(2) = MyIVWhere MyOral and MyIV are previously defined data objects

InitialDose Property

Applies To ToolboxDescription Specifies value for initial doseSyntax Toolbox.InitialDose=numberExample Toolbox.InitialDose=11

InputLag Property

Applies To ToolboxDescription Selects whether the program will constrain the derivative of the estimated

input rate to be zero at the initial time (lag time)Syntax Toolbox.InputLag={True|False}Example Toolbox.InputLag=False

Scripting CommandsJ

669

E

J

Interval Property

Applies To DescDescription Specifies the value of the confidence interval to use when calculating

descriptive statistics.Syntax Desc.Interval = numberRemarks Default is 95.See Also Confidence, PercentilesExample Desc.Interval = 95

JoinCrossVar( , ) Property

Applies To TableDescription Defines the Join Cross variable for the Table engine when “merging” two

tables. A Join Cross variable is the common Cross variable of two tables.Syntax Table.JoinCrossVar(Data Set no., Variable no.) = Variable NameRemarks Applies to Table no. 9. This property always contains two values even if

there is just one data source and/or one Join Cross variable.See Also CrossVar( ), JoinCrossVars, JoinGroupVar( , ), JoinIDVar( , )Example Table.JoinCrossVar(1,1) = “Form”

Table.JoinCrossVar(1,1) = “Subject”Table.JoinCrossVar(2,1) = “Form”Table.JoinCrossVar(2,1) = “Subject”

JoinCrossVars Property

Applies To TableDescription Defines the number of Join Cross variables for the Table engine.Syntax Table.JoinCrossVars = integerRemarks Applies to Table no. 9.

This property is not dimensioned because the two data sets must have the same number of Cross Variables.

See Also CrossVars, JoinCrossVar( , ), JoinIDVars, JoinGroupVars


670

E

Example Table.JoinCrossVars = 2

JoinCrossVars (continued) Property

JoinGroupVar( , ) Property

Applies To TableDescription Defines the Join Group variable for the Table engine when merging two

tables. A Join Group variable is the common Group variable of two tables.Syntax Table.JoinGroupVar(Data Set no., Variable no.) = Variable NameRemarks Applies to Table 9.

This property always contains two values even if there is just one data source and/or one Join Group variable.

See Also GroupVar( ), JoinGroupVars, JoinCrossVar( , ), JoinIDVar( , )Example Table.JoinGroupVar(1,1) = “Form”

Table.JoinGroupVar(1,1) = “Trt”

JoinGroupVars Property

Applies To TableDescription Defines the number of Join Group variables for the Table engine.Syntax Table.JoinGroupVars = integerRemarks Applies to Table 9. This property is not dimensioned because the two data

sets must have the same number of Group Variables.See Also GroupVars, JoinGroupVar( , ), JoinCrossVars, JoinIDVarsExample Table.JoinGroupVars = 1

JoinIDVar( , ) Property

Applies To TableDescription Defines the Join ID variable for the Table engine when merging two tables.

A Join ID variable is the common ID variable from the two data sets.Syntax Table.JoinIDVar(Data Set no., Variable no.) = Variable NameRemarks Applies to Table no. 9. This property always contains two values even if

there is just one data source and/or one Join ID variable.

Scripting CommandsK

671

E

K

L

See Also IDVar( ), JoinIDVars, JoinGroupVar( , ), JoinCrossVar( , )Example Table.JoinIDVar(1,1) = “Subject”

Table.JoinIDVar(1,2) = “PatNo”

JoinIDVar( , ) (continued) Property

JoinIDVars Property

Applies To TableDescription Defines the number of Join ID variables for the Table engine.Syntax Table.JoinIDVars = integerRemarks Applies to Table no. 9. This property is not dimensioned because the two

data sets must have the same number of ID Variables.See Also IDVars, JoinIDVar( , ), JoinGroupVars, JoinCrossVarsExample Table.JoinIDVars = 1

Keo Property

Applies To ToolboxDescription Specifies value for KeoSyntax Toolbox.Keo=numberRemarks Range is between 0 and 1Example Toolbox.Keo=.5

LamzFile Method

Applies To ModelDescription Loads an ASCII data file containing Lambda_z information for NCA mod-

els.Syntax Model.LamzFile = string


672

E

Remarks This method only applies to NCA models. See the Special Notes section later in this chapter for the required format of these ASCII files.

See Also DoseUnit, PartFileExample Model.LamzFile = “c:\lamzdata.dat”

LamzFile (continued) Method

Legend( ) Property

Applies To PlotDescription Defines the string to be displayed in the legend of a plot.Syntax Plot.Legend(Data Set no.) = stringRemarks This property only applies when creating overlaid plots. The string given

with this property is used in the legend instead of the data set name.Example Plot.Legend(1) = “Plasma”

Plot.Legend(2) = “Urine”Plot.Legend(1) = “”

LegendFont Property

Applies To GraphDescription Sets the font for the chart legendSyntax ObjectName.LegendFont=stringSee Also LegendFontSizeExample MyGraph.LegendFont = “Arial”

LegendFontSize Property

Applies To GraphDescription Sets the font size for the chart legendSyntax ObjectName.LegendFontSize=<number>See Also LegendFontExample MyGraph.LegendFontSize = 12

Scripting CommandsL

673

E

LinkFile Method

Applies To ModelDescription Load an ASCII data file containing model parameters information for PK/

PD and IPR models.Syntax Model.LinkFile = stringRemarks When using developer (SCI) pre-compiled, ASCII PK models, or User-

ASCII models, Model.ParmFile is used to read in the model parameters and possibly lower/upper bounds. When using the pre-compiled PK/PD or PK/IPR models, Model.LinkFile is used to read in the PK model parameters and Model.ParmFile is used to read the PD or IPR parameters, and possibly lower/upper bounds. This method should not be used for NCA models. See the “Special file formats” on page 502 for the required format of these ASCII files.

See Also DoseUnit, ParmFileExample Model.LinkFile = “c:\linkdata.dat”

Load Method

Applies To Data, Graph, Model, Text, WinNonlinDescription Loads a file into the system using the current file name.Syntax objectname.LoadRemarks When using graph objects, the Load method only works for file type PCO.

When used with the WinNonlin object, this method is used to load work-spaces. When used with the Data Object associated with a PKS study, load-ing the Data Object as file type PKS with the file name pointing to a PKS file will load the study with or without a scenario, depending upon the con-tents of the PKS file. The scenario name is captured from the PKS file pointed to by the Data Object Filename property.

See Also Filename, FileType, SaveExample MyGraph.Load

LoadTemplate Method

Applies To Graph


674

E

M

Description Loads a template on the current graph.Syntax objectname.LoadTemplate = stringSee Also SaveTemplateExample MyGraph.LoadTemplate “c:\winnonln\temps\xy.gtp”

LoadTemplate (continued) Method

MaintenanceDose Property

Applies To ToolboxDescription Specifies value for maintenance doseSyntax Toolbox.MaintenanceDose=numberExample Toolbox.MaintenanceDose=11

Missing Property

Applies To DataDescription Specifies the alphanumeric string that is used to determine what values in a

data file are to be set to “missing” with a gray background.Syntax objectname.Missing = stringRemarks If this value is not specified, the missing value that was last used in the sys-

tem will be used when using the Load method.See Also ConseqDelim, Delimiter, HeadersExample MYDATA.Missing = .

MoveFirst MovePrevious MoveNext MoveLast Methods

Applies To GraphDescription In a group of graphs created with a sort variable this method selects which

graph is active, or displayed.

Scripting CommandsM

675

E

Syntax objectname.MoveFirstobjectname.MovePreviousobjectname.MoveNextobjectname.MoveLast

See Also SortLevelExample MyGraph.MoveFirst

MoveFirst MovePrevious MoveNext MoveLast (continued) Methods

MsgBox Method

Applies To WinNonlinDescription Provides a message within a script file.Syntax WinNonlin.MsgBox = stringRemarks When MsgBox is used in a script, a message box will be displayed during

the run of the script. The script will pause until the user clears the message box from the screen.

Example WinNonlin.MsgBox = “Script complete”

MultiGraph Method

Applies To GraphDescription Changes the visible graph type in multigraphs.Syntax objectname.MultiGraph = Graph Name

Where the available Graph Names are:Modeling: X vs. Observed Y and Predicted Y, Observed Y vs. Weighted Predicted Y*, Weighted Predicted Y vs. Weighted Residual Y*, X vs. Weighted Residual Y*, Partial DerivativesNCA: X vs. Observed Y Predicted Y* Not created when performing Simulations

Example MyGraph.MultiGraph = “X vs. Observed Y and Pre-dicted Y”


676

E

MultiGrid Method

Applies To DataDescription Selects which sub-grid in a multigrid is active, or displayed.Syntax objectname.MultiGrid = Grid Name

where the available Grid Names are:

Modeling: Initial Parameters, Minimization Process, Final Parameters, Dos-ing, Correlation Matrix, Eigenvalues, Condition Numbers, Variance-Covari-ance Matrix, Summary Table, Diagnostics, Differential Equations, Partial Derivatives, Predicted Data, Secondary Parameters, User Settings, History

NCA: Final Parameters, Dosing, Summary Table, Partial Areas, User Set-tings, History

Linear Mixed Effects: Diagnostics, Sequential Tests, Partial Tests, Final Fixed Parameters, Final Variance Parameters, Parameter Key, Contrasts, Contrast Coefficients, Estimates, Estimates Coefficients, Least Squares, Means, LSM Coefficients, LSM Differences, Residuals, User Settings, Ini-tial Variance Parameters, Iteration History, History

Average Bioequivalence (Crossover Studies): Average Bioequivalence, Ratios Test, Diagnostics, Sequential Tests, Partial Tests, Final Fixed Parame-ters, Final Variance Parameters, Parameter Key, Least Squares Means, LSM Differences, Residuals, User Settings, Initial Variance Parameters, Iteration History, History

Population/Individual Bioequivalence: User Settings, Pop./Individual Bioeq., Ratios Test

Average Bioequivalence (Parallel Studies): Average Bioequivalence, Diagnostics, Sequential Tests, Partial Tests, Final Fixed Parameters, Final Variance Parameters, Parameter Key, Least Squares Means, LSM Differ-ences, Residuals, User Settings, Initial Variance Parameters, Iteration His-tory, History

ANOVA: ANOVA commands call the LinMix or Bioequivalence engine and their workbook output. Therefore, use the worksheet names for those, above.

Scripting CommandsN

677

E

N

Remarks This method generates an error in the script log for data objects that are not multigrids. When sorting a Multigrid, use this command to select the appro-priate Multigird before specifying the SortVars, SortVar( ), and Sort com-mands. If the .Multigrid method is used on a data set that is currently showing the history, the .TAB value will automatically be set to Data (i.e., the data will be toggled into view for that object).

MultiGrid (continued) Method

Npoints Property

Applies To ToolboxDescription Number of output data pointsSyntax Toolbox.Npoints=numberRemarks Value must be 2 or greaterExample Toolbox.Npoints=100

NumData Property

Applies To Table, Plot, MergeDescription Indicates the number of data sets to be used with an engine.Syntax engine.NumData = integerRemarks When used with Merge, NumData must be 2. When used with Table or Plot,

NumData must be 1 or 2.See Also InData( ) Example Table.NumData = 1

NumTerms Property

Applies To ToolboxDescription Number of exponential terms in the unit impulse responseSyntax Toolbox.NumTerms=numberRemarks Range is 1 to 9


678

E

O

Example Toolbox.NumTerms=4

NumTerms (continued) Property

Operation Property

Applies To DataDescription Specifies search operator.Syntax Objectname.Operation = {<> | < | > | <= | >= | = }Remarks Use with Exclude, Include, Remove, and Replace.Example MYDATA.SearchArea="CONC"

MYDATA.Find="3"MYDATA.Operation="="MYDATA.Tolerance="0"MYDATA.CaseSensitive=FalseMYDATA.With="Missing"MYDATA.Replace

OutData Property

Applies To ANOVA, Desc, PK, Table, MergeDescription Specifies the name of the output data object that will be generated by the

Run method of any WinNonlin engine.Syntax engine.OutData = stringRemarks engine.OutData = “” specifies a Null alias, so NO output will be generated.Example PK.OutData = “MYDATA”

OutGraph Property

Applies To Plot, PKDescription Creates a graph object during the run of an engine.Syntax engine.OutGraph = stringRemarks engine.OutGraph = “” specifies a Null alias, so NO graph output will be gen-

erated.

Scripting CommandsP

679

E

P

Example Plot.OutGraph = “MyGraph”

OutGraph (continued) Property

OutText Property

Applies To ANOVA, LinMix, Bioeq, PK, Desc Stats (Box and Whiskers plot)Description Specifies the name of the text object that is to be created, when Run is

invoked for a WinNonlin engine that supports text output.Syntax engine.OutText = stringRemarks engine.OutText= “” specifies a Null alias, so NO text output will be gener-

ated.Example PK.OutText = “MYTEXT”

PageFooter Property

Applies To TableDescription Allows the specification of a footer for a scripted table.Syntax Table.PageFooter = stringRemarks A single footer may be specified for a scripted table using this command. A

footer specified using this command will override any footers specified in a definition file, if both are used in a single run.This command accepts a quote delimited string up to 255 characters.

See Also PageHeader, DefinitionFileExample Table.PageFooter=“This is my Footnote”

PageHeader Property

Applies To TableDescription Allows the specification of a title for a scripted table.Syntax Table.PageHeader = string


680

E

Remarks A single title may be specified for a scripted table using this command. A title specified using this command will override any titles specified in a defi-nition file, if both are used in a single run.This command accepts a quote delimited string up to 255 characters.

See Also PageFooter, DefinitionFileExample Table.PageHeader=“This is my Title”

PageHeader (continued) Property

ParmFile Method

Applies To ModelDescription Loads an ASCII data file containing the model parameter and boundaries

information.Syntax Model.ParmFile = stringRemarks When using developer (SCI) pre-compiled or ASCII PK models or User-

ASCII models, Model.ParmFile is used to read in the model parameters, and possibly lower/upper bounds. However, when using SCI PK/PD or PK/IPR models, Model.LinkFile is used to read in the PK model parameters and Model.ParmFile is used to read the PD or IPR parameters, and possibly lower/upper bounds. This method should not be used for NCA models. See the “Special file formats” on page 502 for the required format of these ASCII files.

See Also DoseUnit, LinkFileExample Model.ParmFile = “c:\parmdata.dat”

PartFile Method

Applies To ModelDescription Loads an ASCII data file containing specification of time ranges for the

computation of partial areas. This only applies to NCA models.

Syntax Model.PartFile = stringRemarks This method should not be used for non-NCA models. See “Special file for-

mats” on page 502 for the required format of these ASCII files.See Also DoseUnit, LamzFile

Scripting CommandsP

681

E

Example Model.PartFile = “c:\partdata.dat”

PartFile (continued) Method

Paste Method

Applies To DataDescription Pastes a range of data selected with the Cut or Copy property to a data set. Syntax Objectname.PasteRemarks Use with the Cut or Copy method.Example MYDATA.Filename = <file name>

MYDATA.StartCol=A MYDATA.StartRow=1MYDATA.EndCol=JMYDATA.EndRow=10MYDATA.CutMYDATA.StartRow=5MYDATA.StartCol=AMYDATA.Paste

Applicable Properties

StartCol, StartRow, EndCol, EndRow

Percentiles Property

Applies To DescDescription When Percentiles is set to “True,” percentile calculations will be included

when doing descriptive statistics.Syntax Desc.Percentiles = {True | False}Remarks The default is False.See Also Confidence, IntervalExample Desc.Percentiles = True

Print Method

Applies To Data, Graph, Model, TextDescription Prints the specified object.


682

E

Syntax objectname.PrintRemarks If the method is used on a multigrid data object, only the current data grid

will be printed. If the history of a data object is visible, the history will be printed rather than the data.

See Also PrintAllExample MyData.Print

Print (continued) Method

PrintAll Method

Applies To WinNonlinDescription Prints all open windows or data grids, including all worksheets of open

workbooks.Syntax WinNonlin.PrintAllSee Also Print, PrintData, PrintGraph, PrintModel, PrintTextExample WinNonlin.PrintAll

PrintData Property

Applies To WinNonlinDescription When using the PrintAll command, setting PrintData to False causes Data

windows not to be printed.Syntax WinNonlin.PrintData = {True | False}Remarks The default is True.See Also PrintAll, PrintGraph, PrintModel, PrintTextExample WinNonlin.PrintData=False

PrintGraph Property

Applies To WinNonlinDescription When using the PrintAll command, setting PrintGraph to False causes Graph

windows not to be printed.Syntax WinNonlin.PrintGraph = {True | False}

Scripting CommandsP

683

E

Remarks The default is True.See Also PrintAll, PrintModel, PrintText, PrintDataExample WinNonlin.PrintGraph=False

PrintGraph (continued) Property

PrintModel Property

Applies To WinNonlinDescription When using the PrintAll command, setting PrintModel to False causes the

Model window not to be printed.Syntax WinNonlin.PrintModel = {True | False}Remarks The default is True.See Also PrintAll, PrintText, PrintData, PrintGraphExample WinNonlin.PrintModel=False

PrintMulti Property

Applies To ChartDescription Turns on printing multiple charts per page.Syntax Chartobject.PrintMulti=True/FalseSee Also PrintMultiAcross, PrintMultiDown, PrintAll

PrintMultiAcross Property

Applies To ChartDescription Sets the number of charts printed across the page.Syntax Chartobject.PrintMultiAcross=nSee Also PrintMulti, PrintMultiDown

PrintMultiDown Property

Applies To ChartDescription Sets the number of charts printed down the page.


684

E

Q

R

Syntax Chartobject.PrintMultiDown=nSee Also PrintMulti, PrintMultiAcross

PrintText Property

Applies To WinNonlinDescription When using the PrintAll command, setting PrintText to False causes Text

windows not to be printed.Syntax WinNonlin.PrintText = {True | False}Remarks The default is True.See Also PrintAll, PrintModel, PrintData, PrintGraphExample WinNonlin.PrintText=False

PrintMultiDown (continued) Property

RegVar( ) Property

Applies To TableDescription Defines the Regular variable that composes the body of the table.Syntax Table.RegVar(Variable no.) = stringRemarks Applies to all table templates.

For Table 8 only one Regular variable may be specified. For Tables 9 and 10, the Regular variables are the variables to be used from Data Set 2.

See Also CrossVar( ), IDVar( ), GroupVar( )Example Table.RegVar(1) = “Tmax”

Table.RegVar(2) = “Cmax”Table.RegVar(3) = “AUClast”

RegVars Property

Applies To Table

Scripting CommandsR

685

E

Description Defines the number of Regular variables for a table.Syntax Table.RegVars = integerRemarks Applies to all table templates.

For Table 8 only one Regular variable may be specified. For Tables 9 and 10, the Regular variables are the variables to be used from Data Set 2.

See Also RegVar( ), CrossVars, IDVars, GroupVarsExample Table.RegVars = 3

RegVars (continued) Property

Remove Method

Applies To DataDescription Removes a row based on search criteria.Syntax objectname.RemoveSee Also Find, Tolerance, SearchArea, Operation, CaseSensitiveExample MYDATA.SearchArea="TIME"

MYDATA.Find="3"MYDATA.Operation="="MYDATA.Tolerance="0"MYDATA.CaseSensitive=FalseMYDATA.Remove

RemoveCol Method

Applies To DataDescription Removes a specified column from a grid.Syntax Objectname.RemoveColSee Also Column, CaseSensitiveExample MYDATA.Column="a"

MYDATA.RemoveCol

RemoveRow Method

Applies To Data


686

E

Description Removes a range of rows from a grid.Syntax objectname.RemoveRowExample MYDATA.StartRow=1

MYDATA.EndRow=18MYDATA.RemoveRow

Applicable Properties

StartRow, EndRow

RemoveRow (continued) Method

RenameCol Method

Applies To DataDescription Renames a column.Syntax objectname.RenameColSee Also Column, With, CaseSensitiveExample MYDATA.Column=”a”


Replace Method

Applies To DataDescription Replaces data specified by the Find property with data specified by the With

property.Syntax objectname.ReplaceSee Also Find, With, Tolerance, SearchArea, Operation, CaseSensitiveExample MYDATA.SearchArea="CONC"

MYDATA.Find="3"MYDATA.Operation="="MYDATA.Tolerance="0"MYDATA.CaseSensitive=FalseMYDATA.With="Missing"MYDATA.Replace

Scripting CommandsR

687

E

Response Property

Applies To ToolboxDescription Specifies column for response dataSyntax Toolbox.Response=column nameExample Toolbox.Response=”Response”

Run Method

Applies To ANOVA, LinMix, Bioeq, Desc, Plot, PK, Trans, Table, MergeDescription Invokes the specified engine with it’s currently defined properties.Syntax engine.RunRemarks Be sure to name all possible output objects prior to using the Run method.Example Desc.Run

RunWordExport Method

Applies To PKDescription Invokes the PK engine with its currently defined properties. RunWordExport

will also launch Word (if not already running), create a new document, and populate the document with the output from the PK engine.

Syntax PK.RunWordExportRemarks This method can also be used with the WordExportFilename property to

have Word automatically save the output file when modeling is complete.Microsoft Word must be installed on the same machine as WinNonlin to use this feature.

See Also Run, WordExportFilenameExample Set MyModel = Model

MyModel.Filename = “bg1.cmd”MyModel.FileType = “ASCII”MyModel.LoadPK.WordExportFilename = “bg1.doc”PK.RunWordExport


688

E

S

SameErrCol( ) Property

Applies To PlotDescription This property determines if the same column is to be used for both up and

down error bars.Syntax Plot.SameErrCol(Data Set no.) = {True | False}Remarks This property must contain a value even if there is only one data source.

The default for this property is False. If set to True, then the column defined by UpErr( ) is used for the error data.

See Also UpErr( ), DnErr( )Example Plot.SameErrCol(1) = True

Save Method

Applies To Data, Graph, Model, Text, WinNonlinDescription Saves a file to disk using the current file name.Syntax objectname.SaveRemarks When working with graph objects, if the FileType is anything other than

PCO, to Save is equivalent to export.Saving Workspaces: Saving a workspace requires that all WinNonlin objects be previously saved to disk files first. The Model object, if one exists, must be saved as a PMO file. Lastly, all multigrid data sets must be saved as PWO's.Saving PKS: Saving a PKS workspace requires that the save operation be performed on the study workbook data object being saved as a file of type PKS. The PKS file contains all information necessary to save the workspace.

See Also Filename, FileType, LoadExample MyGraph.Save

SaveAll Method

Applies To GraphDescription Saves all individual graphs of a multipart graph to a file.Syntax objectname.SaveAll

Scripting CommandsS

689

E

Example MYOUTGRAPH.SaveAllPrefix="graf"MYoutgraph.filetype="BMP"MYOUTGRAPH.SaveAll

SaveAll (continued) Method

SaveAllPrefix Property

Applies To GraphDescription Specifies file name prefix for saving multipart graphs.Syntax objectname.SaveAllPrefix = stringRemarks Use with SaveAll.

This prefix must be between 1 to 4 characters in length.Example rema Save all plots as separate .WMF files

MYOUTGRAPH.SaveAllPrefix="plot"MYOUTGRAPH.filetype="wmf"MYOUTGRAPH.SaveAll

SaveTemplate Method

Applies To GraphDescription Saves the current graph settings to a file, as a template.Syntax objectname.SaveTemplate = stringSee Also LoadTemplateExample MyGraph.SaveTemplate “c:\winnonln\temps\xy.gtp”

SearchArea Property

Applies To DataDescription Specifies where search operation should focus.Syntax objectname.SearchArea = stringRemarks Valid entries are a column name or the entire data set. It is not possible to

search a “Current Selection” using the Scripting Language.Use with Exclude, Include, Remove and Replace.


690

E

Example MYDATA.SearchArea="CONC"MYDATA.Find="3"MYDATA.Operation="="MYDATA.Tolerance="0"MYDATA.CaseSensitive=FalseMYDATA.With="Missing"MYDATA.Replace

SearchArea (continued) Property

Sequence Property

Applies To ToolboxDescription Specifies input data set column for sequence dataSyntax Toolbox.Sequence=column nameExample Toolbox.Sequence=”Sequence”

ShowUnits Property

Applies To PlotDescription When ShowUnits is set to True, if any units are defined by XUnits or

YUnits, they will appear in the respective axis title following the text of the axis title.

Syntax Plot.ShowUnits={True|False}Remarks The default value for this property is True.

See Also XUnits, YUnits

Example Plot.ShowUnits=False

Smoothing Property

Applies To ToolboxSyntax Toolbox.Smoothing={Automatic|None|User}Example Toolbox.Smoothing=”Automtic”

Scripting CommandsS

691

E

Sort Method

Applies To DataDescription Sorts a data set using the specified sortkeys.Syntax objectname.SortSee Also SortVar( ), SortVars

SortLevel Method

Applies To GraphDescription Allows navigation among plots containing sort keys by going directly to a

specified sort level.Syntax objectname.SortLevel = stringRemarks If there is more than one sort key, the string given for SortLevel must contain

a value for each key in order, and be separated by a single space.See Also MoveFirst, MovePrevious, MoveNext, MoveLastExample MyGraph.SortLevel = “SubjA Cap”

SortVar( ) Property

Applies To Data, DescDescription Defines the sort keys to be used by the specified engine.Syntax Data.SortVar(Variable no.) = string

This property must be specified after the property SortVars.See Also SortVar( , ), SortVars( ), GroupVar( )Example Data.SortVar(1) = “Form”

Data.SortVar(2) = “Time”

SortVar( , ) Property

Applies To Plot, MergeDescription Defines the sort keys to be used by the specified engine.


692

E

Syntax Engine.SortVar(Data Set no., Sort Var. no.) = stringThis property must be specified after the property SortVars or SortVars( ).

Remarks When using the Plot engine, there must be two values given even if there is only one data source and/or one sort key. When using the Desc engine, there must be a value even if there is only one sort key.

See Also SortVars( ), GroupVar( )

SortVar( , ) (continued) Property

SortVars Property

Applies To Data, Desc, MergeDescription Defines the number of sort keys to be used by the specified object or engine.Syntax engine.SortVars = integer

orobjectname.SortVars = integer

Remarks When working with the Merge engine, even though there are two data sources, the number of SortVars must be the same for each. Therefore Sort-Vars is used, and not SortVars( ).

See Also SortVars( ), SortVar( ), GroupVars( )Examples Desc.SortVars = 1

or Merge.SortVars = 2

SortVars( ) Property

Applies To PlotDescription Defines the number of sort keys to be used by the Plot engine.Syntax Plot.SortVars(Data Set no.) = integerRemarks There must be a value even if there is only one data source.See Also SortVars, SortVar( ), GroupVars( )Example Plot.SortVars(1) = 2

Scripting CommandsS

693

E

SourceCol Property

Applies To TransDescription Defines the source column for transformations.Syntax Trans.SourceCol = stringSee Also DestColExample Trans.SourceCol = “Conc”

Stacked Property

Applies To ToolboxDescription Selects whether treatment data is in separate columns or stacked in the same

column in the input data setSyntax Toolbox.stacked={True|False}Remarks True=stacked; False=separateExample Toolbox.stacked=True

StartCol Property

Applies To DataDescription Specifies the first column in a range.Syntax Objectname.StartCol = string| <number>Remarks Use with the RemoveRow, Cut and Copy methods or the Font and FontSize

properties. StartCol must be less than or equal to EndCol. The value for StartCol can be a string identifying the column name or a number identifying the column position.

See Also StartRow, EndRow, EndColExamples MyData.StartRow = 1

MyData.StartCol = “Time”MyData.EndRow = 15MyData.EndCol = “Time”MyData.Copy

MyData.StartRow = 1MyData.StartCol = 1MyData.EndRow = 15MyData.EndCol = 3MyData.Copy


694

E

StartRow Property

Applies To DataDescription Specifies first row in a range.Syntax objectname.StartRow = <number>Remarks Use with RemoveRow, Cut and Copy.

StartRow must be less than or equal to EndRow. StartRow and EndRow must both be specified, unless StartRow is –1. If StartRow is –1 and End-Row is not specified, all rows will be selected.

Example MYDATA.StartRow=1MYDATA.EndRow=18MYDATA.RemoveRow

Stats Property

Applies To TableDescription To generate descriptive statistics in the Table engine.Syntax Table.Stats = {True|False}Remarks Applies to Table no. 1, 3, 4, 6, 7, 8, 9, 10.

This selection causes all of the available statistics to be printed.Example Table.Stats = True

Subject Property

Applies To ToolboxDescription Specifies input data set column for subjectSyntax Toolbox.Subject=column nameExample Toolbox.Subject=”Subject”

SummaryVar( ) Property

Applies To DescDescription Specifies a variable to be used as the summary column when doing descrip-

tive statistics.

Scripting CommandsT

695

E

T

Syntax Desc.SummaryVar(Data Set no.) = stringSee Also SummaryVarsExample Desc.SummaryVar(1) = “Conc”

SummaryVar( ) (continued) Property

SummaryVars Property

Applies To DescDescription Specifies the number of summary variables that will be used when doing

descriptive statistics.Syntax Desc.SummaryVars = integerSee Also SummaryVar( )Example Desc.SummaryVars = 1

Tab Property

Applies To DataDescription Activates the Data or History tab of a data object.Syntax objectname.Tab = {Data | History}Remarks If the MultiGrid method is used on a data set that is currently showing the

history, the .TAB value will automatically be set to Data–that is, the data will be toggled into view for that object.

TableNum Property

Applies To TableDescription Identifies a table template number.Syntax Table.TableNum = integerRemarks Tables may be specified in a Script file either using Scripting Language

commands, including TableNum, to specify the details of the table, or using a Table Definition file.

See Also DefinitionFile


696

E

Example Table.TableNum = 2

Tau Property

Applies To ToolboxDescription Specifies value for TauSyntax Toolbox.Tau=numberExample Toolbox.Tau=1

TerminalLower Property

Applies To ToolboxDescription Lower range for terminal phaseSyntax Toolbox.TerminalLower=numberExample Toolbox.TerminalLower=1

TerminalPhase Property

Applies To ToolboxDescription Use terminal phaseSyntax Toolbox.TerminalPhase={1|0}Remarks 1=True; 0=FalseExample Toolbox.TerminalPhase=1

TerminalUpper Property

Applies To ToolboxDescription Upper range for terminal phaseSyntax Toolbox.TerminalUpper=numberExample Toolbox.TerminalUpper=5

TableNum (continued) Property

Scripting CommandsT

697

E

TileHorizontal Property

Applies To WinNonlinDescription Causes the open objects to be tiled horizontally.Syntax WinNonlin.TileHorizontalSee Also TileVertical and CascadeExample WinNonlin.tilehorizontal

TileVertical Property

Applies To WinNonlinDescription Causes the open objects to be tiled vertically.Syntax WinNonlin.TileVerticalSee Also TileHorizontal and CascadeExample WinNonlin.tilevertical

TimeCol Property

Applies To ToolboxDescription Specifies input data set column for TimeSyntax Toolbox.TimeCol=column nameExample Toolbox.TimeCol=”Time”

TimeRepeat Property

Applies To ToolboxDescription Repeat dosing every n time unitsSyntax Toolbox.TimeRepeat=numberExample Toolbox.TimeRepeat=5

Title ‘Property

Applies To Plot


698

E

Description Defines the string to be displayed in the title of the plot.Syntax Plot.Title=stringSee Also XTitle, YTitle, Legend( )Example Plot.Title = “My Plot Title”

Title (continued) ‘Property

TitleFont Property

Applies To GraphDescription Sets the font for the chart titleSyntax ObjectName.TitleFont=stringSee Also TitleFontSizeExample MyGraph.TitleFont = “Arial”

TitleFontSize Property

Applies To GraphDescription Sets the font size for the chart titleSyntax ObjectName.TitleFontSize=<number>See Also TitleFontExample MyGraph.TitleFontSize=12

Tolerance Property

Applies To DataDescription Specifies tolerance range for numeric data searches.Syntax objectname.Tolerance = numberRemarks Use with Exclude, Include, Remove and Replace.

Scripting CommandsU

699

E

U

Example MYDATA.SearchArea="CONC"MYDATA.Find="3"MYDATA.Operation="="MYDATA.Tolerance="0"MYDATA.CaseSensitive=FalseMYDATA.With="Missing"MYDATA.Replace

TreatmentA Property

Applies To ToolboxDescription Specifies input data set column to be used for first treatmentSyntax Toolbox.TreatmentA=column nameExample Toolbox.TreatmentA=”Treatment1”

TreatmentB Property

Applies To ToolboxDescription Specifies input data set column to be used for second treatmentSyntax Toolbox.TreatmentB=column nameExample Toolbox.TreatmentB=”Treatment2”

Uniform Property

Applies To GraphDescription Specifies that plots created with a Sort variable should have uniform axes

across levels.Syntax Objectname.Uniform = {True | False}Example MYOUTGRAPH.UNIFORM=True

Tolerance (continued) Property

Unit Property

Applies To Data Object


700

E

Description Assigns a unit to a column. Used in conjunction with the Column property.Example MyData.Column=”Concentration”

MyData.Unit=”ng/ml”

Unit (continued) Property

Unload Method

Applies To PlotDescription Specifies that plots created with a Sort variable should have uniform axes

across levels.Syntax Objectname.Uniform = {True | False}Remarks Unload should be applied to any object that will not be referenced any

longer in a script.Using the Unload method on the WinNonlin object causes the entire applica-tion to be unloaded. To leave the system interactive after running a script, do not use the Unload method on the WinNonlin object.

See Also LoadExample MyModel.Unload

UpErr( ) Property

Applies To PlotDescription Defines the column to be used for the “up error” data.Syntax Plot.UpErr(Data Set no.) = stringRemarks This property must contain a value even if there is only one data source.

If the SameErrCol( ) property is set to “True,” then the UpErr( ) property is used for both up and down error.

See Also DnErr( ), SameErrCol( )Examples Plot.UpErr(1) = “Maximum”

Plot.UpErr(1) = “SE”

Scripting CommandsV

701

E

V

W

Weight Property

Applies To DescDescription Specified the column to be used for doing weighted descriptive statistics.Syntax Desc.Weight = stringRemarks If a weight variable is not specified, uniform weighting will be used.Example Desc.Weight = “Weight”

WindowState Method

Applies To Data, Graph, Model, Text, WinNonlinDescription Sets the window state of the specified object.Syntax objectname.WindowState = {Minimized | Maximized | Normal}Remarks Using this property on the WinNonlin object allows the user to run a script

with the application minimized.Example WinNonlin.WindowState = Minimized

With Property

Applies To DataDescription Specifies replacement data.Syntax Objectname.With = stringRemarks Use with RenameCol and Replace.Example MYDATA.Column=”a”


WordExportFilename Property

Applies To PK


702

E

X

Description Sets the file name to be used in Word when using the Word export method.Syntax PK.WordExportFilename = stringRemarks This property is used only with the RunWordExport method. If WordExport-

Filename is not specified when using RunWordExport, the output document will still be created but not saved in Word.Microsoft Word must be installed on the same machine as WinNonlin.

See Also RunWordExportExample Set MyModel = Model

MyModel.Filename = “bg1.cmd”MyModel.FileType = “ASCII”MyModel.LoadPK.WordExportFilename = “bg1.doc”PK.RunWordExport

WordExportFilename (continued) Property

WorkingDir Property

Applies To WinNonlinDescription Changes working file directory.Syntax WorkingDir = stringRemarks This property sets the Working directory in which WinNonlin will load and

save files. This is particularly useful for making script files “portable,” as it removes the need to specify absolute paths for data files used in the script--i.e., files can be referred to by name alone, if they are located in the directory set by the workingDir command.

Example WorkingDir = “C:\Newdir”

XLabelsFont Property

Applies To GraphDescription Sets the font for the X axis labels on the chartSyntax ObjectName.XLabelsFont = stringSee Also XLabelsFontSize

Scripting CommandsX

703

E

Example MyGraph.XLabelsFont = “Arial”

XLabelsFontSize Property

Applies To GraphDescription Sets the font size for the X axis labels on the chartSyntax ObjectName.XLabelsFontSize = <number>See Also XLabelsFontExample MyGraph.XLabelsFontSize = 12

XTitle Property

Applies To PlotDescription Defines the string to be displayed in the x-axis title of the plot.Syntax Plot.XTitle=stringSee Also Title, YTitle, Legend( )Example Plot.XTitle = “Time”

XLabelsFont (continued) Property

XTitleFont Property

Applies To GraphDescription Sets the font for the X axis title on the chart.Syntax ObjectName.XTitleFont=stringSee Also XTitleFontSizeExample MyGraph.XTitleFont = “Arial”

XTitleFontSize Property

Applies To GraphDescription Sets the font size for the X axis title on the chartSyntax ObjectName.XTitleFontSize = <number>


704

E

See Also XTitleFontExample MyGraph.XTitleFontSize = 12

XUnits Property

Applies To GraphDescription Defines the units to be displayed in the x-axis title of the plot. The units por-

tion of the x-axis title will appear in parenthesis after the x-axis title.Syntax ObjectName.Xunits=stringSee Also YUnitsExample MyGraph.XUnits = ‘hr”

XUnits Property

Applies To PlotDescription Defines the units to be displayed in the x-axis title of the plot. The units por-

tion of the x-axis title will appear in parenthesis after the x-axis title.Syntax Plot.XUnits=stringSee Also ShowUnits, YUnitsExample Plot.XUnits = “hr”

XVar( ) Property

Applies To PlotDescription Defines the X variable column for a plot.Syntax Plot.XVar(Data Set no.) = stringRemarks This property must contain a value even if there is only one data source.Example Plot.XVar(1) = “Time”

XTitleFontSize (continued) Property

Scripting CommandsY

705

E

Y

YLabelsFont Property

Applies To GraphDescription Sets the font for the Y axis labels on the chartSyntax ObjectName.YLabelsFont=stringSee Also YLabelsFontSizeExample MyGraph.YLabelsFont = “Arial”

YLabelsFontSize Property

Applies To GraphDescription Sets the font size for the Y axis labels on the chartSyntax ObjectName.YLabelsFontSize=<number>See Also YLabelsFontExample MyGraph.YLabelsFontSize=12

YTitle Property

Applies To PlotDescription Defines the string to be displayed in the y-axis title of the plot.Syntax Plot.YTitle=stringSee Also Title, XTitle, Legend( )Example Plot.YTitle = “Concentration”

YTitleFont Property

Applies To GraphDescription Sets the font for the Y axis title on the chartSyntax ObjectName.YTitleFont=stringSee Also YTitleFontSizeExample MyGraph.YTitleFont = “Arial”


706

E

YTitleFontSize Property

Applies To GraphDescription Sets the font size for the Y axis title on the chartSyntax ObjectName.YTitleFontSize = <number>See Also YTitleFontExample MyGraph.YTitleFontSize = 12

YUnits Property

Applies To GraphDescription Defines the units to be displayed in the y-axis title of the plot. The units por-

tion of the y-axis title will appear in parenthesis after the y-axis title.Syntax ObjectName.YUnits=stringSee Also XUnitsExample MyGraph.YUnits = “mg/ml”

YUnits Property

Applies To PlotDescription Defines the units to be displayed in the y-axis title of the plot. The units por-

tion of the y-axis title will appear in parenthesis after the y-axis title.Syntax Plot.YUnits=stringSee Also ShowUnits, XUnitsExample Plot.YUnits = “mg/ml”

YVar Property

Applies To PlotDescription Defines the Y variable column for a plot.Syntax Plot.YVar(Data Set no.) = stringRemarks This property must contain a value even if there is only one data source.Example Plot.YVar(1) = “Concentration”

707

Appendix F

Warnings and Error Messages

There are six sources of error messages in WinNonlin. Each has a unique set of error message numbers, as follows:

Compartmental modelingWhen modeling is run, error messages and warnings are written to the text output. If an error occurs that does not prevent completion of modeling, it will be written to the text output (if the user requested text output). If an error occurs that prevents completion of modeling, text output will be created, whether or not the user requests it; errors and warnings will be written there.

Note: To locate error messages, search for the word ERROR in the text output.

10001 Invalid statement. Program terminated.

Source Message numbers

Microsoft Visual Basic & OCX'sa

a. See Microsoft’s documentation for information on error messages from Visual Basic and the Windows OCX's.

1-9999

Compartmental modeling 10000-10999LinMix and Bioequivalence wizards 11000-11999Table Wizard 12000-12999Descriptive statistics 13000-13999Noncompartmental analysis 14000-14999Scripting language 19000-19999


708

F

The preceding statement contains a syntax error (e.g. C = A+ *B).

10002 Unmatched parenthesis. Program terminated.

The preceding statement contains an extra left parenthesis.

10003 Improper statement found when evaluating model. Program terminated.

This is an unusual error. If it occurs, please bring it to the attention of Phar-sight customer support.

10004 Missing END statement. Program terminated.

An “END” statement was missing for one or more of the following labeled groups of commands: TRANSFORM, COMMANDS, TEMPORARY, STARTING, DIFFERENTIAL, FNUMBER, SECONDARY.

10005 Invalid number. Program terminated.

The previous equation contains an illegal number (constant).

10006 Model too complex. Rerun with larger model size (SIZE command). Program terminated.

The model was too complex for the default memory settings. Try the model again after increasing the model size (via the SIZE command, or the Model size option on the PK Settings tab, in the Model Options dialog box).

10007 Invalid variable name or character. Program terminated.

The previous equation contains an invalid character. (i.e., not A-Z, 0-9, +, -, /, *, **, (), &)


Workspace is not large enough to accommodate the model. The maximum number of variables and operators has been exceeded (2000). To help allevi-ate this problem, assign expressions to temporary variables (in the TEMP sec-tion) before using them to define the model.

10011 Unmatched parenthesis. Program terminated.

There was an unmatched or missing right parenthesis, or too many arguments were encountered in a subscribed variable or function (e.g. DZ(1,1) or ABS (A,B)).

10012 Invalid function number. Program terminated.

An invalid FUNCTION number was assigned. Function numbers must be integers, greater or equal to 1, and less than or equal to the number of func-tions in the NFUNCTIONS command.

Warnings and Error MessagesCompartmental modeling

709

F

10013 Invalid group identifier. Program terminated.

An invalid label was assigned to a group of commands (e.g. STRT in place of START).

10014 Missing argument in function or array. Program terminated.

An argument was missing for a function (e.g., MAX(A) instead of MAX(A,B))

10015 Model section does not exist. Check to see if NSEC > 0 but no secondary parameters are defined, or if the FUNCTION block(s) is missing. Program terminated.

A labeled section does not exist. For example, an NSEC command was speci-fied, but the secondary parameters were never defined.

10017 Equation too complicated. Program terminated.

At least one of the equations was too complicated to evaluate. Split it up into two or more parts using temporary variables.

10018 No IF corresponding to ENDIF. Program terminated.

An ENDIF statement was encountered without a matching IF statement.

10019 Missing ENDIF statement. Program terminated.

An ENDIF statement is missing.

10020 Undefined (GOTO) label. Program terminated.

A label was referenced (e.g. with a GOTO) which was never defined. Either the label is missing entirely, or is missing the ending colon “:”.

10021 Invalid (GOTO) label name. Program terminated.

The label name is invalid. Change the label to a valid name.


The maximum number of temporary variables and labels (100) has been exceeded.

10023 No matching IF.. THEN.. for an ELSE statement. Program terminated.

An ELSE statement was encountered without corresponding IF - THEN state-ments.

10024 IF statements nested too deeply. Program terminated.

IF statements can only be nested as deep as 10 levels.

10025 Cannot branch out of program section. Program terminated.


710

F

An attempt was made to branch from one block of statements (TEMP, FUNC, etc.) to a labeled section in another block of statements using a GOTO. This is not supported.

10026 Duplicate label name. Program terminated.

A duplicate label name was encountered. Change the label to a new name.

10027 Invalid array subscript. Check to see if subscript exceeded array bound. Pro-gram terminated.

An invalid array access was attempted. The model has gone outside allowable limits when accessing some variable which is an array (e.g. DTA (11)).

10028 Invalid statement encountered when evaluating model. Program terminated.

An invalid branching occurred during execution. Check to see that the model is specified correctly.

10029 Invalid statement encountered when evaluating model. Program terminated.

An invalid comparison occurred during execution. Check to see that the model is specified correctly.

10030 Operation attempted using A missing VALUE. Program terminated.

10031 Attempt to divide by zero. Program terminated.

10033 Invalid argument for LOGE(X). Program terminated.

The argument for loge(x) was invalid. Perhaps X was undefined, or 0 or a negative number.

10034 Invalid argument for LOG10(X). Program terminated.

The argument for log10(x) was invalid. Perhaps X was undefined, or 0 or a negative number.

10035 Invalid argument for SQRT(X). Program terminated.

The argument for SQRT(x) was invalid. Perhaps X was undefined or a nega-tive number.

10036 Invalid argument for ATAN2(X,Y). Program terminated.

The argument for ATAN2(x,y) was invalid. Perhaps either X or Y was unde-fined or a negative number, or perhaps only one argument was given.

10037 Problem exceeds available resources. Program terminated.

Notify Pharsight technical support for assistance at [email protected].

10050 DO statement missing a NEXT statement. Program terminated.


711

F

A NEXT statement must end each DO loop. Check all DO statements for cor-responding NEXT statements.

10051 Too many nested DO statements. Program terminated.

DO statements may only be nested 10 deep.

10052 Invalid DO statement. Program terminated.

Check the arguments and syntax of any DO statements.

10053 Maximum model size is 64. Program terminated.

Please check the model specification for problems.

10054 Maximum length of DO statement is 788 characters. Program terminated.

10055 Maximum number of DO statements is 999. Program terminated.

10056 NEXT statement missing corresponding DO. Program terminated.

A NEXT statement ends a DO loop. Check all NEXT statements for corre-sponding DO statements.

10057 String length exceeds 256. Program terminated.

No input record may exceed 256 characters in length.

10058 Invalid lag function argument. Program terminated.

The argument for lag(x) was invalid. X must be the column number of a defined variable.

10101 The number of data observations, NOBS, was not defined.

The number of data observations to be input (NOBS) was not defined.

10102 A DATA command was not encountered.

Missing DATA command.

10103 The number of parameters to be estimated, NPARM, was not given.

No NPARAMETERS command was encountered.

10104 The initial estimates of the parameters, INIT, were not given.

No INITIAL command was encountered.

10105 CONV = 0 is only supported for integrated functions (NDER=0).

Turning off of convergence checks is only supported for integrated equations.

10106 The number of parameter values, NPARM, must be specified prior to INIT, LOWER, OR UPPER

NPARAMETERS must precede INITIAL, LOWER and UPPER commands.


712

F

10107 Error converting units for next value. Using default units.

The preferred units were inconsistent with the default units or were not acceptable units.

10108 The number of data observations, NOBS, must be specified prior to the DATA command.

The number of observations to be input (NOBS), must precede DATA.

10109 Error encountered when reading initial parameter values.

The program was unable to read NPARM numbers on the INITIAL command. Either fewer than NPARM initial estimates were given, or one of the numbers was not carefully defined (e.g. 1.2 - E-3).

10110 Error encountered when reading the number of NOBS for each function.

The program was unable to read NFUN numbers on the NOBS command.

10111 The number of functions must be greater than 0.

The specified number of functions must be between 1 and 10.

10112 The number of parameters to be estimated must be greater than 0. Program terminated.

The specified number of parameters must be between 1 and 10.

10113 The number of derivatives must be greater than 0. Program terminated.

If the system includes differential equations, the number of differential equa-tions in the system must be between 1 and 10.

10114 The specified method for estimating the residual sum of squares must be 1, 2 or 3. Program defaulting to method 2, execution continuing.

The specified METHOD must be 1, 2 or 3. Method 1: Nelder-Mead, Method 2: Hartley's and Levenberg's modification of the Gauss-Newton Algorithm (default), Method 3: Hartley's Modification of the Gauss-Newton Algorithm.

10115 The maximum number of iterations must be greater than or equal to zero. Pro-gram defaulting to 50, execution continuing.

An invalid value was assigned to maximum number of ITERATIONS.

10116 The number of variables in the input file must be greater than 0.

A maximum of 10 variables (columns) can be read in from a data file.

10117 The column numbers corresponding to X and Y must be greater than 0 and must be less than or equal to NVAR.


713

F

The column numbers associated with X and Y (XNUMBER, YNUMBER) must be between 1 and 10.

10118 The number of rows in the plots must be between 10 and 50. PRogram defaulting to 50, execution continuing.

An invalid value was entered.

10119 The number of columns in the plots must be between 10 AND 100. Program defaulting to 100, execution continuing.

An invalid value was entered.

10120 The specified convergence criterion must be greater than or equal to 0. Pro-gram defaulting to 1.E-4, Execution continuing.

An invalid value was assigned to the CONVERGENCE command.

10121 The increment for estimating partial derivatives must be between 0 AND 0.1. Program defaulting to 0.001, execution continuing.

The increment used for estimating the partial derivatives DINC must be between 0.0 and 0.1.

10122 The variable names for X and Y cannot be equal.

X and Y cannot be assigned to the same column in the input data file.

10123 The variable number corresponding to weight must be greater than 0.

If weights are to be read in from the data file, they must have an assigned col-umn number greater than one.

10124 Error encountered when trying to read a number on the preceding command.

An error was encountered when trying to read the (first) number from the pre-ceding command. Either the program was expecting a number to be specified and none was given, or the number was not correctly defined (e.g. 1.2 - E-3).

10125 Error on data file

An error was encountered when reading the data file. There are several ways this can happen: a. Fewer than NOBS observations were on the data file. b. Fewer than NVAR numbers were on one or more rows on the data file. c. One or more illegal numbers (e.g. 1.2 - E-3).

10126 Error encountered when reading in the upper or lower parameter limits. Exe-cution continuing without limits on the parameter space.

An error was encountered when reading the lower (or upper) parameter limits. Either fewer than NPARAMETERS numbers were on the card or one or more invalid numbers were specified (e.g. 1.2 - E-3).


714

F

10127 If lower (or upper) limits are specified then upper (or lower) limits must also be specified. Execution continuing without limits on the parameter space.

If LOWER limits are specified, then UPPER limits must also be specified (and vice-versa).

10128 An improper call was made to the numerical integration routine. Check your input and model. Program terminated.

An error was encountered when trying to numerically integrate a system of differential equations. This can usually be attributed to an improperly defined model. Check to see that the model was correctly specified.

10129 Too much relative accuracy was requested for this problem. Relative error and-or absolute error tolerances were reset. Check your model for possible singularities. Execution continuing.

The program is having difficulty obtaining the necessary precision when inte-grating a system of differential equations. Check the model for possible singu-larities.

10130 The program is having to work very hard to obtain the desired accuracy. Make sure your model is correct. Execution continuing

A very large number of function evaluations are having to be made to obtain the desired precision. Check to see that the model was correctly specified.

10131 The number of constants must be greater than 0.

If CONSTANTS are used, the number of user input constants must be between 1 and 500.

10132 The number of constants must be specified before assigning them values.

The NCON command must appear prior to the CONSTANTS command.

10133 An error was encountered when reading the values assigned to the constants.

An error was encountered when trying to read the NCON values assigned to constants. Either fewer than NCON values were specified, or one of the val-ues was not correctly defined (e.g. 1.2 - E-3).

10134 Parameter estimate for <parameterName> is at or near boundary.

10135 An initial parameter estimate is outside of the specified upper and lower lim-its. Parameter limits ignored - Execution continuing.

One or more of the initial parameter estimates is outside the specified upper and lower limits.

10136 An error was encountered when reading constant names. Program terminated.


715

F

10137 The referenced library contains a model statement without a model number. Program terminated.

Each MODEL statement in a WinNonlin library must also have a correspond-ing model number (e.g. MODEL 7).

10138 A convergence failure occurred during a singular value decomposition. Check the model for possible singularities. Program terminated.

Check to make sure that the model has been correctly defined.

10139 NCON was specified but the constants were not input.

An NCONSTANTS command was encountered but the constants were never defined (CONSTANTS).

10140 NSEC must be specified prior to the SNAME command.

The NSECONDARY command must precede the SNAMES command.

10142 NSEC must be greater than 0.

If secondary parameters are specified, the number of secondary parameters must be between 1 and 50.

10143 An error was encountered when reading parameter, secondary, data or unit names. Program continuing with default names.

An error was encountered reading the parameter or secondary parameter names. Make sure that the number of input names matches NPARAMETERS (or NSECONDARY) and that each name is enclosed in single quotes.

10144 The specified model number does not exist in the specified library.

10145 The specified title number must be 1, 2, 3, 4, OR 5.

The specified TITLE number must be 1, 2, 3, 4, or 5 (e.g. TITLE 3).

10146 The specified number of plot points must be between 10 and 20000. NPOINTS reset to default.

The specified number of points to be included in the output plot file must be between 10 and 20000.

10147 Scale values could not be computed for the next plot. Plot deleted.

Axis scale values could not be computed for a plot. This could happen, for example, if all values to be plotted were identical.

10148 The number of constants (NCON) is inconsistent with the number of adminis-tered doses.

The number of constants (NCONSTANTS) is not consistent with the number of doses given.


716

F

10149 The WEIGHT command cannot be used when performing simulations. The WEIGHT command was changed to REWEIGHT.

When performing simulations, since no observed data exist, it is inappropriate to use the WEIGHT command. REWEIGHT will be used.

10150 The parameter variance-covariance matrix is singular. Program terminated.

The variance-covariance matrix for the model parameters is singular.

10151 The algorithm is unable to converge. Program terminated.

The Gauss-Newton algorithm was unable to converge. Try using different ini-tial estimates, or try rerunning the problem using the Nelder-Mead algorithm.

10152 The residual sum of squares is zero. Convergence assumed.

10153 One or more weights became negative. Weight set to missing.

Check model definition statements to make sure WT is defined correctly.

10154 The specified library file does not exist. Program terminated.

Check for proper specification of the model file.

10155 An error was encountered when reading beta time range. Program continuing with default estimation of time range.

These are the values for selecting the Lambda z time interval.

10156 An error was encountered when reading the missing value code. Program con-tinuing with default missing value code.

Make sure that the missing value code is eight characters or less in length, and surrounded by quotes.

10157 The value of FNUM is invalid. Check to make sure NVAR is correct. Program terminated.

FNUMBER must be the number of a column on the input data set.

10161 Inadequate system resources available for this problem.

Notify Pharsight technical support for assistance at [email protected].

10162 Error encountered when reading link model PK constant values.

An error occurred when reading the parameter values for the PK model.

10163 NOBS command ignored since FNUM specified.

The function variable specified by FNUMBER will be used to determine which observations belong to which functions.

10164 The NOBS values are inconsistent with the number of records in the data file.

mailto: [email protected]


717

F

The sum of the NOBSERVATIONS values is not equal to the number of observations on the data set. It is recommended to use a function variable for data with more than one function. See “FNUMBER” on page 627.

10165 The PNAME, SNAME, DNAME, CNAME, PUNIT and SUNIT values can-not contain embedded blanks.

10166 Internal parsing file error. Please report to technical support.

Contact Pharsight Technical Support for assistance: [email protected].

10167 Command encountered when reading model statements.

Check whether the model is missing an EOM statement or any commands in the model are not inside a block. See also “Model structure” on page 274.

10170 Improper use of END statement. Check to see if a compiled model was speci-fied by user. Model statements were contained in the command file.

END statements are for use only in user models. See “User Models” on page 273.

10171 The lower and upper bounds were equal for one or more model parameters. Please modify them and rerun your model.

10172 The number of observations must be greater than the number of parameters.

10173 Error degrees of freedom less than or equal to zero. Error variance and stan-dard errors or parameters cannot be estimated.

10174 Infusion model should not be used if end time is less than or equal to start time. Use bolus model if start time equals end time.

10175 Models 15, 16, and 17 do not support bolus dose <= zero, IV dose <= zero, or infusion length <= zero.

10201 Initial estimates cannot be determined for this model.

Initial estimates cannot be found for this model. If no bounds were used, try adding bounds so that the program can grid search for initial estimates.

10202 Curve stripping is only done for single dose data.

Automatic estimation of initial estimates is available for single dose data only.

10203 An error occurred during curve stripping.

Initial estimates could not be found for the model. If no bounds were used, try adding bounds so that the program can grid search for initial estimates.

10204 The requested number of exponentials could not be fit. Please try fitting a simpler model.



718

F

Initial estimates for the number of exponential terms in the specified model could not be determined. Try fitting a less complex model, less compartments.

10205 Due to failure of the curve stripping method, a grid search will be performed.

Initial estimates could not be determined for this model via curve stripping. A grid search will be used to obtain initial estimates.

10206 The initial estimates are outside of the lower or upper parameter limits. Exe-cution continuing without limits on parameter space.

The initial parameter estimates are outside of the LOWER and UPPER limits.

Troubleshooting modeling problemsOccasionally when modeling, WinNonlin will terminate abnormally, or termi-nate normally and converge to unreasonable values of the parameter esti-mates. If these types of problems occur, apply the following steps in determining what may have gone wrong.Note that it is possible that a specified model and input values may be correct, but there simply may not be enough information contained in the data to pre-cisely estimate all of the parameters in the model. If that is the case, the only recourse is to obtain additional data. Check the history file associated with the PK Data Output window. Error mes-sages may appear here as guidance in resolving the problem. If no PK Data Output window appears, check the Text (ASCII) output for error messages.If the model was defined by the user (i.e., not one of the models in WinNon-lin's built-in library), carefully check the model definition statements to make sure that there are no undefined or uninitialized variables. Also make sure that the model has not attempted any illegal arithmetic computations such as tak-ing the logarithm of zero or the square root of a negative number.Carefully check the input data set and constants to make sure the values are correct. A plot of the data can be very helpful.Check the initial values of the parameters to see if they are reasonable. One way to do this is to rerun the problem as a simulation. To do this, check the Simulate check box in the Y Variable group box in the Data Variables dialog box. Are the predicted values from the simulation reasonably close to the observed data? Often error messages occur because WinNonlin is having difficulty fitting the model to the data. In addition, warning messages may also be generated to alert the user that WinNonlin is having to work very hard to obtain the param-eter estimates, which may indicate that the model is ill-defined. The data set

Warnings and Error MessagesLinMix and Bioequivalence wizards

719

F

may be ill-conditioned or the initial parameter estimates may be too far from the true values. If these messages occur, try rerunning the problem and add LOWER and UPPER constraints. If the problem recurs, try using METHOD 1 (Nelder - Mead - via the Settings tab in the Model Options dialog box).

LinMix and Bioequivalence wizardsWhen errors occur using the LinMix or Bioequivalence wizards a message box will appear with the error number and a description of the error.

11001 Memory allocation error.

Insufficient memory. If other applications are running, save your work in these applications, close them and try again. Closing other WinNonlin win-dows would also help.

11002-11032 Internal error during calculations. Contact Pharsight Technical Support.

11050, 11051 Internal parsing error. Contact Pharsight Technical Support.

11060 Corrupted data set.

11061 Input data not rectangular.

11062 Too many levels of a classification variable.

11063 Character variables in models must be class variables.

11064 Weight variable must be numeric.

11065 The residual variance is not modeled. Try random instead of repeated.

11066 There are no degrees of freedom for residual. Try the Satterthwaite option.

11067 Dependent variable must be numeric.

11068 There are no residual degrees of freedom. No statistical tests are possible.

11069 There is no residual variance. Try a different model.

11070 Error in Satterthwaite DF. Try using Residual DF option.

11075 Error opening file.

11089 Bioequivalence statistics could not be computed for some test formulations.

11090 Asymptotic covariance matrix not computed. Information matrix is deemed singular.

11091 Newton's algorithm converged with modified Hessian. Output is suspect.

11092 Failed to converge in allocated number of iterations. Output is suspect.

11093 Starting estimates supplied by user are invalid. Using method of moments.


720

F

11094 Negative final variance component. Consider omitting this VC structure.

11095 Negative final variance parameter. Consider FA0 structure instead of UN.

11096 Negative final block term for CS. Consider omitting random model for this structure.

11097 Negative final variance parameter for TOEP structure.

11098 Negative final variance parameter for AR structure.

11099 Negative final standard deviation for ARH/CSH structure.

11101 More than 2 treatment formulations not allowed for population/individual bioequivalence.

11102 More than 10 periods not allowed for population/individual bioequivalence.

11103 More than 200 subjects not allowed for population/individual bioequivalence.

11104 More than 10 sequences not allowed for population/individual bioequiva-lence.

11105 Only 1 treatment formulation is not allowed for population/individual bioequivalence.

11106 Only 1 period is not allowed for population/individual bioequivalence.

11107 Fewer than 2 sequences had complete design. Program terminating.

11108 Missing data for dependent variable causing an incomplete design.

11109 Ln-transform requested for data that is zero or negative causing an incomplete design.

11121 Subject <name> had incomplete design and was discarded.

11122 Sequence < > had less than 2 complete subjects and was discarded.

11201 The column ColName contains alphanumeric value(s) that are greater than maxsize in length. We suggest creating a new variable with re-coded values that are less than or equal to this maximum length. Do you want to continue with shortened values?

Alpha variables are limited to a length of 128 characters.

11206 There is an error on the following tab(s): tab name(s).

This error occurs when there is an error on one of the tabs. Possibly the model is missing, or the dependent variable is missing.

11207 Failed to create model as specified in the model file.

11208 Unable to find any DATA command in command filename.

Warnings and Error MessagesTable Wizard

721

F

This error occurs when the user loads a model command file from the tool bar and this file does not contain any valid DATA statement.

11210 Unable to find file command filename

This error occurs when the specified command file does not exist.

11211 File data filename not found

This error occurs when the data file referenced by the data statement in the command file is not found.

11212 Second delimiter in filename for DATA statement not found.

11214 Variable name too long for LinMix, variable will be temporarily truncated for use by LinMix. Maximum variable name length is 256 characters.

11215 There are greater than 256 variables in your data set. The LinMix module has a limit of using no more than 256 variables. Please decrease the number of variables on the data set then rerun the LinMix module.

Table WizardWhen errors occur with the Table Wizard a message box will appear with the error number and a description of the error.

12999 Memory allocation error


Descriptive statisticsWhen errors occur in the Descriptive Statistics module a message box will appear with the error number and a description of the error.

13000 Floating Point error




722

F

Noncompartmental analysis

Error messages14001 Memory allocation error. Insufficient random access memory. If other appli-

cations are running, save work, close the applications and try again. Closing other WinNonlin windows may also help.

14002 Error opening file. Contact Pharsight Technical Support.

14021 All concentration values are zero.

14022 Only 1 non-zero concentration value found, and it was at dosing time.

14024 All volume values are zero. No grid output for this subject.

14050 Internal parsing error. Contact Pharsight Technical Support.

14061 No data in steady state dosing interval; program terminating.

14062 Duplicate time values on data file. Option: use Descriptive Statistics to com-pute mean data and perform NCA on the means.

14064 Invalid urine data: lower time >= upper time, or negative volume or concen-tration.

Warnings14501 Incompatible units for partial AUCs and summary AUCs; using default units.

14502 Incompatible units for summary table AUMC values; using default units.

14503 Incompatible units for summary table Amount values; using default units.

14504 Incompatible units for final parameter <default parameter name>; using default units.

14511 MRT parameters are adjusted for length of infusion.

14512 Adjusting for infusion has caused negative MRTlast value.

14513 Adjusting for infusion has caused negative MRTinf(obs) value.

14514 Adjusting for infusion has caused negative MRTinf(pred) value.

14515 Therapeutic window calculations cannot be done for negative data.

14520 Only one non-missing observation. All final parameters are set to missing.

14521 All concentration values are zero.

14522 Only 1 non-zero concentration value found, and it was at dosing time.

Warnings and Error MessagesScripting language

723

F

14524 All volume values are zero. All final parameters are set to missing.

14523 Less than two non-missing observations. No grid output for this subject.

14530 Lambda_z could not be estimated. No parameters could be extrapolated to infinity.

14531 AUC_TAU could not be estimated. Steady state PK parameters could not be estimated.

14532 The value at dosing time could not be determined by log-linear regression of the first two measurements, and was set to the first observed measurement. You may also try using a constant infusion model.

Scripting languageErrors that are generated when using the Scripting Language are written to the data log file. Please consult this log for guidance in resolving problems with script files. If no errors exist, this log file will not be created.




724

F

725

Appendix G

Visual Basic Automation ReferenceWinNonlin automation properties, methods and variables

Chart moduleInstancing: MultiUse

AxisLabelsFont PropertyReturns or sets the font for the axis labels.

Example: object.AxisLabelsFont(AxisIdX) = “Arial”See Also: AxisLabelsFontSize Property, AxisTitleFont PropertyApplies To: Chart object

AxisLabelsFontSize PropertyReturns or sets the font size for the axis labels.

Example: object.AxisLabelsFontSize(AxisIdX) = 10See Also: AxisLabelsFont Property, AxisTitleFontSize PropertyApplies To: Chart object

AxisTitle PropertyReturns or sets the axis title.

Example: object.AxitTitle(AxisIdX) = “Time”See Also: ChartTitle Property

Parameter Type (Default) DescriptionnAxisID WnlAxisIDConstants This parameter determines the axis to modify.




726

G

Applies To: Chart object

AxisTitleFont PropertyReturns or sets the font for the axis title.

Example: object.AxisTitleFont(AxisIdX) = “Arial”See Also: AxisTitleFontSize Property, AxisLabelsFont PropertyApplies To: Chart object

AxisTitleFontSize PropertyReturns or sets the font size for the axis title.

Example: object.AxisTitleFontSize(AxisIdX) = 10See Also: AxisTitleFont Property, AxisLabelsFontSize PropertyApplies To: Chart object

AxisUnits PropertyReturns or sets the units in the axis title.

Example: object.AxisUnits(AxisIdX) = “hr”Applies To: Chart object

CaptionPrefix PropertyRead-only property that returns the caption prefix of an object. Remarks: The caption prefix precedes the object type in the object windows caption.Example: sPrefix = object.CaptionPrefixApplies To: Chart object, Workbook object, TextEditor object

Changed PropertyReturns or sets the changed status of the object. Remarks: When the value is True, a file save warning will be shown when the object is closed.Example: object.Changed = False




Visual Basic Automation ReferenceChart module

727

G

Applies To: Chart object, Workbook object, TextEditor object

ChartCountForTab PropertyRead-only property returns the number of charts (or profiles) for the specified tab.

Example: nCharts = object.ChartCountForTabSee Also: MoveFirst Method, MoveNext Method, MovePrevious Method, MoveLast Method, CurrentChartForTab PropertyApplies To: Chart object

ChartTitle PropertyReturns or sets the chart title. Example: object.ChartTitle = “My Chart Title”See Also: AxisTitle PropertyApplies To: Chart object

CurrentChartForTab PropertyRead-only property returns the current chart for the active tab. Example: nChart = object.CurrentChartForTabSee Also: MoveFirst Method, MoveNext Method, MovePrevious Method, MoveLast Method, ChartCountForTab PropertyApplies To: Chart object

EditCopy MethodCopies the current chart to the clipboard. Example: object.EditCopyApplies To: Chart object

Filename PropertyReturns or sets the file name of the object. Example: object.filename = “c:\data\myfile.pco”See Also: FileType PropertyApplies To: Chart object, Workbook object, TextEditor object

Parameter Type (Default) DescriptionnTab Integer (0) (Optional) The tab to return the chart count for

or the active tab if nTab is zero or unspecified.


728

G

FileType PropertyReturns and set the file type. Example: object.FileType = FileFWChartSee Also: Filename PropertyApplies To: Chart object, Workbook object, TextEditor object

FootnoteFont PropertyReturns or sets the font for the chart footnote. Remarks: The chart footnote is used to display sort key information.Example: object.FootnoteFont = “Arial”See Also: FootnoteFontSize Property, TitleFont Property, LegendFont PropertyApplies To: Chart object

FootnoteFontSize PropertyReturns or sets the font size for the chart footnote. Remarks: The chart footnote is used to display sort key information.Example: object.FootnoteFontSize = 8See Also: FootnoteFont Property, TitleFontSize Property, LegendFontSize PropertyApplies To: Chart object

FormCaption PropertyRead-only property that returns the caption of the objects window. Example: sCaption = object.FormCaptionApplies To: Chart object, Workbook object, TextEditor object

ID PropertyRead-only property that returns the ID of the object. Remarks: The ID property is only valid during a WinNonlin session. It is not persis-tent.Example: sID = object.IDSee Also: UUID PropertyApplies To: Chart object, Workbook object, TextEditor object

Image PropertyRead-only property that returns a bitmap image of the current chart. See Also: EditCopy Property


729

G


LegendFont PropertyReturns or sets the font for the chart legend. Example: object.LegendFont = “Arial”See Also: LegendFontSize Property, TitleFont Property, FootnoteFont PropertyApplies To: Chart object

LegendFontSize PropertyReturns or sets the font size for the legend font. Example: object.LegendFontSize = 12See Also: LegendFont Property, TitleFontSize Property, FootnoteFontSize PropertyApplies To: Chart object

LoadTemplate MethodLoads a chart template file.

Remarks: Templates store formatting options for charts, e.g., line color and markers.Example: object.LoadTemplate “studytemplate.gtp”See Also: SaveTemplate MethodApplies To: Chart object

MoveFirst MethodThis method moves to the first chart on the active tab. Remarks: This method only applies to charts with sort keys.Example: object.MoveFirstSee Also: MoveNext Method, MovePrevious Method, MoveLast Method, Sheet Method, SortLevel MethodApplies To: Chart object

MoveLast MethodThis method moves to the last chart on the active tab. Remarks: This method only applies to charts with sort keys.Example: object.MoveLastSee Also: MoveFirst Method, MoveNext Method, MovePrevious Method, Sheet Method, SortLevel Method

Parameter Type (Default) DescriptionsFile String (Optional) The name of the template file.


730

G


MoveNext MethodThis method moves to the next chart on the active tab. Remarks: This method only applies to charts with sort keys.Example: object.MoveNextSee Also: MoveFirst Method, MovePrevious Method, MoveLast Method, Sheet Method, SortLevel MethodApplies To: Chart object

MovePrevious MethodThis method moves to the previous chart on the active tab. Remarks: This method only applies to charts with sort keys.Example: object.MovePreviousSee Also: MoveFirst Method, MoveNext Method, MoveLast Method, Sheet Method, SortLevel MethodApplies To: Chart object

Name PropertyReturns or sets the name of the object. Remarks: This value is used in various modules of the application where filename may not be sufficient.Example: object.Name = “MyChart”Applies To: Chart object, Workbook object, TextEditor object

PrintAll MethodThis method prints all the charts for the object. Example: object.PrintAllSee Also: PrintOut Method, PrintMulti Property, PrintMultiAcross Property, PrinMul-tiDown PropertyApplies To: Chart object

PrintMulti PropertyReturns or sets the PrintMulti property. Remarks: When set to WnlYes, the PrintAll method will print multiple charts per page.Example: object.PrintMulti = WnlYes


731

G

See Also: PrintAll Method, PrintMultiAcross Property, PrinMultiDown PropertyApplies To: Chart object

PrintMultiAcross PropertyReturns or sets the number of charts to print across the page. Example: object.PrintMultiAcross = 2See Also: PrintAll Method, PrintMulti Property, PrinMultiDown PropertyApplies To: Chart object

PrintMultiDown PropertyReturns or sets the number of charts to print down the page. Example: object.PrintMultiDown = 3See Also: PrintAll Method, PrintMulti Property, PrinMultiAcross PropertyApplies To: Chart object

PrintOut MethodThis method prints the active chart for the object. Example: object.PrintOutSee Also: PrintAll MethodApplies To: Chart object, Workbook object, TextEditor object

ReadOnly PropertyReturns or sets the read-only status the object. Example: object.ReadOnly = TrueApplies To: Chart object, Workbook object, TextEditor object

Save MethodSaves the object to file. Example: object.SaveApplies To: Chart object, Workbook object, TextEditor object

SaveAllCharts MethodSaves all the charts for the object. Remarks: This method uses the SaveAllPrefix property when saving the files and appends a number to the prefix.Example: object.SaveAllCharts


732

G

See Also: SaveAllPrefix PropertyApplies To: Chart object

SaveAllPrefix PropertyThe is the text that will prefix all the file names when a call to the SaveAllCharts method is made. Remarks: A series of numbers will be used after the prefix to identify different files.Example: object.SaveAllPrefix = “NCA_OUT”See Also: SaveAllCharts MethodApplies To: Chart object

SaveTemplate MethodSaves a chart template file.

Remarks: Templates store formatting options for charts, such as line color and mark-ers.Example: object.SaveTemplate “settings.gtp”See Also: LoadTemplate MethodApplies To: Chart object

Sheet MethodChanges the active sheet (or tab) based on the sheet name.

Remarks: If the sheet name is not found, then the active sheet is not changed.Example: object.Sheet “Observed vs. Predicted”See Also: MoveFirst Method, MoveNext Method, MovePrevious Method, MoveLast Method, SortLevel MethodApplies To: Chart object, Workbook object

SortLevel MethodMoves to the chart of the specified profile.

Remarks: This method only applies to charts with sort keys.Example: object.SortLevel “SubjectA”

Parameter Type (Default) DescriptionsFile String (Optional) Name of the template file.

Parameter Type (Default) DescriptionsSheetName String (Optional) The name of the sheet (or tab) to activate.

Parameter Type (Default) DescriptionsKey String (Optional) The name of the sort profile to find.


733

G

See Also: MoveFirst Method, MoveNext Method, MovePrevious Method, MoveLast Method, Sheet MethodApplies To: Chart object

Source PropertyRead-only property that returns the source object. Applies To: Chart object

Tag PropertyReturns or sets a tag value for an object. Remarks: can be used to give an object a unique identifying value.Example: object.Tag = “Input chart”Applies To: Chart object, Workbook object, TextEditor object

TitleFont PropertyReturns or sets the font for the chart title. Example: object.TitleFont = “Arial”See Also: TitleFontSize Property, FootnoteFont Property, LegendFont PropertyApplies To: Chart object

TitleFontSize PropertyReturns or sets the font size for the chart title. Example: object.TitleFontSize = 14See Also: TitleFont Property, FootnoteFontSize Property, LegendFontSize PropertyApplies To: Chart object

Uniform PropertyReturns or sets the uniform axis scaling of the object.

Remarks: When set to WnlYes, the axis for each chart will have the same scale. This property only applies to chart with sort keys.Example: object.Uniform(nAxisIdX) = WnlYesApplies To: Chart object

UUID PropertyRead-only property to get the UUID for the object.

Parameter Type (Default) DescriptionnAxisID VtChAxisId (Optional) The axis to modify.


734

G

Remarks: This property is persistent when the object is saved in the proprietary for-mat.Example: sUUID = object.UUIDSee Also: ID PropertyApplies To: Chart object, Workbook object, TextEditor object

WindowState PropertyReturns or sets the window state of the object. Example: object.WindowState = WindowStateConstantsMinimizedApplies To: Chart object, Workbook object, TextEditor object

Charts module

Count PropertyReturns a count of items in the collection. Returns: Returns the number of items in the collection.Applies To: Charts object, Workbooks object, TextEditors object, Variables object

Item PropertyReturns a specific member of the collection object either by position or by key.

Returns: Returns a Chart object.Applies To: Charts object, Workbooks object, TextEditors object, Variables object

Crossover moduleInstancing: MultiUse

InBook PropertyReturns or sets a reference to the input workbook. Example: Set object.InBook = MyBookSee Also: OutBook Property

Parameter Type DescriptionIndex Variant An expression that specifies the position of a member of the col-

lection. If a numeric expression, index must be a number from 1 to the value of the collections Count property. If a string expres-sion, index must correspond to the key argument specified when the member referred to was added to the collection.

Visual Basic Automation ReferenceCrossover module

735

G

Applies To: Crossover object, Deconvolution object, DescStats object, LinMix object, Plot object, Semicomartmental object, Superposition object, Table object

OutBook PropertyRead-only property with a reference to the output workbook. Remarks: The value of this property is Nothing until the engine is run.Example: Set MyOutBook = object.OutBookSee Also: InBook PropertyApplies To: Crossover object, Deconvolution object, DescStats object, LinMix object, Merge object, Pk object, Plot object, Semicomartmental object, Superposition object, Table object

ResponseVar PropertyReturns or sets the response variable. Remarks: This variable should only be set when TreatmentData = TreatDataStackedExample: object.ResponseVar.Name = “Response”See Also: SequenceVar PropertyApplies To: Crossover object

Run MethodThe Run method runs the crossover analysis based on the current settings. Example: object.RunApplies To: Crossover object

SequenceVar PropertyReturns or sets the sequence variable. Example: object.SequenceVar.Name = “Seq”See Also: ResponseVar PropertyApplies To: Crossover object

SortVars PropertyReturns or sets the sort variables. Example: object.SortVars.AddEx “Sort1”, , “Subject”, , Sort, 1

See Also: TimeVar Property, ConcVar PropertyApplies To: Crossover object, Deconvolution object, DescStats object, Plot object, Semicompartmental object, Superposition object


736

G

SubjectVar PropertyReturns or sets the subject variable. Example: object.SubjectVar.Name = “Subject”Applies To: Crossover object

TreatmentAVar PropertyReturns or sets the treatment A variable. Remarks: This variable should only be set when TreatmentData = TreatDataSeparateExample: object.TreatmentAVar.Name = “TreatA”See Also: TreatmentBVar PropertyApplies To: Crossover object

TreatmentBVar PropertyReturns or sets the treatment B variable. Remarks: This variable should only be set when TreatmentData = TreatDataSeparateExample: object.TreatmentBVar.Name = “TreatB”See Also: TreatmentAVar PropertyApplies To: Crossover object

TreatmentData PropertyReturns or sets if input data is stacked or in separate columns Example: object.TreatmentData = TreatDataSeparateApplies To: Crossover object

TreatmentVar PropertyReturns or sets the treatment variable. Remarks: This variable should only be set when TreatmentData = TreatDataStackedExample: object.TreatmentVar.Name = “TreatA”See Also: TreatmentVar PropertyApplies To: Crossover object

Deconvolution moduleInstancing: MultiUse

Visual Basic Automation ReferenceDeconvolution module

737

G

AlphaTerm PropertyReturns or sets the Alpha value.

Remarks: The Index must be between 1 and the value of NumTerms.Example: object.AlphaTerm(1) = 1.5See Also: NumTerms Property, ATerm PropertyApplies To: Deconvolution object

ATerm PropertyReturns or sets the A value.

Remarks: The Index must be between 1 and the value of NumTerms.Example: object.ATerm(1) = 1.5See Also: NumTerms Property, AlphaTerm PropertyApplies To: Deconvolution object

Bolus PropertyReturns or sets whether the program will constrain the derivative of the estimated input rate to be zero at the initial time. Example: object.Bolus = WnlNoApplies To: Deconvolution object

ConcVar PropertyReturns or sets the concentration variable. Example: object.ConcVar.Name = “Conc”See Also: SortVars Property, TimeVar PropertyApplies To: Deconvolution object

Delta PropertyReturns or sets the smoothing parameter. Remarks: This value is only used when Smoothing is set to SmoothingUser.Example: object.Smoothing = 5See Also: Smoothing PropertyApplies To: Deconvolution object

Parameter Type (Default) DescriptionIndex Integer The Alpha value to set.

Parameter Type (Default) DescriptionIndex Integer The A value to set.


738

G

DoseUnits PropertyReturns or sets the dose units. Example: object.DoseUnits = “mg”Applies To: Deconvolution object

InBook PropertyReturns or sets a reference to the input workbook. Example: Set object.InBook = MyBookSee Also: OutBook Property, OutChart PropertyApplies To: Deconvolution object, Crossover object, DescStats object, LinMix object, Plot object, Semicomartmental object, Superposition object, Table object

InputLag PropertyReturns or sets whether the program will constrain the estimated input rate to be zero at the initial time. Example: object.InputLag = WnlYesApplies To: Deconvolution object

NumPoints PropertyReturns or sets the number of output data points. Remarks: The default value is 101. The maximum value is 1001.Example: object.NumPoints = 500Applies To: Deconvolution object

NumTerms PropertyReturns or sets the number of exponential terms in the unit impulse response. Remarks: The number of terms must be between 1 and 9.Example: object.NumTerms = 3See Also: ATerm Property, AlphaTerm PropertyApplies To: Deconvolution object

OutBook PropertyRead-only property with a reference to the output workbook. Remarks: The value of this property is Nothing until the engine is run.Example: Set MyOutBook = object.OutBookSee Also: InBook Property, OutChart Property

Visual Basic Automation ReferenceDeconvolution module

739

G

Applies To: Deconvolution object, Crossover object, DescStats object, LinMix object, Merge object, Pk object, Plot object, Semicomartmental object, Superposition object, Table object

OutChart PropertyRead-only property with a reference to the output chart. Remarks: the value of this property is Nothing until the engine is run.Example: Set MyOutChart = object.OutChartSee Also: InBook Property, OutBook PropertyApplies To: Deconvolution object, Pk object, Plot object, Semicompartmental object, Superposition object

OutputFrom PropertyReturns or sets the start time for output. Remarks: This property is only used when OutputRange is set to OutRangeUser.Example: object.OutputFrom = 6See Also: OutputRange Property, OutputTo PropertyApplies To: Deconvolution object

OutputRange PropertyReturns or sets the range of output values. Remarks: If set to OutRangeZeroToLast then the range of output is from zero to the last time point from the input data set. If set to OutRangeUser, then the range must be defined by the OutputFrom and OutputTo properties.Example: object.OutputRange = OutRangeZeroToLastSee Also: OutputFrom Property, OutputTo PropertyApplies To: Deconvolution object

OutputTo PropertyReturns or sets the end time for output. Remarks: This property is only used when OutputRange is set to OutRangeUser.Example: object.OutputTo = 24See Also: OutputRange Property, OutputFrom PropertyApplies To: Deconvolution object

Run MethodThe Run method runs the deconvolution engine based on the current settings.


740

G

Remarks: The InBook, TimeVar and ConcVar properties must be set before the Run method is called. The Run method sets the OutBook and OutChart properties.Example: object.RunApplies To: Deconvolution object

Smoothing PropertyReturns or sets the type of smoothing to use. Remarks: If set SmoothingNone the input function is just the piecewise linear precur-sor function. If set to SmoothingUser the user can set the value of the dispersion parameter. If set to SmoothingAutomatic the program finds the optimal value for the dispersion parameter gamma.Example: object.Smoothing = SmoothingAutomaticSee Also: Delta PropertyApplies To: Deconvolution object


See Also: TimeVar Property, ConcVar PropertyApplies To: Deconvolution object, Crossover object, DescStats object, Plot object, Semicompartmental object, Superposition object

TimeVar PropertyReturns or sets the time variable. Example: object.TimeVar.Name = “Time”See Also: SortVars Property, ConcVar PropertyApplies To: Deconvolution object

DescStats moduleInstancing: MultiUse

BoxWhiskerPlot PropertyReturns or sets if a box and whiskers plot is generated with the output. Remarks: The box and whiskers plot is generated in a separate text window.Example: object.BoxWhiskerPlot = TrueApplies To: DescStats object

Visual Basic Automation ReferenceDescStats module

741

G

Confidence PropertyReturns or sets if a confidence interval is calculated. Example: object.confidence = WnlYesApplies To: DescStats object

ConfidenceValue PropertyReturns or sets the confidence value. Remarks: This property is only used if the value of Confidence is True.Example: object.ConfidenceValue = 90Applies To: DescStats object

InBook PropertyReturns or set a reference to the input workbook. Example: Set object.InBook = MyBookSee Also: OutBook Property, OutText PropertyApplies To: DescStats object, Crossover object, Deconvolution object, LinMix object, Plot object, Semicomartmental object, Superposition object, Table object

MultiSheet PropertyReturns or sets if summary statistics for each variable are on one output worksheet or a separate worksheet for each summary variable. Remarks: If set to True, the output will be on multiple sheets. If all are shown on one worksheet, any units associated with the variables will be dropped. If the summary statistics are shown on separate worksheets, the units can be displayed.Example: object.MultiSheet = TrueApplies To: DescStats object

OutBook PropertyRead-only property with a reference to the output workbook. Remarks: The value of this property is Nothing until the engine is run.Example: Set MyOutBook = object.OutBookSee Also: InBook Property, OutText PropertyApplies To: DescStats object, Crossover object, Deconvolution object, LinMix object, Merge object, Pk object, Plot object, Semicomartmental object, Superposition object, Table object


742

G

OutText PropertyRead-only property with a reference to the output text editor. Remarks: The value of this property is Nothing until the engine is run. This text win-dow contains the box and whiskers plot if BoxWhiskerPlot is True.Example: Set MyOutText = object.OutTextSee Also: InBook Property, OutBook PropertyApplies To: DescStats object, Crossover object, Deconvolution object, LinMix object, Merge object, Pk object, Plot object, Semicomartmental object, Superposition object, Table object

Percentiles PropertyReturns or sets if percentiles are included in the output. Example: object.Percentiles = WnlYesApplies To: DescStats object

Run MethodThe Run method runs the descriptive statistics engine based on the current settings. Remarks: The InBook and SummaryVars properties must be set before the Run method is called. The Run method sets the OutBook and optionally the OutText prop-erties.Example: object.RunApplies To: DescStats object, Crossover object, Deconvolution object, LinMix object, Merge object, Pk object, Plot object, Semicompartmental object, Superposition object


See Also: SummaryVars Property, WeightVar PropertyApplies To: DescStats object, Crossover object, Deconvolution object, Plot object, Semicompartmental object, Superposition object

SummaryVars PropertyReturns or sets the summary variables. Example: object.SummaryVars.AddEx “Summary1”, , “Conc”, , Summary, 1

See Also: SortVars Property, WeightVar Property

Visual Basic Automation ReferenceLinMix module

743

G

Applies To: DescStats object, Crossover object, Deconvolution object, Plot object, Semicompartmental object, Superposition object

WeightVar PropertyReturns or sets the weight variable. Example: object.WeightVar.Name = “Weight”See Also: SortVars Property, SummaryVars PropertyApplies To: DescStats object

LinMix moduleInstancing: GlobalMultiUse

Filename PropertyReturns or sets the name of the LinMix command file. Remarks: The file must be a valid LML or ANV file.Example: object.filename = “c:\data\project.lml”Applies To: LinMix object

OutBook PropertyRead-only property with a reference to the output workbook. Remarks: The value of this property is Nothing until the engine is run.Example: Set MyOutBook = object.OutBookSee Also: InBook Property, OutText PropertyApplies To: LinMix object, Crossover object, Deconvolution object, DescStats object, Merge object, Pk object, Plot object, Semicomartmental object, Superposition object, Table object

OutText PropertyRead-only property with a reference to the output text editor. Remarks: The value of this property is Nothing until the engine is run.Example: Set MyOutText = object.OutTextSee Also: InBook Property, OutBook PropertyApplies To: LinMix object, Crossover object, Deconvolution object, DescStats object, Merge object, Pk object, Plot object, Semicomartmental object, Superposition object, Table object


744

G

Run MethodThe Run method runs the LinMix engine based on the current settings. Remarks: The InBook and Filename properties must be set before the Run method is called. The Run method sets the OutBook and optionaly the OutText properties.Example: object.RunApplies To: LinMix object, Crossover object, Deconvolution object, DescStats object, Merge object, Pk object, Plot object, Semicompartmental object, Superposition object

Merge moduleInstancing: MultiUse

CarryAlong PropertyReturns or sets if data is carried along for like sort keys. Remarks: When set to WnlYes, and one data set has more observations for a given level of the Sort Variable(s), the last value for that level of the Sort Variables in the other data set will be carried down to all observations for that level of the Sort vari-ables in the new data set.Example: object.CarryAlong = WnlYesApplies To: Merge object

InBook1 PropertyReturns or sets a reference to one of the input workbooks. Example: Set object.InBook1 = MyBook1See Also: InBook2 Property, OutBook PropertyApplies To: Merge object

InBook2 PropertyReturns or sets a reference to one of the input workbooks. Example: Set object.InBook2 = MyBook2See Also: InBook1 Property, OutBook PropertyApplies To: Merge object

IncludeVars1 PropertyReturns or sets the include variables for input workbook 1. Example: object.IncludeVars1.AddEx “Include1”, , “Conc”, , IncludeVar, 1

See Also: SortVars1 Property, SortVars2 Property, IncludeVars2 Property

Visual Basic Automation ReferenceMerge module

745

G

Applies To: Merge object

IncludeVars2 PropertyReturns or sets the include variables for input workbook 2. Example: object.IncludeVars2.AddEx “Include1”, , “Conc”, , IncludeVar, 1

See Also: SortVars1 Property, SortVars2 Property, IncludeVars1 PropertyApplies To: Merge object

Missing PropertyReturns or sets the missing value used in the output workbook. Example: object.Missing = “.”Applies To: Merge object

OutBook PropertyRead-only property with a reference to the output workbook. Remarks: The value of this property is Nothing until the engine is run.Example: Set MyOutBook = object.OutBookSee Also: InBook1 Property, InBook2 PropertyApplies To: Merge object, Crossover object, Deconvolution object, DescStats Prop-erty, LinMix object, Pk object, Plot object, Semicomartmental object, Superposition object, Table object

Run MethodThe Run method performs the merge based on the current settings. Remarks: The Run method sets the OutBook property.Example: object.RunApplies To: Merge object, Crossover object, Deconvolution object, DesStats object, LinMix object, Pk object, Plot object, Semicompartmental object, Superposition object

SortVars1 PropertyReturns or sets the sort variables for input workbook 1. Example: object.SortVars1.AddEx “Sort1”, , “Subject”, , Sort, 1

See Also: SortVars2 Property, IncludeVars1 Property, IncludeVars2 PropertyApplies To: Merge object


746

G

SortVars2 PropertyReturns or sets the sort variables for input workbook 2. Example: object.SortVars2.AddEx “Sort1”, , “Subject”, , Sort, 1

See Also: SortVars1 Property, IncludeVars1 Property, IncludeVars2 PropertyApplies To: Merge object

Model moduleInstancing: MultiUse

Changed PropertyReturns or sets the changed status of the object. Remarks: When the value is True, a file save warning will be shown when the object is closed.Example: object.Changed = FalseApplies To: Model object, Workbook object, Chart object, TextEditor object

ID PropertyRead-only property that returns the ID of the object. Remarks: The ID property is only valid during a WinNonlin session. It is not persis-tent.Example: sID = object.IDSee Also: UUID PropertyApplies To: Model object, Workbook object, Chart object, TextEditor object

LoadDoseFile MethodLoads an ASCII data file containing model dosing information.

Example: object.LoadDoseFile “c:\data\dosefile.dat”See Also: LoadLambdazFile method, LoadLinkFile method, LoadNamesFile method, LoadParamFile method, LoadPartialAreasFile method, LoadUnitsFile methodApplies To: Model object

Parameter Type (Default) DescriptionsFile String The name of the file to load.

Visual Basic Automation ReferenceModel module

747

G

LoadLambdazFile MethodLoads an ASCII data file containing Lambda_z information for NCA models.

Example: object.LoadLambdazFile “c:\data\lzfile.dat”See Also: LoadDoseFile method, LoadLinkFile method, LoadNamesFile method, LoadParamFile method, LoadPartialAreasFile method, LoadUnitsFile methodApplies To: Model object

LoadLinkFile MethodLoads an ASCII data file containing model parameters information for PK/PD and IPR models.

Example: object.LoadLinkFile “c:\data\linkfile.dat”See Also: LoadDoseFile method, LoadLambdazFile method LoadNamesFile method, LoadParamFile method, LoadPartialAreasFile method, LoadUnitsFile methodApplies To: Model object

LoadNamesFile MethodLoads an ASCII data file containing the preferred parameter names for NCA models.

Example: object.LoadNamesFile “c:\data\namefile.dat”See Also: LoadDoseFile method, LoadLambdazFile method, LoadLinkFile method, LoadParamFile method, LoadPartialAreasFile method, LoadUnitsFile methodApplies To: Model object

LoadParamFile MethodLoads an ASCII data file containing the model parameter and boundaries informa-tion.

Example: object.LoadParamFile “c:\data\parmfile.dat”See Also: LoadDoseFile method, LoadLambdazFile method, LoadLinkFile method, LoadNamesFile method, LoadPartialAreasFile method, LoadUnitsFile methodApplies To: Model object






748

G

LoadPartialAreasFile MethodLoads an ASCII data file containing specification of time ranges for the computation of partial areas.

Example: object.LoadPartialsAreasFile “c:\data\part-file.dat”

See Also: LoadDoseFile method, LoadLambdazFile method, LoadLinkFile method, LoadNamesFile method, LoadParamFile method, LoadUnitsFile methodApplies To: Model object

LoadUnitsFile MethodLoads an ASCII data file containing the units information.

Example: object.LoadUnitsFile “c:\data\unitfile.dat”See Also: LoadDoseFile method, LoadLambdazFile method, LoadLinkFile method, LoadNamesFile method, LoadParamFile method, LoadPartialAreasFile methodApplies To: Model object

ModelWindow PropertyRead-only property that returns a reference to the text editor containing the model representation. Example: Set ModelTextEditor = object.ModelWindowApplies To: Model object

ModelWorkbook PropertyRead-only property that returns a reference to the source workbook for the model. Example: Set SourceBook = object.ModelWorkbookApplies To: Model object

Name PropertyReturns or sets the name of the object. Remarks: This value is used in various modules of the application where filename may not be sufficient.Example: object.Name = “MyModel”Applies To: Model object, Workbook object, Chart object, TextEditor object



Visual Basic Automation ReferencePK module

749

G

Source PropertyRead-only property that returns the source object. Applies To: Model object

Tag PropertyReturns or sets a tag value for an object. Remarks: This property can be used to give an object a unique identifying value.Example: object.Tag = “Model 13"Applies To: Model object, Workbook object, Chart object, TextEditor object

UUID PropertyRead-only property to get the UUID for the object. Remarks: This property is persistent when the object is saved in the proprietary for-mat.Example: sUUID = object.UUIDSee Also: ID PropertyApplies To: Model object, Workbook object, Chart object, TextEditor object

PK moduleInstancing: MultiUse

OutBook PropertyRead-only property with a reference to the output workbook. Remarks: The value of this property is Nothing until the engine is run.Example: Set MyOutBook = object.OutBookSee Also: OutChart Property, OutText PropertyApplies To: Pk object, Crossover object, Deconvolution object, DescStats object, Lin-Mix object, Merge object, Plot object, Semicomartmental object, Superposition object, Table object

OutChart PropertyRead-only property with a reference to the output chart. Remarks: the value of this property is Nothing until the engine is run.Example: Set MyOutChart = object.OutChartSee Also: OutBook Property, OutText Property


750

G

Applies To: Pk object, Deconvolution object, Plot object, Semicompartmental object, Superposition object

OutText PropertyRead-only property with a reference to the output text editor. Remarks: The value of this property is Nothing until the engine is run.Example: Set MyOutText = object.OutTextSee Also: OutBook Property, OutChart PropertyApplies To: Pk object, Crossover object, Deconvolution object, DescStats object, Lin-Mix object, Merge object, Plot object, Semicomartmental object, Superposition object, Table object

Run MethodThe Run method executes the appropriate modeling engine based on the active model. Remarks: A valid model must be loaded before this method can be called success-fully. The Run method sets the OutBook and optionaly the OutText properties.Example: object.RunSee Also: RunWordExport MethodApplies To: Pk object, Crossover object, Deconvolution object, DescStats object, Lin-Mix object, Merge object, Plot object, Semicompartmental object, Superposition object

RunWordExport MethodThe RunWordExport method executes the appropriate modeling engine based on the active model and exports the output into a Word document. Remarks: A valid model must be loaded before this method can be called success-fully. The Run method sets the OutBook and optionaly the OutText properties. Word must be properly installed to execute this method.Example: object.RunSee Also: WordExportFilename Property, Run MethodApplies To: Pk object

WordExportFilename PropertyReturns or sets the file name used to save the Word document after the RunWordEx-port method is called. Remarks: If this property is not set, then the Word document is not saved after the RunWordExport method.

Visual Basic Automation ReferencePlot module

751

G

Example: object.WordExportFilename = “c:\data\model3_out.doc”

See Also: RunWordExport MethodApplies To: Pk object

Plot moduleInstancing: MultiUse

AutoSort PropertyReturns or sets the value for auto sorting. Remarks: When set to WnlYes, the plot engine will automatically sort on the x vari-able column before creating the chart.Example: object.AutoSort = WnlYesApplies To: Plot object

ChartType PropertyReturns or sets the chart type. Example: object.ChartType = ChartTypeScatterApplies To: Plot object

DownVar PropertyReturns or sets the variable for Down error data.

Remarks: The index will range from 1 to the number of data sets used.Example: object.DownVar.Name = “DownErr”See Also: UpVar PropertyApplies To: Plot object

ErrType PropertyReturns or sets the value for how to handle error data. Remarks: If set to ErrTypeRelative, the error data is calculated as an offset to the y data value. If set to absolute, the error data is plotted as its value.Example: object.ErrType = ErrTypeRelativeApplies To: Plot object

Parameter Type (Default) DescriptionIndex Integer The index to the data set for setting Down error variable.


752

G

GroupVars PropertyReturns or sets the group variables used in the chart.

Remarks: The Index will range from 1 to the number of data sets used.Example: object.GroupVars(1).AddEx “Form”, , “Form”, , Group, 1

See Also: SortVars Property, XVars Property, YVars PropertyApplies To: Plot object

InBook PropertyReturns or sets an input workbook.

Remarks: Index must be between 1 and NumBook.Example: object.InBook(1) = clsInBookApplies To: Plot object

Intervals PropertyReturns or sets the number of intervals used in a histogram chart. Remarks: If set to 0, then the plot engine will set the number of intervals to the square root of the number of data points.Example: object.Intervals = 10Applies To: Plot object

Legend PropertyReturns or set the values used in the chart legend.

Remarks: This is only available when using multiple data sets or overlay plots.Example: object.Legend(1) = “Data Set 1”Applies To: Plot object

NumBook PropertyReturns or sets the number of workbooks used to create the chart. Remarks: The value for NumBook must be between 1 and 99.

Parameter Type (Default) DescriptionIndex Integer The index to the data set for setting group variables.

Parameter Type (Default) DescriptionIndex Integer The index to the workbook to set.

Parameter Type (Default) DescriptionIndex Integer Index to the legend value to set.

Visual Basic Automation ReferencePlot module

753

G

Example: object.NumBook = 1Applies To: Plot object

OutChart PropertyRead-only property returns a reference to the output workbook. Remarks: The value of this property is Nothing until the Run method has been called.Example: Set clsChart = object.OutChartApplies To: Plot object

Run MethodThe Run method creates the new chart based on the current settings in the Plot engine. Example: object.RunApplies To: Plot object

ShowUnits PropertyReturns or sets the value for showing units. Remarks: If set to WnlYes, the units (if any) will appear on the chart when created.Example: object.ShowUnits = WnlYesSee Also: XUnits Property, YUnits PropertyApplies To: Plot object

SortVars PropertyReturns or sets the sort variables used in the chart.

Remarks: The Index will range from 1 to the number of data sets used.Example: object.SortVars(1).AddEx “Subject”, , “Subject”, , Sort, 1

See Also: GroupVars Property, XVars Property, YVars PropertyApplies To: Plot object

Title PropertyReturns or sets the chart title. Example: object.Title = “my Chart Title”See Also: XTitle Property, YTitle PropertyApplies To: Plot object

Parameter Type (Default) DescriptionIndex Integer The index to the data set for setting sort variables.


754

G

UpVar PropertyReturns or sets the variable for up error data.

Remarks: The index will range from 1 to the number of data sets used.Example: object.UpVar.Name = “UpErr”See Also: DownVar PropertyApplies To: Plot object

UseGroupHeaders PropertyReturns or sets whether to use group headers in the legend. Remarks: When set to WnlYes, column headers will be used to help identify lines in the chart. Setting this to WnlNo can help save chart space.Example: object.UseGroupHeaders = WnlNoApplies To: Plot object

UsePatterns PropertyReturns or sets the value for whether to use patterns. Remarks: This property only applies to bar charts and histograms. If set the WnlYes, then patterns will be used to fill in the bars on the chart.Example: object.UsePatters = WnlYesApplies To: Plot object

XTitle PropertyReturns or sets the x-axis title. Example: object.XTitle = “Time”See Also: Title Property, YTitle PropertyApplies To: Plot object

XUnits PropertyReturns or sets the value for the x-axis units. Example: object.XUnits = “hr”See Also: ShowUnits Property, YUnits PropertyApplies To: Plot object

Parameter Type (Default) DescriptionIndex Integer The index to the data set for setting up error variable.

Visual Basic Automation ReferencePrintExportAll module

755

G

XVars PropertyReturns or sets the x variables used in the chart.

Remarks: The index will range from 1 to the number of data sets used.Example: object.XVars(1).AddEx “Time”, , “Time”, , XSee Also: SortVars Property, GroupVars Property, YVars PropertyApplies To: Plot object

YTitle PropertyReturns or sets the y-axis title. Example: object.YTitle = “Concentration”See Also: Title Property, XTitle PropertyApplies To: Plot object

YUnits PropertyReturns or sets the value for the y-axis units. Example: object.YUnits = “mg”See Also: ShowUnits Property, XUnits PropertyApplies To: Plot object

YVars PropertyReturns or sets the y variables used in the chart.

Remarks: The index will range from 1 to the number of data sets used.Example: object.YVars(1).AddEx “Time”, , “Time”, , YSee Also: SortVars Property, GroupVars Property, XVars PropertyApplies To: Plot object

PrintExportAll moduleInstancing: MultiUse

ChartFormat PropertyReturns or sets the format of charts when exported.

Parameter Type (Default) DescriptionIndex Integer The index to the data set for setting x variables.

Parameter Type (Default) DescriptionIndex Integer The index to the data set for setting y variables.


756

G

Remarks: When set to ChartFormatMetafile (Default), charts are output in metafile format. When set to ChartFormatBitmap, charts are output in bitmap format. This option only applies to export.Example: object.ChartFormat = ChartFormatBitmapApplies To: PrintExportAll object

ExportAll MethodExports all objects. Remarks: Use IncludeWorkbooks, IncludeCharts, IncludeTextEditors and Include-Models to select which objects to Export.Example: object.ExportAllSee Also: PrintAllApplies To: PrintExportAll object

FigureNum PropertySets or returns if charts are numbered in the output. Remarks: This option only applies to export.Example: object.FigureNum = WnlYesSee Also: FigureNumStart PropertyApplies To: PrintExportAll object

FigureNumStart PropertyReturns or sets the starting figure number. Remarks: This option only applies to export.Example: object.FigureNumStart = 5See Also: FigureNum PropertyApplies To: PrintExportAll object

IncludeCharts PropertyReturns or sets if Charts are included in print or export. Example: object.IncludeCharts = WnlYesSee Also: IncludeWorkbooks Property, IncludeTextEditors Property, IncludeModels PropertyApplies To: PrintExportAll object

IncludeModels PropertyReturns or sets if Models are included in print or export.

Visual Basic Automation ReferencePrintExportAll module

757

G

Example: object.IncludeModels = WnlYesSee Also: IncludeWorkbooks Property, IncludeCharts Property, IncludeTextEditors PropertyApplies To: PrintExportAll object

IncludeTextEditors PropertyReturns or sets if TextEditors are included in print or export. Example: object.IncludeTextEditors = WnlYesSee Also: IncludeWorkbooks Property, IncludeCharts Property, IncludeModels Prop-ertyApplies To: PrintExportAll object

IncludeWorkbooks PropertyReturns or sets if workbooks are included in print or export. Example: object.IncludeWorkbooks = WnlYesSee Also: IncludeCharts Property, IncludeTextEditors Property, IncludeModels Prop-ertyApplies To: PrintExportAll object

LockOutput PropertyReturns or sets if the output is locked after export. Remarks: This option only applies to export.Example: object.LockOutput = WnlYesApplies To: PrintExportAll object

LogCharts PropertyReturns or sets if log charts are output. Remarks: If set to WnlYes, then chart with a log y-axis is output for every chart in addition to the chart in linear scale.Example: object.LogCharts = WnlYesApplies To: PrintExportAll object

MultipleChartsPerPage PropertyReturns or sets if multiple charts per page are output. Remarks: Use MultipleChartsPerPageDown and MultipleChartsPerPageAcross to set the number of charts output per page.


758

G

Example: object.MultipleChartsPerPage = WnlYes : object.MultipleChartsPerPageDown = 3 : object.Multiple-ChartsPerPageAcross = 2

See Also: MultipleChartsPerPageDown Property, MultipleChartsPerPageAcross PropertyApplies To: PrintExportAll object

MultipleChartsPerPageAcross PropertyReturns or set the number of columns of charts per page to output. Remarks: The minimum value is 1 and the maximum value is 8.Example: object.MultipleChartsPerPage = WnlYes : object.MultipleChartsPerPageDown = 3 : object.Multiple-ChartsPerPageAcross = 2

See Also: MultipleChartsPerPage Property, MultipleChartsPerPageDown PropertyApplies To: PrintExportAll object

MultipleChartsPerPageDown PropertyReturns or set the number of rows of charts per page to output. Remarks: The minimum value is 1 and the maximum value is 8.Example: object.MultipleChartsPerPage = WnlYes : object.MultipleChartsPerPageDown = 3 : object.Multiple-ChartsPerPageAcross = 2

See Also: MultipleChartsPerPage Property, MultipleChartsPerPageAcross PropertyApplies To: PrintExportAll object

Orientation PropertyReturns or sets the page orientation. Example: object.Orientation = OrientationPortraitApplies To: PrintExportAll object

PreserveTableFormats PropertyReturns or sets if formatting is preserved for tables. Remarks: When set to WnlYes, formatting is preserved for workbooks that are the output of the table generator. This significantly slows down the export. This option only applies to export.Example: object.PreserveTableFormats = WnlNoApplies To: PrintExportAll object

Visual Basic Automation ReferenceRule module

759

G

PrintAll MethodPrints all objects. Remarks: Use IncludeWorkbooks, IncludeCharts, IncludeTextEditors and Include-Models to select which objects to print.Example: object.PrintAllSee Also: ExportAllApplies To: PrintExportAll object

SourceLine PropertyReturns or sets if a source line is included in the export. Remarks: This option only applies to export.Example: object.SourceLine = WnlYesApplies To: PrintExportAll object

TableNum PropertySets or returns if tables are numbered in the output. Remarks: This option only applies to export.Example: object.TableNum = WnlYesSee Also: TableNumStart PropertyApplies To: PrintExportAll object

TableNumStart PropertyReturns or sets the starting table number. Remarks: This option only applies to export.Example: object.TableNumStart = 5See Also: TableNum PropertyApplies To: PrintExportAll object

Rule moduleInstancing: MultiUsecurRuleState Property (Public Variable)

GetValue MethodNo description.

Parameter Type (Default) Descriptiondv WnlRuleType


760

G

Applies To: Rule object

IsUnConditional MethodApplies To: Rule object

LetValue MethodNo description.

Applies To: Rule object

Name Property (Public Variable)

NonNumericCode Property (Public Variable)

Semicompartmental moduleInstancing: MultiUse

ConcVar PropertyReturns or sets the concentration variable. Example: object.ConcVar.Name = "Conc"See Also: SortVars Property, TimeVar Property, EffectVar PropertyApplies To: Semicompartmental object

EffectVar PropertyReturns or sets the effect variable. Example: object.EffectVar.Name = "Effect"See Also: SortVars Property, TimeVar Property, ConcVar PropertyApplies To: Semicompartmental object

InBook PropertyReturns or set a reference to the input workbook. Example: Set object.InBook = MyBook

LLOQ Variant

Parameter Type (Default) DescriptionvNewValue Stringdv WnlRuleType

Visual Basic Automation ReferenceSemicompartmental module

761

G

See Also: OutBook Property, OutChart PropertyApplies To: Semicompartmental object, Crossover object, Deconvolution object, DescStats object, LinMix object, Plot object, Superposition object, Table object

Keo PropertyReturns or sets the Keo value. Remarks: A Keo value is required. If a given Keo value produces unwanted results, the operation must be rerun with a different Keo value specified. In addition, the Keo value applies to all sort keys.Example: object.Keo = 1.5Applies To: Semicompartmental object

Method PropertyReturns or sets the computational method. Remarks: The default is log/linear: linear to t-max and then logarithmic. The other two options are completely linear or completely logarithmic.Example: object.Method = ToolboxMethodLinearApplies To: Semicompartmental object

OutBook PropertyRead-only property with a reference to the output workbook. Remarks: The value of this property is Nothing until the engine is run.Example: Set MyOutBook = object.OutBookSee Also: InBook Property, OutChart PropertyApplies To: Semicompartmental object, Crossover object, Deconvolution object, DescStats object, LinMix object, Merge object, Pk object, Plot object, Superposition object, Table object

OutChart PropertyRead-only property with a reference to the output chart. Remarks: the value of this property is Nothing until the engine is run.Example: Set MyOutChart = object.OutChartSee Also: InBook Property, OutBook PropertyApplies To: Semicompartmental object, Deconvolution object, Pk object, Plot object, Superposition object

Run MethodThe Run method runs the semicompartmental engine based on the current settings.


762

G

Remarks: The InBook, TimeVar, ConcVar and Keo properties must be set before the Run method is called. The Run method sets the OutBook and OutChart properties.Example: object.RunApplies To: Semicompartmental object, Crossover object, Deconvolution object, DescSats object, LinMix object, Merge object, Pk object, Plot object, Superposition object

SortVars PropertyReturns or sets the sort variables. Example: object.SortVars.AddEx "Sort1", , "Subject", , Sort, 1

See Also: TimeVar Property, ConcVar Property, EffectVar PropertyApplies To: Semicompartmental object, Crossover object, Deconvolution object, DescStats object, Plot object, Superposition object

TimeVar PropertyReturns or sets the time variable. Example: object.TimeVar.Name = "Hour"See Also: SortVars Property, ConcVar Property, EffectVar PropertyApplies To: Semicompartmental object

StatusCodes moduleInstancing: MultiUsebLLOQDefined Property (Public Variable)

CarryAlongs PropertyApplies To: StatusCodes object

ConcCol PropertyApplies To: StatusCodes object

InBook PropertyApplies To: StatusCodes object

LLOQCol PropertyApplies To: StatusCodes object

Visual Basic Automation ReferenceSuperposition module

763

G

OutBook PropertyApplies To: StatusCodes object

RSets PropertyApplies To: StatusCodes object

RuleSets PropertyApplies To: StatusCodes object

RuleSetsDest PropertyApplies To: StatusCodes object

Run MethodNo description.

Applies To: StatusCodes object

RuSet PropertyApplies To: StatusCodes object

SortKeys PropertyApplies To: StatusCodes object

StatusCol PropertyApplies To: StatusCodes object

TimeCol PropertyApplies To: StatusCodes object

Superposition moduleInstancing: MultiUse

Parameter Type (Default) DescriptionsMetaData String ("") (Optional)oInBook Workbook (Nothing) (Optional)


764

G

ConcVar PropertyReturns or sets the concentration variable. Example: object.ConcVar.Name = "Conc"See Also: SortVars Property, TimeVar PropertyApplies To: Superposition object, Deconvolution object, Semicompartmental object

DisplayDose PropertyReturns or sets the display dose. Remarks: If set to zero, then steady state will be used for the display dose.Example: object.DisplayDose = 2See Also: DosingType Property, InitialDose Property, MaintenanceDose Property, Tau Property, NumDoses Property, DoseTime Property, Dose Property, TimeRepeat Prop-erty, RangeStart Property, RangeStop PropertyApplies To: Superposition object

Dose PropertyReturns or sets a dose value.

Example: object.Dose(1) = 10See Also: DosingType Property, InitialDose Property, MaintenanceDose Property, Tau Property, DisplayDose Property, NumDoses Property, DoseTime Property, TimeRe-peat Property, RangeStart Property, RangeStop PropertyApplies To: Superposition object

DoseTime PropertyReturns or sets a dosing time value.

Example: object.DoseTime(1) = 0See Also: DosingType Property, InitialDose Property, MaintenanceDose Property, Tau Property, DisplayDose Property, NumDoses Property, Dose Property, TimeRepeat Property, RangeStart Property, RangeStop PropertyApplies To: Superposition object

Parameter Type (Default) DescriptionIndex Integer The dosing time value to return or set. The Index value

must be between 1 and the value of NumDoses.

Parameter Type (Default) DescriptionIndex Integer The dosing time value to return or set. The Index value

must be between 1 and the value of NumDoses.


765

G

DosingType PropertyReturns or sets the type of dosing schedule to use. Example: object.DosingType = DosingTypeRegularSee Also: InitialDose Property, MaintenanceDose Property, Tau Property, Display-Dose Property, NumDoses Property, DoseTime Property, Dose Property, TimeRepeat Property, RangeStart Property, RangeStop PropertyApplies To: Superposition object

InBook PropertyReturns or set a reference to the input workbook. Example: Set object.InBook = MyBookSee Also: OutBook Property, OutChart PropertyApplies To: Superposition object, Crossover object, Deconvolution object, DescStats object, LinMix object, Plot object, Semicompartmental object, Table object

InitialDose PropertyReturns or sets the initial dose. Remarks: The initial dose may be a loading dose or a regular dose.Example: object.InitialDose = 15See Also: DosingType Property, MaintenanceDose Property, Tau Property, Display-Dose Property, NumDoses Property, DoseTime Property, Dose Property, TimeRepeat Property, RangeStart Property, RangeStop PropertyApplies To: Superposition object

LoadDoseFile MethodLoads an ASCII data file containing dosing information.

Example: object.LoadDoseFile "c:\data\dosefile.dat"Applies To: Superposition object

MaintenanceDose PropertyReturns or sets the maintenance dose. Example: object.MaintenanceDose = 5See Also: DosingType Property, InitialDose Property, Tau Property, DisplayDose Property, NumDoses Property, DoseTime Property, Dose Property, TimeRepeat Prop-erty, RangeStart Property, RangeStop PropertyApplies To: Superposition object



766

G

Method PropertyReturns or sets the computational method. Remarks: The default is linear.Example: object.Method = ToolboxMethodLinearApplies To: Superposition object

NumDoses PropertyReturns or sets the number of doses. Example: object.NumDoses = 5See Also: DosingType Property, InitialDose Property, MaintenanceDose Property, Tau Property, DisplayDose Property, DoseTime Property, Dose Property, TimeRepeat Property, RangeStart Property, RangeStop PropertyApplies To: Superposition object

NumPoints PropertyReturns or sets the number of output data points. Remarks: The default is 100.Example: object.NumPoints = 500Applies To: Superposition object

OutBook PropertyRead-only property with a reference to the output workbook. Remarks: The value of this property is Nothing until the engine is run.Example: Set MyOutBook = object.OutBookSee Also: InBook Property, OutChart PropertyApplies To: Superposition object, Crossover object, Deconvolution object, DescStats object, LinMix object, Merge object, Pk object, Plot object, Semicompartmental object, Table object

OutChart PropertyRead-only property with a reference to the output chart. Remarks: the value of this property is Nothing until the engine is run.Example: Set MyOutChart = object.OutChartSee Also: InBook Property, OutBook PropertyApplies To: Superposition object, Deconvolution object, Pk object, Plot object, Semi-compartmental object


767

G

RangeStart PropertyReturns or sets the lower time value of the output range. Example: object.RangeStart = 12See Also: DosingType Property, InitialDose Property, MaintenanceDose Property, Tau Property, DisplayDose Property, NumDoses Property, DoseTime Property, Dose Property, TimeRepeat Property, RangeStop PropertyApplies To: Superposition object

RangeStop PropertyReturns or sets the upper time value of the output range. Example: object.RangeStop = 24See Also: DosingType Property, InitialDose Property, MaintenanceDose Property, Tau Property, DisplayDose Property, NumDoses Property, DoseTime Property, Dose Property, TimeRepeat Property, RangeStart PropertyApplies To: Superposition object

Run MethodThe Run method runs the nonparametric superposition engine based on the current settings. Remarks: The Run method sets the OutBook and OutChart properties.Example: object.RunApplies To: Superposition object, Crossover object, Deconvolution object, DescSats object, LinMix object, Merge object, Pk object, Plot object, Semicompartmental object

SortVars PropertyReturns or sets the sort variables. Example: object.SortVars.AddEx "Sort1", , "Subject", , Sort, 1

See Also: TimeVar Property, ConcVar PropertyApplies To: Superposition object, Crossover object, Deconvolution object, DescStats object, Plot object, Semicompartmental object

Tau PropertyReturns or sets the (assumed equal) dosing interval for steady-state data. Example: object.Tau = 1.5


768

G

See Also: DosingType Property, InitialDose Property, MaintenanceDose Property, DisplayDose Property, NumDoses Property, DoseTime Property, Dose Property, Tim-eRepeat Property, RangeStart Property, RangeStop PropertyApplies To: Superposition object

TermLower PropertyReturns or sets the lower value of the terminal phase. Remarks: This property is only used when TermPhase property is WnlYes.Example: object.TermLower = 12See Also: TermPhase Property, TermUpper PropertyApplies To: Superposition object

TermPhase PropertyReturns or sets if the user defined terminal phase should be used. Example: object.TermPhase = WnlYesSee Also: TermLower Property, TermUpper PropertyApplies To: Superposition object

TermUpper PropertyReturns or sets the upper value of the terminal phase. Remarks: This property is only used when the TermPhase property is WnlYes.Example: object.TermUpper = 24See Also: TermPhase Property, TermLower PropertyApplies To: Superposition object

TimeRepeat PropertyReturns or sets the time value where dosing repeats. Example: object.TimeRepeat = 24See Also: DosingType Property, InitialDose Property, MaintenanceDose Property, Tau Property, DisplayDose Property, NumDoses Property, DoseTime Property, Dose Property, RangeStart Property, RangeStop PropertyApplies To: Superposition object

TimeVar PropertyReturns or sets the time variable. Example: object.TimeVar.Name = "Hour"See Also: SortVars Property, ConcVar Property

Visual Basic Automation ReferenceTable module

769

G

Applies To: Superposition object, Semicompartmental object

Table moduleInstancing: MultiUse

AggregateVar PropertyApplies To: Table object

CrossVars PropertyApplies To: Table object

DataOnly PropertyApplies To: Table object

DefinitionFile PropertyApplies To: Table object

DescStats PropertyApplies To: Table object

GroupVarBreak PropertyNo description.

Applies To: Table object

GroupVars PropertyApplies To: Table object

IDVars PropertyApplies To: Table object

Parameter Type (Default) DescriptionIndex Integer


770

G

InBook PropertyNo description.

Applies To: Table object

JoinCrossVars PropertyApplies To: Table object

JoinGroupVars PropertyApplies To: Table object

JoinIDVars PropertyApplies To: Table object

NumBook PropertyApplies To: Table object

OutBook PropertyApplies To: Table object

PageFooter PropertyApplies To: Table object

PageHeader PropertyApplies To: Table object

RegVars PropertyApplies To: Table object

Run MethodApplies To: Table object

ShowUnits PropertyApplies To: Table object

Parameter Type (Default) DescriptionIndex Integer

Visual Basic Automation ReferenceTextEditor module

771

G

TableNum PropertyApplies To: Table object

UnitsFormat PropertyApplies To: Table object

TextEditor moduleInstancing: MultiUse

BottomMargin PropertyReturns or sets the bottom margin for printing. Remarks: This property is set in twips. There are 1440 twips per inch.Example: object.BottomMargin = 1440See Also: TopMargin Property, LeftMargin Property, RightMargin Property, PrintOut MethodApplies To: TextEditor object

CaptionPrefix PropertyRead-only property that returns the caption prefix of an object. Remarks: The caption prefix precedes the object type in the object windows caption.Example: sPrefix = object.CaptionPrefixApplies To: TextEditor object, Workbook object, Chart object

Changed PropertyReturns or sets the changed status of the object. Remarks: When the value is True, a file save warning will be shown when the object is closed.Example: object.Changed = FalseApplies To: TextEditor object, Workbook object, Chart object

EditCopy MethodCopies the text from the object to the clipboard. Example: object.EditCopySee Also: EditCut Method, EditPaste Method, EditDelete MethodApplies To: TextEditor object


772

G

EditCut MethodCuts the text from the object and places it on the clipboard. Example: object.EditCutSee Also: EditCopy Method, EditPaste Method, EditDelete MethodApplies To: TextEditor object

EditDelete MethodDeletes the text in the current selection. Example: object.EditDeleteSee Also: EditCut Method, EditCopy Method, EditPaste MethodApplies To: TextEditor object

EditorText PropertyReturns or sets the text of a text editor. Remarks: Setting the EditorText property replaces the entire contents of a text editor with the new string.Example: sText = object.EditorTextSee Also: EditorTextRTF PropertyApplies To: TextEditor object

EditorTextLength PropertyRead-only property returns the number of characters in the text editor. Example: lLength = object.EditorTextLengthApplies To: TextEditor object

EditorTextRTF PropertyReturns or sets the text of a text editor, including all .rtf code. Remarks: Setting the EditorTextRTF property replaces the entire contents of a text editor with the new string.Example: sText = object.EditorTextRTFSee Also: EditorText PropertyApplies To: TextEditor object

EditPaste MethodPastes text from the clipboard into the current selection. Example: object.EditPasteSee Also: EditCut Method, EditCopy Method, EditDelete Method


773

G

Applies To: TextEditor object

Filename PropertyReturns or sets the file name of the object. Example: object.Filename = "c:\data\myfile.pto"See Also: FileType PropertyApplies To: TextEditor object, Workbook object, Chart object

FileType PropertyReturns and set the file type. Example: object.FileType = FileFWChartSee Also: Filename PropertyApplies To: TextEditor object, Workbook object, Chart object

Find MethodSearches the text in a text editor for a specified string. Returns: If the text searched for is found, the Find method highlights the specified text and returns the index of the first character highlighted. If the specified text is not found, the Find method returns –1.Remarks: If the text searched for is found, the Find method updates the value of the FindNextPos property to the index of the first character found plus 1.Example: lPos = object.FindSee Also: FindString Property, FindNextPos PropertyApplies To: TextEditor object

FindNextPos PropertyReturns or sets the position to start the next search. Remarks: After a successful call to the Find method, this property is updated with the position of the found string plus 1.Example: lPos = object.FindNextPosSee Also: FindString Property, Find MethodApplies To: TextEditor object

FindString PropertyReturns or sets the string to search for. Example: object.FindString = "transform"See Also: FindNextPos Property, Find Method


774

G

Applies To: TextEditor object

FormCaption PropertyRead-only property that returns the caption of the objects window. Example: sCaption = object.FormCaptionApplies To: TextEditor object, Workbook object, Chart object

ID PropertyRead-only property that returns the ID of the object. Remarks: The ID property is only valid during a WinNonlin session. It is not persis-tent.Example: sID = object.IDSee Also: UUID PropertyApplies To: TextEditor object, Workbook object, Chart object

IsModel PropertyRead-only property that determines if the object is the text window for the model. Example: bIsModel = object.IsModelApplies To: TextEditor object

LeftMargin PropertyReturns or sets the left margin for printing. Remarks: This property is set in twips. There are 1440 twips per inch.Example: object.LeftMargin = 1440See Also: TopMargin Property, BottomMargin Property, RightMargin Property, Print-Out MethodApplies To: TextEditor object

Name PropertyReturns or sets the name of the object. Remarks: This value is used in various modules of the application where filename may not be sufficient.Example: object.Name = "MyText"Applies To: TextEditor object, Workbook object, Chart object

PageHeight PropertyReturns or sets the page height.


775

G

Remarks: This property is set in twips. There are 1440 twips per pixel.Example: object.PageHeight = 11 * 1440See Also: PageWidth PropertyApplies To: TextEditor object

PageWidth PropertyReturns or sets the page width. Remarks: This property is set in twips. There are 1440 twips per pixel.Example: object.PageWidth = 8.5 * 1440See Also: PageHeight PropertyApplies To: TextEditor object

PrintOut MethodThis method prints the text object. Example: object.PrintOutSee Also: PrintAll MethodApplies To: TextEditor object, Workbook object, Chart object

ReadOnly PropertyReturns or sets the read-only status the object. Example: object.ReadOnly = TrueApplies To: TextEditor object, Workbook object, Chart object

RightMargin PropertyReturns or sets the right margin for printing. Remarks: This property is set in twips. There are 1440 twips per inch.Example: object.RightMargin = 1440See Also: TopMargin Property, BottomMargin Property, LeftMargin Property, Print-Out MethodApplies To: TextEditor object

Save MethodThis method prints the text object. Example: object.PrintOutApplies To: TextEditor object, Workbook object, Chart object


776

G

SelectAll MethodSelects all the text in the window. Example: object.SelectAllSee Also: SelectionStart Property, SelectionLength Property, SelectionText Property, SelectionTextRTF PropertyApplies To: TextEditor object

SelectionLength PropertyReturns or sets the number of characters selected. Remarks: Setting SelectionLength less than 0 causes a run-time error.Example: object.SelectionLength = object.EditorTextLengthSee Also: SelectAll Method, SelectionStart Property, SelectionLength Property, SelectionText Property, SelectionTextRTF PropertyApplies To: TextEditor object

SelectionStart PropertyReturns or sets the starting point of text selected; indicates the position of the inser-tion point if no text is selected. Remarks: Setting SelectionStart greater than the text length sets the property to the existing text length; changing SelectionStart changes the selection to an insertion point and sets SelelectionLength to 0.Example: object.SelectionStart = 0See Also: SelectAll Method, SelectionStart Property, SelectionLength Property, SelectionText Property, SelectionTextRTF PropertyApplies To: TextEditor object

SelectionText PropertyReturns or sets the string containing the currently selected text; consists of a zero-length string ("") if no characters are selected. Remarks: Setting SelectionText to a new value sets SelectionLength to 0 and replaces the selected text with the new string.Example: object.SelectionText = "new text"See Also: SelectAll Method, SelectionStart Property, SelectionLength Property, SelectionText Property, SelectionTextRTF PropertyApplies To: TextEditor object

SelectionTextRTF PropertyReturns or sets the text (in .rtf format) in the current selection of a text editor.


777

G

Remarks: Setting the SelectionTextRTF property replaces any selected text in the text editor with the new string. This property returns a zero-length string ("") if no text is selected in the control.Example: object.SelectionTextRTF = "new text"See Also: SelectAll Method, SelectionStart Property, SelectionLength Property, SelectionText Property, SelectionTextRTF PropertyApplies To: TextEditor object

Source PropertyRead-only property that returns the source object. Applies To: TextEditor object

Tag PropertyReturns or sets a tag value for an object. Remarks: This property can be used to give an object a unique identifying value.Example: object.Tag = "Input text"Applies To: TextEditor object, Workbook object, Chart object

TopMargin PropertyReturns or sets the top margin for printing. Remarks: This property is set in twips. There are 1440 twips per inch.Example: object.TopMargin = 1440See Also: BottomMargin Property, LeftMargin Property, RightMargin Property, Print-Out MethodApplies To: TextEditor object

UUID PropertyRead-only property to get the UUID for the object. Remarks: This property is persistent when the object is saved in the proprietary for-mat.Example: sUUID = object.UUIDSee Also: ID PropertyApplies To: TextEditor object, Workbook object, Chart object

WindowState PropertyReturns or sets the window state of the object. Example: object.WindowState = WindowStateConstantsMinimized


778

G

Applies To: TextEditor object, Workbook object, Chart object

TextEditors moduleInstancing: PublicNotCreatable

Count PropertyReturns a count of items in the collection. Returns: Returns the number of items in the colelction.Applies To: TextEditors object, Workbooks object, Charts object, Variables object


Returns: Returns a TextEditor object.Applies To: TextEditors object, Workbooks object, Charts object, Variables object

Variable moduleInstancing: MultiUse

Column PropertyReturns or sets the column of the variable. Example: object.Column = 3See Also: Name PropertyApplies To: Variable object

DataType PropertyReturns or sets the data type of the variable. Example: object.DataType = CharacterApplies To: Variable object

Parameter Type (Default) DescriptionIndex Variant An expression that specifies the position of a member of

the collection. If a numeric expression, index must be a number from 1 to the value of the collections Count property. If a string expression, index must correspond to the key argument specified when the member referred to was added to the collection.

Visual Basic Automation ReferenceVariable module

779

G

ID PropertyReturns or sets the variable ID. Remarks: This property is not used by WinNonlin 4.Applies To: Variable object

key PropertyRead-only property that returns the variable key. Applies To: Variable object

Mapping PropertyReturns or sets the variable mapping. Applies To: Variable object

Name PropertyReturns or sets the name of the variable. Remarks: This will generally match the name of the column in the workbook.Example: object.Name = "Subject"See Also: Column PropertyApplies To: Variable object

SortIndex PropertyReturns or sets the sort index of the variable. Example: object.SortIndex = 1See Also: SortOrder PropertyApplies To: Variable object

SortOrder PropertyReturns or sets the sorting order of the variable. Remarks: When set to SortAscending, the variable is sorted in ascending order. When set to SortDescending, the variable is sorted in descending order.Example: object.SortOrder = SortAscendingSee Also: SortIndex PropertyApplies To: Variable object

VarType PropertyReturns or sets the varaible type.


780

G

Example: object.VarType = SortApplies To: Variable object

Variables moduleInstancing: MultiUse

Add MethodThis method adds a variable object to the variables collection.

Returns: Returns a reference to the variable just added to the collection. Returns Nothing if object is not added.Example: object.Add clsVar, "Sort1"See Also: AddEx MethodApplies To: Variables object

AddEx MethodThis method creates a variable object based on the parameter values and adds it to the variables collection.

Parameter Type (Default) DescriptionobjVar Variable The variable object to add to the collection. sKey String ("") (Optional) A unique string expression that specifies a

key string that can be used, instead of a positional index, to access a member of the collection.

vBefore Variant (Optional) An expression that specifies a relative position in the collection. The member to be added is placed in the collection before the member identified by the before argument.

vAfter Variant (Optional) An expression that specifies a relative position in the collection. The member to be added is placed in the collection after the member identified by the after argument.

Parameter Type (Default) DescriptionsKey String (Optional) A unique string expression that specifies

a key string that can be used, instead of a posi-tional index, to access a member of the collection.

lID Long (Optional) Unused in WinNonlin 4. sName String (Optional) The name of the variable. This generally

corresponds to the column name.

Visual Basic Automation ReferenceVariables module

781

G

Returns: Returns a reference to the variable just added to the collection. Returns Nothing if object is not added.Remarks: Not all properties of the variable object are used by all engines.Example: object.Add "Sort1", , "Subject", , Sort, 1, SortA-scending

See Also: Add MethodApplies To: Variables object

Count MethodReturns the number of items in a collection.

Returns: The number of items in the collection.Example: lCount = object.CountApplies To: Variables object, Workbooks object, Charts object, TextEditors object

Exists MethodReturns if a specified item exists in the collection.

Returns: True if item exist, False otherwise.Example: bRet = object.Exists("Sort1")Applies To: Variables object

lCol Long (Optional) The column number of the variable. (Most engines in WinNonlin will use the column name and this value will be ignored.)

nVarType WnlVarType (Optional) The type of variable. nSortIndex Integer (Optional) The sort index of the variable if the type

is a sorting variable. nSor-tOrder

WnlSortOrder (Optional) The sort order of the variable if the type is a sorting variable.

nDataType WnlDataType (Optional) The data type of the variable. sMapping String (Optional) Unused in WinNonlin 4.

Parameter Type (Default) DescriptionnVarType WnlVarType

(All)(Optional) If specified, then the count property only returns a count for variables of the specified type.

Parameter Type (Default) DescriptionsKey String (Optional) Specifies the item in the collection to search for.

Parameter Type (Default) Description


782

G

Item MethodReturns a specific member of a collection either by position or by key.

Returns: Returns a variable object from the collection.Example: Set MyVar = object.Item(1)Applies To: Variables object, Workbooks object, Charts object, TextEditors object

ItemsByType MethodReturns a collection of variables based on the variable type specified.

Returns: A variables collection.Applies To: Variables object

Remove MethodRemoves a member of the collection.

Example: object.Remove 1See Also: RemoveAll MethodApplies To: Variables object

Parameter Type (Default) DescriptionvKey Variant (Optional) An expression that specifies the position of a

member of the collection. If a numeric expression, index must be a number from 1 to the value of the collections Count property. If a string expression, index must corre-spond to the key argument specified when the member referred to was added to the collection.

Parameter Type (Default) DescriptionnVarType WnlVarType (Optional) The variable type to return.

Parameter Type (Default)

Description

vKey Variant (Optional) An expression that specifies the position of a member of the collection. If a numeric expression, index must be a number from 1 to the value of the collections Count property. If a string expression, index must corre-spond to the key argument specified when the member referred to was added to the collection.

Visual Basic Automation ReferenceWnl4 module

783

G

RemoveAll MethodRemoves all members of the collection.

Example: object.RemoveAllSee Also: Remove MethodApplies To: Variables object

Wnl4 moduleInstancing: MultiUse

Copyright PropertyRead-only property returns the copyright information for the application. Applies To: Wnl4 object

Description PropertyRead-only property returns the description of the application. Applies To: Wnl4 object

Version PropertyRead-only property that returns the version of the application. Applies To: Wnl4 object

Workspace PropertyRead-only property that returns a reference to the workspace object. Remarks: Getting a reference to the workspace object is the first step to automating WinNonlin. All other objects in the system are created by the workspace object.Example: Dim objApp As WinNonlin4.Wnl4 : Dim objWorkspace As WinNonlin4.Workspace : Dim clsBook As Workbook : Set objApp = New WinNonlin4.Wnl4 : Set objWorkspace = Wnl4.Workspace : Set objApp = Nothing : objWork-space.OpenWorkbook clsBook, "c:\data\mydata.pwo", FileFW-Book : REM rest of code...

Applies To: Wnl4 object

Parameter Type (Default) DescriptionnVarType WnlVarType

(All)(Optional) If specified, then only variables of the specified type will be removed from the collection.


784

G

Workbook moduleInstancing: MultiUse

ActiveCol PropertyReturns or sets the active Col of the workbook. Example: object.ActiveCol = 5See Also: GetActiveCell Method, SetActiveCell Method, ActiveRow PropertyApplies To: Workbook object

ActiveRow PropertyReturns or sets the active row of the workbook. Example: object.ActiveRow = 5See Also: GetActiveCell Method, SetActiveCell Method, ActiveCol PropertyApplies To: Workbook object

ActiveSheet PropertyReturns or sets the active sheet in the workbook. Remarks: If the sheet is not found, the active sheet does not change.Example: object.Sheet = "History"See Also: NumSheets Property, SheetName PropertyApplies To: Workbook object, Chart object

Append MethodThis method appends a file to the object. Example: object.AppendSee Also: AppendFileName Property, AppendFileType Property, AppendSheet Prop-ertyApplies To: Workbook object

AppendFileName PropertyReturns or sets the file name for appending to an object. Example: object.AppendFileName = "append.dat"See Also: Append Method, AppendFileType Property, AppendSheet PropertyApplies To: Workbook object

Visual Basic Automation ReferenceWorkbook module

785

G

AppendFileType PropertyReturns or sets the file type of the file to be appended. Example: object.AppendFileType = FileASCIIDATASee Also: Append Method, AppendFileName Property, AppendSheet PropertyApplies To: Workbook object

AppendSheet PropertyReturns or sets the sheet to be appended to. Example: object.AppendSheet = 1See Also: Append Method, AppendFileName Property, AppendFileType PropertyApplies To: Workbook object

AutoFileOptions PropertyReturns or sets if the application should use automatic file options. Remarks: If set to WnlYes, the application will scan the first few rows of a data file to try and determine if headers exist and the delimiter. This only applies to ASCII data files.Example: object.AutoFileOptions = WnlYesSee Also: Headers Property, Delimiter PropertyApplies To: Workbook object

CaptionPrefix PropertyRead-only property that returns the caption prefix of an object. Remarks: The caption prefix precedes the object type in the object windows caption.Example: sPrefix = object.CaptionPrefixApplies To: Workbook object, Chart object, TextEditor object

CellFormula PropertyReturns or sets the cell formula of the active cell. Example: object.CellFormula = "A1+1"See Also: CellFormulaRC PropertyApplies To: Workbook object

CellFormulaRC PropertyReturns or sets the cell formula for a specific cell.

Parameter Type (Default) DescriptionlRow Long The cell row.


786

G

Remarks: When setting the formula, it is not necessary to preceed the formula with the equals sign.Example: sFormula = object.CellFormulaRC(10,5)See Also: CellFormula PropertyApplies To: Workbook object

CellValue PropertyReturns or sets the cell value of the active cell. Example: object.CellValue = "Missing"See Also: CellValueRC PropertyApplies To: Workbook object

CellValueRC PropertyReturns or sets the cell value for a specific cell.

Example: dValue = object.CellValueRC(10,5)See Also: CellValue PropertyApplies To: Workbook object

Changed PropertyReturns or sets the changed status of the object. Remarks: When the value is True, a file save warning will be shown when the object is closed.Example: object.Changed = FalseApplies To: Workbook object, Chart object, TextEditor object

Clip PropertyReturns or sets data in the workbook based on the current selection. Remarks: The string used by the clip property should be tab delimited for columns and carriage return delimited for rows.Example: sText = object.ClipSee Also: Selection PropertyApplies To: Workbook object

lCol Long The cell column.

Parameter Type (Default) DescriptionlRow Long The cell row.lCol Long The cell column.

Parameter Type (Default) Description


787

G

ColName PropertyReturns or sets a colum name.

Example: object.ColName = "Subject"See Also: ColUnit PropertyApplies To: Workbook object

ColUnit PropertyReturns or sets the units for the column.

Example: sUnits = object.ColUnit(5)See Also: ColName PropertyApplies To: Workbook object

ConsecutiveDelimiters PropertyReturns or sets if the application should skip consecutive delimiters on files. Remarks: If set to WnlYes, the application will ignore consecutive delimiters when reading files. This is helpful when reading files delimited by a variable amount of spaces. This only applies to ASCII data files.Example: object.ConsecutiveDelimiters = WnlNoSee Also: AutoFileOptions Property, Headers Property, Delimiter PropertyApplies To: Workbook object

ConvertUnits MethodConverts the units for a specified column.

Remarks: The ConvertUnits operation changes the values in the data column as a result of the conversion. If there are no units in the column specified then the column is assigned the new units with no conversion.

Parameter Type (Default) DescriptionlCol Long The column index.

Parameter Type (Default) DescriptioniIndex Integer The column index.

Parameter Type (Default) DescriptionlCol Long The column to convert units. sNewUnits String The units to convert to. dMoleWt Double (DMISS-

ING)(Optional) The molecular weight of a compound (weight per mole specified in grams). It therefore is the conversion factor needed to convert between grams and moles.


788

G

Example: object.ConvertUnits(3, "hr")See Also: ColUnit PropertyApplies To: Workbook object

Delimiter PropertyReturns or sets the file delimiter. Remarks: This option only applies to ASCII data files.Example: object.Delimiter = ","See Also: AutoFileOptions Property, Headers Property, ConsecutiveDelimiters Prop-ertyApplies To: Workbook object

EditCopy MethodCopies the current selection and places it on the Windows Clipboard. Example: object.EditCopySee Also: EditCut Method, EditPaste Method, EditPasteValues Method, EditDelete MethodApplies To: Workbook object

EditCut MethodCuts the current selection and places it on the Windows Clipboard. Example: object.EditCutSee Also: EditCopy Method, EditPaste Method, EditPasteValues Method, EditDelete MethodApplies To: Workbook object

EditDelete MethodDeletes the current selection.

Example: object.EditDeleteSee Also: EditCut Method, EditCopy Method, EditPaste Method, EditPasteValues MethodApplies To: Workbook object

EditPaste MethodPastes the contents of the clipboard to the current location.

Parameter Type (Default) DescriptionnShift F1ShiftTypeConstants (Optional)


789

G

Example: object.EditPasteSee Also: EditCut Method, EditCopy Method, EditPasteValues Method, EditDelete MethodApplies To: Workbook object

EditPasteValues MethodPastes the contents of the clipboard to the current location. Remarks: If the data in the clipboard represents formulas, then the resulting value is placed in the workbook, not the formula.Example: object.EditPasteValuesSee Also: EditCut Method, EditCopy Method, EditPaste Method, EditDelete MethodApplies To: Workbook object

ExcludeSel MethodExcludes the current selection. Remarks: Excluding cells in the workbook will prevent the data from being used in any analysis.Example: object.ExcludeSelSee Also: IncludeSel MethodApplies To: Workbook object

Filename PropertyReturns or sets the file name of the object. Example: object.Filename = "c:\data\myfile.pwo"See Also: FileType Property, AutoFileOptions Property, Headers Property, Delimiter Property, ConsecutiveDelimiters PropertyApplies To: Workbook object, Chart object, TextEditor object

FileType PropertyReturns and set the file type. Example: object.FileType = FileFWBookSee Also: Filename Property, AutoFileOptions Property, Headers Property, Delimiter Property, ConsecutiveDelimiters PropertyApplies To: Workbook object, Chart object, TextEditor object

FormCaption PropertyRead-only property that returns the caption of the objects window.


790

G

Example: sCaption = object.FormCaptionApplies To: Workbook object, Workbook Object, TextEditor object

GetActiveCell MethodMethod returns the active row and column of the workbook.

Remarks: This method is not compatible with VBScript. Use the ActiveRow and ActiveCol properties instead.Example: object.GetActiveCell lRow, lColSee Also: SetActiveCell Method, ActiveRow Property, ActiveCol PropertyApplies To: Workbook object

GetColNum MethodThis method returns the column number for a specified column.

Applies To: Workbook object

GetLastRowCol MethodThis method returns the last row and last column of the workbook containing data.

Remarks: This method is not compatible with VBScript. Use the LastRow and Last-Col properties instead.Example: object.GetLastRowCol(lRows, lCols)See Also: LastRow Property, LastCol PropertyApplies To: Workbook object

Headers PropertyReturns or sets if the application should look for headers on the data file. Remarks: If set to WnlYes, the first row of the file will be used as headers in the workbook. This only applies to ASCII data files.

Parameter Type (Default) DescriptionlRow Long (Optional) Variable to return the active row.lCol Long (Optional) Variable to return the active column.

Parameter Type (Default) DescriptionsCol String (Optional)

Parameter Type (Default) DescriptionlLastRow Long (Optional) This parameter is set to the last row of the

workbook.lLastCol Long (Optional) This parameter is set to the last column of

the workbook.


791

G

Example: object.Headers = WnlYesSee Also: AutoFileOptions Property, Delimiter Property, ConsecutiveDelimiters PropertyApplies To: Workbook object

ID PropertyRead-only property that returns the ID of the object. Remarks: The ID property is only valid during a WinNonlin session. It is not persis-tent.Example: sID = object.IDSee Also: UUID PropertyApplies To: Workbook object, Chart Object, TextEditor object

IncludeSel MethodInclude the current selection. Remarks: If any cells in the current selection are excluded, calling this method will include them.Example: object.IncludeSelSee Also: ExcludeSel MethodApplies To: Workbook object

InsertCol MethodThis function inserts a column in the workbook.

Returns: Returns true if successful, false otherwise.Remarks: The column is inserted at the current row position in the workbook.Example: bRet = Object.InsertCol("NewCol")See Also: RemoveCol Function, InsertRow FunctionApplies To: Workbook object

InsertRow MethodThis function inserts a row in the workbook.

Returns: Returns true if successful, false otherwise.Remarks: The rows are inserted at the current position in the workbook.

Parameter Type (Default) DescriptionsColName String (Optional) The name of the new column.

Parameter Type (Default) DescriptionlRowsToAdd Long (1) (Optional) The number of rows to insert in the workbook


792

G

Example: bRet = object.InsertRow(5)See Also: RemoveRow Function, InsertCol FunctionApplies To: Workbook object

IsExcluded PropertyRead-only property that determines if the active cell is excluded. Returns: True if active cell is excluded, false otherwise.Example: bIsExcluded = object.IsExcludedSee Also: IsExcludedRC PropertyApplies To: Workbook object

IsExcludedRC PropertyRead-only property that determines if the specified cell is excluded.

Returns: True is the cell is excluded, false otherwise.Example: bIsExcluded = object.IsExcluded(5, 10)See Also: IsExcluded PropertyApplies To: Workbook object

IsMissingVal PropertyRead-only property that determines if the active cell is missing. Returns: True if the active cell is missing, false otherwise.Example: bIsMissing = object.IsMissingValSee Also: IsMissingValRC PropertyApplies To: Workbook object

IsMissingValRC PropertyRead-only property that determines if the specified cell is missing.

Returns: True if the active cell is missing, false otherwise.Example: bIsMissing = object.IsMissingValRC(5, 5)See Also: IsMissingVal Property

Parameter Type (Default) DescriptionlRow Long (Optional) The row to check for exclusion.lCol Long (Optional) The column to check for exclusion.

Parameter Type (Default) DescriptionlRow Long (Optional) The row to check for missing.lCol Long (Optional) the column to check for missing.


793

G


LastCol PropertyRead-only property returns the last column of the workbook containing data. Example: lLastCol = object.LastColSee Also: GetLastRowCol Method, LastRow PropertyApplies To: Workbook object

LastRow PropertyRead-only property returns the last row of the workbook containing data. Example: lLastRow = object.LastRowSee Also: GetLastRowCol Method, LastRow PropertyApplies To: Workbook object

LastRowForCol MethodThis method returns the last row for a specified column that contains data.

Returns: Returns the last row for a specified column that contains data.Example: lLastRow = object.LastRowForCol(2)See Also: LastRow PropertyApplies To: Workbook object

Missing PropertyReturns or sets the missing value for the workbook. Remarks: Missing values will appears in the workbook with gray backgrounds.Example: object.Missing = "Miss"Applies To: Workbook object

Name PropertyReturns or sets the name of the object. Remarks: This value is used in various modules of the application where filename may not be sufficient.Example: object.Name = "MyData"Applies To: Workbook object, Chart object, TextEditor object

Parameter Type (Default) DescriptionlCol Long (Optional) The column to return the last row for.


794

G

numSheets PropertyRead-only property returns the number of sheets in the workbook. Example: lNumSheets = object.NumSheetsSee Also: ActiveSheet Property, SheetName PropertyApplies To: Workbook object

NumSortKeys PropertyReturns or sets the number of sort keys for the active sheet. Remarks: The number of sort keys must be between 0 and 256.Example: object.NumSortKeys = 2 : object.SortKey(1) = 1 : object.SortKey(2) = 2

See Also: NumSortKeysEx Property, SortKey Property, SortKeyEx PropertyApplies To: Workbook object

NumSortKeysEx PropertyReturns or sets the number of sort keys for a specific sheet.

Remarks: The number of sort keys must be between 0 and 256.Example: object.NumSortKeysEx(1) = 2 : object.SortKeyEx(1, 1) = 1 : object.SortKeyEx(1, 2) = 2

See Also: NumSortKeys Property, SortKeyEx Property, SortKey PropertyApplies To: Workbook object

PrintAll MethodPrints the entire workbook. Remarks: This method prints all the sheets in the workbook, not just the active sheet.Example: object.PrintAllSee Also: PrintOut MethodApplies To: Workbook object

PrintOut MethodPrints the active worksheet. Example: object.PrintOutSee Also: PrintAll MethodApplies To: Workbook object, Chart Object, TextEditor Object

Parameter Type (Default) DescriptionlSheet Long (Optional) The sheet to set the number of sort keys.


795

G

ReadOnly PropertyReturns or sets the read-only status the object. Example: object.ReadOnly = TrueApplies To: Workbook object, Chart object, TextEditor object

ResetExclusions MethodThis method resets the exclusions set in the active worksheet. Remarks: After calling this method all data will be included in analysis. This does not affect missing data.Example: object.ResetExclusionsSee Also: IncludeSel Method, ExcludeSel Method, SearchInclude Method, SearchEx-clude MethodApplies To: Workbook object

Save MethodSaves the object to file. Example: object.SaveApplies To: Workbook object, Chart object, TextEditor object

Search MethodThe Search method searches the worksheet for a specified value based on the current search settings. Returns: Returns 1 if value is found, 0 otherwise.Remarks: If the search value is found, the active cell is changed to the cell where the value was found.Example: nRet = object.Search()See Also: SearchReplaceAll Method, SearchExclude Method, SearchInclude Method, SearchArea Property, SearchCaseSensitive Property, SearchCompare Property, SearchReplaceValue Property, SearchRowMode Property, SearchTolerance Property, SearchValue PropertyApplies To: Workbook object

SearchArea PropertyReturns or sets the area to search. Remarks: When SearchArea is SearchAreaCol, the active column is used. When SearchArea is SearchAreaSel, the active selection is used.Example: object.SearchArea = SearchAreaAll


796

G

See Also: Search Method, SearchReplaceAll Method, SearchExclude Method, SearchInclude Method, SearchCaseSensitive Property, SearchCompare Property, SearchReplaceValue Property, SearchRowMode Property, SearchTolerance Property, SearchValue PropertyApplies To: Workbook object

SearchCaseSensitive PropertyReturns or sets if searched are case sensitive. Remarks: If true then searches are case sensitive, otherwise searches are not case sen-sitive.Example: object.SearchCaseSensitive = TrueSee Also: Search Method, SearchReplaceAll Method, SearchExclude Method, SearchInclude Method, SearchArea Property, SearchCompare Property, SearchRe-placeValue Property, SearchRowMode Property, SearchTolerance Property, Search-Value PropertyApplies To: Workbook object

SearchCompare PropertyReturns or sets the search comparison. Remarks: This only applies to searches where the SearchValue is numeric.Example: object.SearchCompare = SearchCompareEQSee Also: Search Method, SearchReplaceAll Method, SearchExclude Method, SearchInclude Method, SearchArea Property, SearchCaseSensitive Property, SearchReplaceValue Property, SearchRowMode Property, SearchTolerance Property, SearchValue PropertyApplies To: Workbook object

SearchExclude MethodThe SearchExclude method searches the worksheet for a specified value and excludes it based on the current search settings. Returns: Returns the number of values excluded.Remarks: When used with row mode (SearchRowMode = True), each row where the search value is found will be excluded.Example: lExcluded = object.SearchExclude()See Also: Search Method, SearchNext Method, SearchReplaceAll Method, SearchIn-clude Method, SearchArea Property, SearchCaseSensitive Property, SearchCompare Property, SearchReplaceValue Property, SearchRowMode Property, SearchTolerance Property, SearchValue PropertyApplies To: Workbook object


797

G

SearchInclude MethodThe SearchInclude method searches the worksheet for a specified value and includes it based on the current search settings. Returns: Returns the number of values included.Remarks: When used with row mode (SearchRowMode = True), each row where the search value is found will be included.Example: lIncluded = object.SearchInclude()See Also: Search Method, SearchNext Method, SearchReplaceAll Method, SearchEx-clude Method, SearchArea Property, SearchCaseSensitive Property, SearchCompare Property, SearchReplaceValue Property, SearchRowMode Property, SearchTolerance Property, SearchValue PropertyApplies To: Workbook object

SearchReplaceAll MethodThe SearchReplaceAll method searches the worksheet for a specified value and replaces it with another value based on the current search settings. Returns: Returns the number of values replaced.Remarks: When used with row mode (SearchRowMode = True), each row where the search value is found will be removed. In this case the SearchReplaceValue is ignored.Example: lReplacements = object.SearchReplaceAll()See Also: Search Method, SearchNext Method, SearchExclude Method, SearchIn-clude Method, SearchArea Property, SearchCaseSensitive Property, SearchCompare Property, SearchReplaceValue Property, SearchRowMode Property, SearchTolerance Property, SearchValue PropertyApplies To: Workbook object

SearchReplaceValue PropertyReturns or sets the replace value. Example: object.SearchReplaceValue = "Capsule"See Also: Search Method, SearchReplaceAll Method, SearchExclude Method, SearchInclude Method, SearchArea Property, SearchCaseSensitive Property, Search-Compare Property, SearchRowMode Property, SearchTolerance Property, Search-Value PropertyApplies To: Workbook object

SearchRowMode PropertyReturns or sets the if the search operates on the row where the search value is found.


798

G

Remarks: This option only applies to SearchReplaceAll, SearchInclude and SearchExclude operations. When SearchReplaceAll is used with row mode, each row where the search value is found will be removed. When SearchInclude or SearchEx-clude is used with row mode, each row where the search value is found will be included or excluded.Example: object.SearchRowMode = TrueSee Also: Search Method, SearchReplaceAll Method, SearchExclude Method, SearchInclude Method, SearchArea Property, SearchCaseSensitive Property, Search-Compare Property, SearchReplaceValue Property, SearchTolerance Property, Search-Value PropertyApplies To: Workbook object

SearchTolerance PropertyReturns or sets the tolerance value for the search. Remarks: This only applies to searches where the SearchValue is numeric. Set SearchTolerance to 0 to turn of searches with tolerance.Example: object.SearchTolerance = 1.5See Also: Search Method, SearchReplaceAll Method, SearchExclude Method, SearchInclude Method, SearchArea Property, SearchCaseSensitive Property, Search-Compare Property, SearchReplaceValue Property, SearchRowMode Property, Search-Value PropertyApplies To: Workbook object

SearchValue PropertyReturns or sets the value to search for. Example: object.SearchValue = "Tablet"See Also: Search Method, SearchReplaceAll Method, SearchExclude Method, SearchInclude Method, SearchArea Property, SearchCaseSensitive Property, Search-Compare Property, SearchReplaceValue Property, SearchRowMode Property, Search-Tolerance PropertyApplies To: Workbook object

Selection PropertyReturns or sets the selection. Remarks: The selection is set based on a reference. Default column names (A-IV) are used for the column reference.Example: object.Selection = "A1:B5" Selects column 1 to column 2 and row 1 to row 5

See Also: SelStartRow Property, SelStartCol Property, SelEndRow Property, SelEnd-Col Property


799

G


SelEndCol PropertyReturns or sets the end column of a selection. Example: object.SelEndCol = 5See Also: Selection Property, SelStartRow Property, SelStartCol Property, SelEnd-Row PropertyApplies To: Workbook object

SelEndRow PropertyReturns or sets the end row of a selection. Example: object.SelEndRow = 5See Also: Selection Property, SelStartRow Property, SelStartCol Property, SelEndCol PropertyApplies To: Workbook object

SelStartCol PropertyReturns or sets the start column of a selection. Example: object.SelStartCol = 1See Also: Selection Property, SelStartRow Property, SelEndRow Property, SelEndCol PropertyApplies To: Workbook object

SelStartRow PropertyReturns or sets the start row of a selection. Example: object.SelStartRow = 1See Also: Selection Property, SelStartCol Property, SelEndRow Property, SelEndCol PropertyApplies To: Workbook object

SetActiveCell MethodMethod sets the active row and column of the workbook.

Example: object.SetActiveCell 10, 1See Also: GetActiveCell Method, ActiveRow Property, ActiveCol Property

Parameter Type (Default) DescriptionlRow Long (Optional) The row to set.lCol Long (Optional) the column to set.


800

G


SheetName PropertyReturns or sets the sheet name of the specified sheet.

Example: object.SheetName(1) = "Input"See Also: Sheet MethodApplies To: Workbook object

ShowUnits PropertyReturns or sets is units are displayed in the column headers. Remarks: If set to WnlYes, then units will appear in the second line of the column header, otherwise the column header will be one line and not show units.Example: object.ShowUnits = WnlNoApplies To: Workbook object

Sort MethodThis function sorts the workbook.

Returns: True if successful, false otherwise.Remarks: If the function parameters are ommitted, the entire working is sorted.Example: object.SortSee Also: Sorted Property, NumKeys Property, SortKey Property, NumKeysEx Prop-erty, SortKeyEx PropertyApplies To: Workbook object

Parameter Type (Default) DescriptionnSheet Integer (Optional) The index of the sheet to change.


Description

lR1 Long (1) (Optional) Starting row of the range to be sorted.lC1 Long (1) (Optional) Starting column of the range to be sorted.lR2 Long (0) (Optional) Ending row of the range to be sorted.lC2 Long (0) (Optional) Ending column of the range to be sorted. bSortBy-Row

Boolean (True)

(Optional) Specifies how data is sorted. If True, data is sorted by rows; if False, data is sorted by columns.

vKeys Variant (Optional) Identifies the key or keys to use to sort the data. This argument can be a single integer or an array of integers.


801

G

Sorted PropertyRead-only property returns if the sheet is sorted. Example: bSorted = object.SortedSee Also: Sort MethodApplies To: Workbook object

SortKey PropertyReturns or sets a specific sort key for the active sheet.

Example: object.NumSortKeys = 2 : object.SortKey(1) = 1 : object.SortKey(2) = 2

See Also: NumSortKeys Property, NumSortKeysEx Property, SortKeyEx PropertyApplies To: Workbook object

SortKeyEx PropertyReturns or sets a specific sort key for a specific sheet.

Example: object.NumSortKeysEx(1) = 2 : object.SortKeyEx(1, 1) = 1 : object.SortKeyEx(1, 2) = 2

See Also: NumSortKeysEx Property, NumSortKeys Property, SortKey PropertyApplies To: Workbook object

Source PropertyRead-only property that returns the source object. Applies To: Workbook object

Tag PropertyReturns or sets a tag value for an object. Remarks: This property can be used to give an object a unique identifying value.Example: object.Tag = "Input workbook"Applies To: Workbook object, Chart object, TextEditor object

Parameter Type (Default) DescriptionnIndex Integer (Optional) The sort key to set. The value must be

between 1 and NumSortKeys.

Parameter Type (Default) DescriptionlSheet Long (Optional) The sheet to set the number of sort keys.nIndex Integer (Optional) The sort key to set. The value must be

between 1 and NumSortKeys.


802

G

Transform MethodPerforms a transformation on a column in a workbook.

Example: object.Transform TransformAdd, 5, "Time", "TimePlus5"

See Also: CellFormula Property, CellFormulaRC PropertyApplies To: Workbook object

UseFormats PropertyReturns or sets if formats should be used when saving files. Example: object.UseFormats = WnlNoApplies To: Workbook object

UUID PropertyRead-only property to get the UUID for the object. Remarks: This property is persistent when the object is saved in the proprietary for-mat.Example: sUUID = object.UUIDSee Also: ID PropertyApplies To: Workbook object, Chart object, TextEditor object

WindowState PropertyReturns or sets the window state of the object. Example: object.WindowState = WindowStateConstantsMinimizedApplies To: Workbook object, Chart object, TextEditor object

Workbooks moduleInstancing: PublicNotCreatable

Parameter Type (Default) DescriptionnFunction WnlTransformConstants (Optional)vExtra Variant (Optional)sSourceCol String (Optional)sDestCol String (Optional)nDestArea WnlTransformDestConstants (TransformDestAppend) (Optional)bUseFormula Boolean (False) (Optional)

Visual Basic Automation ReferenceWorkspace module

803

G

Count PropertyReturns a count of items in the collection. Returns: Returns the number of items in the colelction.Applies To: Workbooks object, Charts object, TextEditors object, Variables object


Returns: Returns a Workbook object.Applies To: Workbooks object, Charts object, TextEditors object, Variables object

Workspace moduleInstancing: PublicNotCreatable

ActiveChart PropertyRead-only property that returns a reference to the active chart object. Example: object.ActiveChart.Filename = "mychart.pco"See Also: ActiveWorkbook Property, ActiveTextEditor Property, ActiveModel Prop-ertyApplies To: Workspace object

ActiveFormType PropertyRead-only property that returns the type of the active object. Example: nType = object.ActiveFormTypeApplies To: Workspace object

ActiveModel PropertyRead-only property that returns a reference to the active model object. Example: object.ActiveModel.Filename = "mymodel.pmo"See Also: ActiveWorkbook, ActiveChart, ActiveTextEditorApplies To: Workspace object

Parameter Type DescriptionIndex Variant An expression that specifies the position of a member of the col-

lection. If a numeric expression, index must be a number from 1 to the value of the collections Count property. If a string expres-sion, index must correspond to the key argument specified when the member referred to was added to the collection.


804

G

ActiveTextEditor PropertyRead-only property that returns a reference to the active text editor object. Example: object.ActiveTextEditor.Filename = "mytext.pto"See Also: ActiveWorkbook Property, ActiveChart Property, ActiveModel PropertyApplies To: Workspace object

ActiveWorkbook PropertyRead-only property that returns a reference to the active workbook object. Example: object.ActiveWorkbook.Filename = "mydata.pwo"See Also: ActiveChart Property, ActiveTextEditor Property, ActiveModel PropertyApplies To: Workspace object

Arrange MethodThis method arranges the objects in the MDI parent.

Example: object.Arrange ArrangeTileHorizontalApplies To: Workspace object

Changed PropertyReturns or sets the changed status of the object. Example: object.Changed = FalseApplies To: Workspace object

Chart PropertyRead-only property that returns a reference to a chart object.

Remarks: The index can be an integer or string value. Valid integer values are 1 to the ChartCount. Valid strings are the ID values of the charts.Example: Set MyChart = object.Chart(1)See Also: Workbook Property, TextEditor Property, Model PropertyApplies To: Workspace object

ChartCount PropertyRead-only property that returns the number of charts in the workspace.

Parameter Type (Default) DescriptionnValue WnlArrangeConstants The type of arrange to perform.

Parameter Type (Default) DescriptionIndex Variant Index to the chart collection.


805

G

Example: nCharts = object.ChartCountSee Also: WorkbookCout Property, TextEditorCount Property, ModelCount PropertyApplies To: Workspace object

Charts PropertyRead-only property that returns a reference to the Chart collection. Example: Set ChartsCollection = object.ChartsSee Also: Workbooks Property, TextEditors PropertyApplies To: Workspace object

CloseAll MethodThis methods closes all the objects in the workspace. Example: object.CloseAllApplies To: Workspace object

CloseChart MethodThis method closes a chart.

Example: object.CloseChart(clsMyChart)See Also: CloseWorkbook Method, CloseTextEditor Method, CloseModel MethodApplies To: Workspace object

CloseModel MethodThis method closes a model.

Example: object.CloseModel(clsMyModel)See Also: CloseWorkbook Method, CloseChart Method, CloseTextEditor MethodApplies To: Workspace object

CloseTextEditor MethodThis method closes a text editor.

Example: object.CloseTextEditor(clsMyTextEditor)

Parameter Type (Default) DescriptionclsChart Chart The book to close.

Parameter Type (Default) DescriptionclsModel Model The book to close.

Parameter Type (Default) DescriptionclsText TextEditor Item to close.


806

G

See Also: CloseWorkbook Method, CloseChart Method, CloseModel MethodApplies To: Workspace object

CloseWorkbook MethodThis method closes a workbook.

Example: object.CloseWorkbook(clsMyBook)See Also: CloseChart Method, CloseTextEditor Method, CloseModel MethodApplies To: Workspace object

Filename PropertyReturns or sets the name of the workspace. Example: object.Filename = "project.wsp"See Also: Load Method, Save MethodApplies To: Workspace object

Load MethodLoads a workspace.

Remarks: If sNewFile is ommitted, then the Filename property is used.Example: object.LoadSee Also: NewWorkspace Method, Save Method, CloseWorkspace MethodApplies To: Workspace object

Model PropertyRead-only property that returns a reference to a model object. Example: Set MyModel = object.ModelSee Also: Workbook Property, Chart Property, TextEditor PropertyApplies To: Workspace object

ModelCount PropertyRead-only property that returns the number of models in the workspace. Example: nModels = object.ModelCount

Parameter Type (Default) DescriptionclsBook Workbook The book to close.

Parameter Type DescriptionsNewFile String ("") (Optional) If set, the Filename property will be changed and

this will be the new file name for the workspace.


807

G

See Also: WorkbookCout Property, ChartCount Property, TextEditorCount PropertyApplies To: Workspace object

NewChart MethodThis method creates a new chart object. Returns: Returns a reference to the new chart. The return value will be Nothing if the method fails.Example: Set MyChart = object.NewChart()See Also: NewWorkbook Method, NewTextEditor Method, NewModel MethodApplies To: Workspace object

NewModel MethodThis method closes the current model. Returns: Returns a reference to the new model. The return value will be Nothing if the method fails.Remarks: In this version of WinNonlin, NewModel functions the same as Close-Model. The return value will always be Nothing.Example: Set MyModel = object.NewModel()See Also: NewWorkbook Method, NewChart Method, NewTextEditor MethodApplies To: Workspace object

NewTextEditor MethodThis method creates a new text editor object. Returns: Returns a reference to the new text window. The return value will be Noth-ing if the method fails.Example: Set MyTextEditor = object.NewTextEditor()See Also: NewWorkbook Method, NewChart Method, NewModel MethodApplies To: Workspace object

NewWorkbook MethodThis method creates a new workbook object.

Returns: Returns a reference to the new workbook. The return value will be Nothing if the method fails.Remarks: The new workbook will have a history worksheet in addition to the number of sheets specified.

Parameter Type (Default) DescriptionnNumSheets Integer (1) (Optional) number of worksheets in the new workbook.


808

G

Example: Set MyBook = object.NewWorkbook(2)See Also: NewChart Method, NewTextEditor Method, NewModel MethodApplies To: Workspace object

NewWorkspace MethodCreates a new workspace. Remarks: The functionality of new workspace is the same as CloseWorkspace.Example: object.NewWorkspaceSee Also: Save Method, Load Method, CloseWorkspace MethodApplies To: Workspace object

OpenChart MethodThis method creates a new chart and opens a file.

Returns: Returns a reference to the new chart. The return value will be Nothing if the method fails.Example: Set MyChart = object.Open-Chart("c:\data\mydata.pco", FileFWChart)

See Also: OpenWorkbook Method, OpenTextEditor Method, OpenModel MethodApplies To: Workspace object

OpenModel MethodThis method creates a new model and opens a file.

Returns: Returns a reference to the new model. The return value will be Nothing if the method fails.Example: Set MyModel = object.Open-Model("c:\data\mymodel.pmo", FileFWModel)

See Also: OpenWorkbook Method, OpenChart Method, OpenTextEditor Method

Parameter Type (Default) DescriptionsFile String (Optional) The name of the file to open.nFileType WnlFileTypeConstants (Optional) The file type.

Parameter Type (Default) DescriptionsFile String (Optional) The name of the file to open. nFileType WnlFileTypeConstants (Optional) The file type. sNewBookID Variant (Optional) The ID of the new workbook if data

is associated with the model. sNewTextID Variant (Optional) The ID of the new text editor that

contains the representation of the model.


809

G

Applies To: Workspace object

OpenTextEditor MethodThis method creates a new text editor and opens a file.

Returns: Returns a reference to the new text window. The return value will be Noth-ing if the method fails.Example: Set MyTextEditor = object.OpenTextEdi-tor("c:\data\mydata.pto", FileFWText)

See Also: OpenWorkbook Method, OpenChart Method, OpenModel MethodApplies To: Workspace object

OpenWorkbook MethodThis method creates a new workbook and opens a file.

Returns: Returns a reference to the new workbook. The return value will be Nothing if the method fails.Example: Set MyBook = object.OpenWork-book("c:\data\mydata.pwo", FileFWBook)

See Also: OpenChart Method, OpenTextEditor Method, OpenModel MethodApplies To: Workspace object

Parameter Type (Default) DescriptionsFile String (Optional) The name of the file to open.nFileType WnlFileTypeConstants (Optional) The file type.

Parameter Type (Default) DescriptionsFile String (Optional) The name of the file to open. nFileType WnlFileType-

Constants(Optional) The file type.

nHeaders WnlYesNoCon-stants (WnlNo)

(Optional) If set to WnlYes, the first row of data will be placed in the column headers.

nConsecDelim WnlYesNoCon-stants (WnlNo)

(Optional) If set to WnlYes, then consecutive delimit-ers will be treated as a single delimiter. This parame-ter only applies to ASCII data files.

sDelim String ("") (Optional) A single character representing the delim-iter. This parameter only applies to ASCII data files.

sMissing String ("") (Optional) Missing value. Any values matching this value will have a gray background in the workbook.

nAutoOptions WnlYesNoCon-stants (WnlYes)

(Optional) This parameter only applies to ASCII data files.


810

G

RunScript MethodThis method runs a legacy script file.

Remarks: used to run script files from WinNonlin 3 and earlier.Applies To: Workspace object

Save MethodSaves the workspace to file.

Remarks: If sNewFile is ommitted, then the Filename property is used.Example: object.SaveSee Also: NewWorkspace Method, Load Method, CloseWorkspace MethodApplies To: Workspace object

ShowMsg MethodDisplays a message box.

Remarks: This can be useful to pause the processing of a script or show status.Example: object.ShowMsg("Click OK to continue...")Applies To: Workspace object

SilentMode PropertySets or returns whether the application is running in verbose mode. Remarks: If set to True then all messages will be surpressed. This is helpful when automating the application so processing does not stop.Example: object.SilentMode = TrueApplies To: Workspace object

TextEditor PropertyRead-only property that returns a reference to a text editor object.

Parameter Type (Default) DescriptionsFile String (Optional) The name of the script to run.


Description

sNewFile String ("") (Optional) If set, the Filename property will be changed and this will be the new file name for the workspace.

Parameter Type (Default) DescriptionsMsg String (Optional) The message to display.

Parameter Type (Default) DescriptionIndex Variant (Optional) Index to the text editor collection.


811

G

Remarks: The index can be an integer or string value. Valid integer values are 1 to the TextEditorCount. Valid strings are the ID values of the text editors.Example: Set MyText = object.TextEditor(1)See Also: Workbook Property, Chart Property, Model PropertyApplies To: Workspace object

TextEditorCount PropertyRead-only property that returns the number of text editors in the workspace. Example: nTextEditors = object.TextEditorCountSee Also: WorkbookCout Property, ChartCount Property, ModelCount PropertyApplies To: Workspace object

TextEditors PropertyRead-only property that returns a reference to the TextEditor collection. Example: Set TextEditorsCollection = object.TextEditorsSee Also: Workbooks Property, Charts PropertyApplies To: Workspace object

UnloadApp MethodUnloads the application. Remarks: The application will not completely unload until all references to applica-tion objects have been set to Nothing.Example: object.UnloadAppApplies To: Workspace object

WindowState PropertyReturns or sets the window state of the main window. Example: object.WindowState = WindowStateConstantsMinimizedApplies To: Workspace object

Workbook PropertyRead-only property that returns a reference to a workbook object.

Remarks: The index can be an integer or string value. Valid integer values are 1 to the WorkbookCount. Valid strings are the ID values of the workbooks.Example: Set MyBook = object.Workbook(1)

Parameter Type (Default) DescriptionIndex Variant (Optional) Index to the workbook collection.


812

G

See Also: Chart Property, TextEditor Property, Model PropertyApplies To: Workspace object

WorkbookCount PropertyRead-only property that returns the number of workbooks in the workspace. Example: nBooks = object.WorkbookCountSee Also: ChartCout Property, TextEditorCount Property, ModelCount PropertyApplies To: Workspace object

Workbooks PropertyRead-only property that returns a reference to the workbook collection. Example: Set BooksCollection = object.WorkbooksSee Also: Charts Property, TextEditors PropertyApplies To: Workspace object

WorkingDir PropertyReturns or sets the current working directory.Example: object.WorkingDir = "c:\examples"Applies To: Workspace object

813

Appendix H

References

This bibliography of modeling and related references is organized under of the following headings.

• “Deconvolution” on page 813

• “Pharmacokinetics” on page 814

• “Regression and modeling” on page 815

• “Statistics” on page 817

• “Bioequivalence” on page 818

DeconvolutionCharter, M.K., Gull, S.F. J Pharmacokinet Biopharm 15, 645-655 (1987).

Cutler, D. J. (1978). Numerical deconvolution by least squares: use of prescribed input func-tions. J Pharmacokinet Biopharm 6(3): 227-41.

Cutler, D. J. (1978). Numerical deconvolution by least squares: use of polynomials to repre-sent the input function. J Pharmacokinet Biopharm 6(3): 243-63.

Daubechies, I. (1988). Orthonormal bases of compactly supported wavelets. Communications on Pure and Applied Mathematics 41(XLI): 909-996.

Gabrielsson, Johan and Daniel Weiner. Pharmacokinetic and Pharmacodynamic Data Analy-sis: Concepts and Applications, 3rd edition. Stockholm: Swedish Pharmaceutical Press, 2001.

Haskel, K.H., Hanson, R.J. Math. Programs 21, 98-118 (1981).

Iman, R.L., and Conover, W.J. Technometrics, 21,499-509,(1979).


814

H

Madden, F. N., Godfrey, K. R., Chappell, M. J., Hovroka, R., and Bates, R. A Comparison of six deconvolution techniques. J Pharmacokinet Biopharm 24: pp. 282 (1996).

Treitel, S. and L. R. Lines (1982). Linear inverse--theory and deconvolution. Geophysics 47(8): 1153-1159.

Verotta, D. (1990). Comments on two recent deconvolution methods. J Pharmacokinet Biop-harm 18(5): 483-499.

PharmacokineticsBrown RD and Manno JE. ESTRIP, A BASIC computer program for obtaining initial polyex-ponential parameter estimates. J. Pharm. Sci. 67:1687-1691 (1978).

Chan KK and Gilbaldi M. Estimation of statistical moments and steady-state volume of distri-bution for a drug given by intravenous infusion. J. Pharm. Bioph. 10(5):551-558 (1982).

Cheng H and Jusko W. Noncompartmental determination of mean residence time and steady-state volume of distribution during multiple dosing, J. Pharm. Sci. 80: 202 (1991).

Dayneka NL, Garg V, and Jusko W. Comparison of four basic models of indirect pharmacody-namic responses. J. Pharmacokin. Biopharm. 21:457 (1993).

Endrenyi L (editor). Kinetic Data Analysis: Design and Analysis of Enzyme and Pharmacoki-netic Experiments. Plenum Press, New York (1981).

Gabrielsson J and Weiner D. Pharmacokinetic and Pharmacodynamic Data Analysis: Con-cepts and Applications, 2nd ed. Swedish Pharmaceutical Press, Stockholm (1997).

Gibaldi M and Perrier D. Pharmacokinetics, 2nd ed. Marcel Dekker, New York (1982).

Gouyette A. Pharmacokinetics: Statistical moment calculations. Arzneim.-Forsch/Drug Res. 33 (1):173-176 (1983).

Holford NHG and Sheiner L. Kinetics of pharmacological response. Pharmacol. Ther. 16:143 (1982).

Jusko WJ. Corticosteroid pharmacodynamics: models for a broad array of receptor-mediated pharmacologic effects. J. Clin. Pharmacol. 30:303 (1990).

Koup JR. Direct linear plotting method for estimation of pharmacokinetic parameters. J. Pharm. Sci. 70:1093-1094 (1981).

Kowalski, K., and Karim A. A semicompartmental modeling approach for pharmacodynamic data assessment. Journal of Pharmacokinetics and Biopharmaceutics 23(3):307-322 (1995).

ReferencesRegression and modeling

815

H

Metzler CM and Tong DDM. Computational problems of compartmental models with Michaelis-Menten-type elimination. Journal of Pharmaceutical Sciences 70:733-737 (1981).

Nagashima R, O’Reilly RA, and Levy G. Kinetics of pharmacologic effects in man: The anti-coagulant action of warfarin. Clin. Pharmacol. Ther. 10:22 (1969).

Wagner JG. Fundamentals of Clinical Pharmacokinetics. Drug Intelligence, Illinois (1975).

Regression and modelingAkaike A. Posterior probabilities for choosing a regression model. Annals of the Institute of Mathematical Statistics 30:A9-14 (1978).

Allen D and Cady F. Analyzing Experimental Data By Regression. Lifetime Learning Publica-tions, Belmont, CA (1982).

Bard Y. Nonlinear Parameter Estimation. Academic Press, New York (1974).

Bates DM and Watts DG. Nonlinear Regression Analyses and Its Applications. John Wiley & Sons, New York (1988).

Beck JV and Arnold KJ. Parameter Estimation in Engineering and Science. John Wiley & Sons, New York (1977).

Belsley DA, Kuh E and Welsch RE. Regression Diagnostics. John Wiley & Sons, New York (1980).

Corbeil, RR and Searle, SR. Restricted maximum likelihood (REML) estimation of variance components in the mixed models, Technometrics, 18:31-38 (1976).

Cornell RG. A method for eitting linear combinations of exponentials. Biometrics 18:104-113 (1962).

Davies M and Whitting IJ. A modified form of Levenberg's correction. Chapter 12 in Numeri-cal Methods for Non-linear Optimization. Academic Press, New York (1972).

DeLean A, Munson PJ, and Rodbard D. Simultaneous analysis of families of sigmoidal curves: Application to bioassay, radioligand assay, and physiological dose-response curves. Am. Journal Physiology 235(2): E97-E102 (1978).

Draper NR and Smith H. Applied Regression Analysis, 2nd ed. John Wiley & Sons, New York (1981).

Fai, Alex Hrong-Tai and Paul L. Cornelius. Approximate f-tests of multiple degree of freedom hypotheses in generalized least squares analysis of unbalanced split-plot experiments. J. Sta-tistical Computing and Simulation, 554: 363-378 (1996).


816

H

Fletcher, Roger. Practical methods of optimization, Vol. 1: Unconstrained Optimization. John Wiley & Sons. 1980.

Foss SD. A method of exponential curve fitting by numerical integration. Biometrics 26:815-821 (1970).

Giesbrecht, Francis G and JC Burns. Two-stage analysis based on a mixed model: Large sam-ple asymptotic theory and small-sample simulation results. Biometrics, 41:477-486 (1985).

Gill PE, Murray W and Wright MH. Practical Optimization. Academic Press (1981).

Gomeni R and Gomeni C. AUTOMOD: A Polyalgorithm for an integrated analysis of linear pharmacokinetic models. Comput. Biol. Med. 9:39-48 (1979).

Hartley HO. The modified Gauss-Newton method for the fitting of nonlinear regression func-tions by least squares. Technometrics 3: 269-280 (1961).

Jennrich RI and Moore RH. Maximum likelihood estimation by means of nonlinear least squares. Amer. Stat. Assoc. Proceedings Statistical Computing Section 57-65 (1975).

Kennedy WJ and Gentle JE. Statistical Computing. Marcel Dekker, New York (1980).

Koch, GG. The use of nonparametric methods in the statistical analysis of the two-period change-over design. Biometrics 577-583(1972).

Kowalski, Kenneth G and Karim, Ariz. A semicompartmental modeling approach for pharma-codynamic data assesment, Journal of Pharmacokinetics and Biopharmaceutics, 23:307-322(1995).

Leferink JG and Maes RAA. STRIPACT, An interactive curve fit programme for pharmacoki-netic analyses. Arzneim. Forsch. 29:1894-1898 (1978).

Longley. Journal of the American Statistical Association, 69:819-841(1967).

Nelder JA and Mead R. A simplex method for function minimization. Computing Journal 7: 308-313 (1965).

Parsons DH. Biological problems involving sums of exponential functions of time: A mathe-matical analysis that reduces experimental time. Math. Biosci. 2:123-128 (1968).

PCNonlin. Scientific Consulting Inc., North Carolina, U.S.A.

Peck CC and Barrett BB. Nonlinear least-squares regression programs for microcomputers. J. Pharmacokin. Biopharm. 7:537-541 (1979).

Ratkowsky DA. Nonlinear Regression Modeling. Marcel Dekker, New York (1983).

ReferencesStatistics

817

H

Satterthwaite, F. E. An approximate distribution of estimates of variance components. Biomet-rics Bulletin 2:110-114 (1946).

Schwarz G. Estimating the dimension of a model. Annals of Statistics 6: 461-464 (1978).

Sedman AJ and Wagner JG. CSTRIP, A FORTRAN IV Computer Program for Obtaining Polyexponential Parameter Estimates. J. Pharm. Sci. 65:1001-1010 (1976).

Shampine LR, Watts HA and Davenport SM. Solving nonstiff ordinary differential equations - the state of the art. SIAM Review 18: 376-411 (1976).

Sheiner,LB, Stanski, DR, Vozeh, S, Miller, RD, and Ham, J. Simultaneous modeling of phar-macokinetics and pharmacodynamics: application to d-tubocurarine. Clin. Pharmacol. Ther. 25: 358-371(1979).

Smith MR and Nichols ST. Improved resolution in the analysis of the multicomponent expo-nential signals. Nuclear Instrum. Meth. 205:479-483 (1983).

Tong DDM and Metzler CM. Mathematical properties of compartment models with Michae-lis-Menten-type elimination. Mathematical Biosciences 48: 293-306 (1980).

Wald, Abraham. Tests of statistical hypotheses concerning several parameters when the num-ber of observations is large. Transaction of the American Mathematical Society 54 (1943).

StatisticsAllen, David. private correspondence, 2001.

Clayton, D and Leslie, A. The bioavailability of erythromycin sterate versus enteric-coated erythromycin base tken immediately before and after food. Int. Med. Res 9:470-477(1981).

Conover, WJ. Practical Nonparametric Statistics (2nd ed.), John Wiley & Sons, New York (1980).

Dixon WJ and Massey FJ Jr. Introduction to Statistical Analysis, 3rd ed. McGraw-Hill Book Company, New York (1969).

Koch, G. The use of non-parametric methods in the statistical analysis of the two-period change-over design. Biometrics 577-584(1972).

Kutner, M. Hypothesis testing in linear models (Eisenhart Model 1). The American Statisti-cian, 28(3):98-100(1974).

Searle SR. Linear Models. John Wiley & Sons, New York (1971).


818

H

Steel RGD and Torrie JH. Principles and Procedures of Statistics; A Biometrical Approach, 2nd ed. McGraw-Hill Book Company, New York (1980).

Winer, BJ. Statistical Principles in Experimental Design, 2nd ed. McGraw-Hill Book Com-pany, New York, et.al. (1971).

BioequivalenceAnderson and Hauck. A new procedure for testing equivalence in comparative bioavailability and other clinical trials. Commun. Stat. Theory Methods, 12:2663-2692(1983).

Average, Population, and Individual Approaches to Establishing Bioequivalence. FDA Guid-ance for Industry. August 1999.

Bioavailability and Bioequivalence Studies for Orally Administered Drug Products—General Considerations. FDA Guidance for Industry. October 2000.

Chow and Liu (2000). Design and Analysis of Bioavailablilty and Bioequivalence Studies, 2nd edition, Marcel Dekker, Inc.

Schuirmann, Donald. A comparison of the two one-sided tests procedure and the power approach for assessing the equivalence of average bioavailability. J. Pharcokinet. Biop-harm.15:657-680 (1987).

Statistical Approaches to Establishing Bioequivalence. FDA Guidance for Industry. January, 2001.

819

Index

Symbols*.anv, 551*.bmp, 21*.exp, 70, 73*.imp, 54*.jpeg, 21*.wmf, 21*.wsp, 23

AABS, 289Absolute error bars, 134AggregateVar, 645AIC. See Akaike’s Information CriterionAkaike’s Information Criterion, 413

compartmental modeling, 268LinMix, 404

AliasPKS, 466

Alignmenttable cells, 198worksheet cells, 98

ALOG, 289ALOG10, 289AlphaTerms(), 645Ampersand (&), 311AND, 288Anderson-Hauck Test, 428

Animal2.pwo, 525ANOVA, 413Aovdata.pwo, 536APPEND, 525, 646Append

scripting, 525AppendFilename, 646AppendFileType, 646AppendSheet, 647Area under the curve. See AUC.ARRANGE, 647ASCII data files, 21ASCII models

creating, 298examples, 291loading user models, 300undo, 299

ATAN, 289ATAN2, 289Aterms(), 647AUC, 268

calculation formulas, 235calculation methods, 230compartmental modeling, 268partial area calculations, 236

AutoFileOptions, 648Automatic sorting, 131Autoregressive variance, 394AutoSort, 648


820

Average bioequivalence, 417, 420fixed effects, 439recommended models, 421setting up, 438

Axesoptions, 137uniform, 137

BBanded no-diagonal factor analytic, 394Banded Toeplitz variance, 394Banded unstructured variance, 394Bar charts, 130BEGIN, 322Bg1.cmd, 527Bg1.pwo, 516Bg1-dxg-9.pwo, 518Bguide1.dat, 521, 530Bioassay functions, 290Bioequivalence, 417

average, 438Bioequivalence Wizard, 437classification variables, 439command files, 445dependent variables, 439errors, 719fixed effects (average), 439fixed effects (pop./individ.), 444general options, 443linear model, 420options, 443, 445output, 446population/individual, 444random effects, 441regressor variables, 439repeated variance, 442sort variables, 439type, 437variance structure, 440weight variables, 439

Bitmaps, 21BOLUS, 648Borders

tables without, 203worksheet cells, 99

Box and whiskers plots, 208

CC++, 273Carry along data for like sort levels, 107CarryData, 648CASCADE, 649CaseSensitive, 649Cell references, 86Chart Designer, 129Chart Wizard, 129Charts, 129

automatic sorting, 131axis options, 137axis titles, 136bar charts, 130copy and paste, 184creating, 129error bars, 133group variables, 133histograms, 132intervals, 137legend, 136log, 137multiple X-Y variables, 131overlay, 131page setup, 182Pharsight Chart Objects, 21preview, 182restore positions, 18saving, 185saving to graphics formats, 21scatter plots, 130sort key title, 136sort variables, 133

IndexC

821

templates, 182title, 136uniform axes, 137units display default, 36use group headers, 136X-Y variables, 130

Classical and Westlake Confidence Inter-vals, 424Classification variables

bioequivalence, 439LinMix, 391

Clayton.pwo, 521, 535Clearing

cell formats, 89cell values, 89units, 127

CloseAll, 649CMT, 51CNAMES, 307Coefficients, 406COLUMN, 649COMMAND, 275, 285Command block, 277Command files, 309

bg1.cmd, 527model definition, 310nca_sort.cmd, 533

Commands, 310APPEND, 525BEGIN, 322command files, 309CONSTANTS, 317CONVERGENCE, 319COPY, 522DATA, 320DATE, 318descriptive statistics, 533DINCREMENT, 319DTA( ), 321EXCLUDE, 524FINISH, 322FNUMBER, 314, 320

INCLUDE, 524INITIAL, 316ITERATIONS, 320LOWER, 316MEANSQUARE, 319MERGE, 525METHOD, 319modeling, 533NCONSTANTS, 317NFUNCTIONS, 320NOBOUNDS, 316NOBS, 320NOPAGE, 319NOPLOTS, 319NOSCALE, 316NPARAMETERS, 316NPOINTS, 319PKS example scripts, 516plots, 526PNAMES, 317REMOVE, 523REPLACE, 522REWIEGHT, 315SET, 521SIMULATE, 313SIZE, 320SORT, 313, 321spanning multiple lines, 311TIME, 318TITLE, 318transformations, 529units, 537UPPER, 316URINE, 314WEIGHT, 315, 322WTnumber, 315, 322Xnumber, 313, 322Ynumber, 313, 322

Comments, 311comment character, 50

Comparison operators, 288Compartmental modeling, 247


822

See also Modeling.Compiling

Using C++, 305Using Fortran, 301

Compound symmetry variance, 394CON(N), 285ConcCol, 650Concentration-effect models, 602COND, 266CONFIDENCE, 650Confidence intervals, 208, 267Confidence limits

Univariate, 267Configuration

PKS, 465Connection string, 54CONSEQDELIM, 650CONSTANTS, 317Constrained optimization, 7Contrasts

degrees of freedom, 388LinMix, 386, 397nonestimability, 388

Control stream, 50CONVERGENCE, 319Convergence criterion, 263, 414

LinMix, 410Convolution, 349, 353COPY, 522, 651Copying

charts, 184Correlation matrix, 267COS, 289Covariates, 391, 439Crossover design, 342CROSSVAR( ), 651CROSSVARS, 652Curve stripping, 221Custom models. See User models.Custom query builder, 64Customer support, 10

licensing, 10

user feedback, 11CUT, 652

DDABS, 289DATA, 320, 632Data, 310

dependencies, 37file type limitations, 21file types, 19merging, 106out of date flag, 38sorting, 101transformations, 102unlocking, 39

Data variablescompartmental modeling, 250noncompartmental analysis, 217

DATAN, 289DATAN2, 289DATE, 318DCOS, 289DCP description, 474Deconvolution, 348, 349, 356Defaults

missing value indicator, 34modeling output, 34NCA calculation method, 34units, 36workbooks, 34

Defect reports, 11DefinitionFile, 653Degrees of freedom

LinMix contrasts, 388LinMix versus PROC MIXED, 413Satterthwaite’s approximation, 411

DeleteFiles, 653Deleting

cells, 91columns, 91

IndexE

823

rows, 91worksheets, 92

DELIMITER, 653DELTA, 654Dependencies, 37Dependent variables

bioequivalence, 439LinMix, 391NONMEM export, 51

Descriptive statistics, 207scripting, 533

DestArea, 654DestCol, 654Detach, 40Determining estimability, 373DEXP, 289DIFF, 285DIFFERENTIAL, 275Differential equations, 4

user models, 283DINCREMENT, 319Disable curve stripping, 221DLOG, 289DLOG10, 289DMAX1, 289DMIN1, 289DNAMES, 280, 286DnErr( ), 655Do, 287Document manager, 479DoseFile, 655DoseUnit, 655Dosing

command files, 317constants for ASCII models, 256dose normalization, 124noncompartmental analysis, 223NONMEM export, 51PKS, 464, 483regimen, 223, 254simulation, 456

Down variable, 134

DSIN, 289DSQRT, 289DTA, 321DTA( ), 321DTA(N), 284DVID, 51DZ(N), 285

EECOL, 656Edit bar, 88Eigenvalues, 268, 405Else, 287END, 276, 285, 292EndCol, 656EndRow, 656Engines, 495

scripting language, 490Enhancement requests, 11EntireRow, 657EOM, 276, 286, 292EQ operator, 288Error bars, 133

absolute, 134relative, 134

Error messages, 707bioequivalence, 719compartmental modeling, 707descriptive statistics, 721LinMix, 719noncompartmental analysis, 722scripting, 723tables, 721

ErrType, 657Estimates

fixed effects, 405LinMix, 389, 398

ExamplesExamples Guide, 2scripting, 520


824

ExcelExcel 4.0 files, 21files, 21saving workbooks to Excel, 21

EXCLUDE, 524, 658Exclude profiles with insufficient data,226Excluding

based on criteria, 109selected cells, 109

EXP, 289ExportAll, 658Exporting, 44, 55

NONMEM, 47ODBC, 69SAS Transport files, 47tables, 203Word export, 44Word export options, 46

EXTRA, 658

FF, 284File types

compatibility, 22FileMask, 659Files

ASCII, 21data file limitations, 21data files, 19PKS files, 513SAS Transport, 47

FileType, 660Fill-down, 88Final parameters

confidence intervals, 267FIND, 660Find, 93FINISH, 322Fixed effects, 375

average bioequivalence, 439LinMix, 375, 391parameter estimates, 405pop./individ. bioequivalence, 444

FNUMBER, 314, 320FONT, 661Font format, 98FontSize, 661FootnoteFont, 662FootnoteFontSize, 662FORMAT, 97Formatting

tables, 200worksheet cells, 97

Formulas, 86operators, 86

FORTRAN, 273, 301Freezing rows and columns, 101FUNC, 285FUNCTION, 275, 662Function block, 292Function variable, 278, 279FUNCTIONS, 307

GGauss-Newton algorithm, 6

Hartley modification, 5, 9Levenberg Hartley modification, 8Levenberg-type modification, 5

GE operator, 288Go to, 96GOTO, 286Green

scenario icon, 476Group variables

charts, 133tables, 192, 193

GroupVar( ), 663GroupVar( , ), 664GroupVarBreak( ), 665

IndexH

825

GroupVars, 664GroupVars( ), 664GT operator, 288

HHALT, 665HEADERS, 665Hessian eigenvalues, 405Heterogeneous

autoregressive variance, 394compound symmetry, 394

Hidden windows, 19Histograms, 132

intervals, 137History

"cannot be processed", 41items logged, 41worksheets, 40

IID variables, 192IDVar( ), 666IDVars, 666If Then Else, 286Import settings file

ODBC, 55Importing

ODBC, 53INCLUDE, 524, 666IncludeVar( , ), 667IncludeVars( ), 667Including

based on criteria, 109selected cells, 109

Increment for partial derivatives, 262InData, 667InData( ), 668Indirect response models, 605, 608

parameter estimates and bounds, 609

parameters, 608Individual bioequivalence, 418INITIAL, 316, 633Initial parameter estimates, 250InitialDose, 668InputLag, 668Inserting

cells, 91columns, 90rows, 90worksheets, 92

INTERVAL, 669Intervals, 137ITERATIONS, 320Iterations, 264

history, 406procedure, 4

Iterative reweighting, 315, 326IV.pwo, 528

JJoin variables

merge data sets, 106tables, 195

JoinCrossVar( , ), 669JoinCrossVars, 669JoinGroupVar( , ), 670JoinGroupVars, 670JoinIDVar( , ), 670JoinIDVars, 671Joint Contrasts, 387JPEG files, 21

KKE0, 671

LLABEL, 286


826

Lambda z, 218LamzFile, 671LE, 289Least squares means, 4, 423

LinMix, 383, 399Legend( ), 672LegendFont, 672LegendFontSize, 672Legends, 136Licensing

customer support, 10Linear interpolation rule, 236Linear Mixed Effects Modeling. See Lin-Mix.Linear models, 2Linear regression, 2

minimization alrorithm, 262Linear trapezoidal rule, 235Link models, 602

simultaneous, 612LinkFile, 673LinMix, 363

Akaike’s criterion, 404classification variables, 391coefficients, 406compared to ANOVA, 413compared to PROC MIXED, 413computations, 407contrasts, 386, 397convergence criterion, 410dependent variables, 391errors, 719estimability, 373estimates, 389, 398fixed effects, 375, 391fixed effects estimates, 405general options, 400Hessian eigenvalues, 405hypothesis tests, 403initial variance parameters, 401iteration history, 406least squares means, 383, 399

limits and constraints, 390linear mixed effects model, 366LinMix Wizard, 389Newton’s algorithm, 408non-estimable functions, 373output, 401output parameterization, 375parameters, 406partial tests, 403predicated values, 405random effects, 380, 395regressor variables, 391REML, 407repeated effects, 378, 396residuals, 405Satterthwaite’s approximation, 411Schwarz’s criterion, 404sequential tests, 403singularity tolerance, 376sort variables, 391text output, 401transformation of the response, 376variance structure, 378, 393weight variables, 392workbook output, 402X matrix, 368

LLOQuse when less than LLOQ, 116

LOAD, 673Loading

a query (ODBC), 62, 69an export (ODBC), 75

LoadTemplate, 673LOG10, 289Logarithmic

axes, 137interpolation rule, 236transformation, 102trapezoidal rule, 236

LOGE, 289LOWER, 267, 316, 633LT operator, 288

IndexM

827

MMaintenanceDose, 674Marking valid/invalid data, 38Mathematical operators, 286MAX, 289Maximum likelihood estimates, 4Mean square, 263MEANSQUARE, 319MERGE, 525Merging, 106

scripting, 525METHOD, 319Method

scripting language, 490Michaelis-Menten, 3, 609Microsoft Excel

table export to, 204Microsoft Visual C++, 305Microsoft Word

export, 44table export to, 203

MIN, 289Minimization algorithm, 261MISSING, 674Missing values

data, 450default indicator, 34in NCA parameter estimates, 235

MODEL, 275, 293Model definition, 310Model options, 225, 257, 318

convergence criterion, 263exclude profiles with insufficient data,

226increment for partial derivatives, 262iterations, 264mean square, 263minimization, 261model size, 264number of predicted values, 263output, 258

output intermediate calculations, 228PK settings, 261title, 261title for NCA, 230transpose final parameter table, 231,

262units, 264weighting for nca, 229

Model parameters, 250command files, 316compartmental models, 250

Model propertiescompartmental models, 249dosing, 254

Model size, 264Model variables

compartmental modeling, 250noncompartmental analysis, 217

Modelingcompartmental, 247convergence criterion, 263data variables, 250default output, 34dose normalization, 124dosing, 254error messages, 707initial parameter estimates, 250iterations, 264linear models, 2mean square, 263minimization alrorithm, 261model options, 257model settings, 249model size, 264NONMEM export, 47notation and conventions, 574number of predicted values, 263options, 34output dependencies, 37output options, 258PK settings, 261refreshing output, 38


828

scaling of weights, 260scripting, 533start, 265stop, 265troubleshooting, 718units, 264weights, 259

Modelsconcentration-effect, 602creating ASCII models, 298indirect response, 605link, 602loading, 247loading ASCII models, 300Michaelis-Menten, 609noncompartmental, 216pharmacokinetic, 575Pharsight Model Objects, 20simulatneous link, 612types, 247user model templates, 273user models, 273

Modified likelihood, 414Multiple charts per page, 183Multiple linear regression, 3Multiple profiles in script files, 501Mydata.pwo, 529

NNaming

columns, 100worksheet, 92

NCA. See Noncompartmental analysis.Nca_sort.cmd, 533Ncamodel.pmo, 534NCONSTANTS, 278, 317NDERIVATIVES, 278, 307Nelder-Mead, 5Nelder-Mead simplex, 8Nested variables, 392

Newton’s Algorithm, 408Next, 288NFUN, 631NFUNCTIONS, 278, 320No Scaling of Weights, 261NOBOUNDS, 316NOBSERVATIONS, 279, 320, 632No-diagonal factor analytic, 394Noncompartmental analysis, 215

AUC formulas, 235computational rules, 234curve stripping, 221data exclusions, 234default calculation method, 34dosing, 223errors, 722exclude profiles with insufficient data,

226Lambda z, 218missing parameter values, 235model selection, 216model variables, 217output, 226output intermediate calculations, 228output options, 226parameter calculations, 240parameter names, 233partial area computations, 236partial areas, 221therapeutic response window, 222therapeutic window calculations, 237units, 232weighting, 229

Nonlinear model, 3Nonlinear regression, 2, 5

methods, 8NONMEM export, 47

CMT, 51comment character, 50control stream, 50dependent variables, 51dosing, 51

IndexO

829

DVID, 51occations, 52other data items, 51problem, 50

Non-numeric datatroubleshooting, 15

Nonparametric superposition, 329NOPAGE, 319NOPLOTS, 319NOSCALE, 316NPARAMETERS, 277, 307, 316, 633NPOINTS, 319NSECONDARY, 279, 307Number format, 97Number of predicted values, 263

OObjects

Scripting Language, 490, 494Occasions, 52ODBC export, 69

defining an export, 70export defined, 55export settings file, 70loading a saved connection, 57saving export settings, 73

ODBC import, 53building a query, 58connection string, 54custom query builder, 64import defined, 55import settings file, 54loading a saved connection, 57save password, 61saving queries, 61Watson DMLIMS, 64

Operators, 288Options, 33

bioequivalence, 443, 445LinMix, 400

models, 34NCA model, 225NCA output, 226Word export, 46workbooks, 34

OR, 288Oral.pwo, 529Other data items

NONMEM export, 51Output intermediate calculations, 228Output titles, 230Overlay chart, 131

PP(N), 285Page setup, 27

charts, 182Parameter names

noncompartmental analysis, 233Parameters

LinMix output, 406Partial areas, 221

computation of, 236Partial derivatives, 4, 7

increment, 262Partial tests, 403Password

PKS, 466save ODBC password, 61

Patterns format, 99Percentiles, 208Performance

PKS, 480Pharmacodynamic models, 596Pharmacokinetic models, 4, 8, 575Pharsight, 9

contact information, 10customer feedback, 11technical support, 10

Pharsight Chart Objects, 21


830

Pharsight Knowledgebase Server. SeePKS.Pharsight Model Objects, 20Pharsight Text Objects, 21Pharsight Workbook Objects, 20PK settings, 261PK text output, 266PK/PD link models, 602

simultaneous, 612PKS, 1

accessing, 463alias, 466configuration, 465creating scenarios, 477DCP description, 474dosing, 464, 483file format, 513green icon, 476load study or scenario, 475logging on, 465non-WinNonlin documents, 479objects, 461password, 466performance, 480red icon, 476scenario search, 477scenarios, 463scripting examples, 516server, 466sessions, 463study, 461study metadata, 462time, 462user name, 466using with WinNonlin, 461

PLANAR, 267Plant2.pwo, 526Plots, 129

scripting, 526PNAMES, 280, 286, 295, 307, 317Population bioequivalence, 418Population/individual bioequivalence, 444

data requirements, 444fixed effects, 444

Power, 428Preferred units, 232Previewing charts, 183Printing, 25

page setup, 27print all, 26print dialog, 25

PrintMulti, 683PrintMultiAcross, 683PrintMultiDown, 683PrintText, 684Problem

NONMEM, 50PROC MIXED, 413Profiles.pwo, 526, 528Programming Language, 286PUNIT, 280, 307, 312

QQueries

building ODBC queries, 58

RRandom effects

bioequivalence, 441LinMix, 380, 395

RANK, 266Ratio tables, 449Red

scenario icon, 476Refresh, 38Refresh All, 39Regression methods, 8

Gauss-newton algorithm, 8, 9Regressor variables

bioequivalence, 439LinMix, 391

IndexS

831

RegVar( ), 684RegVars, 684Relative error bars, 134REMARK, 311REML, 413

LinMix, 407Newton’s algorithm, 408

REMOVE, 523, 685RemoveCol, 685RemoveRow, 685RenameCol, 686Repeated

bioequivalence, 442Repeated effects

LinMix, 378, 396REPLACE, 522, 686Replace, 93Resetting data exclusions, 111Residuals, 268RESPONSE, 687Restore positions, 18Restricted maximum likelihood

LinMix, 407Newton’s algorithm, 408

REWEIGHT, 315Rich text files, 21Rule sets, 114RUN, 687RunWordExport, 687

SS, 268S(N), 285SameErrCol( ), 688SAS Transport file

export, 47Satterthwaite’s approximation, 411SAVE, 688Save import query, 61SaveAll, 688

SaveAllPrefix, 689SaveTemplate, 689Scaling of weights, 260, 326Scatter plots, 130Scenarios, 463

adding non-WinNonlin documents,479

creating, 477search, 477

Schwarz’s Bayesian Criterion (SBC), 268, 404, 413Scripting

appending data, 525copying and pasting data, 521data manipulation, 521descriptive statistics, 533error messages, 723examples, 520excluding and including data, 524loading data files, 521merging data sets, 525modeling, 533PKS, 512PKS examples, 516plots, 526removing a column, 524removing a range of rows, 523removing rows based on a value, 523renaming a column, 522replacing values in a worksheet, 522script file (.PSC), 490script file components, 498tables, 535, 536transformations, 529units, 537

SDK, 75SearchArea, 689SECONDARY, 275, 285, 292Secondary parameters, 269

user models, 283Select Data for Modeling dialog, 265Semicompartmental modeling, 335


832

SEQUENCE, 690Sequential tests, 403Server

PKS, 466SET, 521Setting preferred units, 264Show formulas, 34ShowUnits, 690Significant digits

tables, 198Simplex algorithm, 5, 267SIMULATE, 313Simulation, 451

comparing dose schemes, 459dosing, 456model parameters, 455

Simultaneous PK/PD link models, 612SIN, 289Singular or near-singular equations, 6Singular value decomposition, 6Singularity tolerance, 376, 415SIZE, 320SMOOTHING, 690SNAMES, 280, 286, 307SORT, 101, 313, 321, 691Sort key title, 136Sort variables

bioequivalence, 439charts, 133LinMix, 391

Sortingworksheet data, 101

SortLevel, 691SortVar( ), 691SortVar( , ), 691SortVars, 692SortVars( ), 692SourceCol, 693Splitting Commands, 311SQRT, 289STACKED, 693Standard error, 267

STAR, 285START, 275StartCol, 693StartRow, 694STATS, 694Status code transformations, 111

LLOQ, 116rule sets, 114

Structure of a model, 274Study

PKS, 461SUBJECT, 694Summary statistics, 207

tables, 197SummaryVar( ), 694SummaryVars, 695SUNIT, 280, 307, 312

TTAB, 695Table Wizard, 187

cell alignment, 198data only, 203formatting, 200significant digits, 198summary statistics, 197templates, 188

Table1.pwo, 535Table2.pwo, 536TableNum, 695Tables, 187

cell alignment, 198column alignment, 199data only, 203error messages, 721export to Excel, 204export to Word, 203formatting, 200group variables, 193join variables, 195

IndexU

833

scripting, 535, 536significant digits, 198summary statistics, 197templates, 188units display default, 36

TAU, 696Technical support, 10

licensing, 10TEMP, 285Templates

charts, 182tables, 188user models, 273

TEMPORARY, 275Temporary variables, 280

naming, 281TEMPORARY VARIABLES Block, 281TerminalLower, 696TerminalPhase, 696TerminalUpper, 696Tests of hypotheses, 403Text windows

Pharsight Text Objects, 21Therapeutic response window, 222Therapeutic window

calculations, 237TileHorizontal, 697TileVertical, 697TIME, 318TimeCol, 697TimeRepeat, 697TITLE, 318, 697Title, 230, 261TitleFont, 698TitleFontSize, 698Toeplitz variance, 394TOLERANCE, 698TRANSFORM, 275, 285Transform data command, 102Transformations, 102

LinMix response, 376scripting, 529

Transpose final parameter table, 34compartmental modeling, 262non-compartmental modeling, 231

Trapezoidal rule, 268default method for NCA, 34

Troubleshooting, 718loading tabular data, 15

Trust region, 6Types of models, 247

UUndo, 95

in ASCII models, 299UNIFORM, 699Uniform axes, 137UNIT, 699Units

compartmental modeling, 264converting, 127display, 120entering, 126mass, 122noncompartmental analysis, 232options, 36, 121PKS, 119preferred, 125prefixes, 122scripting, 537summary statistics, 212time, 121volume, 122

Univariate command, 267UNLOAD, 700Unlocking derived data, 39Unstructured variance, 394Up variable, 134UpErr( ), 700UPPER, 267, 316, 633URINE, 314Use group headers, 136


834

User models, 273command block, 277command files, 309compiled, 307creating an ASCII model, 298differential equation block, 283examples, 291function block, 281libraries, 290loading ASCII models, 300secondary parameters block, 283starting values block, 282templates, 273temporary variables, 280transform block, 276WinNonlin variables, 284

User namePKS, 466

VValid data, 38Variables

charts, 130group, 133ID, 192model variables, 250model variables for NCA, 217names, 285sort, 133temporary, 280WinNonlin variables, 284

Varianceautoregressive, 394banded no-diagonal, 394Banded Toeplitz, 394banded unstructured, 394components, 394compound symmetry, 394heterogeneous autoregressive, 394heterogeneous compound symmetry,

394no-diagonal factor analytic, 394Toeplitz, 394unstructured, 394

Variance structure, 378, 393, 420, 440bioequivalence, 440LinMix, 393types, 394

Variation inflation factor (VIF), 458

WWarnings and errors, 707Watson DMLIMS, 54, 64WEIGHT, 315, 322, 701Weight

command, 315, 322variables (bioequivalence), 439variables (LinMix), 392

Weighted least squares, 315, 325Weighted summary statistics, 212Weighting, 325

commands, 314compartmental modeling, 259in ASCII models, 327iterative reweighting, 315, 326noncompartmental analysis, 229scaling, 326scaling of weights, 260weighted least squares, 325weights from data file, 326

Windowshiding, 19

Windows metafiles, 21WindowState, 701WinNonlin

defect reports, 11enhancement requests, 11Enterprise, 1options, 33Professional, 1

IndexX

835

variables in user models, 284WinNonlin object files, 21

WinNonlin Script File, 490WITH, 701Word

export, 44export options, 46table export, 203

WordExportFilename, 701Workbooks, 13

dependencies, 37missing values, 34new, 13operators, 86options, 34out of date, 38Pharsight Workbook Objects, 20refreshing, 38saving to Excel, 21show formulas, 34status codes, 111troubleshooting, 15unlocking, 39

WorkingDir, 702Worksheets, 14

adding, 14borders, 99cell references, 86deleting, 14fill-down, 88find, 93formulas, 86go to, 96history, 40merging, 106replace, 93sorting, 101transformations, 102

Workspaces, 23loading, 25new, 24saving, 24

WT, 285WTnumber, 315, 322

XX, 285X matrix, 368XLabelsFont, 702XLabelsFontSize, 703Xnumber, 313, 322XTitle, 703XTitleFont, 703XTitleFontSize, 703XUnits, 704XVar( ), 704

YYLabelsFont, 705YLabelsFontSize, 705Ynumber, 313, 322YTitle, 705YTitleFont, 705YTitleFontSize, 706YUnits, 706YVar, 706

ZZ(N), 285


836