quantlab-factor-agent 0.1.0__py3-none-any.whl

factor_agent/scoring.py

@@ -0,0 +1,143 @@
+"""Scoring: how a factor's raw values become the values that are judged.
+
+One setting, shared by the Evaluator and Acceptance, so what is admitted is
+what is validated and exported. A factor is
+
+1. ranked across the whole market each day: the graph factors rank their own
+   outputs (``exported.ranked_function``), so the rank is in the compiled
+   graph and an exported factor computes it;
+2. neutralised, when the config asks for it, against the industry code and
+   the logarithm of the market cap of the configured exposures and z-scored
+   (quantlab's ``NeutralizedFactor``), or left as ranked;
+3. kept on the members of each day t (``IndexConstituentDataset.mask``), or
+   on every symbol when there is no membership.
+
+Steps 1 and 2 give the whole-market values a store holds (``apply``);
+step 3 is how they, and any stored reference or baseline factor, are read
+(``on_members``, ``read``, ``mask``). ``read`` takes a reference or known
+factor given as a component through steps 2 and 3, and one given as a
+store through step 3 alone. A stored factor is read from its store's first
+bar on: it has no value, so no score, before.
+"""
+
+from collections.abc import Iterator
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Any
+
+import xarray as xr
+from quantlab.factor.config import (
+    MembershipMaskedFactorConfig, NeutralizedConfig, RosterConfig, StartClippedConfig,
+)
+from quantlab.factor.predefined.membership_mask import MembershipMaskedFactor
+from quantlab.factor.predefined.neutralized import NeutralizedFactor
+from quantlab.factor.predefined.roster import RosterFactor
+from quantlab.factor.predefined.start_clipped import StartClippedFactor
+
+from factor_agent.config import DataConfig, ScoringConfig, load_each
+
+
+@dataclass(frozen=True)
+class Neutralization:
+    """What a ranked factor is neutralised against.
+
+    ``exposures`` is the dataset, or list of datasets, holding
+    ``size_column`` (the market cap, whose logarithm is regressed on) and
+    ``industry_column`` (the integer industry code): ``NeutralizedConfig``'s
+    ``dataset``, ``size_column`` and ``industry_column``.
+    """
+
+    exposures: Any
+    size_column: str
+    industry_column: str
+
+
+class Scoring:
+    """Score factors one way; see the module docstring.
+
+    Parameters
+    ----------
+    membership : quantlab IndexConstituentDataset or None
+        The members of each day; None scores every symbol.
+    neutralization : Neutralization or None
+        What ranked factors are neutralised against; None leaves them ranked.
+    njobs : int
+        KunQuant executor threads of the neutralisation.
+    """
+
+    def __init__(self, membership=None, neutralization: Neutralization | None = None, njobs: int = 1):
+        self.membership = membership
+        self.neutralization = neutralization
+        self._njobs = njobs
+
+    @classmethod
+    def from_config(cls, scoring: ScoringConfig, data: DataConfig, njobs: int) -> "Scoring":
+        """The scoring of a campaign config: its ``scoring`` section and ``data.membership``."""
+        membership = data.load("membership") if data.membership is not None else None
+        neutralization = None
+        if scoring.neutralize is not None:
+            n = scoring.neutralize
+            neutralization = Neutralization(load_each(n.exposures), n.size_column, n.industry_column)
+        return cls(membership, neutralization, njobs)
+
+    def apply(self, factor, file_path: str | Path | None = None, names: tuple[str, ...] | None = None):
+        """``factor``, whose outputs are ranked across the market, as scored on the whole market.
+
+        The neutralised factor, or ``factor`` itself without neutralisation;
+        with ``file_path``, the returned factor's store is there (``build``
+        writes it). ``names`` are the outputs scored, all by default; a
+        neutralised factor holds only them, an unneutralised one keeps the
+        rest unchanged.
+        """
+        path = None if file_path is None else str(file_path)
+        if self.neutralization is None:
+            return factor if path is None else type(factor)(replace(factor.config, file_path=path))
+        n = self.neutralization
+        pinned = {} if names is None else {"factor_names": tuple(names)}
+        return NeutralizedFactor(NeutralizedConfig(
+            factor=factor, dataset=n.exposures, size_column=n.size_column, industry_column=n.industry_column,
+            file_path=path, njobs=self._njobs, **pinned,
+        ))
+
+    def on_members(self, factor):
+        """``factor`` read from its store's first bar on, on the membership's roster, masked to the members of day t.
+
+        Without membership, ``factor`` read from its store's first bar on, on every symbol.
+        """
+        clipped = StartClippedFactor(StartClippedConfig(factor=factor))
+        if self.membership is None:
+            return clipped
+        viewed = RosterFactor(RosterConfig(factor=clipped, roster=self.membership))
+        return MembershipMaskedFactor(MembershipMaskedFactorConfig(factor=viewed, membership=self.membership))
+
+    def read(self, factor, start, end) -> Iterator[tuple[str, xr.DataArray]]:
+        """Yield ``(name, values)`` of every output of ``factor`` from ``start`` to ``end``, masked to day-t members.
+
+        A factor with a store (an entry given as a store) is read as stored,
+        from its first bar on; any other (an entry given as a component) is
+        scored by ``apply``, as a candidate is, and computed. The outputs are
+        masked one at a time, so only one masked copy is in memory.
+        """
+        if factor.store_range() is not None:
+            panel = StartClippedFactor(StartClippedConfig(factor=factor)).read(start, end)
+        else:
+            panel = self.apply(factor).compute(start, end)
+        for name in factor.get_factor_names():
+            yield name, self.mask(panel[[name]])[name]
+
+    def mask(self, panel: xr.Dataset) -> xr.Dataset:
+        """``panel`` NaN where the symbol is not a member on the bar's date; unchanged without membership."""
+        return panel if self.membership is None else self.membership.mask(panel)
+
+    def describe(self) -> str:
+        """One sentence for the prompts: what is done to a factor's values before they are judged."""
+        if self.neutralization is None:
+            neutral = "not neutralised"
+        else:
+            n = self.neutralization
+            neutral = (
+                f"neutralised against the industry ({n.industry_column}) and the logarithm of the market cap "
+                f"({n.size_column}) and z-scored"
+            )
+        members = "on the members of the research universe that day" if self.membership is not None else "on every symbol"
+        return f"A factor is ranked across the whole market each day, {neutral}, and scored {members}."

factor_agent/segments.py

@@ -0,0 +1,184 @@
+"""Evaluation segments: the date ranges the campaign and the acceptance read, the purge and the hold-out lock.
+
+The training segment is the only one the campaign evaluates; the validation
+segment is read by ``Acceptance.validate`` and the hold-out by
+``Acceptance.open_holdout``, once.
+
+The purge: a forward label at t reads prices up to ``lookahead`` bars past t,
+so wherever labels are read the last bars of a segment are dropped and no
+label reads a bar of the next segment. At least ``purge_bars`` (five)
+trading days are dropped, more when the label reads further (``ret_5``,
+whose label at t reads the open of t + 6, drops six).
+
+The hold-out lock: ``Segments.open_holdout`` writes a lock file recording
+when and with which code version the hold-out was opened. A second open is
+refused unless forced; every open, forced or not, is appended to the lock.
+"""
+
+import datetime
+import json
+import subprocess
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+import pandas as pd
+
+#: Trading days dropped at the end of a segment at least.
+PURGE_BARS = 5
+
+
+@dataclass(frozen=True)
+class Segment:
+    """A named, inclusive date range."""
+
+    name: str
+    start: str
+    end: str
+
+    def __post_init__(self):
+        if pd.Timestamp(self.start) > pd.Timestamp(self.end):
+            raise ValueError(f"segment {self.name}: start {self.start} is after end {self.end}")
+
+
+def purge(lookahead: int, purge_bars: int = PURGE_BARS) -> int:
+    """The bars dropped at the end of a segment for a label that reads ``lookahead`` bars past t."""
+    return max(purge_bars, lookahead)
+
+
+class HoldoutLocked(RuntimeError):
+    """The hold-out was opened before and the open was not forced."""
+
+
+@dataclass(frozen=True)
+class HoldoutOpen:
+    """One open of the hold-out: when (UTC), with which code, and whether it was forced past the lock."""
+
+    opened_at: str
+    code_version: dict
+    forced: bool
+
+
+@dataclass(frozen=True)
+class HoldoutLock:
+    """The lock after an open: ``opens`` holds every open so far, this one last."""
+
+    path: Path
+    opens: tuple[HoldoutOpen, ...]
+
+    @property
+    def last(self) -> HoldoutOpen:
+        """This open."""
+        return self.opens[-1]
+
+
+@dataclass(frozen=True)
+class Segments:
+    """The training, confirmation, validation and hold-out segments, in that order, and the purge between them.
+
+    Parameters
+    ----------
+    training : Segment
+        The segment the campaign evaluates.
+    confirmation : Segment, optional
+        The later part of the training data: a candidate is evaluated there
+        too and must hold there to be accepted, and no prompt shows a
+        statistic of it (``AdmissionConfig.confirm_t``).
+    validation, holdout : Segment, optional
+        The segments ``Acceptance`` reads; each starts after the one before ends.
+    purge_bars : int
+        The fewest trading days dropped at the end of a segment.
+    """
+
+    training: Segment
+    confirmation: Segment | None = None
+    validation: Segment | None = None
+    holdout: Segment | None = None
+    purge_bars: int = PURGE_BARS
+
+    def __post_init__(self):
+        order = [s for s in (self.training, self.confirmation, self.validation, self.holdout) if s is not None]
+        for before, after in zip(order, order[1:]):
+            if pd.Timestamp(after.start) <= pd.Timestamp(before.end):
+                raise ValueError(f"segment {after.name} starts on {after.start}, before {before.name} ends ({before.end})")
+        if self.purge_bars < 0:
+            raise ValueError(f"segments: purge_bars must be non-negative, got {self.purge_bars}")
+
+    def scored(self, segment: Segment, calendar: pd.DatetimeIndex, lookahead: int) -> tuple[str, str]:
+        """The first and last dates of ``segment`` whose label lies inside it.
+
+        Parameters
+        ----------
+        segment : Segment
+            The segment.
+        calendar : pd.DatetimeIndex
+            The trading days, covering the segment.
+        lookahead : int
+            Bars past t the label at t reads (``lookahead_bars()``).
+
+        Raises
+        ------
+        ValueError
+            If the purge leaves the segment no date.
+        """
+        bars = calendar[(calendar >= pd.Timestamp(segment.start)) & (calendar <= pd.Timestamp(segment.end))]
+        dropped = purge(lookahead, self.purge_bars)
+        kept = bars[: max(len(bars) - dropped, 0)]
+        if not len(kept):
+            raise ValueError(f"segment {segment.name}: the purge of {dropped} bars leaves no date")
+        return kept[0].strftime("%Y-%m-%d"), kept[-1].strftime("%Y-%m-%d")
+
+    def open_holdout(self, lock_path: str | Path, force: bool = False) -> HoldoutLock:
+        """Record an open of the hold-out in the lock at ``lock_path`` and return the lock.
+
+        Raises
+        ------
+        ValueError
+            If there is no hold-out segment.
+        HoldoutLocked
+            If the hold-out was opened before and ``force`` is false; the lock is unchanged.
+        """
+        if self.holdout is None:
+            raise ValueError("segments: there is no hold-out segment to open")
+        path = Path(lock_path)
+        opens = [HoldoutOpen(**o) for o in json.loads(path.read_text())["opens"]] if path.exists() else []
+        if opens and not force:
+            first = opens[0]
+            raise HoldoutLocked(
+                f"the hold-out was opened on {first.opened_at} (code {first.code_version.get('factor_agent')}), "
+                f"{len(opens)} open(s) so far; pass force=True to open it again, which the report states"
+            )
+        opens.append(HoldoutOpen(
+            opened_at=datetime.datetime.now(datetime.UTC).isoformat(timespec="seconds"),
+            code_version=code_version(), forced=bool(opens),
+        ))
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_suffix(".tmp")
+        tmp.write_text(json.dumps({"segment": asdict(self.holdout), "opens": [asdict(o) for o in opens]}, indent=2) + "\n")
+        tmp.replace(path)
+        return HoldoutLock(path, tuple(opens))
+
+
+def code_version() -> dict:
+    """The commit (``+dirty`` with uncommitted changes) of this package and of quantlab, and quantlab's version."""
+    import quantlab
+
+    import factor_agent
+
+    return {
+        "factor_agent": _commit(Path(factor_agent.__file__).parent),
+        "quantlab": _commit(Path(quantlab.__file__).parent),
+        "quantlab_version": quantlab.__version__,
+    }
+
+
+def _commit(directory: Path) -> str:
+    """The git commit of the checkout holding ``directory``, or ``"unknown"`` outside one."""
+    def git(*args: str) -> str:
+        return subprocess.run(["git", "-C", str(directory), *args], capture_output=True, text=True, check=True).stdout
+
+    try:
+        head = git("rev-parse", "HEAD").strip()
+        dirty = bool(git("status", "--porcelain", "--untracked-files=no").strip())
+    except (OSError, subprocess.CalledProcessError):
+        return "unknown"
+    return head + ("+dirty" if dirty else "")