feat(timeseries): add idxmin / idxmax to TimeSeries

[jbbqqf]

Fixes #2696.

Summary

TimeSeries.min(axis=0) and .max(axis=0) return a single-row series whose timestamp is just the first entry of the original time index, not the timestamp of the actual minimum / maximum. As @eschibli pointed out in #2696, this is misleading — users may not read the min/max docstring before trusting the index. @madtoinou agreed in the same thread that the corresponding time-step is well-defined per component, even in the multivariate case.

This PR adds TimeSeries.idxmin() and TimeSeries.idxmax(), which return a pandas.Series indexed by component name with values being the time-index entry (Timestamp or int for RangeIndex-based series) at which each component attains its minimum / maximum — mirroring pandas.DataFrame.idxmin/idxmax. The change is purely additive (no break in existing behavior).

Other Information

Why a pd.Series and not a TimeSeries?
Each component can have a different argmin / argmax (this is exactly the multivariate dilemma raised in the issue thread). A single-row TimeSeries cannot represent that — it would have to pick one component's argmax index for the whole row. Returning a pd.Series (which is what users were already falling back to via series.pd_dataframe().idxmax()) sidesteps the problem cleanly and matches pandas semantics.

Stochastic series. For probabilistic series we reduce samples with the median first, so the returned index does not depend on n_samples.

min / max docstrings. Added a one-line note pointing readers to the new helpers when they want the actual argmin/argmax timestamp; the existing behaviour (and signature) is unchanged.

CHANGELOG. Updated under Unreleased > For users of the library > Improved.

Reproduce BEFORE/AFTER yourself (copy-paste)

# --- one-time setup ---
git clone https://github.com/unit8co/darts.git /tmp/darts-2696 && cd /tmp/darts-2696
uv sync --group dev

# --- BEFORE (origin/master) ---
git checkout origin/master
uv run python -c "
import pandas as pd
from darts import TimeSeries
idx = pd.date_range('2020-01-01', periods=5, freq='D')
ts = TimeSeries(times=idx, values=[3.0, 1.0, 4.0, 0.0, 2.0], components=['a'])
print('min(axis=0).time_index[0] =', ts.min(axis=0).time_index[0])
print('idxmin =', ts.idxmin())
"
# Expected: prints 2020-01-01 (misleading: actual min is at 2020-01-04),
#           then AttributeError: 'TimeSeries' object has no attribute 'idxmin'

# --- AFTER (this PR) ---
git fetch https://github.com/jbbqqf/darts.git feat/2696-add-idxmin-idxmax
git checkout FETCH_HEAD
uv run python -c "
import pandas as pd
from darts import TimeSeries
idx = pd.date_range('2020-01-01', periods=5, freq='D')
ts = TimeSeries(times=idx, values=[3.0, 1.0, 4.0, 0.0, 2.0], components=['a'])
print('min(axis=0).time_index[0] =', ts.min(axis=0).time_index[0])  # unchanged
print('idxmin =', ts.idxmin().to_dict())
"
# Expected: same first line, then idxmin = {'a': 2020-01-04} — the real argmin timestamp.

The two commands are identical except for the checked-out ref.

What I ran locally

• uv run pytest darts/tests/test_timeseries.py::TestSimpleStatistics -v → 14 / 14 passed (10 pre-existing + 4 new).
• uv run pytest darts/tests/test_timeseries.py -k 'min or max' → all green.
• uv run ruff check darts/timeseries.py darts/tests/test_timeseries.py → all checks passed.
• Re-ran test_idxmin_idxmax_univariate_datetime against origin/master (with the test cherry-picked but the implementation reverted) — fails with AttributeError: 'TimeSeries' object has no attribute 'idxmin'. The new tests therefore both fail on master and pass on this branch.

Edge cases tested

#	Scenario	Input	Expected	Verified by
1	Univariate, datetime index	5 floats with argmin=3, argmax=2	idxmin → 2020-01-04, idxmax → 2020-01-03	test_idxmin_idxmax_univariate_datetime
2	Multivariate, different argmin per component	2 components with disjoint min/max positions	per-component values in returned pd.Series	test_idxmin_idxmax_multivariate
3	RangeIndex time index	Int-indexed series	returned values are int, not Timestamp	test_idxmin_idxmax_range_index
4	Stochastic series (50 samples around a target curve)	argmin of the median curve at t=2	returns 2020-01-03 regardless of sample noise	test_idxmin_idxmax_stochastic

Risk / blast radius

Purely additive — two new methods on TimeSeries, no change to min/max semantics, no signature changes elsewhere. The two min/max docstrings gain a .. note:: block but their behavior and return shape are identical to before.

---

PR drafted with assistance from Claude Code (Anthropic). Implementation, regression tests, and the BEFORE/AFTER reproducer above were reviewed manually against unit8co/darts@master and the discussion in #2696. The reproducer block was used during development; reviewers can paste it verbatim to verify.

[jakubchlapek]

Hey @jbbqqf, thanks for this PR.
The code looks fine, just had a few documentation changes I left in the comments. I also debated adding the axis parameter to the idxmin/max methods, but can't see a real usecase in which we wouldn't use multi series instead. You can let me know what you think.

[jakubchlapek]

i'd say this is redudnant with the rest of the docstring as the behavior is already mentioned above (`If we reduce over time (axis=0), the series will have length one and will use the first entry of the
original ``time_index```)

[jakubchlapek]

same case as above for min

[jakubchlapek]

i'd say this is unnecesssary

[jakubchlapek]

same as above

[jakubchlapek]

unnecessary, already mentioned in the docstring

[jakubchlapek]

Suggested change

	- Added `TimeSeries.idxmin()` and `TimeSeries.idxmax()`, returning a `pandas.Series` (indexed by component) of the time index value at which each component attains its minimum / maximum. Also clarified the docstrings of `min()` / `max()` to point users to these new helpers when they want the actual argmin/argmax timestamp. Closes [#2696](https://github.com/unit8co/darts/issues/2696).
	- Added `TimeSeries.idxmin()` and `TimeSeries.idxmax()`, returning a `pandas.Series` (indexed by component) of the time index value at which each component attains its minimum / maximum. Closes [#3115](https://github.com/unit8co/darts/pull/3115).

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.48%. Comparing base (b0ccd3a) to head (8f2c4f5).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3115      +/-   ##
==========================================
- Coverage   96.55%   96.48%   -0.07%     
==========================================
  Files         160      160              
  Lines       17285    17293       +8     
==========================================
- Hits        16689    16686       -3     
- Misses        596      607      +11     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.