Skip to content

Add TimeSeries.argmax() and argmin() aggregation methods - #3180

Closed
jaideeppyne wants to merge 1 commit into
unit8co:masterfrom
jaideeppyne:feat/timeseries-argmax-argmin
Closed

jaideeppyne wants to merge 1 commit into
unit8co:masterfrom
jaideeppyne:feat/timeseries-argmax-argmin

Conversation

@jaideeppyne

Copy link
Copy Markdown

Summary

Adds TimeSeries.argmax() and TimeSeries.argmin(), which return the integer position of the maximum/minimum along a given axis, following numpy.argmax/numpy.argmin semantics.

This addresses the second half of #2696, which notes:

There also does not seem to be a TimeSeries equivalent of Series.idxmax or np.ndarray.argmax.

Rather than changing the existing max()/min() behaviour (which the issue observes is kept for consistency with mean(axis=0), median(axis=0), … and would be a breaking change), this adds the missing positional reducers alongside them.

With axis=0, the returned position maps straight back to a timestamp:

pos = series.argmax(axis=0)          # position of each component's max over time
ts_of_max = series.time_index[int(pos.values()[0, 0])]

Details

  • argmax(axis=2) / argmin(axis=2) mirror the existing max()/min() implementation exactly, reusing _get_agg_dims for the output time index and component naming (components_argmax / components_argmin when reducing over components).
  • Works over all three axes (time, components, samples), consistent with the other reducers.
  • Non-breaking: purely additive.

Testing

  • Added test_argmin / test_argmax to TestSimpleStatistics, checking both that the positions equal numpy.argmin/argmax and that each returned position actually points back to the true extremum (via np.take_along_axis) across all three axes.
  • New tests pass; the full TestSimpleStatistics suite is green; ruff check and ruff format --check pass.
  • Added a CHANGELOG.md entry under Improved.

Add argmax()/argmin() to complement the existing max()/min() aggregations.
They return the integer position of the extremum along the given axis,
following numpy.argmax/argmin semantics. With axis=0 the returned position
maps back to a timestamp via series.time_index[position], which addresses
the common need to locate *when* a series reaches its min/max (see unit8co#2696).

Mirrors the existing max()/min() implementation and _get_agg_dims handling,
adds unit tests covering all three axes, and a CHANGELOG entry.

Signed-off-by: Jaideep Pyne <jaideeppyne1997@gmail.com>
@jaideeppyne
jaideeppyne force-pushed the feat/timeseries-argmax-argmin branch from 0b2553b to 83311af Compare August 16, 2026 12:07

@dennisbader dennisbader left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the PR @jaideeppyne. This is already being worked on in #3115, so I'm closing this one in favor of the other. Feel free to add your comments / review there.

@dennisbader dennisbader closed this Sep 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants