Resampling, Aggregation, and Time Alignment

Install and import#

npm install fintech-algorithms

import { resamplingAggregationAndTimeAlignment } from "fintech-algorithms/foundations/financial-time-series-foundations/resampling-aggregation-and-time-alignment";

Signature#

resamplingAggregationAndTimeAlignment(input)

Cuts the series into consecutive fixed-size buckets and averages each one, coarsening the sampling frequency.

Parameters#

Returns#

D00Output

aggregatedMeans holds one mean per bucket and bucketSizes their lengths, the last of which is short when the series does not divide evenly. alignment is the fixed label left-closed sequential buckets.

Errors#

• When values is absent, empty, or holds a non-finite number — throws RangeError
• When timestamps and values have different lengths — throws RangeError
• When the series holds fewer than two observations — throws RangeError
• When resampleSize is not a positive integer — throws RangeError

Complexity: time O(n^2), space O(n).

Worked example#

verified This is the worked example published in the article, replayed by the test suite on every run. The output cannot drift.

Input#

{
  "timestamps": [
    "2025-01-01T00:00:00Z",
    "2025-01-02T00:00:00Z",
    "2025-01-03T00:00:00Z",
    "2025-01-04T00:00:00Z",
    "2025-01-05T00:00:00Z",
    "2025-01-06T00:00:00Z"
  ],
  "values": [100, 102, 101, 104, 106, 105],
  "lag": 1,
  "window": 3,
  "resampleSize": 2,
  "period": 3,
  "stationarityTolerance": 3,
  "alpha": 0.4,
  "splitIndex": 4
}

Call#

resamplingAggregationAndTimeAlignment(input)

Returns#

object with 2 fields: aggregatedMeans, bucketSizes

{
  "aggregatedMeans": [101, 102.5, 105.5],
  "bucketSizes": [2, 2, 2]
}

Diagrams#

Calculation flow#

flowchart LR
    A["Synthetic input + metadata"] --> B{"Contract valid?"}
    B -->|No| C["Reject or route with reason"]
    B -->|Yes| D["Apply Resampling, Aggregation, and Time Alignment"]
    D --> E["Formula: bucket statistic=aggregate{xₜ:t in declared interval}"]
    E --> F["Verified fixture output"]
    F --> G{"Interpretation within boundary?"}
    G -->|Yes| H["Report value + convention + audit"]
    G -->|No| I["Add companion view or narrower claim"]

How it works#

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References#

• Time Series Plot — NIST/SEMATECH e-Handbook
• Common Pitfalls and Recommended Practices — scikit-learn
• Historical-example decision

The rest of the Financial Time-Series Foundations family#

• Time Order, Frequency, Regularity, and Financial CalendarsChecks whether a timestamped series runs in chronological order and whether its observations are evenly spaced, reporting the c…
• Levels, Changes, Differences, and ReturnsConverts a level series into its period-over-period differences and its simple returns, keeping the original levels alongside t…
• Lags, Leads, and Temporal DependencePairs every observation with the value lag positions behind it, and exposes the same series shifted forward as the lead.
• Rolling and Expanding WindowsComputes a fixed-length rolling mean of the series next to its expanding mean, so a window that forgets can be compared with on…
• Trend, Seasonality, Cycles, and RemainderSeparates a series into a rolling-mean trend, a seasonal difference taken period steps back, and the remainder left once the …
• Autocovariance and AutocorrelationMeasures how far a series moves with its own past at a given lag, using the population convention that divides by the full obse…
• Stationarity and Differencing IntuitionCompares the average level of the second half of a series with the first half, and reports the first differences, as a rough re…
• Smoothing, Baselines, and Naive ForecastsRuns simple exponential smoothing over the series and reports both the naive last-value forecast and the smoothed one.
• Look-Ahead Leakage and Time-Aware Data SplitsSplits a timestamped series at a given position and reports whether the training block reaches into the testing block's time ra…