Equilla Vectors

The following article offers an introduction to vectors in Equilla. Vectors are deprecated in Tradesignal and are superseded by arrays.

Vectors in Equilla are the same kind of construction as those called arrays in other programming languages. They are data fields designed to contain large quantities of data. Each piece of data can be retrieved via the unique position (index) in the vector. With the help of additional functions delivered with Tradesignal, a wide range of applications can be covered with vectors.

What is a Vector?

In the basic Equilla article, variables were introduced as being "containers with an identification number". Via the name of the variable, existing contents can be called up or new contents can be assigned to the variable.

While you can only save one value per variable, vectors are a lot more flexible - an infinite number of values can be put into a vector. To expand the container comparison: vectors are containers that include an unlimited number of storage spaces, like boxes in a container. Each box can be retrieved by its index (unique position in the vector).

Vector Declaration

A vector is treated similar to a variable. In the variable declaration, the vector has to be defined and named. The keyword Vector has to be added in brackets.
Variables:
    myVeryFirstVector( Vector );



When you forget the keyword Vector, a variable of this name is available but without the vector properties.

As with variables, you can create a global vector. This way it is possible to call up the vector from several scripts. Global vectors are defined as follows:
Variables:
    myVeryFirstGlobalVector( GlobalVector );

Read and Write Data

Vectors offer the two basic features ReadVector() and WriteVector(). Both functions need the name and the unique index to address the right storage place. When writing a vector, you also need to pass the content to be written.

Vectors can include all data types available in Equilla.

Write Data

Data is written into the vector with the WriteVector ( ) function. As parameters, the vector name and the value to be written have to be passed. The size of the vector is automatically adapted to the highest used index. Therefore, the possible length of the future vector is irrelevant for the calculation.

Variables:
    myVeryFirstVector( Vector );


If isLastBar Then
    Begin
        //The string 'Hello' is written at the position with ID 0
        WriteVector( myVeryFirstVector, 0, "Hello");
        //The string 'Rene' is written at the position with ID 1
        WriteVector( myVeryFirstVector, 1, " Rene");
    End;

Output Catenated Data

If you want to output the complete content of a vector in a quick and easy way, you can use the function FormatVector. It is part of the delivered functions and catenates all elements of a vector to one string. This can then be output with the print command. The function is especially useful if you want to keep track of the values while programming.

We expand the source code given above:
Variables:
    myVeryFirstVector( Vector );


If isLastBar Then
    Begin
        //The string 'Hello' is written at the position with ID 0
        WriteVector( myVeryFirstVector, 0, "Hello");
        //The string 'Rene' is written at the position with ID 1
        WriteVector( myVeryFirstVector, 1, " Rene");
        Print( FormatVector( myVeryFirstVector ));
    End;


In the output window, the line "Hello Rene" appears.

Read Data

Vector data can be read with the ReadVector ( ) function. As parameters, the vector name and the index have to be passed.

Make sure that the program does not try to read from non-existing positions. When this happens, Tradesignal aborts the execution with an error message in the chart legend.
Variables:
    myVeryFirstVector( Vector ), OutputText;


If isLastBar Then
    Begin
        //The string 'Hello' is written at the position with ID 0
        WriteVector( myVeryFirstVector, 0, "Hello");
        //The string 'Rene' is written at the position with ID 1
        WriteVector( myVeryFirstVector, 1, " Rene");
        OutputText = ReadVector( myVeryFirstVector, 0 );
        OutputText = OutputText + ReadVector( myVeryFirstVector, 1 );
        Print( OutputText );
    End;


In the output window, the line "Hello Rene" appears.

Reading the Vector Properties

Some useful functions are available for reading the vector properties. For example, by using the VectorLength( ) function, you receive the vector size, i.e. the number of included elements.

With other functions you gain information about the highest or lowest value in a vector (and their unique IDs in the vector). Please note that a vector indexing always starts at zero. The first index is zero, the second is one and so on.
  • VectorLength( VectorName ) - Offers the number of elements.
  • HighestVector( VectorName ) - Offers the highest value in the vector as result.
  • IndexOfHighestVector( VectorName ) - Offers the unique ID of the highest value in the vector.
  • LowestVector( VectorName ) - Offers the lowest value in the vector as result.
  • IndexOfLowestVector( VectorName ) - Offers the unique ID of the lowest value in the vector.
With the following little routine you can test the functions listed above. When you change the content of the FillVector( ) function, different values will be output.
Variables:
    myVeryFirstVector ( Vector ), OutputText;


If isLastBar Then
    Begin
        //Fill the vector with values
        FillVector( myVeryFirstVector , 2,4,6,8,10,2,3,5 );
        //Output vector contents
        Print( "Vector Contents: " + FormatVector( myVeryFirstVector ));
        //Read the number of elements
        OutputText = "Number of Elements: " + VectorLength( myVeryFirstVector );
        //Output in the output window
        Print( OutputText);
        //Retrieve the highest value
        OutputText = "Highest Value: " + HighestVector( myVeryFirstVector );
        //Retrieve unique ID / position of highest value
        OutputText = OutputText + " - at position No.: " +
IndexOfHighestVector( myVeryFirstVector );
        //Output in the output window
        Print( OutputText);
        //Retrieve the lowest value
        OutputText = "Lowest Value: " + LowestVector( myVeryFirstVector );
        //Retrieve unique ID / position of lowest value
        OutputText = OutputText + " - at position No.: " +
IndexOfLowestVector( myVeryFirstVector );
        //Output in the output window
        Print( OutputText);
    End;


In the output window, the following appears:
Vector contents: '2', '4', '6', '8', '10', '2', '3', '5'

Number of elements: 8

Highest value: 10 - at position No.: 4

Lowest value: 2 - at position No.: 0

Fill Vectors with Content and Delete Content

To write a defined number of values into a vector, use the function FillVector( VectorName, Value1, Value2, ..). This function was already used in the example above.

To delete the content of a vector, use the function ClearVector(VectorName). This function deletes all elements in a vector and resets its size to zero. Use this function when you reuse vectors in your program, except in cases when you want to use old vector data.

Let us expand the source code of the example above by adding the delete function:
Variables:
    myVeryFirstVector ( Vector ), OutputText;


If isLastBar Then
    Begin
        //Fill the vector with values
        FillVector( myVeryFirstVector , 2,4,6,8,10,2,3,5 );
        //Output vector contents
        Print( "Vector Contents: " + FormatVector( myVeryFirstVector ));
        //Read the number of elements
        OutputText = "Number of Elements: " + VectorLength( myVeryFirstVector );
        //Output in the output window
        Print( OutputText);
        //Retrieve the highest value
        OutputText = "Highest Value: " + HighestVector( myVeryFirstVector );
        //Retrieve unique ID / position of highest value
        OutputText = OutputText + " - at position No.: " +
IndexOfHighestVector( myVeryFirstVector );
        //Output in the output window
        Print( OutputText);
        //Retrieve the lowest value
        OutputText = "Lowest Value: " + LowestVector( myVeryFirstVector );
        //Retrieve unique ID / position of lowest value
        OutputText = OutputText + " - at position No.: " +
IndexOfLowestVector( myVeryFirstVector );
        //Output in the output window
        Print( OutputText);

        Print( "Vector deleted!" );
        ClearVector( myVeryFirstVector );

        Print( "Vector contents: " + FormatVector( myVeryFirstVector ));

        //Repeat all analysis:
        OutputText = "Number of Elements: " + VectorLength( myVeryFirstVector );
        //Output in the output window
        Print( OutputText);
        //Retrieve the highest value
        OutputText = "Highest Value: " + HighestVector( myVeryFirstVector );
        //Retrieve unique ID / position of highest value
        OutputText = OutputText + " - at position No.: " +
IndexOfHighestVector( myVeryFirstVector );
        //Output in the output window
        Print( OutputText);
        //Retrieve the lowest value
        OutputText = "Lowest Value: " + LowestVector( myVeryFirstVector );
        //Retrieve unique ID / position of lowest value
        OutputText = OutputText + " - at position No.: " +
IndexOfLowestVector( myVeryFirstVector );
        //Output in the output window
    End;


In the output window, the following appears:
Vector contents: '2', '4', '6', '8', '10', '2', '3', '5'

Number of elements: 8

Highest value: 10 - at position No.: 4

Highest value: 2 - at position No.: 0

Vector deleted!

Vector contents:

Number of elements: 0

Highest value: 0 - at position No.: -1

Highest value: 0 - at position No.: -1


As you can see, the vector is empty after the deletion. Due to this, some functions output an error with the result "-1".

Finding and Sorting Data

Some useful functions are available to navigate in a vector.

To find data in a vector, use the function SearchVector( VectorName, SearchedValue).

To sort data, use the function SortVector( VectorName, SortAscending ).

To demonstrate the sorting, we modify the indicator of the deletion example. We simply exchange the ClearVector( VectorName ) function with the sorting function SortVector( VectorName, SortAscending ). You can change the sorting direction with true/false. Enter true for ascending and false for descending order.

Variables:
    myVeryFirstVector ( Vector ), OutputText;


If isLastBar Then
    Begin
        //Fill the vector with values
        FillVector( myVeryFirstVector , 2,4,6,8,10,2,3,5 );
        //Output vector contents
        Print( "Vector Contents: " + FormatVector( myVeryFirstVector ));
        //Read the number of elements
        OutputText = "Number of Elements: " + VectorLength( myVeryFirstVector );
        //Output in the output window
        Print( OutputText);
        //Retrieve the highest value
        OutputText = "Highest Value: " + HighestVector( myVeryFirstVector );
        //Retrieve unique ID / position of highest value
        OutputText = OutputText + " - at position No.: " +
IndexOfHighestVector( myVeryFirstVector );
        //Output in the output window
        Print( OutputText);
        //Retrieve the lowest value
        OutputText = "Lowest Value: " + LowestVector( myVeryFirstVector );
        //Retrieve unique ID / position of lowest value
        OutputText = OutputText + " - at position No.: " +
IndexOfLowestVector( myVeryFirstVector );
        //Output in the output window
        Print( OutputText);

        SortVector( myVeryFirstVector , true );

        //Repeat the analysis:
        Print( "Vector contents: " + FormatVector( myVeryFirstVector ));
        //Fill the vector with values
        FillVector( myVeryFirstVector , 2,4,6,8,10,2,3,5 );
        //Output vector contents
        Print( "Vector Contents: " + FormatVector( myVeryFirstVector ));
        //Read the number of elements
        OutputText = "Number of Elements: " + VectorLength( myVeryFirstVector );
        //Output in the output window
        Print( OutputText);
        //Retrieve the highest value
        OutputText = "Highest Value: " + HighestVector( myVeryFirstVector );
        //Retrieve unique ID / position of highest value
        OutputText = OutputText + " - at position No.: " +
IndexOfHighestVector( myVeryFirstVector );
        //Output in the output window
        Print( OutputText);
        //Retrieve the lowest value
        OutputText = "Lowest Value: " + LowestVector( myVeryFirstVector );
        //Retrieve unique ID / position of lowest value
        OutputText = OutputText + " - at position No.: " +
IndexOfLowestVector( myVeryFirstVector );
        //Output in the output window
        Print( OutputText);
    End;


In the output window, the following appears:

Vector contents: '2', '4', '6', '8', '10', '2', '3', '5'

Number of elements: 8

Highest value: 10 - at position No.: 4

Lowest value: 2 - at position No.: 0

Vector contents: '2', '2', '3', '4', '5', '6', '8', '10'

Number of elements: 8

Highest value: 10 - at position No.: 7

Lowest value: 2 - at position No.: 0


Here is an example for the search function. The wanted value is "10".
Variables:
    myVeryFirstVector ( Vector )

If isLastBar Then
    Begin
        //Fill the vector with values
        FillVector( myVeryFirstVector , 2,4,6,8,10,2,3,5 );

        //Search the vector for a value
        Print( "The wanted value 10 is at position No.: " +
SearchVector( myVeryFirstVector, 10 ));
     End;


In the output window appears:
Vector content: '2', '4', '6', '8', '10', '2', '3', '5'

The wanted value 10 is at position No.: 4

Overview of all Vector Functions

In the following you can find a list of all vector functions in Equilla. More information and examples for each vector you can find in the Tradesignal help under Equilla Formula Language, menu entry Vectors.

To open the Tradesignal help, click on the button with the yellow question mark in the toolbox or in the header bar. In the Equilla editor, you can also right-click on an Equilla function and select Lookup Equilla Function.

VectorFunktion
AppendVector()Appends the contects of one vector onto the end of another vector.
AverageVector()Returns the average value (mean) of the elements in a vector.
AvgDeviationVector()Returns the average deviation of the elements in a vector.
BinarySearchVector()Returns the position of an element with a specific value in a vector using a binary search.
ClearVector()Clears the contents of a vector and sets its size to zero (0).
CompareVector()Compares the elements in one vector to those in another vector.
CopyVector()Copies some or all of the elements from one vector to another.
CreateSortedIndexVector()Creates a sorted index to a vector. The vector containing the actual data will remain unchanged.
FillVector()Fills a vector with the specified elements.
GlobalVector()Returns a newly created vector that can be shared between scripts.
HarmonicMeanVector()Returns the harmonic mean of the values in a vector.
HighestVector()Returns the highest element in a vector.
IndexOfHighestVector()Returns the zero based index of the first occurrence of the highest element in a vector.
IndexOfLowestVector()Returns the zero based index of the first occurrence of the lowest element in a vector.
KurtosisVector()Returns the Kurtosis value of the elements in a vector.
LowestVector()Returns the lowest element in a vector.
MedianVector()Returns the median of the elements in a vector.
ReadVector()Returns the value stored at a specific index within a vector.
ReadVectorIndirect()Returns the value stored at a certain index within the data vector.
SearchVector()Returns the position of an element with a specific value in a vector.
SetMaxIndexVector()Sets the largest index value for this vector.
SetValRangeVector()Sets a range of elements in a vector to a specified value.
SkewnessVector()Returns the skewness (the degree of asymmetry) of the elements in a vector.
SortVector()Sorts the contents of the vector.
StdDeviationVector()Returns the standard deviation of the elements in a vector.
StdErrorVector()Returns the standard error of the elements in a vector.
SummationRecVector()Returns the sum of reciprocals of each element in a vector.
SummationSqrVector()Returns the sum of squares of each element in a vector.
SummationVector()Returns the sum of all, or a range of elements in the vector.
VarianceVector()Returns the variance of the elements in a vector.
Vector()Returns a newly created vector.
VectorLength()Returns the number of elements stored in a vector..
WriteVector()Writes a value to a specific index within a vector.
WriteVectorIndirect()Writes a value to a specific index within a vector. The index into the data vector will be looked up via the index vector.