Understanding the matrix.add_row() Function in Pine Script

In this article, we delve into the matrix.add_row() function, a versatile tool for dynamically modifying matrix dimensions by adding rows.

Syntax and Overloads

The matrix.add_row() function allows for the addition of rows to a matrix, either as empty (initialized with na values) or by specifying an array of values to fill the new row. The function comes in two main forms:

• matrix.add_row(id, row) → void
• matrix.add_row(id, row, array_id) → void

Arguments:

• id (any matrix type): The matrix object to which a row will be added.
• row (series int): The index after which the new row will be inserted. This argument is optional, with the default being the last row of the matrix (matrix.rows).
• array_id (optional): An array containing values to fill the new row. This parameter is used in the second overload of the function.

Adding a Row to the Matrix

Example 1: Adding a Row with na Values

//@version=5
indicator("`matrix.add_row()` Example 1")

// Create a 2x3 "int" matrix with initial values of `0`.
matrixA = matrix.new<int>(2, 3, 0)

// Add a new row with `na` values to `matrixA`.
matrix.add_row(matrixA)

// Display matrix elements.
if barstate.islastconfirmedhistory
    var displayTable = table.new(position.top_right, 2, 2, color.green)
    table.cell(displayTable, 0, 0, "Matrix elements:")
    table.cell(displayTable, 0, 1, str.tostring(matrixA))

Example 2: Adding an Array as a Row to the Matrix

//@version=5
indicator("`matrix.add_row()` Example 2")

if barstate.islastconfirmedhistory
    // Create an empty matrix object.
    var matrixB = matrix.new<int>()
    
    // Create an array with values `1` and `2`.
    var array1 = array.from(1, 2)
    
    // Add `array1` as the first row of `matrixB`.
    matrix.add_row(matrixB, 0, array1)
    
    // Display matrix elements.
    var displayTable2 = table.new(position.top_right, 2, 2, color.green)
    table.cell(displayTable2, 0, 0, "Matrix elements:")
    table.cell(displayTable2, 0, 1, str.tostring(matrixB))

Explanation of Code

1. Indicator Declaration:
   • //@version=5: Specifies the version of Pine Script being used, which is version 5 in this case.
   • indicator("matrix.add_row() Example 2"): Declares a custom indicator named “matrix.add_row() Example 2″ for displaying in the TradingView chart.
2. Conditional Execution:
   • if barstate.islastconfirmedhistory: This condition checks if the script is executing on the last confirmed historical bar. This ensures that the matrix manipulation and display logic only run once, avoiding unnecessary recalculations on every bar update.
3. Matrix Initialization:
   • var matrixB = matrix.new<int>(): Initializes an empty matrix named matrixB with data type int (integer). The var keyword ensures that matrixB is only initialized once when the script is first run, and retains its value over subsequent script calculations.
4. Array Creation:
   • var array1 = array.from(1, 2): Creates a new array named array1 containing the integers 1 and 2. Similar to matrixB, array1 is also initialized once due to the var keyword.
5. Adding a Row to the Matrix:
   • matrix.add_row(matrixB, 0, array1): Adds a new row to matrixB at the first position (0 index) using the values from array1. This means array1 is inserted as the first row of the matrix.
6. Creating a Display Table:
   • var displayTable2 = table.new(position.top_right, 2, 2, color.green): Initializes a new display table named displayTable2 with 2 rows and 2 columns, positioned at the top right of the chart. The table’s background color is set to green. This table is used to display the matrix contents.
7. Displaying Matrix Elements:
   • table.cell(displayTable2, 0, 0, "Matrix elements:"): Sets the first cell (top-left) of displayTable2 to display the text “Matrix elements:”.
   • table.cell(displayTable2, 0, 1, str.tostring(matrixB)): Converts the contents of matrixB to a string using str.tostring() and displays this string in the adjacent cell (top-right) of the table. This effectively shows the matrix’s elements in the chart.

Key Features and Takeaways

• Dynamic Matrix Manipulation: matrix.add_row() facilitates dynamic changes to matrix dimensions, allowing for more flexible data analysis and manipulation in your scripts.
• Efficiency Consideration: While adding rows to an empty matrix is supported, it’s more efficient to declare a matrix with explicit dimensions and populate it with values, especially for large datasets.
• Zero-based Indexing: Pine Script uses zero-based indexing for rows and columns, making the first row and column index 0.
• Versatility in Usage: The function supports adding empty rows or rows filled with specified values, catering to various programming needs and scenarios.