The Cluster Search indicator scans finished bars for footprint rows that satisfy a user-defined condition and returns the matching rows in a table. It is a scan over completed data rather than a live overlay, so the rule set is evaluated when a bar closes and the table is refreshed as new bars arrive. Configuration is split into a condition builder, a threshold block, an aggregation block and a look-back window.
01 Condition builder
A condition is a small tree of comparisons. A leaf node selects one field of a cluster row and compares it with a constant or with another field of the same row. Branches combine leaves with AND, OR and NOT. The tree is edited as a list where each line is one leaf and indentation expresses grouping.
- Fields available to a leaf: bid volume, ask volume, total volume, delta, trade count, imbalance ratio and the price offset of the row from the bar open.
- Operators: greater than, less than, equal to within a tolerance, and a percentage comparison between two fields.
- Right-hand side: a literal, another field of the same row, or a rolling average of that field over the previous n bars.
An example leaf reads: delta is greater than 1.5 times the 20-bar rolling average of delta. Grouping matters, because joining two leaves with OR and then combining the pair with AND against a third leaf produces a different result set than a flat AND over three leaves.
02 Ratio and volume thresholds
Ratio tests compare the two sides of a row, while volume tests gate the search on absolute size. Both are needed in practice: a ratio test alone fires on noise during thin periods, and a volume test alone fires on large but balanced rows.
| Parameter | Value |
|---|---|
| Asymmetry ratio, ask over bid | 3.0 |
| Minimum row volume | 250 |
| Minimum bar volume | 2 000 |
| Minimum trade count per row | 5 |
| Ratio tolerance for equality | 2 percent |
The minimum volume floor should be scaled to the instrument. A value that is reasonable for an index contract will suppress nearly every row on a low-liquidity contract.
03 Aggregation filters
A raw match is a single row. Aggregation filters group matches into events so that the table reports activity rather than individual rows.
- Minimum consecutive rows — a match counts only when at least n neighbouring rows also match.
- Maximum gap — consecutive rows are treated as one event even when up to n non-matching rows separate them.
- Direction filter — keep only rows whose delta sign matches the direction of the parent bar.
- Cooldown — suppress new events within n bars after a reported event.
With a minimum of two consecutive rows and a gap of one, a run of three matching rows separated by a single quiet row is reported as one event of length four.
04 Look-back window
The look-back window bounds the scan. It can be expressed as a number of bars, a number of sessions or a fixed date range. A window of 500 bars on a five-minute chart covers roughly 41 hours of continuous data; the same window on a one-hour chart covers several weeks. Session-limited windows reset at the session boundary, so the first bars of a new session are scanned against a shorter history.
A larger window increases both the number of matches and the time needed to refresh the table after each closed bar. When the scan is set to recalculate on every tick instead of on close, the cost is paid per tick and the window should be kept small.
05 Result table and chart mapping
The result table has one row per aggregated event with the columns time, price row, bar volume, row volume, row delta, asymmetry ratio and event length. Selecting a table row moves the chart to the parent bar and draws a marker on it. Markers are drawn on closed bars only, so the most recent bar receives a marker after it closes.
06 Saving and loading rule sets
A rule set is the full tree plus thresholds, aggregation filters and the window. Rule sets are named and kept with the chart template or with the workspace, depending on the storage option selected at save time. Loading a rule set replaces the current tree; it does not merge with it. Exporting a rule set writes a plain text description of the tree so that two configurations can be compared line by line.
