preprocessing.linearly_interpolate_ts

preprocessing.linearly_interpolate_ts

Linear interpolation transformer for time series data.

Classes

Name	Description
LinearlyInterpolateTS	Transformer that applies linear interpolation to time series data.

LinearlyInterpolateTS

preprocessing.linearly_interpolate_ts.LinearlyInterpolateTS(on_missing='raise')

Transformer that applies linear interpolation to time series data.

The transformer always runs y.interpolate(method="linear") first. The on_missing keyword then chooses how to handle any NaN that linear interpolation cannot bridge (typically the leading and trailing endpoints of the series).

Parameters

Name	Type	Description	Default
on_missing	OnMissing	Contract for residual NaN after linear interpolation. - "raise" (default, fail-safe): raise ValueError if any NaN remains. Refuses to silently embed imputed values disguised as measurements. - "ffill_bfill": explicit opt-in to endpoint forward-then-backward fill, so that leading and trailing NaNs are both bridged. - "passthrough": return the linearly interpolated series unchanged. The caller promises to handle the residual NaN downstream.	'raise'

Raises

Name	Type	Description
	ValueError	If on_missing is not one of the three accepted values, or if on_missing="raise" (the default) and any NaN remains after linear interpolation.

Examples

import numpy as np
import pandas as pd
from spotforecast2_safe.preprocessing.linearly_interpolate_ts import LinearlyInterpolateTS

# Interior gaps are bridged by linear interpolation under every
# mode; the default "raise" then succeeds because nothing remains.
s = pd.Series([1.0, np.nan, 3.0])
result = LinearlyInterpolateTS().fit_transform(s)
print(result.tolist())
assert result.tolist() == [1.0, 2.0, 3.0]

[1.0, 2.0, 3.0]

import numpy as np
import pandas as pd
from spotforecast2_safe.preprocessing.linearly_interpolate_ts import LinearlyInterpolateTS

# Endpoint NaNs are bridged only when the caller opts in explicitly.
s = pd.Series([1.0, np.nan, 3.0, np.nan])
result = LinearlyInterpolateTS(on_missing="ffill_bfill").fit_transform(s)
print(result.tolist())
assert result.tolist() == [1.0, 2.0, 3.0, 3.0]

[1.0, 2.0, 3.0, 3.0]

import numpy as np
import pandas as pd
from spotforecast2_safe.preprocessing.linearly_interpolate_ts import LinearlyInterpolateTS

# "passthrough" lets the residual NaN survive for the caller to handle.
s = pd.Series([1.0, np.nan, 3.0, np.nan])
out = LinearlyInterpolateTS(on_missing="passthrough").fit_transform(s)
print(out.isna().tolist())
assert bool(out.isna().iloc[-1]) is True

[False, False, False, True]

Methods

Name	Description
apply	Apply linear interpolation and dispatch on on_missing.
fit	Fit the transformer (no-op; satisfies the sklearn fit contract).
transform	Transform the input data by applying linear interpolation.

apply

preprocessing.linearly_interpolate_ts.LinearlyInterpolateTS.apply(y)

Apply linear interpolation and dispatch on on_missing.

Parameters

Name	Type	Description	Default
y	Union[pd.Series, pd.DataFrame]	Input Series or DataFrame.	required

Returns

Name	Type	Description
	Union[pd.Series, pd.DataFrame]	Union[pd.Series, pd.DataFrame]: The transformed data. For
	Union[pd.Series, pd.DataFrame]	on_missing="ffill_bfill" any residual endpoint NaN has
	Union[pd.Series, pd.DataFrame]	been forward- and back-filled; for "passthrough" it
	Union[pd.Series, pd.DataFrame]	survives; for "raise" (the default) the method raises
	Union[pd.Series, pd.DataFrame]	instead of returning a NaN-bearing result.

Raises

Name	Type	Description
	ValueError	If self.on_missing is not a recognized value, or if self.on_missing == "raise" and any NaN remains after linear interpolation.

Examples

import numpy as np
import pandas as pd
from spotforecast2_safe.preprocessing.linearly_interpolate_ts import LinearlyInterpolateTS

# Small hourly DataFrame with a deliberately-placed interior NaN.
idx = pd.date_range("2024-01-01", periods=6, freq="h")
df = pd.DataFrame({"load_mw": [100.0, 110.0, 120.0, 130.0, 140.0, 150.0]}, index=idx)
df.iloc[2, 0] = np.nan

transformer = LinearlyInterpolateTS()
result = transformer.apply(df)
print(result)
assert result["load_mw"].iloc[2] == 120.0
assert not result.isna().any().any()

                     load_mw
2024-01-01 00:00:00    100.0
2024-01-01 01:00:00    110.0
2024-01-01 02:00:00    120.0
2024-01-01 03:00:00    130.0
2024-01-01 04:00:00    140.0
2024-01-01 05:00:00    150.0

fit

preprocessing.linearly_interpolate_ts.LinearlyInterpolateTS.fit(X, y=None)

Fit the transformer (no-op; satisfies the sklearn fit contract).

Parameters

Name	Type	Description	Default
X	Any	Input data (ignored — this transformer is stateless).	required
y	Any	Ignored.	None

Returns

Name	Type	Description
LinearlyInterpolateTS	LinearlyInterpolateTS	The fitted transformer (self).

Examples

import numpy as np
import pandas as pd
from spotforecast2_safe.preprocessing.linearly_interpolate_ts import LinearlyInterpolateTS

idx = pd.date_range("2024-01-01", periods=4, freq="h")
df = pd.DataFrame({"load_mw": [100.0, np.nan, 120.0, 130.0]}, index=idx)

interp = LinearlyInterpolateTS()
result = interp.fit(df)
assert result is interp, "fit() must return self"
print(f"fit() returned self: {result is interp}")

fit() returned self: True

transform

preprocessing.linearly_interpolate_ts.LinearlyInterpolateTS.transform(X)

Transform the input data by applying linear interpolation.

Delegates to LinearlyInterpolateTS.apply() after the sklearn fit → transform contract is satisfied by fit().

Parameters

Name	Type	Description	Default
X	Union[pd.Series, pd.DataFrame]	Input Series or DataFrame to interpolate.	required

Returns

Name	Type	Description
	Union[pd.Series, pd.DataFrame]	Union[pd.Series, pd.DataFrame]: Interpolated data, with
	Union[pd.Series, pd.DataFrame]	residual NaN handled according to self.on_missing.

Examples

import numpy as np
import pandas as pd
from spotforecast2_safe.preprocessing.linearly_interpolate_ts import LinearlyInterpolateTS

# Fit-then-transform mirrors the canonical sklearn workflow.
idx = pd.date_range("2024-01-01", periods=4, freq="h")
df = pd.DataFrame({"load_mw": [100.0, np.nan, 120.0, 130.0]}, index=idx)

interp = LinearlyInterpolateTS()
interp.fit(df)
df_out = interp.transform(df)
print(df_out)
assert df_out["load_mw"].iloc[1] == 110.0, "interior NaN must be filled"
assert not df_out.isna().any().any(), "no NaN must remain"

                     load_mw
2024-01-01 00:00:00    100.0
2024-01-01 01:00:00    110.0
2024-01-01 02:00:00    120.0
2024-01-01 03:00:00    130.0