RainbowStats™ · Command reference

SAME_DATE_RANGE — Align Observations

Align overlapping series to a common date grid, interpolating where needed.

SAME_DATE_RANGE accepts individual series, data-series lists, or a mixture. It collects the inputs, trims their overlapping history, selects a reference series using getLowestFrequency(), and interpolates the members onto that reference series’ observation dates. It returns a data list whose observation timestamps match exactly.

Quick start: align overlapping monthly samples

u = SERIES_BETWEEN(UNRATE,20240101,20240601)
v = SERIES_BETWEEN(U6RATE,20240301,20240801)
aligned = SAME_DATE_RANGE(u,v)
LINE_CHART(aligned)

Run this example in RainbowStats

The first series spans January–June and the second March–August 2024. The tested aligned result contains March, April, May and June: four observations per series.

Syntax, aliases and return type

SAME_DATE_RANGE(series1,series2,...)
SAME_DATE_RANGE(seriesList)
SAME_DATE_RANGE(series1,seriesList,...)
SAME_DATE_RANGE(series)

Input	Behavior
Individual series	Collects the series into a list and aligns them.
One list	Aligns the members of the list.
A mixture of series and lists	Flattens the supplied lists alongside individual series, then aligns the collected inputs.
One individual series	Accepted in the variadic route. Returns a one-member list rather than a standalone series.
Return type	Always a `DataListOperator`, suitable for list-based charts and models.
Aliases	`SAME_RANGE` and `COMMON_RANGE` map to this command.

The command does not take numeric start and end parameters. Select a date interval with SERIES_BETWEEN or a starting cutoff with SERIES_SINCE before or after alignment as appropriate.

Reference dates, interpolation and frequency labels

Find the overlap. Use the latest input starting date and the earliest input ending date. No overlap produces an empty list.
Trim each series. Retain its observations within that common calendar interval.
Select the reference. The helper calls getLowestFrequency() on the trimmed list and uses that series’ actual date array as the reference grid. This is not a newly generated regular calendar.
Interpolate to the reference grid. For each series, exact timestamp matches retain their observed values; dates between observations use linear interpolation weighted by elapsed milliseconds.
Verify exact alignment. The outer wrapper checks identical timestamps and counts, retries up to three alignment passes, and returns an empty list if alignment still fails.

Output frequency follows the reference. After interpolating onto the reference date grid, the corrected helper assigns reference.getFrequency() to every output member. A daily series aligned to a monthly reference therefore reports “Monthly,” matching the selected grid.

The frequency label describes the reference grid’s nominal frequency. Gaps or irregular dates in that reference can still leave irregular spacing in the aligned output.

A daily/monthly example

daily = SERIES_BETWEEN(DGS10,20240101,20240601)
monthly = SERIES_BETWEEN(UNRATE,20240101,20240601)
aligned = SAME_DATE_RANGE(daily,monthly)
aligned

In the checked live result, both members contained February 1, March 1, April 1 and May 1, 2024. The trimmed monthly reference supplied those dates. Treasury values on those dates were exact observed values; in another sample, an absent reference-date observation could be interpolated. This example does not establish an exact-date intersection rule.

The production test after the correction reports both members as “Monthly.” The Treasury values are sampled or interpolated values at reference dates, not monthly average Treasury yields.

Interpolation and aggregation answer different questions. Use AGGREGATE_TO_PERIOD for a defined sum, average, first, last, minimum or maximum within calendar periods. SAME_DATE_RANGE uses an observation-date grid and interpolation; it does not perform those within-period aggregation calculations.

The interpolation wrapper considers requested dates only within each trimmed series’ bounds and omits calculated NaN values. Such omissions can prevent exact alignment and cause further passes or an empty final result. It does not guarantee a regular or gap-free calendar.

Examples: lists, mixed inputs and extraction

Align a list for regression

sample = SERIES_BETWEEN(LIST(UNRATE,U6RATE,TCU),20010101,20191231)
aligned = SAME_DATE_RANGE(sample)
r = REGRESSION(aligned)
EXTRACT(r,"slideshow")

Mix a series and a list

u = SERIES_BETWEEN(UNRATE,20240101,20240601)
others = LIST(SERIES_BETWEEN(U6RATE,20240301,20240801),SERIES_BETWEEN(TCU,20240201,20240501))
aligned = SAME_DATE_RANGE(u,others)
aligned

The tested result contains three observations per series, dated March 1 through May 1, 2024. Every added input can change the overlap, reference selection or final sample.

Retrieve an aligned member

aligned = SAME_DATE_RANGE(SERIES_BETWEEN(UNRATE,20240101,20240601),SERIES_BETWEEN(U6RATE,20240301,20240801))
u = EXTRACT(aligned,"series:0")
v = EXTRACT(aligned,"series:1")
LINE_CHART(u,v)

The data-list series:N extract uses zero-based member positions. The extracted member is a single series. Keep input codes distinct when assembling a comparison; do not assume duplicate series identities are retained as separate members.

Prepare the sample deliberately

Command	Purpose	Return type
`SERIES_SINCE(data,start)`	Retain observations from a selected starting cutoff through the available end of the input.	Series for a series input; list for a list input.
`SERIES_BETWEEN(data,start,end)`	Retain observations within an explicit date interval.	Series for a series input; list for a list input.
`SAME_DATE_RANGE(data,...)`	Align overlapping series to a reference observation-date grid, interpolating where needed.	Always a data-series list, including for a single series input.

Choose the economic frequency and aggregation rules.
Select the desired historical window.
Apply transformations such as differences or lags with sufficient preceding history.
Align the series that will enter the comparison or model.
Inspect dates, spacing, interpolated values, frequency labels and observation counts before interpreting results.

Some models already call the underlying alignment routine. Calling it explicitly can make the intended sample visible, but alignment alone does not establish statistical suitability, stationarity or causal identification.

Working with the data

Inspect the reference grid. Many inputs or sparse series can change overlap and coverage. Interpolated values can appear even when no original observation existed on a reference date.
Check interior gaps. Matching timestamps do not mean regular elapsed-time intervals. Interpolation across a long source gap deserves particular attention.
Inspect missing values. The date-array interpolation method omits calculated NaN values. It does not explicitly reject every other nonfinite numeric value. Check the final data and downstream cleaning rules.
Preserve variable roles. In a regression list, the first retained member defines the dependent variable. Verify the members and their ordering after preparing the sample.
Keep compatible economic definitions. A shared date label does not mean two source measurements describe identical periods or were published at the same time.
Inspect empty results before modeling. No overlapping range, an empty reference or failure to achieve identical timestamps within three passes can leave an empty list.