Equilla Functions

What is a Function?

In programming languages, functions are subordinate portions of the code in which regularly used calculations and subroutines are sourced out. For example, instead of writing the calculation of standard deviation again and again, the calculation is put into a function. By calling up the function by its name - and passing the relevant parameter(s) for calculation - the user receives the return value as result.

The call may look as follows:

/* With the following function you receive the standard deviation over a 10 day range. 'StandardDev' is the Equilla function that contains the actual calculation. */

myStdAbw = StandardDev( Close, 10 , 0 );

This is the source code of the Equilla StandardDev:

Meta:
    Synopsis( "[Standard Deviation 1] Returns the Standard Deviation value for the current bar." );

Inputs:
    Price( NumericSeries ),
    Period( NumericSimple ),
    DataType( NumericSimple );

Variables:
    divisor, sumSquare, avg, i;

StandardDev = 0;

If DataType = 1 Then
    divisor = Period
Else
    divisor = Period - 1;

If divisor > 0 Then Begin
    avg = AverageFC( Price, Period );
    sumSquare = 0;
    For i = 0 To Period - 1 Do
        sumSquare = sumSquare + Sqr( Price[i] - avg );
    If sumSquare > 0 Then
        StandardDev = Sqrt( sumSquare / divisor );
End
// *** Copyright tradesignal GmbH ***
// *** www.tradesignal.com ***

Another big advantage of functions is that you can call up the same functions from indicators and strategies. In fact, all indicators are based on functions - just as strategies are based on indicators.

You can find the functions that came with the program by clicking on the button Functions in the toolbox. To see the code of the function, right-click on it to open the context and select Edit.

Function Structure

For the programming of Equilla functions, the same conditions apply as for all Equilla scripts, see the chapter Equilla Program Structure and Syntax. Minor divergences are given in the following paragraphs.

Function Name

The function name is necessary to a) save the function in the file system and b) call up the function from within an Equilla script. When choosing the name, take care that the name

is short and concise
relates to the contents
is not yet in use for another function (this might cause problems)

//The function Momentum gives the indicator of the same name as result
myFirstVar = Momentum( PriceSerie, CalculationPeriod );

Passing Parameters upon Function Call

For the calculation of indicators, statistics and other values, certain information has to be given:

which data is to be used for calculation
which time range is to be used for calculation

When calling up the function, these parameters (separated by commas) have to be passed in brackets.

/* The function 'Momentum' gives the indicator of the same name as result As parameter the function demands the data to be used for the Momentum and the time range over which to calculate. */

myFirstVar = Momentum( Close, 20 );

Input Declaration in Functions

In the source code of the function, any inputs from outside have to be declared. As opposed to the definition of indicators, the type of the input parameters has to be declared in functions.

Inputs:
    //A data series, e.g. prices, has to be declared as NumericSeries
    PriceValue( NumericSeries ),

    //Simple numeric values are declared as NumericSimple
    PeriodFast( NumericSimple ),

    //Booleans as true/false (yes/no) value are declared TrueFalseSimple
    DrawVisuals( TrueFalseSimple ),

    //Strings like words or symbols are declared as StringSimple
    UserName( StringSimple ),

    //If you want to pass data that will be modified within the function and the
    //resulting modified value is to be used outside of the function, you have
    //to declare this as NumericRef
    AdjustedPeriod( NumericRef ),

    //Arrays can have multiple dimensions in Equilla, each dimension also
    //declares an additional input for the function, in this example the
    //function expects a 2-dimensional array as input which will be accessible
    //with the name Array2D and the numeric inputs Rows and Columns which are
    //initialized to contain the lenght of the array in this dimension.
    Array2D [ Rows, Columns ] ( NumericArray ),

    //If you want to pass an extension object to a function, you have to declare
    //the input as ObjectSimple (available in Tradesignal 6.3 and above).
    ExtensionObject ( ObjectSimple );

Make sure to use the parameters in the same sequence as they are declared in the function. The names of parameters used inside of functions are independent of parameter names that are passed. Therefore you can use the parameter 'Period', which is passed when calling the function, under another name within the function. You only have to take care that the sequence of values passed is the same as in the declaration.

Variable Declaration in Functions

The same conventions apply as described in Equilla Basics. You can also use variable names that are already in use in the main program, as there is no danger of collision.

Returning Values

Values that were calculated in the function usually should be available for further processing. To do so, the values have to be "returned". The actual way of returning depends on which kind of value has to be returned.

Returning a single value

If only a single value has to be returned, this is usually done with the name of the function. In the calling script, the function is assigned to a declared variable. The variable takes up the calculation result and makes it available for further operations.

// In the calling script, the result of the Momentum calculation
// is assigned to the variable myFirstVar

myFirstVar = Momentum( Close, 20 );

In the source code of the function, the calculation result has to be assigned to the name of the function.

Meta:
    Synopsis( "[Momentum] Returns the momentum of a series over a specified period." );

Inputs:
    Price( NumericSeries ),
    Period( NumericSimple );

//Assignment, i.e. returning the value

Momentum = Price - Price[ Period ];

Returning several values

When you want to return more than one result from a function, you must use so called reference parameters. These parameters will be passed into your function, modified within the function and then can be used. The following function shows two such reference parameters that are set to the result of two different moving averages:

//Function: TwoSmoothMA
Inputs:
    FastMA(NumericRef), // Notice how we declare the type of the inputs as numeric references
    SlowMA(NumericRef); // instead of numericseries or numericsimple.

Variables:
    smoothMA;

smoothMA = Average(Close, 5);
FastMA = Average(smoothMA, 10);
SlowMA = Average(smoothMA, 50);
TwoSmoothMA = 1; // A dummy return value that will not be used in this case.

We can now use our new function in the following way:

//Indicator: Two Smooth Averages
Meta:
SubChart(False);
Variables:
slowMA, fastMA;

TwoSmoothMA(slowMA, fastMA); // The values for slowMA and fastMA are set in the function

DrawLine(slowMA, "Slow");
DrawLine(fastMA, "Fast");

The advantage of using multiple output functions is that related operations can be nicely encapsulated, but more importantly that if the result of each output rely on a shared calculated value, it is more efficient to do the shared part once rather than twice in two functions that return single values.

Retrieving Past Values with Displacements

By using displacements, for example "Price[i]", you can retrieve older function results. A good example for this would be the search for a breakout within the last 20 days' high or low. Please note that with the displacement attribute, past values are retrieved. Therefore "[1]" gives the value for yesterday, [2] the value of two days ago etc.

Attention: Trying to retrieve values of functions that are not calculated continuously may result in wrong indicator results. This would be the case, for example, when the function call is in a subroutine that is not executed for each bar.

Additional Information for Functions

For all Equilla functions, you can find additional information in Tradesignal. To display it, open the source code in the Equilla Editor. Then right-click on the function in question, e.g. DateTime, and choose Lookup Equilla Function from the context menu. A window opens with information on the command and links to related functions.