Home » Mathemtical Functions » Understanding matrix.add_col() Function in Pine Script

Understanding matrix.add_col() Function in Pine Script

Photo of author
Published on

The matrix.add_col() function in Pine Script is a versatile tool designed for matrix manipulation. It allows you to add a new column to an existing matrix, either filled with na values or specified values from an array. This function is instrumental in data organization and manipulation, offering flexibility in handling matrix structures within your Pine Script indicators or strategies.

Syntax and Overloads

The matrix.add_col() function comes with two primary usages:

  1. matrix.add_col(id)
    Adds a column filled with na values to the end of the matrix specified by id.
  2. matrix.add_col(id, column, array_id)
    Inserts a new column at the specified column index in the matrix id, filling it with values from array_id.

Arguments:

  • id (any matrix type): The target matrix object.
  • column (series int): The index after which the new column will be added. This argument is optional, with the default being the matrix’s current number of columns, effectively adding the new column at the end.
  • array_id: An array containing values to fill the new column. This argument is optional.

Examples

Adding a Column with na Values

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

// Initialize a 2x3 "int" matrix with all elements set to `0`.
mtrxInit = matrix.new<int>(2, 3, 0)

// Append a column filled with `na` values to the matrix.
matrix.add_col(mtrxInit)

// Visualize matrix elements.
if barstate.islastconfirmedhistory
    var tblDisplay = table.new(position.top_right, 2, 2, color.green)
    table.cell(tblDisplay, 0, 0, "Updated Matrix:")
    table.cell(tblDisplay, 0, 1, str.tostring(mtrxInit))
Examples

Adding an Array as a Column

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

if barstate.islastconfirmedhistory
    // Create an initially empty matrix object.
    var mtrxEmpty = matrix.new<int>()
    
    // Generate an array with values `1` and `3`.
    var arrayVals = array.from(1, 3)
    
    // Insert the `arrayVals` as the first column of the matrix.
    matrix.add_col(mtrxEmpty, 0, arrayVals)
    
    // Display the matrix to visualize the changes.
    var tblMatrixDisplay = table.new(position.top_right, 2, 2, color.green)
    table.cell(tblMatrixDisplay, 0, 0, "Matrix Update:")
    table.cell(tblMatrixDisplay, 0, 1, str.tostring(mtrxEmpty))
Adding an Array as a Column

Explanation of Code

  1. Indicator Declaration:
    • //@version=5: Specifies the use of version 5 of Pine Script.
    • indicator("Enhanced matrix.add_col() Example 2"): Declares a new indicator with a custom title.
  2. Conditional Execution:
    • if barstate.islastconfirmedhistory: Ensures that the code block executes only on the last confirmed historical bar. This is used to avoid unnecessary computations on every bar update.
  3. Matrix Initialization:
    • var mtrxEmpty = matrix.new<int>(): Initializes a new, empty matrix of integer type. The var keyword ensures that the matrix is initialized only once and retains its values over the script’s execution.
  4. Array Creation:
    • var arrayVals = array.from(1, 3): Creates a new array containing the integers 1 and 3. Similar to the matrix, the array is declared with var to maintain its values throughout the script’s lifecycle.
  5. Adding a Column to the Matrix:
    • matrix.add_col(mtrxEmpty, 0, arrayVals): Adds a new column at the beginning of mtrxEmpty (since the column index is specified as 0), filling it with the values from arrayVals (1 and 3).
  6. Table Creation for Display:
    • var tblMatrixDisplay = table.new(position.top_right, 2, 2, color.green): Initializes a new display table with 2 rows and 2 columns, positioned at the top right of the chart, with a green border color. The table is created once and updated as needed.
  7. Populating the Table:
    • table.cell(tblMatrixDisplay, 0, 0, "Matrix Update:"): Sets the first cell of the table to display the text “Matrix Update:”.
    • table.cell(tblMatrixDisplay, 0, 1, str.tostring(mtrxEmpty)): Converts the matrix mtrxEmpty to a string and displays its content in the adjacent cell. This visually represents the updated matrix structure after adding the new column.

Key Remarks

  • Efficiency: It’s generally more efficient to initialize a matrix with predetermined dimensions and fill it with values, as opposed to adding columns to an empty matrix.
  • Performance: Adding a column to a matrix is slower compared to adding a row using the matrix.add_row function. This is an important consideration for scripts that require high performance or handle large data sets.

Summary

  • matrix.add_col() enhances matrix manipulation by allowing columns to be added dynamically.
  • Two main forms: adding a column of na values or inserting values from an array.
  • Remember, while flexible, adding columns is less efficient than predefining matrix sizes or adding rows.

This function broadens the scope of matrix manipulation in Pine Script, making it a valuable tool for developers looking to handle complex data structures within their trading algorithms.

Leave a Comment