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:
matrix.add_col(id)
Adds a column filled withna
values to the end of the matrix specified byid
.matrix.add_col(id, column, array_id)
Inserts a new column at the specifiedcolumn
index in the matrixid
, filling it with values fromarray_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))
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))
Explanation of Code
- 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.
- 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.
- Matrix Initialization:
var mtrxEmpty = matrix.new<int>()
: Initializes a new, empty matrix of integer type. Thevar
keyword ensures that the matrix is initialized only once and retains its values over the script’s execution.
- Array Creation:
var arrayVals = array.from(1, 3)
: Creates a new array containing the integers1
and3
. Similar to the matrix, the array is declared withvar
to maintain its values throughout the script’s lifecycle.
- Adding a Column to the Matrix:
matrix.add_col(mtrxEmpty, 0, arrayVals)
: Adds a new column at the beginning ofmtrxEmpty
(since the column index is specified as0
), filling it with the values fromarrayVals
(1
and3
).
- 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.
- 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 matrixmtrxEmpty
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.