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 Devel