Skip to content

Rollup functions

riweather.rollup_starting 

rollup_starting(data, period='h', *, upsample_first=True)

Roll up data, labelled with the period start.

Parameters:

  • data (Series | DataFrame) –

    Time series data with a datetime index

  • period (str, default: 'h' ) –

    Period to resample to. Defaults to "h", which is hourly.

  • upsample_first (bool, default: True ) –

    Perform minute-level upsampling prior to calculating the period average.

Returns:

  • Series | DataFrame –

    The time series rolled up to the specified period.

Examples:

>>> import pandas as pd
>>> t = pd.Series(
...     [1, 2, 10],
...     index=pd.date_range(
...         "2023-01-01 00:01",
...         "2023-01-01 01:05",
...         freq="32min",
...     ),
... )
>>> t
2023-01-01 00:01:00     1
2023-01-01 00:33:00     2
2023-01-01 01:05:00    10
Freq: 32min, dtype: int64

By default, the data are upsampled to minute-level before aggregation.

>>> rollup_starting(t)
2023-01-01 00:00:00    3.207627
2023-01-01 01:00:00    9.375000
Freq: h, dtype: float64

The above is equivalent to upsampling and then aggregating with Pandas resample():

>>> x = upsample(t, period="min")
>>> x
2023-01-01 00:01:00     1.00000
2023-01-01 00:02:00     1.03125
2023-01-01 00:03:00     1.06250
2023-01-01 00:04:00     1.09375
2023-01-01 00:05:00     1.12500
                         ...
2023-01-01 01:01:00     9.00000
2023-01-01 01:02:00     9.25000
2023-01-01 01:03:00     9.50000
2023-01-01 01:04:00     9.75000
2023-01-01 01:05:00    10.00000
Freq: min, Length: 65, dtype: float64
>>> x.resample("h").mean()
2023-01-01 00:00:00    3.207627
2023-01-01 01:00:00    9.375000
Freq: h, dtype: float64

To skip upsampling and aggregate raw values only, use upsample_first=False.

>>> rollup_starting(t, upsample_first=False)
2023-01-01 00:00:00     1.5
2023-01-01 01:00:00    10.0
Freq: h, dtype: float64
Source code in src/riweather/stations.py 
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
def rollup_starting(
    data: pd.Series | pd.DataFrame, period: str = "h", *, upsample_first: bool = True
) -> pd.Series | pd.DataFrame:
    """Roll up data, labelled with the period start.

    Args:
        data: Time series data with a datetime index
        period: Period to resample to. Defaults to `"h"`, which is hourly.
        upsample_first: Perform minute-level upsampling prior to calculating
            the period average.

    Returns:
        The time series rolled up to the specified period.

    Examples:
        >>> import pandas as pd
        >>> t = pd.Series(
        ...     [1, 2, 10],
        ...     index=pd.date_range(
        ...         "2023-01-01 00:01",
        ...         "2023-01-01 01:05",
        ...         freq="32min",
        ...     ),
        ... )
        >>> t
        2023-01-01 00:01:00     1
        2023-01-01 00:33:00     2
        2023-01-01 01:05:00    10
        Freq: 32min, dtype: int64

        By default, the data are [upsampled][riweather.upsample] to minute-level before aggregation.

        >>> rollup_starting(t)
        2023-01-01 00:00:00    3.207627
        2023-01-01 01:00:00    9.375000
        Freq: h, dtype: float64

        The above is equivalent to upsampling and then aggregating with [Pandas `resample()`][pandas.Series.resample]:

        >>> x = upsample(t, period="min")
        >>> x
        2023-01-01 00:01:00     1.00000
        2023-01-01 00:02:00     1.03125
        2023-01-01 00:03:00     1.06250
        2023-01-01 00:04:00     1.09375
        2023-01-01 00:05:00     1.12500
                                 ...
        2023-01-01 01:01:00     9.00000
        2023-01-01 01:02:00     9.25000
        2023-01-01 01:03:00     9.50000
        2023-01-01 01:04:00     9.75000
        2023-01-01 01:05:00    10.00000
        Freq: min, Length: 65, dtype: float64
        >>> x.resample("h").mean()
        2023-01-01 00:00:00    3.207627
        2023-01-01 01:00:00    9.375000
        Freq: h, dtype: float64

        To skip upsampling and aggregate raw values only, use `upsample_first=False`.

        >>> rollup_starting(t, upsample_first=False)
        2023-01-01 00:00:00     1.5
        2023-01-01 01:00:00    10.0
        Freq: h, dtype: float64
    """
    if upsample_first:
        data = upsample(data, period="min")
    return data.resample(period, label="left", closed="left").mean()

riweather.rollup_ending 

rollup_ending(data, period='h', *, upsample_first=True)

Roll up data, labelled with the period end.

Parameters:

  • data (Series | DataFrame) –

    Time series data with a datetime index

  • period (str, default: 'h' ) –

    Period to resample to. Defaults to "h", which is hourly.

  • upsample_first (bool, default: True ) –

    Perform minute-level upsampling prior to calculating the period average.

Returns:

  • Series | DataFrame –

    The time series rolled up to the specified period.

Examples:

>>> import pandas as pd
>>> t = pd.Series(
...     [1, 2, 10],
...     index=pd.date_range(
...         "2023-01-01 00:01",
...         "2023-01-01 01:05",
...         freq="32min",
...     ),
... )
>>> t
2023-01-01 00:01:00     1
2023-01-01 00:33:00     2
2023-01-01 01:05:00    10
Freq: 32min, dtype: int64

By default, the data are upsampled to minute-level before aggregation.

>>> rollup_ending(t)
2023-01-01 01:00:00    3.3
2023-01-01 02:00:00    9.5
Freq: h, dtype: float64

The above is equivalent to upsampling and then aggregating with Pandas resample():

>>> x = upsample(t, period="min")
>>> x
2023-01-01 00:01:00     1.00000
2023-01-01 00:02:00     1.03125
2023-01-01 00:03:00     1.06250
2023-01-01 00:04:00     1.09375
2023-01-01 00:05:00     1.12500
                         ...
2023-01-01 01:01:00     9.00000
2023-01-01 01:02:00     9.25000
2023-01-01 01:03:00     9.50000
2023-01-01 01:04:00     9.75000
2023-01-01 01:05:00    10.00000
Freq: min, Length: 65, dtype: float64
>>> x.resample("h", label="right", closed="right").mean()
2023-01-01 01:00:00    3.3
2023-01-01 02:00:00    9.5
Freq: h, dtype: float64

To skip upsampling and aggregate raw values only, use upsample_first=False.

>>> rollup_ending(t, upsample_first=False)
2023-01-01 01:00:00     1.5
2023-01-01 02:00:00    10.0
Freq: h, dtype: float64
Source code in src/riweather/stations.py 
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
def rollup_ending(
    data: pd.Series | pd.DataFrame, period: str = "h", *, upsample_first: bool = True
) -> pd.Series | pd.DataFrame:
    """Roll up data, labelled with the period end.

    Args:
        data: Time series data with a datetime index
        period: Period to resample to. Defaults to `"h"`, which is hourly.
        upsample_first: Perform minute-level upsampling prior to calculating
            the period average.

    Returns:
        The time series rolled up to the specified period.

    Examples:
        >>> import pandas as pd
        >>> t = pd.Series(
        ...     [1, 2, 10],
        ...     index=pd.date_range(
        ...         "2023-01-01 00:01",
        ...         "2023-01-01 01:05",
        ...         freq="32min",
        ...     ),
        ... )
        >>> t
        2023-01-01 00:01:00     1
        2023-01-01 00:33:00     2
        2023-01-01 01:05:00    10
        Freq: 32min, dtype: int64

        By default, the data are [upsampled][riweather.upsample] to minute-level before aggregation.

        >>> rollup_ending(t)
        2023-01-01 01:00:00    3.3
        2023-01-01 02:00:00    9.5
        Freq: h, dtype: float64

        The above is equivalent to upsampling and then aggregating with [Pandas `resample()`][pandas.Series.resample]:

        >>> x = upsample(t, period="min")
        >>> x
        2023-01-01 00:01:00     1.00000
        2023-01-01 00:02:00     1.03125
        2023-01-01 00:03:00     1.06250
        2023-01-01 00:04:00     1.09375
        2023-01-01 00:05:00     1.12500
                                 ...
        2023-01-01 01:01:00     9.00000
        2023-01-01 01:02:00     9.25000
        2023-01-01 01:03:00     9.50000
        2023-01-01 01:04:00     9.75000
        2023-01-01 01:05:00    10.00000
        Freq: min, Length: 65, dtype: float64
        >>> x.resample("h", label="right", closed="right").mean()
        2023-01-01 01:00:00    3.3
        2023-01-01 02:00:00    9.5
        Freq: h, dtype: float64

        To skip upsampling and aggregate raw values only, use `upsample_first=False`.

        >>> rollup_ending(t, upsample_first=False)
        2023-01-01 01:00:00     1.5
        2023-01-01 02:00:00    10.0
        Freq: h, dtype: float64
    """
    if upsample_first:
        data = upsample(data, period="min")
    return data.resample(period, label="right", closed="right").mean()

riweather.rollup_midpoint 

rollup_midpoint(data, period='h', *, upsample_first=True)

Roll up data, labelled with the period midpoint.

Parameters:

  • data (Series | DataFrame) –

    Time series data with a datetime index

  • period (str, default: 'h' ) –

    Period to resample to. Defaults to "h", which is hourly.

  • upsample_first (bool, default: True ) –

    Perform minute-level upsampling prior to calculating the period average.

Returns:

  • Series | DataFrame –

    The time series rolled up to the specified period.

Examples:

>>> import pandas as pd
>>> t = pd.Series(
...     [1, 2, 10],
...     index=pd.date_range(
...         "2023-01-01 00:01",
...         "2023-01-01 01:05",
...         freq="32min",
...     ),
... )
>>> t
2023-01-01 00:01:00     1
2023-01-01 00:33:00     2
2023-01-01 01:05:00    10
Freq: 32min, dtype: int64

By default, the data are upsampled to minute-level before aggregation.

>>> rollup_midpoint(t)
2023-01-01 00:00:00    1.437500
2023-01-01 01:00:00    5.661458
Freq: h, dtype: float64

The above is equivalent to upsampling, shifting the data forward by half of the period, and then aggregating with Pandas resample():

>>> x = upsample(t, period="min")
>>> x
2023-01-01 00:01:00     1.00000
2023-01-01 00:02:00     1.03125
2023-01-01 00:03:00     1.06250
2023-01-01 00:04:00     1.09375
2023-01-01 00:05:00     1.12500
                         ...
2023-01-01 01:01:00     9.00000
2023-01-01 01:02:00     9.25000
2023-01-01 01:03:00     9.50000
2023-01-01 01:04:00     9.75000
2023-01-01 01:05:00    10.00000
Freq: min, Length: 65, dtype: float64
>>> x.shift(freq="30min").resample("h").mean()
2023-01-01 00:00:00    1.437500
2023-01-01 01:00:00    5.661458
Freq: h, dtype: float64

To skip upsampling and aggregate raw values only, use upsample_first=False.

>>> rollup_midpoint(t, upsample_first=False)
2023-01-01 00:00:00    1.0
2023-01-01 01:00:00    6.0
Freq: h, dtype: float64
Source code in src/riweather/stations.py 
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
def rollup_midpoint(
    data: pd.Series | pd.DataFrame, period: str = "h", *, upsample_first: bool = True
) -> pd.Series | pd.DataFrame:
    """Roll up data, labelled with the period midpoint.

    Args:
        data: Time series data with a datetime index
        period: Period to resample to. Defaults to `"h"`, which is hourly.
        upsample_first: Perform minute-level upsampling prior to calculating
            the period average.

    Returns:
        The time series rolled up to the specified period.

    Examples:
        >>> import pandas as pd
        >>> t = pd.Series(
        ...     [1, 2, 10],
        ...     index=pd.date_range(
        ...         "2023-01-01 00:01",
        ...         "2023-01-01 01:05",
        ...         freq="32min",
        ...     ),
        ... )
        >>> t
        2023-01-01 00:01:00     1
        2023-01-01 00:33:00     2
        2023-01-01 01:05:00    10
        Freq: 32min, dtype: int64

        By default, the data are [upsampled][riweather.upsample] to minute-level before aggregation.

        >>> rollup_midpoint(t)
        2023-01-01 00:00:00    1.437500
        2023-01-01 01:00:00    5.661458
        Freq: h, dtype: float64

        The above is equivalent to upsampling, [shifting][pandas.Series.shift] the data forward
        by half of the period, and then aggregating with [Pandas `resample()`][pandas.Series.resample]:

        >>> x = upsample(t, period="min")
        >>> x
        2023-01-01 00:01:00     1.00000
        2023-01-01 00:02:00     1.03125
        2023-01-01 00:03:00     1.06250
        2023-01-01 00:04:00     1.09375
        2023-01-01 00:05:00     1.12500
                                 ...
        2023-01-01 01:01:00     9.00000
        2023-01-01 01:02:00     9.25000
        2023-01-01 01:03:00     9.50000
        2023-01-01 01:04:00     9.75000
        2023-01-01 01:05:00    10.00000
        Freq: min, Length: 65, dtype: float64
        >>> x.shift(freq="30min").resample("h").mean()
        2023-01-01 00:00:00    1.437500
        2023-01-01 01:00:00    5.661458
        Freq: h, dtype: float64

        To skip upsampling and aggregate raw values only, use `upsample_first=False`.

        >>> rollup_midpoint(t, upsample_first=False)
        2023-01-01 00:00:00    1.0
        2023-01-01 01:00:00    6.0
        Freq: h, dtype: float64
    """
    if upsample_first:
        data = upsample(data, period="min")
    half_period = to_offset(period) / 2
    return data.shift(freq=half_period).resample(period, label="left", closed="left").mean()

riweather.rollup_instant 

rollup_instant(data, period='h', *, upsample_first=True)

Roll up data, labelled with interpolated values.

Parameters:

  • data (Series | DataFrame) –

    Time series data with a datetime index

  • period (str, default: 'h' ) –

    Period to resample to. Defaults to h, which is hourly.

  • upsample_first (bool, default: True ) –

    Perform minute-level upsampling prior to returning a value.

Returns:

Examples:

>>> import pandas as pd
>>> t = pd.Series(
...     [1, 2, 10],
...     index=pd.date_range(
...         "2023-01-01 00:01",
...         "2023-01-01 01:05",
...         freq="32min",
...     ),
... )
>>> t
2023-01-01 00:01:00     1
2023-01-01 00:33:00     2
2023-01-01 01:05:00    10
Freq: 32min, dtype: int64

By default, the data are upsampled to minute-level before aggregation.

>>> rollup_instant(t)
2023-01-01 00:00:00    1.00
2023-01-01 01:00:00    8.75
Freq: h, dtype: float64

The above is equivalent to upsampling and then aggregating with Pandas resample(), but instead of taking the mean over each time period, taking the first value:

>>> x = upsample(t, period="min")
>>> x
2023-01-01 00:01:00     1.00000
2023-01-01 00:02:00     1.03125
2023-01-01 00:03:00     1.06250
2023-01-01 00:04:00     1.09375
2023-01-01 00:05:00     1.12500
                         ...
2023-01-01 01:01:00     9.00000
2023-01-01 01:02:00     9.25000
2023-01-01 01:03:00     9.50000
2023-01-01 01:04:00     9.75000
2023-01-01 01:05:00    10.00000
Freq: min, Length: 65, dtype: float64
>>> x.resample("h").first()
2023-01-01 00:00:00    1.00
2023-01-01 01:00:00    8.75
Freq: h, dtype: float64

To skip upsampling and aggregate raw values only, use upsample_first=False. Notice that this is simply the first value in every time period (hour by default).

>>> rollup_instant(t, upsample_first=False)
2023-01-01 00:00:00     1
2023-01-01 01:00:00    10
Freq: h, dtype: int64
Source code in src/riweather/stations.py 
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
def rollup_instant(
    data: pd.Series | pd.DataFrame, period: str = "h", *, upsample_first: bool = True
) -> pd.Series | pd.DataFrame:
    """Roll up data, labelled with interpolated values.

    Args:
        data: Time series data with a datetime index
        period: Period to resample to. Defaults to `h`, which is hourly.
        upsample_first: Perform minute-level upsampling prior to returning
            a value.

    Returns:
        The time series aligned to the specified period.

    Examples:
        >>> import pandas as pd
        >>> t = pd.Series(
        ...     [1, 2, 10],
        ...     index=pd.date_range(
        ...         "2023-01-01 00:01",
        ...         "2023-01-01 01:05",
        ...         freq="32min",
        ...     ),
        ... )
        >>> t
        2023-01-01 00:01:00     1
        2023-01-01 00:33:00     2
        2023-01-01 01:05:00    10
        Freq: 32min, dtype: int64

        By default, the data are [upsampled][riweather.upsample] to minute-level before aggregation.

        >>> rollup_instant(t)
        2023-01-01 00:00:00    1.00
        2023-01-01 01:00:00    8.75
        Freq: h, dtype: float64

        The above is equivalent to upsampling and then aggregating with [Pandas `resample()`][pandas.Series.resample],
        but instead of taking the mean over each time period, taking the first value:

        >>> x = upsample(t, period="min")
        >>> x
        2023-01-01 00:01:00     1.00000
        2023-01-01 00:02:00     1.03125
        2023-01-01 00:03:00     1.06250
        2023-01-01 00:04:00     1.09375
        2023-01-01 00:05:00     1.12500
                                 ...
        2023-01-01 01:01:00     9.00000
        2023-01-01 01:02:00     9.25000
        2023-01-01 01:03:00     9.50000
        2023-01-01 01:04:00     9.75000
        2023-01-01 01:05:00    10.00000
        Freq: min, Length: 65, dtype: float64
        >>> x.resample("h").first()
        2023-01-01 00:00:00    1.00
        2023-01-01 01:00:00    8.75
        Freq: h, dtype: float64

        To skip upsampling and aggregate raw values only, use `upsample_first=False`. Notice that
        this is simply the first value in every time period (hour by default).

        >>> rollup_instant(t, upsample_first=False)
        2023-01-01 00:00:00     1
        2023-01-01 01:00:00    10
        Freq: h, dtype: int64
    """
    if upsample_first:
        data = upsample(data, period="min")
    return data.resample(period, label="left", closed="left").first()

riweather.upsample 

upsample(data, period='min')

Upsample and interpolate time series data.

Parameters:

  • data (Series | DataFrame) –

    Time series data with a datetime index

  • period (str, default: 'min' ) –

    Period to upsample to. Defaults to "min", which is minute-level

Returns:

Examples:

>>> import pandas as pd
>>> t = pd.Series(
...     [1, 2, 10],
...     index=pd.date_range(
...         "2023-01-01 00:01",
...         "2023-01-01 01:05",
...         freq="32min",
...     ),
... )
>>> upsample(t)
2023-01-01 00:01:00     1.00000
2023-01-01 00:02:00     1.03125
2023-01-01 00:03:00     1.06250
2023-01-01 00:04:00     1.09375
2023-01-01 00:05:00     1.12500
                         ...
2023-01-01 01:01:00     9.00000
2023-01-01 01:02:00     9.25000
2023-01-01 01:03:00     9.50000
2023-01-01 01:04:00     9.75000
2023-01-01 01:05:00    10.00000
Freq: min, Length: 65, dtype: float64

You can upsample to a different frequency if you want.

>>> upsample(t, period="5min")
2023-01-01 00:00:00     1.000000
2023-01-01 00:05:00     1.166667
2023-01-01 00:10:00     1.333333
2023-01-01 00:15:00     1.500000
2023-01-01 00:20:00     1.666667
2023-01-01 00:25:00     1.833333
2023-01-01 00:30:00     2.000000
2023-01-01 00:35:00     3.142857
2023-01-01 00:40:00     4.285714
2023-01-01 00:45:00     5.428571
2023-01-01 00:50:00     6.571429
2023-01-01 00:55:00     7.714286
2023-01-01 01:00:00     8.857143
2023-01-01 01:05:00    10.000000
Freq: 5min, dtype: float64
Source code in src/riweather/stations.py 
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
def upsample(data: pd.Series | pd.DataFrame, period: str = "min") -> pd.Series | pd.DataFrame:
    """Upsample and interpolate time series data.

    Args:
        data: Time series data with a datetime index
        period: Period to upsample to. Defaults to `"min"`, which is minute-level

    Returns:
        Upsampled data

    Examples:
        >>> import pandas as pd
        >>> t = pd.Series(
        ...     [1, 2, 10],
        ...     index=pd.date_range(
        ...         "2023-01-01 00:01",
        ...         "2023-01-01 01:05",
        ...         freq="32min",
        ...     ),
        ... )
        >>> upsample(t)
        2023-01-01 00:01:00     1.00000
        2023-01-01 00:02:00     1.03125
        2023-01-01 00:03:00     1.06250
        2023-01-01 00:04:00     1.09375
        2023-01-01 00:05:00     1.12500
                                 ...
        2023-01-01 01:01:00     9.00000
        2023-01-01 01:02:00     9.25000
        2023-01-01 01:03:00     9.50000
        2023-01-01 01:04:00     9.75000
        2023-01-01 01:05:00    10.00000
        Freq: min, Length: 65, dtype: float64

        You can upsample to a different frequency if you want.

        >>> upsample(t, period="5min")
        2023-01-01 00:00:00     1.000000
        2023-01-01 00:05:00     1.166667
        2023-01-01 00:10:00     1.333333
        2023-01-01 00:15:00     1.500000
        2023-01-01 00:20:00     1.666667
        2023-01-01 00:25:00     1.833333
        2023-01-01 00:30:00     2.000000
        2023-01-01 00:35:00     3.142857
        2023-01-01 00:40:00     4.285714
        2023-01-01 00:45:00     5.428571
        2023-01-01 00:50:00     6.571429
        2023-01-01 00:55:00     7.714286
        2023-01-01 01:00:00     8.857143
        2023-01-01 01:05:00    10.000000
        Freq: 5min, dtype: float64
    """
    return data.resample(period).mean().interpolate(method="linear", limit=60, limit_direction="both")