Understanding matrix.copy() Function in Pine Script

Pine Script’s matrix.copy() function is a powerful tool for duplicating matrix objects, ensuring that scripts can manipulate matrix data without altering the original source. This tutorial explores the function’s syntax, usage, and practical applications within Pine Script programming.

Syntax of `matrix.copy()`

The syntax for the matrix.copy() function is straightforward:

matrix.copy(id) → matrix<type>

Arguments

id (any matrix type): This is the matrix object you wish to copy.

Example

To demonstrate the utility of matrix.copy(), consider the following Pine Script example:

//@version=5
indicator("Matrix Duplication Example")

// For efficiency, execute this code only once.
if barstate.islastconfirmedhistory
    // Create a 2x3 "float" matrix with `1` values.
    var originalMatrix = matrix.new<float>(2, 3, 1)
    
    // Copy the matrix to a new one.
    var copiedMatrix = matrix.copy(originalMatrix)
    
    // Display using a table.
    var displayTable = table.new(position.top_center, 5, 2, color.green)
    table.cell(displayTable, 0, 0, "Original Matrix:")
    table.cell(displayTable, 0, 1, str.tostring(originalMatrix))
    table.cell(displayTable, 1, 0, "Matrix Copy:")
    table.cell(displayTable, 1, 1, str.tostring(copiedMatrix))

Detailed Walkthrough

Indicator Declaration: The indicator function call at the top defines a new indicator named “Matrix Duplication Example”. This is a mandatory declaration for any script running on TradingView’s Pine Script environment.
Conditional Execution: The if barstate.islastconfirmedhistory condition ensures that the code block inside it is executed only once and specifically when the script processes the last historical bar on the chart. This is done to improve efficiency by preventing the code from running on every bar update, which is unnecessary for operations like creating and copying matrices that only need to be done once.
Matrix Creation: var originalMatrix = matrix.new<float>(2, 3, 1) initializes a new 2×3 matrix (2 rows and 3 columns) where every element is set to a floating-point value of 1. The use of var ensures that the matrix is created only once during the script’s lifetime, even if the script’s context is recalculated.
Matrix Copying: var copiedMatrix = matrix.copy(originalMatrix) duplicates the originalMatrix. This operation creates a new matrix (copiedMatrix) with the same dimensions and values as originalMatrix. Again, var is used to ensure single initialization.
Table Display: The code then creates a new table positioned at the top center of the chart with 5 columns and 2 rows. However, the column and row count seem to be a mistake since the script only uses 2 columns and 2 rows for display. It uses table.new with color.green indicating the table’s border or background color.
Filling the Table: table.cell() functions are used to fill the table. The first argument is the table ID, followed by the row and column indices where the text should be placed, and finally the text itself. The script displays “Original Matrix:” and its content in the first row, and “Matrix Copy:” with its content in the second row. The content of the matrices is converted to string format using str.tostring() for display purposes.

Returns

The matrix.copy() function returns a new matrix object, which is a duplicate of the specified id matrix. This new matrix is completely independent of the original, allowing for safe modifications without affecting the source data.

Key Features and Takeaways

Functionality: matrix.copy() provides a reliable method to duplicate matrix objects, crucial for data manipulation and analysis tasks in financial scripting.
Syntax and Application: Understanding the function’s syntax and practical application is essential for effective Pine Script programming, especially in scenarios requiring data integrity and manipulation.
Efficiency in Scripting: The example demonstrates efficient scripting practices, such as using barstate.islastconfirmedhistory to limit operations to a single execution, optimizing script performance.

Syntax of matrix.copy()