Understanding matrix.columns() Function in Pine Script

Introduction

In this tutorial, we’ll dive into the matrix.columns() function in Pine Script, a powerful tool in the TradingView platform that allows traders and developers to create custom indicators and strategies. This function is particularly useful when working with matrix data structures, offering a straightforward way to retrieve the number of columns in a given matrix. Let’s explore its syntax, usage, and practical applications through an example.

Syntax

The syntax for matrix.columns() is:

matrix.columns(id) → series int

• id: This argument expects a matrix object, which is the matrix from which you want to find out the number of columns.

Example

//@version=5
indicator("`matrix.columns()` Example")
// Create a 2x6 matrix with values `0`.
var m = matrix.new<int>(2, 6, 0)
// Get the quantity of columns in matrix `m`.
var x = matrix.columns(m)
// Display using a label.
if barstate.islastconfirmedhistory
    label.new(bar_index, high, "Columns: " + str.tostring(x) + "\n" + str.tostring(m))

Example Explained

1. Indicator Declaration:
   • //@version=5: Specifies that the script uses version 5 of Pine Script. This is necessary for compatibility and to access the latest features.
   • indicator("matrix.columns() Example"): This line declares the script as an indicator and sets its name to “matrix.columns() Example”. Indicators are used to analyze and visualize data on TradingView charts.
2. Matrix Creation:
   • var m = matrix.new<int>(2, 6, 0): A 2×6 matrix named m is created and initialized with all elements set to 0. The var keyword is used to declare m as a variable that retains its value between chart bars. The matrix is of type integer (<int>), with 2 rows and 6 columns.
3. Retrieving the Number of Columns:
   • var x = matrix.columns(m): The number of columns in the matrix m is retrieved using the matrix.columns(m) function. The result is stored in the variable x, which is also declared with var to ensure its value is preserved across chart bars.
4. Displaying the Result:
   • The if condition if barstate.islastconfirmedhistory checks if the script is processing the last confirmed historical bar. This is a common practice to avoid unnecessary computations or drawing objects multiple times.
   • label.new(bar_index, high, "Columns: " + str.tostring(x) + "\n" + str.tostring(m)): If the condition is true, a label is created at the current bar’s index (bar_index) and at a vertical position equal to the high price. The label displays the number of columns in the matrix (x) and the matrix’s content as a string. str.tostring() is used to convert the integer and matrix to string format for display.

Key Features and Takeaways

• Function Usability: matrix.columns() is invaluable for scripts that dynamically manipulate matrices, allowing developers to adapt their logic based on the matrix dimensions.
• Syntax and Application: The function requires a single argument, the matrix object, and returns an integer representing the number of columns. Its straightforward syntax makes it accessible even for beginners in Pine Script.
• Practical Use Case: Commonly used in strategies or indicators that involve complex data manipulation, such as statistical models or custom chart visualizations.

By incorporating matrix.columns() into your Pine Script toolbox, you’ll enhance your ability to create dynamic and robust trading strategies and indicators. This function’s simplicity and utility make it a staple for anyone working with matrices in Pine Script.