Skip to content

"Vibe-Trading: Your Personal Trading Agent"

20.0 KB
Raw Blame
"""Statistical invariants, timing boundaries and tool contract for factor transforms."""

from __future__ import annotations

import json

import numpy as np
import pandas as pd
import pytest

from src.quantlib.neutralization import neutralize_factor, pca_factors
from src.tools.quantlib_tool import QuantlibCallTool


def panel(values, times=None):
    values = np.atleast_2d(values).astype(float)
    if times is None:
        times = pd.date_range("2024-01-01", periods=len(values), freq="D")
    return pd.DataFrame(
        values, index=times, columns=[f"s{i}" for i in range(values.shape[1])]
    )


def sample(n_rows=3, times=None):
    rng = np.random.default_rng(20)
    x = panel(rng.normal(size=(n_rows, 20)), times)
    other = panel(rng.normal(size=(n_rows, 20)), times)
    noise = panel(rng.normal(size=(n_rows, 20)), times)
    return 3 + 2 * x - other + noise, {"size": x, "momentum": other}


def test_ols_matches_independent_least_squares_and_preserves_inputs():
    signal, controls = sample()
    original = signal.copy(deep=True)
    result = neutralize_factor(signal, controls, standardize=False)
    for row in range(len(signal)):
        x = np.column_stack(
            [np.ones(20), *[value.iloc[row].to_numpy() for value in controls.values()]]
        )
        y = signal.iloc[row].to_numpy()
        expected = y - x @ np.linalg.lstsq(x, y, rcond=None)[0]
        np.testing.assert_allclose(result.residuals.iloc[row], expected, atol=1e-12)
        np.testing.assert_allclose(x.T @ result.residuals.iloc[row], 0, atol=1e-12)
        assert (
            max(
                abs(value)
                for value in result.diagnostics[row]["exposure_after"].values()
            )
            < 1e-12
        )
    pd.testing.assert_frame_equal(signal, original)


def test_wls_matches_reference_and_standardization_preserves_weighted_orthogonality():
    signal, controls = sample()
    weights = panel(np.tile(np.arange(1, 21), (3, 1)))
    result = neutralize_factor(signal, controls, method="wls", weights=weights)
    for row in range(len(signal)):
        x = np.column_stack(
            [np.ones(20), *[value.iloc[row].to_numpy() for value in controls.values()]]
        )
        y = signal.iloc[row].to_numpy()
        w = weights.iloc[row].to_numpy()
        beta = np.linalg.lstsq(x * np.sqrt(w)[:, None], y * np.sqrt(w), rcond=None)[0]
        expected = y - x @ beta
        expected /= np.sqrt(np.average(expected**2, weights=w))
        np.testing.assert_allclose(result.residuals.iloc[row], expected, atol=1e-12)
        np.testing.assert_allclose(
            x.T @ (w * result.residuals.iloc[row]), 0, atol=1e-10
        )
        assert (
            max(
                abs(value)
                for value in result.diagnostics[row]["exposure_after"].values()
            )
            < 1e-12
        )
    equal = neutralize_factor(signal, controls, method="wls", weights=weights * 0 + 1)
    pd.testing.assert_frame_equal(
        equal.residuals, neutralize_factor(signal, controls).residuals
    )


def test_industry_dummies_remove_group_means_and_preserve_missing_labels():
    signal = panel([2, 4, 10, 14, 3, 7, 11, 15, 6, 8, 20, 22])
    industry = pd.DataFrame(
        [["A", "A", "B", "B"] * 3], index=signal.index, columns=signal.columns
    )
    industry.iloc[0, -1] = None
    result = neutralize_factor(
        signal, categorical_controls={"industry": industry}, standardize=False
    )
    for tag in ("A", "B"):
        assert result.residuals.iloc[0][
            industry.iloc[0] == tag
        ].mean() == pytest.approx(0, abs=1e-12)
    assert pd.isna(result.residuals.iloc[0, -1])
    assert result.diagnostics[0]["fit_count"] == 11


def test_auto_selection_reports_low_coverage_constants_and_collinearity():
    signal, controls = sample()
    sparse = controls["size"].copy()
    sparse.iloc[:, :10] = np.nan
    candidates = {
        "size": controls["size"],
        "size_copy": controls["size"] * 4 + 10,
        "constant": controls["size"] * 0 + 1,
        "sparse": sparse,
        "momentum": controls["momentum"],
    }
    result = neutralize_factor(signal, candidates, control_selection="auto")
    for detail in result.diagnostics:
        assert detail["selected_controls"] == ["size", "momentum"]
        assert detail["dropped_controls"] == {
            "size_copy": "constant_or_collinear",
            "constant": "constant_or_collinear",
            "sparse": "low_coverage",
        }
    pd.testing.assert_frame_equal(
        result.residuals, neutralize_factor(signal, controls).residuals
    )


def test_categorical_reference_uses_fitted_assets_not_masked_or_missing_assets():
    signal, controls = sample(n_rows=1)
    industry = pd.DataFrame(
        [["A"] + ["B", "C"] * 9 + ["B"]], index=signal.index, columns=signal.columns
    )
    mask = pd.DataFrame(True, index=signal.index, columns=signal.columns)
    mask.iloc[0, 0] = False
    masked = neutralize_factor(
        signal, categorical_controls={"industry": industry}, mask=mask
    )
    assert masked.diagnostics[0]["status"] == "ok"
    controls["size"].iloc[0, 0] = np.nan
    missing = neutralize_factor(
        signal, controls, categorical_controls={"industry": industry}
    )
    assert missing.diagnostics[0]["status"] == "ok"
    assert missing.diagnostics[0]["fit_count"] == 19
    auto = neutralize_factor(
        signal,
        controls,
        categorical_controls={"industry": industry},
        control_selection="auto",
    )
    assert auto.diagnostics[0]["selected_controls"] == ["size", "momentum", "industry"]
    pd.testing.assert_frame_equal(auto.residuals, missing.residuals)


def test_encoded_control_name_collisions_are_rejected():
    signal, controls = sample(n_rows=1)
    industry = pd.DataFrame(
        [["A", "B"] * 10], index=signal.index, columns=signal.columns
    )
    with pytest.raises(ValueError, match="names collide"):
        neutralize_factor(
            signal,
            {"industry=B": controls["size"]},
            categorical_controls={"industry": industry},
        )


def test_auto_checks_joint_coverage_and_skipped_output_coverage_is_zero():
    signal, controls = sample(n_rows=1)
    controls["size"].iloc[0, :4] = np.nan
    controls["momentum"].iloc[0, 4:8] = np.nan
    result = neutralize_factor(
        signal, controls, control_selection="auto", min_observations=14
    )
    detail = result.diagnostics[0]
    assert detail["selected_controls"] == ["size"]
    assert detail["fit_count"] == 16
    assert detail["coverage"] == pytest.approx(0.8)
    assert (
        detail["dropped_controls"]["momentum"] == "insufficient_sample_or_residual_dof"
    )
    skipped = neutralize_factor(signal, controls, min_observations=20)
    assert skipped.diagnostics[0]["coverage"] == 0
    assert skipped.diagnostics[0]["fit_count"] == 0


def test_auto_selection_respects_residual_dof_and_does_not_fallback_to_demeaning():
    signal, controls = sample()
    result = neutralize_factor(
        signal, controls, control_selection="auto", min_residual_dof=18
    )
    assert result.diagnostics[0]["selected_controls"] == ["size"]
    assert (
        result.diagnostics[0]["dropped_controls"]["momentum"]
        == "insufficient_sample_or_residual_dof"
    )
    empty = neutralize_factor(
        signal, {"constant": signal * 0 + 1}, control_selection="auto"
    )
    assert empty.residuals.isna().all().all()
    assert all(detail["reason"] == "no_usable_controls" for detail in empty.diagnostics)


def test_alignment_mask_and_wls_weight_exclusions_are_explicit():
    signal, controls = sample()
    aligned = {name: value.iloc[::-1, ::-1] for name, value in controls.items()}
    pd.testing.assert_frame_equal(
        neutralize_factor(signal, controls).residuals,
        neutralize_factor(signal, aligned).residuals,
    )
    weights = signal * 0 + 1
    weights.iloc[0, :4] = [0, -1, np.nan, np.inf]
    mask = pd.DataFrame(True, index=signal.index, columns=signal.columns)
    mask.iloc[0, 4] = False
    signal.iloc[0, 5] = np.nan
    controls["size"].iloc[0, 6] = np.nan
    result = neutralize_factor(
        signal, controls, method="wls", weights=weights, mask=mask
    )
    assert result.residuals.iloc[0, :7].isna().all()
    assert result.diagnostics[0]["excluded_weight_count"] == 4
    assert result.diagnostics[0]["fit_count"] == 13
    pd.testing.assert_index_equal(result.residuals.index, signal.index)
    pd.testing.assert_index_equal(result.residuals.columns, signal.columns)


@pytest.mark.parametrize("frequency", ["min", "h", "D", "W", "MS"])
def test_frequency_independence_and_no_future_row_influence(frequency):
    times = pd.date_range("2024-01-01", periods=3, freq=frequency, tz="UTC")
    signal, controls = sample(times=times)
    result = neutralize_factor(signal, controls, control_selection="auto")
    pca = pca_factors(controls, n_components=2)
    signal.iloc[1:] *= -1000
    for frame in controls.values():
        frame.iloc[1:] *= 42
    updated = neutralize_factor(signal, controls, control_selection="auto")
    updated_pca = pca_factors(controls, n_components=2)
    pd.testing.assert_series_equal(result.residuals.iloc[0], updated.residuals.iloc[0])
    assert result.diagnostics[0] == updated.diagnostics[0]
    for name in pca.components:
        pd.testing.assert_series_equal(
            pca.components[name].iloc[0], updated_pca.components[name].iloc[0]
        )
    assert pca.diagnostics[0] == updated_pca.diagnostics[0]


def test_irregular_times_are_not_sorted_or_resampled_and_missing_dates_are_not_filled():
    times = pd.to_datetime(["2024-02-01 10:01", "2024-01-04 09:32", "2024-02-01 10:08"])
    signal, controls = sample(times=times)
    controls["size"] = controls["size"].iloc[:2]
    result = neutralize_factor(signal, controls)
    pd.testing.assert_index_equal(result.residuals.index, times)
    assert result.residuals.iloc[2].isna().all()
    assert result.diagnostics[2]["reason"] == "insufficient_sample"


def test_explicit_collinearity_is_skipped_and_exactly_explained_signal_stays_zero():
    signal, controls = sample()
    bad = neutralize_factor(signal, {"x": controls["size"], "copy": controls["size"]})
    assert bad.residuals.isna().all().all()
    assert all(detail["reason"] == "rank_deficient" for detail in bad.diagnostics)
    perfect = neutralize_factor(controls["size"] * 2 + 3, {"size": controls["size"]})
    np.testing.assert_array_equal(perfect.residuals, 0)
    assert all(detail["zero_residual"] for detail in perfect.diagnostics)


def test_tiny_signal_is_not_mistaken_for_zero_residual():
    signal, controls = sample()
    expected = neutralize_factor(signal, controls)
    actual = neutralize_factor(signal * 1e-15, controls)
    np.testing.assert_allclose(actual.residuals, expected.residuals, atol=1e-12)


def test_pca_components_are_uncorrelated_and_full_components_reconstruct_inputs():
    _, factors = sample()
    result = pca_factors(factors, n_components=2)
    for row, detail in enumerate(result.diagnostics):
        scores = np.column_stack(
            [frame.iloc[row].to_numpy() for frame in result.components.values()]
        )
        covariance = np.cov(scores.T)
        assert covariance[0, 1] == pytest.approx(0, abs=1e-12)
        loadings = np.array(
            [list(detail["loadings"][name].values()) for name in result.components]
        )
        x = np.column_stack([frame.iloc[row].to_numpy() for frame in factors.values()])
        expected = (x - x.mean(axis=0)) / x.std(axis=0)
        np.testing.assert_allclose(scores @ loadings, expected, atol=1e-12)
        assert sum(detail["explained_variance_ratio"]) == pytest.approx(1)
        for loading in loadings:
            anchors = np.flatnonzero(
                np.isclose(
                    np.abs(loading),
                    np.abs(loading).max(),
                    rtol=32 * np.finfo(float).eps,
                    atol=0,
                )
            )
            assert loading[anchors[0]] >= 0


def test_pca_variance_fraction_handles_variable_component_counts_and_missing_assets():
    _, factors = sample()
    factors["momentum"].iloc[0] = factors["size"].iloc[0] * 2
    factors["momentum"].iloc[2, 0] = np.nan
    result = pca_factors(factors, n_components=0.95)
    assert result.diagnostics[0]["n_components"] == 1
    assert result.diagnostics[1]["n_components"] == 2
    assert result.components["PC2"].iloc[0].isna().all()
    assert pd.isna(result.components["PC1"].iloc[2, 0])
    assert all(detail["retained_variance"] >= 0.95 for detail in result.diagnostics)


def test_pca_constant_and_insufficient_rank_observations_are_skipped():
    _, factors = sample()
    constant = pca_factors({"x": factors["size"], "constant": factors["size"] * 0 + 1})
    assert not constant.components
    assert all(detail["reason"] == "constant_factor" for detail in constant.diagnostics)
    rank_one = pca_factors(
        {"x": factors["size"], "copy": factors["size"]}, n_components=2
    )
    assert not rank_one.components
    assert all(
        detail["reason"] == "insufficient_rank" for detail in rank_one.diagnostics
    )
    short = pca_factors({name: frame.iloc[:, :3] for name, frame in factors.items()})
    assert all(
        detail["reason"] == "insufficient_sample" for detail in short.diagnostics
    )


@pytest.mark.parametrize(
    "kwargs",
    [
        {"method": "unknown"},
        {"control_selection": "best_ic"},
        {"method": "wls"},
        {"min_coverage": 0},
        {"min_coverage": np.nan},
        {"min_observations": True},
        {"min_residual_dof": 0},
        {"rcond": 0},
        {"standardize": "yes"},
    ],
)
def test_invalid_residualization_settings_are_rejected(kwargs):
    signal, controls = sample()
    with pytest.raises(ValueError):
        neutralize_factor(signal, controls, **kwargs)


def test_invalid_panels_masks_and_weight_method_combinations_are_rejected():
    signal, controls = sample()
    with pytest.raises(ValueError, match="at least one"):
        neutralize_factor(signal)
    with pytest.raises(ValueError, match="unique"):
        neutralize_factor(pd.concat([signal, signal]), controls)
    with pytest.raises(ValueError, match="boolean"):
        neutralize_factor(signal, controls, mask=signal * 0 + 2)
    with pytest.raises(ValueError, match="weights require"):
        neutralize_factor(signal, controls, weights=signal * 0 + 1)
    with pytest.raises(ValueError, match="distinct"):
        neutralize_factor(signal, controls, categorical_controls=controls)


@pytest.mark.parametrize("count", [0, -1, True, 1.0, 1.1, np.nan, 3])
def test_invalid_pca_component_counts_are_rejected(count):
    _, factors = sample()
    with pytest.raises(ValueError):
        pca_factors(factors, n_components=count)


def envelope(frame):
    return {
        "__dataframe__": {
            "index": [str(time) for time in frame.index],
            "columns": list(frame.columns),
            "data": frame.to_numpy().tolist(),
        }
    }


def test_quantlib_tool_lists_calls_and_serializes_both_transforms():
    tool = QuantlibCallTool()
    listing = json.loads(tool.execute(action="list", module="neutralization"))
    assert {item["name"] for item in listing["functions"]} == {
        "neutralize_factor",
        "pca_factors",
    }
    signal, controls = sample(n_rows=1)
    encoded = {name: envelope(frame) for name, frame in controls.items()}
    residual = json.loads(
        tool.execute(
            action="call",
            module="neutralization",
            function="neutralize_factor",
            kwargs={"factor": envelope(signal), "controls": encoded},
        )
    )
    assert residual["ok"]
    assert residual["result"]["diagnostics"][0]["status"] == "ok"
    assert "__dataframe__" in residual["result"]["residuals"]
    pca = json.loads(
        tool.execute(
            action="call",
            module="neutralization",
            function="pca_factors",
            kwargs={"factors": encoded, "n_components": 2},
        )
    )
    assert pca["ok"]
    assert set(pca["result"]["components"]) == {"PC1", "PC2"}
    error = json.loads(
        tool.execute(
            action="call",
            module="neutralization",
            function="neutralize_factor",
            kwargs={"factor": envelope(signal), "controls": encoded, "method": "wls"},
        )
    )
    assert not error["ok"]
    assert "requires weights" in error["error"]


@pytest.mark.parametrize("units", [1e-200, 1e200])
@pytest.mark.parametrize("method", ["ols", "wls"])
def test_residualization_is_stable_under_finite_unit_changes(units, method):
    signal, controls = sample(n_rows=1)
    kwargs = {"method": method}
    if method == "wls":
        kwargs["weights"] = panel([np.arange(1, 21)])
    reference = neutralize_factor(signal, controls, **kwargs)
    changed = {name: value * units for name, value in controls.items()}
    actual = neutralize_factor(signal * units, changed, **kwargs)
    assert actual.diagnostics[0]["status"] == "ok"
    np.testing.assert_allclose(actual.residuals, reference.residuals, atol=1e-12)
    raw = neutralize_factor(signal * units, changed, standardize=False, **kwargs)
    expected = neutralize_factor(signal, controls, standardize=False, **kwargs)
    np.testing.assert_allclose(raw.residuals / units, expected.residuals, atol=1e-12)
    assert all(
        np.isfinite(v) for v in actual.diagnostics[0]["exposure_before"].values()
    )


@pytest.mark.parametrize("units", [1e-200, 1e200])
@pytest.mark.parametrize("standardize", [False, True])
def test_pca_preserves_variance_and_reconstruction_across_units(units, standardize):
    _, factors = sample(n_rows=1)
    reference = pca_factors(factors, n_components=2, standardize=standardize)
    changed = {name: value * units for name, value in factors.items()}
    actual = pca_factors(changed, n_components=2, standardize=standardize)
    detail = actual.diagnostics[0]
    assert detail["status"] == "ok"
    np.testing.assert_allclose(
        detail["explained_variance_ratio"],
        reference.diagnostics[0]["explained_variance_ratio"],
        atol=1e-12,
    )
    for name, scores in actual.components.items():
        np.testing.assert_allclose(
            scores / (1 if standardize else units),
            reference.components[name],
            atol=1e-12,
        )
    scores = np.column_stack([frame.iloc[0] for frame in actual.components.values()])
    loadings = np.array([list(v.values()) for v in detail["loadings"].values()])
    scales = np.array(list(detail["scales"].values()))
    means = np.array(list(detail["means"].values()))
    # Normalize before comparing to avoid an absolute tolerance hiding tiny output.
    reconstructed = (scores @ loadings) * (scales / units) + means / units
    original = np.column_stack([frame.iloc[0] for frame in factors.values()])
    np.testing.assert_allclose(reconstructed, original, atol=1e-12)


@pytest.mark.parametrize("units", [1e-200, 1e200])
def test_signal_units_alone_never_turn_real_residuals_into_zero(units):
    signal, controls = sample(n_rows=1)
    reference = neutralize_factor(signal, controls)
    result = neutralize_factor(signal * units, controls)
    assert not result.diagnostics[0]["zero_residual"]
    np.testing.assert_allclose(result.residuals, reference.residuals, atol=1e-12)


def test_raw_pca_preserves_relative_factor_units_against_independent_svd():
    _, factors = sample(n_rows=1)
    factors["momentum"] *= 100
    x = np.column_stack([frame.iloc[0] for frame in factors.values()])
    centered = x - x.mean(axis=0)
    _, singular, vt = np.linalg.svd(centered, full_matrices=False)
    result = pca_factors(factors, n_components=2, standardize=False)
    detail = result.diagnostics[0]
    np.testing.assert_allclose(
        detail["explained_variance_ratio"], singular**2 / (singular**2).sum()
    )
    actual = np.array([list(v.values()) for v in detail["loadings"].values()])
    np.testing.assert_allclose(np.abs(actual), np.abs(vt), atol=1e-12)


def test_unrepresentable_raw_pca_scores_skip_instead_of_successful_infinities():
    factor = panel([1e308, -1e308] * 6)
    result = pca_factors(
        {"a": factor, "b": factor, "c": factor, "d": factor},
        n_components=1,
        standardize=False,
    )
    assert result.components == {}
    assert result.diagnostics[0]["reason"] == "nonfinite_result"
    assert result.diagnostics[0]["fit_count"] == 0