Class PointInTimeUniverse

java.lang.Object

com.quantfinlib.data.PointInTimeUniverse

public final class PointInTimeUniverse
extends Object

Point-in-time universe membership — the engine-side half of survivorship-bias-free backtesting.

Survivorship bias enters when a backtest's universe is built from today's constituents: every bankruptcy, acquisition and delisting has already been silently removed, so the strategy only ever "picks" from winners. Removing the bias needs two things:

1. Data — historical membership including dead tickers, and delisting returns (what a holder actually received). This class cannot conjure that; it comes from CRSP-style datasets.
2. Engine — screens and rebalances that only see members as of each date, and positions that terminate correctly when a security dies. That is what this class provides, consumed by screener.StockScreener#membersAsOf and the universe-aware backtest.portfolio.PortfolioBacktester overload.

Per symbol it records membership intervals (a symbol can leave and rejoin an index) and at most one terminal event:

• PointInTimeUniverse.EventType.DELISTING with a delisting return — the final-day return relative to the last close (−1 = shareholders got nothing). When the true value is unknown for an involuntary delisting, the literature's convention is DEFAULT_INVOLUNTARY_DELISTING_RETURN (Shumway 1997).
• PointInTimeUniverse.EventType.MERGER with per-share deal terms: cash and/or shares of the acquirer.

Timestamps use the same epoch units as the BarSeries being backtested. Not thread-safe during construction; effectively immutable afterwards if not mutated.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	PointInTimeUniverse.EventType	How a security's life ends.
static final record	PointInTimeUniverse.TerminalEvent	A security's terminal event.

Field Summary

Fields

Modifier and Type	Field	Description
static final double	DEFAULT_INVOLUNTARY_DELISTING_RETURN	The standard haircut for involuntary delistings with unknown proceeds: −30% on the last traded price (Shumway, Journal of Finance 1997).

Constructor Summary

Constructors

Constructor	Description
PointInTimeUniverse()

Method Summary

Modifier and Type	Method	Description
PointInTimeUniverse	addMembership(String symbol, long fromTimestamp)	Membership from a date with no known end (a current constituent).
PointInTimeUniverse	addMembership(String symbol, long fromTimestamp, long toTimestampInclusive)	Adds a membership interval (inclusive of both endpoints).
Set<String>	allSymbols()	Every symbol that ever appears in this universe (living and dead).
boolean	isMember(String symbol, long timestamp)	Whether the symbol is a universe member at timestamp: inside a membership interval and not past its terminal event.
Set<String>	membersAsOf(long timestamp)	All members as of a timestamp, sorted for determinism.
PointInTimeUniverse	recordDelisting(String symbol, long timestamp, double delistingReturn)	Records a delisting: membership (if any) is truncated at the event and the position terminates at lastClose × (1 + delistingReturn).
PointInTimeUniverse	recordMerger(String symbol, long timestamp, double cashPerShare, double acquirerSharesPerShare, String acquirer)	Records a merger/acquisition: at the event each held share converts to cashPerShare cash plus acquirerSharesPerShare shares of acquirer.
PointInTimeUniverse.TerminalEvent	terminalEvent(String symbol)	The symbol's terminal event, or null while it lives.

Methods inherited from class java.lang.Object

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

Field Details

DEFAULT_INVOLUNTARY_DELISTING_RETURN

public static final double DEFAULT_INVOLUNTARY_DELISTING_RETURN

The standard haircut for involuntary delistings with unknown proceeds: −30% on the last traded price (Shumway, Journal of Finance 1997).

See Also:

• Constant Field Values

Constructor Details

PointInTimeUniverse

public PointInTimeUniverse()

Method Details

addMembership

public PointInTimeUniverse addMembership(String symbol,
 long fromTimestamp,
 long toTimestampInclusive)

Adds a membership interval (inclusive of both endpoints). A symbol may hold several disjoint intervals — index drop and later re-add.

addMembership

public PointInTimeUniverse addMembership(String symbol,
 long fromTimestamp)

Membership from a date with no known end (a current constituent).

recordDelisting

public PointInTimeUniverse recordDelisting(String symbol,
 long timestamp,
 double delistingReturn)

Records a delisting: membership (if any) is truncated at the event and the position terminates at lastClose × (1 + delistingReturn). Use DEFAULT_INVOLUNTARY_DELISTING_RETURN when the true proceeds are unknown.

recordMerger

public PointInTimeUniverse recordMerger(String symbol,
 long timestamp,
 double cashPerShare,
 double acquirerSharesPerShare,
 String acquirer)

Records a merger/acquisition: at the event each held share converts to cashPerShare cash plus acquirerSharesPerShare shares of acquirer. All-cash deals pass 0 shares and a null acquirer.

isMember

public boolean isMember(String symbol,
 long timestamp)

Whether the symbol is a universe member at timestamp: inside a membership interval and not past its terminal event.

membersAsOf

public Set<String> membersAsOf(long timestamp)

All members as of a timestamp, sorted for determinism.

terminalEvent

public PointInTimeUniverse.TerminalEvent terminalEvent(String symbol)

The symbol's terminal event, or null while it lives.

allSymbols

public Set<String> allSymbols()

Every symbol that ever appears in this universe (living and dead).