User’s Guide

StatTools 5.0 for

Excel Developer
Kit
Programming Interface for
the StatTools Add-in to
Microsoft Excel
®

Windows Version 5
April, 2009

Palisade Corporation
798 Cascadilla St
Ithaca, NY 14850
(607) 277-8000
http://www.palisade.com
Copyright Notice
Copyright © 2009, Palisade Corporation.

Trademark Acknowledgments
Microsoft, Excel and Windows are registered trademarks of Microsoft, Inc.
Lotus and 1-2-3 are registered trademarks of Lotus Development Corporation
IBM is a registered trademark of International Business Machines, Inc.
Palisade, TopRank, BestFit and RISKview are registered trademarks of Palisade Corporation.
RISK is a trademark of Parker Brothers, Division of Tonka Corporation and is used under license.
Contents

Introduction............................................................................................ 1
An Overview to Automating StatTools ........................................................ 1
Creation of Custom Analyses................................................................ 1
Automation of Existing Analyses ......................................................... 2
The Automation Components ....................................................................... 3
The StatTools Object Library (StatToolsOL.DLL)............................... 3
The StatTools Controls Library (STControls5.OCX) .......................... 4
The StatTools Core Pack Automation Library
(StatToolsCoreAL5.DLL)........................................................................ 5
Packs, Categories, and Analyses ................................................................... 6
Terminology............................................................................................. 6
Automation Objects ................................................................................ 7
The StatToolsAnalysis and StatToolsAnalyses Objects.......................... 8
Data Sets, Variables, and Variable Lists ....................................................... 9
Terminology............................................................................................. 9
Automation Objects ................................................................................ 9
Scanning Workbooks............................................................................ 10
Stacked and Unstacked Variables....................................................... 11
Creating New Data Sets and Variables .............................................. 14
Selecting Variables in Dialogs ............................................................. 15
Reports, Tables, and Charts ......................................................................... 16
Reports Objects...................................................................................... 16
Table Objects.......................................................................................... 18
Chart Objects.......................................................................................... 20
Live vs. Static Results ........................................................................... 20

Creating a Custom Analysis for StatTools ....................................... 23

Building an Analysis ..................................................................................... 23
Introduction ........................................................................................... 23
Creating an Add-in File........................................................................ 24
Creating a Reference to the StatTools Object Library ...................... 24
Running Your Custom Analysis ......................................................... 25

Contents i
 Creating a Defined Type and Global State Variable ........................ 26
The Required Public Subroutines ....................................................... 27
Compiling and Saving the New Analysis.......................................... 32
Debugging Your Custom Analysis..................................................... 33
Creating Analysis Packs ............................................................................... 34
Creating a Simple Custom Analysis Pack ......................................... 34
Customizing Packs with Configuration Files.................................... 34
Creating an Analysis Pack Help File .................................................. 38

StatTools Object Library Reference ...................................................39

StatTools Object.............................................................................................. 39
Analyses Property ................................................................................. 39
AnalysisCategories Property ............................................................... 40
AnalysisPacks Property........................................................................ 41
AskOKCancel Method.......................................................................... 42
AskYesNo Method ................................................................................ 42
DataSets Property.................................................................................. 43
DisplayAlerts Property......................................................................... 43
ExcelApp Property................................................................................ 44
Message Method ................................................................................... 45
NewChart Method ................................................................................ 46
NewReport Method .............................................................................. 47
NewStackedVariable Method.............................................................. 49
NewStackedVariableList Method ....................................................... 50
NewTable Method ................................................................................ 51
NewVariableList Method..................................................................... 52
ProductInformation Property.............................................................. 53
ProgramDirectory Property................................................................. 53
ProgressBar Method ............................................................................. 54
ResultString Property ........................................................................... 56
Settings Property ................................................................................... 56
ShowAboutDialog Method.................................................................. 57
ShowAuthorizationDialog Method .................................................... 57
ShowHelp Method ................................................................................ 58
ShowOnlineManual Method ............................................................... 58
SystemDirectory Property.................................................................... 59
StatTools Analyses Object............................................................................. 61
Count Property ...................................................................................... 61
Item Property ......................................................................................... 61
StatToolsAnalysis Object .............................................................................. 63
AddinPath Property.............................................................................. 63
AnalysisCategory Property.................................................................. 63
AnalysisPack Property ......................................................................... 64
BeginGroup Property ........................................................................... 64

ii
 BuiltIn Property..................................................................................... 65
DebugMode Property........................................................................... 65
Default Method ..................................................................................... 66
DefaultDataSet Method........................................................................ 68
DefaultRange Method .......................................................................... 69
DefaultVariable Method ...................................................................... 70
DefaultVariableList Method................................................................ 71
HelpContextID Property...................................................................... 72
LoadAddIn Method.............................................................................. 73
MenuCaption Property ........................................................................ 74
Name Property ...................................................................................... 74
NewSheetName Property .................................................................... 75
ReportDescription Property ................................................................ 75
RequiresVariables Property................................................................. 76
Run Method ........................................................................................... 77
ShowHelp Method................................................................................ 78
UnloadAddin Method .......................................................................... 79
Utility Property ..................................................................................... 80
StatToolsAnalysisCategories Object ........................................................... 81
Count Property...................................................................................... 81
Item Property......................................................................................... 82
StatToolsAnalysisCategory Object .............................................................. 83
Analyses Property................................................................................. 83
AnalysisPack Property ......................................................................... 83
BeginGroup Property ........................................................................... 84
BuiltIn Property..................................................................................... 84
MenuCaption Property ........................................................................ 85
Name Property ...................................................................................... 85
ToolbarBitmapFile Property ................................................................ 86
StatToolsAnalysisPack Object...................................................................... 87
Analyses Property................................................................................. 87
AnalysisCategories Property............................................................... 87
BuiltIn Property..................................................................................... 88
Description Property ............................................................................ 88
HasConfigurationFile Property........................................................... 89
HelpPath Property ................................................................................ 89
Name Property ...................................................................................... 90
Path Property......................................................................................... 90
Priority Property ................................................................................... 91
ShowHelp Method................................................................................ 91
StatToolsAnalysisPacks Object .................................................................... 92
Count Property...................................................................................... 92
Item Property......................................................................................... 92

Contents iii
 Path Property ......................................................................................... 93
StatToolsChart Object.................................................................................... 94
AddCategoryXAxis Method................................................................ 94
AddLegend Method.............................................................................. 95
AddTitle Method................................................................................... 95
AddValueXAxis Method...................................................................... 96
AddValueYAxis Method...................................................................... 97
AddWatermark Method....................................................................... 98
ApplyDefaultFormatting Method....................................................... 98
ApplyGradientToBars Method ........................................................... 99
Chart Property ....................................................................................... 99
DefaultSeriesColor Method ............................................................... 101
StatToolsDataSet Object .............................................................................. 103
Attach Method ..................................................................................... 103
AutoFitColumns Method ................................................................... 104
CreateUtilityVariables Method ......................................................... 104
CreateUtilityVariables_Validate Method ........................................ 106
DataRegion Property .......................................................................... 107
Delete Method ..................................................................................... 108
ExcelRange Property........................................................................... 108
ExcelRangeCount Property................................................................ 109
FormatRange Property ....................................................................... 109
Name Property .................................................................................... 110
NameRegion Property........................................................................ 111
Variables Property .............................................................................. 111
StatToolsDataSets Object ............................................................................ 113
Add Method......................................................................................... 113
AddMulti Method ............................................................................... 116
CheckModelLimitations Method ...................................................... 119
Count Property .................................................................................... 119
DeleteAll Method ................................................................................ 120
Find Method......................................................................................... 121
Item Property ....................................................................................... 122
Scan Method ........................................................................................ 123
ScannedWorkbook Property.............................................................. 124
ShowDataSetManager Method ......................................................... 124
TotalNumVariables Property ............................................................ 125
StatToolsProductInfo Object ...................................................................... 127
Copyright Property............................................................................. 127
DaysUntilExpiration Property .......................................................... 127
Edition Property .................................................................................. 128
Language Property.............................................................................. 128
LimitedModelSize Property............................................................... 129
Name Property .................................................................................... 129
ProductType Property ........................................................................ 130
iv
 RegisteredCompany Property........................................................... 130
RegisteredSerialNumber Property ................................................... 131
RegisteredUser Property.................................................................... 131
Version Property ................................................................................. 131
WatermarkedGraphs Property.......................................................... 132
StatToolsReport Object ............................................................................... 133
FinalizeReport Method....................................................................... 133
HeaderRange Property....................................................................... 134
ReportRange Property........................................................................ 134
Result Property.................................................................................... 135
StatToolsSettings Object.............................................................................. 137
AnalysisDialogsUseMemory Property ............................................ 137
AnalysisPercentileCalculationMethod Property ............................ 138
AnalysisWarnMissingData Property ............................................... 139
AnalysisWarnNonNumericData Property ...................................... 140
ClearWorkbookMemory Method ..................................................... 141
DataSetDefaultFormatRange Property ............................................ 142
DataSetDefaultNamesInRange Property ......................................... 143
DataSetDefaultVariableLayout Property......................................... 144
ReportDestinationCell Property ....................................................... 145
ReportEducationalComments Property........................................... 146
ReportLiveUpdatingPreferred Property.......................................... 147
ReportNotesAndWarnings Property ............................................... 148
ReportOverwriteExisting Property................................................... 149
ReportPlacement Property................................................................. 150
ReportReuseNewWorkbook Property ............................................. 151
ShowDialog Method........................................................................... 152
UtilityLiveUpdatingPeferred Property............................................ 153
UtilityNewVariablePreference Property.......................................... 154
StatToolsTable Object.................................................................................. 156
AddCustomComment Method ......................................................... 156
AddDividerLine Method ................................................................... 157
AddHeaderTallText Method ............................................................. 158
AddHeaderText Method.................................................................... 159
AddHeaderVariable Method............................................................. 160
AddHeaderVariableList Method ...................................................... 161
AddStandardComment Method ....................................................... 162
HeaderRange Property....................................................................... 163
InteriorRange Property ...................................................................... 164
SignatureRange Property................................................................... 164
TableRange Property .......................................................................... 165
StatToolsVariable Object............................................................................. 166
AutoFitColumns Method................................................................... 166

Contents v
 CheckCategoryHeuristic Method ..................................................... 167
CountCategories Method ................................................................... 168
CountCategoryOccurrences Method................................................ 169
CountCells Method ............................................................................. 170
Covariance Property ........................................................................... 171
DisplayName Property....................................................................... 172
ExcelRange Property........................................................................... 173
ExcelRangeCount Property................................................................ 174
FreezeData Method............................................................................. 175
GetCategoryNames Method.............................................................. 176
GetCategoryOccurrences Method..................................................... 177
GetCellPositions Method ................................................................... 178
GetCellValues Method ....................................................................... 179
GetCellValuesAsCategories Method................................................ 180
GetCellValuesAsNumbers Method .................................................. 181
HasMissingData Property.................................................................. 182
HasNonNumericData Property ........................................................ 183
Maximum Property............................................................................. 183
Mean Property ..................................................................................... 184
Minimum Property ............................................................................. 185
Name Property .................................................................................... 185
NumberFormatExcelCode Property................................................. 186
NumberFormatIsAuto Property ....................................................... 188
NumberFormatNumDigits Property................................................ 189
NumberFormatString Property......................................................... 190
NumberFormatType Property .......................................................... 191
Percentile Property.............................................................................. 192
RangeName Property ......................................................................... 193
ReferenceStr Property......................................................................... 194
ReferenceStrEx Property .................................................................... 195
Stacked Property ................................................................................. 196
StackedCategoryVariable Property .................................................. 197
StackedValueVariable Property ........................................................ 198
StdDev Property .................................................................................. 199
Variance Property ............................................................................... 200
WriteCustomFormattedFormula Method........................................ 201
WriteStandardFormattedFormula Method ..................................... 202
StatToolsVariableList Object ...................................................................... 205
Add Method......................................................................................... 205
AddList Method .................................................................................. 206
AllFromSameDataSet Property ......................................................... 206
AllSameLayout Property.................................................................... 207
AllSameSize Property ......................................................................... 207
ApplyUtilityFormatting Method ...................................................... 208
Clear Method ....................................................................................... 209
vi
 Count Property.................................................................................... 209
HasMissingData Property.................................................................. 210
HasMultiRangeVariable Property .................................................... 210
HasNonNumericData Property ........................................................ 211
IsStackingSet Property........................................................................ 211
Item Property....................................................................................... 212
MaxCellCount Property ..................................................................... 212
Remove Method .................................................................................. 213
SharedNumberFormatExcelCode Property .................................... 214
Validate Method.................................................................................. 216
StatToolsVariables Object........................................................................... 217
Count Property.................................................................................... 217
Insert Method ...................................................................................... 218
InsertValidate Method........................................................................ 218
Item Property....................................................................................... 220
Layout Property .................................................................................. 220
NamesInRange Property.................................................................... 221

Using the STControls OCX ............................................................... 222

Overview ...................................................................................................... 222
Adding the Controls to Excel VBA................................................... 222
Attaching and Detaching the Controls............................................. 223
The Option Panel Control .................................................................. 224
The Variable Selector Control............................................................ 225

STControls OCX Reference .............................................................. 229

STControlsOptionPanel Object.................................................................. 229
Attach Method..................................................................................... 229
Detach Method .................................................................................... 230
SaveAsDefault Event .......................................................................... 230
STControlsValidation Object ..................................................................... 231
CategoryCountMax Property ............................................................ 231
CategoryCountMin Property ............................................................ 232
CategoryHeuristic Property .............................................................. 232
CategoryOverflowResponse Property ............................................. 233
CellCountMatching Property ............................................................ 234
CellCountMin Property...................................................................... 235
CellCountMax Property ..................................................................... 236
CellCountNonMissingOnly Property .............................................. 237
Enabled Property ................................................................................ 238
MissingDataBeginningResponse Property...................................... 239
MissingDataEndResponse Property................................................. 240

Contents vii
 MissingDataMiddleResponse Property ........................................... 241
MissingDataSetAll Method................................................................ 242
MultiRangeVariablesAllowed Property .......................................... 243
NonNumericDataResponse Property............................................... 243
NumericRangeMax Property ............................................................ 244
NumericRangeMin Property ............................................................. 245
RowVariablesAllowed Property ....................................................... 246
SelectionCountMax Property ............................................................ 246
SelectionCountMin Property ............................................................. 247
SetDefaultConfiguration Method ..................................................... 248
SingleDataSet Property....................................................................... 250
ValidateEvenIfInvisible Property ..................................................... 250
STControlsVarSelector Object.................................................................... 251
ActiveDataSet Property ...................................................................... 251
Attach Method ..................................................................................... 252
Caption Property................................................................................. 253
DataFormat Property .......................................................................... 254
DataFormatChange Event.................................................................. 255
DataFormatMode Property................................................................ 256
Detach Method .................................................................................... 257
EnforceSingleSelectionPerRow Property......................................... 258
Fields Property .................................................................................... 259
SelectionChange Event ....................................................................... 259
StdCaption Property ........................................................................... 260
Validate Method.................................................................................. 261
STControlsVarSelectorField Object ........................................................... 263
Caption Property................................................................................. 263
EnforceSingleSelection Property ....................................................... 263
GetSelectionCount Method................................................................ 264
Index Property ..................................................................................... 264
Selection Property ............................................................................... 265
SelectionList Property......................................................................... 266
Validation Property ............................................................................ 266
Visible Property................................................................................... 267
STControlsVarSelectorFields Object ......................................................... 269
Count Property .................................................................................... 269
GetVariableListFromStackedPair Method....................................... 270
Item Property ....................................................................................... 271
SetStackedPairFromVariableList Method........................................ 272

Automating the StatTools Core Analysis Pack.............................. 273

Overview....................................................................................................... 273
Attaching to the Core Analysis Pack Automation Library ........... 274
Creating an Automation Object ........................................................ 275

viii
 An Example.......................................................................................... 276

StatTools Core Analysis Pack Automation Reference .................. 277

Methods and Properties Shared By All Automation Objects ................ 277
AnalysisObject Property .................................................................... 277
Defaults Method.................................................................................. 278
GenerateReport Method..................................................................... 279
RunAnalysis Method.......................................................................... 280
ShowDialog Method........................................................................... 281
Validate Method.................................................................................. 282
Automation Object Reference .................................................................... 283
StatTools_ANOVAOneWay .............................................................. 283
StatTools_ANOVATwoWay ............................................................. 284
StatTools_Autocorrelation ................................................................. 284
StatTools_BoxPlot ............................................................................... 285
StatTools_ChiSqIndependence.......................................................... 285
StatTools_ChiSqTest ........................................................................... 286
StatTools_Combination ...................................................................... 287
StatTools_ConfInterval....................................................................... 288
StatTools_ControlChartC................................................................... 289
StatTools_ControlChartP ................................................................... 291
StatTools_ControlChartU................................................................... 293
StatTools_ControlChartXR ................................................................ 295
StatTools_CorrAndCovar .................................................................. 297
StatTools_Diff ...................................................................................... 297
StatTools_Discriminant ...................................................................... 298
StatTools_Dummy .............................................................................. 299
StatTools_Forecast .............................................................................. 300
StatTools_Histogram .......................................................................... 303
StatTools_HypothesisTest.................................................................. 304
StatTools_Interaction .......................................................................... 306
StatTools_Lags..................................................................................... 307
StatTools_Lilliefors ............................................................................. 307
StatTools_Logistic ............................................................................... 308
StatTools_MannWhitneyTest ............................................................ 309
StatTools_OneVarSummary .............................................................. 310
StatTools_ParetoChart........................................................................ 311
StatTools_SignTest .............................................................................. 313
StatTools_QQNormal ......................................................................... 314
StatTools_RandomSample ................................................................. 315
StatTools_Regression.......................................................................... 316
StatTools_RunsTest............................................................................. 319
StatTools_SampleSize......................................................................... 320
Contents ix
 StatTools_ScatterPlot .......................................................................... 321
StatTools_Stack.................................................................................... 322
StatTools_TimeSeriesGraph............................................................... 323
StatTools_Transform........................................................................... 324
StatTools_Unstack............................................................................... 325
StatTools_WilcoxonRankTest ............................................................ 326

x
Contents xi
Introduction
An Overview to Automating StatTools
StatTools is a Microsoft Excel statistics add-in that allows you to
calculate statistics on data in Excel worksheets. Along with standard
toolbars and menus for user control, StatTools includes a complete,
object-oriented, programming interface. Using this interface, custom
statistical procedures may be added to StatTools using Excel's built-in
VBA programming language. These procedures can utilize StatTools'
built-in data management, charting and reporting tools, all accessible
via StatTools custom controls, functions and methods. Custom
procedures can even be displayed on the StatTools menu for easy
access.
The StatTools programming interface also allows you to write macros in
VBA that control existing "built-in" StatTools analyses. This is useful
for automating repetitive analyses and reports.
Each of these StatTools automation capabilities -
1) Creating Your Own Custom Analyses
2) Controlling Existing StatTools Analyses
are briefly discussed here.

Creation of Custom Analyses

The first type of automation allows you to create your own custom
analyses that integrate seamlessly with the main StatTools interface. Is
there a new statistical procedure that you really wish StatTools had?
Why not write one? StatTools has a large array of public objects,
methods, and properties to support this sort of development.
Most of the sections of this document are relevant for the creation of
custom analyses. To get started quickly with this, you can skip directly
to the section of this manual titled Creating a Custom Analysis for
StatTools.

Introduction 1
Automation of Existing Analyses
The second type of automation allows you to control existing analyses.
For example, you might want to take a particular data set and create a
composite report by automating a series of calls to different analyses,
and then applying custom formatting or adding additional calculations
to the output.
Not all analysis packs will support this sort of automation. The
analyses that are built into StatTools itself, the so-called “core analysis
pack” do support automation. See the section Automating the
StatTools Core Analysis Pack of this document for more information.
Custom analysis packs that you write yourself can be configured to
support 3rd party automation, but this document does not cover how to
implement that functionality. Contact Palisade Corporation for more
information on automating custom analysis packs.

2 An Overview to Automating StatTools

The Automation Components
There are three components that support StatTools automation, each
with a different function.

The StatTools Object Library (StatToolsOL.DLL)

This is the main automation library. Regardless of the type of
automation you are performing, you will need to make a reference to
this library. To create this reference, open up your VBA project and
bring up the References dialog (on the Tools menu):

Make sure the item Palisade StatTools 5.0 Object Library is checked in
this list.
Once your VBA project has referenced this object, immediately you
have access to StatTools methods, objects, and properties via the global
StatTools object. As a simple example, you can get the number of
analyses installed with StatTools with the code:
numAnalyses = StatTools.Analyses.Count
The three sections of this document 1) Packs, Categories, and Analyses,
2) Data Sets, Variables, and Variable Lists, and 3) Reports, Tables,
and Charts discuss the most important objects in this library and how
to use them. The section StatTools Object Library Reference contains
a list of the library’s objects, methods, and properties.

Introduction 3
The StatTools Controls Library (STControls5.OCX)
This component is only use in the development of your own analyses.
It provides two custom controls to help you implement your analysis’
own dialog.
To use these controls in Excel, you must add them to the list of VBA’s
Additional Controls. To do this, bring up an Excel UserForm window
in VBA, and choose the Tools menu’s Additional Controls menu item.
Then select the STControls5.STControlsOptionPanel and
STControls5.STControlsVarSelector items:

After doing so, the Excel VBA Toolbox window should have two new
controls added:

The first of these is the STControlsVarSelector control. The second, is

the STControlsOptionPanel control. They can now be added to your
Excel UserForms.

4 The Automation Components

 Note: Unlike the StatTools Object Library, the STControls do not need
to be added to each VBA project. Once you had added the controls to
Excel’s list of “Additional Controls,” they will be there for all VBA
projects.

See the section Using the STControls OCX of this document for more
information on setting up and using these controls. The section
“STControls OCX Library Reference” contains a list of all of the objects,
methods, and properties of the controls.

The StatTools Core Pack Automation Library

(StatToolsCoreAL5.DLL)
This component allows you to control StatTools built-in core analysis
pack. The core analysis pack ships with every copy of StatTools and
includes the statistical analyses built into StatTools. You should not use
this component if you are developing your own custom analyses.
To create a reference to this library, open up your VBA project and
bring up the “References” dialog (on the Tools menu):

Make sure the item Palisade StatTools 5.0 Core Pack Automation
Library is checked.
The section Automating the StatTools Core Analysis Pack of this
document gives a general overview of how this library can be used,
while the section StatTools Core Analysis Pack Automation Reference
contains a list of all of its objects, methods, and properties.

Introduction 5
Packs, Categories, and Analyses
To understand the expansion capabilities of StatTools, it is important to
first master the basic concepts of “analyses”, “analysis categories”, and
“analysis packs.” The sections of this document Creating a Custom
Analysis for StatTools and Creating and Distributing Analysis Packs
cover how to create your own analyses and analysis packs.

Terminology
Each individual StatTools procedure that you can run is called an
analysis. An analysis consists of an Excel add-in (.xla) file that
implements a dialog, and a specific set of public subroutines and
functions for calculating results and displaying StatTools reports. For
example, the One Variable Summary procedure that ships with
StatTools is one analysis, in the file StatToolsOneVarSummary.xla.
Each analysis belongs to a single “analysis category.” An analysis
category is a collection of analyses that appear under a single menu and
icon in the StatTools interface. For example, the category Normality
Tests is a built-in analysis category. Your custom add-ins may be
added to new categories that you create, or be added to the built in
categories.
An analysis pack is a collection of analyses and categories which is
distributed as a unit. One pack, the “core” analysis pack, with a large
number of built-in categories and analyses, ships with every copy of
StatTools. Additional packs may be purchased from Palisade
Corporation. StatTools makes it easy to make your own packs as well,
as described later in this section.

6 Packs, Categories, and Analyses

 Automation Objects
There are three automation objects (and three corresponding collection
objects) for querying and manipulating analysis packs, analysis
categories, and analyses.
StatToolsAnalysi There is one StatToolsAnalysisPack object for each analysis pack loaded
sPack and in StatTools. The collection of analyses and analysis categories
StatToolsAnalysi belonging to this pack is available via the Analyses and
sPacks Objects AnalysisCategories properties.
The entire collection of analysis packs, represented by the
StatToolsAnalysisPacks object, can be accessed via the AnalysisPacks
property of the root StatTools object. So, for example, to walk through
every analysis pack, printing their names to the screen, you could use
the code:
Dim onePack as StatToolsAnalysisPack
For Each onePack in StatTools.AnalysisPacks
MsgBox onePack.Name
Next
StatToolsAnalysi There is one StatToolsAnalysisCategory object created for each analysis
sCategory and category loaded in StatTools. The pack that the category belongs to can
StatToolsAnalysi be accessed via the object’s AnalysisPack property. A list of the analyses
sCategories belonging to this analysis category is available via the object’s Analyses
Object property.
The entire collection of analysis categories, represented by the
StatToolsAnalysisCategories object, can be accessed via the
AnalysisCategories property of the root StatTools object. In addition each
StatToolsAnalysisPack object contains a similarly named property which
returns a collection containing only the categories belonging to the
specific pack. So, for example, to walk through a list of analysis
categories in StatTools, printing their names to the screen, you could
use the code:
Dim oneCategory as StatToolsAnalysisPack
‘This displays the list of all categories loaded in StatTools:
For Each oneCategory in StatTools.AnalysisCategories
MsgBox oneCategory.Name
Next
‘This limits the display to only the categories in the pack named “MyPack”:
For Each oneCategory in StatTools.AnalysisPacks(“MyPack”).AnalysisCategories
MsgBox oneCategory.Name

Introduction 7
 Next

The StatToolsAnalysis and StatToolsAnalyses Objects

There is one StatToolsAnalysis object created for each analysis loaded in
StatTools. The analysis pack and analysis category that the analysis
belongs to can be accessed via the AnalysisPack and AnalysisCategory
properties of the object.
The entire collection of analyses, represented by the StatToolsAnalyses
object, can be accessed via the Analyses property of the root StatTools
object. In addition each StatToolsAnalysisPack and
StatToolsAnalysisCategory object contains a similarly named property
which returns a collection containing only the analyses belonging to
that analysis pack or analysis category.

8 Packs, Categories, and Analyses

Data Sets, Variables, and Variable Lists
StatTools requires users to organize their data into “variables” and
“data sets.” There are several objects, and a large number of methods
and properties that allow you to create, manipulate, and destroy data
sets and variables.

Terminology
This document assumes you are already comfortable with the concepts
of data sets and variables in StatTools, and this section serves only as a
brief review of those concepts.
A “variable” is a collection of spreadsheet cells that contain data
entered by the user. Typically a variable is a single column of a
spreadsheet, although they can be arranged row-wise, or extended to
multiple rows or columns using a multiple-range data set. A data set is
a collection of variables which are adjacent to one another in the
spreadsheet and each have the same number of cells.

Automation Objects
There are five StatTools automation objects used to control StatTools
data sets and variables.
The StatToolsDataSets collection object, accessible using the DataSets
property of the StatTools root object, contains a list of all data sets in the
currently scanned workbook. You can use the Scan method of this
object to scan a workbook manually. See the Scanning Workbooks
section later in this document for more information about scanning.
The Add and AddMulti methods of this object allow you to create new
data sets. See the section Creating New Data Sets and Variables
section later in this document for more information.
There is one StatToolsDataSet object, a child of the data sets collection
described above, for each data set in the currently scanned workbook.
The Variables property of this object returns a StatToolsVariables
collection object, containing one StatToolsVariable object for each
variable in the data set.

Introduction 9
 The StatToolsVariables collection object is a child of a StatToolsDataSet
object and contains a list of StatToolsVariable objects. There is one such
object for each variable in the data set. Using this object, you can insert
new variables into an existing data set, or return information about how
the variables are arranged in that data set.
The StatToolsVariableList collection object also contains a set of
StatToolsVariable objects, but in this case the members of the collection
are arbitrary. A variable list object provides a convenient object for
grouping and manipulating an arbitrary collection of variables.
Finally, the StatToolsVariable object represents a variable. This can be
either be a real, “unstacked” variable (one that has a data set as a
parent) or a virtual, “stacked” variable. See the section Stacked and
Unstacked variables later in this document for more information.

Scanning Workbooks
When automating StatTools, it is important to understand how
StatTools keeps track of the data sets and variables in your workbook
models. The DataSets property of the root StatTools object gives you
access to a StatToolsDataSets collection object. But that list will be
empty until an Excel workbook is “scanned.”
The scanning process consists of StatTools going though an Excel
workbook (only one workbook may be scanned at any one time) and
identifying all the data sets and variables in the model. StatTools then
constructs the appropriate StatToolsDataSet, StatToolsVariables, and
StatToolsVariable objects, all accessible via the data sets collection object.
In some cases the scanned model can become out of sync with the Excel
model. For example, if you have scanned a workbook for data sets and
variables, and then you insert a column into a data set. The new
variable in the middle of that column will not be in the list of variable
objects for that data set until you rescan the workbook. Thus, often you
will want to rescan whatever workbook you are using if you have
changed the spreadsheet in this sort of way, or if you have given control
to the user who might have done such an operation.
Since there can only be one currently scanned workbook at any one
time, you will need to run a scan every time you switch between
workbooks.

10 Data Sets, Variables, and Variable Lists

 Scanning may be done manually via the Scan method of the
StatToolsDataSets collection object. The currently scanned workbook
can be retrieved from the ScannedWorkbook property of the same
object. Some StatTools methods will automatically cause a scan of a
workbook, or in many cases a rescan of the currently scanned
workbook. These functions are:
o Run (StatToolsAnalysis Object)
o Add (StatToolsDataSets Object)
o AddMulti (StatToolsDataSets Object)
o DeleteAll (StatToolsDataSets Object)
o ShowDataSetManager (StatToolsDataSets Object)

Stacked and Unstacked Variables

There are two types of StatToolsVariable objects. The first type consists
of variables that actually exist in an Excel workbook. These “real”
variables belong to a specific data set’s collection of variables, and are
often called unstacked to distinguish them from their stacked
counterparts, described below. You can only create new unstacked
variables by either creating new data sets or by inserting new variables
into existing data sets.
The second type of StatToolsVariable objects are the so-called stacked
variables constructed from two “real” source variables, one category
variable and one value variable, in addition to a single category name.
Stacked variables are “virtual” variables in the sense that there is not a
corresponding range in Excel for the variable. You can create new
stacked variables by calling the NewStackedVariable or
NewStackedVariableList methods of the root StatTools object. Once you
have created a stacked variable, you may use most of its other
properties and methods, and in general treat it as if it were a “real”
variable.

Introduction 11
Stacked Here’s an example of how to use a stacked variable object. Imagine
Variable there are two columns of data in Excel as follows:
Example

Gender Weight
Male 200
Female 120
Female 130
Male 190
Male 185
Female 120
Female 135
Male 210
Male 175
Female 115
If you want to perform an analysis of all the men in the data set, you
can construct a stacked variable with the following code:
Set sourceCatVar = sourceDataSet.Variables(1)
Set sourceValVar = sourceDataSet.Variables(2)
Set stackedVar = StatTools.NewStackedVariable(sourceValVar, sourceCatVar,
“Male”)
Now the new variable stackedVar can, for most purposes, be treated as
any other StatToolsVariable object. So for example, you could write the
following code to retrieve the mean and standard deviation of all the
men in the data set.
myMean = stackedVar.Mean
myStdDev = stackedVar.StdDev
If you want to get a list of stacked variables, one for each category in the
source category variable, you can use the NewVariableList method:
Set sourceCatVar = sourceDataSet.Variables(1)
Set sourceValVar = sourceDataSet.Variables(2)
Set stackedVarList = StatTools.NewStackedVariableList(sourceValVar,
sourceCatVar, 100)
Now stackedVarList is a StatToolsVariableList object filled containing
two stacked variables, one for males and one for females. The last
argument of the NewStackedVariableList method is the maximum

12 Data Sets, Variables, and Variable Lists

 number of variables you want to construct. This is useful to limit the
size of the collection.
There are a number of properties and method of the StatToolsVariable
object which are useful for retrieving information about category
variables. Note: These are properties that are applied to an unstacked
category variables (e.g. the Gender column in the example above) and
not to an already “stacked” variable. These properties and methods are:
o CountCategories
o CountCategoryOccurrences
o CheckCategoryHeuristic
o GetCategoryNames
o GetCategoryOccurrences

Introduction 13
Creating New Data Sets and Variables
The previous section discussed how to create new stacked variables. To
create new unstacked variables, however, you must either create a new
data set or insert variables into an existing data set.
Creating New To create an entirely new data set, use the Add or AddMulti methods of
Data Sets the StatToolsDataSets collection object. The former method should be
used for data sets consisting of a single Excel range, while the latter for
multiple range data sets. Here’s an example of how you could add the
range A1:F50 as a new data set, with six variables (one per column) and
with the first row reserved for the variable names:
StatTools.DataSets.Add(ActiveSheet.Range(“A1:F50”,
StatToolsVariableLayoutColumns, TRUE)
When you create a new data set using either the Add or AddMulti
methods, usually you will let StatTools automatically “attach” it to the
workbook for you. The attaching process writes the data set
information into the workbook, sets up any defined names for the data
set’s variables, and (if specified) formats the data set’s range. If,
however, after you create the data set, you need to make a large number
of modifications to the variables of the data set, you may want to attach
it manually after you have made these changes. This prevents a large
amount of reading and writing of information from Excel and will
speed the process of creating a new data set. See the description of the
Add method of the StatToolsDataSets collection object for more
information.
Inserting New To insert a variable into an existing data set, you can use the Insert
Variables into method of the StatToolsVariables collection object. Keep in mind, that
an Existing Data this process inserts rows or columns into the Excel spreadsheet and
Set might have unintended consequences. To check if there is enough room
to insert one or more variables without actually inserting anything, call
the InsertValidate method of the same object. For example, the following
code checks if there is enough room to insert three variables at the end
of a data set and, if so, to actually insert them:
If Not theDataSet.Variables.InsertValidate(3) Then
MsgBox “Couldn’t insert variables.”
Else
For I = 1 to 3
theDataSet.Insert(“var #” & I)
Next i
End If

14 Data Sets, Variables, and Variable Lists

Creating There is one other advanced technique, which allows you to create a
“Utility” new “utility” variable. A utility variable is a variable created by the
Variables transformation of one or more other existing variables in a data set.
These variables are either placed to the right of the existing variables in
the data set, or alternatively in a completely new data set on a new
worksheet. This is generally determined by the
UtilityNewVariablePreference property of the StatToolsSettings object, but
this setting can be overridden in some circumstances. See the
CreateUtilityVariables and CreateUtilityVariablesValidate methods of the
StatToolsDataSet object for more information.

Selecting Variables in Dialogs

In your own analyses, most likely you will want to provide a method
for users to select one or more variables for your add-in to analyze.
StatTools provides a control, the STControlsVarSelector control for just
this purpose. See the section Using the STControls OCX later in the
document for more information.

Introduction 15
Reports, Tables, and Charts
Your custom analyses will typically create new StatTools reports and
then fill them with one or more tables and charts. StatTools provides
several objects and dozens of useful methods and properties for you to
do this in a quick and consistent manner.

Reports Objects
When your analysis needs to generate output information (usually in
the form of tables or charts) to an Excel spreadsheet, you should create a
StatToolsReport object. This object will find a destination location of the
size (number of rows and columns) you specify, as well as create any
new worksheets and header ranges. It also provides a utility for
“finalizing” the report, as discussed below.
Creating a To create a report object, use the NewReport method of the root StatTools
StatToolsReport object. StatTools will:
Object
1) Examine the current settings to determine where the report
should be placed (in a new worksheet or workbook, etc)
2) Appropriately format the report range, and
3) Generate a new StatToolsReport object.
For reports that should be put in new worksheets, the method will
create the new worksheet, name it, and put a report “header” at the top
of the report.
For complicated reasons, and unlike most other StatTools methods,
when you create a StatToolsReport object using the NewReport method of
the root StatTools object, and it fails (because the requested report size is
too large to fit in the destination location, or the user cancelled the
operation, or some other exceptional condition) it will not raise an error
to the calling application. Instead it will still create StatToolsReport
object, but will set the Result property of that object to an non-zero error
code. Thus, after you create a new StatToolsReport object, but before
you use it, you should always check the Result code for a non-zero
value. Typically in your custom analyses, you will simply return this
result back to the StatTools function that called your routine.

16 Reports, Tables, and Charts

 There are two properties of the report object that return Excel ranges.
The
ReportRange The ReportRange property returns the destination range where you may
and write your analysis’ output. This range will have the size (number of
HeaderRange rows and columns) that you requested. The HeaderRange property,
Properties which will only be set if the destination range of the report was placed
on a new Excel worksheet, contains a range at the top of the new
worksheet with summary information about the report, when it was
created, and what analysis was being run.
The Finalize The Finalize method of the StatToolsReport object provides a useful
Method utility for performing some standard formatting on a report which you
have finished writing. It performs three main actions. First, if the
report generated is a “static” report, it will scan through the report
range and replace all spreadsheet functions in the range with fixed
values. Second, it will resize column widths so the contents of the
report cells are visible. Third, it will scroll the active window’s view so
that the upper-left corner of the report will be visible to the user. See
the description of the Finalize method for more information.
An Example Here’s a fairly typical example of how your code can create a new
report object, use it, and finalize it:
‘Create a report of size 20x20 (assuming the name of this analysis is
MyAnalysis)
With StatTools.NewReport(20,20, “MyAnalysis”)
‘Check the return code:
If .Result <> 0 Then Goto Fail

‘Retrieve the report range:

Set destRange = StatTools.ReportRange

‘…Fill in destRange here with tables and charts or whatever…

.Finalize
End With

Introduction 17
Table Objects
Most of your numeric results should be placed in standard StatTools
style tables. StatTools makes this process easy by providing the
StatToolsTable object.
Creating a To create a table object call the NewTable method of the StatTools root
StatToolsTable object. You pass as arguments to this method the upper-left cell of the
Object table’s destination, as well as the size of the table (the number of interior
table rows and columns.) This method then constructs a table, with
default StatTools formatting, of the specified size and at the specified
location, and returns a new StatToolsTable object which you can then
proceed to use.
The Parts of a Each table has four parts. The “signature” range of the table consists of
Table two cells in the upper-left corner of the table where a small description
of the table is placed. There are two “header” ranges, one on the left
and one of the top of the table where descriptions of the rows and
columns of the table may be placed. Finally, the “interior” range of the
table is the area where your output result may be placed. These ranges
can be accessed via the SignatureRange, HeaderRange, and InteriorRange
properties of the table object. To get the entire table range use the
TableRange property.
Adding Header To add headers to your tables, you can always get the header ranges
Text and write to the header cells directly. However, the table object
provides several methods for efficiently writing text to the headers. The
AddHeaderText and AddHeaderTallText can be used to write arbitrary text
to the headers. The AddHeaderVariable and AddHeaderVariableList
methods are useful for writing the names of variables to the headers.
Adding Table The table object provides two methods for adding pop-up comments to
Comments tables. The AddCustomComment method allows you to add a comment
containing arbitrary text. The AddStandardComment method adds a
comment with predefined text. Comments fall in two categories. The
“Notes and Warnings” category includes comments that are general in
nature, and which we you want all users of the product, at least at first,
to read. These comments are shown, by default, when reports are
generated unless the user specifically turns them off. The second
category has “Educational Comments” which serve as learning aids for
students using StatTools in a classroom environment. These comments
are, by default, not shown, unless they are turned on by the user. When
you create a comment using the AddCustomComment method, you must
specify if it is in the “Notes and Warnings” category or the “Educational
Comments” category.

18 Reports, Tables, and Charts

An Example
Here’s an example of creating a table object:

‘Create a table with 5 rows and 2 columns.

With StatTools.NewTable(5, 2, “MyTable”)

‘Write the top header

.AddHeaderText(StatToolsHeaderTop, 1, “Top”, “Left”, “Right”

‘Write the left header

.AddHeaderText(StatToolsHeaderLeft, 1, “”, “A”, “B”, “C”, “D”, “E”

‘Fill in the interior of the table (here with nonsensical information):

With .InteriorRange
For r = 1 to 5
For c = 1 to 2
.Cells(r,c).Value = r * c
Next c
Next r
End With

‘Add a custom comment to the upper left corner of the table:

AddCustomComment 0, 0, FALSE, “Cell values contain row number
times column number.”

End With

Introduction 19
Chart Objects
You are free to create an Excel chart object using normal Excel VBA
commands. However, StatTools provides a wrapper object, the
StatToolsChart object, which make it easy to make charts that have a
consistent look and feel.
Creating as To create a new chart call the NewChart method of the StatTools root
StatToolsChart object. You pass as an arguments to this method the cell where the
Object upper-left corner of the chart should be placed, the type of the chart,
and the graph’s data source. The method will create an Excel
ChartObject in the specified location, configured with the default
StatTools formatting, and returns a StatToolsChart object.
Customizing the Once the chart is created, you can customize the chart in two ways.
Chart First, you can always access the underlying Excel chart object using the
Chart property of the StatToolsChart object. Then you can modify the
chart as you would any other Excel chart object. But in addition, there
are a number of methods of the StatToolsChartObject for adding chart
elements which are formatted in a standard StatTools manner. To add
axes, legends, and a title to your chart, use the AddCategoryXAxis,
AddValueXAxis, or AddValueYAxis, AddLegend, and AddTitle methods.

Live vs. Static Results

In StatTool’s Settings dialog, the user can specify the updating
preference for reports. The choices are “live” or “static.” This setting is
stored in the StatToolsSettings object’s ReportLiveUpdatingPreferred
property. Live reports use functions to generate results, and those
results change as the user changes the source data. Static reports have
results do not contain functions, and that don’t change as the user
changes the source data. The default setting is live.
It is important to note, however, that this setting is just a preference.
Where possible, you should write analyses that can generate both live
and static reports. In some cases, however, it is impossible or
impractical to support the generation of live reports. In those cases, you
will need to override the default ReportUpdating argument of the
NewReport method when you create your report. In some cases, it is
easy to make a report have live updating, but difficult to maintain its
link to the original source data. In that case, pass the value
StatToolsReportUpdatingLiveButNotLinked to the ReportUpdating
argument.

20 Reports, Tables, and Charts

 Also note, that analyses classified as utilities (that is, analysis that create
new variables out of transformations of already existing variables) do
not respect the ReportLiveUpdatingPreferred property. Instead the use
the UtilityLiveUpdatingPreferred property. Typically, utilities will be
static while reports will be live, which are the default StatTools settings.
It is the responsibility of your analysis to support live and static report
generation if possible. One way to accomplish this would be to have
two different sets of code in your analysis. One that writes formulas
into the report cells and one that calculates the result internally, and
writes the static results into the report cells. However, for many cases,
the Finalize method of the StatToolsReport object provides a better
alternative. This method, if the report is static, will look through all
spreadsheet cells and replace the functions in those cells with the
equivalent calculated value. Thus an easy way to write a report that
support both live and static updating is to always write it in a live
format (with formulas) and then rely on the Finalize method to convert
it to a static report for you when appropriate.

Introduction 21
22 Reports, Tables, and Charts
Creating a Custom Analysis for
StatTools
Building an Analysis
Introduction
A StatTools custom analysis is a new statistical procedure which you
wish to add to StatTools. A custom analysis can utilize StatTools' built-
in data management, charting and reporting tools and can even be
displayed on the StatTools menu for easy access. Example custom
analyses are the three non-parametric tests that are available from
Palisade.
Creating your own custom analysis for StatTools is a relatively
straightforward process:
1) First, you must create an add-in (.xla) file and add a reference
to the main StatTools Object Library (StatToolsOL.DLL) file.
2) Second, you should create a defined type and a global variable
of that type to represent the “state” of your add-in.
3) Third, you must implement a small number of public
subroutines that perform certain standard functions, such as
reading default values, putting up an analysis dialog, and so
on.
4) Finally, you must place that analysis in a destination where
StatTools can find it and add it to your copy of StatTools.
An example add-in, Template.xls, is in the Developer Kit sub-folder of
the folder with example spreadsheets (accessible through the Help >
Example Spreadsheets command). We recommend you use this
template as a starting point for your analysis development efforts.
Many of the steps described below will already be accomplished if you
use the template.

Creating a Custom Analysis for StatTools 23

Creating an Add-in File
We assume you know how to create Excel .xls and .xla files using the
Visual Basic for Applications (VBA) language built into Excel.
The first step in creating a custom StatTools analysis is to create an
Excel .xls file. Give it a unique name, since StatTools requires all add-in
files to have different names (if this were not the case, StatTools would
not necessarily be able to simultaneously load all the add-ins that it
might need.)
We recommend you start with the file Template.xls in the Developer
Kit sub-folder of the folder with example spreadsheets (accessible
through the Help > Example Spreadsheets command). It contains a
"shell" that will make it easier to structure your add-in.

Creating a Reference to the StatTools Object Library

Now, in your .xls file, you must create a reference to the main StatTools
object library before you can use any StatTools functionality. If you are
using the Template.xls file as a starting point for your analysis
development, this step should already be done for you.
To create this reference, open up your VBA project and bring up the
References dialog (on the Tools menu):

Make sure the item Palisade StatTools 5.0 Object Library is checked in
this list.

24 Building an Analysis
Running Your Custom Analysis
To run a custom analysis one needs to write appropriate VBA code that
will be executed when the user clicks a button or selects a menu item
(with the button or menu created by the VBA programmer). The
example Running Custom Analysis.xls (accessible through the Help >
Example Spreadsheets command) demonstrates how to do that using a
custom button.
For example, the following code will run custom analysis named
"Template":

Dim theAnalysis As StatToolsAnalysis

Set theAnalysis = StatTools.Analyses("Template")
theAnalysis.Run
Note that for this code to run, a reference to the StatTools object library
must added. To do that in the VBA editor select References on the
Tools menu, and then select "Palisade StatTools 5.0 Object Library".

Creating a Custom Analysis for StatTools 25

Creating a Defined Type and Global State Variable
The next step in creating your custom add-in is to create a defined type
and global “state” variable for your analysis. In addition, you should
define constants for any enumerated values your analysis requires.
The type variable is a structure which can store the exact state of the
analysis’ operation. Usually, this type will almost exactly match the
options available to the user in the analysis dialog. The global “state
variable” is simply a global variable of this new defined type.
As a concrete example, here is the defined type and state variable
declarations for the Chi-Square Normality Test analysis, which is part
of the built-in core analysis pack:
Public Type ChiSqTestType
VariableList As New StatToolsVariableList
BinMinimum As Double
BinMaximum As Double
NumBins As Integer
ExtendFirstBinToMinusInfinity As Boolean
ExtendLastBinToInfinity As Boolean
End Type

Public analysisInfo as ChiSqTestType

Notice how this structure matches up, item for item, with the dialog box
for that analysis.

26 Building an Analysis
 The VariableList member of the type keeps track of what variables are
selected in the variable selector at the top of the dialog. The
BinMinimum, BinMaximum, and NumBins members keep track of the
like-named items in the dialog (There are special constant values – not
shown here - for the “auto” options for each of these.) And the
ExtendFirstBinToMinusInfinity and ExtendLastBinToInfinity Boolean
members correspond to the check boxes.
The global variable analysisInfo contains the current “state” of the
analysis. For example, after the user dismisses the analysis’ dialog, the
global state variable will contain the choices that were made there. Or,
when StatTools asks you to store the current settings as defaults, the
setting you store should come from that variable.

The Required Public Subroutines

There are four public functions that your add-in must provide in order
to satisfy the requirements of StatTools: Validate, Defaults, ShowDialog,
and GenerateReport. Each of these functions will perform a very specific
action, either relying on, or changing the current state of the global
“state” variable of the analysis. These four functions are each described
below.
Validate Each analysis add-in must provide a Validate function, with the
prototype:
Public Function Validate(validationMode As StatToolsValidationMode) As
StatToolsResult
This is the easiest function for your analysis to support. In most cases,
you should simply make this function return the value
StatToolsResultOK.
Your custom analysis will typically have its own dialog. And when the
user presses the OK button of this dialog, you will validate the settings
entered there before changing the analysis’ global state variable to
reflect the user’s choices. Usually, this is the only validation that your
analysis needs to perform, and the public Validate function needs to do
nothing except return the value StatToolsResultOK.
The Validate function can be used in two circumstances, which you
likely will rarely or never need. First, in some circumstances you may
need to add some additional validation of the analysis’s state variable
before the analysis dialog is put up, before analysis defaults are written,
or after a dialog is dismissed but before any reports are written.
Second, if you want external users to be able to automate your analysis

Creating a Custom Analysis for StatTools 27

 via VBA (like you can manipulate StatTool’s built in analysis pack using
the Core Automation Library) where the normal analysis dialog might
be entirely bypassed, you will need to write code that validates the
analysis’s state.
There is a single parameter which is passed to this function, the
validationMode. It is one of the three enumerated values:
o StatToolsValidationModeWriteDefaults – the Validate function will
only ever be called in this mode if your analysis is being
controlled by VBA, and if the user has requested the current
global state be written to a workbook or to the global defaults.
This give you the opportunity to confirm that the settings about
to be written are a legal set of default values.
o StatToolsValidationModeShowDialog – the Validate function is
called in this mode just before StatTools calls the ShowDialog
function. It gives you the opportunity to ensure that the current
global state of the analysis is capable of being displayed in your
dialog.
o StatToolsValidationModeGenerateReport – the Validate function is
called in this mode just before StatTools calls the GenerateReport
function. It gives you the opportunity to ensure that the current
global state of the analysis can be used to generate a report.
The return value of the function is StatToolsResultOK if validation
passed, or one of the many other StatToolsResult result codes for an
error value. See the object browser for a list of available result codes.

28 Building an Analysis
Defaults Each analysis add-in must provide a Defaults function, with the
prototype:
Public Function Defaults(writeDefaults As Boolean, wbContext As Workbook)
As StatToolsResult
This function is called when StatTools either wants to write the current
global state of your analysis as the default, or alternatively, if it wants to
set the global state of the analysis to the default values.
Analysis defaults determine what values are put into the global state
variable when the analysis is first initialized. There are two levels of
these defaults. First, the currently active workbook may have defaults
for an analysis stored within it. These values are written whenever an
analysis dialog is dismissed with a click of the OK button. This allows
those same settings to reappear when the analysis is again used for the
same workbook. Second, there is a set of global defaults, stored in the
system registry, which are used when the analysis dialog is displayed in
the context of a workbook that doesn’t have any workbook level
defaults. These global defaults are written when the user clicks the
Save as Defaults icon in an analysis dialog.
The first argument to the function is writeDefaults. If TRUE, defaults are
being written from the global state into a workbook or the global
defaults. If FALSE, defaults are being read from the workbook or
global defaults into the global state. Usually, you simply pass this
argument back into individual default functions you call in this routine,
as you’ll see in the example at the end of this section.
The second argument to the function is the wbContext. If this is Nothing
the default is being read from or written to the global defaults. If this is
set to a specific workbook, the defaults are being read from or written to
that specific workbook. Note some items can only be written to a
workbook. For example, you can not write a specific variable object as a
global default, since that object has no meaning outside the current
workbook. For convenience, you can still call the default functions in
these cases, but no values will be written, and empty object variables
will always be returned.

Creating a Custom Analysis for StatTools 29

 You should return StatToolsResultOK if the function is run successfully,
or an non-zero StatToolsResult code if there is a failure.
It is usually quite easy to support the Default function. You need to get
the analysis object for your analysis, and then call one of the five
methods available for writing a default for each member of your
analysis’s defined type. The routines that are available (all members of
the StatToolsAnalysis Object) are:
o Default – for Boolean, Integer, Long, Double, or String values (or
arrays of those values.)
o DefaultDataSet – for a default StatToolsDataSet Object
(workbook level only.)
o DefaultRange – for a default Excel Range Object (workbook-level
only.)
o DefaultVariable – for a default StatToolsVariable Object
(workbook-level only.)
o DefaultVariableList – for a default StatToolsVariableList Object
(workbook-level only.)
As a concrete example, return to the Chi-Square Normality Test
analysis, discussed earlier. The Defaults method of this analysis look
like this:

Public Function Defaults(writeDefaults As Boolean, wbContext As Workbook) as StatToolsResult

Dim anObj As StatToolsAnalysis
Set anObj = StatTools.Analyses(“ChiSqTest”)
'Write or read the defaults:
With analysisInfo
anObj.DefaultVariableList writeDefaults, wbContext, "VariableList", .VariableList
anObj.Default writeDefaults, wbContext, "NumBins", .NumBins,
StatToolsAutoNumBins
anObj.Default writeDefaults, wbContext, "NumBins", .NumBins,
StatToolsAutoNumBins
anObj.Default writeDefaults, wbContext, "BinMinimum", .BinMinimum,
StatToolsAutoBinMinimum
anObj.Default writeDefaults, wbContext, "BinMaximum", .BinMaximum,
StatToolsAutoBinMaximum
anObj.Default writeDefaults, wbContext, "ExtendFirstBinToMinusInfinity",
.ExtendFirstBinToMinusInfinity, True
anObj.Default writeDefaults, wbContext, "ExtendLastBinToInfinity" ,
.ExtendLastBinToInfinity, True
End With
Defaults = StatToolsResultOK
End Function

30 Building an Analysis
ShowDialog Each analysis must provide a ShowDialog function with the following
prototype:
Public Function ShowDialog() As StatToolsResult
This function show display your analysis’s custom dialog. Make sure to
always show the dialog modally. If you show the dialog modelessly,
StatTools will crash. The return value should be StatToolsResultOK if
the dialog’s OK button is pressed, or StatToolsResultActionCancelled if
the dialog’s Cancel button was pressed.
What goes into your dialog is up to you, but we recommend you follow
the basic design of the dialog in the Template.xls add-in. StatTools has
two custom controls to aid your dialog development. The section
Using the STControls OCX of this document discusses how to set up
and use these controls.
GenerateReport Each analysis add-in must provide a GenerateReport function, with the
prototype:
Public Function GenerateReport() As StatToolsResult
This function is called when StatTools wants you to generate your
analysis’ report using the current global state.
How you implement the GenerateReport function is up to you, but here
is a general outline of the sequence you will most likely want to follow:
1) Based on the current global state, determine how large a report
(number of rows and columns) you will need.
2) Call the NewReport method of the root StatTools object to create
a new StatToolsReport object, being sure to check the .Result
property of this object before proceeding to use it.
3) Use the .ReportRange property of the StatToolsReport object as
the destination range for your analysis’ report, filling it in with
whatever charts, tables, and numeric results are necessary.
4) Optionally, call the .Finalize method of the StatToolsReport
object. The method provides a convenient method for
converting a live report into a static one, and also for resizing
the columns of your report to be able to display the result.
In code, this sequence would be something like this:
Public Function GenerateReport() as StatToolsResult
Dim rc as StatToolsResult
Dim numRows as Long
Dim numColumns as Long

Creating a Custom Analysis for StatTools 31

 'Determine the report size and region:
rc = DetermineReportSize(numRows, numColumns): If rc <> 0 Then GoTo fail

With StatTools.NewReport(numRows, numColumns, ANALYSIS_NAME)

rc = .Result: If rc <> 0 Then GoTo fail
rc = CreateReport(.ReportRange): If rc <> 0 Then GoTo fail
.FinalizeReport
End With

fail:
GenerateReport = rc
End Function

Of course, in the above example the implementation of the

DetermineReportSize and CreateReport function are up to you to write.

Compiling and Saving the New Analysis

To make an analysis you have written callable from StatTools, you need
to “compile” it into an .xla file and then put this .xla file it into a
location where StatTools can find it.
It is easy to compile your .xls file into a .xla add-in file. Just choose the
Save As method of Excel, and make sure to save the file as an .xla type.
To make the add-in callable from StatTools, you must create an analysis
pack. This can be done very simply by creating a new subdirectory in
the \StatTools\Analyses directory structure. See the following section,
Creating and Distributing Analysis Packs for information on how to
do this.

32 Building an Analysis
Debugging Your Custom Analysis
While developing your analysis add-in, you will most likely want to
debug the .xls file, while having it be called by StatTools as if it were
already compiled. StatTools will normally not recognize .xls files as
analyses, but there is a way you can force StatTools to call the .xls file
you are working on instead of your analysis’ compiled add-in.
To do this, compile your .xla and place it in a directory where StatTools
can find it (as described in the section Creating and Distributing
Analysis Packs below.) After you launch the StatTools add-in,
manually open your analysis’ .xls file. When StatTools tries to run a
procedure in your analysis, and it sees that an .xls file with the same
name as the .xla file that it would normally run is there, it will call the
.xls code instead of the .xla code. It also will never dynamically try to
load or unload your add-in, which it normally would do for other .xla
files.
Thus you can now set breakpoints and other debugging information in
the .xls file.

Creating a Custom Analysis for StatTools 33

Creating Analysis Packs
Creating a Simple Custom Analysis Pack
It is simple to create a new StatTools analysis pack. Simply create a new
subdirectory of \StatTools\Analyses directory. The name of the
subdirectory will be the name of the pack. For example, to create a new
analysis pack called “NewPack,” you create the subdirectory
\STATTOOLS\ANALYSES\NEWPACK. This new pack will
automatically be shown in the StatTools interface.
By default the new pack will have a single analysis category with the
same name as the analysis pack. A default “custom” icon will appear
for this category in StatTools menu. This can be changed using a
configuration file, as discussed later in this section.
Any .xla files added to the new analysis pack subdirectory will
automatically be added as new analyses belonging to this pack. The
subject of how to actually create your own .xla files was discussed
earlier in this document. If you do not have a configuration file for the
pack (discussed below) each analysis will have the same name and
menu caption as the name of the add-in file (excluding the .xla
extension.) The analysis will be placed in the single default analysis
category, sorted in alphabetical order.

Customizing Packs with Configuration Files

As we’ve already discussed, when you create an analysis pack
following the steps in the previous section, StatTools automatically
creates a single analysis category (with the same name as the pack) and
adds any .xla files found in the pack’s subdirectory as new analyses
using default icons and menu captions. While this is fine for analyses
you are writing for your own use, if you plan on distributing your
analysis pack to others, you will most likely wish to customize the
appearance of the pack, including customizing the order, menu-
captions, and icons of the pack. To do this, you can create a
configuration file for the pack.
A configuration file is a file named CONFIG.INI residing in the pack’s
StatTools subdirectory. The file has a standard Windows initialization
(.INI) format, which is text file made up of a series of main bracketed [ ]
sections, each containing a sequence of text pairs connected by equal
signs.

34 Creating Analysis Packs

Configuration The general layout of the file is shown below:
File Layout
[PACK]
Priority =
Description =
HelpFile =
[CATEGORYn]
Name =
[ANALYSISn]
Name =
Category =
ReportDescription =
NewSheetTitle =
Utility =
RequiresVariables =
HelpContextID =
The [PACK] The [PACK] section appears at the top of the file and controls three
Section settings:
o Priority – A double value which initializes the otherwise read-
only Priority property of the StatToolsAnalysisPack object. The
pack’s priority is a number which determines which packs are
displayed first in the StatTools user interface. The lower the
pack’s priority, the earlier in the user interface it will be listed.
Ties are broken by alphabetical order. The built-in core analysis
pack will always have earlier priority than all other packs. It is
recommend you leave this item blank, unless you need to order
two or more of your own packs with respect to each other.
o Description – A string which initializes the otherwise read-only
Description property of the StatToolsAnalysisPack object. This
string describes the analysis pack, and appears in the header
range when an analysis in the pack creates a report.
o HelpFile – A string giving the name of the help file for this
analysis pack. The help file must be in .chm (compiled html
help) or .hlp format, and must exist in the analysis pack’s
subdirectory. See the following section Creating an Analysis
Pack Help File for more details about creating a help file for
your analysis.

Creating a Custom Analysis for StatTools 35

 Next comes one or more [CATEGORYn] sections, where n should be
The
[CATEGORYn] replaced by a number. The first category will have the header
Sections [CATEGORY1], the second [CATEGORY2], and so on for as many
categories as you want the pack to have. The entries under this section
are:
o Name – A string which initializes the otherwise read-only Name
property of the StatToolsAnalysisCategory object. This is the
“internal” name of the category. It is also the name that must
be used in the Category item of the [ANALYSISn] section to
place an analysis in this category.
o MenuCaption – A string which initializes the otherwise read-
only MenuCaption property of the StatToolsAnalysisCategory
object. This is the text that appears for this category in the
StatTools menu, and as the pop-up text for the category’s icon.
To add an accelerator key to a character of the menu caption,
add a “&” character before that character. (To display the
character ‘&’ itself, write two ‘&’ characters.) For example, to
have a caption “John & Mark’s Analysis Category” with the
“A” being the accelerator key, you would write the string “John
&& Mark’s &Analysis Category”.

36 Creating Analysis Packs

 Next comes one or more [ANALYSISn] sections, where n should be
The
[ANALYSISn] replaced by a number. The first analysis will have the header
Sections [ANALYSIS1], the second [ANALYSIS2], and so on for as many
analyses as the pack has. The entries under this section are:
o Name – The name of the analysis. This name must match the
name of the add-in (.xla) file excluding the .xla extension. Thus
if you have an add-in file named “MyAnalysis.xla” this name
must be “MyAnalysis”.
o Category – The category name which this analysis should be
added to. This can be a category defined earlier in this same
configuration file, or a category created by another analysis
pack (usually the core analysis pack.)
o ReportDescription – A string which initializes the otherwise
read-only ReportDescription property of the StatToolsAnalysis
object. This text sets descriptive text which appears in the
header region of a StatTools report for this analysis.
o NewSheetTitle – A string which initializes the otherwise read-
only NewSheetName property of the StatToolsAnalysis object.
This is the text which appears when this analysis creates a new
worksheet for generating StatTools reports.
o Utility – A Boolean (“TRUE” or “FALSE”) which initializes the
otherwise read-only Utility property of the StatToolsAnalysis
object. This tells StatTools whether this analysis is considered a
“utility” or not. A utility performs operations on data sets and
variables to create or modify existing data sets and variables.
StatTools treats utilities differently from regular analyses. For
example, a utility uses the settings on the “Utilities” tab of the
StatTools settings dialog instead of the “Reports” tab.
o RequiresVariables - A Boolean (“TRUE” or “FALSE”) which
initializes the otherwise read-only RequiresVariables property of
the StatToolsAnalysis object. This tells StatTools if this analysis
requires one or more StatTools variables to be selected by the
user in order to run. Most analyses require the user to select
one or more variable to analyze. There are some that do not,
however, and StatTools will treat these analyses slightly
differently. For example, StatTools will never prompt the user
to switch from a workbook without defined data sets to one
that has them when running an analysis that doesn’t require
variables.

Creating a Custom Analysis for StatTools 37

 o HelpContextID – a integer value specifying the contextID for
this analysis in the analysis pack’s help file. If there is no
contextID (or no help file) leave this item blank. See the
following section Creating an Analysis Pack Help File for
more details about creating a help file for your analysis.

Creating an Analysis Pack Help File

If you know how to compile a help file, it is easy add one to your
custom analysis pack. StatTools supports both .chm (compiled html-
help files) and .hlp (older-style windows help files) formats.
The file should be placed in the analysis pack’s directory, the same
place the .xla files are located. If you are not using a configuration file
(unlikely if you went to the trouble to write and compile a help file) you
must name the file the same name as the analysis pack name (but, of
course, with the .chm or .hlp extension added.) If you are using a
configuration file, the name of the file is specified in the configuration
file.
If your help system is capable of adding context sensitive tags to the
help file, you can specify a contextID for each analysis. When the user
clicks the help icon in your analysis’ dialog, StatTools will launch the
help file and have it display the appropriate context page. You must
use a configuration file to set help context IDs for help files.

38 Creating Analysis Packs

 StatTools Object — Analyses Property

StatTools Object Library

Reference

StatTools Object
Analyses Property
Description Returns a StatToolsAnalyses collection object which
contains all the analysis modules that were registered with
StatTools when the program was launched. See the
section Packs, Categories, and Analyses of this
document for more information on analyses.

Syntax Object.Analyses

Arguments None.

Return Value A StatToolsAnalyses object.

Example Set myAnalyses = StatTools.Analyses

StatTools Object Library Reference 39

StatTools Object — AnalysisCategories Property

AnalysisCategories Property
Description Returns a StatToolsAnalysisCategories collection object
which contains all the analysis categories that were
registered with StatTools when the program was launched.
An analysis category is a collection of analyses that are
grouped together under a common StatTools icon and
submenu. For example, StatTools has a built-in category
called “Normality Tests” which contains several analyses
all related to performing normality tests. See the section
Packs, Categories, and Analyses of this document for
more information on analysis categories.

Syntax Object.AnalysisCategories

Arguments None.

Return Value A StatToolsAnalysisCategories object.

Example Set myCategories = StatTools.AnalysisCategories

40 StatTools Object
 StatTools Object — AnalysisPacks Property

AnalysisPacks Property
Description Returns a StatToolsAnalysisPacks collection containing all
the analysis packs that were registered with StatTools
when then program was launched. An analysis pack is a
collection of analyses and analysis categories that are
packaged and sold together as a unit. StatTools comes
with a single built-in analysis pack, called the “core” pack,
which contains the most commonly used statistical
analyses. Additional packs, containing additional
analyses, can be purchased directly from Palisade
Corporation, or from 3rd party vendors. You can also write
and publish your own analysis packs. See the section
Packs, Categories, and Analyses of this document for
more information on analysis packs.

Syntax Object.AnalysisPacks

Arguments None.

Return Value A StatToolsAnalysisPacks object.

Example Set myAnalysisPacks = StatTools.AnalysisPacks

StatTools Object Library Reference 41

StatTools Object — AskOKCancel Method

AskOKCancel Method
Description Presents a standard StatTools OK/Cancel dialog to the
user, displaying the message specified. If the user selects
“OK”, the method will return TRUE. If the user selects
“Cancel”, the method will return FALSE. If the
DisplayAlerts property has been set to False, the dialog
will not appear and this method will always return TRUE.

Syntax Object.AskOKCancel(queryString as String)

Arguments queryString (String) – the message that will be displayed in

the dialog.

Return Value Boolean. TRUE if “OK” is selected. FALSE if “Cancel” is

selected.

Example If StatTools.AskOKCancel(“This will erase your results.”)

Then …

AskYesNo Method
Description Presents a standard StatTools Yes/No dialog to the user,
displaying the message specified. If the user selects
“Yes”, the method will return TRUE. If the user selects
“No”, the method will return FALSE. If the DisplayAlerts
property has been set to False, the dialog will not appear
and this method will always return TRUE.

Syntax Object.AskYesNo(queryString as String)

Arguments queryString (String) – the message that will be displayed in

the dialog.

Return Value Boolean. TRUE if “Yes” is selected. FALSE if “No” is

selected.

Example If StatTools.AskYesNo(“Are you sure you want to erase

your results.”) Then …

42 StatTools Object
 StatTools Object — DataSets Property

DataSets Property
Description Returns a StatToolsDataSets object, which is the
collection of currently scanned StatTools data sets. In
addition, this same object provides access to several
methods and properties for manipulating this collection of
data sets. Only a single workbook can be “scanned” at
any one time. See the section Data Sets and Variables” of
this document for more information about DataSets and
how they are scanned.

Syntax Object.DataSets

Arguments None.

Return Value A StatToolsDataSets object.

Example numberOfDataSets = StatTools.DataSets.Count

DisplayAlerts Property
Description Controls whether StatTools messages, warnings, and
queries are displayed. If set to TRUE, all messages are
displayed normally. If set to FALSE, all StatTools
messages, including those passing through the
AskOKCancel, AskYesNo, and Message methods, are not
displayed. This is useful for automation code which needs
to suppress user interaction.

Syntax Object.DisplayAlerts

Arguments None.

Return Value Boolean. TRUE indicates messages are being displayed

normally. FALSE indicates messages are being
suppressed.

Example StatTools.DisplayAlerts = FALSE

StatTools Object Library Reference 43

StatTools Object — ExcelApp Property

ExcelApp Property
Description Returns the Microsoft Excel Application object, which the
running copy of StatTools is attached to.

Syntax Object.ExcelApp

Arguments None.

Return Value An Excel Application object.

Example Set myExcelApplication = StatTools.ExcelApp

44 StatTools Object
 StatTools Object — Message Method

Message Method
Description Presents a standard StatTools message dialog to the user,
with a single “OK” button. If the StatTool’s DisplayAlerts
property has been set to False, the dialog will not appear.

Syntax Object.Message(messageText as String)

Arguments messageText (String) – the message that will be displayed

in the dialog.

Return Value None.

Example StatTools.Message “This is a test message.”

StatTools Object Library Reference 45

StatTools Object — NewChart Method

NewChart Method
Description Creates and returns a new StatToolsChart object, which is a
wrapper object for an embedded Excel chart. The four built-in
chart types are preset StatTools templates for standard Excel
charts, which make it easy to create charts which have the
standard StatTools look and feel. If these chart types are not
sufficient for your needs, you can also create a “custom” chart.
See the section “Creating Reports, Tables, and Charts” for
more information.
Syntax Object.NewChart(anchorCell As Range, chartType As
StatToolsChartType, xDataRange As Range, yDataRange As
Range)
Arguments anchorCell (Range object) – the upper-left cell location where
the StatTools style chart will be located.
chartType (StatToolsChartType Enumerated Constant) –
controls what type of Excel graph is being made. The different
chartTypes have different data requirements, which are listed
in the xDataRange and yDataRange arguments. One of the
following constant values:
o StatToolsChartTypeColumn – a Excel column chart.
o StatToolsChartTypeScatterMarkers – an (x-y) plot
with markers and no lines.
o StatToolsChartTypeScatterLine – an (x-y) plot with
lines and markers
o StatToolsChartTypeLine – a “line” plot
o StatToolsChartTypeCustom – a chart that does not
fall into one of the above categories.
xDataRange (Range object) – the “x” data for the chart. This
should be set to “Nothing” except for scatter (x,y) chart types,
in which case it should be set to a range consisting of a single
Excel row or column, containing the x-data for the graph.
yDataRange (Range object) – the “y” data for the chart. For a
column chart, this should be set to an Excel range, with the
data arranged in columns. There will be one chart series per
column in the range. For a scatter (x,y) chart, this should be
set to a range consisting of a single Excel row or column,
containing the y-data for the graph. For a line chart, this
should be set to a single row or column, containing the heights
of the line graph.
Return Value A StatToolsChart object.
Example ‘Create a scatter plot of the data in the range A1:B100:
Set theXData = sourceSheet.Range(“A1:A100”)
Set theYData = sourceSheet.Range(“B1:B100”)
Set newChart = StatTools.NewChart(destSheet.Cells(1,1),
StatToolsChartTypeScatterLine, theXData, theYData)

46 StatTools Object
 StatTools Object — NewReport Method

NewReport Method
Description Call this method when you need StatTools to determine
the destination in Excel for a new StatTools report.
StatTools will examine the current settings to determine
where the report should be placed (in a new worksheet or
workbook, etc,) will appropriately format the report range,
and then will generate a new StatToolsReport object. For
reports that should be put in new worksheets, the method
will create the new worksheet, name it, and put a report
“header” at the top of the report. Note: Make sure to
always check the .Result property of the object
returned by the NewReport method before using it to
check for any error conditions. See the example
below. See the section “Creating Reports, Tables, and
Charts” of this document for more information.

Syntax Object.NewReport(numRows as Long, numCols as Long,

Optional whichAnalysis, Optional ReportUpdating As
StatToolsReportUpdating, Optional customHeaderInfo)

Arguments numRows (Long) – the number of rows for the report. This
does not include the rows used by the header range that
StatTools puts at the top of reports that are placed on new
worksheets. The maximum number of rows is 65525.
numCols (Long) – the number of columns for the report.
The maximum number of columns is 256.
whichAnalysis (Optional Variant) – if specified, either a
StatToolsAnalysis object or the string name of the analysis
from which the report is being generated. Supplying this
information allows StatTools to place the appropriate
information in the report header range, and also give
appropriate names to any new worksheet required by the
report. If not supplied, StatTools will put generic
information in these spots.
reportUpdating (Optional StatToolsReportUpdating
Enumerated Constant) – by default StatTools will examine
the current settings to determine what the preferred
updating style the user has chosen (“live” or “static”) for
reports. In some cases, however, your report might not be
able to support that preference, and you need to override
it. In those cases specified one of the following constants:
o StatToolsReportUpdatingAuto – the default. The
report will use either “Live” or “Static” updating
depending on the user preference specified in the
Settings dialog.

StatTools Object Library Reference 47

StatTools Object — NewReport Method
o StatToolsReportUpdatingStatic – The results in
report will be determined via StatTools and/or
Excel formulas, and will not be linked to the
original source data.
o StatToolsReportUpdatingLive – The results
shown will be determined via StatTools and/or
Excel formulas, and will be linked to the original
source data.
o StatToolsReportUpdatingLiveButNotLinked –The
results shown will be determined via StatTools
an/or Excel formulas, but will not be linked to the
original source data.
The setting chosen here will be shown in the report’s
header range, and it also affects how the FinalizeReport
method works.
customHeaderInfo (Optional Variant Containing an Array
of Strings) – if you supply a variant containing an array of
strings (at most five) in this optional argument, that
information will appear as additional lines in the report’s
header range. Each string should contain two parts
separated by a tab character. The first part of the string
(to the left of the tab character) is the title for the item,
while the second part of the string (to the right of the tab
character) is the value of the item.
Return Value A StatToolsReport object. Note: if StatTools is unable to
create a new report for whatever reason, this function will
still return a StatToolsReport object. Be sure to check this
object’s .Result property before using it, as demonstrated
in the example below.

Example ‘Have StatTools make a new report of (45x15) cells for the
analysis named “CustomAnalysis” with “Static” updating:

With StatTools.NewReport(45, 15, “CustomAnalysis”,

StatToolsReportUpdatingStatic)
if .Result <> 0 Then Goto fail

‘Add code here to fill in the report region.

.FinalizeReport
End With

48 StatTools Object
 StatTools Object — NewStackedVariable Method

NewStackedVariable Method
Description Creates a new, stacked StatToolsVariable object. A
stacked variable is a “virtual” variable created from the
combination of two “real” variables (one category variable
and one value variable) and a category name. For
example, if you had one variable called “Gender” filled with
cells labeled either “Male” or “Female” and a second
variable called “Height” filled with numbers, you could
make a “virtual” stacked variable of the heights of all males
using this function, which could then be used like a “real”
variable in other StatTools methods and properties. See
the section DataSets, Variables, and VariableLists of
this document for more information.

Syntax Object.NewStackedVariable(valueVariable As
StatToolsVariable, categoryVariable As StatToolsVariable,
categoryName as String)

Arguments valueVariable (StatToolsVariable Object) – the source

value variable, typically filled with numeric values.

categoryVariable (StatToolsVariable Object) – the source

category variable, typically filled with descriptive labels.

categoryName (String) – the category name will the

stacked variable use. Only the cells in the value variable
where the corresponding category cell matches this name
will be used in the stacked variable.

Return Value A StatToolsVariable object.

Example Set catVariable = StatTools.DataSets(1).Variables(1)

Set valVariable = StatTools.DataSets(1).Variables(2)
Set stackedVariable =
StatTools.NewStackedVariable(valVariable, catVariable,
“Female”)

StatTools Object Library Reference 49

StatTools Object — NewStackedVariableList Method

NewStackedVariableList Method

Description Similar to the NewStackedVariable method, this method

creates a StatToolsVariableList object, containing a
collection of “virtual” stacked variables, one for each
category present in the given category variable. See the
NewStackedVariable method and the section DataSets,
Variables, and VariableLists of this document for more
information.

Syntax Object.NewStackedVariableList(valueVariable As
StatToolsVariable, categoryVariable As StatToolsVariable,
maxNumCategories as Integer)

Arguments valueVariable (StatToolsVariable Object) – the source

value variable, typically filled with numeric values.

categoryVariable (StatToolsVariable Object) – the source

category variable, typically filled with descriptive labels.

maxNumCategories (Integer) – in order to prevent the list

being filled with more variables that your code can tolerate,
this argument specifies the maximum number of variables
to add to the list. If the category variable you specified
contains more than this number of categories, only the first
maxNumCategories (determined alphabetically) will be
added.

Return Value A StatToolsVariableList object containing one

StatToolsVariable object for every distinct category in the
category variable.

Example Set catVariable = StatTools.DataSets(1).Variables(1)

Set valVariable = StatTools.DataSets(1).Variables(2)
Set stackedVariableList =
StatTools.NewStackedVariableList(valVariable,
catVariable, 1024)

50 StatTools Object
 StatTools Object — NewTable Method

NewTable Method
Description Creates a new StatToolsTable object . This object
provides a convenient wrapper for creating tables in Excel
with a standard StatTools look and feel. Once the table
object is created, additional methods and properties of it
may be used to customize the table appropriately. See the
section Creating Reports, Tables, and Charts of this
document for more information.

Syntax Object.NewTable(anchorCell As Range, numInteriorRows

as Long, numInteriorColumns as Long, Optional
descriptiveLabel as String, Optional columnAlignment As
StatToolsAlignment, Optional tableFormat as
StatToolsTableFormat)
Arguments anchorCell (Range) – the upper-left cell in Excel where the
table should be placed.
numInteriorRows (Long) – the number of interior rows that
the table should have. The header rows at the top of the
table are not included in this count.
numInteriorColumns (Long) – the number of interior
columns that the table should have. The header column at
the left of the table is not included in this count.
descriptiveLabel (Optional String) – an optional descriptive
label for the table that appears in the upper-left “signature”
range of the table. If this value is missing, no descriptive
label will be written.
columnAlignment (Optional StatToolsAlignment
Enumerated Constant) – determines the column alignment
of the interior range of the table. Must be one of the
following constant values:
o StatToolsAlignmentLeft - the default. The table
interior is left justified.
o StatToolsAlignmentCenter - the table interior is
center justified.
o StatToolsAlignmentRight – the table interior is
right justified.
tableFormat (Optional StatToolsTableFormat Enumerated
Constant) – controls the formatting style of the table.
Generally, you should use the “open” format, as this is how
all StatTools tables in core pack are formatted.
o StatToolsTableFormatStandard – a bit of
misnomer, since the “open” format is actually the
default table format. The “standard” format is an
older style of table formatting, used in early
versions of StatTools. You should probably

StatTools Object Library Reference 51

StatTools Object — NewVariableList Method
never use this style.
o StatToolsTableFormatOpen – the default
StatTools table format.

Return Value A StatToolsTable object. Once you have gotten this

object, use its methods and properties to customize the
table for your needs.

Example ‘Make a table with 10 interior rows and 20 interior columns:

With StatTools.NewTable(ActiveSheet.Cells(1,1), 10,20,
“Example Table”)
‘Add your table customization code here.

End With

NewVariableList Method
Description Creates a new, empty StatToolsVariableList object. A
variable list is simply a collection of StatToolsVariable
objects. The list may consist of simple “unstacked”
variables, virtual “stacked” variables, or a combination of
both. The list object also contains a number of methods
and properties for manipulating the collection of variables
as a whole. The variable list, when created, contains no
variables. Use the Add or AddList methods to add
variables to a list object.

Syntax Object.NewVariableList

Arguments None.

Return Value An empty StatToolsVariableList object.

Example Set myVarList = StatTools.NewVariableList

myVarList.Add StatTools.DataSets(1).Variables(2)

52 StatTools Object
 StatTools Object — ProductInformation Property

ProductInformation Property
Description Returns the StatToolsProductInfo object, which contains
general information about the installed copy of StatTools,
like version or edition.
Syntax Object. ProductInformation

Arguments None.

Return Value A StatToolsProductInfo object.

Example MsgBox "StatTools Version: " &
StatTools.ProductInfo.Version

ProgramDirectory Property
Description Returns the fully qualified directory path from which
StatTools is currently running.

Syntax Object.ProgramDirectory

Arguments None.

Return Value A string containing the fully qualified path.

Example myPath = StatTools.ProgramDirectory

StatTools Object Library Reference 53

StatTools Object — ProgressBar Method

ProgressBar Method
Description Displays, updates, or closes the standard StatTools
progress bar.

Syntax Object.ProgressBar(mode As StatToolsProgressBarMode,

Optional mainText as String, Optional status as Variant)

Arguments mode (StatToolsProgressBarMode Enumerated Constant)

– determines what action should be taken by the progress
bar. Must be one of the following enumerated constants:
o StatToolsProgressBarModeUpdateImmediate –
the progress bar should be updated immediately
with the text and status information given. If the
progress bar is currently not being shown, it
should be displayed immediately.
o StatToolsProgressBarModeUpdateDelayed –the
progress bar should be displayed or updated with
the text and status information given, but only if
“enough” time since the last update
(approximately ¼ of a second) has elapsed. If
the progress bar is currently not being shown, it
will be displayed only if “significant” time has
elapsed since the first call to this function
(approximately 3 seconds.) This mode makes it
easy to write code that only displays the progress
bar for operations that take significant time to
process. In addition, after the progress window is
displayed, it allows you to make calls to update at
sporadic intervals, while still having the progress
bar update in a smooth fashion. Note: The first
time you call this function in this mode, the
progress dialog will not be displayed. That
first call only starts the timer running. A
future call that occurs approximately 3
seconds or more later is required to actually
display the progress bar.
StatToolsProgressBarModeFinished – use this mode to
hide the progress bar when you are finished with it. Call
this function even if you started the progress bar in
“delayed” mode and the progress bar did not get displayed
because your processing time wasn’t long enough.
mainText (Optional String) – the text that should be
displayed in the center of the progress bar window. If this
is text is missing and this is the first call to the progress
bar, a default string is supplied by StatTools. If this text is
missing in subsequent calls to the progress bar method,
the main text is left unmodified from the previous calls.

54 StatTools Object
 StatTools Object — ProgressBar Method
status (Optional Variant) – an optional string or number. If
not missing, this is the value or text that will be displayed
in the bottom of the progress bar window. If a numeric
value, it should be a value between 0 and 1, and will be
formatted and displayed as a percentage. If it is a string,
that string will be displayed.

Return Value A StatToolsResult code. If the user has clicked the

“Cancel” button of the progress bar since the last time you
called this function, the return code will be
StatToolsResultActionCancelled. Otherwise, the result
code will be zero.

Example ‘Below is the most common way you will use the Progress
Bar:
‘Imagine a loop through N items which potentially can take
a long time:

For i = 1 to N
‘Show the progress bar (in delayed mode)
if
StatTools.ProgressBar(StatToolsProgressBarModeUpdat
eDelayed, “Processing Items”, CDbl(i)/N) <> 0 then
cancelFlag = True: Exit For

‘Do operation on item #i here…

Next I

‘Turn off Progress Bar:

StatTools.ProgressBar
StatToolsProgressBarModeFinished

‘Check if the user canceled the operation:

If cancelFlag Then Goto failureCode

StatTools Object Library Reference 55

StatTools Object — ResultString Property

ResultString Property
Description Several StatTools methods and properties return
StatToolsResult codes. These typically are error
conditions, or result codes stemming from abnormal user
responses, for example an operation cancelled by the
user. This function returns a string description of a given
StatToolsResult.

Syntax Object.ResultString(theResult as StatToolsResult)

Arguments theResult (StatToolsResult Enumerated Constant) – the

result code which you want the string description of.

Return Value A string description of the result code.

Example ‘Display the text associated with a result code:

MsgBox StatTools.ResultString(myResultCode)

Settings Property
Description Returns the StatToolsSettings which contains all the
current user settings for the program.

Syntax Object.Settings

Arguments None.

Return Value A StatToolsSettings object.

Example StatTools.Settings.ReportPlacement =
StatToolsPlaceInNewWorkbook

56 StatTools Object
 StatTools Object — ShowAboutDialog Method

ShowAboutDialog Method
Description Shows the StatTools “About” dialog, which displays the
version, registered user name, company, and serial
number of the product.

Syntax Object.ShowAboutDialog

Arguments None.

Return Value None.

Example StatTools.ShowAboutDialog

ShowAuthorizationDialog Method
Description Shows the “Authorization” dialog for StatTools and the
StatTools Core Analysis Pack. To show authorization
information for a different analysis pack, call the similarly
named method of the appropriate StatToolsAnalysisPack
object. See the StatTools User’s Guide for more
information about authorization and how to authorize your
copy of StatTools.

Syntax Object.ShowAuthorizationDialog

Arguments None.

Return Value None.

Example StatTools.ShowAuthorizationDialog

StatTools Object Library Reference 57

StatTools Object — ShowHelp Method

ShowHelp Method
Description Shows the main StatTools help file, displaying the
specified context page. This method shows the help file
for the main StatTools product. To show help for a
specific analysis, call the similarly named method in the
appropriate StatToolsAnalysis object.

Syntax Object.ShowHelp(context As StatToolsHelpContext)

Arguments context (StatToolsHelpContext Enumerated Constant) –

one of the following constants:
o StatToolsHelpContextNone – displays the table
of contents of the help file
o StatToolsHelpContextDataSetManagerDialog
o StatToolsHelpContextMultiRangeDialog
o StatToolsHelpContextSettingsDialog

Return Value None.

Example ‘Show the help file page for the StatTools Settings dialog:
StatTools.ShowHelp(StatToolsHelpContextSettingDialog)

ShowOnlineManual Method
Description Shows the online manual for the main StatTools program
and the Core Analysis Pack. The online manual is in
Adobe Acrobat format. You will need a copy of Acrobat
Reader 4.0 or higher in order to display this document.

Syntax Object.ShowOnlineManual

Arguments None.

Return Value None.

Example StatTools.ShowOnlineManual

58 StatTools Object
 StatTools Object — SystemDirectory Property

SystemDirectory Property
Description Returns the full path of the shared Palisade “System”
directory. This directory is used by a large number of
software packages developed by Palisade Corporation,
including StatTools.

Syntax Object.SystemDirectory

Arguments None.

Return Value A string containing the full path of the system directory.

Example theSysDir = StatTools.SystemDirectory

StatTools Object Library Reference 59

StatTools Object — SystemDirectory Property

60 StatTools Object
 StatTools Analyses Object — Count Property

StatTools Analyses Object

Count Property
Description Returns the number of analyses in the collection.

Syntax Object.Count

Arguments None.

Return Value Integer. The number of analyses in the collection.

Example ‘How many analyses are registered with StatTools?

numAnalyses = StatTools.Analyses.Count

Item Property
Description Returns a specific analysis, by index or by “internal” name,
from the collection of analyses. Note this is the default
method for this object.

Syntax Object.Item(indexOrName as Variant)

Arguments indexOrName (Variant) – If an integer, the index of the

analysis in the collection. If a string, the “internal” name of
the analysis. The “internal” name of an analysis is always
the same as the filename of the analysis on disk, minus
the extension. For example, the One-Variable Summary
analysis has the filename “OneVarSummary.xla” and its
“internal” name is “OneVarSummary.”

Return Value A StatToolsAnalysis object.

Example ‘These two lines of code are the same:

MsgBox StatTools.Analyses.Item(3).Name
MsgBox StatTools.Analyses(3).Name

StatTools Object Library Reference 61

StatTools Analyses Object — Item Property

62 StatTools Analyses Object

 StatToolsAnalysis Object — AddinPath Property

StatToolsAnalysis Object
AddinPath Property
Description Returns the path and filename of the add-in (.xla) file of
the analysis.

Syntax Object.AddinPath(Optional fullPath As Boolean)

Arguments fullPath (Optional Boolean) – If TRUE, the full path and

filename is returned. If FALSE, only the filename is
returned.

Return Value A string containing the path and filename.

Example theAddinPath = analysisObj.AddinPath

AnalysisCategory Property
Description Returns the StatToolsAnalysisCategory object which this
analysis belongs to. See the section Packs, Categories,
and Analyses for more information on the relationship
between analyses and analysis categories.

Syntax Object.AnalysisCategory

Arguments None.

Return Value A StatToolsAnalysisCategory object.

Example Set theCategory = analysisObj.AnalysisCategory

StatTools Object Library Reference 63

StatToolsAnalysis Object — AnalysisPack Property

AnalysisPack Property
Description Returns the StatToolsAnalysisPack object which this
analysis belongs to. See the section Packs, Categories,
and Analyses for more information on the relationship
between analyses and analysis packs.

Syntax Object.AnalysisPack

Arguments None.

Return Value A StatToolsAnalysisPack object.

Example Set thePack = analysisObj.AnalysisPack

BeginGroup Property
Description Returns whether this analysis begins a “group” within its
category. A group has a divider line separating it from its
predecessor in the StatTools menu and toolbars. You can
set this property in your own custom analyses by creating
a configuration file. See the Configuration Files section
of this document for more information.

Syntax Object.BeginGroup

Arguments None.

Return Value Boolean. TRUE if the analysis starts a new group.

FALSE if not.

Example If analysisObj.BeginGroup then MsgBox “It begins a

group.”

64 StatToolsAnalysis Object
 StatToolsAnalysis Object — BuiltIn Property

BuiltIn Property
Description Returns whether this analysis belongs to StatTools’ Core
Analysis Pack, or to another analysis pack.

Syntax Object.BuiltIn

Arguments None.

Return Value Boolean. TRUE if the analysis is a member of the Core

Pack. FALSE if not.

Example If analysisObj.BuiltIn Then MsgBox “It is a built in

analysis.”

DebugMode Property
Description To facilitate debugging, you can manually load an .xls
version of an analysis you are working on, and StatTools
will call it instead of the .xla file it would normally call. In
those cases, this property will be set to TRUE.

Syntax Object.DebugMode

Arguments None.

Return Value Boolean. TRUE if the analysis is running in a debug .xls

mode. FALSE if not.

Example If analysisObj.DebugMode Then MsgBox “Running in

DebugMode.”

StatTools Object Library Reference 65

StatToolsAnalysis Object — Default Method

Default Method
Description Reads or writes an analysis default to the specified
workbook or to StatTools’ global defaults in the registry.
Use this function to write string, numeric, or Boolean
values. Variants filled with arrays of these values are also
allowed. The DefaultDataSet, DefaultRange,
DefaultVariable, or DefaultVariableList methods are
available for writing or reading defaults of these objects.
Typically you will only call this function from within your
custom analysis’ public “Defaults” function.
Analysis defaults determine what values are shown when
an analysis dialog is first displayed. There are two levels
of these defaults. First, the currently active workbook may
have defaults for an analysis stored within it as hidden
defined names. These values should be written whenever
an analysis dialog is dismissed with a click to the OK
button. This allows those same settings to reappear when
the dialog is next displayed for the same workbook.
Second there is a set of global defaults, stored in the
system registry, which are used when the analysis dialog
is displayed in the context of a workbook that doesn’t have
any workbook level defaults. These global defaults are
written when the user clicks the “Save as Defaults” icon in
an analysis dialog.
Syntax Object.Default(writeDefault As Boolean, wbContext As
Workbook, keyName as String,, val As Variant, Optional
defaultValue)
Arguments writeDefault (Boolean) – TRUE if the default is being
written. FALSE if being read.
wbContext (Workbook) – If set to “Nothing” the default will
be written to or read from StatTools’ global defaults in the
registry. If set to an Excel workbook, the default will be
written to or read from that workbook.
keyName (String) – The name of this item which must be
an alphanumeric string, capable of being written as an
Excel defined name, to identify the default.
val (Variant) – The value that is being written or read into.
Must be one of the following data types
o Boolean
o Integer
o Long
o Double
o String
o A variant containing an array of one of the above
data types.

66 StatToolsAnalysis Object
 StatToolsAnalysis Object — Default Method
defaultValue (Optional Variant) – This setting should be
left blank when writing a default, but is required when
reading. There is no guarantee that the setting you
request will be found stored in either a workbook or the
global defaults. The default value is what value will be
assigned to the val argument if no entry is found.

Return Value None.

Example ‘Write a global default Boolean value of TRUE for the

default called “ShowGraph”:
analysisObject.Default TRUE, Nothing, “ShowGraph”,
TRUE

‘Read the “ShowGraph” default from the workbook wb into

the variable V.
‘If the default value is not there, use a value of TRUE.
analysisObject.Default FALSE, wb, “ShowGraph”, V,
TRUE

StatTools Object Library Reference 67

StatToolsAnalysis Object — DefaultDataSet Method

DefaultDataSet Method
Description This routine reads or writes a StatToolsDataSet object to a
workbook level default. Unlike the Default method, this
method requires the default to be written into a workbook;
Data set defaults can not be stored in the global defaults.
If reading a default from a workbook that does not have
that particular default stored in it, or if the data set stored
there has been deleted, the returned data set will be set to
“Nothing.”

See the Default method for more information on how

defaults are used in StatTools.

Syntax Object.DefaultDataSet(writeDefault As Boolean,

wbContext As Workbook, keyName as String, theDataSet
As StatToolsDataSet)

Arguments writeDefault (Boolean) – TRUE if the default is being

written. FALSE if being read.

wbContext (Workbook) – the Excel Workbook to which the

default will be written to or read from.

keyName (String) – The name of this item which must be

an alphanumeric string, capable of being written as an
Excel defined name, to identify the default.

theDataSet (StatToolsDataSet Object) – the data set

object which will be stored if writing a default, or which will
receive the information if reading.

Return Value None.

Example ‘Write “theDataSet” as the “PredictionDS” default to the

workbook wb.
analysisObject.DefaultDataSet TRUE, wb, “PredictionDS”,
theDataSet

‘Read that same default back out of the workbook:

analysisObject.DefaultDataSet FALSE, wb,
“PredictionDS”, theDataSet

68 StatToolsAnalysis Object
 StatToolsAnalysis Object — DefaultRange Method

DefaultRange Method
Description This routine reads or writes an Excel Range object to a
workbook level default. Unlike the Default method, this
method requires the default to be written into a workbook;
Excel Range defaults can not be stored in the global
defaults. If reading a default from a workbook that does
not have that particular default stored in it, or if the Excel
Range stored there has been deleted, the returned object
will be set to “Nothing.” See the Default method for more
information on how defaults are used in StatTools.

Syntax Object.DefaultDataSet(writeDefault As Boolean,

wbContext As Workbook, keyName as String, theRange
As Range)

Arguments writeDefault (Boolean) – TRUE if the default is being

written. FALSE if being read.

wbContext (Workbook) – the Excel Workbook to which

default will be written to or read from.

keyName (String) – The name of this item which must be

an alphanumeric string, capable of being written as an
Excel defined name, to identify the default.

theRange (Excel Range Object) – the Excel Range which

will be stored if writing a default, or which will receive the
information if reading.

Return Value None.

Example ‘Write “theRange” as the “SourceRange” default to the

workbook wb.
analysisObject.DefaultRange TRUE, wb, “SourceRange”,
theRange

‘Read that same default back out of the workbook:

analysisObject.DefaultRange FALSE, wb,
“SourceRange”, theRange

StatTools Object Library Reference 69

StatToolsAnalysis Object — DefaultVariable Method

DefaultVariable Method
Description This routine reads or writes a StatToolsVariable object to a
workbook level default. Unlike the Default method, this
method requires the default to be written into a workbook;
Variable defaults can not be stored in the global defaults.
If reading a default from a workbook that does not have
that particular default stored in it, or if the variable stored
there has been deleted, the returned variable will be set to
“Nothing.” See the Default method for more information
on how defaults are used in StatTools.

Syntax Object.DefaultVariable(writeDefault As Boolean,

wbContext As Workbook, keyName as String, theVariable
As StatToolsVariable)

Arguments writeDefault (Boolean) – TRUE if the default is being

written. FALSE if being read.

wbContext (Workbook) – the Excel Workbook to which the

default will be written to or read from.

keyName (String) – The name of this item which must be

an alphanumeric string, capable of being written as an
Excel defined name, to identify the default.

theVariable (StatToolsVariable Object) – the variable

object which will be stored if writing a default, or which will
receive the information if reading.

Return Value None.

Example ‘Write “theVariable” as the “SourceVar” default to the

workbook wb.
analysisObject.DefaultVariable TRUE, wb, “SourceVar”,
theVariable

‘Read that same default back out of the workbook:

analysisObject.DefaultVariable FALSE, wb, “SourceVar”,
theVariable

70 StatToolsAnalysis Object
 StatToolsAnalysis Object — DefaultVariableList Method

DefaultVariableList Method
Description This routine reads or writes a StatToolsVariableList object
to a workbook level default. Unlike the Default method,
this method requires the default to be written into a
workbook; Variable list defaults can not be stored in the
global defaults. If reading a default from a workbook that
does not have that particular default stored in it, an empty
variable list object will be returned. If reading a default list
of which some of the variables have been deleted, the list
will contain only the variables which still exist in the
workbook. See the Default method for more information
on how defaults are used in StatTools.

Syntax Object.DefaultVariableList(writeDefault As Boolean,

wbContext As Workbook, keyName as String,
theVariableList As StatToolsVariableList)

Arguments writeDefault (Boolean) – TRUE if the default is being

written. FALSE if being read.
wbContext (Workbook) – the Excel Workbook to which the
default will be written to or read from.
keyName (String) – The name of this item which must be
an alphanumeric string, capable of being written as an
Excel defined name, to identify the default.
theVariableList (StatToolsVariableList Object) – the
variable list object which will be stored if writing a default,
or which will receive the information if reading.

Return Value None.

Example ‘Write “theVariableList” as the “SourceVars” default to the

workbook wb.
analysisObject.DefaultVariableList TRUE, wb,
“SourceVars”, theVariableList

‘Read that same default back out of the workbook:

analysisObject.DefaultVariableList FALSE, wb,
“SourceVars”, theVariableList

StatTools Object Library Reference 71

StatToolsAnalysis Object — HelpContextID Property

HelpContextID Property
Description Returns the help context ID for this analysis. This ID
number identifies what context page in the analysis pack’s
help file is displayed when the user requests help for this
particular analysis. To set the context ID for your own
analyses, you need do two things. First, imbed a context
ID code in the help file you have written for your analysis
pack. Second, create a configuration file for your analysis
pack, and put the help context ID for this analysis in that
file. See the section “Configuration Files” of this document
for more information.

Syntax Object.HelpContextID

Arguments None.

Return Value Long. The context ID for the analysis.

Example myContextID = myAnalysisObject.HelpContextID

72 StatToolsAnalysis Object
 StatToolsAnalysis Object — LoadAddIn Method

LoadAddIn Method
Description Since StatTools has a large number of different analysis
procedures, each within its own Excel .xla add-in file, it
loads and unloads them dynamically in order to effectively
utilize system resources. Typically StatTools takes care of
this process automatically. If, however, you want to
explicitly load and unload an analysis .xla, you can use the
LoadAddin and UnloadAddin methods to do so.

You will usually want to surround this call with an error

handler, to handle cases where StatTools is unable to load
your add-in.

Syntax Object.LoadAddIn

Arguments None.

Return Value None.

Example ‘Explicitly load the add-in, checking to make sure it actually

worked:
On Error Resume Next
myAnalysis.LoadAddIn
If Err <> 0 Then Goto HandleLoadError
On Error goto 0

‘Do stuff with the loaded add-in here…

‘Finally unload the add-in:

myAnalysis.UnloadAddIn

StatTools Object Library Reference 73

StatToolsAnalysis Object — MenuCaption Property

MenuCaption Property
Description Returns the text that appears in the StatTools menu for
this analysis. If the item has an accelerator key
associated with the menu caption, a “&” character will
precede that accelerated letter.

You can set this property in your own custom analyses by

creating a configuration file. See the “Configuration Files”
section of this document for more information.

Syntax Object.MenuCaption

Arguments None.

Return Value A String containing the menu caption.

Example myMenuCaption = myAnalysisObj.MenuCaption

Name Property
Description Returns the “internal” name of the analysis object. The
“internal” name of an analysis is always the same as the
filename of the analysis on disk, minus the extension. For
example, the One-Variable Summary analysis has the
filename “OneVarSummary.xla” and its “internal” name is
“OneVarSummary.”

Syntax Object.Name

Arguments None.

Return Value A String containing the name of the object.

Example myAnalysisName = myAnalysisObj.Name

74 StatToolsAnalysis Object
 StatToolsAnalysis Object — NewSheetName Property

NewSheetName Property
Description Returns the text which appears when this analysis creates
a new worksheet for generating StatTools reports.
StatTools will append a “uniquifier” to this name to make
sure the actual worksheet name does not conflict with an
existing worksheet.

You can set this property in your own custom analyses by

creating a configuration file. See the “Configuration Files”
section of this document for more information.

Syntax Object.NewSheetName

Arguments None.

Return Value A String containing the worksheet name text.

Example myNewSheetText = myAnalysisObj.NewSheetText

ReportDescription Property
Description Returns the descriptive text which appears in the header
region of a StatTools report for this analysis.

You can set this property in your own custom analyses by

creating a configuration file. See the “Configuration Files”
section of this document for more information.

Syntax Object.ReportDescription

Arguments None.

Return Value A String containing the description text.

Example myDescription = myAnalysisObj.ReportDescription

StatTools Object Library Reference 75

StatToolsAnalysis Object — RequiresVariables Property

RequiresVariables Property
Description Returns whether this analysis requires one or more
StatTools variables to be selected by the user in order to
run. Most analyses require the user to select one or
more variable to analyze. There are some that do not,
however, and StatTools will treat these analyses slightly
differently. For example, StatTools will never prompt the
user to switch from a workbook without defined data sets
to one that has them when running an analysis that
doesn’t require variables.

You can set this property in your own custom analyses by

creating a configuration file. See the Configuration Files
section of this document for more information.

Syntax Object.RequiresVariables

Arguments None.

Return Value Boolean. TRUE if this analysis requires variable selection.

FALSE if not.

Example requiredVars = myAnalysisObj.RequiresVariables

76 StatToolsAnalysis Object
 StatToolsAnalysis Object — Run Method

Run Method
Description Run the analysis, just as if the user had clicked on the
analysis’ menu item.

Note: This method will cause a “rescan” of the data sets in

the StatToolsDataSets collection in order to ensure the
information in the Excel workbook is consistent with the
StatTools model definition. See the section Data Sets,
Variables, and Variable Lists for more information on data
sets and how they are scanned.

Syntax Object.Run

Arguments None.

Return Value A StatToolsResult enumerated constant. A zero result

indicates the analysis ran properly. A non-zero result
indicates some sort of exceptional condition (most likely
that the operation was cancelled by the user.) Use the
ResultString method of the StatTools root object for a
string description of the result code.

Example result = myAnalysis.Run()

If result <> 0 Then MsgBox StatTools.ResultString(result)

StatTools Object Library Reference 77

StatToolsAnalysis Object — ShowHelp Method

ShowHelp Method
Description Shows the help file for the analysis pack to which this
analysis belongs to, displaying the appropriate context
page if there is one. See the HelpContextID property for
information on help file context pages.

Syntax Object.ShowHelp

Arguments None.

Return Value None.

Example myAnalysisObj.ShowHelp

78 StatToolsAnalysis Object
 StatToolsAnalysis Object — UnloadAddin Method

UnloadAddin Method
Description Since StatTools has a large number of different analysis
procedures, each within its own Excel .xla add-in file, it
loads and unloads them dynamically in order to effectively
utilize system resources. Typically StatTools takes care of
this process automatically. If, however, you want to
explicitly load and unload an analysis .xla, you can use the
LoadAddin and UnloadAddin methods to do so.

Syntax Object.UnloadAddin

Arguments None.

Return Value None.

Example ‘Explicitly load the add-in, checking to make sure it actually

worked:
On Error Resume Next
myAnalysis.LoadAddIn
If Err <> 0 Then Goto HandleLoadError
On Error goto 0

‘Do stuff with the loaded add-in here…

‘Finally unload the add-in:

myAnalysis.UnloadAddIn

StatTools Object Library Reference 79

StatToolsAnalysis Object — Utility Property

Utility Property
Description Returns whether this analysis is considered a “utility” or
not. A utility performs operations on data sets and
variables to create or modify existing data sets and
variables. StatTools treats utilities differently from regular
analyses. For example, a utility uses the settings on the
“Utilities” tab of the StatTools settings dialog instead of the
“Reports” tab.

You can set this property in your own custom analyses by

creating a configuration file. See the “Configuration Files”
section of this document for more information.

Syntax Object.Utility

Arguments None.

Return Value Boolean. TRUE if the analysis is a “utility.” FALSE if not.

Example isUtility = myAnalysisObj.Utility

80 StatToolsAnalysis Object
 StatToolsAnalysisCategories Object — Count Property

StatToolsAnalysisCategories Object
Count Property
Description Return the number of analysis categories in the collection.

Syntax Object.Count

Arguments None.

Return Value Integer containing the number of categories.

Example ‘How many analysis categories are registered with

StatTools?
numCategories = StatTools.Categories.Count

StatTools Object Library Reference 81

StatToolsAnalysisCategories Object — Item Property

Item Property
Description Returns a specific StatToolsAnalysisCategory object from
the collection, referenced by either index or name. Note
this is the default method for this object.

Syntax Object.Item(indexOrName as Variant)

Arguments indexOrName (Variant) – If an integer, the index of the

category in the collection. If a string, the “internal” name of
the category. The “internal” name of an analysis category
can be explicitly defined in an analysis pack’s configuration
file. If no configuration file exists, each analysis pack will
have one analysis category, with the same internal name
as the pack itself. See the section Packs, Categories,
and Analyses and “Configuration Files” of this document
for more information.

Return Value A StatToolsAnalysisCategory object.

Example ‘These two lines of code are the same:

MsgBox StatTools.AnalysisCategories.Item(3).Name
MsgBox StatTools.AnalysisCategories(3).Name

82 StatToolsAnalysisCategories Object
 StatToolsAnalysisCategory Object — Analyses Property

StatToolsAnalysisCategory Object
Analyses Property
Description Returns a StatToolsAnalyses collection object, containing
a list of all the analyses that belong to this particular
category object. See the section Packs, Categories, and
Analyses of this document for more information on the
relationship between analyses and analysis categories.

Syntax Object.Analyses

Arguments None

Return Value A StatToolsAnalyses collection object.

Example ‘Count how many analyses belong to the first analysis

category:
numAnalyses =
StatTools.AnalysisCategories(1).Analyses.Count

AnalysisPack Property
Description Returns the StatToolsAnalysisPack object which this
analysis category belongs to. See the section Packs,
Categories, and Analyses of this document for more
information on the relationship between analysis packs
and analysis categories.

Syntax Object.AnalysisPack

Arguments None.

Return Value A StatToolsAnalysisPack object.

Example Set myAnalysisPack = myAnalysisCategory.AnalysisPack

StatTools Object Library Reference 83

StatToolsAnalysisCategory Object — BeginGroup Property

BeginGroup Property
Description Returns whether this analysis category begins a “group”
within the user-interface. A group has a divider line
separating it from its predecessor in the StatTools menu
and toolbars.
You can set this property in your own custom analyses by
creating a configuration file. See the “Configuration Files”
section of this document for more information.
Syntax Object.BeginGroup

Arguments None.

Return Value Boolean. TRUE if the category begins a group. FALSE if

not.

Example If myAnalysisCategory.BeginGroup Then MsgBox “It

begins a group.”

BuiltIn Property
Description Returns whether this analysis category belongs to
StatTools’ Core Analysis Pack, or to another analysis
pack.

Syntax Object.BuiltIn

Arguments None.

Return Value Boolean. TRUE if the analysis category is a member of

the Core Pack. FALSE if not.

Example If myAnalysisCategory.BuiltIn Then MsgBox “It is a built in

category.”

84 StatToolsAnalysisCategory Object
 StatToolsAnalysisCategory Object — MenuCaption Property

MenuCaption Property
Description Returns the text that appears in the StatTools menu for
this analysis category. If the item has an accelerator key
associated with the menu caption, a “&” character will
precede that accelerated letter.
You can set this property in your own custom analyses by
creating a configuration file. See the “Configuration Files”
section of this document for more information.

Syntax Object.MenuCaption

Arguments None.

Return Value A String containing the menu caption.

Example myMenuCaption = myAnalysisCategory.MenuCaption

Name Property
Description Returns the “internal” name of this analysis category. The
“internal” name of an analysis category can be explicitly
defined in an analysis pack’s configuration file. If no
configuration file exists, each analysis pack will have one
analysis category, with the same internal name as the
pack itself. See the section Packs, Categories, and
Analyses and “Configuration Files” of this document for
more information.

Syntax Object.Name

Arguments None.

Return Value A String containing the internal name of the analysis

category.

Example analysisCatName = myAnalysisCategory.Name

StatTools Object Library Reference 85

StatToolsAnalysisCategory Object — ToolbarBitmapFile Property

ToolbarBitmapFile Property
Description Returns the fully qualified path and file name of the bitmap
used in the StatTools toolbar to display this category. This
bitmap can be specified for your own custom analyses
using a configuration file. See the “Configuration Files”
section of this document for more information.

Syntax Object.ToolbarBitmapFile

Arguments None.

Return Value A string containing the bitmap path and filename.

Example bitmapPath = myAnalysisCategory.ToolbarBitmapFile

86 StatToolsAnalysisCategory Object
 StatToolsAnalysisPack Object — Analyses Property

StatToolsAnalysisPack Object
Analyses Property
Description Returns a StatToolsAnalyses collection object which
contains a list of all the analyses which belong to the pack.
See the section Packs, Categories, and Analyses of this
document for information about the relationship between
analysis packs and analyses.

Syntax Object.Analyses

Arguments None.

Return Value A StatToolsAnalyses collection object.

Example ‘Determine how many analyses are in the pack

numAnalyses = myAnalysisPack.Analyses.Count

AnalysisCategories Property
Description Returns a StatToolsAnalysisCategories collection object
which contains a list of all the analysis categories which
come from the pack. See the section Packs, Categories,
and Analyses of this document for information about the
relationship between analysis packs and categories.

Syntax Object.AnalysisCategories

Arguments None.

Return Value A StatToolsAnalysisCategories collection object.

Example ‘Determine the number of analysis categories in the pack:

numCategories =
myAnalysisPack.AnalysisCategories.Count

StatTools Object Library Reference 87

StatToolsAnalysisPack Object — BuiltIn Property

BuiltIn Property
Description Returns TRUE if this analysis pack is the built-in “core”
analysis pack that ships with StatTools.

Syntax Object.BuiltIn

Arguments None.

Return Value Boolean. TRUE if the pack is the “core” analysis pack.
FALSE if not.

Example If analysisPackObj.BuiltIn Then MsgBox “This is the core

pack.”

Description Property
Description Returns a descriptive string that describes the analysis
pack. This string appears in the header range when an
analysis in the pack creates a report.

You can set this property in your own custom analysis

pack by creating a configuration file. See the
“Configuration Files” section of this document for more
information.

Syntax Object.Description

Arguments None.

Return Value A String containing the pack’s description.

Example myDescription = analysisPackObj.Description

88 StatToolsAnalysisPack Object
 StatToolsAnalysisPack Object — HasConfigurationFile Property

HasConfigurationFile Property
Description Returns TRUE if this analysis pack uses a configuration
file. A configuration file allows you to control, in detail, an
analysis packs integration with the StatTools program.
While an analysis pack is not required to have a
configuration file, if you plan on distributing your custom
analysis packs to others you will most likely want to write
one. See the “Configuration Files” section of this
document for more information.

Syntax Object.HasConfigurationFile

Arguments None.

Return Value Boolean. TRUE if the analysis pack uses a configuration

file. FALSE if not.

Example If analysisPackObj.HasConfigurationFile Then MsgBox

“It has a configuration file”

HelpPath Property
Description Returns the full path and filename of this analysis’ help file.
If the analysis does not have a help file, the string returned
is empty. The help file for your custom written analysis
pack can be set using a configuration file. See the
“Configuration Files” section of this document for more
information.

Syntax Object.HelpPath

Arguments None.

Return Value A String containing the full path and filename of the help
file.

Example myHelpPath = myAnalysisPack.HelpPath

StatTools Object Library Reference 89

StatToolsAnalysisPack Object — Name Property

Name Property
Description Returns the name of the analysis pack. An analysis pack’s
name is the name of the subdirectory of the
\StatTools\Analyses folder.

Syntax Object.Name

Arguments None.

Return Value A string containing the name of the analysis pack.

Example MsgBox myAnalysisPack.Name

Path Property
Description Returns the path of the analysis pack’s directory on disk.
An analysis pack is installed as a subdirectory of the
\StatTools\Analyses folder.

Syntax Object.Path

Arguments None.

Return Value A string containing the directory path of the analysis pack

Example myPathDirectory = analysisPackObj.Path

90 StatToolsAnalysisPack Object
 StatToolsAnalysisPack Object — Priority Property

Priority Property
Description Returns the priority of the pack, which is a number which
determines which packs are displayed first in the StatTools
user interface. The lower the pack’s priority, the earlier in
the user interface it will be listed. Ties are broken by
alphabetical order. The built-in core analysis pack will
always have earlier priority than all other packs.
The priority for your custom written analysis pack can be
set using a configuration file. See the “Configuration Files”
section of this document for more information.

Syntax Object.Priority

Arguments None.

Return Value A double value representing the priority of the pack.

Example myPackPriority = analysisPackObj.Priority

ShowHelp Method
Description Shows the help file for the analysis pack, optionally set to
display the given help context ID.

Syntax Object.ShowHelp(Optional contextID as Long)

Arguments contextID (Optional Long) – the help context ID which

should be displayed. If not supplied, the table of contents
of the help file will be shown.

Return Value None.

Example analysisPackObj.ShowHelp

StatTools Object Library Reference 91

StatToolsAnalysisPacks Object — Count Property

StatToolsAnalysisPacks Object
Count Property
Description Returns the number of StatToolsAnalysisPack objects in
the collection.

Syntax Object.Count

Arguments None.

Return Value Integer. The number of packs in the collection.

Example ‘Determine the number of analysis packs in the collection:

numAnalysisPacks = StatTools.AnalysisPacks.Count

Item Property
Description Returns a specific analysis pack, by index or by name,
from the collection of analysis packs. Note this is the
default method for this object.

Syntax Object.Item(indexOrName as Variant)

Arguments indexOrName (Variant) – If an integer, the index of the

analysis pack in the collection. If a string, the name of the
analysis pack.

Return Value A StatToolsAnalysisPack object.

Example ‘These two lines of code are the same:

MsgBox StatTools.AnalysisPacks.Item(3).Name
MsgBox StatTools.AnalysisPacks(3).Name

92 StatToolsAnalysisPacks Object
 StatToolsAnalysisPacks Object — Path Property

Path Property
Description Returns the “Analyses” subdirectory of StatTools.

Syntax Object.Path

Arguments None.

Return Value A string containing the analyses subdirectory path.

Example thePath = StatTools.AnalysisPacks.Path

StatTools Object Library Reference 93

StatToolsChart Object — AddCategoryXAxis Method

StatToolsChart Object
AddCategoryXAxis Method
Description Adds a category (i.e. non-numeric) x-axis to a
StatToolsChart object, formatted in the standard StatTools
manner.
Syntax Object.AddCategoryXAxis(categoryNamesRange As
Range, Optional axisTitle as String, Optional
verticalLabels As Boolean)

Arguments categoryNamesRange (Range) – the source Excel Range

where the category tick labels are retrieved from. If this
argument is set to “Nothing” no labels will be created.

axisTitle (Optional String) – if not missing, the title of the

axis.

verticalLabels (Optional Boolean) – If TRUE, the axis tick

labels will be written vertically. If FALSE (the default) the
orientation of the axis tick labels will be determined
automatically by Excel.

Return Value The Excel Axis object that was created.

Example Set labelNames = myWorksheet.Range(“A1:B10”)

Set theNewAxis =
myChart.AddCategoryXAxis(labelRange, “My Axis Title”)

94 StatToolsChart Object
 StatToolsChart Object — AddLegend Method

AddLegend Method
Description Adds a legend to a StatToolsChart object formatted in the
standard StatTools manner.

Syntax Object.AddLegend(seriesNames() as String)

Arguments seriesNames (Array of Strings) – an array of the names to

associated with each series in the chart. The underlying
Excel chart object must already exist before the call to the
AddLegend method, or the names will no be created
properly.

Return Value None.

Example Redim theNames(1 to 3)

theNames(1) = “First Series”
theNames(2) = “Second Series”
theNames(3) = “Third Series”
myChart.AddLegend theNames()

AddTitle Method
Description Adds a title to a StatToolsChart object, formatted in the
standard StatTools manner.

Syntax Object.AddTitle(titleText as String)

Arguments titleText (String) – the text of the chart title.

Return Value An Excel ChartTitle object.

Example myChart.AddTitle “This is my chart’s title.”

StatTools Object Library Reference 95

StatToolsChart Object — AddValueXAxis Method

AddValueXAxis Method
Description Adds a value (i.e. numeric) x-axis to a StatToolsChart
object, formatted in the standard StatTools manner.

Syntax Object. AddValueXAxis(Optional axisTitle as String,

Optional min as Double, Optional max as Double, Optional
unit as Double, Optional numberFormat as String)

Arguments axisTitle (Optional String) – the text that should appear

next to the axis. If missing, no text will be displayed.
min (Optional Double) – the lowest x-axis value. If
missing, the value will float under the control of Excel.
max (Optional Double) – the highest x-axis value. If
missing, the value will float under the control of Excel.
unit (Optional Double) – the spacing between tick marks.
If missing, the value will float under the control of Excel.
numberFormat (Optional String) – an Excel formatting
string (such as “0.000”) which determines the numeric
precision of the axis labels. If missing, Excel’s “General”
format will be used.

Return Value The Excel Axis object that was created.

Example ‘Make an x-axis that runs from 0 to 1 with units of .1:

Set theNewAxis = myChart.AddValueXAxis(“Axis Title”, 0,
1, .1)

96 StatToolsChart Object
 StatToolsChart Object — AddValueYAxis Method

AddValueYAxis Method
Description Adds a value (i.e. numeric) y-axis to a StatToolsChart
object, formatted in the standard StatTools manner.

Syntax Object. AddValueYAxis(Optional axisTitle as String,

Optional min as Double, Optional max as Double, Optional
unit as Double, Optional numberFormat as String, Optional
isSecondaryAxis As Boolean)

Arguments axisTitle (Optional String) – the text that should appear

next to the axis. If missing, no text will be displayed.
min (Optional Double) – the lowest y-axis value. If
missing, the value will float under the control of Excel.
max (Optional Double) – the highest y-axis value. If
missing, the value will float under the control of Excel.
unit (Optional Double) – the spacing between tick marks.
If missing, the value will float under the control of Excel.
numberFormat (Optional String) – an Excel formatting
string (such as “0.000”) which determines the numeric
precision of the axis labels. If missing, Excel’s “General”
will be used.
isSecondaryAxis (Optional Boolean) – if set to TRUE, this
axis will be placed as a secondary y-axis, on the right of
the graph. If FALSE (the default) the new axis is a
standard y-axis, on the left side of the graph.

Return Value The Excel Axis object that was created.

Example ‘Make an y-axis that runs from 0 to 1 with units of .1:

Set theNewAxis = myChart.AddValueYAxis(“Axis Title”, 0,
1, .1)

StatTools Object Library Reference 97

StatToolsChart Object — AddWatermark Method

AddWatermark Method
Description StatTools charts generated from a student or trial versions
typically will automatically be given watermarks in order to
show the user that this is an academic or unlicensed
version of the software. If, however, you make a chart of
type StatToolsChartTypeCustom, you should call this
method to manually add the watermark. Note: You do not
need to check first if the currently running copy of
StatTools is a student or trial version before calling this
method. StatTools will ignore the call if no watermark is
needed.

Syntax Object.AddWatermark

Arguments None.

Return Value None.

Example myChartObject.AddWatermark

ApplyDefaultFormatting Method
Description StatTools will normally format new charts in a consistent
manner, but if you create a chart of type
StatToolsChartTypeCustom, you may want to call this
function to format chart axes, titles, and legends in the
standard StatTools fashion.

Syntax Object.ApplyDefaultFormatting

Arguments None.

Return Value None.

Example myChartObject.ApplyDefaultFormatting

98 StatToolsChart Object
 StatToolsChart Object — ApplyGradientToBars Method

ApplyGradientToBars Method
Description For column style charts, StatTools often will apply a
shading gradient to the bars. If you wish to apply the
standard StatTools shading to your own graphs, this
method may be called.

Syntax Object.ApplyGradientToBars

Arguments None.

Return Value None.

Example myChartObject.ApplyGradientToBars

Chart Property
Description The StatToolsChart object is just a wrapper for an Excel
Chart object, which allows you to quickly format your
charts in the standard StatTools manner. Often you will
need to access the underlying Excel chart object from the
StatTools wrapper. The Chart property allows you to
retrieve that object.

Syntax Object.Chart

Arguments None.

Return Value An Excel Chart object.

Example ‘Look through each series in the underlying Excel chart

object, and change its color:
For each oneSeries in
myChartObject.Chart.SeriesCollection
oneSeries.Interior.Color = RGB(255,0,0)
Next

StatTools Object Library Reference 99

StatToolsChart Object — Chart Property

100 StatToolsChart Object

 StatToolsChart Object — DefaultSeriesColor Method

DefaultSeriesColor Method
Description To provide a consistent look to graphs with multiple series,
often you need a color “sequence.” That is, a nice
sequence of colors that are mutually distinct and look good
together on a graph. This method provides a utility for
doing that.

Syntax Object.DefaultSeriesColor(seriesIndex as Integer)

Arguments seriesIndex (Integer) – which color in the sequence you

wish to retrieve.

Return Value Long. An RGB color value.

Example ‘Use the default series color sequence on the series of this
graph
For i=1 to myChartObject.Chart.SeriesCollection.Count
Set thisSeries =
myChartObject.Chart.SeriesCollection(i)
thisSeries.Interior.Color =
myChartObject.DefaultSeriesColor(i)
Next

StatTools Object Library Reference 101

StatToolsChart Object — DefaultSeriesColor Method

102 StatToolsChart Object

 StatToolsDataSet Object — Attach Method

StatToolsDataSet Object
Attach Method
Description “Attaches” a StatToolsDataSet object to its Excel
workbook location if the attachManually flag was set in
either the Add or AddMulti methods. When you create a
new data set using either the Add or AddMulti methods,
usually you will let StatTools automatically “attach” it to the
workbook for you. This attaching process writes the data
set information into the workbook, sets up any defined
names for the data set’s variables, and (if specified)
formats the data set’s range. If, however, after you create
the data set, you need to make a large number of
modifications to the variables of the data set, you may
want to attach it manually after you have made these
changes. This prevents a large amount of reading and
writing of information from Excel and will speed the
process of creating a new data set.

Syntax Object.Attach

Arguments None.

Return Value None.

Example ‘Use manual attachment here because there are 26

variables, and I am manually
‘setting their names because they are not gotten from the
spreadsheet.
‘This is more efficient that automatic attachment:
With
StatTools.DataSets.Add(ActiveSheet.Range(“A1:Z20”,
StatToolsVariableLayoutColumns, FALSE, TRUE,
“myDataSet”, TRUE)
For i = 1 to 26
.Variables(i).Name = “var # “ & i
Next i
.Attach
End With

StatTools Object Library Reference 103

StatToolsDataSet Object — AutoFitColumns Method

AutoFitColumns Method
Description Sizes the columns of the data set to be wide enough to
display it’s contents. This method will not shrink or
increase the column width beyond certain limits.

Syntax Object.AutoFitColumns

Arguments None.

Return Value None.

Example myDataSetObject.AutoFitColumns.

CreateUtilityVariables Method
Description Creates one or more “utility” variables. A “utility” variable
is a variable created by the transformation of one or more
other variables in a data set. These variables are either
placed to the right of the existing variables in the data set,
or alternatively in a completely new data set on a new
worksheet. This is generally determined by the
UtilityNewVariablePreference property of the
StatToolsSettings object, but this setting can be
overridden in some circumstances. For example, if the
new variables will not fit if inserted into the existing data
set, they will be placed on a new worksheet. Also, if the
data set is made up of multiple ranges, it is not permitted
to create the new utility variables on a new worksheet.
The CreateUtilityVariables_Validate method can be used
to determine what placement style will be used in advance.
That same method can also be used to determine whether
utility variables are able to be created, without actually
doing so.

Syntax CreateUtilityVariables(numVariables as Integer,

varNames() as String, Optional whichAnalysis)

Arguments numVariables (Integer) - the number of utility variables

that should be created.
104 StatToolsDataSet Object
 StatToolsDataSet Object — CreateUtilityVariables Method

varNames (Array of Strings) – the names of the new

variables. This array should be dimensioned to have the
same number of elements as specified in the
numVariables argument.

whichAnalysis (Optional String or StatToolsAnalysis

Object) – the string name or object of the analysis that is
requesting the new utility variables. This is only used
when a new worksheet must be created for the new utility
variables. The NewSheetName property of the specified
analysis will be called to determine the new sheet’s name.
If no analysis is supplied, a default sheet name will be
used.

Return Value A StatToolsVariableList object, containing a list of the new

utility variables.

Example ‘Create three utility variables named “VarA” “VarB” and

“VarC”:
Redim varNames(1 to 3)
varNames(1) = “VarA”
varNames(2) = “VarB”
varNames(3) = “VarC”
Set utilityVarList = myDataSet.CreateUtilityVariables(3,
varNames(), “MyAnalysisName”)

StatTools Object Library Reference 105

StatToolsDataSet Object — CreateUtilityVariables_Validate Method

CreateUtilityVariables_Validate Method
Description See the CreateUtilityVariables method for more information
about utility variables. This method can be called in advance
of that method to determine whether it is possible to insert
certain number of utility variables into a data set. This method
will not actually create any variables. If the
displayUserWarningsAndQueries argument is set, this method
will also warn the user about inserting rows and columns into
their data, as well displaying other errors and warnings that
may occur. Optionally, you may also retrieve what type of
placement style will be used by the CreateUtilityVariables
method.

Syntax Object.CreateUtilityVariables_Validate(numVariables as
Integer, displayUserWarningsAndQueries As Boolean,
Optional resultPlacement as StatToolsUtilityPlacement)

Arguments numVariables (Integer) – the number of utility variables that are

to be created.
displayUserWarningsAndQueries (Boolean) – if TRUE, the
user will receive warning messages about inserting rows and
columns into their data, as well displaying other errors and
warnings that may occur. If FALSE, no messages will be
displayed to the user.
resultPlacement (Optional StatToolsUtilityPlacement
Enumerated Constant) – If you pass a
StatToolsUtilityPlacement variable to this optional argument,
the method will return in it the placement style that a call to the
CreateUtilityVariable method will use. The possible results are:
o StatToolsPlaceInInsertedVariables – the new utility
variables will be created in new variables inserted at
the end of the date set.
o StatToolsPlaceInNewDataSet – the new utility
variables will be created in a completely new data set
in a new worksheet.
Return Value A StatToolsResult code. A zero result indicates no errors. A
non-zero result indicates an error condition. Use the
ResultString method of the StatTools root object for a string
description of the result code.

106 StatToolsDataSet Object

 StatToolsDataSet Object — DataRegion Property
Example ‘If there isn’t enough room to insert 4 utility variables in this
data set, then fail
StatTools.Settings.UtilityNewVariablePreference =
StatToolsPlaceInInsertedVariables
if myDataSetObject.CreateUtilityVariables_Validate(4,
FALSE, placementStyle) <> 0 Then Goto Fail
if placementStyle <> StatToolsPlaceInInsertedVariables then
Goto fail

DataRegion Property
Description Returns an Excel range corresponding to the data region
of the data set. The data region is the data set range
minus any part reserved for the names of variables. For a
multi-range data set, you must specify which of the
multiple ranges to retrieve. See the section “DataSets,
Variables, and VariableLists” of this document for more
information.

Syntax DataRegion(Optional rangeIndex as Integer)

Arguments rangeIndex (Optional Integer) – for multiple range data

sets, use this argument to specify which of the ranges to
return. If left missing, the first range is always returned.

Return Value An Excel range object.

Example Set theRange = myDataSet.DataRegion

StatTools Object Library Reference 107

StatToolsDataSet Object — Delete Method

Delete Method
Description Deletes the data set. Deleting a data set will remove its
definition from the workbook where it resides, remove any
defined names associated with the data set, and remove
any formatting of the data set’s range. It does not,
however delete any cell values in the data set.

Syntax Object.Delete

Arguments None.

Return Value None.

Example myDataSetObject.Delete

ExcelRange Property
Description Returns an Excel range corresponding to the entire data
set, including both the data region and the name region.
For a multi-range data set, you must specify which of the
multiple ranges to retrieve. See the section “DataSets,
Variables, and VariableLists” of this document for more
information.

Syntax Object.ExcelRange(Optional rangeIndex as Integer)

Arguments rangeIndex (Optional Integer) - for multiple range data

sets, use this argument to specify which of the ranges to
return. If left missing, the first range is always returned.

Return Value An Excel range object.

Example Set theRange = myDataSet.ExcelRange

108 StatToolsDataSet Object

 StatToolsDataSet Object — ExcelRangeCount Property

ExcelRangeCount Property
Description Returns the number of Excel ranges that make up the data
set. Most data sets are made up of a single range, and
they will return a count of 1. Multiple-range data sets,
however, are made up of more than one Excel range, and
will return a count greater than 1. The maximum number
of ranges in a data set is 255.

Syntax Object.ExcelRangeCount

Arguments None.

Return Value Integer. The number of Excel ranges.

Example ‘Color every range in the data set red:

For i = 1 to myDataSetObj.ExcelRangeCount
myDataSetObj.ExcelRange(i).Interior.Color =
RGB(255,0,0)
Next i

FormatRange Property
Description Sets or returns whether the data set range is formatted.
Changing this property will add or remove formatting as
appropriate.

Syntax Object.FormatRange

Arguments None.

Return Value Boolean. TRUE if the data set’s Excel range is formatted.
FALSE if not.

Example ‘Make the data set have a formatted range:

myDataSetObj.FormatRange = TRUE

StatTools Object Library Reference 109

StatToolsDataSet Object — Name Property

Name Property
Description Returns or sets the descriptive name of the data set. Data
set names are required to be unique within a workbook.

Syntax Object.Name

Arguments None.

Return Value A String containing the name of the data set.

Example myDataSetObj.Name = “Sales 2002”

110 StatToolsDataSet Object

 StatToolsDataSet Object — NameRegion Property

NameRegion Property
Description Returns an Excel range corresponding to the data set’s
variable name region, which is the first row or column of
the data set. If the data set does not store its variable
names in the spreadsheet, this property will return
“Nothing.” For a multi-range data set, you must specify
which of the multiple ranges to retrieve. See the section
Data Sets, Variables, and Variable Lists of this
document for more information.

Syntax Object.NameRegion(Optional rangeIndex as Integer)

Arguments rangeIndex (Optional Integer) - for multiple range data

sets, use this argument to specify which of the ranges to
return. If left missing, the first range is always returned.

Return Value An Excel range object.

Example Set theRange = myDataSet.ExcelRange

Variables Property
Description Returns the StatToolsVariables collection object,
containing all the variables in this data set. See the
section Data Sets, Variables, and Variable Lists of this
document for more information concerning the relationship
between data sets and variables.

Syntax Object.Variables

Arguments None.

Return Value A StatToolsVariables object.

Example ‘Determine the number of variables in the data set:

numVariables = myDataSetObj.Variables.Count

StatTools Object Library Reference 111

StatToolsDataSet Object — Variables Property

112 StatToolsDataSet Object

 StatToolsDataSets Object — Add Method

StatToolsDataSets Object

Add Method
Description Creates a new StatToolsDataSet object with the specified
properties. This method can not be used to create multi-
range data sets. You must use the AddMulti method to do
this. This method provides you with arguments to control
the most common options for the new data set. Other
options are set to default values, which you may change
by setting various properties of the object returned by this
method. If you do this, you should consider “attaching” the
data set manually, as discussed below.
When you create a new data set using either the Add or
AddMulti methods, usually you will let StatTools
automatically “attach” it to the workbook for you. This
attaching process writes the data set information into the
workbook, sets up any defined names for the data set’s
variables, and (if specified) formats the data set’s range.
If, however, after you create the data set, you need to
make a large number of modifications to the variables of
the data set, you may want to attach it manually after you
have made these changes. This prevents a large amount
of reading and writing of information from Excel and will
speed the process of creating a new data set.
Note: This method will cause a “rescan” of the data sets in
the StatToolsDataSets collection in order to ensure the
information in the Excel workbook is consistent with the
StatTools model definition. See the section Data Sets,
Variables, and Variable Lists of this document for more
information on data sets and how they are scanned.

Syntax Add(xlRange As Range, Optional variableLayout As

StatToolsVariableLayout, Optional variableNamesInCells
as Boolean, Optional formatRange as Boolean, Optional
dataSetName as String, Optional attachManually As
Boolean)

Arguments xlRange (Excel Range Object) – the full range of the data
set, including both the name region (if used) and the data
region.
variableLayout (Optional StatToolsVariableLayout
Enumerated Constant) – the layout of the variables within
the data set. Must be one of the following enumerated
constant values:
StatTools Object Library Reference 113
StatToolsDataSets Object — Add Method

o StatToolsVariableLayoutColumns – one variable

for each data set column
o StatToolsVariableLayoutRows – one variable for
each data set row.
If missing, the value is set to the
DataSetDefaultVariableLayout property of the
StatToolsSettings object.
variableNamesInCells (Optional Boolean) – If TRUE, the
first row or column (depending on the variableLayout
argument) of the data set is reserved for the names of the
variables. If FALSE, the names are not in the spreadsheet
cells, but are instead stored internally. If you set this to
FALSE, you can set the variables names using the
properties of the StatToolsVariables child object of the
StatToolsDataSet object returned by the Add method. If
this argument is missing, it is determined by the
DataSetDefaultNamesInRange property of the
StatToolsSettings object.
formatRange (Optional Boolean) – If TRUE the data set’s
Excel range will be formatted. If FALSE (the default) no
formatting will be applied. If this argument is missing, it is
determined by the DataSetDefaultFormatRange property
of the StatToolsSettings object.
dataSetName (Optional String) – the descriptive name of
the data set. Data set names must be unique within a
single workbook. If this name is missing, a generic, unique
name will be generated for the new data set.
attachManually (Optional Boolean) – if FALSE (the default)
the Add method will automatically attach the data set to
Excel. If TRUE, you are responsible for explicitly calling
the Attach method on the StatToolsDataSet object
returned by this method. It is more efficient to manually
attach a data set when you are changing a large number
of the default variable properties of the new data set right
after you create it.

Return Value A new StatToolsDataSet object.

114 StatToolsDataSets Object

 StatToolsDataSets Object — Add Method
Example ‘A simple example with automatic attachment:
Set newDataSet =
StatTools.DataSets.Add(ActiveSheet.Range(“A1:Z20”),
StatToolsVariableLayoutColumns, FALSE, TRUE,
“myDataSet”, FALSE)
‘A more complicated example with manual attachment:
With
StatTools.DataSets.Add(ActiveSheet.Range(“A1:Z20”,
StatToolsVariableLayoutColumns, FALSE, TRUE,
“myDataSet”, TRUE)
For i = 1 to 26
.Variables(i).Name = “var # “ & i
Next i
.Attach
End With

StatTools Object Library Reference 115

StatToolsDataSets Object — AddMulti Method

AddMulti Method
Description This function is similar to the Add method, but it allows you
to add multiple range data sets.

This method provides you with arguments to control the

most common options for the new data set. Other options
are set to default values, which you may change by setting
various properties of the object returned by this method. If
you do this, you should consider “attaching” the data set
manually, as discussed below.

When you create a new data set using either the Add or
AddMulti methods, usually you will let StatTools
automatically “attach” it to the workbook for you. This
attaching process writes the data set information into the
workbook, sets up any defined names for the data set’s
variables, and (if specified) formats the data set’s range.
If, however, after you create the data set, you need to
make a large number of modifications to the variables of
the data set, you may want to attach it manually after you
have made these changes. This prevents a large amount
of reading and writing of information from Excel and will
speed the process of creating a new data set.

Note: This method will cause a “rescan” of the data sets in

the StatToolsDataSets collection in order to ensure the
information in the Excel workbook is consistent with the
StatTools model definition. See the section Data Sets,
Variables, and Variable Lists of this document for more
information on data sets and how they are scanned.

Syntax AddMulti(xlRanges() As Range, Optional variableLayout

As StatToolsVariableLayout, Optional
variableNamesInPrimaryRange as Boolean, Optional
variableNamesInSecondaryRange as Boolean, Optional
formatRange as Boolean, Optional dataSetName as
String, Optional attachManually As Boolean)

Arguments xlRanges (Array of Excel Range Objects) – an array

containing the Excel ranges that make up the multiple
range data set. Each range should include the entire data
set range, including both the name region (if used) and the
data region.
variableLayout (Optional StatToolsVariableLayout
Enumerated Constant) – the layout of the variables within
the data set. Must be one of the following enumerated

116 StatToolsDataSets Object

 StatToolsDataSets Object — AddMulti Method
constant values:
o StatToolsVariableLayoutColumns – one variable
for each data set column (the default.)
o StatToolsVariableLayoutRows – one variable for
each data set row.
If missing, the value is set to the
DataSetDefaultVariableLayout property of the
StatToolsSettings object.
variableNamesInPrimaryRange (Optional Boolean) – If
TRUE (the default) the first row or column (depending on
the variableLayout argument) of the primary data set
range (that is, the first range in the multiple-range data set)
is reserved for the names of the variables. If FALSE, the
names are not in the spreadsheet cells, but are instead
stored internally. If you set this to FALSE, you can set the
variables names using the properties of the
StatToolsVariables child object of the StatToolsDataSet
object returned by the Add method. If this argument is
missing, it is determined by the
DataSetDefaultNamesInRange property of the
StatToolsSettings object.
variableNamesInSecondaryRange (Optional Boolean) – If
TRUE (the default) the first row or column (depending on
the variableLayout argument) of the secondary data set
ranges (that is, all the ranges except the first in the
multiple-range data set) is reserved for the names of the
variables. These secondary name ranges are just for
labeling purposed only. The official name of the variables
are either in the primary name range or stored internally. If
this argument is missing, it is determined by the
DataSetDefaultNamesInRange property of the
StatToolsSettings object.
formatRange (Optional Boolean) – If TRUE the data set’s
Excel range will be formatted. If FALSE (the default) no
formatting will be applied. If this argument is missing, it is
determined by the DataSetDefaultFormatRange property
of the StatToolsSettings object.
dataSetName (Optional String) – the descriptive name of
the data set. Data set names must be unique within a
single workbook. If this name is missing, a generic, unique
name will be generated for the new data set.
attachManually (Optional Boolean) – if FALSE (the default)
the Add method will automatically attach the data set to
Excel. If TRUE, you are responsible for explicitly calling
the Attach method on the StatToolsDataSet object
returned by this method. It is more efficient to manually
attach a data set when you are changing a large number
of the default variable properties of the new data set right
after you create it.

StatTools Object Library Reference 117

StatToolsDataSets Object — AddMulti Method

Return Value A new StatToolsDataSet object.

Example ‘Make a three range data set

Redim theRanges(1 to 3)
Set theRanges(1) =
ThisWorkbook.Worksheets(1).Range(“A1:C65535”)
Set theRanges(2) =
ThisWorkbook.Worksheets(2).Range(“A1:C65535”)
Set theRanges(3) =
ThisWorkbook.Worksheets(3).Range(“A1:C65535”)
newDataSet = StatTools.DataSets.AddMulti(theRanges(),
StatToolsVariableLayoutColumns, FALSE, TRUE,
“myDataSet”, FALSE)

118 StatToolsDataSets Object

 StatToolsDataSets Object — CheckModelLimitations Method

CheckModelLimitations Method
Description Student versions and other restricted versions of StatTools
may enforce limitations on the number and size of the data
sets and variables. This method allows you to determine if
all the requirements are met, without running an analysis.

Syntax Object.CheckModelLimitations

Arguments None.

Return Value A StatToolsResult code. If zero, no model limitations were

exceeded. If non-zero, a result code indicating what limit
was not met. Pass this code to the ResultString method of
the root StatTools object to get a string description of the
result code.

Example rslt = StatTools.DataSets.CheckModelLimitations

if rslt <> 0 then MsgBox StatTools.ResultString(rslt)

Count Property
Description Returns the number of items in the collection of currently
scanned data sets. See the section Data Sets, Variables,
and Variable Lists of this document for more information
on data sets and scanning.

Syntax Object.Count

Arguments None.

Return Value Integer. The number of data sets.

Example numDataSets = StatTools.DataSets.Count

StatTools Object Library Reference 119

StatToolsDataSets Object — DeleteAll Method

DeleteAll Method
Description Deletes all data sets in the currently scanned workbook.

Deleting a data set will remove its definition from the

workbook where it resides, remove any defined names
associated with the data set, and remove any formatting of
the data set’s range. It does not, however delete any cell
values in the data set.

Note: This method will cause a “rescan” of the data sets in

the StatToolsDataSets collection in order to ensure the
information in the Excel workbook is consistent with the
StatTools model definition. See the section Data Sets,
Variables, and Variable Lists of this document for more
information on data sets and how they are scanned.

Syntax Object.DeleteAll

Arguments None.

Return Value None.

Example StatTools.DataSets.DeleteAll

120 StatToolsDataSets Object

 StatToolsDataSets Object — Find Method

Find Method
Description Returns a data set in the currently scanned collection,
which either overlaps or exactly matches a given range.

Note: This function will find data sets in the currently

scanned list of data sets. You may want to call the Scan
method before calling this method, if you have modified
Excel since the last scan was performed. See the section
Data Sets, Variables, and Variable Lists of this
document for more information on data sets and how they
are scanned.

Syntax Find(rangeToFind As Range, Optional mustBeExactMatch

As Boolean, Optional ignoreDataSet As StatToolsDataSet)

Arguments rangeToFind (Excel Range Object) – the Excel range that

you a trying to find.

mustBeExactMatch (Optional Boolean) – if TRUE, the

rangeToFind argument needs to exactly match the data
set’s range in order to be considered a match. If FALSE
(the default) the rangeToFind argument only needs to
overlap the data set’s range in order to be considered a
match.

ignoreDataSet (Optional StatToolsDataSet Object) – this

esoteric, optional argument allows you to exclude one
particular data set from the search list.

Return Value If a match was found, the method returns the matching
StatToolsDataSet object. If no match was found, the
function returns “Nothing.”

Example If StatTools.DataSets.Find(xlRange, FALSE) Then

MsgBox “Overlap Found”

StatTools Object Library Reference 121

StatToolsDataSets Object — Item Property

Item Property
Description Returns a specific data set, by index or by name, from the
collection of data sets. Note this is the default method for
this object.

Note: This function will find data sets in the currently

scanned list of data sets. You may want to call the Scan
method before calling this method, if you have modified
Excel since the last scan was performed. See the section
Data Sets, Variables, and Variable Lists of this
document for more information on data sets and how they
are scanned.

Syntax Object.Item(indexOrName as Variant)

Arguments indexOrName (Variant) – If an integer, the index of the

data set in the collection. If a string, the name of the data
set.

Return Value A StatToolsDataSet object.

Example ‘These two lines of code are the same:

MsgBox StatTools.DataSets.Item(3).Name
MsgBox StatTools.DataSets(3).Name

122 StatToolsDataSets Object

 StatToolsDataSets Object — Scan Method

Scan Method
Description This method forces a scan of the specified workbook.

To populate the StatTools data set collection object,

StatTools must search through an Excel Workbook looking
for data set and variable definitions. Any definitions that
are found are added as StatToolsDataSet and
StatToolsVariable objects to the StatTools.DataSets
collection. This search process is called a “scan” and the
workbook that has been searched is called the “scanned
workbook.”

Only a single workbook can be scanned at a time. So if

you are working between multiple workbooks, you may
need to rescan as you shift from working on one workbook
to another. You may also need to rescan if you have
inserted or deleted rows or columns in existing data sets.

A few StatTools methods will automatically perform a

rescan , because they require consistency between Excel
and the currently scanned data set collection. This fact is
noted in the description of those methods in this
document.

Syntax Scan(wb As Workbook, Optional

allowSwitchToOtherWorkbook As Boolean)

Arguments wb (Excel Workbook Object) – the workbook that should

be scanned. If set to “Nothing” the current active
workbook is scanned.

allowSwitchToOtherWorkbook (Optional Boolean) – if this

argument is TRUE and the workbook being scanned has
no defined data sets, but there are data sets in an other
loaded workbook, StatTools will ask the user if it is okay to
switch to the different workbook, which will then be
scanned. The default is FALSE.

Return Value None.

Example StatTools.DataSets.Scan(myWorkbook)

StatTools Object Library Reference 123

StatToolsDataSets Object — ScannedWorkbook Property

ScannedWorkbook Property
Description Returns the Excel Workbook object that was last scanned.
If no workbook has been scanned, “Nothing” is returned.

Syntax Object.ScannedWorkbook

Arguments None.

Return Value An Excel Workbook object, or “Nothing” if there is no

scanned workbook.

Example Set theScannedWB =

StatTools.DataSets.ScannedWorkbook

ShowDataSetManager Method
Description Shows StatTool’s “Data Set Manager” dialog in the context
of the currently active Excel workbook and applies any
changes the user made in it to the data set.

Note: This method will cause a “rescan” of the data sets in

the StatToolsDataSets collection in order to ensure the
information in the Excel workbook is consistent with the
StatTools model definition. See the section Data Sets,
Variables, and Variable Lists of this document for more
information on data sets and how they are scanned.

Syntax Object.ShowDataSetManager

Arguments None.

Return Value Boolean. TRUE if the dialog’s “OK” button was pressed.
FALSE if the dialog was cancelled.

Example If StatTools.DataSets.ShowDataSetManager() Then

MsgBox “OK was pressed.”

124 StatToolsDataSets Object

 StatToolsDataSets Object — TotalNumVariables Property

TotalNumVariables Property
Description Returns the total number of variables in the currently
scanned workbook. See the section Data Sets,
Variables, and Variable Lists of this document for more
information on data sets and scanning.

Syntax Object.TotalNumVariables

Arguments None.

Return Value Long. The total number of variables in all currently

scanned data sets.

Example numVars = StatTools.DataSets.TotalNumVariables

StatTools Object Library Reference 125

StatToolsDataSets Object — TotalNumVariables Property

126 StatToolsDataSets Object

 StatToolsProductInfo Object — Copyright Property

StatToolsProductInfo Object
Copyright Property
Description Returns a string containing the copyright text of the
product.

Syntax Object.Copyright

Arguments None.

Return Value A string.

Example MsgBox StatTools.ProductInfo.Copyright

DaysUntilExpiration Property
Description Returns the number of day left before the StatTools
product license expires.

Syntax Object.DaysUntilExpiration

Arguments None.

Return Value Long

Example MsgBox StatTools.ProductInfo.DaysUntilExpiration

StatTools Object Library Reference 127

StatToolsProductInfo Object — Edition Property

Edition Property
Description Indicates the edition (Professional or Industrial) of
StatTools.

Syntax Object.Edition

Arguments None.

Return Value StatToolsEdition Enumerated Constant, with the possible

values:
StatToolsEditionProfessional
StatToolsEditionIndustrial
Example MsgBox IIF(StatTools.ProductInfo.Edition =
StatToolsEditionProfessional, "Professional Edition",
"Industrial Edition")

Language Property
Description Indicates the language version of StatTools.

Syntax Object.Language

Arguments None.

Return Value StatToolsLanguageID Enumerated Constant, with the

possible values:
StatToolsDefaultLanguage
StatToolsEnglishLanguage
StatToolsFrenchLanguage
StatToolsGermanLanguage
StatToolsItalianLanguage
StatToolsJapaneseLanguage
StatToolsSpanishLanguage
Example MsgBox IIF(StatTools.ProductInfo.Language =
StatToolsEnglishLanguage, "English Version", "Non-
English Version")

128 StatToolsProductInfo Object

 StatToolsProductInfo Object — LimitedModelSize Property

LimitedModelSize Property
Description Indicates whether StatTools is running with a limited model
size restriction.

Syntax Object.LimitedModelSize

Arguments None.

Return Value Boolean

Example MsgBox StatTools.ProductInfo.LimitedModelSize

Name Property
Description Returns the official name of the StatTools product,
localized appropriately for the current language.

Syntax Object.Name

Arguments None.

Return Value String

Example MsgBox StatTools.ProductInfo.Name

StatTools Object Library Reference 129

StatToolsProductInfo Object — ProductType Property

ProductType Property
Description Indicates the type of product license for the running copy
of StatTools

Syntax Object.ProductType

Arguments None.

Return Value StatToolsLanguageID Enumerated Constant, with the

possible values:
StatToolsProductTypeBeta
StatToolsProductTypeBook
StatToolsProductTypeBought
StatToolsProductTypeCourse
StatToolsProductTypeStudent
StatToolsProductTypeTrial
Example MsgBox IIF(StatTools.ProductInfo. ProductType =
StatToolsProductTypeTrial, "Trial Version", "Not a Trial
Version")

RegisteredCompany Property
Description The registered company of the user, as specified during
the installation of StatTools.

Syntax Object.RegisteredCompany

Arguments None.

Return Value String

Example MsgBox StatTools.ProductInfo.RegisteredCompany

130 StatToolsProductInfo Object

 StatToolsProductInfo Object — RegisteredSerialNumber Property

RegisteredSerialNumber Property
Description The registered serial number of the user, as specified
during the installation of StatTools.

Syntax Object.RegisteredSerialNumber

Arguments None.

Return Value String

Example MsgBox StatTools.ProductInfo.RegisteredSerialNumber

RegisteredUser Property
Description The registered name of the user, as specified during the
installation of StatTools.

Syntax Object.RegisteredUser

Arguments None.

Return Value String

Example MsgBox StatTools.ProductInfo.RegisteredUser

Version Property
Description Indicates the version of the running copy of StatTools.

Syntax Object.Version

Arguments None.

Return Value String

Example MsgBox StatTools.ProductInfo.Version

StatTools Object Library Reference 131

StatToolsProductInfo Object — WatermarkedGraphs Property

WatermarkedGraphs Property
Description Indicates whether StatTools graphs will have a watermark.

Syntax Object.WatermarkedGraphs

Arguments None.

Return Value String

Example MsgBox StatTools.ProductInfo. WatermarkedGraphs

132 StatToolsProductInfo Object

 StatToolsReport Object — FinalizeReport Method

StatToolsReport Object
FinalizeReport Method
Description When you are finished generating a report, you can call
this method to do some useful processing and formatting.
The FinalizeReport method performs three main actions.
First, if the report generated is a “static” report, it will scan
through the report range and replace all spreadsheet
function in the range with fixed values. Second, it will
resize column widths so the contents of the report cells are
visible. Third, it will scroll the active window’s view so that
the upper-left corner of the report will be visible to the
user.

See the “Creating Reports, Tables, and Charts” section of

this document for more information on creating reports.

Syntax Object.FinalizeReport(Optional freeze as Boolean,

Optional fitColumns as Boolean)

Arguments freeze (Optional Boolean) – if TRUE all Excel functions in

the report range will be replaced with their fixed values.
Note: This can trigger an Excel recalculation to ensure that
the proper, calculated values are used. If FALSE, this
process is skipped. Since the scan process can take
some time, you might bypass this step if you have already
ensured all static values have been used in your report. If
this value is left missing, the default is determined by the
report’s ReportUpdating property (as set when the report
was created with the NewReport method)
fitColumns (Optional Boolean) – if TRUE (the default) the
columns of the report range will be resized in order to fully
display their contents. There is a maximum and minimum
resizing width. If FALSE, no column resizing will be
performed.

Return Value None.

Example With StatTools.NewReport(45, 15, “CustomAnalysis”,

StatToolsReportUpdatingStatic)
if .Result <> 0 Then Goto fail
‘Add code here to fill in the report region…
.FinalizeReport
End With
StatTools Object Library Reference 133
StatToolsReport Object — HeaderRange Property

HeaderRange Property
Description Returns an Excel Range Object which is the “header”
range of the report. This is at the top of the report’s
worksheet, and contains general information about the
analysis being run and the date and time. A report only
has a header range if it is being placed on a new
worksheet, either in the source data workbook or in
another workbook. If a report doesn’t have a header
range, this property will return “Nothing.” See the
“Creating Reports, Tables, and Charts” section of this
document for more information on the layout of reports.

Syntax Object.HeaderRange

Arguments None.

Return Value An Excel Range object, or “Nothing” if the report has no

header range.

Example Set myHeaderRange = myReportObject.HeaderRange

ReportRange Property
Description Returns an Excel Range Object containing the range in
which your report may write its output. This range will be
of the size requested when the report was created using
the NewReport method. See the “Creating Reports,
Tables, and Charts” section of this document for more
information on the layout of reports.

Syntax Object.ReportRange

Arguments None.

Return Value An Excel Range Object.

Example Set destRange = myReportObj.ReportRange

134 StatToolsReport Object

 StatToolsReport Object — Result Property

Result Property
Description Returns the a result code indicating the success or failure
of the creation of the report. A zero indicates success,
while a non-zero result indicates an error condition. The
result code can be passed to the ResultString method of
the root StatTools object to get a description of the error.

For complicated reasons, unlike most other StatTools

methods, when you create a StatToolsReport object using
the NewReport method of the root StatTools object, and it
fails (because it is too large to fit in the destination
location, or the user cancelled the operation, or some
other exceptional condition) it will not raise an error to the
calling application. Instead it will still create
StatToolsReport object, but will set the Result property of
that object to an non-zero error code. Thus, after you
create a new StatToolsReport object, but before you use
it, you should always check the Result code for a non-zero
value. Typically in your custom analyses, you will simply
return this result back to the StatTools function that called
your routine.
See the “Creating Reports, Tables, and Charts” section of
this document for more information creating reports.

Syntax Object.Result

Arguments None.

Return Value A StatToolsResult code. A zero value indicates success.

A non-zero value indicates an error condition. The result
code can be passed to the ResultString method of the root
StatTools object to get a description of the error.

Example With StatTools.NewReport(45, 15, “CustomAnalysis”,

StatToolsReportUpdatingStatic)
if .Result <> 0 Then Goto fail

‘Add code here to fill in the report region.

.FinalizeReport
End With

StatTools Object Library Reference 135

StatToolsReport Object — Result Property

136 StatToolsReport Object

 StatToolsSettings Object — AnalysisDialogsUseMemory Property

StatToolsSettings Object
AnalysisDialogsUseMemory Property
Description Sets or returns if an analysis will look in the currently
active workbook for default dialog settings.

Whenever an analysis dialog is successfully dismissed (by

the user clicking the “OK” button of the dialog) the settings
chosen for the analysis are all stored in the currently active
workbook. The next time that dialog is displayed with that
active workbook, and if this setting is TRUE, those same
setting will be displayed again. This gives a consistent
interaction between the user and the analysis. If this
setting is FALSE, the dialogs will default to the settings in
the global defaults.

Syntax Object.AnalysisDialogsUseMemory

Arguments None.

Return Value Boolean. TRUE if default settings are read out of the
active workbook. FALSE if not.

Example ‘Turn off the dialog memory

StatTools.Settings.AnalysisDialogsUseMemory =
FALSE

StatTools Object Library Reference 137

StatToolsSettings Object — AnalysisPercentileCalculationMethod Property

AnalysisPercentileCalculationMethod Property
Description Returns or sets the method by which StatTool’s calculates
percentiles.

While the concept of a percentile is unambiguous for

theoretical probability distributions, the calculation of
percentiles of a finite sample of data is problematic
because there are a number of different calculation
methods. This setting affects the output of the Percentile
property of the StatToolsVariable object, as well as the
Median, Percentile, and Quartile functions created using
the WriteStandardFormattedFormula method of the
StatToolsVariable object.

Syntax Object.AnalysisPercentileCalculationMethod

Arguments None

Return Value A StatToolsPercentileCalculationMethod Enumerated

Constant, with the following options:
o StatToolsPercentileExcelPercentileFunction
o StatToolsPercentileInterpolatedAssymmetricEndp
oints
o StatToolsPercentileClosestObservation
o StatToolsPercentileEmpiricalDistFunction
o StatToolsPercentileInterpolatedSymmetricEndpoi
nts
o StatToolsPercentileEmpiricalDistFunctionWithAv
eraging
o StatToolsPercentileAuto

Example StatTools.Settings.
AnalysisPercentileCalculationMethod =
StatToolsPercentileClosestObservation

138 StatToolsSettings Object

 StatToolsSettings Object — AnalysisWarnMissingData Property

AnalysisWarnMissingData Property
Description Returns or sets whether analyses that support missing
data values warn the user when variables that contain
missing data are selected.

Many analyses can handle variables that contain missing

data points (that is, variables that have blank cells in
them.) By default, however, those analyses will warn the
user that it will be ignoring missing data points. If the user
is constantly analyzing data with missing data, this can
become irritating, and can be turned off.

Syntax Object.AnalysisWarnMissingData

Arguments None.

Return Value Boolean. If TRUE, selected variables with missing data

will generate warning messages. If FALSE, those
warnings will be suppressed.

Example ‘Turn off the missing data warning messages:

StatTools.AnalysisWarnMissingData = FALSE

StatTools Object Library Reference 139

StatToolsSettings Object — AnalysisWarnNonNumericData Property

AnalysisWarnNonNumericData Property
Description Returns or sets whether analyses that support non-
numeric data values warn the user when variables that
contain such data are selected.

Many analyses can handle variables that contain non-

numeric data points By default, however, those analyses
will warn the user that it will be ignoring the invalid, non-
numeric data points. If the user is constantly analyzing
data with non-numeric data, this can become irritating, and
can be turned off.

Syntax Object.AnalysisWarnNonNumericData

Arguments None.

Return Value Boolean. If TRUE, selected variables with non-numeric

data will generate warning messages. If FALSE, those
warnings will be suppressed.

Example ‘Turn off the non-numeric data warning messages:

StatTools.AnalysisWarnNonNumericData = FALSE

140 StatToolsSettings Object

 StatToolsSettings Object — ClearWorkbookMemory Method

ClearWorkbookMemory Method
Description Clears all default settings stored in the specified workbook.

Whenever an analysis dialog is successfully dismissed (by

the user clicking the “OK” button of the dialog) the settings
chosen for the analysis are all stored in the currently active
workbook. The next time that dialog is displayed with that
active workbook, those same setting will be displayed
again. This gives a consistent interaction between the
user and the analysis. If, however, you want to clear the
“memorized” defaults for a particular workbook and have it
act as if no analyses have been run on it before, this
method may be used.

Note: You can turn off the memory feature entirely by

setting the AnalysisDialogsUseMemory property to
FALSE.

Syntax Object.ClearWorkbookMemory(wb as Workbook)

Arguments wb (Excel Workbook Object) – the Excel workbook to clear

the memory from.

Return Value None.

Example ‘Clear the dialog memory from Excel’s active workbook:

StatTools.Settings.ClearWorkbookMemory(ActiveWorkb
ook)

StatTools Object Library Reference 141

StatToolsSettings Object — DataSetDefaultFormatRange Property

DataSetDefaultFormatRange Property
Description Sets or returns whether new data sets are created, by
default, with special formatting applied to their Excel
range. This affects the default settings for new data sets
in the Data Set Manager dialog, as well as new data sets
created with the Add or AddMulti methods of the
StatToolsDataSets object.

Syntax Object.DataSetDefaultFormatRange

Arguments None.

Return Value Boolean. TRUE if, by default, new data sets will be
formatted. FALSE if not.

Example StatTools.Settings.DataSetDefaultFormatRange = TRUE

142 StatToolsSettings Object

 StatToolsSettings Object — DataSetDefaultNamesInRange Property

DataSetDefaultNamesInRange Property
Description Sets or returns whether new data sets are created, by
default, with the first row or column of the data set
reserved for names. This affects the default settings for
new data sets in the Data Set Manager dialog, as well as
new data sets created with the Add or AddMulti methods
of the StatToolsDataSets object.

Syntax Object.DataSetDefaultNamesInRange(secondaryRange
as Boolean)

Arguments secondaryRange (Boolean) – if FALSE, this property

applies to the primary range of multiple range data sets
(i.e. the first range in the multiple range set.) if TRUE, this
property applies the secondary ranges of multiple range
data sets (i.e. all the other ranges.)

Return Value Boolean. TRUE if, by default, there is a row or column

reserved for names in the data set. FALSE if not.

Example ‘Set the defaults so that there is a name row in new

primary ranges, but not in secondary ones:
StatTools.Settings.DataSetDefaultNamesInRange(FALS
E) = TRUE
StatTools.Settings.DataSetDefaultNamesInRange(TRUE
) = FALSE

StatTools Object Library Reference 143

StatToolsSettings Object — DataSetDefaultVariableLayout Property

DataSetDefaultVariableLayout Property
Description Sets or returns whether new data sets are created, by
default, with variables arranged in columns or rows. This
affects the default settings for new data sets in the Data
Set Manager dialog, as well as new data sets created with
the Add or AddMulti methods of the StatToolsDataSets
object.

Syntax Object.DataSetDefaultVariableLayout

Arguments None.

Return Value A StatToolsVariableLayout enumerated constant. The

legal values are:
o StatToolsVariableLayoutColumns
o StatToolsVariableLayoutRows

Example ‘Change the default layout to rows:

StatTools.Settings.DataSetDefaultVariableLayout =
StatToolsVariableLayoutRows

144 StatToolsSettings Object

 StatToolsSettings Object — ReportDestinationCell Property

ReportDestinationCell Property
Description Controls the destination range for reports when the
ReportPlacement property is set to
StatToolsPlaceInSpecificCell.

If the ReportPlacement property is set to

StatToolsPlaceInSpecificCell, during the creation of a new
report, StatTools will prompt the user to enter the upper-
left cell of the report’s destination. If you want to suppress
this dialog and specify a destination range via code, set
this property to the desired destination cell.

Note: after the report is generated, this property is

automatically cleared.

Syntax Object.ReportDestinationCell

Arguments None.

Return Value An Excel Range Object representing the upper-left cell of

the desired destination.

Example ‘Make the destination that active spreadsheet cell:

StatTools.ReportPlacement =
StatToolsPlaceInSpecificCell
Set StatTools.Settings.ReportDestinationCell =
ActiveCell

StatTools Object Library Reference 145

StatToolsSettings Object — ReportEducationalComments Property

ReportEducationalComments Property
Description Returns or sets whether educational comments are shown
in reports.

StatTools reports often add little comments to various

cells, to warn you of analysis limitations, or to point out
certain results or features. These comments fall in two
categories. The “Notes and Warnings” category includes
comments that are general in nature, and which we
recommend all user of the product, at least at first, read.
These comments are shown, by default, when reports are
generated unless the user specifically turns them off. The
“Educational Comments” category serve as learning aids
for students using StatTools in a classroom environment.
These comments are, by default, not shown, unless they
are turned on by the user.

Syntax Object.ReportEducationalComments

Arguments None.

Return Value Boolean. TRUE if educational comments are shown in

reports. FALSE, if not.

Example ‘Make sure educational comments are shown:

StatTools.Settings.ReportEducationalComments =
TRUE

146 StatToolsSettings Object

 StatToolsSettings Object — ReportLiveUpdatingPreferred Property

ReportLiveUpdatingPreferred Property
Description Returns or sets the updating preference for reports. If
TRUE, the user prefers “live” reports. That is, reports
which use functions to generate results, and whose results
change as the user changes the source data. If FALSE,
the user prefers “static” reports. That is, reports whose
results do not contain functions, and whose results don’t
change as the user changes the source data. The default
setting is “live.”

Note: This is setting is just a preference. Where possible,

you should write analyses that can generate both “live”
and “static” reports. In some cases, however, it is
impossible or impractical to support the generation of “live”
reports. In those cases, you will need to override the
default ReportUpdating argument of the NewReport
method when you create reports.

Note: This setting does not apply to analyses that are

classified as “utilities.” They obey the
UtilityLiveUpdatingPreferred property. Typically, utilities
will be “static” while reports will be “live.”

Syntax Object.ReportLiveUpdatingPreferred

Arguments None.

Return Value Boolean. TRUE for a preference of “live” reports, FALSE

for “static” reports.

Example ‘Set the preference to static reports:

StatTools.Settings.ReportLiveUpdatingPreferred = FALSE

StatTools Object Library Reference 147

StatToolsSettings Object — ReportNotesAndWarnings Property

ReportNotesAndWarnings Property
Description Returns or sets whether notes and warnings are shown in
reports.

StatTools reports often add little comments to various

cells, to warn you of analysis limitations, or to point out
certain results or features. These comments fall in two
categories. The “Notes and Warnings” category includes
comments that are general in nature, and which we
recommend all user of the product, at least at first, read.
These comments are shown, by default, when reports are
generated unless the user specifically turns them off. The
“Educational Comments” category serve as learning aids
for students using StatTools in a classroom environment.
These comments are, by default, not shown, unless they
are turned on by the user.

Syntax Object.ReportNotesAndWarnings

Arguments None.

Return Value Boolean. TRUE if notes and warnings are shown in

reports. FALSE, if not.

Example ‘Make sure educational comments are not shown:

StatTools.Settings.ReportNotesAndWarnings = FALSE

148 StatToolsSettings Object

 StatToolsSettings Object — ReportOverwriteExisting Property

ReportOverwriteExisting Property
Description Controls whether newly generated reports in a workbook
will replace already existing reports in that same
workbook.
This property only has effect if the ReportPlacement
property is StatToolsPlaceInActiveWorkbook or if the
ReportPlacement property is
StatToolsPlaceInNewWorkbook and the
ReportReuseNewWorkbook property is True.
Syntax Object.ReportOverwriteExisting

Arguments None.

Return Value Boolean.

Example StatTools.Settings.ReportOverwriteExisting = True

StatTools Object Library Reference 149

StatToolsSettings Object — ReportPlacement Property

ReportPlacement Property
Description Determines where new reports are placed. Analyses that
are classified as utilities will not respect this preference.
They are controlled by the UtilityNewVariablePreference
property. The options are:
o StatToolsPlaceInNewWorkbook - Reports go in a
newly created Excel workbook.
o StatToolsPlaceInActiveWorkbook - Reports go in
the currently active Excel workbook.
o StatToolsPlaceInLastColumn – reports are
placed in the first unused column in the active
worksheet. If there is not enough room on the
active worksheet, the report will go on a new
worksheet in the active workbook.
o StatToolsPlaceInSpecificCell – reports are placed
in a location specified by the user via a dialog, or
from the ReportDestinationCell property.

Syntax Object.ReportPlacement

Arguments None.

Return Value A StatToolsReportPlacement enumerated constant, as

described above.

Example ‘Place reports in a new worksheet in myWorkbook:

StatTools.Settings.ReportPlacement =
StatToolsPlaceInActiveWorkbook
Set StatTools.Settings.ReportDestinationWorkbook =
myWorkbook

150 StatToolsSettings Object

 StatToolsSettings Object — ReportReuseNewWorkbook Property

ReportReuseNewWorkbook Property
Description Controls whether only a single new Excel workbook will be
created to hold reports.
This property only has effect if the ReportPlacement
property is set to StatToolsPlaceInNewWorkbook, in which
case a new Excel workbook will be created only the first
time reports are generated. All subsequent reports will
then be put into the workbook originally created.
Syntax Object. ReportReuseNewWorkbook

Arguments None.

Return Value Boolean.

Example StatTools.Settings. ReportReuseNewWorkbook = True

StatTools Object Library Reference 151

StatToolsSettings Object — ShowDialog Method

ShowDialog Method
Description Shows the settings dialog to the user, with the specified
tab of the dialog activated.

Syntax ShowDialog(Optional activeTab As

StatToolsSettingsDialogTab)

Arguments activeTab (Optional StatToolsSettingDialogTab

enumerated constant) – which tab to make active when
the dialog appears. One of the following enumerated
constant values:
o StatToolsSettingsReports (the default)
o StatToolsSettingsUtilities
o StatToolsSettingsDataSets
o StatToolsSettingsAnalyses

Return Value Boolean. TRUE if the dialogs “OK” button was clicked.
FALSE if the dialog was cancelled.

Example ‘Bring up the settings dialog which the data sets tab active:
If
StatTools.Settings.ShowDialog(StatToolsSettingsDataSet
s) Then MsgBox “OK Clicked”

152 StatToolsSettings Object

 StatToolsSettings Object — UtilityLiveUpdatingPeferred Property

UtilityLiveUpdatingPeferred Property
Description Returns or sets the updating preference for results of
analyses classified as utilities. A utility is a special sort of
analysis that performs operations on data sets and
variables to create new data sets and variables.

If TRUE, the user prefers “live” utility results. That is, they
use functions to generate results, and these results
changes as the user changes the source data. If FALSE,
the user prefers “static” utility results. That is, results
which do not contain functions, and that don’t change as
the user changes the source data. The default setting is
“static.”

Note: This is setting is just a preference. Where possible,

you should write utilities that can generate both “live” and
“static” results. In some cases, however, it is impossible
or impractical to support the generation of “live” results.

Note: This setting only applies to analyses that are

classified as “utilities.” Non-utility analyses use the
ReportLiveUpdatingPreferred property. Typically, utilities
will be “static” while reports will be “live.”

Syntax Object.UtilityLiveUpdatingPreferred

Arguments None.

Return Value Boolean. TRUE for a preference of “live” results, FALSE

for “static” results.

Example ‘Set the preference to static utility results:

StatTools.Settings.UtilityLiveUpdatingPreferred =
FALSE

StatTools Object Library Reference 153

StatToolsSettings Object — UtilityNewVariablePreference Property

UtilityNewVariablePreference Property
Description Returns or sets the preferred destination for utility results.
A utility is a special sort of analysis that performs
operations on data sets and variables to create new data
sets and variables. The placement of non-utility analyses
is governed by the ReportPlacement property.

Note: This is setting is just a preference. In some cases

StatTools will not be able to respect this preference. For
example, if the new variables will not fit if inserted into the
existing data set, they will be placed on a new worksheet.
Also, if the data set is made up of multiple ranges, it is not
permitted to create the new utility variables on a new
worksheet.

Syntax Object.UtilityNewVariablePreference

Arguments None.

Return Value A StatToolsUtilityPlacement enumerated constant:

o StatToolsPlaceInInsertedVariables – the
transformed results are placed as new variables
in the existing data sets.
o StatToolsPlaceInNewDataSet – the transformed
results are placed in a completely new data set in
a new worksheet.

Example StatTools.Settings.UtilityNewVariablePreferrence =
StatToolsPlaceInInsertedVariables

154 StatToolsSettings Object

 StatToolsSettings Object — UtilityNewVariablePreference Property

StatTools Object Library Reference 155

StatToolsTable Object — AddCustomComment Method

StatToolsTable Object
AddCustomComment Method
Description Adds an “custom” comment to a cell of a table.

There are two ways to add comments to your own table cells,
using either the AddCustomComment method or the
AddStandardComment method. A “standard” comment’s text
is determined by StatTools. A “custom” comment’s text is
passed in as a arbitrary text string.
StatTools reports often add little comments to various cells, to
warn you of analysis limitations, or to point out certain results
or features. These comments fall in two categories. The
“Notes and Warnings” category includes comments that are
general in nature, and which we recommend all user of the
product, at least at first, read. These comments are shown, by
default, when reports are generated unless the user
specifically turns them off. The “Educational Comments”
category serve as learning aids for students using StatTools in
a classroom environment. These comments are, by default,
not shown, unless they are turned on by the user.

Syntax Object.AddCustomComment(rowPos as Long, colPos as Long,

isEducationalComment As Boolean, commentText as String)

Arguments rowPos (Long) – the row position where the comment should
appear. This is relative to the interior cells of the table. Thus a
value of 1 is the 1st interior row of the table. A value of 0, will
put the comment in the header row at the top of the table.
colPos (Long) – the column position where the comment
should appear. This is relative to the interior of the table.
Thus a value of 1 is the 1st interior column of the table. A value
of 0, will put the comment in the header column at the left of
the table.
isEducationalComment (Boolean) – If TRUE, this comment is
an educational comment. In that case the comment will only
appear if the ReportEducationalComments property of the
user’s settings is set to TRUE. If FALSE, this comment is a
StatTools note or warning. In that case the comment will only
appear if the ReportNotesAndWarnings property of the user’s
settings is set to TRUE.
commentText (String) – the actual text of the message. Must
be no longer than 255 characters.

Return Value Boolean. TRUE if the comment was actually written. FALSE if

156 StatToolsTable Object

 StatToolsTable Object — AddDividerLine Method
not. A comment might not be written because the comment
feature has been turned off.

Example ‘Add a custom comment in the upper-left corner of the table:

myTableObject.AddCustomComment 0,0,FALSE, “This is a
test comment”

AddDividerLine Method
Description Adds a divider line to separate table rows or table
columns.

Syntax Object.AddDividerLine(rowDivider As Boolean, position as

Long, Optional excelLineStyle as Long, Optional
extendIntoHeader)

Arguments rowDivider (Boolean) – TRUE to create a horizontal line

that separates table rows. FALSE to create a vertical line
that separates columns.
position (Long) – the position of the divider, relative to the
interior of the table. Must be a value between 1 and one
less than the number of rows or columns of the table.
excelLineStyle (Optional XLLineStyle Enumerated
Constant) – the Excel line style of the divider line. One of
the Excel Enumerated Constants:
o xlContinuous (the default)
o xlDash
o xlDashDot
o xlDashDotDot
o xlDot
o xlDouble
o xlSlantDashDot
extendIntoHeader (Optional Boolean) – If TRUE, the
divider line will extend into the header range. If FALSE
(the default) the divider line will only be visible in the
interior of the table.
Return Value None.

Example ‘Add a double divider line after the third row of the table:
myTableObject.AddDividerLine(TRUE, 3, xlDouble)

StatTools Object Library Reference 157

StatToolsTable Object — AddHeaderTallText Method

AddHeaderTallText Method
Description Writes a special type of text in the top header of the table
at the specified interior column position. If two strings are
specified, the first string appears on top of the other. If a
single string is specified, the two top header rows are
merged together, and the single string appears in the
newly merged cell.

See the section “Creating Reports, Tables, and Charts” of

this document for more information on tables, table
headers, and their layout.

Syntax Object.AddHeaderTallText(columnPos as Long, topText

as String, Optional bottomText as String)

Arguments columnPos (Long) – the position (with respect to the

interior table columns) of the header being written.

topText (String) – if bottomText is also specified, then this

text goes in the first header row of the specified column. if
bottomText is missing, the two header rows of this
specified column are merged, and this string goes in the
newly merged cell.

bottomText (String) – the text that goes in the second

header row of the specified column.

Return Value None.

Example ‘Make the first column have a merged header:

myTableObject.AddHeaderTallText 1, “merged”

‘Make the second column have two header strings one on

top of the other:
myTableObject.AddHeaderTallText 2, “top”, “bottom”

158 StatToolsTable Object

 StatToolsTable Object — AddHeaderText Method

AddHeaderText Method
Description Writes one or more strings to a table’s header. If you are
writing one or more variable names in a header, you
should use either the AddHeaderVariable or
AddHeaderVariableList methods. See the section
“Creating Reports, Tables, and Charts” of this document
for more information on tables, table headers, and their
layout.

Syntax Object.AddHeaderText(whichHeader As StatToolsHeader,

startPos as Long, summaryText as String, ParamArray
headerText())

Arguments whichHeader (StatToolsHeader Enumerated Constant) –

which header is be written to. One of the enumerated
constant values:
o StatToolsHeaderTop
o StatToolsHeaderLeft
startPos (Long) – which position in the header to start
writing, relative to the table’s interior. Must be between 1
and the number of rows (for the left header) or columns
(for the top header.)
summaryText (String) – applies only for top headers.
Since the top header is made up of two rows, and the
standard header text goes on the bottom row, you may
write a single string across the entire top part of the
header by setting a non-blank string here.
headerText (ParamArray of Strings) – one or more string
values which to be written to the header.

Return Value None.

Example ‘Write the left header with three header strings:

myTableObject.WriteHeaderText StatToolsHeaderLeft, 1,
“”, “Header1”, “Header2”, “Header3”

‘Write the top header with a summary header, plus two

header strings:
myTableObject.WriteHeaderText StatToolsHeaderTop, 1,
“Summary Text”, “Header1”, “Header2”

StatTools Object Library Reference 159

StatToolsTable Object — AddHeaderVariable Method

AddHeaderVariable Method
Description Writes the name and data set name of a variable into a
table’s header. To write more than one variables’
information into a table header, use the
AddHeaderVariableList method. See the section “Creating
Reports, Tables, and Charts” of this document for more
information on tables, table headers, and their layout.

Syntax Object.AddHeaderVariable(whichHeader As
StatToolsHeader, startPos as Long, var As
StatToolsVariable)

Arguments whichHeader (StatToolsHeader Enumerated Constant) –

which header is be written to. One of the enumerated
constant values:
o StatToolsHeaderTop
o StatToolsHeaderLeft

startPos (Long) – which position in the header to start write

to, relative to the table’s interior. Must be between 1 and
the number of rows (for the left header) or columns (for the
top header.)

var (StatToolsVariable Object) – which variable should

have its information written into the header.

Return Value None.

Example myTableObject.AddHeaderVariable StatToolsHeaderTop,

1, myVarObject

160 StatToolsTable Object

 StatToolsTable Object — AddHeaderVariableList Method

AddHeaderVariableList Method
Description Writes the name and data set name of one or more
variables into a table’s header. To write a single
variable’s information into a table header, use the
AddHeaderVariable method. See the section “Creating
Reports, Tables, and Charts” of this document for more
information on tables, table headers, and their layout.

Syntax Object.AddHeaderVariableList(whichHeader As
StatToolsHeader, startPos as Long, varList As
StatToolsVariableList)

Arguments whichHeader (StatToolsHeader Enumerated Constant) –

which header is be written to. One of the enumerated
constant values:
o StatToolsHeaderTop
o StatToolsHeaderLeft

startPos (Long) – which position in the header to start

writing, relative to the table’s interior. Must be between 1
and the number of rows (for the left header) or columns
(for the top header.)

varList (StatToolsVariableList Object) – which variables

should have their information written into the header.

Return Value None.

Example myTableObject.AddHeaderVariableList
StatToolsHeaderTop, 1, myVarListObject

StatTools Object Library Reference 161

StatToolsTable Object — AddStandardComment Method

AddStandardComment Method
Description Adds a “standard” comment to a cell of a table.
There are two ways to add comments to your own table
cells, using either the AddCustomComment method or the
AddStandardComment method. A “standard” comment’s
text is determined by StatTools. A “custom” comment’s
text is passed in as a arbitrary text string.
StatTools reports often add little comments to various
cells, to warn you of analysis limitations, or to point out
certain results or features. These comments fall in two
categories. The “Notes and Warnings” category includes
comments that are general in nature, and which we
recommend all user of the product, at least at first, read.
These comments are shown, by default, when reports are
generated unless the user specifically turns them off. The
“Educational Comments” category serve as learning aids
for students using StatTools in a classroom environment.
These comments are, by default, not shown, unless they
are turned on by the user. Note: Each “standard”
comment knows whether it is an educational comment or a
note or warning, thus unlike the AddCustomComment
method, you do not need to specify which category the
comment falls in.

Syntax Object.AddStandardComment(rowPos as Long, colPos as

Long, whichComment as StatToolsStdComment)

Arguments rowPos (Long) – the row position where the comment

should appear. This is relative to the interior cells of the
table. Thus a value of 1 is the 1st interior row of the table.
A value of 0, will put the comment in the header row at the
top of the table.
colPos (Long) – the column position where the comment
should appear. This is relative to the interior of the table.
Thus a value of 1 is the 1st interior column of the table. A
value of 0, will put the comment in the header column at
the left of the table.
whichComment (StatToolsStdComment Enumerated
Constant) – which standard comment to display. Note:
There currently are very few standard comments
supported by StatTools. As new analyses are being
created, this list of comments is expected to grow.
Currently this list is limited to:
o StatToolsCommentConfidenceLevel
o StatToolsCommentNormalAssumption

162 StatToolsTable Object

 StatToolsTable Object — HeaderRange Property
Return Value Boolean. TRUE if the comment was actually written.
FALSE if not. A comment might not be written because
the comment feature has been turned off.

Example ‘Add the standard normal assumption comment to the

upper-left corner of the table:
myTableObject.AddStandardComment 0,0,FALSE,
StatToolsCommentNormalAssumption

HeaderRange Property
Description Returns the Excel Range Object corresponding to either
the top or left table header. See the section “Creating
Reports, Tables, and Charts” of this document for more
information on tables, table headers, and table layout.

Syntax Object.HeaderRange(whichHeader as StatToolsHeader)

Arguments whichHeader (StatToolsHeader Enumerated Constant) –

which header you want to retrieve. One of the enumerated
constant values:
o StatToolsHeaderTop
o StatToolsHeaderLeft

Return Value An Excel Range Object corresponding to the specified

header.

Example Set leftHeaderRange =

myTableObject.HeaderRange(StatToolsHeaderLeft)

StatTools Object Library Reference 163

StatToolsTable Object — InteriorRange Property

InteriorRange Property
Description Returns the Excel Range Object corresponding to the
table’s interior, where the table’s data is typically written.
See the section “Creating Reports, Tables, and Charts” of
this document for more information on tables, table
interiors, and their layout.

Syntax Object.InteriorRange

Arguments None.

Return Value An Excel Range Object corresponding to the interior range

of the table.

Example Set interiorRange = myTableObject.InteriorRange

SignatureRange Property
Description Returns the Excel Range Object corresponding to the
table’s signature range, the small rectangle in the upper-
left corner of the table where the table’s description is
written. See the section “Creating Reports, Tables, and
Charts” of this document for more information on tables,
signature ranges, and table layout.

Syntax Object.SignatureRange

Arguments None.

Return Value An Excel Range Object corresponding to the signature

range of the table.

Example Set theSignatureRange =

myTableObject.SignatureRange

164 StatToolsTable Object

 StatToolsTable Object — TableRange Property

TableRange Property
Description Returns the Excel Range Object corresponding to the
entire table range.

Syntax Object.TableRange

Arguments None.

Return Value An Excel Range Object.

Example Set myTableRange = myTableObject.TableRange

StatTools Object Library Reference 165

StatToolsVariable Object — AutoFitColumns Method

StatToolsVariable Object
AutoFitColumns Method
Description Sizes the spreadsheet column or columns of the variable
to be wide enough to display it’s contents. This method
will not shrink or increase the column width beyond certain
limits.

Syntax Object.AutoFitColumns

Arguments None.

Return Value None.

Example myVariableObject.AutoFitColumns.

166 StatToolsVariable Object

 StatToolsVariable Object — CheckCategoryHeuristic Method

CheckCategoryHeuristic Method
Description Checks if a variable “looks” like a category variable.

A variable sometimes will contain (typically) non-numeric,

categorical data (for example, a variable named “Gender”
with values of “Male” and “Female”) Often, you will want to
look at a variable selected by the user as a category
variable to make sure it is actually one. Obviously this can
not be done perfectly, but must be done with some sort of
semi-arbitrary heuristic. This method’s heuristic counts
the number of distinct categories in the variable (ignoring
blanks and case) and compares it to the total number of
cells in the variable. If there are more than five categories
and the number of categories is greater than half the
number of cells, the heuristic fails.
If the heuristic passes, the method returns a TRUE value.
If the heuristic fails, two different things may happen. If
the method was called with the askUserIfQuestionable
argument set to FALSE, the method simply returns
FALSE, and it is up to the caller to determine what to do
about it. If, however, askUserIfQuestionable is TRUE, the
user will be prompted with a warning message indicating
that the variable in question doesn’t seem to be a category
variable, and if they want to go ahead and use it anyway.
If they select “Yes,” the heuristic method will return TRUE,
just as if the heuristic itself had passed. If they select
“No,” the heuristic method will return a FALSE value,
which the caller must catch and handle.

Syntax Object.CheckCategoryHeuristic(askUserIfQuestionable As
Boolean)

Arguments askUserIfQuestionable (Boolean) – Determines whether

the method will ask the user to confirm the use of the
variable if it fails the heuristic.

Return Value Boolean. TRUE if the heuristic passes. FALSE if not.

Example If myCatVariable.CheckCategoryHeuristic(FALSE) Then

MsgBox “Heuristic Passed”
Else
MsgBox “Heuristic Failed”
End If

StatTools Object Library Reference 167

StatToolsVariable Object — CountCategories Method

CountCategories Method
Description Returns the number of distinct categories in the variable.

A variable sometimes will contain categorical data (for

example, a variable named “Gender” with values of “Male”
and “Female”) This routine looks through all the cells in
the variable, and counts the number of distinct categories.
Categories are case-insensitive, so “Male” “MALE” and
“male” are treated as the same category. Blank cells are
not treated as a category.

Syntax Object.CountCategories

Arguments None.

Return Value Long. The number of distinct categories in the variable.

Example numCategories = myVariableObject.CountCategories

168 StatToolsVariable Object

 StatToolsVariable Object — CountCategoryOccurrences Method

CountCategoryOccurrences Method
Description Returns the number of times a given category name
appears in a variable.

A variable sometimes will contain categorical data (for

example, a variable named “Gender” with values of “Male”
and “Female”) This routine looks through all the cells in
the variable, and counts the number of times the variable
contains a particular name. Categories are case-
insensitive, so “Male” “MALE” and “male” are treated as
the same category.

Syntax Object.CountCategoryOccurrences(catName as String)

Arguments catName (String) – the name of the category for which you
want to count the number of occurrences.

Return Value Long. The number of times that category name appears in
the variable.

Example ‘Count the number of “Male”s in the variable:

numOccurences =
myVariableObject.CountCategoryOccurrences(“Male”)

StatTools Object Library Reference 169

StatToolsVariable Object — CountCells Method

CountCells Method
Description Counts the number of cells in the variable which meet a
specified criterion. You can use the GetCellPositions
method to return the positions of the cells within the
variable that meet the criterion in addition to the count.

Syntax Object.CountCells(countWhat As StatToolsCountOption)

Arguments countWhat (StatToolsCountOption Enumerated Constant)

– controls exactly what cells are to be counted. Must be
one of the following enumerated constant values:
o StatToolsCountCells – count all cells in the
variable.
o StatToolsCountNumeric – count only cell
containing numeric values.
o StatToolsCountNonBlank – count only cells that
have a value (numeric or text) in them.
o StatToolsCountNonBlankNonNumeric – count
only cells that have non-numeric values in them.
o StatToolsCountBlank – count only blank cells.

Return Value Long. The number of cells in the variable meeting the
specified criterion.

Example ‘Count the number of blank cells:

numBlankCells =
myVariableObject.CountCells(StatToolsCountBlank)

170 StatToolsVariable Object

 StatToolsVariable Object — Covariance Property

Covariance Property
Description Returns the measure of covariance between this variable
and another specified variable. The two variables must
have the same number of values. Blank and non-numeric
values in either variable will be ignored.

This is equivalent to the StatCovariance spreadsheet

function.

Syntax Object.Covariance(var As StatToolsVariable)

Arguments var (StatToolsVariable Object) – the variable with which

you want to calculate the covariance of this variable.

Return Value Double. The covariance of the two variables. If the value
is not legal (for example if there is no data in one of the
variables) the special value StatToolsNoValue is returned.

Example myCovariance =
myFirstVariableObject.Covariance(mySecondVariableObj
ect)
If myCovariance = StatToolsNoValue Then Goto
errorHandler

StatTools Object Library Reference 171

StatToolsVariable Object — DisplayName Property

DisplayName Property
Description Returns a descriptive string for the variable, suitable for
display in a dialog or in a report. For unstacked variables,
this is simply the name of the variable (optionally
appended to the name of the variable’s parent data set.)
For stacked variables, the name includes both the name of
the underlying value variable plus the category name for
this particular stacked variable. See the section Data
Sets, Variables, and Variable Lists of this document for
more information on stacked versus unstacked variables.

Syntax Object.DisplayName(includeDataSetName As Boolean)

Arguments includeDataSetName (Boolean) – if TRUE, the name of

the variable’s parent data set will be included in the string
returned. if FALSE, the data set name will not be
included.

Return Value String.

Example ‘Set the active cell to display the variables display name:
ActiveCell.Value =
myVariableObject.DisplayName(FALSE)

172 StatToolsVariable Object

 StatToolsVariable Object — ExcelRange Property

ExcelRange Property
Description Returns an Excel range corresponding to the variable,
optionally including or excluding the name region. For a
multi-range data set, you must specify which of the
multiple ranges of the variable to retrieve. See the section
“DataSets, Variables, and VariableLists” of this document
for more information.

Syntax Object.ExcelRange(Optional rangeIndex, Optional

includingNameHeader As Boolean)

Arguments rangeIndex (Optional Integer) - for multiple range data

sets, use this argument to specify which of the ranges to
return. If left missing, the first range is always returned.

includingNameHeader (Optional Boolean) – if TRUE, the

name region of the range (if any) is included in the range
returned. If FALSE (the default) the name region is left
out.

Return Value An Excel.Range object.

Example Set destRange = myVariableObject.ExcelRange

StatTools Object Library Reference 173

StatToolsVariable Object — ExcelRangeCount Property

ExcelRangeCount Property
Description Returns the number of Excel ranges that make up the
variable. Most variables are made up of a single range,
and they will return a count of 1. Multiple-range data sets,
however, have variables that are made up of more than
one Excel range, and these variables will return a count
greater than 1. The maximum number of ranges in a
variable is 255.

Syntax Object.ExcelRangeCount

Arguments None.

Return Value Integer. The number of Excel ranges.

Example ‘Color every range in the variable red:

For i = 1 to myVariableObject.ExcelRangeCount
myVariableObject.ExcelRange(i).Interior.Color =
RGB(255,0,0)
Next i

174 StatToolsVariable Object

 StatToolsVariable Object — FreezeData Method

FreezeData Method
Description Replaces all Excel formulas in the variable cells with their
currently calculated values.

Syntax Object.FreezeData

Arguments None.

Return Value None.

Example myVariableObject.FreezeData

StatTools Object Library Reference 175

StatToolsVariable Object — GetCategoryNames Method

GetCategoryNames Method
Description Returns an array of the distinct category names of this
variable.

A variable sometimes will contain categorical data (for

example, a variable named “Gender” with values of “Male”
and “Female”) This routine looks through all the cells in
the variable, and returns an array containing all the unique
category names. Categories are case-insensitive, so
“Male” “MALE” and “male” are treated as the same
category.

Syntax Object.GetCategoryNames(catNames() as String, Optional

maxCount as Long)

Arguments catNames (Array of Strings) – the array which will be

redimensioned and filled with a list of the distinct category
names. The most names this function can return is 32767.

maxCount (Optional Long) – the maximum number of

category names to return. If left missing, the default value
is 32767.

Return Value Integer. The total number of category names returned.

Example ‘Get the category names of the variable. Get no more

than 10 of them:
Dim catNames() as String
numCategories =
myVariableObject.GetCategoryNames(catNames(), 10)

176 StatToolsVariable Object

 StatToolsVariable Object — GetCategoryOccurrences Method

GetCategoryOccurrences Method
Description For a variable that contains categorical data (for example,
a variable with values of “Male” and “Female”.) This
routine returns the positions of all the data values that
match a given category name. Categories are case-
insensitive, so “Male” “MALE” and “male” are all treated as
the same category.

Syntax Object.GetCategoryOccurrences(catName as String,

posArray() as Long)

Arguments catName (String) – the name of the category to retrieve

data for.
posArray (Array of Longs) – an array which will be
redimensioned and filled with the positions of the cells that
have the category name specified. The first cell position is
1.
Return Value (Long) – the total number of items returned in the posArray
argument.
Example ‘Get the number of occurrences and the positions of the
category “Male”
Dim numOccurrences as Long
Dim posArray() as Long
numOccurrences =
myVariableObject.GetCategoryOccurrences(“Male”,
posArray())

StatTools Object Library Reference 177

StatToolsVariable Object — GetCellPositions Method

GetCellPositions Method
Description Returns the positions and count of cells that match a
certain criterion. For example, you might want the cell
positions of all the blank cells in a variable. The returned
array are offsets of the cells in the variable object. So if
the array of 3 elements {2,7,13} were returned by this
function, that corresponds to the 2nd, 7th, and 13th cells of
the variable. You can use the CountCells method to
simply return the number of cells in a variable meeting the
same criterion, without getting the cell positions.

Syntax Object.GetCellPositions(getWhat As
StatToolsCountOption, cellPositions() As Long)

Arguments getWhat (StatToolsCountOption Enumerated Constant) –

determines what types of cells are being searched for.
Must be one of the following enumerated constant values:
o StatToolsCountCells – include all cells in the
variable.
o StatToolsCountNumeric – include only cells
containing numeric values.
o StatToolsCountNonBlank – include only cells that
have a value (numeric or text) in them.
o StatToolsCountNonBlankNonNumeric – include
only cells that have non-numeric values in them.
o StatToolsCountBlank – include only blank cells.

cellPositions (Array of Longs) – this array will be

redimensioned and filled with the cell positions that meet
the criterion specified.

Return Value Long. The number of values returned in the cellPositions

array.

Example ‘Count the number of blank cells and get their positions:
Dim cellPositions() as Long
numBlankCells =
myVariableObject.GetCellPositions(StatToolsCountBlank
, cellPositions())

178 StatToolsVariable Object

 StatToolsVariable Object — GetCellValues Method

GetCellValues Method
Description Returns all the cell values of a particular type from the
variable. This function returns this information in an array
of Variants. See also the GetCellValuesAsNumbers and
GetCellValuesAsCategories for alternative methods.

Syntax Object.GetCellValues(getWhat as StatToolsCountOption,

cellValues() as Variant)

Arguments getWhat (StatToolsCountOption Enumerated Constant) –

controls exactly what cells are to be counted. Must be one
of the following enumerated constant values:
StatToolsCountCells – get all cell values.
StatToolsCountNumeric – get only numeric values.
StatToolsCountNonBlank – get only cells that have a value
(numeric or text) in them.
StatToolsCountNonBlankNonNumeric – get only cells that
have non-numeric values in them.

cellValues (Array of Variants) - an array which will be

redimensioned and filled with the values of the cells that
meet the criteria specified in getWhat.
Return Value (Long) – the total number of items returned in the
cellValues argument.
Example ‘Get all the non-blank values from the variable:
Dim numValues as Long
Dim theValues() as Variant
numValues =
myVariableObject.GetCellValues(StatToolsCountNonBlan
k, theValues())

StatTools Object Library Reference 179

StatToolsVariable Object — GetCellValuesAsCategories Method

GetCellValuesAsCategories Method
Description (Available in StatTools version 1.1 and later)
Returns all the cell values of a particular type from the
variable. This function returns this information in an array
of Strings. See also the GetCellValues and
GetCellValuesAsNumbers for alternative methods.
Syntax Object.GetCellValuesAsCategories(getWhat as
StatToolsCountOption, missingTextValue as String,
cellValues() as String)
Arguments getWhat (StatToolsCountOption Enumerated Constant) –
controls exactly what cells are to be counted. Must be one
of the following enumerated constant values:
StatToolsCountCells – get all cell values.
StatToolsCountNumeric – get only numeric values.
StatToolsCountNonBlank – get only cells that have a value
(numeric or text) in them.
StatToolsCountNonBlankNonNumeric – get only cells that
have non-numeric values in them.

missingTextValue (String) – the value to use when a blank

(missing) cell value is retrieved. Generally should be set
to a blank string, but may be set to another value to handle
special cases.
cellValues (Array of Strings) - an array which will be
redimensioned and filled with the values of the cells that
meet the criteria specified in getWhat.
Return Value (Long) – the total number of items returned in the
cellValues argument.
Example ‘Get all values, putting a “N/A” wherever a blank cell is:
Const MISSING_VALUE as String = “N/A”
Dim numValues as Long
Dim theValues() as String
numValues =
myVariableObject.GetCellValuesAsCategories(StatTools
CountCells, MISSING_VALUE, theValues())

180 StatToolsVariable Object

 StatToolsVariable Object — GetCellValuesAsNumbers Method

GetCellValuesAsNumbers Method
Description (Available in StatTools version 1.1 and later)
Returns all the cell values of a particular type from the
variable. This function returns this information in an array
of Doubles. See also the GetCellValues and
GetCellValuesAsCategories for alternative methods.

Syntax Object.GetCellValuesAsNumbers(getWhat as
StatToolsCountOption, missingOrNonNumericValue as
Double, cellValues() as Double)
Arguments getWhat (StatToolsCountOption Enumerated Constant) –
controls exactly what cells are to be counted. Must be one
of the following enumerated constant values:
StatToolsCountCells – get all cell values.
StatToolsCountNumeric – get only numeric values.
StatToolsCountNonBlank – get only cells that have a value
(numeric or text) in them.
StatToolsCountNonBlankNonNumeric – get only cells that
have non-numeric values in them.

missingOrNonNumericValue (Double) – the value to use

when a cell value is retrieved that can not be represented
as a Double.
cellValues (Array of Variants) - an array which will be
redimensioned and filled with the values of the cells that
meet the criteria specified in getWhat.
Return Value (Long) – the total number of items returned in the
cellValues argument.
Example ‘Get all the non-blank values from the variable:
Const INVALID_VALUE as Double = 1E+300
Dim numValues as Long
Dim theValues() as Double
numValues =
myVariableObject.GetCellValuesAsNumbers(StatToolsC
ountNonBlank, INVALID_VALUE, theValues())

StatTools Object Library Reference 181

StatToolsVariable Object — HasMissingData Property

HasMissingData Property
Description Returns whether the variable contains missing values.
The search for missing values can be performed on the
entire variable, or limited to the beginning, middle, or end.

Syntax Object.HasMissingData(checkLocation As
StatToolsCheckLocation)

Arguments checkLocation (StatToolsCheckLocation Enumerated

Constant) – determines where in the variable to check for
missing values:
o StatToolsCheckAll – check the entire variable
range for missing values.
o StatToolsCheckBeginning – check for missing
values only at the beginning of the variable.
Missing values appearing between non-missing
values in both directions, as well as missing data
at the end of the variable, are ignored.
o StatToolsCheckMiddle – check only for missing
values that appear between non-missing values
in both directions.
o StatToolsCheckEnd - check for missing values
only at the end of the variable. Missing values
appearing between non-missing values in both
directions, as well as missing data at the
beginning of the variable, are ignored.
o StatToolsCheckBeginningOrEnd – check only for
missing data at the beginning or end of the
variable. Missing values appearing between non-
missing values in both directions are ignored.

Return Value Boolean. TRUE if missing data was found in the specified
location. FALSE if not.

Example hasInteriorBlanks =
myVariableObject.HasMissingValues(StatToolsCheckMid
dle)

182 StatToolsVariable Object

 StatToolsVariable Object — HasNonNumericData Property

HasNonNumericData Property
Description Returns whether the variable contains any non-numeric
cell values. Blanks are ignored.

Syntax Object.HasNonNumericData

Arguments None.

Return Value Boolean. TRUE if the variable contains any non-numeric,

non-blank values. FALSE if not.

Example If myVariableObject.HasNonNumericData the MsgBox

“Invalid Data”

Maximum Property
Description Returns the current maximum numeric value in the
variable. Blanks, and non-numeric values are ignored.

This is equivalent to the StatMax spreadsheet function.

Syntax Object.Maximum

Arguments None.

Return Value Double. The maximum value. If the value is not legal (for
example if there is no data in the variables) the special
value StatToolsNoValue is returned.

Example myMaxValue = myVariableObject.Maximum

If myMaxValue = StatToolsNoValue Then Goto
errorHandler

StatTools Object Library Reference 183

StatToolsVariable Object — Mean Property

Mean Property
Description Returns the current mean of the numeric values in the
variable. Blanks and non-numeric values are ignored.

This is equivalent to the StatMean spreadsheet function.

Syntax Object.Mean

Arguments None.

Return Value Double. The mean value. If the value is not legal (for
example if there is no data in the variables) the special
value StatToolsNoValue is returned.

Example myMeanValue = myVariableObject.Mean

If myMeanValue = StatToolsNoValue Then Goto
errorHandler

184 StatToolsVariable Object

 StatToolsVariable Object — Minimum Property

Minimum Property
Description Returns the current minimum numeric value in the
variable. Blanks, and non-numeric values are ignored.

This is equivalent to the StatMin spreadsheet function.

Syntax Object.Minimum

Arguments None.

Return Value Double. The minimum value. If the value is not legal (for
example if there is no data in the variables) the special
value StatToolsNoValue is returned.

Example myMinValue = myVariableObject.Minimum

If myMinValue = StatToolsNoValue Then Goto
errorHandler

Name Property
Description Returns or sets the name of the variable.

For an unstacked variable, this is the name entered by the

user at the top of the spreadsheet range of the variable, or
alternatively in the Data Set Manager dialog. For a
stacked variable, it is the category name. See the section
Data Sets, Variables, and Variable Lists for more
information on the differences between stacked and
unstacked variable objects.

Syntax Object.Name

Arguments None.

Return Value String. The name of the variable.

Example myVariableName = myVariableObject.Name

StatTools Object Library Reference 185

StatToolsVariable Object — NumberFormatExcelCode Property

NumberFormatExcelCode Property
Description Returns an Excel number format code (a string that can be
passed to the NumberFormat) that gives a recommended
number format for a given statistical function of the
variable (i.e. Mean, Variance, Skewness, etc.) Most
statistics will respect the NumberFormatIsAuto,
NumberFormatNumDigits, and NumbeFormatType
properties (which are all set by the user via the Data Set
Manager dialog.) Others, however, use alternate or
modified formats. For example, the mean of the variable
will most likely be formatted differently than the skewness.
You may need a number format for your own statistic
function which is not in the list. In that case, you either
need to determine which one of the existing statistic
function is closest to your function (usually a fairly easy
task), or determine what number formatting to use
yourself.

Syntax NumberFormatExcelCode(Optional formatStyle As

StatToolsVariableFormula)

Arguments formatStyle (Optional StatToolsVariableFormula

Enumerated Constant) – what statistic function to get the
number format for. Must be on the following enumerated
constants values:
o StatToolsFuncAutocorrelation
o StatToolsFuncAveDev
o StatToolsFuncKurtosis
o StatToolsFuncMax
o StatToolsFuncMean (the default)
o StatToolsFuncMedian
o StatToolsFuncMin
o StatToolsFuncPercentile
o StatToolsFuncQuartile
o StatToolsFuncRange
o StatToolsFuncSkewness
o StatToolsFuncStdDev
o StatToolsFuncVariance
o StatToolsFuncCount
o StatToolsFuncSum

Return Value String. The Excel Number Format code.

186 StatToolsVariable Object

 StatToolsVariable Object — NumberFormatExcelCode Property

StatTools Object Library Reference 187

StatToolsVariable Object — NumberFormatIsAuto Property
Example ‘Format the cell with the recommended standard deviation
format:
myCell.NumberFormat =
myVariableObject.NumberFormatExcelCode(StatToolsFun
cStdDev)

NumberFormatIsAuto Property
Description Returns or sets whether this variable’s default output
number format is determined automatically by StatTools
based on the data stored in the variable. A variable’s
default output number format controls how many (but by
no means all) report cells will be numerically formatted.

If this property is TRUE, the NumberFormatNumDigits and

NumberFormatType properties will change automatically,
based on the variable’s data. If FALSE, the output number
format is controlled by NumberFormatNumDigits and
NumberFormatType properties.

The user can set the number format of a variable to be

automatic by entering the word “auto” in the Output Format
entry for the variable in the Data Set Manager Dialog.

Syntax Object.NumberFormatIsAuto

Arguments None.

Return Value Boolean. TRUE for an automatic number format. FALSE

for a manually set number format.

Example myVariableObject.NumberFormatIsAuto = TRUE

188 StatToolsVariable Object

 StatToolsVariable Object — NumberFormatNumDigits Property

NumberFormatNumDigits Property
Description Returns or sets the number of digits after the decimal in
the variable’s default output number format. If you set this
property, the NumberFormatIsAuto property will be turned
off. A variable’s default output number format controls
how many (but by no means all) report cells will be
numerically formatted.

This property only has effect if the NumberFormatType

property is set to StatToolsNumberFormatFixed or
StatToolsNumberFormatCurrency.

Syntax Object.NumberFormatNumDigits

Arguments None.

Return Value Integer. The number of digits past the decimal.

Example ‘Set the default output format to 5 fixed digits after the
decimal:
myVariableObject.NumberFormatType =
StatToolsNumberFormatFixed
myVariableObject.NumberFormatNumDigits = 5

StatTools Object Library Reference 189

StatToolsVariable Object — NumberFormatString Property

NumberFormatString Property
Description Allows you to return or set the default output number
format as a string. Setting this property is equivalent of
individually setting the NumberFormatIsAuto,
NumberFormatType, and NumberFormatNumDigits
properties.

The format of the string follows the formats allowed in

StatTool’s Data Set Manager. The possible choices are:
o “Auto”
o “General”
o “Fixed(N)” – where “N” is the number of digits.
o “Currency(N)” – where “N” is the number of digits.

Syntax Object.NumberFormatString

Arguments None.

Return Value String. The number format string as described above.

Example ‘These two code snippets are equivalent:

myVariableObject.NumberFormatString = “Fixed(5)”

With myVariableObject
.NumberFormatIsAuto = FALSE
.NumberFormatType = StatToolsNumberFormatFixed
.NumberFormatNumDigits = 5
End With

190 StatToolsVariable Object

 StatToolsVariable Object — NumberFormatType Property

NumberFormatType Property
Description Returns or sets the type of the default output number
format for the variable. If you set this property, the
NumberFormatIsAuto property will be turned off. A
variable’s default output number format controls how many
(but by no means all) report cells will be numerically
formatted.

Syntax Object.NumberFormatType

Arguments None.

Return Value A StatToolsNumberFormatType Enumerated Constant.

One of the following values:
o StatToolsNumberFormatGeneral – equivalent to
Excel default “General” number formatting.
o StatToolsNumberFormatFixed
o StatToolsNumberFormatCurrency

Example ‘Set the default output format to 5 fixed digits after the
decimal:
myVariableObject.NumberFormatType =
StatToolsNumberFormatFixed
myVariableObject.NumberFormatNumDigits = 5

StatTools Object Library Reference 191

StatToolsVariable Object — Percentile Property

Percentile Property
Description Calculates a percentile (x-value) from a specified p-value.

Syntax Object.Get Percentile(p as Double, Optional

CalculationMethod as
StatToolsPercentileCalculationMethod)

Arguments p (Double) – the p-value of the percentile being sought.

Must be a value between 0 and 1. Thus, the 57% is
retrieved by setting p = 0.57.

CalculationMethod (Optional
StatToolsPercentileCalculationMethod) - While the
concept of a percentile is unambiguous for theoretical
probability distributions, the calculation of percentiles of a
finite sample of data is problematic because there are a
number of different calculation methods. The possible
choices are:
o StatToolsPercentileExcelPercentileFunction
o StatToolsPercentileInterpolatedAssymmetricEndp
oints
o StatToolsPercentileClosestObservation
o StatToolsPercentileEmpiricalDistFunction
o StatToolsPercentileInterpolatedSymmetricEndpoi
nts
o StatToolsPercentileEmpiricalDistFunctionWithAv
eraging
o StatToolsPercentileAuto
If this option is left missing, the option is retrieved from the
AnalysisPercentileCalculationMethod property of the
settings object.

Return Value Double. The x-value percentile corresponding to the

specified p-value. If the value is not legal (for example if
there is no data in the variables) the special value
StatToolsNoValue is returned.

Example ‘Get the percentile (using the user’s current calculation

mode):
myPercValue = myVariableObject.Percentile(.75)
If myPercValue = StatToolsNoValue Then Goto
errorHandler

192 StatToolsVariable Object

 StatToolsVariable Object — RangeName Property

RangeName Property
Description Returns or sets the Excel range name of this variable.

Each variable, when created by the user, is give a unique

Excel range name which can be used inside StatTools or
Excel functions to refer to that variable. Range names are
usually automatically generated by StatTools based on the
variable’s name, but this default value may be overridden.

Note: This property applies only to unstacked variable

objects. See the section Data Sets, Variables, and
Variable Lists for more information on the differences
between stacked and unstacked variable objects.

Syntax Object.RangeName

Arguments None.

Return Value String. The variable’s range name.

Example varRangeName = myVariableObject.RangeName

StatTools Object Library Reference 193

StatToolsVariable Object — ReferenceStr Property

ReferenceStr Property
Description Returns a string which can be used to reference the
variable in a spreadsheet function.
Often you need to put a reference to a variable into a
spreadsheet function. For example, to make a cell return
the mean of a variable, you would write:
=StatMean(varRef)
into the cell. Instead of hard-coding the excel range (e.g.
$A$1:$A$100) of the variable, however, you should use
this property. For simple, unstacked variables, the range
name of the variable will be used (with or without full
qualification – see below.) For stacked variables,
however, it is much more complicated. This function will
take care of the details of creating the appropriate
StatDestack function. See the section Data Sets,
Variables, and Variable Lists for more information on the
differences between stacked and unstacked variable
objects.
One important note: References need to be fully qualified
(that is, they need to include the name of the workbook
where the variable resides) if the cell where the reference
is being made from is not the same as the workbook
where the variable resides. This function decides whether
to return a fully qualified reference or not based on the
current ReportPlacement, ReportDestinationWorkbook,
and ReportDestinationCell properties. If these properties
indicate that the destination is not the same as the
workbook the variable resides in, the reference will be fully
qualified. Otherwise it will be locally qualified. If you need
to control explicitly how the reference is qualified, use the
ReferenceStrEx method instead.

Syntax Object.ReferenceStr

Arguments None.

Return Value String. A reference that can be use in a spreadsheet

function.

Example ‘Put a formula calculating the mean in the cell:

myCellObject.Formula = “=StatMean(“ &
myVarObject.ReferenceStr & “)”

194 StatToolsVariable Object

 StatToolsVariable Object — ReferenceStrEx Property

ReferenceStrEx Property
Description Returns a string which can be used to reference the variable in a
spreadsheet function. Unlike the ReferenceStr method,
ReferenceStrEx allows you to explicitly control the qualification of
the reference.
Often you need to put a reference to a variable into a
spreadsheet function. For example, to make a cell return the
mean of a variable, you would write:
=StatMean(varRef)
into the cell. Instead of hard-coding the excel range (e.g.
$A$1:$A$100) of the variable, however, you should use this
property. For simple, unstacked variables, the range name of the
variable will be used (with or without full qualification – see
below.) For stacked variables, however, it is much more
complicated. This function will take care of the details of creating
the appropriate StatDestack function. See the section Data Sets,
Variables, and Variable Lists for more information on the
differences between stacked and unstacked variable objects.
One important note: References need to be fully qualified (that
is, they need to include the name of the workbook where the
variable resides) if the cell where the reference is being made
from is not the same as the workbook where the variable resides.
This function decides whether to return a fully qualified reference
or not based on the argument you pass in. In contrast, the
method ReferenceStr examines the current user’s settings to
determine what qualification to use.

Syntax Object.ReferenceStrEx(fullyQualify as Boolean)

Arguments fullyQualify (Boolean) – if TRUE the reference will be fully

qualified with the Excel workbook name where the variable
resides. If FALSE the reference will only be locally qualified.

Return Value String. A reference that can be use in a spreadsheet function.

Example ‘Put a formula calculating the mean in the cell

‘Make sure to use full qualification:
myCellObject.Formula = “=StatMean(“ &
myVarObject.ReferenceStrEx(True) & “)”

StatTools Object Library Reference 195

StatToolsVariable Object — Stacked Property

Stacked Property
Description Returns TRUE if this is a stacked variable.

This is a slightly confusing notation. If this parameter is

TRUE, the variable is actually a variable which has been
“destacked” from a pair of variables in stacked format, one
category variable and one value variable, along with the
particular category name. The category variable is in the
StackedCategoryVariable property, the value variable in
the StackedValueVariable properties, and the category
name is store in the variable’s Name property. You can
create a stacked variable object using the
NewStackedVariable or NewStackedVariableList methods
of the root StatTools object.

See the section Data Sets, Variables, and Variable Lists

for more information on the differences between stacked
and unstacked variable objects.

Syntax Object.Stacked

Arguments None.

Return Value Boolean. TRUE if the variable is stacked. FALSE if not.

Example ‘If the variable is stacked do one thing, otherwise another:

If myVariableObject.Stacked Then
DoOneThing
Else
DoAnother
End If

196 StatToolsVariable Object

 StatToolsVariable Object — StackedCategoryVariable Property

StackedCategoryVariable Property
Description For a stacked variable, returns the source category
variable. If this is not a stacked variable, “Nothing” is
returned. The corresponding value variable can be found
from the StackedValueVariable property, and the category
name is store in the variable’s Name property. You can
create a stacked variable object using the
NewStackedVariable or NewStackedVariableList methods
of the root StatTools object.

See the section Data Sets, Variables, and Variable Lists

for more information on the differences between stacked
and unstacked variable objects.

Syntax Object.StackedCategoryVariable

Arguments None.

Return Value A StatToolsVariable object, which is the source category

variable.

Example If myVar.Stacked Then

Set sourceCatVar = myVar.StackedCategoryVariable
Set sourceValVar = myVar.StackedValueValue
End If

StatTools Object Library Reference 197

StatToolsVariable Object — StackedValueVariable Property

StackedValueVariable Property
Description For a stacked variable, returns the source value variable.
If this is not a stacked variable, “Nothing” is returned. The
corresponding category variable can be found from the
StackedCategoryVariable property, and the category name
is store in the variable’s Name property. You can create a
stacked variable object using the NewStackedVariable or
NewStackedVariableList methods of the root StatTools
object.

See the section Data Sets, Variables, and Variable Lists

for more information on the differences between stacked
and unstacked variable objects.

Syntax Object.StackedValueVariable

Arguments None.

Return Value A StatToolsVariable object, which is the source value

variable.

Example If myVar.Stacked Then

Set sourceCatVar = myVar.StackedCategoryVariable
Set sourceValVar = myVar.StackedValueValue
End If

198 StatToolsVariable Object

 StatToolsVariable Object — StdDev Property

StdDev Property
Description Returns the current standard deviation of the numeric
values in the variable. Blanks and non-numeric values
are ignored.

This is equivalent to the StatStdDev spreadsheet

function.

Syntax Object.StdDev

Arguments None.

Return Value Double. The standard deviation. If the value is not legal
(for example if there is no data in the variables) the
special value StatToolsNoValue is returned.

Example myStdDevValue = myVariableObject.StdDev

If myStdDevValue = StatToolsNoValue Then Goto
errorHandler

StatTools Object Library Reference 199

StatToolsVariable Object — Variance Property

Variance Property

Description Returns the current variance of the numeric values in

the variable. Blanks and non-numeric values are
ignored.

This is equivalent to the StatVariance spreadsheet

function.

Syntax Object.Variance

Arguments None.

Return Value Double. The variance. If the value is not legal (for
example if there is no data in the variables) the special
value StatToolsNoValue is returned.

Example myVarianceValue = myVariableObject.Variance

If myVarianceValue = StatToolsNoValue Then Goto
errorHandler

200 StatToolsVariable Object

 StatToolsVariable Object — WriteCustomFormattedFormula Method

WriteCustomFormattedFormula Method
Description Puts a custom spreadsheet formula into the specified
range and sets the range’s numeric formatting. If you are
writing one of the standard StatTools summary measures,
consider using the WriteStandardFormattedFormula
method instead.

Syntax Object.WriteCustomFormattedFormula(xlRange As
Range, formulaString as String, Optional formatLike As
StatToolsVariableFormula)

Arguments xlRange (Excel Range Object) – the destination range for

the formula.
formulaString (String) – the spreadsheet formula to write.
formatLike (StatToolsVariableFormula Enumerated
Constant) – Determines what type of numeric formatting
will be applied to the range. This is specified in terms of
which standard StatTools function is the custom formula
similar to. The choices are:
o StatToolsFuncAutocorrelation
o StatToolsFuncAveDev
o StatToolsFuncKurtosis
o StatToolsFuncMax
o StatToolsFuncMean (the default)
o StatToolsFuncMedian
o StatToolsFuncMin
o StatToolsFuncMode
o StatToolsFuncPercentile
o StatToolsFuncQuartile
o StatToolsFuncRange
o StatToolsFuncSkewness
o StatToolsFuncStdDev
o StatToolsFuncVariance
o StatToolsFuncCount
o StatToolsFuncSum

Return Value None.

StatTools Object Library Reference 201

StatToolsVariable Object — WriteStandardFormattedFormula Method
Example ‘Write a custom formula in the cell which calculates 1/25 of
the mean
‘And is formatted like the mean would be:
myVariableObject.WriteCustomFormattedFormula(myC
ellObject, “=StatMean(“ & myVariableObject.ReferenceStr
& “) / 25”, StatToolsFuncMean)

WriteStandardFormattedFormula Method
Description Puts a standard spreadsheet formula into the specified range and
sets the range’s numeric formatting. If you need to write a function
not on the list of standard ones, use the
WriteCustomFormattedFormula method instead.

Syntax Object. (xlRange As Range, whichFormula As

StatToolsVariableFormula, Optional param)

Arguments xlRange (Excel Range Object) – the destination range for the
formula.
whichFormula (StatToolsVariableFormula Enumerated Constant) –
which standard formula to write. One of the following constant
values:
o StatToolsFuncAutocorrelation
o StatToolsFuncAveDev
o StatToolsFuncKurtosis
o StatToolsFuncMax
o StatToolsFuncMean (the default)
o StatToolsFuncMedian
o StatToolsFuncMin
o StatToolsFuncPercentile
o StatToolsFuncQuartile
o StatToolsFuncRange
o StatToolsFuncSkewness
o StatToolsFuncStdDev
o StatToolsFuncVariance
o StatToolsFuncCount
o StatToolsFuncSum
param (Optional Variant) – the median, percentile, and quartile
functions all require additional parameters. These can be entered
here. If the parameter is a single numeric value, simply add that
as the final argument. If there is more than one parameter, or the
parameter is not a number, enter it as a string.

202 StatToolsVariable Object

 StatToolsVariable Object — WriteStandardFormattedFormula Method
Return Value None.

Example ‘Put the mean of this variable in myCell1:

myVarObject.WriteStandardFormattedFormula myCell1,
StatToolsMean

‘Put the Median in myCells2:

myVarObject.WriteStandardFormattedFormula myCell2,
StatToolsMedian

‘Put the Median in myCells3, this time with a different percentile

calc method:
myVarObject.WriteStandardFormattedFormula myCell3,
StatToolsMedian, StatTools,
StatToolsPercentileClosestObservation

StatTools Object Library Reference 203

StatToolsVariable Object — WriteStandardFormattedFormula Method

204 StatToolsVariable Object

 StatToolsVariableList Object — Add Method

StatToolsVariableList Object
Add Method
Description Adds a new variable to the variable list collection. If you
want to add one variable list collection to another, use the
AddList method.

Syntax Object.Add(newItem as StatToolsVariable)

Arguments newItem (StatToolsVariable Object) – the new item to add

to the list.

Return Value None.

Example myVarListObject.Add myVariableObject

StatTools Object Library Reference 205

StatToolsVariableList Object — AddList Method

AddList Method
Description Adds an entire variable list to this variable list. If you want
to add a single variable to a list, use the Add method.

Syntax Object.AddList(listToMerge as StatToolsVariableList)

Arguments listToMerge (StatToolsVariableList Object) – the list of

items to add to this variable list.

Return Value None.

Example firstVarListObject.AddList secondVarListObject

AllFromSameDataSet Property
Description Returns whether all variables in the list come from the
same StatToolsDataSet object.

Syntax Object.AllFromSameDataSet

Arguments None.

Return Value Boolean. TRUE if all variables in the collection come from
the same data set. FALSE if not.

Example If Not myVarListObject.AllFromSameDataSet Then Goto

fail

206 StatToolsVariableList Object

 StatToolsVariableList Object — AllSameLayout Property

AllSameLayout Property
Description Returns whether all variables in the list have the same
layout. That is, if they all are arranged in rows or if they
are all in columns.

Syntax Object.AllSameLayout

Arguments None.

Return Value Boolean. TRUE if all variables are arranged in rows or if

all are arranged in columns. FALSE if variables are
mixed, with some in rows, some in columns.

Example If Not myVarListObject.AllSameLayout Then Goto fail

AllSameSize Property
Description Returns whether all variables in the list have the same
number of cells.

Syntax Object.AllSameSize

Arguments None.

Return Value Boolean. TRUE if all the variables in the list contain the
same number of spreadsheet cells. FALSE if not.

Example If Not myVarListObject.AllSameSize Then Goto fail

StatTools Object Library Reference 207

StatToolsVariableList Object — ApplyUtilityFormatting Method

ApplyUtilityFormatting Method
Description Applies formatting for new variables created by a utility
analysis. A utility performs operations on data sets and
variables to create or modify existing data sets and
variables.

The method will optionally freeze the cells and resize the
columns of all the variables in the list.

Syntax Object.ApplyUtilityFormatting(Optional freeze as Boolean,

Optional fitColumns as Boolean)

Arguments freeze (Optional Boolean) – if TRUE, all Excel functions in

the variables’ ranges will be replaced with their fixed
values. Note: This can trigger an Excel recalculation to
ensure that the proper, calculated values are used. If
FALSE, this process is skipped. If left missing, the default
is determined by the UtilityLiveUpdatePreferred property.
Since the scan process can take some time, you might
bypass this step if you have already ensured all static
values have been used in your result.

fitColumns (Optional Boolean) – if TRUE (the default) the

columns of the variable ranges will be resized in order to
fully display their contents. There is a maximum and
minimum resizing width. If FALSE, no column resizing will
be performed.

Return Value None.

Example myVarListObject.ApplyUtilityFormatting

208 StatToolsVariableList Object

 StatToolsVariableList Object — Clear Method

Clear Method
Description Removes all items from the variable list.

Syntax Object.Clear

Arguments None.

Return Value None.

Example myVarListObject.Clear

Count Property
Description Returns the number of StatToolsVariable objects in the
list.

Syntax Object.Count

Arguments None.

Return Value Integer. The number of items in the variable list.

Example numVariables = myVarListObject.Count

StatTools Object Library Reference 209

StatToolsVariableList Object — HasMissingData Property

HasMissingData Property
Description Returns whether any variable in the variable list collection
has missing (i.e. blank) data cells.

Syntax Object.HasMissingData

Arguments None.

Return Value Boolean. TRUE if any variable in the collection has

missing data. FALSE if not.

Example ‘Check for missing data and fail if found:

If myVarListObject.HasMissingData Then Goto fail

HasMultiRangeVariable Property
Description Returns whether any variable in the variable list collection
is a multiple range variable.

Syntax Object.HasMultiRangeVariable

Arguments None.

Return Value Boolean. TRUE if any variables in the collection are multi-
range variables. FALSE if not.

Example ‘Check for multi-range variables and fail if found:

If myVarListObject.HasMultiRangeVariable Then Goto
fail

210 StatToolsVariableList Object

 StatToolsVariableList Object — HasNonNumericData Property

HasNonNumericData Property
Description Returns whether any variable in the variable list collection
has non-numeric cell values. Missing data is not
considered non-numeric.

Syntax Object.HasNonNumericData

Arguments None.

Return Value Boolean. TRUE if any variable in the collection has non-
numeric data

Example ‘Check for non-numeric data and fail if found:

If myVarListObject.HasNonNumericData Then Goto fail

IsStackingSet Property
Description Returns whether all variables in the variable list collection
are stacked, and if so, if they all have the same source
category variable and value variable. See the section
Data Sets, Variables, and Variable Lists of this
document for more information on stacked versus
unstacked variables.

Syntax Object.IsStackingSet

Arguments None.

Return Value Boolean. TRUE if all variables in the list are stacked from
the same source. FALSE if not.

Example ‘If the variable list doesn’t form a “stacking set” fail:
If Not myVarListObject.IsStackingSet Then Goto fail

StatTools Object Library Reference 211

StatToolsVariableList Object — Item Property

Item Property
Description Returns a specific variable, by index, from the variables in
the collection. Note this is the default method for this
object.

Syntax Object.Item(index as Integer)

Arguments index(Integer) – the index of the variable in the collection.

Return Value A StatToolsVariable object.

Example ‘These two lines of code are the same:

MsgBox myVarListObject.Item(3).Name
MsgBox myVarListObject(3).Name

MaxCellCount Property
Description Returns the number of data cells in the largest variable in
the variable list collection.

Syntax Object.MaxCellCount

Arguments None.

Return Value Long. The number of data cells in the largest variable in
the list.

Example maxCount = myVarListObject.MaxCellCount

212 StatToolsVariableList Object

 StatToolsVariableList Object — Remove Method

Remove Method
Description Removes the specified item from the list.

Syntax Object.Remove(index as Integer)

Arguments index (Integer) – the index of the item in the collection to

remove.

Return Value None.

Example ‘Remove the last item in the collection

myVarListObject.Remove(myVarListObject.Count)

StatTools Object Library Reference 213

StatToolsVariableList Object — SharedNumberFormatExcelCode Property

SharedNumberFormatExcelCode Property
Description Returns an Excel number format code (a string that can be
passed to the NumberFormat) that gives a recommended
number format for a given statistical function of the
variables.
This is similar to the NumberFormatExcelCode property of
the StatToolsVariable object, except it tries to determine a
single number format appropriate for displaying statistic of
the entire variable list, if possible. If all the variables in the
list have the same NumberFormatExcelCode property for
the formatStyle specified, this is simple, and that shared
value is returned by this function. If not, however, this
property will determine the mode that best encompasses
the different codes.
Note: You may need a number format for your own
statistic function which is not in the formatStyle list. In that
case, you either need to determine which one of the
existing statistic function is closest to your function (usually
a fairly easy task), or determine what number formatting to
use yourself.

Syntax Object.SharedNumberFormatExcelCode(Optional
formatStyle As StatToolsVariableFormula)

Arguments formatStyle (Optional StatToolsVariableFormula

Enumerated Constant) – what statistic function to get the
number format for. Must be on the following enumerated
constants values:
o StatToolsFuncAutocorrelation
o StatToolsFuncAveDev
o StatToolsFuncKurtosis
o StatToolsFuncMax
o StatToolsFuncMean (the default)
o StatToolsFuncMedian
o StatToolsFuncMin
o StatToolsFuncPercentile
o StatToolsFuncQuartile
o StatToolsFuncRange
o StatToolsFuncSkewness
o StatToolsFuncStdDev
o StatToolsFuncVariance
o StatToolsFuncCount
o StatToolsFuncSum

214 StatToolsVariableList Object

 StatToolsVariableList Object — SharedNumberFormatExcelCode Property

Return Value String. The Excel Number Format code.

Example ‘Format the cell with the recommended standard deviation

format:
myCell.NumberFormat =
myVarListObject.NumberFormatExcelCode(StatToolsFu
ncStdDev)

StatTools Object Library Reference 215

StatToolsVariableList Object — Validate Method

Validate Method
Description Performs simple validation of a variable list, which can be used to
simplify repetitive checks in an analysis’s public Validate routine.
Its exact behavior changes depending on the validation mode
passed in. This mode is usually the same value passed into the
analysis’s Validate routine.
Syntax Object.Validate(validationMode As StatToolsValidationMode,
Optional minCount, Optional maxCount)

Arguments validationMode (StatToolsValidationMode Enumerated Constant)

– controls what sort of validation occurs. One of the following
enumerated values:
• StatToolsValidationModeWriteDefaults – checks that all
variables in the list come from the currently scanned data set,
and that no variable in the list is repeated twice. Does not check
the number of variables.
• StatToolsValidationModeShowDialog – same as
StatToolsValidationModeWriteDefaults.
• StatToolsValidationModeGenerateReport – checks that all
variables in the list come from the currently scanned data set,
and that no variable in the list is repeated twice. Also checks that
the number of variables in the list is in the allowed range
specified by minCount and maxCount, if specified.

minCount (Optional Integer) – if specified, the minimum number

of variables required in the list. Only checked if validationMode is
StatToolsValidationModeGenerateReport. If not specified, there
is no minimum allowed number.

maxCount (Optional Integer) – if specified, the maximum number

of variables allowed in the list. Only checked if validationMode is
StatToolsValidationModeGenerateReport. If not specified, there
is no upper limit.
Return Value A StatToolsResult code. A zero indicates the validation passed,
while a non-zero value indicates a problem. The ResultString
method of the StatTools root object can be use to generate a
string description of the error. This result is typically passed back
as the result of an analysis’s public Validate routine.
Example ‘A public Validate routine in an analysis might have this code.
Public Function Validate(validationMode as
StatToolsValidationMode) as StatToolsResult
Validate = analysisInfo.VariableList.Validate(validationMode, 1,
MaxNumVariables)
End Function

216 StatToolsVariableList Object

 StatToolsVariables Object — Count Property

StatToolsVariables Object
Count Property
Description Returns the number of variable objects in a data set’s
variables collection.

Syntax Object.Count

Arguments None.

Return Value Integer. The number of variables in the collection.

Example numVars = myVariablesObject.Count

StatTools Object Library Reference 217

StatToolsVariables Object — Insert Method

Insert Method
Description Inserts a new variable in an existing variable into an
existing data set’s variable collection.

Note: This method will insert a new row or column into the
spreadsheet for the new variable. You can call the
InsertValidate method before calling this method to
determine if there is enough room to insert variables.

Syntax Object.Insert(newVariableName as String, Optional

newVariableRangeName as String, Optional insertPos as
Integer) As StatToolsVariable

Arguments newVariableName (String) – the name of the new variable.

newVariableRangeName (Optional String) – the range

name of the new variable. If left missing, a range name
will be created for you based on the variable’s name.

insertPos (Optional Integer) – where in the data set’s

range should the new variable be inserted. If insertPos =
1, the new variable will be placed as the first variable in the
data set. If left missing, the new variable is placed as the
last variable in the data set.

Return Value The new StatToolVariable object.

Example ‘If there is enough room, insert three new variables at the
end of the data set:
If myDataSet.Variables.InsertValidate(3) = 0 Then
myDataSet.Variables.Insert(“New Var #1”)
myDataSet.Variables.Insert(“New Var #2”)
myDataSet.Variables.Insert(“New Var #3”)
End If

InsertValidate Method
Description Determines if there is enough room to insert one or more

218 StatToolsVariables Object

 StatToolsVariables Object — InsertValidate Method
variables into an existing data set’s collection of variables.
To actually insert the variables, use the Insert method.

Syntax Object.InsertValidate(numVariablesToInsert as Integer) As

StatToolsResult

Arguments numVariablesToInsert (Integer) – The number of variables

you want to check if there is room for.

Return Value A StatToolResult code. A zero result indicates there is

sufficient room for the insertion. A non-zero result
indicates an error condition. Use the ResultString method
of the StatTools root object for a string description of the
result code.

Example ‘If there is enough room, insert three new variables at the
end of the data set:
If myDataSet.Variables.InsertValidate(3) = 0 Then
myDataSet.Variables.Insert(“New Var #1”)
myDataSet.Variables.Insert(“New Var #2”)
myDataSet.Variables.Insert(“New Var #3”)
End If

StatTools Object Library Reference 219

StatToolsVariables Object — Item Property

Item Property
Description Returns a specific variable, by index, from the
collection of variables. Note this is the default
method for this object.

Syntax Object.Item(index as Integer)

Arguments index(Integer) – the index of the variable in the

collection.

Return Value A StatToolsVariable object.

Example ‘These two lines of code are the same:

MsgBox myDataSet.Variables.Item(3).Name
MsgBox myDataSet.Variables(3).Name

Layout Property
Description Returns how the variables are laid out in the data set,
either in rows or in columns. This property is set when you
create the data set parent of the variables object, and may
not be changed subsequently.

Syntax Object.Layout

Arguments None.

Return Value A StatToolsVariableLayout enumerated constant, with one

of the two values:
o StatToolsVariableLayoutColumns
o StatToolsVariableLayoutRows

Example If myDataSet.Variables.Layout =
StatToolsVariableLayoutColumns Then
MsgBox “Columns”
Else
MsgBox “Rows”
End If

220 StatToolsVariables Object

 StatToolsVariables Object — NamesInRange Property

NamesInRange Property
Description Returns whether the first row or column of each variable in
a data set’s range is reserved for the variable name. This
property is set when you create the data set parent of the
variables object, and may not be changed subsequently.

Note: There are actually two properties here, controlled by

an optional argument, one for the primary range of a data
set and one for the secondary ranges. This distinction is
only important for multiple range data sets.

Syntax Object.NamesInRange(Optional secondaryRanges as

Boolean)

Arguments secondaryRanges (Optional Boolean) – FALSE (the

default) to return the property concerning the primary
range (i.e. the first range in a multiple range data set.)
TRUE to return the property concerning the secondary
ranges (i.e. all other ranges in a multiple range data set.)

Return Value Boolean. TRUE if names are displayed in the first cell of
the range. FALSE if not.

Example namesInPrimaryRange =
myDataSet.NamesInRange(FALSE)
namesInSecondaryRanges =
myDataSet.NamesInRange(TRUE)

StatTools Object Library Reference 221

Overview — Adding the Controls to Excel VBA

Using the STControls OCX

Overview
Each analysis you write needs to be able to display a dialog to the user to
retrieve the source data and parameters for your analysis. StatTools
provides two controls, the STControlsOptionPanel control and the
STControlsVarSelector control to make this process easier. The
STControlsOptionPanel control is a simple container control consisting of
three buttons, which provide a way for the user to request context sensitive
help, save the current dialog settings as the default settings for the
analysis, and bring up StatTools’ settings dialog. The STControlsVarSelector
control is a flexible component for allowing the user to select one or more
variables to be analyzed.
A list of all the methods, properties, and objects of these controls is listed in
the section “STControls OCX Library Reference” of this document.

Adding the Controls to Excel VBA

To use these controls in Excel, you must add them to the list of VBA’s
“Additional Controls.” To do this, bring up an Excel UserForm window in
VBA, and choose the Tools menu’s “Additional Controls” menu item.
Then select the STControls5.STControlsOptionPanel and
STControls5.STControlsVarSelector items:

222 Overview
 Overview — Attaching and Detaching the Controls
After doing so, the Excel VBA Toolbox window should have two new
controls added:

The first of these is the STControlsVarSelector control. The second, is the

STControlsOptionPanel control. They can now be added to your Excel
UserForms.

Attaching and Detaching the Controls

Both the STControlsOptionPanel and STControlsVarSelector controls must be
“attached” to StatTools before you use them. In addition they must be
“detached” when you are finished. Here is an example code snippet for a
public subroutine of a UserForm that attaches the two controls, displays
the dialog to the user, and then detaches the controls:
Public Function ShowDialog&()
Dim rc&
'Initialize the StatTools controls:
VarSelector.Attach StatTools, “MyAnalysisName”, 3
OptionPanel.Attach StatTools, “MyAnalysisName”
'Show the dialog:
rc = InitializeDialogState(): If rc <> 0 Then GoTo fail
Me.Show
If dialogWasCancelled then rc = CancelError: GoTo fail
rc = GetDialogState(): If rc <> 0 Then GoTo fail

fail:
'Detach the controls from the External StatTools Module:
VarSelector.Detach dialogWasCancelled
OptionPanel.Detach
ShowDialog = rc
End Function

Using the STControls OCX 223

Overview — The Option Panel Control
Both Attach methods require the name of the running analysis. The attach
method of the STControlsVarSelector control also requires the number of
fields (that is the number of columns containing check boxes) that the
controls should have. When you call the Detach of the
STControlsVarSelector control, you must pass whether the dialog was
cancelled or not.

The Option Panel Control

The STControlsOptionPanel control (shown above) is made up of three

buttons. The Help button provides context sensitive help (if available) for
the analysis. The Save as Default button allows the user to write the
current dialog settings as the default settings for new workbooks. The
Settings button brings up the StatTools Settings dialog.
Make sure to call the Attach method of the control before you use it, and
the Detach method when you are finished with it as described in the
previous section.
The Help Button When the user clicks on the Help button, the context page of the analysis’
help file will be displayed if it exists. See the Creating an Analysis Pack
Help File section of this document for more information on creating a help
file page for your analysis. If no help file page exists, the help button will
be disabled.
The Save as When the user clicks on the Save as Default button, a SaveAsDefault Event
Default Button will be generated, and it is your responsibility to respond to that event and
save the current dialog state as the defaults for new workbooks. The
following code snippet shows an example:
Private Sub OptionPanel_SaveAsDefault()
'Make sure the dialog settings are valid:
If Not Validate(False) Then Exit Sub
'Ask the user if they really want to do this:
If Not StatTools.AskYesNo("Are you sure you want to save these settings as
defaults for all new Excel workbooks?") Then Exit Sub
SaveDefaults()
End Sub
See the Template.xls example model in the Writing a Custom Analyses
section of this document for the recommended procedure for saving
defaults.

224 Overview
 Overview — The Variable Selector Control

The Variable Selector Control

The dialogs of most analyses need to provide a mechanism for the user to
select one or more variables to analyze. The STControlsVarSelector control
(shown above) provides a convenient and flexible way to ask for this
information.
Make sure to call the Attach method of the control before you use it, and
the Detach method when you are finished with it as described in the
previous section.
Parts of the The variable selector control is made of four parts: the caption, the data
Variable set selector, the data format selector, and the list of variables and fields.
Selector Control
The caption is the text that appears at the very top of the control, and
which explains to the user the number (and sometimes the type) of
variables that should be selected. The caption can be set using either the
StdCaption or Caption properties of the control. The StdCaption property
allows you to choose from a small number of default captions. Using this
makes it easy to be consistent with the core analysis pack’s captions. If
none of the standard captions meet your needs, use the Caption method to
write any text you desire in the caption.
The data set selector, just beneath the caption, lets the user select the active
data set of the control. Only the variables in the chosen data set will be
shown in the grid display underneath. The user can also set the control to
show all data sets simultaneously. The ActiveDataSet property of the
control corresponds to this setting.

Using the STControls OCX 225

Overview — The Variable Selector Control
The Format button, at the top-right allows the user to select if the control is
set to stacked or unstacked mode. The selected value can be read or set
using the DataFormat property. You can control the display of this button
(or even make it entirely invisible) using the DataFormatMode property.
Keep in mind, it is the responsibility of your code to make any changes to
the control’s appearance (such as hiding some fields and showing others)
when this setting changes. You are informed if the user changes this
property by DataFormatChange event.
Finally, the remainder of the control is the variable list itself. Here, the
name of each variable in the active data set, along with its Excel
spreadsheet address is displayed. And to the left is one or more
checkboxes, which the user can check to select the variables to be analyzed.
Each column of checkboxes is known as a Field of the control. You are
informed if the user clicks a checkbox by the SelectionChange event.
Variable When you call the Attach method of the control, you must pass the number
Selector of fields (that is, the number of columns of checkboxes) the control uses.
“Fields” Each field is represented by a STControlsVarSelectorField object and the
entire collection of fields by a STControlsVarSelectorFields collection object.
The caption of a field is the text label at the top of the column of
checkboxes. Typically only three or four characters (depending on the
exact characters being displayed) will fit in the header. Typical captions
are “Cat”, “Val”, “C1”, “C2”, etc. It is also very common, usually when
there is but a single field, to have a blank field caption.
You can check or uncheck the checkboxes in a field, or retrieve the
checkboxes that are checked using the Selection or SelectionList properties of
the field. The Selection property is useful if the selection is limited to a
single item. The SelectionList property is used when there is potentially
more than one selected variable in a single field. The GetSelectionCount
method returns the number of selected variables in the field without
returning which variables were selected. For advanced users, the pair of
methods GetStackedPairFromVariableList and SetStackedPairFromVariableList
are convenient for setting and retrieving stacked variable information.

226 Overview
 Overview — The Variable Selector Control
If you know that a given field must have at most one selected variable, you
should set the field’s EnforceSingleSelection property. If the user clicks on a
field’s checkbox when this property set, the control will automatically
uncheck other selections in the same field. The
EnforceSingleSelectionPerRow property of the STControlsVarSelector control
does a similar thing, except it enforces that a given variable may be
selected in only a single field.
It is often convenient to hide one or more fields. For example, if your
control supports both stacked and unstacked data formats, a good way to
support both formats is to configure the control with three fields, one for
the unstacked case, and two for the category and value variables of the
stacked case. Then if the user switches data format modes, you simply
need hide or unhide the appropriate fields. Use the Visible property of the
STControlsVarSelectorField object to hide and unhide fields.
Validation When the user clicks the OK button of your dialog, you will usually want
to check that there is a proper number of selected variables, and perhaps
that the variables selected meet certain requirements. While it is certainly
possible for you to do all your own validation of selected variables, by
retrieving the selected variables from the control (and sometimes for
custom validation you will need to do this very thing) the
STControlsValidation object can make your life much easier. It also help
you remain consistent with other StatTools analyses.
Each STControlsVarSelectorField object has a child STControlsValidation
object, which can be accessed via the Validation property. The validation
object contains a large number of properties which you can set
individually to control the validation process. Typically, however, you
will use the SetDefaultConfiguration method to set the validation object to a
base state, and then set one or two other properties to non-default values.
For example, to create a field that requires between two and five variables,
all which must have the size (bigger than ten cells), you could write the
code:
With VarSelector.Fields(1).Validation
.SetDefaultConfiguration STControlsNumericVariables, 2, 5
.CellCountMatching = STControlsMatchWithinField
.CellCountMin = 10
End With
When the user clicks the OK button of your dialog, call the Validate method
of the STControlsVarSelector control to actually perform the validation. If
the method returns a zero, the validation passed. If the method returns a
non-zero result the validation failed and the dialog should not be
dismissed.
Using the STControls OCX 227
Overview — The Variable Selector Control

228 Overview
 STControlsOptionPanel Object — Attach Method

STControls OCX Reference

STControlsOptionPanel Object
Attach Method

Description Initializes the option panel control to work with StatTools

and the analysis specified. This method must be called
before any other methods or properties of the
STControlsOptionPanel object. Make sure to call the
Detach method when you are finished with the control.

See the section “Using the STControls OCX” of this

document for more information.

Syntax Object.Attach(spObj as StatTools, analysisName as

String)

Arguments spObj (StatTools Root Object) – the root StatTools object.

analysisName (String) – the name of the analysis that the

option panel control is being displayed for.

Return Value None.

Example ‘Attach the control before using it:

OptionPanel.Attach StatTools, “OneVarSummary”
…
‘Use the control
…
‘Detach the control when finished with it:
OptionPanel.Detach

STControls OCX Reference 229

STControlsOptionPanel Object — Detach Method

Detach Method
Description Informs the control that you are finished using it. This
method should be called when you are finished with the
STControlsOptionPanel object. Make sure to call the
Attach method before you use the control.

See the section “Using the STControls OCX” of this

document for more information.

Syntax Object.Detach

Arguments None.

Return Value None.

Example ‘Attach the control before using it:

OptionPanel.Attach StatTools, “OneVarSummary”
…
‘Use the control
…
‘Detach the control when finished with it:
OptionPanel.Detach

SaveAsDefault Event
Description An event that fires when the user clicks the “Save as
Default” icon.

Syntax Public Sub Object_SaveAsDefault()

Arguments None.

Return Value None.

Example Public Sub OptionControl_SaveAsDefault()

‘Handle the save as default call here
End Sub

230 STControlsOptionPanel Object

 STControlsValidation Object — CategoryCountMax Property

STControlsValidation Object
CategoryCountMax Property
Description Sets or returns the maximum number of categories (that is
distinct text values) that are allowed in the variables being
validated. A value of zero suppresses any check for
maximum number of categories. The response to having
too many categories is controlled by the
CategoryOverflowResponse property.

If validating a variable expected to contain numeric values,

this value should be zero.

Syntax Object.CategoryCountMax

Arguments None.

Return Value The maximum number of categories allowed or zero for no

checking.

Example ‘Display a warning if more than 4 categories are present:

With VarSelector.Fields(1).Validation
.CategoryOverflowResponse =
STControlsResponseWarningMessage
.CategoryCountMax = 4
End With

STControls OCX Reference 231

STControlsValidation Object — CategoryCountMin Property

CategoryCountMin Property
Description Sets or returns the minimum number of categories (that is
distinct text values) that are allowed in variables being
validated. A value of zero suppresses any check for
minimum number of categories. The response to having
too few categories is an error, never a warning.

If validating a variable expected to contain numeric values,

this value should be zero.

Syntax Object.CategoryCountMin

Arguments None.

Return Value The minimum number of allowed categories, or zero for no

checking.

Example ‘Display a warning if less than 2 categories are present:

VarSelector.Fields(1).Validation.CategoryCountMin = 2

CategoryHeuristic Property
Description Sets or returns whether the user should be warned if a
variable doesn’t appear to be a category variable. This
validation step will call the CheckCategoryHeuristic
method for each of the variables being validated, and
warns the user if any one of them fails the check.

Syntax Object.CategoryHeuristic

Arguments None.

Return Value Boolean. TRUE if variables should be tested with the

category heuristic. FALSE if not.

Example VarSelector.Fields(1).Validation.CategoryHeuristic =
TRUE

232 STControlsValidation Object

 STControlsValidation Object — CategoryOverflowResponse Property

CategoryOverflowResponse Property
Description Sets or returns what happens if there are more categories
than the value given in the CategoryCountMax property.

Syntax Object.CategoryOverflowResponse

Arguments None.

Return Value STControlsResponseType Enumerated Constant. One of

the following values:
o STControlsResponseIgnore – no action will be
taken.
o STControlsResponseWarningMessage – a
warning will be presented to the user. They may
cancel the operation, or ignore the warning.
o STControlsResponseErrorMesage – an error
message will be presented to the user, and the
validation will fail.

Example ‘Display a warning if more than 4 categories are present:

With VarSelector.Fields(1).Validation
.CategoryOverflowResponse =
STControlsResponseWarningMessage
.CategoryCountMax = 4
End With

STControls OCX Reference 233

STControlsValidation Object — CellCountMatching Property

CellCountMatching Property
Description Sets or returns whether every variable being validated
must have the same number of data cells. This check can
be performed in two fashions. First, it can be done only on
the selected variables within the field. Second, it can be
done on all selected variables in all fields with the
matchingStyle option set to STControlsMatchAcrossFields.

Syntax Object.CellCountMatching

Arguments None.

Return Value STControlsMatchingStyle Enumerated Constant, with

possible values:
o STControlsNoMatching – no check is performed
on the variables.
o STControlsMatchWithinField – the size matching
check is only performed on the selected variables
within the same field.
o STControlsMatchAcrossFields – all variables with
this selected option are checked as a single unit.
If any one of them has a different size, the check
will fail.

Example ‘The selected variables in field 1 must all be of the same

size
VarSelector.Fields(1).Validation.CellCountMatching =
STControlsMatchWithinFields

‘The selected variables of fields 2 and 3 (grouped) must all

be the same size:
VarSelector.Fields(2).Validation.CellCountMatching =
STControlsMatchAcrossFields
VarSelector.Fields(3).Validation.CellCountMatching =
STControlsMatchAcrossFields

234 STControlsValidation Object

 STControlsValidation Object — CellCountMin Property

CellCountMin Property
Description Sets or returns the minimum number of data values that
must be present in the variables being validated. A value
of zero suppresses any check for the minimum number of
values.

By setting the CellCountNonMissingOnly property, you can

control whether all cell values are used in the validation
(regardless if they are filled or blank) or if only non-blank
cells are counted.

Syntax Object.CellCountMin

Arguments None.

Return Value The minimum number of data values in the variables being
validated, or zero if the check is not being performed.

Example ‘Make sure there are between 5 and 15 non-blank cells

With VarSelector.Fields(1).Validation
.CellCountNonMissingOnly = TRUE
.CellCountMin = 5
.CellCountMax = 15
End With

STControls OCX Reference 235

STControlsValidation Object — CellCountMax Property

CellCountMax Property
Description Sets or returns the maximum number of data values that is
allowed in the variables being validated. A value of zero
suppresses any check for the maximum number of values.

By setting the CellCountNonMissingOnly property, you can

control whether all cell values are used in the validation
(regardless if they are filled or blank) or if only non-blank
cells are counted.

Syntax Object.CellCountMax

Arguments None.

Return Value The maximum number of data values allowed in the

variables being validated, or zero if the check is not being
performed.

Example ‘Make sure there are between 5 and 15 non-blank cells

With VarSelector.Fields(1).Validation
.CellCountNonMissingOnly = TRUE
.CellCountMin = 5
.CellCountMax = 15
End With

236 STControlsValidation Object

 STControlsValidation Object — CellCountNonMissingOnly Property

CellCountNonMissingOnly Property
Description Sets or returns whether the CellCountMin and
CellCountMax properties perform their check on all cell
values (regardless if they are blank or occupied) or if it
performs it on only the non-missing cell values.

Syntax Object.CellCountNonMissing

Arguments None.

Return Value Boolean. TRUE if the validation check is performed only

on the non-missing values of the variables. FALSE if the
validation is performed on all cells values.

Example ‘Make sure there are between 5 and 15 non-blank cells

With VarSelector.Fields(1).Validation
.CellCountNonMissingOnly = TRUE
.CellCountMin = 5
.CellCountMax = 15
End With

STControls OCX Reference 237

STControlsValidation Object — Enabled Property

Enabled Property
Description Sets or returns whether the validation object is enabled. A
disabled validation object performs no validation at all.
Note: Even if this property is set to TRUE to enable the
validation, if the STControlsField parent object is invisible,
the validation will not be performed unless the
ValidateEvenIfInvisible property is set to TRUE.

By default, when a STControlsField is created, its

validation object is disabled until you set the Enabled
property to TRUE, or call SetDefaultConfiguration method.

Syntax Object.Enabled

Arguments None.

Return Value Boolean. TRUE if the validation object is enabled. FALSE

if not.

Example VarSelector.Fields(1).Validation = TRUE

238 STControlsValidation Object

 STControlsValidation Object — MissingDataBeginningResponse Property

MissingDataBeginningResponse Property
Description Sets or returns the response of the validator when missing
data is found at the “beginning” of the data set. The
beginning of the data set is all the data before the first
non-blank cell in the data set.

There are three possible responses. First, The missing

data may be ignored entirely. Second, a warning message
may be displayed to the user, warning them of the missing
data and giving them an opportunity to cancel the
operation. Finally, an error message may be displayed to
the user, and the validation fails.

There are three properties that control the validation of

missing data. MissingDataBeginningResponse,
MissingDataMiddleResponse, and
MissingDataEndResponse. These can conveniently be
set all at the same time using the MissingDataSetAll
method.

Syntax Object.MissingDataBeginningResponse

Arguments None.

Return Value A STControlsResponse enumerated constant. Must be

one of the following values:
o STControlsResponseIgnore
o STControlsResponseWarningMessage
o STControlsResponseErrorMesage

Example ‘Ignore missing data at the beginning, put up a warning for

missing data
‘at the end, and put up an error message for missing data
in the middle
With VarSelector.Fields(1).Validation
.MissingDataBeginningResponse =
STControlsResponseIgnore
.MissingDataMiddleResponse =
STControlsResponseErrorMessage
.MissingDataEndResponse =
STControlsResponseWarningMessage
End With

STControls OCX Reference 239

STControlsValidation Object — MissingDataEndResponse Property

MissingDataEndResponse Property
Description Sets or returns the response of the validator when
missing data is found at the “end” of the data set.
The end of the data set is all the data after the last
non-blank cell in the data set.

There are three possible responses. First, The

missing data may be ignored entirely. Second, a
warning message may be displayed to the user,
warning them of the missing data and giving them an
opportunity to cancel the operation. Finally, an error
message may be displayed to the user, and the
validation fails.

There are three properties that control the validation

of missing data. MissingDataBeginningResponse,
MissingDataMiddleResponse, and
MissingDataEndResponse. These can conveniently
be set all at the same time using the
MissingDataSetAll method.

Syntax Object.MissingDataEndResponse

Arguments None.

Return Value A STControlsResponse enumerated constant. Must

be one of the following values:
o STControlsResponseIgnore
o STControlsResponseWarningMessage
o STControlsResponseErrorMesage

Example ‘Ignore missing data at the beginning, put up a

warning for missing data
‘at the end, and put up an error message for missing
data in the middle
With VarSelector.Fields(1).Validation
.MissingDataBeginningResponse =
STControlsResponseIgnore
.MissingDataMiddleResponse =
STControlsResponseErrorMessage
.MissingDataEndResponse =
STControlsResponseWarningMessage
End With

240 STControlsValidation Object

 STControlsValidation Object — MissingDataMiddleResponse Property

MissingDataMiddleResponse Property

Description Sets or returns the response of the validator when missing

data is found at the “middle” of the data set. The middle of
the data set is all the data after (and including) the first
non-blank cell and before (and including) the last non-
blank cell.
There are three possible responses. First, The missing
data may be ignored entirely. Second, a warning
message may be displayed to the user, warning them of
the missing data and giving them an opportunity to cancel
the operation. Finally, an error message may be displayed
to the user, and the validation fails.
There are three properties that control the validation of
missing data. MissingDataBeginningResponse,
MissingDataMiddleResponse, and
MissingDataEndResponse. These can conveniently be
set all at the same time using the MissingDataSetAll
method.

Syntax Object.MissingDataBeginningResponse

Arguments None.

Return Value A STControlsResponse enumerated constant. Must be

one of the following values:
o STControlsResponseIgnore
o STControlsResponseWarningMessage
o STControlsResponseErrorMesage

Example ‘Ignore missing data at the beginning, put up a warning for

missing data
‘at the end, and put up an error message for missing data
in the middle
With VarSelector.Fields(1).Validation
.MissingDataBeginningResponse =
STControlsResponseIgnore
.MissingDataMiddleResponse =
STControlsResponseErrorMessage
.MissingDataEndResponse =
STControlsResponseWarningMessage
End With

STControls OCX Reference 241

STControlsValidation Object — MissingDataSetAll Method

MissingDataSetAll Method

Description This method is a shortcut for quickly setting the

MissingDataBeginningResponse,
MissingDataMiddleResponse, and MissingDataEndResponse
properties to the same value.

Syntax Object.MissingDataSetAll(newValue As
STControlsResponseType)

Arguments newValue (STControlsReponseType Enumerated Constant) –

one of the following values:
o STControlsResponseIgnore
o STControlsResponseWarningMessage
o STControlsResponseErrorMesage

Return Value None.

Example With VarSelector.Fields(1).Validation

‘This line of code:

.MissingDataSetAll(STControlsResponseWarningMessage)

‘Is equivalent to these three:

.MissingDataBeginningResponse =
STControlsResponseWarningMessage
.MissingDataMiddleResponse =
STControlsResponseWarningMessage
.MissingDataEndResponse =
STControlsResponseWarningMessage
End With

242 STControlsValidation Object

 STControlsValidation Object — MultiRangeVariablesAllowed Property

MultiRangeVariablesAllowed Property
Description Returns or sets whether the variables being validated are
allowed to be made up of multiple Excel ranges.

Syntax Object.MultiRangeVariablesAllowed

Arguments None.

Return Value Boolean. TRUE if multi-range variables are allowed.

FALSE if not.

Example VarSelector.Fields(1).Validation.MultiRangeVariablesAll
owed = FALSE

NonNumericDataResponse Property
Description Sets or returns the response when non-numeric data is
found in the variables being validated. Note: Blank data is
not treated as non-numeric data.
There are three possible responses. First, The missing
data may be ignored entirely. Second, a warning message
may be displayed to the user, warning them of the missing
data and giving them an opportunity to cancel the
operation. Finally, an error message may be displayed to
the user, and the validation fails.

Syntax Object.NonNumericDataResponse

Arguments None.

Return Value A STControlsResponse enumerated constant. Must be

one of the following values:
o STControlsResponseIgnore
o STControlsResponseWarningMessage
o STControlsResponseErrorMesage

Example VarSelector.Fields(1).Validation.NonNumericDataRespons
e = STControlsResponseWarningMessage

STControls OCX Reference 243

STControlsValidation Object — NumericRangeMax Property

NumericRangeMax Property
Description Sets or returns the maximum numeric data value allowed
in the variables being validated. If set to the special value
StatToolsInfinity (which is the default value) there is no
upper limit to the numeric values in the variables.

Note: This check ignores non-numeric values and blank

values. Use the NonNumericDataResponse,
MissingDataBeginningResponse,
MissingDataEndResponse to check for missing and non-
numeric data.

Syntax Object.NumericRangeMax

Arguments None.

Return Value Double. The maximum allowed numeric value, or

StatToolsInfinity to suppress the check.

Example ‘Make sure all numeric values are between 0 and 100:
With VarSelector.Fields(1).Valiadation
.NumericRangeMin = 0
.NumericRangeMax = 100
End With

244 STControlsValidation Object

 STControlsValidation Object — NumericRangeMin Property

NumericRangeMin Property
Description Sets or returns the minimum numeric data value
allowed in the variables being validated. If set to the
special value StatToolsMinusInfinity (which is the
default value) there is no lower limit to the numeric
values in the variables.

Note: This check ignores non-numeric values and

blank values. Use the NonNumericDataResponse,
MissingDataBeginningResponse,
MissingDataEndResponse to check for missing and
non-numeric data.

Syntax Object.NumericRangeMin

Arguments None.

Return Value Double. The minimum allowed numeric value, or

StatToolsMinusInfinity to suppress the check.

Example ‘Make sure all numeric values are between 0 and 100:
With VarSelector.Fields(1).Valiadation
.NumericRangeMin = 0
.NumericRangeMax = 100
End With

STControls OCX Reference 245

STControlsValidation Object — RowVariablesAllowed Property

RowVariablesAllowed Property
Description Returns or sets whether the variables being validated are
allowed to be oriented in rows.

Syntax Object.RowVariablesAllowed

Arguments None.

Return Value Boolean. TRUE if variables may be oriented in rows.

FALSE if they must have a column layout.

Example ‘Make sure variables in rows are not allowed:

VarSelector.Fields(1).Validation.RowVariablesAllowed =
FALSE

SelectionCountMax Property
Description Sets or returns the maximum number of variables that may
be selected in the given field being validated. If set to
zero, there is not maximum number of variables.

Syntax Object.SelectionCountMax

Arguments None.

Return Value Integer. The maximum number of variables that may be

selected in the field being validated.

Example ‘Make sure between 2 and 20 variables are selected in

field #1:
With VarSelector.Fields(1).Validation
.SelectionCountMin = 2
.SelectionCountMax = 20
End With

246 STControlsValidation Object

 STControlsValidation Object — SelectionCountMin Property

SelectionCountMin Property
Description Sets or returns the minimum number of variables that may
be selected in the given field being validated. If set to zero,
there is not minimum number of variables.

Syntax Object.SelectionCountMin

Arguments None.

Return Value Integer. The minimum number of variables that may be

selected in the field being validated.

Example ‘Make sure between 2 and 20 variables are selected in field

#1:
With VarSelector.Fields(1).Validation
.SelectionCountMin = 2
.SelectionCountMax = 20
End With

STControls OCX Reference 247

STControlsValidation Object — SetDefaultConfiguration Method

SetDefaultConfiguration Method
Description Sets the validation object to one of several preset
configurations.
Instead of setting up a validation object from scratch, setting
potentially a dozen or more properties, it is usually much more
efficient to call this method to set the STControlsValidation
object to one of the preset base configurations and then apply
a smaller number of changes to arrive at the final configuration.

Syntax Object.SetDefaultConfiguration(whichDefault As
STControlsDefaultValidationConfiguration, Optional
selectionCountMin as Integer, Optional selectionCountMax as
Integer, Optional categoryCountMin as Integer, Optional
categoryCountMax as Integer)
Arguments whichDefault (STControlsDefaultValidationConfiguration
Enumerated Constant) – one of the following constant values:
o STControlsNoValidation
o STControlsNumericVariables
o STControlsStackedCategoryVariable
o STControlsStackedValueVariable
o STControlsTextVariables
Each of these preset configurations has a default set of
validation properties as shown in the table below:
selectionCountMin (Optional Integer) – sets the
SelectionCountMin property. The default value is zero if the
argument is missing.
selectionCountMax (Optional Integer) – sets the
SelectionCountMax property. The default value is zero if the
argument is missing.
categoryCountMin (Optional Integer) – sets the
CategoryCountMin property. The default value is zero if the
argument is missing.
categoryCountMax (Optional Integer) - sets the
CategoryCountMax property. The default value is zero if the
argument is missing.

Return Value None.

Example VarSelector.Fields(1).Validation.SetDefaultConfiguration
STControlsTextVariables

248 STControlsValidation Object

 STControlsValidation Object — SetDefaultConfiguration Method
Stacked Stacked
Validation
NoValidation Numeric Cat Val Text
Properties for
Preset meth. meth. meth.
Configurations CategoryCountMax meth. param param param param meth. param
meth. meth. meth.
CategoryCountMin meth. param param param param meth. param
CategoryHeuristic FALSE FALSE TRUE FALSE FALSE
CategoryOverflowResponse Ignore Ignore Warning Ignore Ignore
MatchAc
NoMatchi MatchAcr rossFiel
CellCountMatching NoMatching ng ossFields ds NoMatching
CellCountMax 0 0 0 0 0
CellCountMin 0 0 0 0 0
CellCountNonMissingOnly FALSE FALSE FALSE FALSE FALSE
Enabled FALSE TRUE TRUE TRUE TRUE
MissingDataBeginningResponse Ignore Warning Warning Warning Ignore
MissingDataEndResponse Ignore Warning Warning Warning Ignore
MissingDataMiddleResponse Ignore Warning Warning Warning Ignore
MultiRangeVariablesAllowed TRUE TRUE TRUE TRUE TRUE
NonNumericDataResponse Ignore Warning Ignore Warning Ignore
NumericRangeMax +INF +INF +INF +INF +INF
NumericRangeMin -INF -INF -INF -INF -INF
RowVariablesAllowed TRUE TRUE TRUE TRUE TRUE
meth. meth. meth.
SelectionCountMax meth. param param param param meth. param
meth. meth. meth.
SelectionCountMin meth. param param param param meth. param
SingleDataSet FALSE FALSE FALSE FALSE FALSE
ValidateEvenIfInvisible FALSE FALSE FALSE FALSE FALSE

STControls OCX Reference 249

STControlsValidation Object — SingleDataSet Property

SingleDataSet Property
Description Returns or sets whether all the variables being validated
when the field must belong to the same data set object.

Syntax Object.SingleDataSet

Arguments None.

Return Value Boolean. TRUE if all variables being validation must come
from the same data set. FALSE if not.

Example VarSelector.Fields(1).Validation.SingleDataSet = TRUE

ValidateEvenIfInvisible Property
Description Returns or sets whether the validation will occur even if the
parent STControlsField object is not visible. Normally, you
will not wish to do this.

Syntax Object.ValidateEvenIfInvisible

Arguments None.

Return Value Boolean. TRUE to perform validation even if parent field is

invisible. FALSE to suppress validation when parent field
is invisible.

Example VarSelector.Fields(1).Validation.ValidateEvenIfInvisible =
TRUE

250 STControlsValidation Object

 STControlsVarSelector Object — ActiveDataSet Property

STControlsVarSelector Object
ActiveDataSet Property
Description Returns or sets the data set that is currently shown in the
Data Set combo box. If that control is set to display “All
Data Sets” the object is “Nothing.”

Syntax Object.ActiveDataSet

Arguments None.

Return Value A StatToolsDataSet Object, which is the currently active

data set, or “Nothing” if the control is in “All Data Sets”
mode.

Note: For complicated internal reasons, the object is

always returned as a “late-bound” generic object, as
opposed to being set to an early-bound StatToolsDataSet
object.

Example ‘Get the currently active data set

Set activeDataSet = VarSelector.ActiveDataSet

STControls OCX Reference 251

STControlsVarSelector Object — Attach Method

Attach Method
Description Initializes the variable selector control to work with
StatTools and the analysis specified. At this point the
number of fields (i.e. the number of columns containing
check boxes) that the control should display must be set.
This method must be called before any other methods or
properties of the STVarSelector object. Make sure to call
the Detach method when you are finished with the control.

See the section “Using the STControls OCX” of this

document for more information.

Syntax Object.Attach(spObj As StatTools, analysisName as

String, numFields as Integer)

Arguments spObj (StatTools Root Object) – the root StatTools object.

analysisName (String) – the name of the analysis that the

option panel control is being displayed for.

numFields (Integer) – the number of independent fields

(columns with check boxes) should be created. The
minimum number of fields is one. The maximum number
of fields is nine.

Return Value None.

Example ‘Attach the control before using it.

‘And initialize it to have 3 independent fields:
VarSelector.Attach StatTools, “OneVarSummary”, 3
…
‘Use the control
…
‘Detach the control when finished with it:
VarSelector.Detach dialogWasCancelled

252 STControlsVarSelector Object

 STControlsVarSelector Object — Caption Property

Caption Property
Description Sets or returns the caption of the control. Use this
property to set a custom caption of arbitrary text. Use the
StdCaption property to set the caption to one of the
standard, built-in captions.

Syntax Object.Caption

Arguments None.

Return Value String. The text of the caption.

Example VarSelector.Caption = “This is my caption”

STControls OCX Reference 253

STControlsVarSelector Object — DataFormat Property

DataFormat Property
Description Sets or returns the current data format. The two formats
are “stacked” and “unstacked.” The related
DataFormatMode property controls which options are
allowed for this property and if the user is allowed to
change them.

Note: This setting only controls what is shown in the

control that drops down when the user click the “Data
Format” button in the control. Your code is responsible for
implementing whatever changes to the control’s interface
are required when the user changes this setting. Your
code will receive a DataFormatChange event when the
user changes this parameter, but changing the property in
your code will not raise that event.

See the section Data Sets, Variables, and Variable Lists

of this document for more information about stacked and
unstacked variables.

Syntax Object.DataFormat

Arguments None.

Return Value A STControlsDataFormat Enumerated Constant with the

following possible values:
o STControlsDataFormatUnstacked
o STControlsDataFormatStacked

Example ‘Set the control to allow both stacked and unstacked

modes
‘And set the current state of the control to be unstacked:
With VarSelector
.DataFormatMode = STControlsBoth
.DataFormat = STControlsDataFormatUnstacked
End With

254 STControlsVarSelector Object

 STControlsVarSelector Object — DataFormatChange Event

DataFormatChange Event
Description Raised when the user changes the DataFormat property
via the control’s user interface. Your code is responsible
for implementing whatever changes to the control’s
interface are required when the user changes this setting.

Syntax Object_DataFormatChange(newFormat As
STControlsDataFormat)

Arguments newFormat (STControlsDataFormat Enumerated

Constant) – the new data format, selected by the user.
One of the following values:
o STControlsDataFormatUnstacked
o STControlsDataFormatStacked

Return Value None.

Example Public Sub VarSelector_DataFormatChange(newFormat

as STControlsDataFormat)

‘Handle the event here…

End Sub

STControls OCX Reference 255

STControlsVarSelector Object — DataFormatMode Property

DataFormatMode Property
Description Sets or returns how the “Data Format” button should be
configured. It can be set to allow either one or both of the
stacked and unstacked formats, or alternatively, the entire
control can be removed if it is not relevant.

See the section Data Sets, Variables, and Variable Lists

of this document for more information about stacked and
unstacked variables.

Syntax Object.DataFormatMode

Arguments None.

Return Value STControlsDataFormatMode Enumerated Constant. One

of the values:
o STControlsStackedOnly
o STControlsUnstackedOnly
o STControlsBoth
o STControlsInvisible

Example ‘Set the control to allow both stacked and unstacked

modes
‘And set the current state of the control to be unstacked:
With VarSelector
.DataFormatMode = STControlsBoth
.DataFormat = STControlsDataFormatUnstacked
End With

256 STControlsVarSelector Object

 STControlsVarSelector Object — Detach Method

Detach Method
Description Informs the control that you are finished using it. This
method should be called when you are finished with the
STVarSelector control. Make sure to call the Attach
method before you use the control.

See the section “Using the STControls OCX” of this

document for more information.

Syntax Object.Detach(dialogWasCancelled as Boolean)

Arguments dialogWasCancelled (Boolean) – you must pass whether

the dialog containing the control was dismissed because
the dialog was cancelled or not. If the dialog was not
cancelled, information will be stored in the active
workbook so that the same control will come up in the
same configuration the next time it is displayed in the
context of the same active workbook.

Return Value None.

Example ‘Attach the control before using it.

‘And initialize it to have 3 independent fields:
VarSelector.Attach StatTools, “OneVarSummary”, 3
…
‘Use the control
…
‘Detach the control when finished with it:
VarSelector.Detach dialogWasCancelled

STControls OCX Reference 257

STControlsVarSelector Object — EnforceSingleSelectionPerRow Property

EnforceSingleSelectionPerRow Property

Description Returns or sets whether each variable may be selected in

only a single field. If set to TRUE, the control will, when
the user selects a variable’s checkbox for a given field,
unselect all other field checkboxes for the same variable.
In other words, there will be at most a single checked item
per row of the control. Note: This will not change fields
which have been made invisible.
The STControlsVarSelectorField object has a property
called EnforceSingleSelection for doing a similar thing with
columns instead of rows.

Syntax Object.EnforceSingleSelection

Arguments None.

Return Value Boolean. TRUE if at most one field may be selected per
variable. FALSE if any number of fields may be selected
per variable.

Example VarSelector.EnforceSingleSelectionPerRow = TRUE

258 STControlsVarSelector Object

 STControlsVarSelector Object — Fields Property

Fields Property
Description Returns a STControlsVarSelectorFields object containing
a collection of all the STControlsVarSelectorField objects
in the control.

Syntax Object.Fields

Arguments None.

Return Value A STControlsVarSelectorFields object.

Example ‘Count the total number of selected items:

For each oneField in VarSelector.Fields
totalCount = totalCount + oneField.GetSelectionCount()
Next

SelectionChange Event
Description Raised when the user clicks in any field’s check box.

Syntax Object_SelectionChange()

Arguments None.

Return Value None.

Example Private Sub VarSelector_SelectionChange()

‘Handle the selection change here….
End Sub

STControls OCX Reference 259

STControlsVarSelector Object — StdCaption Property

StdCaption Property
Description Sets the caption of the control to one of several standard
string values. Use the Caption property to set a custom
caption to an arbitrary text string.

Syntax Object.StdCaption

Arguments None.

Return Value A STControlsStdCaption Enumerated Constant. One of the

following values:
o STControlsStdCaptionOne
o STControlsStdCaptionOneOrMore
o STControlsStdCaptionTwo
o STControlsStdCaptionTwoOrMore
o STControlsStdCaptionStackedPair
o STControlsStdCaptionOneSizeOneValue
o STControlsStdCaptionIndependentsAndDependent
o STControlsStdCaptionBlocksAndOneDependent

Example VarSelector.StdCaption =
STControlsStdCaptionOneOrMore

260 STControlsVarSelector Object

 STControlsVarSelector Object — Validate Method

Validate Method
Description Causes the control to validate all fields based on the current
settings in each field's validation object.

Syntax Object.Validate(Optional suppressMessaging As Boolean)

Arguments suppressMessaging (Optional Boolean) – if FALSE (the default)

the control will display error and warning messages to the user as
they arise. If TRUE, the control will suppress all messaging and
simply return whether the validation passed or failed. When
messaging is suppressed, all warning messages are treated as if
the user chose the “OK” button.

Return Value A STControlsValidationResult Enumerated value. Usually you

only care if the result is zero (meaning the validation passed) or
non-zero (meaning the validation failed for some reason or
another.) If you are looking for a specific failure codes, they are:
o STControlsValidationOK
o STControlsValidationCancelled
o STControlsValidationMultiRangeVariableInField
o STControlsValidationRowVariableInField
o STControlsValidationVariablesInMultipleDataSets
o STControlsValidationBadSelectionCount
o STControlsValidationBadCellCount
o STControlsValidationVariableOutOfLegalNumericRange
o STControlsValidationCellSizeMismatch
o STControlsBadCategoryVariable
o STControlsValidationBadCategoryCount
o STControlsValidationNonNumericData
o STControlsValidationMissingData

Example If VarSelector.Validate <> 0 Then Goto fail

STControls OCX Reference 261

STControlsVarSelector Object — Validate Method

262 STControlsVarSelector Object

 STControlsVarSelectorField Object — Caption Property

STControlsVarSelectorField Object
Caption Property
Description Sets the caption (the text in the header row for this field.)
Note, this caption is limited to an extremely small number
of characters. Typically only three or four characters
(depending on the exact characters being displayed) will fit
in the header. Typical captions are “Cat”, “Val”, “C1”, “C2”,
etc. It is also very common, usually when there is a single
field, to have a blank field caption.

Syntax Object.Caption

Arguments None.

Return Value String. The caption of the field.

Example VarSelector.Fields(1).Caption = “Cat”

VarSelector.Fields(2).Caption = “Val”

EnforceSingleSelection Property
Description Returns or sets whether more than one variable may be
selected in a given field. If this property is set, and the
user clicks a checkbox in the field, the control will ensure
that all other check boxes in the same field are unchecked.

Syntax Object.EnforceSingleSelection

Arguments None.

Return Value Boolean. TRUE if the field may have only one variable
selected at a time. FALSE if more than one variable may
be selected in the field.

Example VarSelector.Fields(1).EnforceSingleSelection = TRUE

STControls OCX Reference 263

STControlsVarSelectorField Object — GetSelectionCount Method

GetSelectionCount Method
Description Returns the number of selected variables in the field. Use
the Selection and SelectionList properties to get the items
that were selected.

Syntax Object.GetSelectionCount

Arguments None.

Return Value Long. The number of selected checkboxes in the field.

Example numSelectedItem =
VarSelector.Fields(1).GetSelectionCount()

Index Property
Description Returns the position of this field within the collection of
fields in the control.

Syntax Object.Index

Arguments None.

Return Value Integer. The position of the field.

Example fieldIndex = myFieldObject.Index

264 STControlsVarSelectorField Object

 STControlsVarSelectorField Object — Selection Property

Selection Property
Description Returns or sets the field’s selection. This method is useful
to retrieve or set a field that allows only single variable to
be selected at a time. Use the SelectionList property to
return or set a list of variables.

Syntax Object.Selection

Arguments None.

Return Value A StatToolsVariable Object or “Nothing” if there is no

selected variable. If there is more than one variable
selected, the first one in the list is returned.

Note: For complicated internal reasons, the object is

always returned as a “late-bound” generic object, as
opposed to being set to an early-bound StatToolsVariable
object.

Example Set selectedVar = VarSelector.Fields(1).Selection

STControls OCX Reference 265

STControlsVarSelectorField Object — SelectionList Property

SelectionList Property
Description Returns all the variables selected in the field in a new
StatToolsVariableList collection object. If you know the
selection will only ever be one variable at a time, you can
use the Selection property instead.

Syntax Object.SelectionList

Arguments None.

Return Value A StatToolsVariableList Object, filled with all the selected

variables. If there are no selected variables, the returned
list object will contain no items.

Note: For complicated internal reasons, the object is

always returned as a “late-bound” generic object, as
opposed to being set to an early-bound
StatToolsVariableList object.

Example Set selectedVarList = VarSelector.Fields(1).SelectionList

Validation Property
Description Returns the STControlsValidation object corresponding to
this field.

Syntax Object.Validation

Arguments None.

Return Value A STControlsValidation object.

Example VarSelector.Fields(1).Validation.Enabled = TRUE

266 STControlsVarSelectorField Object

 STControlsVarSelectorField Object — Visible Property

Visible Property
Description Returns or sets whether the field is visible or not. The
ability to toggle the visibility of fields is very useful if you
have a selector control which has two or more different
configurations depending on the other settings in your
analysis dialog. As the user makes changes to the dialog,
the appropriate fields can be shown or hidden as
appropriate.

Note: Invisible fields will not be validated unless you set

the ValidateEvenIfInvisible property of the field’s validation
object. Also, the EnforceSingleSelectionPerRow property
will never affect the selection of an invisible field.

Syntax Object.Visible

Arguments None.

Return Value Boolean. TRUE if the field is visible. FALSE if the field is
invisible.

Example ‘Show the first field, but hide the second:

VarSelector.Fields(1).Visible = TRUE
VarSelector.Fields(2).Visible = FALSE

STControls OCX Reference 267

STControlsVarSelectorField Object — Visible Property

268 STControlsVarSelectorField Object

 STControlsVarSelectorFields Object — Count Property

STControlsVarSelectorFields Object
Count Property
Description Returns the number of fields in the collection. The number
of fields is set when the variable selector is first initialized
with the Attach method and can not subsequently be
changed.

Syntax Object.Count

Arguments None.

Return Value Integer. The number of fields. The minimum number of

fields is one. The maximum number of fields is nine.

Example numFields = VarSelector.Fields.Count

STControls OCX Reference 269

STControlsVarSelectorFields Object — GetVariableListFromStackedPair Method

GetVariableListFromStackedPair Method
Description Returns (in the varList argument) a list of stacked
variables created from a source value variable and
category variable that the user has selected. Typically,
there will be one stacked variable in the list for each
distinct category name in the selected category variable.
The number of variables is limited, however, by the
maxNumVariables argument, and optionally by the
catNames list.
You may use the SetStackedPairFromVariableList method
to (approximate) the opposite of this routine.
See the section Data Sets, Variables, and Variable Lists
of this document for more information about stacked and
unstacked variables.

Syntax Object.GetVariableListFromStackedPair(valFieldIndex as
Integer, catFieldIndex as Integer, varList As Object,
maxNumVariables as Integer, Optional catNames)

Arguments valFieldIndex (Integer) – the index of the field where the

user has selected the value variable. If there is not
variable selected in this field, an error occurs. If there is
more than one variable selected in this field, the first one
will be used.
catFieldIndex (Integer) – the index of the field where the
user has selected the category variable. If there is not
variable selected in this field, an error occurs. If there is
more than one variable selected in this field, the first one
will be used.
varList (A StatToolVariableList Object) – the
StatToolsVariableList object that will be created and filled
with stacked variables.
maxNumVariables (Integer) – the maximum number of
variables that may be created and added to the list. If the
actual number of categories exceeds this number, only the
first maxNumVariables categories will be used.
catNames (Optional Array of Strings) – Set this to an array
of string to limit the created variables to a specific set of
category names.

Return Value None.

270 STControlsVarSelectorFields Object

 STControlsVarSelectorFields Object — Item Property
Example ‘Get all the stacked variables.
‘The value variable is in field 2. The category variable is
field 1.
VarSelector.Fields.GetVariableFromStackedPair(2,1,var
ListObject, 100)

‘Get only the stacked variables named “Male” and

“Female”
Dim catNames(1 to 2) as String
catNames(1) = “Male”
catNames(2) = “Female”
VarSelector.Fields.GetVariableFromStackedPair(2,1,var
ListObject, 2, catNames())

Item Property
Description Returns a specific field, by index, from the collection of
fields. Note this is the default method for this object.

Syntax Object.Item(index as Integer)

Arguments index(Integer) – the index of the variable in the

collection.

Return Value A VarSelectorField object.

Example ‘These two lines of code are the same:

MsgBox VarSelector.Fields.Item(3).Caption
MsgBox VarSelector.Fields(3).Caption

STControls OCX Reference 271

STControlsVarSelectorFields Object — SetStackedPairFromVariableList Method

SetStackedPairFromVariableList Method
Description Given a StatToolsVariableList object filled with stacked
variables, presumably constructed from the
GetVariableListFromStackedPair method, this method sets
the selection of a pair of a pair of fields with the
appropriate value and category variable.

Since the variable list passed in may not contain variables

all from the same stacking source (or perhaps even
contains unstacked variables) this routine is can not
always uniquely represent any variable list passed in. In
those cases, it simply looks at the first stacked variable in
the list (if any) to select the appropriate value and category
variables.

See the section Data Sets, Variables, and Variable Lists

of this document for more information about stacked and
unstacked variables.

Syntax Object.SetStackedPairFromVariableList(valFieldIndex as
Integer, catFieldIndex as Integer, varList As Object)

Arguments valFieldIndex (Integer) – the index of the field where the

user selects the value variable.

catFieldIndex (Integer) – the index of the field where the

user selects the category variable.

varList (A StatToolVariableList Object) – the

StatToolsVariableList object that contains the list of
stacked variables.

Return Value None.

Example ‘Set the stacked value and category variables that are to
be selected
VarSelector.Fields.SetStackedPairFromVaribleList 2,1,
myVarListObject

272 STControlsVarSelectorFields Object

 Overview — SetStackedPairFromVariableList Method

Automating the StatTools Core

Analysis Pack

Overview
It is fairly easy to automate the built-in “core” StatTools analyses as part of
your own custom VBA code. To do this you must first attach to the core
pack’s automation library, as described below. Next, you must create a
automation object corresponding to the particular analysis you want to
automate, set the properties of that object as appropriate, and then run the
analysis by calling one or more methods of that object.
The rest of this section of this document discusses how to automate the
core analysis pack. It is possible to automate other analysis packs if they
come with an automation library. While the process will be similar to
automating the core analysis pack, you need to check with the pack’s
documentation before proceeding.

Automating the StatTools Core Analysis Pack 273

Overview — Attaching to the Core Analysis Pack Automation Library

Attaching to the Core Analysis Pack Automation Library

In order to automate the core analysis pack, you must first create a
reference to the core pack’s automation library. To create a reference to
this library, open up your VBA project and bring up the “References”
dialog (on the Tools menu):

Make sure the item “Palisade StatTools Core Pack Automation Library” is
checked.

274 Overview
 Overview — Creating an Automation Object

Creating an Automation Object

Within the automation library, each analysis in the pack has an automation
object. In order to automate a particular analysis, you must first create the
automation object for that analysis. For example, to automate the one
variable summary analysis, you must first create an instance of the
StatTools_OneVarSummary object:
Dim analysisObject as New StatTools_OneVarSummary
The automation objects in the core pack are:

StatTools_ANOVAOneWay StatTools_Histogram
StatTools_ANOVATwoWay StatTools_HypothesisTest
StatTools_Autocorrelation StatTools_Interaction
StatTools_BoxPlot StatTools_Lags
StatTools_ChiSqIndependence StatTools_Lilliefors
StatTools_ChiSqTest StatTools_Logistic
StatTools_Combination StatTools_OneVarSummary
StatTools_ConfInterval StatTools_QQNormal
StatTools_ControlChartC StatTools_RandomSample
StatTools_ControlChartP StatTools_Regression
StatTools_ControlChartU StatTools_RunsTest
StatTools_ControlChartXR StatTools_SampleSize
StatTools_CorrAndCovar StatTools_ScatterPlot
StatTools_Diff StatTools_Stack
StatTools_Discriminant StatTools_TimeSeriesGraph
StatTools_Dummy StatTools_Transform
StatTools_Forecast StatTools_Unstack

Automating the StatTools Core Analysis Pack 275

An Example

An Example
As a concrete example of how to automate an analysis in the core
analysis pack, here is a code snippet of how to generate a one-variable
summary report:

Public Sub TestMacro()

Dim automationObj as New StatTools_OneVarSummary

‘First make sure StatTools has scanned this workbook

StatTools.DataSets.Scan ThisWorkbook

‘Add the first two variables of the first data set to the list of variables
to analyze:

With automationObj.VariableList
.Add StatTools.DataSets(1).Variables(1)
.Add StatTools.DataSets(1).Variables(2)
End With

‘Now generate the report, using the default properties

.GenerateReport
End Sub
Another example is provided in the Automating Built-In Analysis.xls
example (accessible through the Help > Example Spreadsheets
command).

276 Overview
 AnalysisObject Property

StatTools Core Analysis Pack

Automation Reference
Methods and Properties Shared By All
Automation Objects
There is a common set of methods and properties that all StatTools Core
Analysis Pack automation objects share. These common methods and
properties are listed in this section.

AnalysisObject Property
Description Returns the StatToolsAnalysis object corresponding to this
analysis automation object. Use this object to gain access to
the generic properties and methods of the StatToolsAnalysis
object.

Syntax Object.AnalysisObject

Arguments None.

Return Value A StatToolsAnalysis object.

Example Set myAnalysisObject =

myAutomationObject.AnalysisObject

StatTools Core Analysis Pack Automation Reference 277

Defaults Method

Defaults Method
Description Forces the analysis to either read or write its current state
as a default, either to the global defaults or to a specific
workbook’s defaults.
Analysis defaults determine what values are shown when
an automation object is first created or an analysis dialog
is first displayed. There are two levels of these defaults.
First, the currently active workbook may have defaults for
an analysis stored within it as hidden defined names.
These values should be written whenever an analysis
dialog is dismissed with a click to the OK button. This
allows those same settings to reappear when the dialog is
next displayed for the same workbook. Second there is a
set of global defaults, stored in the system registry, which
are used when the analysis dialog is displayed in the
context of a workbook that doesn’t have any workbook
level defaults. These global defaults are written when the
user clicks the “Save as Defaults” icon in an analysis
dialog.
Note: This method is automatically called for you (in read
mode) when the automation object is first created. It is
also automatically called when you call the RunAnalysis
method.
Note: When you call this method to write defaults, it will
automatically call the Validate method with ValidationMode
set to StatToolsValidationModeWriteDefaults.

Syntax Object.Defaults(writeDefaults As Boolean, wbContext As

Object)

Arguments writeDefaults (Boolean) – TRUE if the defaults are being

written. FALSE if the defaults are being read.
wbContext (Excel Workbook Object) – Set to “Nothing” to
write to or read from the global defaults. Set to an Excel
Workbook Object to write or read to that specific
workbook.

Return Value A StatToolsResult code. StatToolsResultOK if the method

was successfully called. Another result code if the method
failed. Use the ResultString method of the root StatTools
object for a description of the result code.

Example ‘Read the global defaults:

resultCode = myAutomationObject.Defaults(False,
Nothing)

278 Methods and Properties Shared By All Automation Objects

 GenerateReport Method

GenerateReport Method
Description Causes the analysis to generate a report based on the
current automation object properties.
Note: When you call this method, it will automatically call
the Validate method with ValidationMode set to
StatToolsValidationGenerateReport.
Note: This method is automatically called when you call
the RunAnalysis method.

Syntax Object.GenerateReport

Arguments None.

Return Value A StatToolsResult code. StatToolsResultOK if the method

was successfully called. Another result code if the method
failed. Use the ResultString method of the root StatTools
object for a description of the result code.

Example resultCode = myAutomationObject.GenerateReport()

StatTools Core Analysis Pack Automation Reference 279

RunAnalysis Method

RunAnalysis Method
Description Runs the complete analysis, just as if the analysis button
had been pressed in the user interface, including getting
analysis defaults, presenting the user with the dialog, and
generating the report.

Syntax Object.RunAnalysis

Arguments None.

Return Value A StatToolsResult code. StatToolsResultOK if the method

was successfully called. Another result code if the method
failed. Use the ResultString method of the root StatTools
object for a description of the result code.

Example resultCode = myAutomationObject.RunAnalysis()

280 Methods and Properties Shared By All Automation Objects

 ShowDialog Method

ShowDialog Method
Description Causes the analysis’ dialog to be displayed, using the
current settings as the dialog defaults. When the dialog’s
OK button is pressed, the current settings will change to
reflect the user’s choices.

Note: When you call this method, it will automatically call

the Validate method with ValidationMode set to
StatToolsValidationModeShowDialog.

Note: This method is automatically called when you call

the RunAnalysis method.

Syntax Object.ShowDialog

Arguments None.

Return Value A StatToolsResult code. StatToolsResultOK if the method

was successfully called. Another result code if the method
failed. Use the ResultString method of the root StatTools
object for a description of the result code.

Example resultCode = myAutomationObject.ShowDialog()

StatTools Core Analysis Pack Automation Reference 281

Validate Method

Validate Method
Description Validates the current automation object settings.

Note: This method is, in general, automatically called for

you when you invoke other methods. However, if you
need to validate the automation object’s state manually,
you may call it separately.

Syntax Object.Validate(validationMode as
StatToolsValidationMode)

Arguments validationMode (StatToolsValidationMode enumerated

constant) controls the style of validation to perform. One
of the enumerated constant values:
StatToolsValidationModeWriteDefaults
StatToolsValidationModeWriteShowDialog
StatToolsValidationModeGenerateReport

Return Value A StatToolsResult code. StatToolsResultOK if the method

was successfully called. Another result code if the method
failed. Use the ResultString method of the root StatTools
object for a description of the result code.

Example resultCode = myAutomationObject.Validate()

282 Methods and Properties Shared By All Automation Objects

 StatTools_ANOVAOneWay

Automation Object Reference

Every automation object in the core pack’s automation library has its
own set of custom properties (and occasionally some custom methods)
which closely follow the options available in the analysis’ dialog. These
are listed in this section.

StatTools_ANOVAOneWay
Property or Method Description
DefaultDataFormat Controls the default data format mode for the One-Way
(StatToolsDataFormat ANOVA dialog. NOTE: This setting does not affect the
Enumerated Constant) analysis results in anyway. Must be of the following
enumerated constants:
o StatToolsDataFormatStacked
o StatToolsDataFormatUnstacked
VariableList The list of variables to be analyzed. There must be
(StatToolsVariableList Object) between 2 and 50 variables to analyze. Either stacked or
unstacked variables may be specified.
NoCorrection (Boolean) Specifies whether confidence intervals will be generated
with using the “no-correction” method.
Bonferroni (Boolean) Specifies whether confidence intervals will be generated
with using the “Bonferroni” correction method.
Tukey (Boolean) Specifies whether confidence intervals will be generated
with using the “Tukey” correction method.
Scheffe (Boolean) Specifies whether confidence intervals will be generated
with using the “Scheffe” correction method.
ConfidenceLevel (Double) Sets the confidence level to be used in the confidence
interval calculations. A number between 0 and 1.

StatTools Core Analysis Pack Automation Reference 283

StatTools_ANOVATwoWay

StatTools_ANOVATwoWay
Property or Method Description
CategoryVariable1 The first category variable to be analyzed. Must be
(StatToolsVariable Object) an unstacked variable.
CategoryVariable2 The second category variable to be analyzed. Must
(StatToolsVariable Object) be an unstacked variable.
ValueVariable The value variable to be analyzed. Must be an
(StatToolsVariable Object) unstacked variable.

NOTE: All the variables must have the same number of elements, and the pair of
category variables must form a “balanced” design. That is, the number elements
in each distinct combination of the two category variables must have the same
number of elements.

StatTools_Autocorrelation
Property or Method Description
VariableList The list of variables to be analyzed. There must be
(StatToolsVariableList Object) between 1 and 10 variables to analyze. All variables
must be unstacked.
NumLags (Integer) The number of lags. Must be between 1 and 32, or
the special value StatToolsAutoNumLags to have the
number of lags be determined automatically for you,
based on the size of your variables.
CreateChart (Boolean) determines whether an autocorrelation (or
correleogram) chart is created.

284
 StatTools_BoxPlot

StatTools_BoxPlot
Property or Method Description
DefaultDataFormat controls the default data format mode for the Box-Plot
(StatToolsDataFormat) dialog. NOTE: This setting does not affect the analysis
results in anyway. Must be of the following enumerated
constants:
o StatToolsDataFormatStacked
o StatToolsDataFormatUnstacked
VariableList the list of variables to analyze. Must be between 1 and
(StatToolsVariableList) 10. Stacked or unstacked variables may be specified.
IncludeKey (Boolean) determines whether a picture is displayed under the
boxplot, which serves as a “key” to identify the different
pieces of a box-plot and what they mean.

StatTools_ChiSqIndependence
Property or Method Description
ContingencyTableRange the range of the contingency table to analyze, which may
(Excel Range Object) or may not include a header row and column.

RangeIncludesHeaders controls whether the contingency range includes an extra

(Boolean) row and column for a header, which describes what each
row and column in the table represents.
ColumnsTitle (String) An optional string, which is used to label the columns (as
a whole) of the report.
RowsTitle (String) An optional string, which is used to label to rows (as a
whole) of the report.

StatTools Core Analysis Pack Automation Reference 285

StatTools_ChiSqTest

StatTools_ChiSqTest
Property or Method Description
VariableList the list of variables to analyze. In the current release
(StatToolsVariableList Object) of StatTools, you can populate this list with only a
single variable. Future versions of StatTools may
expand this analysis to support more than a single
variable. The variables must be unstacked.
BinMinimum (Double) the minimum of the first bin. If
ExtendFirstBinToMinusInfinity is TRUE, this is the
maximum of the first bin (which has no minimum.)
BinMaximum (Double) the maximum of the last bin. If
ExtendLastBinToInfinity is TRUE, this is the minimum
of the last bin (which has no maximum.)
NumBins (Integer) the number of bins in the chi-sq test. Must be
between 3 and 50. You may also set it to the special
value StatToolsAutoNumBins.
ExtendFirstBinToMinusInfinity If TRUE, the first bin extends from the BinMinimum
(Boolean) value to negative infinity.
ExtendLastBinToInfinity if TRUE, the last bin extends from the BinMaximum
(Boolean) value to positive infinity.

286
 StatTools_Combination

StatTools_Combination
Property or Method Description
VariableList the list of variables to be analyzed. There must be
(StatToolsVariableList Object) between 2 and 30 variables to combine. All variables
must be unstacked.

CombinationType controls how the selected variables are combined. Must

(StatToolsCombinationType be one of the following enumerated constant values:
Enumerated Constant) o StatToolsCombinationProduct
o StatToolsCombinationSum
o StatToolsCombinationAverage
o StatToolsCombinationMin
o StatToolsCombinationMax
o StatToolsCombinationRange

StatTools Core Analysis Pack Automation Reference 287

StatTools_ConfInterval

StatTools_ConfInterval
Property or Method Description
AnalysisType determines what sort of analysis will be
(StatToolsConfidenceIntervalA performed. Must be one of the following
nalysisType Enumerated enumerated constants:
Constant) StatToolsConfIntervalOneSample
StatToolsConfIntervalTwoSample
StatToolsConfIntervalPairedSample

DefaultDataFormat controls the default data format mode for the

(StatToolsDataFormat Confidence Interval dialog. NOTE: This setting
Enumerated Constant) does not affect the analysis results in anyway.
Must be of the following enumerated constants:
StatToolsDataFormatStacked
StatToolsDataFormatUnstacked

VariableList the list of variables to analyze. The number of

(StatToolsVariableList Object) variables that may be analyzed depends on the
AnalysisType property. A
StatToolsConfIntervalOneSample analysis may
have between 1 and 250 variables. The
StatToolsConfIntervalTwoSample and
StatToolsConfIntervalPairedSample analyses
require exactly two variables. Variables may be
stacked or unstacked.
CalculateMeanInterval controls whether the analysis will calculate the
(Boolean) confidence interval about the sample mean.
MeanConfidenceLevel the confidence level for the mean. Must be a
(Double) value between 0 and 1.
CalculateStdDevInterval controls whether the analysis will calculate the
(Boolean) confidence interval about the sample standard
deviation. Only available for when the
AnalysisType is
StatToolsConfIntervalOneSample.
StdDevConfidenceLevel the confidence level for the standard deviation.
(Double) Must be a value between 0 and 1.

288
 StatTools_ControlChartC

StatTools_ControlChartC
Property or Description
Method
VariableList the list of variables to analyze. In the current release of
(StatToolsVariableList StatTools, you can populate this list with only a single variable.
Object) Future versions of StatTools may expand this analysis to
support more than a single variable. The variables must be
unstacked.
LimitGraphRange controls whether the values shown in the graph is limited to the
(Boolean) data with indices between GraphStartIndex and
GraphStopIndex.
GraphStartIndex the starting index of the data shown in the graph. This only
(Integer) takes effect if the LimitGraphRange property is TRUE.
GraphStopIndex the stopping index of the data shown in the graph. This only
(Integer) takes effect if the LimitGraphRange property is TRUE.
ControlLimitsType controls what data is used to calculate the controls limits:
(StatToolsControlChart StatToolsControlChartLimitsAll – all the source data is used to
LimitsType calculate the control limits.
Enumerated Constant)
StatToolsControlChartLimitsObservationsInRange – only the
source data in the range specified by ControlLimitsStartIndex
and ControlLimitsStopIndex is used to calculate the control
limits.
StatToolsControlChartLimitsPrevious – the control limits are
calculated based on the results of a previous analysis, with the
previous data’s average C value specified in PreviousCBar.
ControlLimitsStartIndex the starting index of the data to use to calculate the control
(Long) limits. This property only has effect when the
ControlLimitsType property is set to
StatToolsControlChartLimitsObservationsInRange.
ControlLimitsStopIndex the stopping index of the data to use to calculate the control
(Long) limits. This property only has effect when the
ControlLimitsType property is set to
StatToolsControlChartLimitsObservationsInRange.

PreviousCBar (Double) the average C value of a previously run analysis, used to

calculate the control limits. This property only has effect when
the ControlLimitsType property is set to
StatToolsControlChartLimitsPrevious.
PlotZoneAAnalysis controls whether a “Zone A” information will be added to the
(Boolean) graph. This analysis examines the number of data points that
fall outside two standard deviations of the central value.

StatTools Core Analysis Pack Automation Reference 289

StatTools_ControlChartC
PlotZoneBAnalysis controls whether a “Zone B” information will be added to the
(Boolean) graph. This analysis examines the number of data points that
fall outside one standard deviation of the central value.
PlotRunsUpDownAnaly controls whether a “runs” information will be added to the
sis (Boolean) graph. This analysis examines the number of consecutive up
or down movements in the data.
PlotAboveBelowAnalysi controls whether an “above/below” information will be added to
s (Boolean) the graph. This analysis examines the number of consecutive
samples above or below the central value.
PlotSigma2ControlLimit controls whether the 2-sigma lines are displayed on the graph.
(Boolean)
PlotSigma1ControlLimit controls whether the 1-sigma lines are displayed on the graph.
(Boolean)

290
 StatTools_ControlChartP

StatTools_ControlChartP
Property or Description
Method
InputDataType controls what type of P-analysis is being performed. Must
(StatToolsPChartDataTy be one of the following enumerated constant values:
pe Enumerated o StatToolsPChartNumberDefects – in this mode, each data
Constant) point in the variable to analyze contains the number of
defects in a batch of items.
o StatToolsPChartFractionofDefects – in this mode, each
each data point is the fraction of defective items in the
sample
VariableList the list of variables to analyze. In the current release of
(StatToolsVariableList StatTools, you can populate this list with only a single
Object) variable. Future versions of StatTools may expand this
analysis to support more than a single variable. The
variables must be unstacked.
UseCommonSampleSiz If the number of items in each batch is fixed, set this
e (Boolean) property to TRUE and then specify the batch size in the
CommonSampleSize property. If the number of items in
each batch is dynamic (that is, it has a potentially different
value for each sample taken) set this property to FALSE
and specify the batch size in the SizeVariable.
CommonSampleSize If the number of items in each batch is fixed, set that
(Long) common size here. The UseCommonSampleSize property
must be TRUE for this property to take effect.
SizeVariable If the number of items in each batch changes with each
(StatToolsVariable sampled value, set this property to a variable containing the
Object) batch sizes. The UseCommonSampleSize property must
be FALSE for this property to take effect.
LimitGraphRange controls whether the values shown in the graph is limited to
(Boolean) the data with indices between GraphStartIndex and
GraphStopIndex.
GraphStartIndex the starting index of the data shown in the graph. This only
(Integer) takes effect if the LimitGraphRange property is TRUE.
GraphStopIndex the stopping index of the data shown in the graph. This only
(Integer) takes effect if the LimitGraphRange property is TRUE.

StatTools Core Analysis Pack Automation Reference 291

StatTools_ControlChartP
ControlLimitsType controls what data is used to calculate the controls limits:
(StatToolsControlChartL StatToolsControlChartLimitsAll – all the source data is used
imitsType Enumerated to calculate the control limits.
Constant)
StatToolsControlChartLimitsObservationsInRange – only the
source data in the range specified by ControlLimitsStartIndex
and ControlLimitsStopIndex is used to calculate the control
limits.
StatToolsControlChartLimitsPrevious – the control limits are
calculated based on the results of a previous analysis, with
the previous data’s average P value specified in
PreviousPBar and the sample size in PreviousSampleSize.
ControlLimitsStartIndex the starting index of the data to use to calculate the control
(Long) limits. This property only has effect when the
ControlLimitsType property is set to
StatToolsControlChartLimitsObservationsInRange.
ControlLimitsStopIndex the stopping index of the data to use to calculate the
(Long) control limits. This property only has effect when the
ControlLimitsType property is set to
StatToolsControlChartLimitsObservationsInRange.
PreviousPBar (Double) the average P value of a previously run analysis, used to
calculate the control limits. This property only has effect
when the ControlLimitsType property is set to
StatToolsControlChartLimitsPrevious.
PreviousSampleSize the sample size of a previously run analysis, used to
(Long) calculate the control limits. This property only has effect
when the ControlLimitsType property is set to
StatToolsControlChartLimitsPrevious.
PlotZoneAAnalysis controls whether a “Zone A” information will be added to the
(Boolean) graph. This analysis examines the number of data points
that fall outside two standard deviations of the central value.
PlotZoneBAnalysis controls whether a “Zone B” information will be added to
(Boolean) the graph. This analysis examines the number of data
points that fall outside one standard deviation of the central
value.
PlotRunsUpDownAnalys controls whether a “runs” information will be added to the
is (Boolean) graph. This analysis examines the number of consecutive
up or down movements in the data.
PlotAboveBelowAnalysi controls whether an “above/below” information will be added
s (Boolean) to the graph. This analysis examines the number of
consecutive samples above or below the central value.
PlotSigma2ControlLimit controls whether the 2-sigma lines are displayed on the
(Boolean) graph.
PlotSigma1ControlLimit controls whether the 1-sigma lines are displayed on the
(Boolean) graph.

292
 StatTools_ControlChartU

StatTools_ControlChartU
Property or Method Description
InputDataType controls what type of U-analysis is being performed. Must be
(StatToolsUChartDataType one of the following enumerated constant values:
Enumerated Constant) o StatToolsPChartNumberDefects – in this mode, each data
point in the variable to analyze contains the number of
defects in a batch of items.
o StatToolsPChartRateofDefects – in this mode, each data
point is the number of defect per unit time.

VariableList the list of variables to analyze. In the current release of

(StatToolsVariableList StatTools, you can populate this list with only a single
Object) variable. Future versions of StatTools may expand this
analysis to support more than a single variable. The
variables must be unstacked.
UseCommonSampleSize If the number of items in each batch is fixed, set this property
(Boolean) to TRUE and then specify the batch size in the
CommonSampleSize property. If the number of items in each
batch is dynamic (that is, it has a potentially different value for
each sample taken) set this property to FALSE and specify
the batch size in the SizeVariable.
CommonSampleSize If the number of items in each batch is fixed, set that common
(Long) size here. The UseCommonSampleSize property must be
TRUE for this property to take effect.
SizeVariable If the number of items in each batch changes with each
(StatToolsVariable Object) sampled value, set this property to a variable containing the
batch sizes. The UseCommonSampleSize property must be
FALSE for this property to take effect.
LimitGraphRange controls whether the values shown in the graph is limited to
(Boolean) the data with indices between GraphStartIndex and
GraphStopIndex.
GraphStartIndex (Integer) the starting index of the data shown in the graph. This only
takes effect if the LimitGraphRange property is TRUE.
GraphStopIndex (Integer) the stopping index of the data shown in the graph. This only
takes effect if the LimitGraphRange property is TRUE.

StatTools Core Analysis Pack Automation Reference 293

StatTools_ControlChartU
ControlLimitsType controls what data is used to calculate the controls limits:
(StatToolsControlChartLimit StatToolsControlChartLimitsAll – all the source data is used
sType Enumerated to calculate the control limits.
Constant)
StatToolsControlChartLimitsObservationsInRange – only the
source data in the range specified by ControlLimitsStartIndex
and ControlLimitsStopIndex is used to calculate the control
limits.
StatToolsControlChartLimitsPrevious – the control limits are
calculated based on the results of a previous analysis, with
the previous data’s average U value specified in
PreviousUBar and the sample size in PreviousSampleSize.
ControlLimitsStartIndex the starting index of the data to use to calculate the control
(Long) limits. This property only has effect when the
ControlLimitsType property is set to
StatToolsControlChartLimitsObservationsInRange.
ControlLimitsStopIndex the stopping index of the data to use to calculate the control
(Long) limits. This property only has effect when the
ControlLimitsType property is set to
StatToolsControlChartLimitsObservationsInRange.
PreviousUBar (Double) the average U value of a previously run analysis, used to
calculate the control limits. This property only has effect
when the ControlLimitsType property is set to
StatToolsControlChartLimitsPrevious.
PreviousSampleSize (Long) the sample size of a previously run analysis, used to calculate
the control limits. This property only has effect when the
ControlLimitsType property is set to
StatToolsControlChartLimitsPrevious.
PlotZoneAAnalysis controls whether a “Zone A” information will be added to the
(Boolean) graph. This analysis examines the number of data points that
fall outside two standard deviations of the central value.
PlotZoneBAnalysis controls whether a “Zone B” information will be added to the
(Boolean) graph. This analysis examines the number of data points that
fall outside one standard deviation of the central value.
PlotRunsUpDownAnalysis controls whether a “runs” information will be added to the
(Boolean) graph. This analysis examines the number of consecutive up
or down movements in the data.
PlotAboveBelowAnalysis controls whether an “above/below” information will be added
(Boolean) to the graph. This analysis examines the number of
consecutive samples above or below the central value.
PlotSigma2ControlLimit controls whether the 2-sigma lines are displayed on the
(Boolean) graph.
PlotSigma1ControlLimit controls whether the 1-sigma lines are displayed on the
(Boolean) graph.

294
 StatTools_ControlChartXR

StatTools_ControlChartXR
Property or Method Description
ControlChartType controls which charts are created. Must be on of the
(StatToolsXRControlChartTy following enumerated constant values:
pe Enumerated Constant) o StatToolsControlChartTypeXR – create both an X
and an R chart.
o StatToolsControlChartTypeX – create an X chart
only.
o StatToolsControlChartTypeR – create an R chart
only.

VariableList the list of variables to analyze. There must be between 2

(StatToolsVariableList and 25 variables to analyze. The variables must be
Object) unstacked.

LimitGraphRange (Boolean) controls whether the values shown in the graph is limited to
the data with indices between GraphStartIndex and
GraphStopIndex.
GraphStartIndex (Integer) the starting index of the data shown in the graph. This only
takes effect if the LimitGraphRange property is TRUE.
GraphStopIndex (Integer) the stopping index of the data shown in the graph. This only
takes effect if the LimitGraphRange property is TRUE.
ControlLimitsType controls what data is used to calculate the controls limits:
(StatToolsControlChartLimits StatToolsControlChartLimitsAll – all the source data is used
Type Enumerated Constant) to calculate the control limits.
StatToolsControlChartLimitsObservationsInRange – only the
source data in the range specified by
ControlLimitsStartIndex and ControlLimitsStopIndex is used
to calculate the control limits.
StatToolsControlChartLimitsPrevious – the control limits are
calculated based on the results of a previous analysis, with
the previous data’s average X-bar value specified in
PreviousXBarBar, the previous average R-value in
PreviousRBar and the sample size in PreviousSampleSize.

ControlLimitsStartIndex the starting index of the data to use to calculate the control
(Long) limits. This property only has effect when the
ControlLimitsType property is set to
StatToolsControlChartLimitsObservationsInRange.

StatTools Core Analysis Pack Automation Reference 295

StatTools_ControlChartXR
ControlLimitsStopIndex the stopping index of the data to use to calculate the control
(Long) limits. This property only has effect when the
ControlLimitsType property is set to
StatToolsControlChartLimitsObservationsInRange.
PreviousXBarBar (Double) the average X-bar value of a previously run analysis, used to
calculate the control limits. This property only has effect
when the ControlLimitsType property is set to
StatToolsControlChartLimitsPrevious.
PreviousRBar (Double) the average R-value of a previously run analysis, used to
calculate the control limits. This property only has effect
when the ControlLimitsType property is set to
StatToolsControlChartLimitsPrevious.
PreviousSampleSize (Long) the sample size of a previously run analysis, used to
calculate the control limits. This property only has effect
when the ControlLimitsType property is set to
StatToolsControlChartLimitsPrevious.

PlotZoneAAnalysis controls whether a “Zone A” information will be added to the

(Boolean) graph. This analysis examines the number of data points
that fall outside two standard deviations of the central value.
PlotZoneBAnalysis controls whether a “Zone B” information will be added to the
(Boolean) graph. This analysis examines the number of data points
that fall outside one standard deviation of the central value.
PlotRunsUpDownAnalysis controls whether a “runs” information will be added to the
(Boolean) graph. This analysis examines the number of consecutive
up or down movements in the data.
PlotAboveBelowAnalysis controls whether an “above/below” information will be added
(Boolean) to the graph. This analysis examines the number of
consecutive samples above or below the central value.
PlotSigma2ControlLimit controls whether the 2-sigma lines are displayed on the
(Boolean) graph.
PlotSigma1ControlLimit controls whether the 1-sigma lines are displayed on the
(Boolean) graph.

296
 StatTools_CorrAndCovar

StatTools_CorrAndCovar
Property or Method Description
VariableList (StatToolsVariableList the list of variables to be analyzed. There must be
Object) between 1 and 250 variables to analyze. All variables
must be unstacked.
CorrelationTable (Boolean) controls if a correlation table is created.
CovarianceTable (Boolean) controls if a covariance table is created.
TableStructure controls how the correlation and covariance tables
(StatToolsTableStructure are filled in. Since these tables are both always
Enumerated Constant) symmetric around the diagonal, in some cases you
might want to fill in only half the table. Must be one of
the following enumerated constant values:
StatToolsTableStructureSymmetric - fill in all table
elements.
StatToolsTableStructureAboveDiagonal- fill in only
the upper half of the table.
StatToolsTableStructureBelowDiagonal - fill in only
the lower half of the table.

StatTools_Diff
Property or Method Description
Variable (StatToolsVariable Object) the variable to calculate the differences of. Must
be unstacked.

NumberOfDiffs (Long) the number of difference to be generated. Must

be between 1 and 100.

StatTools Core Analysis Pack Automation Reference 297

StatTools_Discriminant

StatTools_Discriminant
Property or Method Description
DependentVariable (StatToolsVariable) the dependent variable to analyze.

IndependentVariableList the list of independent variables. Must be between 1

(StatToolsVariableList Object) and 250 variables. All variables must be unstacked.
UseMisclassification (Boolean) Controls whether this misclassification information in
the PriorProbability, Misclassification_1as2, and
Misclassification_2as1 properties are use in the
analysis. This setting only has effect when there are
two categories in the dependent variable.
PriorProbability (Double) The prior probability of the first category (determined
alphabetically) of the dependent variable. Must be a
value between 0 and 1. This property only has effect
if UseMisclassification is TRUE and there are two
categories in the dependent variable.
Misclassification_1as2 (Double) The cost of misclassification of an item that is actually
in the first category (determined alphabetically) as
being in the second. This property only has effect if
UseMisclassification is TRUE and there are two
categories in the dependent variable.
Misclassification_2as1 (Double) The cost of misclassification of an item that is actually
in the second category (determined alphabetically) as
being in the first. This property only has effect if
UseMisclassification is TRUE and there are two
categories in the dependent variable.
IncludeClassificationSummary (Boolean) controls whether the report will include a classification
summary table.
IncludeClassificationResults (Boolean) controls whether the report will include the
classification results tables.

IncludeVarsAndCovars (Boolean) controls whether a table variances and covariances

of the input variables are displayed.

IncludePrediction (Boolean) controls whether the results of the analysis should be

applied to another data set in order to predict a set of
classification results for that data. The data set to
predict is specified in the PredictionDataSet property.
PredictionDataSet (StatToolsDataSet) a data set to prediction classification values for. This
property only has effect when IncludePrediction is set
to TRUE.

298
 StatTools_Dummy

StatTools_Dummy
Property or Method Description
Variable (StatToolsVariable) the variable to create dummy variables from. Must be an
unstacked variable, which typically will contain a small
number of text “category” values, such as “Male” and
“Female.”
DummyType the type of dummy variable to construct. Must be one of
(StatToolsDummyType the following enumerated values:
Enumerated Constant) o StatToolsDummyCategories – creates one
dummy variable for each unique category in the
source variable. Each of these dummy variables
will have a “1” where the source variable has that
particular category, and a “0” otherwise.
o StatToolsDummyNumericCondition – creates a
single dummy variable by comparing the source
variable to a value using the given
ConditionOperator and ConditionValue
properties.

ConditionOperator Determines what operator is used in the comparison. This

(StatToolsOperator property only has effect if DuumyType is set to
Enumerated Constant) StatToolsDummyNumericCondition. It must have one of
the following enumerated constant values:
o StatToolsOperatorLessThan
o StatToolsOperatorLessThanOrEqualTo
o StatToolsOperatorEqualTo
o StatToolsOperatorGreaterThan
o StatToolsOperatorGreaterThanOrEqualTo
o StatToolsOperatorNotEqual

ConditionValue (Double) Determines the value to compare the source variable to

using the ConditionOperator. This property only has
effect if DummyType is set to
StatToolsDummyNumericCondition.

StatTools Core Analysis Pack Automation Reference 299

StatTools_Forecast

StatTools_Forecast
Property or Method Description
Variable (StatToolsVariable the variable to run the forecast analysis on.
Object)
NumberOfForecasts (Integer) the number of forecast values to project into the future.
NumberOfHoldOuts (Integer) the number of values to reserve in the hold-out region.
Hold-out values are not used in the forecast, but are used to
validate the forecast model.
OptimizeParameters (Boolean) controls whether the forecasting parameters (Span, Level,
Trend, and Seasonality) should be set to their optimal
values by the forecast analysis, or left at fixed values you
specify.
ForecastMethod controls the forecasting method to be used. Must be on of
(StatToolsForecastMethod the following enumerated constant values:
Enumerated Constant) StatToolsForecastMethodMovingAverage
StatToolsForecastMethodExponentialSimple
StatToolsForecastMethodExponentialHolts
StatToolsForecastMethodExponentialWinters

Span (Integer) controls the number of observations used in the moving

average calculation. Relevant only when the
ForecastMethod is set to StatToolsMovingAverage. The
value set here is ignored if the OptimizeParameters property
is TRUE.
Level (Double) a modeling parameter between 0 and 1. Relevant only
when the ForecastMethod is set to one of the exponential
smoothing options, and the OptimizeParameters property is
FALSE.
Trend (Double) a modeling parameter between 0 and 1. Relevant only
when the ForecastMethod is set to
StatToolsForecastMethodExponentialHolts or
StatToolsForecastMethodExponentialWinters. The value
set here is ignored if the OptimizeParameters property is
TRUE.
Seasonality (Double) a modeling parameter between 0 and 1. Relevant only
when the ForecastMethod is set to
StatToolsForecastMethodExponentialWinters.
Deseasonalize (Boolean) controls whether the forecasting method will deseasonalize
the data before the analysis (based on the SeasonalPeriod
parameter.) This method has no effect if the
ForecastMethod is set to
StatToolsForecastMethodExponentialWinters, since that
method has a built in seasonality adjustment.

300
 StatTools_Forecast
SeasonalPeriod controls the seasonal period of the analysis. This not only
(StatToolsSeasonalPeriod controls the deasonalizing process, but also controls how
Enumerated Constant) the graphs will be labeled if the UseSeasonLabels property
is TRUE. Must be one of the following enumerated constant
values:
o StatToolsAnnual
o StatToolsQuarterly
o StatToolsMonthly
o StatToolsWeekly
o StatToolsDaily
o StatToolsNone

UseSeasonLabels (Boolean) Determines if graphs will be labelled using seasons. If

TRUE, season labels will be used, and the StartingYear,
StartingQuarter, StartingMonth, StartingWeek, or
StartingDay parameters are used to control the starting
label. If FALSE, the graph labels will be simple numeric
indices, the first of which is controlled by the StartingIndex
property.
StartingYear (Integer) Determines the starting year for graph labels. Only used
when UseSeasonLabels is TRUE.
StartingQuarter (Integer) Determines the starting quarter for graph labels. Must be an
integer between 1 and 4. Only used when
UseSeasonLabels is TRUE and the SeasonalPeriod is set
to StatToolsQuarterly.
StartingMonth (Integer) Determines the starting month for graph labels. Must be an
integer between 1 and 12. Only used when
UseSeasonLabels is TRUE and the SeasonalPeriod is set
to StatToolsMonthly.
StartingWeek (Integer) Determines the starting week for graph labels. Must be an
integer between 1 and 52. Only used when
UseSeasonLabels is TRUE and the SeasonalPeriod is set
to StatToolsWeekly.
StartingDay (Integer) Determines the starting day for graph labels. Must be an
integer between 1 and 365. Only used when
UseSeasonLabels is TRUE and the SeasonalPeriod is set
to StatToosDaily.
StartingIndex (Integer) Determines the starting index for graph labels. Used when
UseSeasonLabels is FALSE, or when the SeasonalPeriod is
set to StatToolsNone.
GraphOriginalSeries (Boolean) controls whether a graph of the original time series (with no
superimposed forecast) will be displayed.

GraphForecastOverlay controls whether a graph displaying both the original time

(Boolean) series and an overlay of the forecast result will be displayed.

StatTools Core Analysis Pack Automation Reference 301

StatTools_Forecast
GraphForecastErrors (Boolean) controls whether a graph displaying the forecast errors will
be displayed.
GraphDeseasonalizedOriginalSe controls whether a graph of the original time series, adjusted
ries (Boolean) to remove seasonal effects, will be displayed.
GraphDeseasonalizedForecastO controls whether a graph of the forecasted result, adjusted
verlay (Boolean) to remove seasonal effects, will be displayed.
GraphDeseasonalizedForecastE controls whether a graph displaying the forecast errors will
rrors (Boolean) be displayed, adjusted to remove seasonal effects.

302
 StatTools_Histogram

StatTools_Histogram

Property or Method Description

DefaultDataFormat controls the default data format mode for the Histogram
(StatToolsDataFormat dialog. NOTE: This setting does not affect the analysis
Enumerated Constant) results in anyway. Must be of the following enumerated
constants:
o StatToolsDataFormatStacked
o StatToolsDataFormatUnstacked
VariableList the list of variables to be analyzed. There must be
(StatToolsVariableList Object) between 1 and 100 variables to analyze. Either stacked
or unstacked variables may be specified.
BinMinimum (Double) the minimum value of the left most bin, or the special
value StatToolsAutoBinMinimum to have the analysis use
the minimum data value as the bin minimum.
BinMaximum (Double) the maximum value of the right most bin, or the special
value StatToolsAutoBinMaximum to have the analysis use
the maximum data value as the bin maximum.
NumBins (Integer) the number of bars to use in the histogram, or the special
value StatToolsAutoNumBins to let the analysis pick a
reasonable number of bins based on the number of data
points.
XAxisStyle controls what type of x-axis to use. Must be one of the
(StatToolsHistXAxisStyles two following enumerated constant values:
Enumerated Constant) o StatToolsHistXAxisCategorical - a categorical x-
axis is a bar chart, with each bin label at its
midpoint.
o StatToolsHistXAxisNumeric-a numeric x-axis has
a graph labeled with nice, even increments of
values, with the histogram bars displayed freely
on top.
YAxisStyle controls what type of y-axis to use. Must be one of the
(StatToolsHistYAxisStyles following enumerated constant values:
Enumerated Constant) o StatToolsHistYAxisFrequency- the y-axis shows
the actual number of samples in each bin.
o StatToolsHistYAxisRelativeFrequency -the y-axis
shows the relative number of items in each bin.
That is, the number of items in each bin divided
by the total number of items.
o StatToolsHistYAxisProbabilityDensity - the y-axis
shows the probability density of samples in the
bin. This is the same as the relative frequency,
divided by the width of the bin.

StatTools Core Analysis Pack Automation Reference 303

StatTools_HypothesisTest

StatTools_HypothesisTest
Property or Method Description
AnalysisType determines what sort of analysis will be performed.
(StatToolsHypothesisTestAnalysisT Must be one of the following enumerated constants:
ype Enumerated Constant) StatToolsHypothesisTestOneSample
StatToolsHypothesisTestTwoSample
StatToolsHypothesisTestPairedSample

DefaultDataFormat controls the default data format mode for the

(StatToolsDataFormat Enumerated Hypothesis Test dialog. NOTE: This setting does not
Constant) affect the analysis results in anyway. Must be of the
following enumerated constants:
StatToolsDataFormatStacked
StatToolsDataFormatUnstacked

VariableList (StatToolsVariableList the list of variables to analyze. The number of

Object) variables that may be analyzed depends on the
AnalysisType property. A
StatToolsHypothesisTestOneSample analysis may
have between 1 and 250 variables. The
StatToolsHypothesisTestTwoSample and
StatToolsHypothesisTestPairedSample analyses
require exactly two variables. Variables may be
stacked or unstacked.

PerformMeanTest (Boolean) controls whether a hypothesis test for the mean will
be performed.

MeanNullValue (Double) the null value for the mean hypothesis test.

MeanAlternativeType the alternative hypothesis for the mean test. Must be

(StatToolsAlternative Enumerated of the following enumerated values:
Constant) StatToolsAlternativeNotEqual - the alternative
hypothesis is not equal to the null value
StatToolsAlternativeLessThan - the alternative
hypothesis is less than the null value
StatToolsAlternativeGreaterThan - the alternative
hypothesis is greater than the null value

304
 StatTools_HypothesisTest
PerformStdDevTest (Boolean) controls whether a hypothesis test for the standard
deviation will be performed. Only available if
AnalysisType is set to
StatToolsHypothesisOneSample.

StdDevNullValue (Double) the null value for the standard deviation test.

StdDevAlternativeType the alternative hypothesis for the standard deviation

(StatToolsAlternative Enumerated test. Must be one of the following enumerated
Constant) values:
StatToolsAlternativeNotEqual - the alternative
hypothesis is not equal to the null value
StatToolsAlternativeLessThan - the alternative
hypothesis is less than the null value
StatToolsAlternativeGreaterThan - the alternative
hypothesis is greater than the null value

StatTools Core Analysis Pack Automation Reference 305

StatTools_Interaction

StatTools_Interaction
Property or Method Description
InteractionType controls what type of interaction variable or variables to
(StatToolsInteractionType create. Must be on of the following enumerated constant
Enumerated Constant) values:
o StatToolsInteractionTypeValues - combines two
numeric variables (both in the ValueVariableList) to
create a new variable which is the product of the
two variables.
o StatToolsInteractionTypeValueAndCategory -
combines a single value variable (in the
ValueVariableList) with a single category variable
(in the CategoryVariableList) to create a new
variable for each distinct category. The variable for
each category contains the product of the original
value variable with a dummy (0,1) variable based
on the source category variable and the particular
category in question.
o StatToolsInteractionTypeCategories - combines
two categorical variables (both in
CategoryVariableList) to create a set of dummy
(0,1) variables representing all possible
combinations of categories.
ValueVariableList the value variables to use in the utility. Should contain two
(StatToolsVariableList value variables if InteractionType is
Object) StatToolsInteractionTypeValues, one variable if
InteractionType is
StatToolsInteractionTypeValueAndCategory, and should be
empty if InteractionType is
StatToolsInteractionTypeCategories.

CategoryVariableList the category variables to use in the utility. Should contain

(StatToolsVariableList two category variables if InteractionType is
Object) StatToolsInteractionTypeCategories, one variable if
InteractionType is
StatToolsInteractionTypeValueAndCategory, and should be
empty if InteractionType is StatToolsInteractionTypeValues.

306
 StatTools_Lags

StatTools_Lags
Property or Method Description
Variable (StatToolsVariable the variable object to generate lagged variables from.
Object)

NumberOfLags (Long) the number of lags to generate. Must be between 1

and 100, and no more than two less than the number
of cells in the source variable.

StatTools_Lilliefors
Property or Method Description
DefaultDataFormat controls the default data format mode for the Lilliefors
(StatToolsDataFormat dialog. NOTE: This setting does not affect the
Enumerated Constant) analysis results in anyway. Must be of the following
enumerated constants:
o StatToolsDataFormatStacked
o StatToolsDataFormatUnstacked

VariableList (StatToolsVariableList the list of variables to analyze. There must be

Object) between 1 and 10 variables to analyze. The variables
must be unstacked.

StatTools Core Analysis Pack Automation Reference 307

StatTools_Logistic

StatTools_Logistic
Property or Method Description
LogisticRegressionType The type of logistic regression to perform. Must be one of
(StatToolsLogisticRegression the following enumerated constant values:
Type Enumerated Constant) StatToolsLogisticRegressionStandard - in this case, the
DependentVariable is a (0,1) response variable that
specifies whether each observation is a “success” or a
“failure.” The CountVariable is not used.
StatToolsLogisticRegressionSummary - in this case, the
DependentVariable is the number of “successes” in each
sample, while the CountVariable contains the size of each
sample.

IndependentVariableList the list of (potentially) explanatory variables. There must

(StatToolsVariableList Object) be between 1 and 250 unstacked variables.

DependentVariable the dependent variable. If LogisticRegressionType is

(StatToolsVariable Object) StatToolsLogisticRegressionStandard, this variable must
be a (0,1) response variable. If LogisticRegressionType is
StatToolsLogisticRegressionSummary, this must be a
count of the number of successes, while the total count is
given in the CountVariable.
CountVariable contains the counts of each sample, when
(StatToolsVariable Object) LogisticRegressionType is set to
StatToolsLogisticRegressionSummary.

IncludeClassificationSummary controls whether a summary of the classification results is

(Boolean) included in the report.

IncludeClassificationResults controls whether the classification results are included in

(Boolean) the report.

IncludePrediction (Boolean) controls whether the results of the analysis should be

applied to another data set in order to predict a set of
classification results for that data. The data set to predict
is specified in the PredictionDataSet property.

PredictionDataSet a data set to prediction classification values for. This

(StatToolsDataSet) property only has effect when IncludePrediction is set to
TRUE.

308
 StatTools_MannWhitneyTest

StatTools_MannWhitneyTest
Property or Method Description
DefaultDataFormat Controls the default data format mode for the analysis.
(StatToolsDataFormat NOTE: This setting does not affect the analysis results in
Enumerated Constant) any way. Must be one of the following enumerated
constants:
• StatToolsDataFormatStacked
• StatToolsDataFormatUnstacked
AnalysisType Determines the type of analysis to be performed. Must be
(StatToolsMannWhitneyAnalysi one of the following constant values:
sType Enumerated Constant) • StatToolsMannWhitneyAnalysisTypeGeneral
• StatToolsMannWhitneyAnalysisTypeMedian
VariableList The list of variables to analyze. There must be exactly two
(StatToolsVariableList Object) variable in this analysis.
AlternativeType Specifies the type of alternative hypothesis for the test.
(StatToolsMannWhitneyAlterna Must be one of the following constants:
tiveType Enumerated • StatToolsMannWhitneyAlternativeTypeEitherSma
Constant) ller – a two-tailed alternative
• StatToolsMannWhitneyAlternativeTypeFirstSmall
er - a one-tailed alterative with the first variable
in the VariableList smaller than the second.
• StatToolsMannWhitneyAlternativeTypeSecondS
maller – a one-tailed alternative with the second
variable in the VariableList smaller than the first
CorrectForTies (Boolean) Controls whether the analysis will automatically correct for
ties.

StatTools Core Analysis Pack Automation Reference 309

StatTools_OneVarSummary

StatTools_OneVarSummary
Property or Method Description
DefaultDataFormat controls the default data format mode for the dialog.
(StatToolsDataFormat NOTE: This setting does not affect the analysis results in
Enumerated Constant) anyway. Must be of the following enumerated constants:
o StatToolsDataFormatStacked
o StatToolsDataFormatUnstacked
VariableList the list of variables to be analyzed. There must be
(StatToolsVariableList Object) between 1 and 100 variables to analyze. Either stacked or
unstacked variables may be specified.
ValueVariable When DataType is set to
(StatToolsVariable Object) StatToolsParetoChartDataTypeCategoryAndValue,
ValueVariable will contain the frequency (number of
occurrences) of each corresponding CategoryVariable
entry.

Mean (Boolean) include Mean

Variance (Boolean) include Variance
StandardDeviation (Boolean) include Standard Deviation
Skewness (Boolean) include Skewness
Kurtosis (Boolean) include Kurtosis
Median (Boolean) include Median
MeanAbsDeviation (Boolean) include Mean Absolug Deviation
Mode (Boolean) include Mode
Minimum (Boolean) include Minimum
Maximum (Boolean) include Maximum
Range (Boolean) include Range
Count (Boolean) include Count
Sum (Boolean) include Sum
FirstQuartile (Boolean) include First Quartile
ThirdQuartile (Boolean) include Third Quartile
InterQuartileRange (Boolean) include Inter-Quartile Range
OtherPercentiles (Boolean) include OtherPercentiles
SetPercentileList (Array of Sets Array of Doubles corresponding to percentiles to
Doubles) include
GetPercentileList (Array of Gets Array of Doubles corresponding to percentiles to
Doubles) include

310
 StatTools_ParetoChart

StatTools_ParetoChart
Property or Method Description
DataType Controls whether one or two variables will be used in
(StatToolsParetoChartDataTy constructing the Pareto chart. Must be one of the
pe Enumerated Constant) following enumerated constants:
StatToolsParetoChartDataTypeCategoryOnly – in this
case, CategoryVariable will contain individual
readings/reasons. For example, each entry might
correspond to the reason a batch of parts was rejected.
ValueVariable is not used.
StatToolsParetoChartDataTypeCategoryAndValue -- in
this case, CategoryVariable will contain unique categories,
and ValueVariable will contain the corresponding
frequencies (counts).

CategoryVariable The variable containing category data. By default, each

(StatToolsVariable Object) unique category entry will be represented by a bar in the
Pareto chart.

ValueVariable When DataType is set to

(StatToolsVariable Object) StatToolsParetoChartDataTypeCategoryAndValue,
ValueVariable will contain the frequency (number of
occurrences) of each corresponding CategoryVariable
entry.

StatTools Core Analysis Pack Automation Reference 311

StatTools_ParetoChart
OptionalCategoryType Controls whether the report will include a “Misc” bar at the
(StatToolsParetoChartOptiona extreme right edge of the Pareto chart. Must be one of the
lCategoryType) following enumerated constants:
StatToolsParetoChartOptionalCategoryTypeNone – no
“Misc” bar will be displayed. Every unique category will be
represented as a bar on the Pareto chart.
StatToolsParetoChartOptionalCategoryTypeFixedValue –
a “Misc” bar with a frequency value equal to
FixedCategoryValue will be displayed. In addition, every
unique category will be represented as a bar on the Pareto
chart.
StatToolsParetoChartOptionalCategoryTypeCombined – a
“Misc” bar with a frequency value equal to the sum of all
category entries with a frequency less than or equal to
CombinedCategoryThreshold will be displayed. In
addition, every unique category with a frequency greater
than CombinedCategoryThreshold will be represented as
a bar on the Pareto chart.

FixedCategoryValue (Double) Specifies the height of a “Misc” bar added to the extreme
right side of the Pareto chart. Only used when
OptionalCategoryType is set to
StatToolsParetoChartOptionalCategoryTypeFixedValue.

CombinedCategoryThreshold Specifies the frequency threshold for combining small

(Double) categories. All category entries with a frequency less than
or equal to CombinedCategoryThreshold will be combined
into a single “Misc” bar added to the extreme right side of
the Pareto chart. Only used when OptionalCategoryType
is set to
StatToolsParetoChartOptionalCategoryTypeCombined.

312
 StatTools_SignTest

StatTools_SignTest
Property or Method Description
DefaultDataFormat Controls the default data format mode for the analysis.
(StatToolsDataFormat NOTE: This setting does not affect the analysis results in
Enumerated Constant) any way. Must be one of the following enumerated
constants:
• StatToolsDataFormatStacked
• StatToolsDataFormatUnstacked
AnalysisType Determines the type of analysis to be performed. Must be
(StatToolsSignTestAnalysisTyp one of the following constant values:
e Enumerated Constant) • StatToolsSignTestAnalysisTypeOneSample
• StatToolsSignTestAnalysisTypePairedSample
VariableList The list of variables to analyze. For one-sample analyses,
(StatToolsVariableList Object) this may be one or more variables. For paired-sample
analyses, the list must contain exactly two variables.
MedianNullValue (Double) The null-value of the median used in the hypothesis test.
MedianAlternativeType Specifies the type of alternative hypothesis for the test.
(StatToolsSignTestAlternativeT Must be one of the following constants:
ype Enumerated Constant) • StatToolsSignTestAlternativeNotEqual – a two-
tailed alternative
• StatToolsSignTestAlternativeLessThan – a one-
tailed alternative with the alternative less than the
null-value.
• StatToolsSignTestAlternativeGreaterThan – a
one-tailed alternative with the alternative greater
than the null-value.

StatTools Core Analysis Pack Automation Reference 313

StatTools_QQNormal

StatTools_QQNormal
Property or Method Description
VariableList the list of variables to analyze. In the current release
(StatToolsVariableList Object) of StatTools, you can populate this list with only a
single variable. Future versions of StatTools may
expand this analysis to support more than a single
variable. The variables must be unstacked.

StandardQ (Boolean) controls whether the y-axis of the graph uses a

standardize value (that is rescaled to a standard
normal) instead of the raw data. Setting this to TRUE
makes comparisons of the Y-axis values between Q-Q
normal plots possible.

314
 StatTools_RandomSample

StatTools_RandomSample
Property or Method Description
VariableList (StatToolsVariableList the list of variables to be analyzed. There must
Object) be between 1 and 32 variables to analyze. The
variables must be unstacked.

NumSamples (Integer) the number of samples to take from the variables.

Must be between 1 and 25.

SampleSize (Integer) the size of each sample. If

SampleWithReplacement is TRUE, this must be a
number between 1 and 65525. If
SampleWithReplacement is FALSE, this must be
a number between 1 and the size of the variables
being sampled.

SampleWithReplacement (Boolean) controls whether the sampling is done with

replacement or not. If TRUE, the same item can
be drawn multiple times in a single sample. If
FALSE, a single item can only be drawn once per
sample.

SampleMultipleVariablesIndependently controls whether multiple variables in the

(Boolean) VariableList are sampled together or
independently. If TRUE, each variable is sampled
independently, with no relationship between the
samples drawn for one variable to another. If
FALSE, the variables are all tied together when
they are sampled. Thus if a sample of the first
variable draws the 3rd data value, the second
variable’s 3rd element will also be drawn.

StatTools Core Analysis Pack Automation Reference 315

StatTools_Regression

StatTools_Regression
Property or Method Description
RegressionType controls the type of regression to be performed. Must
(StatToolsRegressionType be one of the following enumerated constant values:
Enumerated Constant) StatToolsRegressionMultiple
StatToolsRegressionStepwise
StatToolsRegressionForward
StatToolsRegressionBackward
StatToolsRegressionBlock

DependentVariable sets the dependent variable for the regression. Must

(StatToolsVariable Object) be an unstacked variable.

IndependentVariableList sets one or more independent variables for the

(StatToolsVariableList regression. Must be unstacked variables.
Object)

NumberOfBlocks (Integer) controls the number of blocks. Only relevant when

RegressionType is StatToolsRegressionBlock.

SetBlockList (Array of a function which sets which variables are members

Integers) of which blocks. Only relevant when RegressionType
is set to StatToolsRegressionBlock. The array
passed in should be the same size as the number of
variables in the IndependentVariableList property.
The value of each element of the array should be the
index of the block the corresponding element in the
IndependentVariableList is a member of.

GetBlockList (Array of a function which returns which blocks the variables

Integers) in the IndependentVariableList are members of. See
the SetBlockList function for more information. This
function only has affect when RegressionType is set
to StatToolsRegressionBlock.

316
 StatTools_Regression
EnterExitMode controls what parameters are used to determine
(StatToolsRegressionEnter whether a variable (or a block of variables.) This
ExitMode Enumerated property has no effect if RegressionType is set to
Constant) StatToolsRegressionMultiple. Must be one of the
following enumerated constant values:
o StatToolsRegressionUsePValues with the p-
values controlled by the PValueToEnter and
PValueToLeave properties
o StatToolsRegressionUseFValues with the F-
values controlled by the FValueToEnter and
FValueToLeave properties.

PValueToEnter (Double) the p-value at which a variable (or a block of

variables) may enter the regression equation. Must
be between 0 and 1, and must be less than
PValueToLeave. For this property to have effect,
EnterExitMode must be
StatToolsRegressionUsePValues, and
RegressionType must not be
StatToolsRegressionMultiple
PValueToLeave (Double) the p-value at which a variable (or a block of
variables) must leave the regression equation. Must
be between 0 and 1, and must be greater than
PValueToEnter. For this property to have effect,
UsePValue must be
StatToolsRegressionUsePValues, and
RegressionType must not be
StatToolsRegressionMultiple.

FValueToEnter (Double) the F-value at which a variable (or a block of

variables) may enter the regression equation. Must
be greater than FValueToLeave. For this property to
have effect, EnterExitMode must be
StatToolsRegressionUseFValues, and
RegressionType must not be
StatToolsRegressionMultiple.

StatTools Core Analysis Pack Automation Reference 317

StatTools_Regression
FValueToLeave (Double) the F-value at which a variable (or a block of
variables) must leave the regression equation. Must
be less than FvalueToEnter.. For this property to
have effect, EnterExitMode property must be
StatToolsRegressionUseFValues, and
RegressionType must not be
StatToolsRegressionMultiple.

GraphFittedValueVsActual controls whether a graph of the fitted regression

YValue (Boolean) values vs. the actual y-values present in the data is
generated as part of the report.

GraphFittedValueVsXValu controls whether a graph of the fitted regression

e (Boolean) values vs. the source x-values present in the data is
generated as part of the report.

GraphResidualVsFittedVal controls whether a graph of the residuals (errors) of

ue (Boolean) the regression curve vs. the fitted result is generated
as part of the report.

GraphResidualVsXValue controls whether a graph of the residuals (errors) of

(Boolean) the regression curve vs. the source x-values present
in the data is generated as part of the report.

IncludeSteps (Boolean) controls whether detailed information about each step

of the regression process are displayed as part of the
output of the report.

IncludePrediction controls whether the results of the analysis should be

(Boolean) applied to another data set in order to predict a set of
classification results for that data. The data set to
predict is specified in the PredictionDataSet property.

PredictionDataSet a data set to prediction classification values for. This

(StatToolsDataSet) property only has effect when IncludePrediction is set
to TRUE.

318
 StatTools_RunsTest

StatTools_RunsTest
Property or Method Description
VariableList the list of variables to be analyzed. There must be
(StatToolsVariableList Object) between 1 and 100 variables to analyze. The
variables must be unstacked.

CutoffType controls what type of cutoff value to use for the runs
(StatToolsRunsTestCutoffType test. Must be one of the following enumerated
Enumerated Constant) constant values:
o StatToolsRunsTestCutoffMean - uses the
mean of each variable as the cutoff.
o StatToolsRunsTestCutoffMedian - uses the
median of each variable as the cutoff.
o StatToolsRunsTestCutoffCustom - uses the
value specified in CustomCutoffValue as the
cutoff.

CustomCutoffValue (Double) specified a cutoff value to use for the runs test. This
value only has effect if the CutoffType property is set
to StatToolsRunTestCutoffCustom.

StatTools Core Analysis Pack Automation Reference 319

StatTools_SampleSize

StatTools_SampleSize
Property or Method Description
ParameterType controls what type of sample size is to be determined.
(StatToolsSampleSizeParameter Must be one of the following enumerated constant
Type Enumerated Constant) values:
StatToolsSampleSizeMean
StatToolsSampleSizeProportion
StatToolsSampleSizeDifferenceOfMeans
StatToolsSampleSizeDifferenceOfProportions

ConfidenceLevel (Double) controls the confidence level of the sample size

calculation. Must be a value between 0 and 1.

IntervalHalfLength (Double) controls the desired half-length of the confidence

interval you are seeking to cover.

EstimatedStdDev (Double) the estimated standard deviation of the sample, if the

ParameterType property is set to
StatToolsSampleSizeMean. The estimated common
sample size, if the ParameterType property is set to
StatToolsSampleSizeDifferenceOfMeans. This property
is ignored for other values of the ParameterType
property.

EstimatedProportion1 (Double) the estimated proportion of the sample, if the

ParameterType property is set to
StatToolsSampleSizeProportion. The first of the two
estimated proportions of the sample, if the
ParameterType property is set to
StatToolsSampleSizeDifferenceOfProportions. This
property is ignored for other values of the
ParameterType property.

EstimatedProportion2 (Double) The second of the two estimated proportions of the

sample, if the ParameterType property is set to
StatToolsSampleSizeDifferenceOfProportions. This
property is ignored for other values of the
ParameterType property.

320
 StatTools_ScatterPlot

StatTools_ScatterPlot
Property or Method Description
XVariableList (StatToolsVariableList a list of variables to be used for the x-values of the
Object) scatter graphs. There must be between 1 and 10
unstacked variables. Note: There will be one graph
generated for every unique combination of values in the
XVariableList and YVariableList.

YVariableList (StatToolsVariableList a list of variables to be used for the y-values of the

Object) scatter graphs. There must be between 1 and 10
unstacked variables. Note: There will be one graph
generated for every unique combination of values in the
XVariableList and YVariableList.

DisplayCorrelationCoefficient controls whether the correlation between each x-y pair

(Boolean) of variables is displayed under that pair’s scatterplot.

StatTools Core Analysis Pack Automation Reference 321

StatTools_Stack

StatTools_Stack
Property or Method Description
VariableList a list of variables to stack. There must be between 2 and 100
(StatToolsVariableList unstacked variables specified. The total number of items in
Object) the final stacked variable can not exceed 65535 cells.

CategoryVariableName the name to use for the resulting stacked category variable.
(String)

ValueVariableName the name to use for the resulting stacked value variable.
(String)

322
 StatTools_TimeSeriesGraph

StatTools_TimeSeriesGraph
Property or Method Description
DefaultUseLabelVariable controls whether the Time Series Graph Dialog defaults to
(Boolean) asking the user to specify a LabelVariable. NOTE: This
setting does not affect the analysis results in anyway.

VariableList the variables to graph. If SingleGraph is TRUE, there can

(StatToolsVariableList Object) be at most 10 unstacked variables. If SingleGraph is
FALSE< there can be up to 100 unstacked variables.

LabelVariable if specified, this variable supplies the labels on the x-axis

(StatToolsVariable Object) of all time-series graphs. If left as Nothing, the x-axis will
simply contain the integer positions of the data in the
array.

SingleGraph (Boolean) controls the placement of the time-series curves. If

TRUE, all the variables are plotted on the same graph. If
FALSE, each variable is placed on its own graph.

TwoVerticalAxes (Boolean) if exactly two variables are plotted, and if SingleGraph is

TRUE, this property controls whether the graph is drawn
with two separate y-axes, one for each variable.

StatTools Core Analysis Pack Automation Reference 323

StatTools_Transform

StatTools_Transform
Property or Method Description
VariableList the list of variables to transform. Must be between 1 and
(StatToolsVariableList 100 unstacked variables.
Object)

TransformationType what transformation operation to perform. Must be one of

(StatToolsTransformationTyp the following enumerated constant values:
e Enumerated Constant) o StatToolsTransformationLog
o StatToolsTransformationReciprocal
o StatToolsTransformationSquareRoot
o StatToolsTransformationSquare
o StatToolsTransformationCustom

Shift (Double) a shift applied to the source data before the transformation
function is applied. This property has no effect when the
TransformationType property is set to
StatToolsTransformationCustom.

CustomFunction (String) a custom transformation formula, used only if the

TransformationType property is set to
StatToolsTransformationCustom. This is a standard Excel
formula, with the keyword “variable” used wherever a
variable’s value should be substituted.

324
 StatTools_Unstack

StatTools_Unstack
Property or Method Description
ValueVariableList the value variable from which a group of unstacked
(StatToolsVariableList Object) variables will be created. Keep in mind, while the value
and category variables specified in this property and the
CategoryVariable property, when grouped together form
a stacking pair (that is, together they can make a whole
group of stacked variables) the value variable specified
here itself is an unstacked variable.

CategoryVariable the category variable from which a group of unstacked

(StatToolsVariable Object) variables will be created. Keep in mind, while the value
and category variables specified in this property and the
ValueVariable property, when grouped together form a
stacking pair (that is, together they can make a whole
group of stacked variables) the categorical variable
specified here itself is an unstacked variable.

StatTools Core Analysis Pack Automation Reference 325

StatTools_WilcoxonRankTest

StatTools_WilcoxonRankTest
Property or Method Description
DefaultDataFormat Controls the default data format mode for the analysis.
(StatToolsDataFormat NOTE: This setting does not affect the analysis results in
Enumerated Constant) any way. Must be one of the following enumerated
constants:
• StatToolsDataFormatStacked
• StatToolsDataFormatUnstacked
AnalysisType Determines the type of analysis to be performed. Must be
(StatToolsWilcoxonAlternativeT one of the following constant values:
ype Enumerated Constant) • StatToolsWilcoxonAnalysisTypeOneSample
• StatToolsWilcoxonAnalysisTypePairedSample
VariableList The list of variables to analyze. For one-sample analyses,
(StatToolsVariableList Object) this may be one or more variables. For paired-sample
analyses, the list must contain exactly two variables.
MedianNullValue (Double) The null-value of the median used in the hypothesis test.
MedianAlternativeType Specifies the type of alternative hypothesis for the test.
(StatToolsWilcoxonAlternativeT Must be one of the following constants:
ype Enumerated Constant) • StatToolsWilcoxonAlternativeNotEqual – a two-
tailed alternative
• StatToolsWilcoxonAlternativeLessThan – a one-
tailed alternative with the alternative less than the
null-value.
• StatToolsWilcoxonAlternativeGreaterThan – a
one-tailed alternative with the alternative greater
than the null-value.
CorrectForTies (Boolean) Controls whether the analysis will automatically correct for
ties.

326