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.

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(). Freezing the symbol order once here is what makes plain double[] the interchange type for the whole pipeline — no per-step map lookups, no ordering ambiguity.

Series must be index-aligned (same length, same bar times — see data.SeriesAligner); the constructor enforces equal length, the timestamp discipline is the caller's (documented) responsibility. Fundamentals are an optional static snapshot: factors that need them (Factors.value(), Factors.quality()) return NaN for symbols without entries. A point-in-time fundamentals history is data this library cannot invent — the snapshot is honest about that.

Survivorship: alpha research is the stage survivorship bias flatters most — the delisted losers a short book would have held are the exact names a today's-constituents panel lacks. Attach a PointInTimeUniverse via withUniverse(com.quantfinlib.data.PointInTimeUniverse) and every built-in factor scores non-members/dead names as NaN at each bar (isActive(int, int)), so ICs, validation and constructed weights only ever see the point-in-time cross-section. Without a universe the panel is survivorship-blind — fine for methodology work, dishonest for performance claims. Custom AlphaFactors should honor isActive the same way. Note the weight-based AlphaBacktester still earns ghost returns on a name that dies mid-hold (weights only change at rebalances); for lifecycle-exact accounting feed the weights into backtest.portfolio.PortfolioBacktester's survivorship-aware overload.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    bars()
    Panel length in bars (every series has exactly this many).
    Fundamentals
    fundamentals(int i)
    Fundamentals for symbol index i, or null when unknown.
    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).
    static AlphaContext
    of(Map<String, BarSeries> data)
    Panel without fundamentals (technical factors only).
    static AlphaContext
    of(Map<String, BarSeries> data, Map<String, Fundamentals> fundamentals)
    Panel with a fundamentals snapshot for value/quality factors.
    double
    returnOver(int i, int fromIndex, int toIndex)
    Simple return of symbol i over (fromIndex, toIndex] — the forward-return building block evaluation and backtesting share.
    BarSeries
    series(int i)
    Price series for symbol index i (the panel axis, not the bar).
    int
    symbolCount()
     
    List<String>
    symbols()
    The frozen symbol order every score/weight array aligns with.
    long
    timestamp(int index)
    Bar timestamp at index (taken from the first series).
    AlphaContext
    withUniverse(PointInTimeUniverse universe)
    The same panel with a point-in-time universe attached: built-in factors then score non-members as NaN per bar (see the class doc).

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • 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 fundamentals snapshot for value/quality factors.

    • withUniverse

      public AlphaContext withUniverse(PointInTimeUniverse universe)
      The same panel with a point-in-time universe attached: built-in factors then score non-members as NaN per bar (see the class doc). Universe timestamps must be in the same units as the bar timestamps.

    • 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)
      Fundamentals for symbol index i, or null when unknown.

    • timestamp

      public long timestamp(int index)
      Bar timestamp at index (taken from the first series).

    • returnOver

      public double returnOver(int i, int fromIndex, int toIndex)
      Simple return of symbol i over (fromIndex, toIndex] — the forward-return building block evaluation and backtesting share.