Class AlphaContext

java.lang.Object
com.quantfinlib.alpha.AlphaContext
public final class AlphaContext extends Object
The research dataset an alpha factor operates on: an index-aligned panel of price series over a fixed symbol order, with optional fundamentals and an optional point-in-time universe.

Everything in com.quantfinlib.alpha works cross-sectionally: at a bar index a factor scores every symbol, and downstream steps (evaluation, construction, backtest) consume those scores as arrays aligned with symbols(). Symbols are sorted once here, so plain double[] is the interchange type for the whole pipeline.

Alignment. Series must share one timeline (see data.SeriesAligner). of(Map) checks both the length and every bar timestamp against the first series: a one-bar offset in one name silently turns a cross-sectional IC into a lead-lag estimate.

Fundamentals. Two sources:

Survivorship. Attach a PointInTimeUniverse with withUniverse(PointInTimeUniverse). Then:

  • isActive(int, int) is point-in-time membership, and every built-in factor scores inactive names as NaN;
  • returnOver(int, int, int) is terminal-event aware: a name alive at the start of a window that delists inside it returns close(e−1)·(1 + delistingReturn)/close(from) − 1, where e is the first bar at or after the event; a merged name returns its deal value (cash plus acquirer shares marked at the acquirer's price). Without this the forward-filled ghost bars after a delisting read as a zero return, which removes exactly the losses a short book is paid to capture.

The terminal value convention matches backtest.portfolio.PortfolioBacktester: proceeds anchor on the last close before the event bar.

  • Method Details

    • of

      public static AlphaContext of(Map<String, BarSeries> data)
      Panel without fundamentals (technical factors only).

    • of

      public static AlphaContext of(Map<String, BarSeries> data, Map<String, Fundamentals> fundamentals)
      Panel with a static fundamentals snapshot. The snapshot is only valid at the last bar (see the class doc); attach a FundamentalsHistory to score fundamentals historically.
      Throws:
      IllegalArgumentException - when series differ in length or in any bar timestamp

    • withUniverse

      public AlphaContext withUniverse(PointInTimeUniverse universe)
      The same panel with a point-in-time universe attached (see the class doc). Universe timestamps must be in the bar timestamps' units.

    • withFundamentalsHistory

      public AlphaContext withFundamentalsHistory(FundamentalsHistory history)
      The same panel with point-in-time fundamentals attached.

    • isActive

      public boolean isActive(int i, int barIndex)
      Whether symbol i is in the tradeable cross-section at barIndex: always true without a universe, otherwise point-in-time membership (dead and dropped names excluded).

    • symbols

      public List<String> symbols()
      The frozen symbol order every score/weight array aligns with.

    • symbolCount

      public int symbolCount()

    • bars

      public int bars()
      Panel length in bars (every series has exactly this many).

    • series

      public BarSeries series(int i)
      Price series for symbol index i (the panel axis, not the bar).

    • fundamentals

      public Fundamentals fundamentals(int i)
      Static snapshot fundamentals for symbol i, or null.

    • hasFundamentalsHistory

      public boolean hasFundamentalsHistory()
      Whether a point-in-time fundamentals history is attached.

    • fundamentalsAsOf

      public Fundamentals fundamentalsAsOf(int i, int index)
      Fundamentals of symbol i as known at bar index. With a FundamentalsHistory: the latest record published at or before the bar (null when none). With only a static snapshot: the snapshot at the last bar; earlier bars throw, because using today's fundamentals to score the past is look-ahead.
      Throws:
      IllegalStateException - for a historical bar without a history

    • timestamp

      public long timestamp(int index)
      Bar timestamp at index (all series share it).

    • terminalIndex

      public int terminalIndex(int i)
      First bar at or after symbol i's terminal event, or −1 when there is no universe, no event, or the event falls after the panel.

    • acquirerIndex

      public int acquirerIndex(int i)
      Panel index of the acquirer receiving symbol i's holders in a stock merger, or −1.

    • terminalAcquirerShares

      public double terminalAcquirerShares(int i)
      Acquirer shares paid per share of symbol i at its terminal event (0 if none).

    • returnOver

      public double returnOver(int i, int fromIndex, int toIndex)
      Simple return of symbol i over (fromIndex, toIndex], close to close, terminal-event aware (see the class doc). NaN when the name was already dead at fromIndex.

    • returnBetween

      public double returnBetween(int i, int fromIndex, boolean fromOpen, int toIndex, boolean toOpen)
      Simple return between two price points, each the open or the close of a bar: the building block for fill-lagged backtests. Terminal-event aware: once the event bar is reached the position is worth its terminal value (cash, plus acquirer shares marked at the acquirer's price at the end point). NaN when the name was already dead at the start point.
      Throws:
      IllegalStateException - when a stock merger pays shares of an acquirer outside the panel