Source code for numeraire_dataset.zones.view

"""View zone: turn a clean table into a numeraire point-in-time view (lazy numeraire import).

Adds no persisted state — it is the thin bridge from a tidy ``clean`` table to a numeraire
``CrossSectionView`` / ``TimeSeriesView``. ``numeraire`` is imported lazily so the raw + clean
zones stay installable without it.
"""

from __future__ import annotations

from typing import TYPE_CHECKING, Any

import pandas as pd

from numeraire_dataset._compat import return_type_kwargs

if TYPE_CHECKING:
    from numeraire.core.data import CrossSectionView




def to_cross_section_view(
    clean: pd.DataFrame,
    *,
    chars: list[str],
    date_col: str = "date",
    asset_col: str = "permno",
    ret: str = "ret",
    horizon: int = 1,
    return_type: str = "simple",
) -> CrossSectionView:
    """Build a numeraire :class:`CrossSectionView` from a tidy clean panel (lazy numeraire import).

    Pass the ``DataLock.data_vintage(name)`` string to the engine (``backtest_weights(...,
    data_vintage=...)``) so a downstream result carries that provenance stamp. The view also exposes
    a ``provenance`` mapping of its own, but this bridge adds no persisted state to it.

    ``return_type`` declares the algebra of the ``ret`` column to numeraire (``"simple"`` by
    default, or ``"log"`` when the panel carries a ``source_log_return``-style column). It is
    forwarded only when non-simple and requires ``numeraire >= 0.3``; on an older numeraire a
    non-simple value raises rather than silently mixing log and simple return algebra.
    """
    from numeraire.core.data import CrossSectionView

    kwargs: dict[str, Any] = {
        "chars": chars,
        "date_col": date_col,
        "asset_col": asset_col,
        "ret": ret,
        "horizon": horizon,
    }
    kwargs.update(return_type_kwargs(CrossSectionView, return_type))
    return CrossSectionView(clean, **kwargs)