Home » Table Functions » Understanding the table.merge_cells() Function in Pine Script

Understanding the table.merge_cells() Function in Pine Script

Photo of author
Published on

In Pine Script, the table.merge_cells() function is a powerful tool for creating more dynamic and visually appealing tables within your trading indicators or strategies. This function allows you to merge a sequence of cells into one, creating a rectangle shape that spans from a specified top-left corner to a bottom-right corner. This feature is particularly useful for organizing and displaying grouped data or headings in a concise and readable format. Let’s dive into the syntax, arguments, and practical application of this function.

Syntax

The syntax for the table.merge_cells() function is straightforward:

table.merge_cells(table_id, start_column, start_row, end_column, end_row) → void

This function does not return any value (void) and operates directly on the table object specified by table_id.

Arguments

  • table_id (series table): This is the identifier of the table you’re working with. You must create a table object using table.new() before you can merge its cells.
  • start_column (series int): The column index of the top-left cell in the merge area, starting from 0.
  • start_row (series int): The row index of the top-left cell in the merge area, starting from 0.
  • end_column (series int): The column index of the bottom-right cell in the merge area, starting from 0.
  • end_row (series int): The row index of the bottom-right cell in the merge area, starting from 0.

Example

Let’s consider an example that creates a table displaying three Simple Moving Averages (SMAs) for the last bar on the chart:

//@version=5
indicator("table.merge_cells example")
SMA50  = ta.sma(close, 50)
SMA150 = ta.sma(close, 150)
SMA250 = ta.sma(close, 250)
if barstate.islast
    maTable = table.new(position.bottom_right, 3, 3, bgcolor = color.gray, border_width = 1, border_color = color.black)
    // Header
    table.cell(maTable, 0, 0, text = "SMA Overview")
    table.merge_cells(maTable, 0, 0, 2, 0)
    // Cell Titles
    table.cell(maTable, 0, 1, text = "SMA 50")
    table.cell(maTable, 1, 1, text = "SMA 150")
    table.cell(maTable, 2, 1, text = "SMA 250")
    // Values
    table.cell(maTable, 0, 2, bgcolor = color.white, text = str.tostring(SMA50))
    table.cell(maTable, 1, 2, bgcolor = color.white, text = str.tostring(SMA150))
    table.cell(maTable, 2, 2, bgcolor = color.white, text = str.tostring(SMA250))
Example

Walkthrough of Code 

  1. Indicator Declaration:
    • The script begins with //@version=5 indicating it uses version 5 of Pine Script.
    • indicator("table.merge_cells example") declares a new indicator with the title “table.merge_cells example”.
  2. Calculation of SMAs:
    • SMA50 = ta.sma(close, 50) calculates the 50-period SMA of the closing prices.
    • SMA150 = ta.sma(close, 150) calculates the 150-period SMA of the closing prices.
    • SMA250 = ta.sma(close, 250) calculates the 250-period SMA of the closing prices.
  3. Conditional Execution:
    • if barstate.islast ensures the following code block executes only on the last bar of the chart. This is typically used to avoid unnecessary calculations on every bar update.
  4. Table Creation:
    • maTable = table.new(position.bottom_right, 3, 3, bgcolor = color.gray, border_width = 1, border_color = color.black) creates a new table positioned at the bottom right of the chart. This table has 3 columns and 3 rows, with a gray background, a border width of 1, and a black border color.
  5. Header Creation and Merging:
    • table.cell(maTable, 0, 0, text = "SMA Overview") adds a cell with the text “SMA Overview” at the top-left corner (0,0) of the table.
    • table.merge_cells(maTable, 0, 0, 2, 0) merges the cells in the first row from the first column (0,0) to the third column (2,0) to create a single header cell spanning the entire width of the table.
  6. Adding Cell Titles:
    • The script adds titles for each SMA value in the second row of the table:
      • table.cell(maTable, 0, 1, text = "SMA 50") for the 50-period SMA.
      • table.cell(maTable, 1, 1, text = "SMA 150") for the 150-period SMA.
      • table.cell(maTable, 2, 1, text = "SMA 250") for the 250-period SMA.
  7. Displaying SMA Values:
    • The script displays the calculated SMA values in the third row with a white background:
      • table.cell(maTable, 0, 2, bgcolor = color.white, text = str.tostring(SMA50)) shows the 50-period SMA value.
      • table.cell(maTable, 1, 2, bgcolor = color.white, text = str.tostring(SMA150)) shows the 150-period SMA value.
      • table.cell(maTable, 2, 2, bgcolor = color.white, text = str.tostring(SMA250)) shows the 250-period SMA value.

Key Features and Takeaways

  • Merging Capability: The function merges multiple cells into one larger cell, based on specified start and end points, enhancing table readability and organization.
  • Inheritance of Properties: The merged cell inherits properties from the top-left cell, excluding width and height, which are automatically adjusted based on the merge.
  • Modification Post-Merge: To modify a merged cell, use table.cell_set_* functions targeting the start cell’s coordinates.
  • Error Handling: Attempting to merge already merged cells will result in an error, ensuring data integrity and preventing script crashes.

Leave a Comment