Time series¶

Time series of rainfall, discharge, elevation and storage values.

class pyrunoff.utils.time_series.TimeSeries(data, sorted=False, _time_step=None)[source]¶

Bases: object

Base class for numeric time series indexed by timestamps.

Parameters:

data (Series) – Numeric values indexed by timestamps.
sorted (bool) – Whether to assume the index is already sorted.
_time_step (Timedelta | None) – Internal override for the series time step. For user-supplied data, the time step should normally be inferred from the DatetimeIndex. This override is not a trusted public API path and should only be used when the caller understands the implications of using it.

property time_step¶: Return the interval between consecutive time-series values.

classmethod sum(series)[source]¶

Return the elementwise sum of aligned series with matching intervals.

Every series must be an instance of the class sum is called on, so DischargeSeries.sum only accepts discharge series.

Parameters:

series (Iterable[TimeSeries]) – Series to add, with identical indexes and time steps.

Returns:

Sum, of the class sum is called on.

Raises:

TypeError – If a series is not of that class.
ValueError – If no series are given, or they are unsorted or their time steps or indexes differ.

Return type:

TimeSeries

classmethod dict_from_dataframe(data, columns=None, end=None)[source]¶

Return one series per column of a table indexed by timestamps.

The index is sorted and its time step inferred once for all columns.

Parameters:

data (DataFrame) – Values indexed by timestamps, one column per series.
columns (Iterable[str] | None) – Columns to convert; defaults to all of them.
end (Timestamp | datetime | None) – Optional timestamp at which every series ends; see fix_end().

Returns:

Series keyed by column name.

Raises:

ValueError – If columns are missing or duplicated, or a column’s values are invalid for this class (the error names the column).
TypeError – If a column’s values are not float-convertible.

Return type:

dict[str, Self]

copy()[source]¶

Return a copy of the same class with independent underlying data.

Return type:: TimeSeries

fix_end(end)[source]¶

Return a series of the same class ending at end.

Values after end are dropped; timestamps up to end are added at time_step with zero values.

Parameters:: end (Timestamp | datetime) – Timestamp at which the returned series ends.
Returns:: New series; this one is unchanged.
Return type:: Self

resample_at(time_step)[source]¶

Return series values resampled to the requested interval.

Parameters:: time_step (Timedelta | timedelta) – Interval of the returned values.
Returns:: Resampled values.
Raises:: NotImplementedError – Unless a subclass supports resampling.
Return type:: Series

class pyrunoff.utils.time_series.DischargeSeries(data, sorted=False, _time_step=None)[source]¶

Bases: TimeSeries

Time series of discharge values.

Parameters:

data (Series)
sorted (bool)
_time_step (Timedelta | None)

class pyrunoff.utils.time_series.StageSeries(data, sorted=False, _time_step=None)[source]¶

Bases: TimeSeries

Time series of water-level values.

Parameters:

data (Series)
sorted (bool)
_time_step (Timedelta | None)

class pyrunoff.utils.time_series.ElevationSeries(data, sorted=False, _time_step=None)[source]¶

Bases: TimeSeries

Time series of elevation values.

Parameters:

data (Series)
sorted (bool)
_time_step (Timedelta | None)

class pyrunoff.utils.time_series.StorageSeries(data, sorted=False, _time_step=None)[source]¶

Bases: TimeSeries

Time series of storage values.

Parameters:

data (Series)
sorted (bool)
_time_step (Timedelta | None)

class pyrunoff.utils.time_series.RainfallSeries(data, sorted=False, _time_step=None)[source]¶

Bases: TimeSeries

Time series of incremental rainfall values.

Parameters:

data (Series)
sorted (bool)
_time_step (Timedelta | None)

resample_at(time_step)[source]¶

Resample rainfall while preserving accumulated depth.

Each value is the depth over the interval ending at its timestamp, so the first value covers the interval before the first timestamp. The result therefore starts one new time_step after index[0] - self.time_step and keeps the total depth.

Parameters:: time_step (Timedelta | timedelta) – Interval of the returned values.
Returns:: Incremental depth at time_step intervals.
Return type:: Series