doc: Improve documentation for decimation on datetime axis

[rzats]

What type of PR is this? (Check all that apply)

• 🛠 Refactor
• ✨ Feature
• 🐛 Bug Fix
• ⚡ Optimization
• 📝 Documentation Update

Description

Adds an example of decimating data where we want to display a datetime axis. The idea is that the MinMaxDecimator takes the first and second column of the dataframe as x and y axes:

x = data[:, 0]
y = data[:, 1]

But it's possible to just set a different column as X axis marks. (Please correct me if my understanding isn't correct :)

Related Tickets & Documents

• Closes [DOCS] Improve decimator for datetime axis or improve documentation #2285.

How to reproduce the issue

N/A - it's just a docs update, but feel free to run the included example file as well.

Backporting

This change should be backported to:

• 3.0
• 3.1
• 4.0
• develop

Checklist

We encourage keeping the code coverage percentage at 80% or above.

• ✅ This solution meets the acceptance criteria of the related issue.
• 📝 The related issue checklist is completed.
• 🧪 This PR includes unit tests for the developed code.
  If not, explain why: docs only
• 🔄 End-to-End tests have been added or updated.
  If not, explain why: docs only
• 📚 The documentation has been updated, or a dedicated issue has been created.
  If not, explain why:
• 📌 The release notes have been updated.
  If not, explain why: handled by maintainers?

[github-actions]

This PR has been labelled as "🥶Waiting for contributor" because it has been inactive for more than 14 days. If you would like to continue working on this PR, then please add new commit or another comment, otherwise this PR will be closed in 14 days. For more information please refer to the contributing guidelines.

[github-actions]

This PR has been labelled as "🥶Waiting for contributor" because it has been inactive for more than 14 days. If you would like to continue working on this PR, then please add new commit or another comment, otherwise this PR will be closed in 14 days. For more information please refer to the contributing guidelines.

[Copilot]

Pull request overview

This PR aims to improve documentation by adding an example demonstrating how to use decimators with datetime data on the x-axis. However, the implementation contains a fundamental misunderstanding of how the MinMaxDecimator processes DataFrame columns.

Key Issues:

• The example incorrectly assumes the decimator always uses the first two DataFrame columns (data[:, 0] and data[:, 1])
• In reality, the decimator uses the columns specified by the chart's x and y parameters
• The current implementation will cause the decimator to operate on datetime objects rather than numeric values

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The DataFrame structure shown here will not work as described in the comments. The decimator uses the columns specified by the chart's x and y parameters (line 56: x="X_datetime"), not the first two columns.

Since x="X_datetime" is specified, the decimator will attempt to use the X_datetime column (datetime values) for the x-axis in its algorithm, not X_numeric. This means the MinMax algorithm will operate on datetime objects rather than numeric values, which is likely not the intended behavior and may cause errors or unexpected results.

[Copilot]

The docstring description is misleading. It states "using numeric x-axis values while keeping datetime information separate," but the actual implementation uses x="X_datetime" in the chart configuration (line 56), which means the decimator algorithm will receive datetime values, not numeric values.

The current approach does not demonstrate "proper use of decimators with datetime data" because the decimator will attempt to perform numeric operations (like reshaping and finding min/max) on datetime objects based on the specified x column.

[Copilot]

The comment incorrectly describes how the decimator algorithm works. The decimator does not automatically use data[:, 0] and data[:, 1] based on DataFrame column order. Instead, it uses the columns specified by the chart's x and y parameters.

In this example, since x="X_datetime" is set on line 56, the decimator will extract X_datetime (datetime values) and Y columns, convert them to a numpy array, and then apply the MinMax algorithm. This means the decimator will try to perform numeric operations on datetime objects, which may not work as intended.

The X_numeric column is never used by the decimator in this configuration. If the goal is to decimate based on numeric values while displaying datetime on the x-axis, this approach will not work as described.

Suggested change

	# How to decimate datetime data? - Structure data for decimation algorithm:
	# Column 0: Numeric values for decimation algorithm (data[:, 0])
	# Column 1: Y values (data[:, 1])
	# Column 2: DateTime values for x-axis display (data[:, 2])
	# How to decimate datetime data?
	# The decimator uses the columns specified by the chart's `x` and `y` parameters.
	# In this example, since `x="X_datetime"` is set, the decimator will operate on datetime values,
	# which may not work as intended for numeric decimation. If you want to decimate based on numeric values,
	# set `x="X_numeric"` and handle datetime display separately.

[github-actions]

This PR has been labelled as "🥶Waiting for contributor" because it has been inactive for more than 14 days. If you would like to continue working on this PR, then please add new commit or another comment, otherwise this PR will be closed in 14 days. For more information please refer to the contributing guidelines.