newanalysis.RouteOutput(newanalysis.Dialog.Summary).Visible = True
newanalysis.RouteOutput(newanalysis.Dialog.Histograms).Visible = True

How Are Case Selection Conditions and Case Weights Handled in Recorded Macros?

It depends on whether you are recording a Master Macro or an Analysis Macro. The general rule is that case selection conditions and case weights specified via the Select Cases or Case Weights buttons in a specific analysis are recorded into the respective Analysis Macro as well as the Master Macro (if one is being recorded at the time); when case selection conditions or case weights are changed from the Tools menu, then those changes are only recorded in Master Macros.

How Are Output Options Handled in Recorded Macros?

It depends on whether you are recording a Master Macro or an Analysis Macro. Like with case selection conditions and case weights, if the Analysis/Graph Output Manager is brought up via the Output option for a specific analysis from the Options menu (of the respective analysis dialog), then the choices on that dialog will be recorded into the respective Analysis Macro as well as the Master Macro (if one is being recorded at the time); when output options are changed by choosing Tools - Options, and then the Output Manager tab, then any changes made to the output options are only recorded in Master Macros.

General SVB Language Features

What Data Types Are Supported in SVB?

STATISTICA Visual Basic supports several data types including Double, Integer, Long, Boolean, String, Variant, and Object.

The Double data type and the Integer and Long data types are probably the ones most commonly used in computations. Variables declared as Double can hold (store) real numbers, approximately in the range from +/-1.7E +/- 308 (approximately 15 digits of precision); variables declared as Integer can hold (store) integer numbers in the range from -32,768 to 32,767, and Long variables can hold (store) integer numbers in the range from -2,147,483,648 to 2,147,483,647; other common data types are Boolean (True [1] or False [0]) and String (a string variable of arbitrary length). Refer to the Electronic Manual for a description of all data types.

Declaring variables. Variables should be declared at the beginning of each program by using the dim command; for example:

   ...
Dim i As Integer, j As Long
Dim x As Double, v As Variant
   ...

' This program illustrates the Variant data type;
' Variant's can be empty, numeric, currency, date,
' string, object, error code, null or array value;
' here, only the numeric, currency, and string
' identities are illustrated.
Sub Main
    Dim CurrentDateAndTime As Variant
' The Now function will return the current system
' time and date.
    CurrentDateAndTime = Now
    AsDouble(CurrentDateAndTime)
    AsLong(CurrentDateAndTime)
    AsCurrency(CurrentDateAndTime)
    AsString(CurrentDateAndTime)
End Sub

Sub AsDouble (x As Double)
    MsgBox "x+1="+Str(x+1)
End Sub

Sub AsLong (x As Long)
    MsgBox "x+1="+Str(x+1)
End Sub

Sub AsCurrency (x As Currency)
    MsgBox "x+1="+Str(x+1)
End Sub

Sub AsString (x As String)
    MsgBox x
End Sub

How Do I Assign a Value to a Variable?

Here are examples of simple declarations of variable types, and how to assign values to them:

' This program illustrates simple assignments of
' values to variables and elements in arrays.
Sub Main
Dim i As Long, j As Long
Dim c As String
Dim x As Double
Dim xx(10) As Double
Dim xx1(1 To 10) As Double
  i=1
  j=2
  x=i+j
' Note that the Str(x) function converts x
' to a string.
  c="1+2="+Str(x)
' This function will display a message box
' with the text "1+2=3"
  MsgBox c
  xx(0)=x
  xx1(1)=x
  xx(10)=xx(0)+xx1(1)
' Note that the _ (underline) at the end of a
' line can be used to continue a statement to the
' next line.
  c="1+2 + 1+2 =" _
    +Str(xx(10))
  MsgBox c
End Sub

Sub Main
      Dim wb As Workbook
      Dim ss As Spreadsheet
      Dim g As Graph
      Set wb=ActiveWorkbook
' Note that the _ (underline) at the end of a
' line can be used to continue a statement to the
' next line.
      Set ss=Spreadsheets.Open( _
        "j:\Statistica\Examples\Datasets\Adstudy.sta")
      ss.Visible=True
      Set g=ActiveGraph
End Sub

What Are Collections?

A collection is very similar to an array; however, the collection is an object with various methods that in many instances make dealing with a collection much more convenient than dealing with an array. In STATISTICA Visual Basic, all results spreadsheets and graphs from analyses are returned as collections, which makes the programmatic editing, storing, and further processing of results very convenient.

How Do I Specify a Conditinal Instruction (If ... Then)?

The following program illustrates various general features of the Visual Basic (VB, and SVB) language including a conditional instruction.

Sub Main
' Bring up a Message Box, with the Ok and Cancel buttons,
' and with the following text; note the continuation
' symbol _ (underline) at the end of the first line,
' to allow the single statement to span two lines.
      If MsgBox ("Hello! Click OK or Cancel", _
          vbOkCancel)=vbOK Then
        MsgBox "You clicked OK"
      Else
        MsgBox "You clicked Cancel"
      End If
End Sub

How Do I Execute an Expression in a Loop?

Here is an example of a simple (For...Next) loop. The loop is used to fill array x with values between 1 and 10.

' This program illustrates simple assignments of
' values to array elements.
Sub Main
Dim i As Long
Dim x(10) As Double
' Note that array x is zero-referenced by default;
' i.e., the first element in array x is x(0), and
' not x(1). Do not include the statement:
' Option Base 1
' at the beginning of this program file, or else the
' program will not run.
 For i=0 To 10
   x(i)=i
 Next i
End Sub

I Already Know about Visual Basic; Does SVB Support Advanced Language Features?

STATISTICA Visual Basic is an advanced programming environment that allows experienced programmers to build large and complex custom applications. Support is provided for subroutines and functions, as well as user-defined class modules and object modules.

What Are Subroutines and Functions?

Typically, complex applications written in STATISTICA (or any other) Visual Basic are structured. In other words, most programs will not consist of a single routine, but of many separate routines that will call each other. Every macro program consists of a Main program inside a Sub Main ... End Sub block. Inside the main program you can call subroutines and functions to perform repetitive tasks, or just to keep the structure of your program transparent. Here is an example program that consists of several subroutines and functions; note that the main program performs no computations, and only contains calls to the subroutines.

' This program will compute the sum of the
' squared values from 1 to 10. The program
' illustrates how subroutines and functions
' are declared, and how different numeric
' and string data types are declared and
' passed to subroutines and functions.
Sub Main
' Declare x as an array of double values;
' there are 10 elements in this array, which
' can be addressed as x(1), x(2), etc. (i.e.,
' the lower bound of the array is element 1,
' the upper bound is 10).
      Dim x (1 To 10) As Double
      Dim SumValue As Double, ResText As String
' The following subroutine will fill the array
' with numbers from 1 to 10.
      ComputeArray x()
' A function is called to compute the sum of
' the squared values in array x; note how
' we do not pass explicitly the lower and
' upper bounds for array x, but use functions
' (LBound, UBound) to retrieve those values.
      SumValue=ComputeSumOfSqrs ( LBound (x), _
                                  UBound(x), _
                                  x)
' The following subroutine makes the results string
' ResText.
      MakeResultsText SumValue,x(),ResText
      MsgBox ResText
End Sub

' In this subroutine, a For...Next loop is
' used to fill array x with values between
' 1 and 10.
Sub ComputeArray(x() As Double)
      Dim i As Integer
      For i =1 To 10
        x(i)=i
      Next i
End Sub

' This function computes the sum of the squared
' values in an array of double numbers. The
' function returns a double value.
Function ComputeSumOfSqrs (iFrom As Long, _
                           iTo As Long, _
                           x() As Double) As Double
      Dim i As Integer
      ComputeSumOfSqrs=0
      For i= iFrom To iTo
      ComputeSumOfSqrs=ComputeSumOfSqrs+x(i)^2
      Next i
End Function

' The following subroutine makes the results text, to be
' displayed at the end of the Main program.
Sub MakeResultsText(SumValue As Double, _
   x() As Double, _
   ResText As String)
      ResText="The sum of the square of values from " + _
                 Str(LBound(x)) + _
                 " to " + _
                 Str(UBound(x)) + _
                 " is " + _
                 Str(SumValue)
End Sub

What Is the Difference between Passing Variables to Subroutines and Functions By Value and By Reference?

If you want to pass a variable to a subroutine, run computations on it, and alter its contents, then the variable must be passed by reference (this is the default method how arguments are passed to subroutines or functions). Essentially, passing a variable by reference means passing the variable itself to the subroutine, and any changes made to it in the subroutine will be permanent. By contrast, if you want to pass a variable, run computations on it, and alter the temporary instance of it within the subroutine without affecting the original variable, then you must pass the variable by value. When a variable is passed by value to a function or subroutine, only a copy of the variable is passed, not the actual variable. If any changes are applied to the variable within the called function, then those changes will only pertain to the copy of the original variable. When passing a variable by value, its value will always be preserved, no matter what is done within the called function. To illustrate, instead of making ComputeSumOfSqrs in this example a function, we could make it a subroutine and pass the variable SumValue as an argument by reference; by using this approach, SumValue will be directly altered by the subroutine without needing to return a value. Note that the ByRef keyword in the example below would be optional, since the default method of passing arguments to subroutines or function is by reference.

Sub Main
      ...
      ...
      ComputeSumOfSqrs ( LBound (x), _
                         UBound(x), _
                         x, _
                        SumValue)
      ...
      ...
End Sub
' Now, ComputeSumOfSqrs is a subroutine, with arguments passed
' explicitly by value, or by reference (note that arrays are
' always passed by reference).
Sub ComputeSumOfSqrs ByVal iFrom As Long, _
                     ByVal iTo As Long, _
                     x() As Double, _
                     ByRef SumOfSqrs As Double
      Dim i As Integer
      SumOfSqrs=0
      For i= iFrom To iTo
      SumOfSqrs=SumOfSqrs+x(i)^2
      Next i
End Sub
      ...
      ...

What Are Local Variables vs. Global Variables?

Variables declared in a Visual Basic program are visible (i.e., they can be referenced) inside the "scope" where they are defined. The scope is the program unit inside of which the variable is defined. For example, variables declared inside a subroutine are only visible inside that subroutine. Variables declared outside any routines, before any program code, are visible to all subroutines and functions in the same file. In the programs shown below, variable a is either defined inside the Main routine, and then must be passed to the subroutine that displays its value, or it is declared as a global variable, outside the Main routine, in which case it is visible in all subroutines and functions in the same file.

Here is a simple program, where the variable must be passed, because it is defined only inside the scope of the Main program.

Sub Main
 Dim a As Long
 a=1
 DisplayVariableA a
End Sub

Sub DisplayVariableA (a As Long)
 MsgBox Str(a)
End Sub

Dim a As Long
Sub Main
 a=1
 DisplayVariableA
End Sub

Sub DisplayVariableA
 MsgBox Str(a)
End Sub

Can I Define My Own Class Modules and Object Modules?

STATISTICA Visual Basic supports class modules and objects modules. A discussion of classes and objects and the advantages (and some disadvantages) of object-oriented programming is beyond the scope of this introductory documentation; you should consult more advanced general sources on Visual Basic for details. In general, when developing large projects in Visual Basic, it is advantageous to impose as much structure on the program as possible, i.e., to break it down as much as possible into smaller functional units. This can be accomplished to a large extent by subroutines and functions; however, another way is by defining classes.

For example, you may want to use in your computations some highly customized way in which to compute some statistics to denote the central tendency for a dataset. One such statistic is, for example, the mean, but there may be additional considerations and problems that preclude you from using the simple arithmetic mean (e.g., censoring, missing data, highly skewed distributions, invalid data ranges, etc.). You may want to define a separate set of routines, options, etc., to compute the central tendency of a dataset. One way to do this is to create a class that contains the respective functions, subroutines, variables, etc. This class could for example compute the central tendency in one variable (e.g., variable CentralTendency), and the method that was used as a name in another variable (e.g., variable MethodName).

One of the advantages of using classes, as opposed to simple subroutines and functions, is that you can program all "things" related to the central tendency measure in a separate file. In the actual program, you would always access a variable called CentralTendency; even if the method for computing the central tendency is refined or variables are added to the class, etc., you don't have to rewrite the code that uses these measures at all. In other words, the class itself can be modified or refined, or another team of programmers could develop it, while the programs that use the class do not have to be modified at all.

Classes vs. objects. The difference between classes and objects is that classes have to be explicitly declared (instantiated) in the program that uses them, while objects are automatically instantiated and available at all times. Both of these will be illustrated in a simple example below.

The asterisk (*) convention: Writing portable programs. When writing programs that include classes or objects, and that are to be deployed on other computers you can use the asterisk (*) convention to access the include files that contain the classes and objects. Specifically, after you wrote (defined) your class or object modules, save them either in the directory where STATISTICA is installed (where the STATISTICA executable programs are located), in the directory where the current module is running from (if it has been saved), or in the global macro directory. To access modules from within an SVB program, you can then use, for example, #Uses "*MyClassModule.svc", to access the previously saved class module MyClassModule.svc, and you do not have to use the explicit reference to the respective directory (e.g., #Uses "J:\STATISTICA\Examples|Macros\MyClassModule.svc"). Thus, by using the asterisk (*) convention with the #Uses or $Include directives.

A simple example. Suppose you wrote a program to retrieve some keys (key-codes) or passwords to gain access to particular datafiles or programs. The main program does nothing else but access the class (or object) that generates those keys. The method in which those keys are computed is entirely "encapsulated" inside the respective class (or object).

Create the following three files as STATISTICA Visual Basic macro programs. The first one defines Class as the Module Type (when creating the new Visual Basic document); call this program KeyCodesClass. The screen below shows the selections from the Create New Document and the Module Type dialogs to create the KeyCodesClass module.

The second file defines Object as the Module Type; call this program KeyCodesObject. As a third file, create a standard STATISTICA Visual Basic macro program, and call it RetrieveKeyCodes; note that only this latter program will automatically have the Sub Main ... End Sub declarations inserted into the code.

Now enter the following code into these programs:

The Class Module: KeyCodesClass

' This file contains the code that defines the
' KeyCodesClass,i.e., the functions and subroutines
' that belong to this class. This file should be created
' (or already exists) as:
'
' J:\STATISTICA\Examples\Macros\KeyCodesClass.svc
'
' Variable KeyCode is defined globally inside this
' file; it can be accessed by the class member functions
' and subroutines.
Dim KeyCode As String

Private Sub Class_Initialize()
' This function is called when you initialize the class.
' Here you could put the code to generate the keycodes
' for various versions, etc.
' For the example, we will simply set it to a constant
' string.

KeyCode="ThisIsMyCodeFromTheClass"
End Sub

Private Sub Class_Terminate()
' This function is always called when you terminate
' the program, and this class. You could, for example,
' put some code here to update some data base, or internal
' counters that keep track of how many times the key codes
' program (class) has been used.
  MsgBox "KeyCodesClass is terminating."
End Sub

Function RetrieveCodeFromClass As String
' This is the routine that will be called to
' retrieve the code from this class.

  RetrieveCodeFromClass=KeyCode
End Function

' This file contains the code that defines the
' KeyCodesObject,i.e., the functions and subroutines
' that belong to this object. This file should be created
' (or already exists) as:
'
' J:\STATISTICA\Examples\Macros\KeyCodesObject.svo
'
' Variable KeyCode is defined globally inside this
' file; it can be accessed by the member functions
' and subroutines.
Dim KeyCode As String

Private Sub Object_Initialize()
' This function is called when you initialize the object.
' Here you could put the code to generate the keycodes
' for various versions, etc.
' For the example, we will simply set it to a constant
' string.
  KeyCode="ThisIsMyCodeFromTheObject"
End Sub

Private Sub Object_Terminate()
' This function is always called when you terminate the
' program, and this object. You could, for example,
' put some code here to update some data base, or internal
' counters that keep track of how many times the key codes
' program (object) has been used.
  MsgBox "KeyCodesObject is terminating."
End Sub Function RetrieveCodeFromObject As String
' This is the routine that will be called to
' retrieve the code from this object.
  RetrieveCodeFromObject=KeyCode
End Function

' This program illustrates the use of classes and
' objects in STATISTICA Visual Basic. The following
' two lines include the references to definitions
' for a class module and an object module, respectively.
' (Files containing a class module have the extension
' .svc; files containing an object module have the
' extension .svo)
' NOTE: The directory in which these files are located may
' be different in your installation of STATISTICA.
'#Uses "J:\STATISTICA\Examples\Macros\KeyCodesClass.svc"
'#Uses "J:\STATISTICA\Examples\Macros\KeyCodesObject.svo"
Sub Main
' Because KeyCodesClass is a Class, an object of this type
' has to be explicitly created (initialized).
      Dim Keys As New KeyCodesClass
      MsgBox Keys.RetrieveCodeFromClass
' KeyCodesObject is an object module, so it already exists.
' We can simply call it.
      MsgBox KeyCodesObject.RetrieveCodeFromObject
' The following line will explicitly destroy
' this instance of the KeyCodesClass, i.e., call
' the destructor function for that class.
      Set Keys = Nothing
End Sub

Can I Expand My SVB By Calling External DLLs?

There are two ways in which you can access external libraries from STATISTICA Visual Basic. The first method is the easiest, but relies on the external DLL's compliance with Visual Basic standards. In other words, if the external DLL (program) supports Visual Basic (e.g., such as Microsoft Excel), you can select Tools - References from the STATISTICA Visual Basic toolbar to load the respective libraries. The objects, functions, methods, etc. in that library are now accessible like all STATISTICA Visual Basic functions. So you could, for example, create from within STATISTICA Visual Basic an Excel Spreadsheet, perform some spreadsheet operations and computations, and then transfer the results back to a STATISTICA Spreadsheet (e.g., via the .Copy and .Paste methods).

Writing your own DLLs, or accessing "exported" functions in external DLLs. You can also access "exported" functions or subroutines in other DLLs, even if they were not specifically designed to work with Visual Basic. For example, if you are an experienced C++ programmer, you may want to add some highly customized computational routines to your STATISTICA Visual Basic program. In a sense, this method of accessing "the outside world" would allow you to add custom program options to STATISTICA; for example, you may have a proprietary complex algorithm, implemented in a complete program (which includes its own user interface), for evaluating stocks based on historical data. You could write a STATISTICA Visual Basic program to put a new option on the Statistics menu to execute this program and call your custom program when this option is chosen.

There are a number of things to consider when writing your own DLLs that are to be called by STATISTICA Visual Basic, or when writing STATISTICA Visual Basic programs to access functions in such DLLs.

Declaration of functions and subroutines in the external DLL. SVB requires that the external DLL use the _stdcall calling conventions. This is true of all Win32 API calls (allowing them to be used directly from SVB), but when defining your own entry points in a custom DLL, care must be taken to make sure the export is defined correctly. Here are two prototypes of sample routines that could be called from SVB:
            extern "C" int AFX_API_EXPORT WINAPI SampleFunction(int x);
            extern "C" void AFX_API_EXPORT WINAPI SampleSubroutine(int q);

'where:

'extern "C"             means this name is not "decorated" (as C programmers used to say) with C++ type information;

'AFX_API_EXPORT   is defined to __declspec(dllexport), which tells the compiler to export 'this name;

'WINAPI                        is defined to __stdcall, meaning use "standard calling conventions."

Calling external functions and subroutines. To use these routines in STATISTICA Visual Basic, you need to "declare" them in the declarations area of your SVB program (before the first function is defined). Refer to the Electronic Manual for a full explanation of the Declare statement and its options. For example:

Private Declare Sub SampleSubroutine Lib _
"J:\DLLTest\Debug\DLLTest" _
            Alias "_SampleSubroutine@4" (ByVal X As Integer)
      Private Declare Function SampleFunction Lib _
"J:\DLLTest\Debug\DLLTest" _
      Alias "_SampleFunction@4" (ByVal X As Integer) _
      As Integer

Sub Main
 Dim ii As Integer
      Dim jj As Integer
      jj=1
      ii=SampleFunction(jj)
      SampleSubroutine(jj)

End Sub

SVB Development Environment

Does the SVB Environment Provide Tools for Debugging?

Once a macro program has been specified, the STATISTICA Visual Basic environment provides powerful methods for testing and debugging the program. You can set individual breakpoints in the program where you want the program to stop temporarily to allow you to look at the values of variables at that point (you can set and clear breakpoints by pressing F9 or by clicking the Toggle breakpoint toolbar button). You can step through the program by pressing SHIFT+F8 or clicking the Step over toolbar button.

Note that the variables in the Watch window (tab) not only can be observed, but they can also be changed interactively as the program is running.

How Can I Get On-Line Help?

The STATISTICA Visual Basic language contains ("understands") all standard Visual Basic language declaration, features, and functions, as well as more than 10,000 functions, declarations, statements, etc. that provide access to the STATISTICA functionality. To read more about a particular Visual Basic (non-STATISTICA specific) statement such as Dim, For...Next, etc., highlight the respective statement and press F1.

To learn how to access the STATISTICA specific functions and procedures, study the STATISTICA object model. The various features of graphs, spreadsheets, and reports are logically organized into hierarchies of objects. The objects representing the standard analyses (and graphs) are organized according to the "flow" of dialogs, as if you were performing an interactive analysis. This is best illustrated if you record an analysis in a STATISTICA Visual Basic macro program. Every dialog is a separate object, and all the options available on the respective dialogs are properties. In practically all cases, after you record a macro, you will be able to match the various properties that were recorded (for the different dialogs) with the detailed descriptions of the respective options in the context of the dialog help.

What Is the Function Browser?

There are numerous functions specific to STATISTICA, and generally only available in STATISTICA Visual Basic. These are extensions to the general Visual Basic language, such as probability functions, matrix functions (see also page 1000), simple user input dialogs, etc. You can review these functions in the Function Browser, which is accessible via the SVB View menu or by clicking the Function Browser toolbar button.



Shown below is a simple program that will "look up" the z value for p = .975.

Sub Main
        Dim p As Double
        p=VNormal(.975,0,1)
        MsgBox "For z=.975, p="+Str(p)
End Sub

How Are Errors Handled During the Execution of an SVB Program?

STATISTICA Visual Basic provides the same facilities for error handling as other general implementations of Visual Basic. Thus, detailed discussions on error handling can be found in the numerous general sources describing this programming language.

General Visual Basic errors, math errors, etc. A standard method for trapping general Visual Basic errors, such as math errors (e.g., division by zero), is to use the On Error Goto ... statement, to direct the program flow to a particular label in the program. Note that each subroutine and function should have its own On Error Goto statement. Here is a simple example program that will generate a division-by-zero math error.

Sub Main
' Set the label where to go to if an
' error occurs.
    On Error GoTo DisplayVBError
    Dim x As Double, y As Double
    y=0
' Division-by-zero error
    x=2/y
    Exit Sub
' An error occurred; Visual Basic maintains
' an object called Err with various properties;
' the Description property contains the description
' of the most recent error.
DisplayVBError:
    MsgBox Err.Description
    Exit Sub
End Sub

How Are Non-Fatal Errors (Warnings) Handled During the Execution of an SVB Program?

In many instances throughout interactive analyses you may receive non-fatal error (warning) messages, for example, to inform you that some missing data were replaced by means, that some variables were dropped from the analyses, that some parameters were reset, etc. Usually, these warning will not require that the respective analyses be terminated, but the information provided in these warnings may be important for the user to be aware of.

When such warning messages occur during the execution of an SVB program, the Analysis Warning dialog will come up displaying the warnings that have occurred, when they occurred (the time and in which specific analysis), the approximate line numbers in the SVB program code where the warnings occurred, etc; if the respective non-fatal error, when it occurred during the interactive analysis, required some user response (e.g., Yes/No in response to a question whether or not to continue), then that user-input is also shown in the Message field.

This dialog will allow you to manage the warnings that occurred during your current "session" with STATISTICA (running SVB programs). Note that the warnings are collected across multiple analyses, and you can at any time create a Report of these analysis, send them to a Spreadsheet (so you can write SVB code to further process these messages), etc.

The GetAnalysisErrorReport method. When running STATISTICA analyses via Visual Basic from another application (e.g., from inside MS Excel), it can be desirable to deal with the warnings inside the other applications, without bringing up any STATISTICA specific dialogs. For example, you may want to place the warning messages into particular cells of an MS Excel spreadsheet. For that purpose, the Application object of STATISTICA contains a specific method:

Function GetAnalysisErrorReport( _
    [MakeVisible As Boolean = True]) As Spreadsheet

Does SVB include a "Dialog Painter"?

Yes, a interactive dialog editor is included that allows you to build dialogs by dragging controls from a toolbar with the mouse.

Using SVB to Manage Analyses, Data Files, Graphs, etc.

How Is SVB Integrated with STATISTICA Data (Input), Analyses and Output?

The STATISTICA libraries contain all functions that allow you to fully program and customize your STATISTICA application; these functions can be called from other applications that support the standard Visual Basic language, such as Microsoft Visual Basic, Microsoft Excel, etc.

Organization of SVB programs. STATISTICA Visual Basic is organized around analysis objects; for example, to run an analysis with the STATISTICA Basic Statistics module, you would first create an analysis object with the constant scBasicStatistics and (optionally) with a datafile name (location of the file containing the input spreadsheet). To make access to the thousands of statistical functions and options available in the STATISTICA system as convenient as possible, SVB maintains a very close correspondence between the dialogs as they are presented during interactive analyses, and the flow of the SVB program. In a sense, once an analysis has been created, such as an analysis via the Basic Statistics module, you simply "program the dialogs" for the respective statistical analysis. Put another way, if you were to do the analysis by hand, then, after invoking the Basic Statistics module, you would follow through a sequence of dialogs to specify the desired analysis.

You can think of each dialog as a property of the (e.g., Basic Statistics) analysis, and of each option, selection, etc. on that dialog as a property of that dialog. Thus, you first invoke a module by declaring the respective analysis object, and then set the desired options etc. as properties of the analysis (and the dialogs of that analysis). Note that when designing actual programs, the automatic macro recording facilities of STATISTICA will do most of the programming work for you. You simply run the desired analyses interactively, and then create the macro for those analyses that macro will contain all of the programming code to recreate the analysis step by step, and it can easily be edited (copied, pasted) to create the desired customized application.

Moving between implied dialogs of the statistics module. To move from one dialog to the next when running STATISTICA interactively, you click the OK button (to move forward to the next dialog) and the Cancel button (to return to the previous dialog). SVB has two methods to accomplish this that belong to the analysis object: Run (to move forward to the next dialog) and GoBack (to return to the previous dialog).

Creating output documents. Most results from STATISTICA analyses are presented in results spreadsheets and graphs. When running STATISTICA interactively, you would create results spreadsheets and graphs by clicking on the respective buttons on the results dialogs. In SVB, each results "button" can be (implicitly) clicked by executing the respective method, that is part of the respective dialog. For example, every results dialog in STATISTICA has a Summary button to create the most "important" results from the respective analysis. In SVB, every results dialog has a Summary method to do the same.

Results spreadsheets and graphs. Each method that can be used to produce results spreadsheets and graphs (e.g., the Summary method) will return a Collection of spreadsheet objects, graph objects, or spreadsheet and graph objects. Note that even if the respective results spreadsheet or graph consists of only a single document, it will still be returned as a collection. Thus, you can use the standard Visual Basic conventions to retrieve individual objects from the collection, etc.

RouteOutput method, and AnalysisOutput objects. When running STATISTICA interactively, the output spreadsheets and graphs can be sent to workbooks (by default), stand-alone windows, reports, etc., depending on the selection of options on the Analysis/Graph Output Manager dialog. The choices of options in that dialog are implemented by the AnalysisOutput object, which can be used as a "container" for the results spreadsheets and graphs. Typically, a summary results spreadsheet or graphs collection would be recorded in an Analysis Macro or Master Macro as:

newanalysis.RouteOutput(newanalysis.Dialog.Summary).Visible=True

What Are the Names for the STATISTICA Reference Libraries (Modules)?

How Can I Access Results Spreadsheets, Graphs, Workbooks Etc.?

The STATISTICA Visual Basic object model provides access to practically all aspects of STATISTICA analyses, and the results of those analyses. When you perform an interactive analysis, and record a macro program (see also How Can I Record My Analysis in a STATISTICA Visual Basic Program?, page 942), you will see that all of your output choices are recorded. The most important thing to remember is that all output spreadsheets and graphs are returned as a Collection of spreadsheet and graph objects respectively (see also What Are Collections?, page 957). You can retrieve and modify these objects in your program; for example, you can make the results (spreadsheet) of one analysis the input to the next analysis. Here is an example program:

Sub Main
Dim newanalysis As Analysis
Dim s As Object
Dim PPlot As Object
' Create the STATISTICA Basic Statistics Analysis object;
' open the input data spreadsheet (example file) 10items.sta
' NOTE: This file may reside in a different directory on
' your installation.
      Set newanalysis = Analysis (scBasicStatistics, _
            "J:\STATISTICA\Examples\Datasets\10items.sta")
' Select from the startup dialog of Basic Statistics, option
' Descriptives (the first option on the startup dialog).
      newanalysis.Dialog.Statistics = scBasDescriptives
' "Click OK", i.e., Run this dialog.
      newanalysis.Run
' On the following dialog, select all variables 1-10.
      newanalysis.Dialog.Variables = "1-10"
' Make the Summary results (descriptive statistics) spreadsheet.
      Set s=newanalysis.Dialog.Summary

' Create a 2D Probability Plots object; use the results
' spreadsheet from the previous analysis as the input spreadsheet.
      Set newanalysis = Analysis (sc2dProbabilityPlots, s.item(1))
' Request a Normal Probability plot for variable 2 (Means).
      With newanalysis.Dialog
          .Variables = 2
          .GraphType = scProbNormal
      End With
' Create the normal probability plot of means for all variables in
' file 10items.sta.
      Set PPlot=newanalysis.Dialog.Graphs
      PPlot.Visible=True
End Sub

How Can I Create a Blank Graph, and Set Data Directly into the Graph?

Practically all graphics options of STATISTICA are directly accessible via SVB; this makes SVB a very powerful graphics programming language. The following program shows how to create a blank 2D graph, set some data into the graph, and add an arrow.

Option Base 1
Sub Main
    Dim i As Integer
      Dim g As New Graph
      Dim gl As Layout2D
' Make a graph object with content.
    Set gl=g.GraphObject.CreateContent(scg2DGraph)
' Make room for 10 data points.
    gl.Plots.Add(scgSimplePlot,10)
' Make the data.
    For i=1 To 10
     gl.Plots(1).Variable(1).Value(i)=i
     gl.Plots(1).Variable(2).Value(i)=Log(i)
    Next
' Let us add an arrow to this graph.
    Dim x(2) As Double, y(2) As Double
' Point to location..
    x(1)=2
    y(1)=Log(2)
' Point from location...
    x(2)=2.5
    y(2)=1.5
    g.ExtraObjects.AddDynamicArrow(x(1),y(1),x(2),y(2))
' Finally make the graph visible.
    g.Visible=True
End Sub

What Is the RouteOutput Method, What Is the AnalysisOutput Object?

When running STATISTICA interactively, the output spreadsheets and graphs can be sent to workbooks (by default), stand-alone windows, reports, etc., depending on the selection of options on the Analysis/Graph Output Manager dialog (accessed by selecting Output from the Options menu). The choices of options in that dialog are implemented by the AnalysisOutput object, which can be used as a "container" for the results spreadsheets and graphs. Typically, a summary results spreadsheet or graphs collection would be recorded as:

newanalysis.RouteOutput(newanalysis.Dialog.Summary).Visible=True

Sub Main
' NOTE: This file may reside in a different directory on
' your installation. Also, if you recorded this portion of
' the code via a Master Macro [option Tools - Macro - Start
' Recording of Log of Analyses (Master Macro) ], consecutive
' analyses would be enumerated as newanalysis1, newanalysis2,
' etc., and the input datafile spreadsheets would be explicitly
' assigned to variables (objects) S1, S2, etc.
      Set newanalysis = Analysis (scBasicStatistics, _
            "j:\STATISTICA\Examples\Datasets\exp.sta")
      newanalysis.Dialog.Statistics = scBasFrequencies
      newanalysis.Run
      newanalysis.Dialog.Variables = "1-8"
' Create the Analysis Output object as requested by
' the current settings in the Output Manager.
      Set r=newanalysis.RouteOutput(newanalysis.Dialog.Summary)
' Make sure that the AnalysisOutput object contains
' a Workbook.
      If (r.HasWorkbook=True) then
' We will next find the first results spreadsheet
' (frequency table) that was produced, and extract it
' from the workbook as a stand-alone spreadsheet; note
' that the objects are explicitly dimensioned in the
' following SVB code, to make it more transparent.
      Dim w as Workbook
      Set w=r.Workbook
      Dim wi As WorkbookItem
      Set wi=w.Root.Child
      While (wi.Type<>scWorkbookItemTypeSpreadsheet)
       Set wi=wi.Child
      Wend
      Dim s As Spreadsheet
      Set s=wi.Extract(scWorkbookExtractCopy)
      s.Visible=True
      End If
End Sub

What Kind of Output Can I Create with SVB?

There are a number of possible ways to display results, numbers, messages, etc. generated with a STATISTICA Visual Basic program. Most often, you will want to present results in spreadsheets, graphs, or reports. A very useful method for sending results spreadsheets and graphs to a current default "place" (workbook, stand-alone window, report) is to use the RouteOutput method described earlier (see page 979). However, you can also copy and paste results from STATISTICA into spreadsheets, text documents, etc., as long as those other types of output objects ("belonging" to other applications, such as Microsoft Excel or Word) support the Visual Basic standards.

Probably, the method you will most frequently use to display results is via spreadsheets and graphs; occasionally, you may also want to write some text or tables into a report. All of these are supported as objects, in the STATISTICA Visual Basic object model. For example, the following program will produce a spreadsheet, a line graph, and a report that will contain the spreadsheet and the line graph. All of these output objects will then be placed into a new workbook.

Note that the following program does not use the RouteOutput method (see page 979) to send the spreadsheet and graph to a default location (e.g., workbook) as currently defined via the Analysis/Graph Output Manager. Instead, the program illustrates how you can explicitly create spreadsheet and graph objects and move them to the location of your choosing.

Sub Main
Dim newanalysis as Analysis
' Create a new workbook; by default it will be
' empty and "invisible."
      Dim wb As New Workbook
' Create a new report; by default it will be
' empty and invisible.
      Dim r As New Report
' Create a new Spreadsheet; by default it will
' contain 10 rows and 10 columns, and it will
' be invisible.
      Dim ss As New Spreadsheet
' Declare an object of type Graph; we will
' create it later as a line graph.
      Dim g As Graph
      Dim NumberOfRows As Long
      Dim NumberOfColumns As Long
      Dim i As Long,j As Long
      NumberOfRows=100
      NumberOfColumns=5
' Note how we can dynamically "re-dimension" arrays.
      ReDim x(1 To NumberOfRows, _
         1 To NumberOfColumns) As Double
' Here we fill the data array x with numbers
      For i=1 To NumberOfColumns
       For j=1 To NumberOfRows
         x(j,i)=Exp(j*i/500)
       Next j
      Next i
' Next put the numbers into the spreadsheet ss. First
' we will resize the default (10 x 10) spreadsheet
' to make room for the 100 x 5 data matrix.
      ss.SetSize(NumberOfRows,NumberOfColumns)
' The following line is a shortcut method for copying
' the entire array into the spreadsheet.
      ss.Data=x
' Alternatively, the following loop could be used.
' For i=1 To NumberOfColumns
' For j=1 To NumberOfRows
' ss.Value(j,i)=x(j,i)
' Next j
' Next i
'
' Create a new analysis object of type line plot; pass
' as input data the contents of spreadsheet ss.
      Set newanalysis = Analysis (sc2dLinePlots,ss)
      newanalysis.Dialog.GraphType = scLineMultiplePlot
' Select all variables in the new spreadsheet.
      newanalysis.Dialog.Variables="*"
' Create the graph, and assign it to the previously
' declared object g. Note that all results from analyses
' in STATISTICA are returned as collections, and by default
' all results objects are invisible.
      Set g=newanalysis.Dialog.Graphs.Item(1)
' Now let us "print" both results to the report.
      r.SelectionObject=ss
      r.SelectionObject=g
' Finally, move the new objects (spreadsheet ss,
' graph g, and report r) to the workbook.
      wb.InsertObject(ss,wb.Root,)
      wb.InsertObject(g,wb.Root,)
      wb.InsertObject(r,wb.Root,)
' Make the final results workbook visible.
      wb.Visible=True
End Sub

How Can I Change the Font (or Other Aspects) of Numbers in Spreadsheets?

The functions in STATISTICA Visual Basic are organized in an intuitive hierarchical object model. The example program shown below illustrates the hierarchical nature of the objects, and the available respective methods and properties. Note that in order to review all available objects, methods, and properties, as well as constants that are recognized, you can always display the Object Browser.

The Object Browser can be displayed by clicking the Object Browser toolbar button (on the Macro toolbar), or by selecting Object Browser from the View menu.

Shown below is a simple example program that will change the font of the first column of the currently active input data spreadsheet to italics and bold.

Sub Main
' Find the currently active input spreadsheet, and
' assign it to variable (object) InSpr; note
' that ActiveSpreadsheet is a property of the
' current default (STATISTICA) Application; if no
' input Spreadsheet is currently open, then an
' error message will be issued.
      Dim InSpr As Spreadsheet
      Set InSpr=Application.ActiveSpreadsheet
' Select all numbers in the first column of the
' spreadsheet; note that the CellsRange property
' returns an object of type Range; here is the
' complete syntax (see also the Object Browser):
' Property CellsRange(
' FirstRow As Long, FirstColumn As Long,
' LastRow As Long, LastColumn As Long)
' As Range
' Note also that the underscore _ at the end of
' a line, after a blank, means that the next line
' is interpreted as a continuation of the respective
' command.
      Dim Cells As Range
      Set Cells=InSpr.CellsRange( _
         1, 1, _
         InSpr.NumberOfCases, _
         1)
' Cells is a Range object; one of the properties
' of the Range object is the Font; now set the font;
' the font is accessible as a Font object.
      Dim CellFont As Font
      Set CellFont=Cells.Font
' Italic and Bold are properties of the Font.
      CellFont.Italic=True
      CellFont.Bold=True

End Sub

How Can I Modify the Appearance of Graphs (e.g., Axis Labels) from within SVB?

The customization of graphs proceeds in much the same way as the customization of spreadsheets. After a graph object is created, various properties and methods are available to customize practically all aspects of the display. Here is an example of how to customize the font of the x-axis labels in a histogram:

Sub Main
' Create an analysis object; create a histogram from
' a variable in datafile Exp.sta (this example
' datafile may be located in a different directory
' on you installation).
   Dim a As Analysis
   Set a = Analysis (sc2dHistograms, _
        "j:\STATISTICA\Examples\DataSets\Exp.sta")
   a.Dialog.Variables = "5"
' Retrieve the first graph object from the collection.
' Note that all results spreadsheets and graphs
' are created in STATISTICA as collections of
' objects.
   Dim g as Graph
   Set g = a.Dialog.Graphs(1)
' Make the graph visible.
   g.Visible=True
' The Content property returns a "polymorphic"
' object, i.e., an object depending on the graph
' type that was created.
   Dim l As Object
   Set l = g.Content
' Next we want to "get to" the axes of the plot.
' Xaxis is a property of graph Content.Axes:
   Dim x As Axis2D
   Set x = l.Axes.Xaxis
' To modify the font of the x-axis labels, retrieve
' the Font property (object) of the x-axis.
   Dim xf As GraphicsFont2
   Set xf=x.Font
' Change the size of the font.
   xf.Size=20
' To change the Font itself, retrieve the FontFace
' property (object) from the GraphicsFont2 object.
   Dim xff As FontFace
   Set xff=xf.Face
' Finally, set the font to bold.
   xff.Bold=True
End Sub

How Can Other Aspects of Graphs Be Modified?

Here is a more complex example program that will customize various aspect of a graph:

' This program illustrates how create and customize
' different aspects of STATISTICA Graphs.
'
Sub Main
        Dim a As Analysis
' Create the 2D Line Plot analysis object; you
' may have to edit the path name for the input data
' file (spreadsheet), to match the installation of
' STATISTICA on your computer.
        Set a = Analysis (sc2dLinePlots, _
        "j:\STATISTICA\Examples\DataSets\Exp.sta")
        a.Dialog.GraphType = scLineMultiplePlot
        a.Dialog.Variables = "6 7 8"

'Retrieve the first graph object from the collection.
        Dim g As Graph
        Set g = a.Dialog.Graphs(1)

        Dim bFirstLevel, bSecondLevel, _
        bThirdLevel, bFourthLevel _
        As Boolean
        bFirstLevel = True
        bSecondLevel = True
        bThirdLevel = True
        bFourthLevel = True

' Customize titles, background.
        If bFirstLevel Then
          g.Titles.Item(1) = "New (better?) title"
          g.GraphWindow.Background.Color = _
           RGB (255,255,0)
        End If

' Get graph content.
        Dim l As Layout2D
        Set l = g.Content

' Customize plots: axis title and set line set to
' solid.
        If bSecondLevel Then
                'set y axis manual scale
                Dim y As Axis2D
                Set y = l.Axes.YAxis
                y.setManualRange(0,20)
                y.RangeMode = scgManualRange
                y.StepSize = 5
                y.StepMode = scgManualStep

' Set x axis title and turn off gridlines.
                Dim x As Axis2D
                Set x = l.Axes.XAxis
                x.Title = "Sequential cases"
                x.DisplayMajorGridLine = False

' Customize gridlines on y axis
                y.MajorGridLine.ForegroundColor = RGB(0,0,0)
                y.MajorGridLine.Type = scgSolid

        End If

        Dim pp As Plots2D
        Set pp = l.Plots

        If bThirdLevel Then
' Plot customizations

' Line patterns
                pp.Item(1).Line.Type = scgSolid
                pp.Item(2).Line.Type = scgSolid
                pp.Item(3).Line.Type = scgSolid

' Make third plot stand out from the rest.
                pp.Item(3).Marker.Size = 6
                pp.Item(3).Line.Weight = .75
        End If

        If bFourthLevel Then
' Changing plot variable values; we will set values <= 0
' to mean of previous and next value.
                Dim v As Variable
                Set v = pp.Item(3).Variable(2)

                Dim vind As Integer
                For vind = 2 To v.ValuesCount() - 1
                        If v.Value(vind) <= 0 Then
                                v.Value(vind) = (v.Value(vind-1) + _
                                  v.Value(vind+1))/2
                        End If
                Next vind
        End If

        g.Visible = True
End Sub

Can I Use SVB to Develop "Extensions" of STATISTICA and My Own New "Modules?"

This is one of the many useful applications for STATISTICA Visual Basic programs. By recording routine analyses, you can quickly generate all the necessary program code to perform particular analyses. By combining the code from different programs, and by customizing perhaps some of the user interface, a completely new module can be created that will perform custom analyses. Shown below is an example program that will combine multiple analyses.

' This program will compute tests comparing the
' central tendency measures in multiple groups.
' The Basic Statistics Breakdowns options will
' be used to compute the ANOVA; the Nonparametric
' Statistics Kruskal-Wallis and Median tests will
' be computed as nonparametrics alternatives to
' ANOVA.
'
' The following variables are declared as public
' symbols, i.e., they will be "visible" to
' all routines throughout this program.
Public GroupingVariable As Integer
Public DependentVariableList() As Integer
Public ndep As Integer
Public NVars As Long
Public ResultsWorkbook As Workbook
Public Folder As WorkbookItem
Public InputSpreadsheet as Spreadsheet
Dim newanalysis As Analysis
Dim ResultsSpreadsheet As Object
' The main program will ask for variable selections
' and then perform the necessary computations by calling
' two subroutines.
Sub Main
  Set InputSpreadsheet = ActiveDataSet
' Determine the number of variables in the input datafile
      NVars = InputSpreadsheet.NumberOfVariables
' Set up an array to hold the dependent variable list
      ReDim DependentVariableList(1 To NVars)
      Dim i As Integer, ret As Integer, nindep As Integer
' Bring up the STATISTICA variable selection dialog
      ret = SelectVariables2 (InputSpreadsheet, _
             "Select dependent variables, and grouping variable", _
            1, NVars, DependentVariableList, ndep, _
             "Dependent variables:", _
            1, 1, GroupingVariable, nindep, _
             "Independent (grouping) variable: ")
      if ret=0 then GoTo Finish
' Make new workbook
    Set ResultsWorkbook = Workbooks.New
    ResultsWorkbook.Visible = True
' Call the subroutine to compute the ANOVA tables
      ANOVATable
' Call the subroutine to compute the Kruskal-Wallis
' and Median tests
      KruskalWallisAndMedianTests
Finish:
End Sub

Sub ANOVATable
      Set newanalysis = Analysis (scBasicStatistics, InputSpreadsheet)
      newanalysis.Dialog.Statistics = scBasBreakdowns
      newanalysis.Run
' NOTE: The Array function is a standard Visual Basic
' function that combines the (two in this case) arrays of integers
' into a Variant that is an array of those arrays.
      newanalysis.Dialog.Variables = _
            Array(DependentVariableList,GroupingVariable)
      newanalysis.Dialog.Codes = "*"
      newanalysis.Run
' Compute the ANOVA results spreadsheet
      Set ResultsSpreadsheet=newanalysis.Dialog.AnalysisOfVariance
' Set up a folder in the workbook, and call it "ANOVA Results"
      Set Folder=ResultsWorkbook.InsertFolder( _
            ResultsWorkbook.Root, scWorkbookLastChild)don'
      Folder.Name="ANOVA Results"
' Move the results spreadsheet into the workbook; remember
' that all results spreadsheets returned from analysis objects
' in STATISTICA are collections of objects (spreadsheets);
' thus we need to explicitly reference Item(1) in the collection.
      ResultsWorkbook.InsertObject( _
            ResultsSpreadsheet.Item(1), Folder, scWorkbookLastChild)
End Sub

' This subroutine uses the Nonparametric Statistics module
' to compute the Kruskal-Wallis and Median tests; the results
' will be moved into the workbook set up in the Main program.
Sub KruskalWallisAndMedianTests
      Dim i As Integer
      Set newanalysis = Analysis (scNonparametrics, InputSpreadsheet)
      newanalysis.Dialog.NonparametricStatistics = _
            scNonComparingMultipleIndependentSamples
      newanalysis.Run
' NOTE: The Array function is a standard Visual Basic
' function that turns the two arrays of integers into
' arrays of type Variant
      newanalysis.Dialog.Variables = _
            Array(DependentVariableList,GroupingVariable)
      newanalysis.Dialog.Codes = "1-2"
      Set ResultsSpreadsheet=newanalysis.Dialog.Summary
      Set Folder=ResultsWorkbook.InsertFolder( _
            ResultsWorkbook.Root, scWorkbookLastChild)
' Set up a folder in the workbook, and call it
' "Nonparametric tests"
      Folder.Name="Nonparametric tests"
' Move the results spreadsheet into the workbook; remember
' that all results spreadsheets returned from analysis objects
' in STATISTICA are collections of objects (spreadsheets);
' the .Count property will retrieve the number of objects
' (spreadsheets) in the collection.
      For i =1 To ResultsSpreadsheet.Count
            ResultsWorkbook.InsertObject( _
              ResultsSpreadsheet.Item(i), Folder, scWorkbookLastChild)
      Next i
End Sub

How Can I Attach a Macro Program to a Toolbar Button (Keyboard Command, or Menu Option)?

One common application of STATISTICA Visual Basic macro programs is to "enhance" the STATISTICA functionality by creating toolbar buttons or keyboard commands (e.g., CTRL+key sequences) that allow you to quickly perform a series of operations or routine analyses. Shown below is a simple program that will sort a spreadsheet in a workbook, by the (first) selected column.

' This program will sort the spreadsheet data by
' the currently selected column (the first column
' in a range of selected columns). The program
' assumes that the spreadsheet is inside the
' currently active workbook.

Sub Main
' The following line will cause the program to
' resume at label ErrOut, if any error occurs (e.g.,
' if a workbook or spreadsheet can't be found).
      On Error GoTo ErrOut
      Dim ss As Spreadsheet
      Dim wb As Workbook
      Dim r As Range
      Dim ifault As Integer
      ifault=1
      On Error GoTo ErrOut
      Set wb=ActiveWorkbook
      Set ss=wb.ActiveItem.Object
      ifault=2
      Set r=ss.ActiveCell
      ifault=0
      ss.SortData(r.Column)
      Exit Sub
ErrOut:
      If ifault=1 Then
        MsgBox "Nothing to sort; the program assumes that you" + _
         "have a Spreadsheet with numbers highlighted in a Workbook."
      ElseIf ifault=2 Then
        MsgBox "No column is currently highlighted; nothing to sort."
      Else
        MsgBox "Cannot sort data."
      End If
End Sub

Running SVB Programs from Other Applications

Can I Execute an SVB Program from within Other Visual Basic Compatible Applications?

Yes; in general, because of the industry standard compatibility of STATISTICA Visual Basic, you can execute STATISTICA Visual Basic programs from any other Visual Basic compatible environment (e.g., Microsoft Excel, Microsoft Word, or a stand alone Visual Basic language; in practice, you would typically call STATISTICA functions from VB in another application). However, there are a few considerations and limitations that you need to be aware of:

STATISTICA libraries must be properly licensed and installed. When you run a STATISTICA Visual Basic program or attempt to call STATISTICA functions from any other application, all calls to the STATISTICA specific functions (as opposed to the generic functions of Microsoft Visual Basic) will be executed only if the respective STATISTICA libraries are present on the computer where the execution takes place - that is, the user of the program must be a licensed user of the respective STATISTICA libraries of procedures. Note that this large library of STATISTICA functions (more than 10,000 procedures) is transparently accessible not only to Visual Basic (either the one that is built in, or a different one), but also to calls from any other compatible programming language or environment, such as C/C++, Java, or Delphi.

The proper STATISTICA libraries must be loaded. In order to access the thousands of library functions available in STATISTICA, the respective object reference libraries must be loaded. For example, in Microsoft Excel, use option Tools - References and then select the STATISTICA Object library, and any other libraries that you would want to access.

The STATISTICA Application object must be explicitly created. When you run STATISTICA Visual Basic programs from with the STATISTICA program editor, then a few shortcuts are available. In particular, the STATISTICA program editor assumes that the current application is STATISTICA, so it doesn't have to be initialized. However, when running STATISTICA from within another application (e.g., from within the Microsoft Excel Visual Basic editor), you have to explicitly declare the STATISTICA Application object.

Some other limitations and differences between SVB and Visual Basic in other applications. While the objects of the STATISTICA libraries are fully exposed and accessible to all compatible Visual Basic programming environments in other applications, there are a few functions that are only available in SVB, i.e., when the Visual Basic program is run from within STATISTICA. (Likewise, there are some functions in other applications that are not accessible in the SVB environment.) Specifically, all user interface functions, such as user-defined dialogs or functions for retrieving variable lists or value lists (via dialogs from the user) are closely tied to the STATISTICA application itself. Therefore, when designing a Visual Basic program to run from a "foreign" application (e.g., from within Microsoft Excel), it is best to design the user interface (dialogs) using the tools available in that application; those tools are usually designed such that they allow you to program interfaces with an overall look and feel that makes them compatible with all other interfaces (dialogs) used in the respective application.

How Can I Run a STATISTICA Analysis from Microsoft Excel?

First, if you want to run STATISTICA from within the Visual Basic environment in Microsoft Excel, be aware of the issues (and some limitations).

To illustrate, we will create an example program that can be run from Visual Basic within Excel. After starting Excel, create a new Worksheet. Then select Macro - Visual Basic Editor from the Tools menu. From the Visual Basic Tools menu, select References.

The References dialog allows you to select the libraries (objects) that you would like to be visible inside the Visual Basic program. To make STATISTICA visible, select the STATISTICA Object Library, and the STATISTICA Basic Statistics Library (for the current version of STATISTICA); then click the OK button.



Now type or paste the following program into the program editor.

Sub ExcelTest()
' Run the STATISTICA application; create the STATISTICA
' Application object and assign it to variable (object) x.
    Set x = CreateObject("Statistica.Application")
' Create a STATISTICA Basic Statistics object (i.e., run the
' Basic Statistics module; start it with datafile exp
' (note: the actual location of that datafile may be
' different on your installation).
    Set a = x.Analysis(scBasicStatistics, _
       "j:\STATISTICA\Examples\Datasets\exp.sta")
' the following 7 lines of code will produce a summary results
' spreadsheet from the STATISTICA Basic Statistics module.
    a.Dialog.Statistics = scBasDescriptives
    a.Run
    a.Dialog.Variables = "5-8"
    Set out = a.Dialog.Summary
' Select all rows and columns in the STATISTICA results spreadsheet.
    out.Item(1).SelectAll
' Copy the highlight selection (all rows and columns in the
' Summary results spreadsheet.
    out.Item(1).Copy

' Set the cursor to cell A1 in the currently active Excel Spreadsheet.
    Range("A1").Select
' Paste in the summary statistics.
    ActiveSheet.PasteSpecial Format:="Biff4"
End Sub

Handling Large Computational Problems, Matrices

What Is the Capacity of SVB, and Can It Handle Large Computational Problems?

STATISTICA Visual Basic is a powerful programming language which combines the general Visual Basic Programming Environment [with facilities and extensions for designing user interfaces (dialogs) and file handling], with the STATISTICA libraries with thousands of functions that provide access to practically all functionality of STATISTICA. It is well suited to handle large computational problems.

SVB supports local data arrays with up to 8 dimensions, and there is no limit to the size of the arrays (all memory available in your system can be used, including virtual memory, e.g., correlation matrices 1,000 x 1,000 and larger can be computed [with a single function call] on most systems), so custom procedures involving operations on large multidimensional matrices can be developed (a comprehensive selection of matrix operations are also supported). Matrices can be dynamically allocated or redimensioned in run time.

Performance of STATISTICA Visual Basic programs. While the obvious advantage of Visual Basic (compared to other languages) is its ease of use and being familiar to a very large number of computer users, the possible drawback of VB programs is that they do not perform as fast as applications developed in lower-level programming languages (such as C). However, that potential problem will not apply to STATISTICA Visual Basic applications, especially those that rely mostly on executing calls to STATISTICA analytic, graphics, and data management procedures. These procedures fully employ the STATISTICA technology and they will perform at a speed comparable to running the respective procedures in STATISTICA directly.

Does SVB Support Matrix Operations?

STATISTICA Visual Basic contains a large number of designated matrix and statistical functions, which make the SVB environment ideal for prototyping algorithms or for developing custom statistical procedures. The matrix and statistical functions are documented in detail in the section on the STATISTICA Matrix Function Library (see the Electronic Manual).

One major advantage of using the STATISTICA library of matrix functions, instead of writing these functions "by hand" in Visual Basic, is that the former will evaluate much faster. For example, when you want to invert large matrices, the MatrixInverse function will perform the actual matrix inversion using the highly optimized (compiled) algorithms of STATISTICA.

Include file: STB.svx. To provide convenient access to the matrix functions without requiring you to pass explicitly the dimensions of the arrays that are being passed, STATISTICA includes a file with function interfaces: STB.svx. You may want to open this file to review the functions and see how they provide simplified access to the actual matrix library. It is recommended that you routinely include that file at the beginning of your program when you intend to use functions from the STATISTICA libraries of matrix and statistical functions.

In order to insure the portability of all STATISTICA Visual Basic macros, you can specify an asterisk in front of the root file name for the standard include files. When STATISTICA detects the *, it will automatically search for the STB.svx file in standard places (e.g., the directory where the macro has been saved, the global macro directory, and the directory where the STATISTICA application is located). Thus it is not necessary to state the complete path for the STB.svx file when including this file in your STATISTICA Visual Basic programs via the $Include statement.

Reviewing the matrix functions in the function browser. You can review the available matrix functions either in the Electronic Manual or in the Function Browser, which also lists various other functions available in STATISTICA Visual Basic. The Function Browser is accessible via the SVB View menu or by clicking on the Function Browser toolbar button.

Example. The following example illustrates how to use the functions in the STATISTICA library of matrix functions, to perform some basic matrix operations: Namely, matrix inversion and matrix multiplication:

' The following line is very important!
' It contains the "interfaces" to the STATISTICA
' Matrix and Statistical Function libraries.
'
'$include: "*STB.svx"
' The next statement will cause all arrays to be
' declared by default as 1-referenced, i.e., the
' first element in an array will be element 1, not 0.
' Note that the matrix and statistical functions
' will work fine with 0-referenced arrays; however,
' it can be confusing to write programs with 0-
' referenced arrays, because many of the matrix
' functions expect arguments based on 1-referenced
' arrays.
Option Base 1
Sub Main
' Set up two 4 x 4 matrices.
  Dim a(4,4) As Double, ainv(4,4) As Double
  Dim i As Long, j As Long
' Fill the matrix with random numbers
  For i=1 To 4
   For j=1 To 4
    a(i,j)=Rnd(10)
   Next j
  Next i
' Display the original matrix.
  MatrixDisplay (a, "Original Matrix A")
' Invert the matrix.
  MatrixInverse(a,ainv)
' Display the inverted matrix.
  MatrixDisplay (ainv, "A, Inverse")
' Multiply a*a-inverse
  MatrixMultiply(a,ainv,a)
  MatrixDisplay(a,"A * A-inverse")
End Sub

How Can I Use the Data in a Spreadsheet with Matrix Functions? (How Do I Copy Data Efficiently from Spreadsheets to Matrices, and Back?)

STATISTICA Visual Basic contains several functions to quickly move columns (variables), rows (cases), or the entire data matrix from spreadsheets to dimensioned arrays, and back. The following example shows how you can use the .VData(variable), CData(case), and .Data properties of the spreadsheet object to retrieve particular columns (variables) or rows (cases) of data from the respective spreadsheet, or to copy the entire data matrix.

' This program will fill a dimensioned array
' x(100,10) with random numbers, and then
' transfer the contents of that array to
' a spreadsheet.
'
' To use any of the matrix functions, make sure to
' include the following line, to include the file
' with the the matrix function interfaces.
'$include: "*STB.svx"

Sub Main
      Dim i As Integer
        Dim j As Integer
' Create the new Spreadsheet; by default it will have
' 10 rows and 10 columns.
      Dim ss As New Spreadsheet
' The next statement will resize the new Spreadsheet to
' 100 cases and 10 variables.
      ss.SetSize(100,10)
' Dimension array x.
      ReDim x(1 To ss.NumberOfCases, _
              1 To ss.NumberOfVariables) As Double
' Fill array x with random numbers.
      For i = 1 To ss.NumberOfCases
       For j=1 To ss.NumberOfVariables
        x(i,j)=Rnd(1)
       Next j
      Next i
' Copy the contents of array x to the new spreadsheet.
      ss.Data=x
' Make the resulting spreadsheet visible.
      ss.Visible=True
' Dimension another array y.
      ReDim y(1 To ss.NumberOfCases, _
              1 To ss.NumberOfVariables) As Double
' With the next line, the entire contents of spreadsheet
' ss is transferred to the array y.
      y=ss.Data
' Alternatively, you could also have used the .Vdata(Variable)
' property, to copy the contents column-by-column, or the
' Cdata(Case) property, to copy the contents row by row.
'
' The following code will add first 10, and then 100 to
' each random number; so the final spreadsheet that will
' be displayed will contain numbers in the range from
' 110 to 111.
      ReDim yVector(1 To ss.NumberOfCases) As Double
      For i=1 To ss.NumberOfVariables
' Copy column i from the spreadsheet to the vector.
       yVector=ss.VData(i)
' Use matrix function MatrixElemAdd to add 10 to each
' element in yVector.
       MatrixElemAdd (yVector, 10, yVector)
' Copy the contents of the vector to column i of the
' spreadsheet.
       ss.VData(i)=yVector
      Next i

      ReDim yVector(1 To ss.NumberOfVariables)
      For i=1 To ss.NumberOfCases
' Copy row i from the spreadsheet to the vector.
       yVector=ss.CData(i)
' Use matrix function MatrixElemAdd to add 100 to each
' element in yVector.
       MatrixElemAdd (yVector, 100, yVector)
' Copy the contents of the vector to row i of the
' spreadsheet.
      ss.CData(i)=yVector
     Next i
End Sub

Creating and Managing Custom Dialogs in STATISTICA Visual Basic

Can I Create Custom Dialogs and Other Interactive User Input Controls in SVB?

The STATISTICA Visual Basic environment provides all tools to program complete custom user interfaces. A powerful User-Dialog Editor is included to design dialogs using simple operations like dragging buttons to the desired locations. Unlike in Microsoft Visual Basic, the user-defined dialogs will be stored along with the program code as data of type UserDialog. This method of creating dialogs allows you to create sophisticated user interfaces that can easily be edited in textual form; also, by defining the entire dialog as a variable, you can completely define dialogs inside subroutines, which can be freely moved around the program.

However, user-defined dialogs designed in the STATISTICA Visual Basic environment cannot be ported directly to Microsoft Visual Basic, which uses a form-based method of creating dialogs. This is not a serious limitation, though, but rather a design issue, in the sense that you should decide before embarking on the development of a complex program with extensive custom (user-defined) dialogs which environment you would prefer. For example, if you are already familiar with the Microsoft Visual Basic environment, or would like to augment an existing program that was developed in that environment, then there would be clear advantages in staying with that language. To reiterate, virtually all STATISTICA Visual Basic functions are accessible from the Visual Basic environments in other applications (such as Microsoft Visual Basic, Microsoft Excel, Microsoft Word, etc.).

The following example illustrates how to create a simple dialog and "service" the user choices on this dialog. Start by creating a new macro: Select New from the File menu, select the Macro tab, and create a new macro called SimpleDialog.

Creating the dialog. Next select Dialog Editor from the Tools menu or click the Dialog Editor toolbar button to display the UserDialog Editor.



Click the OK button on the left side of this dialog, and then click in the upper-right corner of the window; an OK button will be inserted in that location.



Note that you can further edit the size and location of the OK button by clicking on it and dragging it to the desired location, or resizing it. Repeat these steps for the Cancel button and for a user-defined button. The latter can be produced by clicking the blank button toolbar button on the lower-left of the toolbar on the UserDialog, and then clicking on the desired location in the dialog editor.



By default, the new button is labeled Pushbutton1; to change that, double-click on it to display the Edit PushButton Properties dialog. Then edit the fields as follows:



Note that the Caption for the new button is &My Button! When you click Close, the actual caption of the button will change to My Button!, i.e., with the M underlined. Thus, M is the keyboard accelerator that will "click" this button. The other important information in the Edit PushButton Properties dialog is the ID of the button, entered into the Field box. The ID for this button is MyButton; this ID will be referenced throughout the SVB program to service the button, i.e., to identify when the button was pushed, and to respond inside the program.

Now close the Edit PushButton Properties dialog, and close the UserDialog Editor dialog by clicking on the toolbar button in the UserDialog editor. The SVB program will now contain the following code.

Sub Main
      Begin Dialog UserDialog 400,203 ' %GRID:10,7,1,1
            OKButton 300,14,70,21
            CancelButton 300,42,70,21
            PushButton 30,14,90,21,"&My Button!",.MyButton
      End Dialog
      Dim dlg As UserDialog
      Dialog dlg
End Sub

Sub Main
      Begin Dialog UserDialog 400,203 ' %GRID:10,7,1,1
            OKButton 300,14,70,21
            CancelButton 300,42,70,21
            PushButton 30,14,90,21,"&My Button!",.MyButton
      End Dialog
      Dim dlg As UserDialog
    Dim ReturnId As Integer
' NOTE: here we added parenthesis around the argument
' (dlg) for the Dialog method; this allows us to
' retrieve the return code from that method.
    ReturnId = Dialog (dlg)
    Select Case ReturnId
      Case -1
        MsgBox "The OK button was pressed"
      Case 0 ' Cancel Button
        MsgBox "The CANCEL button was pressed"
      Case 1 ' The 'first' button on the Dialog,
        MsgBox "The MY BUTTON was pressed"
   End Select
End Sub

How Are the Different Controls in Custom Dialogs "Serviced?"

Here is a fairly elaborate example program to illustrate how to service the various elements commonly used in dialogs.

' This program demonstrate how one can service various
' controls in a complex dialog.
'
' The following arrays will be used to handle the text
' in the list box and combo box.
Dim ListArray(4) As String
Dim ComboArray(5) As String

' In this program, the Main routine calls a subroutine
' that displays the dialog; note that you can "string together"
' many such subroutines to construct complex programs.
Sub Main
    If DisplayDialog = False Then
       GoTo Finish
    End If
    Exit Sub
Finish:
End Sub

' This function brings up the dialog, and services the various
' controls in the dialog using the DialogFunc (dialog function)
' method. See also the general STATISTICA Visual Basic syntax
' help for additional details.
Function DisplayDialog As Boolean
  DisplayDialog=True
      Begin Dialog UserDialog 390,336,"Demonstating Dialog Controls", _
        .MyDialogFunction ' %GRID:10,7,1,1
            OKButton 300,14,70,21,.OkButton
            CancelButton 300,42,70,21,.CancelButton
            PushButton 30,14,160,21,"&Reset to defaults",.MyButton
            Text 30,49,90,14,"&Combo box:",.TextForMyComboBox
            ComboBox 130,49,160,70,ComboArray(),.MyComboBox
      Text 30,126,100,28,"&Text box (multiple lines):", _
  .TextForTextBox
            TextBox 130,126,160,35,.MyTextBox,1
            Text 30,175,90,14,"Value:",.TextForMyTextBox2
            TextBox 130,168,160,21,.MyTextBox2
            Text 30,196,60,14,"List box:",.TextForMyListBox
            DropListBox 130,196,160,91,ListArray(),.MyListBox
            CheckBox 30,231,130,14,"My Checkbox",.MyCheckBox
            GroupBox 30,252,180,63,"&Group Box",.MyGroupBox1
            OptionGroup .MyOptionButtons
                  OptionButton 40,273,150,14,"My Option Button &1"
                  OptionButton 40,294,150,14,"My Option Button &2"
      End Dialog
      Dim dlg As UserDialog
' The following routine will initialize various controls in the
' dialog (fill the combo box, list box, check buttons, etc.)
      InitializeUserDialogFields (dlg)
TryAgain:
' The following line will display the dialog.
    DisplayDialog=Dialog(dlg)
' If the user exited the dialog via OK, then DisplayDialog will
' be set to True; in that case, retrieve the chosen settings for
' the controls, and check for their correctness; if an error
' occurred, display the dialog again.
    If DisplayDialog=True Then
      If RetrieveUserDialogFields (dlg)=0 Then
        MsgBox "Error in the dialog specs; try again.", vbCritical
        GoTo TryAgain
      End If
    End If
End Function

' This is the (private) dialog function that services the UserDialog.
' The name of this function must match the name given to the Dialog
' (see the .MyDialogFunction above).
' Three parameters are passed to the dialog function. Refer to the
' general syntax help for additional details about each parameter.
Private Function MyDialogFunction(DlgItem$, Action%, SuppValue&) As Boolean

        Select Case Action%

        Case 1 ' Dialog box initialization
        Case 2 ' Value changing or button pressed
' Set the default return code for MyDialogFunction to True; this will
' mean that the dialog will not close; only on OK and Cancel set this
' value to False, i.e., close the dialog.
                MyDialogFunction = True

                Select Case DlgItem

                Case "MyButton"
' Reset all controls to their initial defaults
                 DlgValue "MyListBox", 0
                 DlgText "MyComboBox", ComboArray(1)
                 DlgText "MyTextBox", _
                        "Initial text for multiple line edit field"
                 DlgText "MyTextBox2",".5"
                 DlgValue "MyCheckBox", True
                 DlgValue "MyOptionButtons", 1
                 MyDialogFunction=True

                Case "MyListBox"
                  MsgBox "New combo box selection:" _
                     + ListArray(SuppValue)

                Case "OkButton"
                  MyDialogFunction=False

                Case "CancelButton"
                  MsgBox "The CANCEL button was pressed"
                  MyDialogFunction=False

                End Select

        End Select
End Function

' This subroutine initializes the list box, combo box, text
' fields, etc.
' Note that the entries in list boxes and combo boxes are
' zero-referenced, i.e., the first item in the list is
' referenced as element 0.
Sub InitializeUserDialogFields (dlg)
    ListArray(0)="List entry 0"
    ListArray(1)="List entry 1"
    ListArray(2)="List entry 2"
    ListArray(3)="List entry 3"
    ListArray(4)="List entry 4"
    dlg.MyListBox=0

    ComboArray(0)="Combobox entry 0"
    ComboArray(1)="Combobox entry 1"
    ComboArray(2)="Combobox entry 2"
    ComboArray(3)="Combobox entry 3"
    ComboArray(4)="Combobox entry 4"
    ComboArray(5)="Combobox entry 5"
    dlg.MyComboBox=ComboArray(1)

    dlg.MyTextBox="Initial text for multiple line edit field"
    dlg.MyTextBox2=".5"

      dlg.MyCheckBox=True

' Note that the option buttons in a group of option buttons are
' zero-referenced, i.e., the first button in the group is referenced
' as element 0; thus here we set the second option button
      dlg.MyOptionButtons=1

End Sub

Function RetrieveUserDialogFields (dlg) As Boolean
On Error GoTo InvalidInput
Dim xval As Double
            RetrieveUserDialogFields=True
        MsgBox "My combo box is set to: " + dlg.MyComboBox
        MsgBox "My multi-line text box is set to: " + dlg.MyTextBox
        xval=CDbl(dlg.MyTextBox2)
        MsgBox "My value was set to: " + Str(xval)
        MsgBox "My (0-referenced) element chosen in My Listbox is: " _
           + Str(dlg.MyListBox)
        MsgBox "My check box is set to: " + Str(dlg.MyCheckBox)
        MsgBox "My options buttons are set to (0-referenced): " _
           + Str(dlg.MyOptionButtons)
        Exit Function
InvalidInput:
        RetrieveUserDialogFields=False
End Function

Customizing the Appearance and "Behavior" of STATISTICA

What Are Application Events and How Can They Be Controlled from SVB?

An event is an action that is typically performed by a user, such as clicking a mouse button, pressing a key, changing data, or opening a spreadsheet or workbook. In STATISTICA certain events are visible to the outside world, i.e., accessible to STATISTICA Visual Basic, and they can be used to customize its behavior. Using programmable events you can tailor the program's behavior to the users' needs. Examples of events applications might include: