Analysis¶
Import public analysis functions from persistra.analysis. Submodule sections group them by
the kind of input and calculation.
General numeric analysis¶
persistra.analysis.general
¶
General analysis for explicit wide numeric frames.
AnalysisError
¶
Bases: PersistraError, ValueError
Raised when data violates a mathematical assumption.
require_integer(value: object, *, name: str, minimum: int | None = None) -> int
¶
Return a normalized integer after enforcing an optional inclusive minimum.
_numeric(frame: pd.DataFrame) -> pd.DataFrame
¶
Copy a wide frame after requiring finite, non-boolean numeric observations.
coverage_summary(frame: pd.DataFrame) -> pd.DataFrame
¶
Summarize observed and missing labels for each column.
summary_statistics(frame: pd.DataFrame) -> pd.DataFrame
¶
Return sample statistics and pandas linear quantiles by column.
absolute_change(frame: pd.DataFrame, *, periods: int = 1) -> pd.DataFrame
¶
Calculate arithmetic differences without bridging missing levels.
percentage_change(frame: pd.DataFrame, *, periods: int = 1) -> pd.DataFrame
¶
Calculate fractional changes without filling missing levels.
log_change(frame: pd.DataFrame, *, periods: int = 1) -> pd.DataFrame
¶
Calculate log-level differences after requiring positive levels.
simple_returns(frame: pd.DataFrame, *, periods: int = 1) -> pd.DataFrame
¶
Calculate simple price returns without filling missing levels.
log_returns(frame: pd.DataFrame, *, periods: int = 1) -> pd.DataFrame
¶
Calculate log price returns after requiring positive levels.
rebase(frame: pd.DataFrame, *, base: float = 100) -> pd.DataFrame
¶
Rebase each column to its first observed positive level.
cumulative_returns(returns: pd.DataFrame) -> pd.DataFrame
¶
Compound simple returns after rejecting internal observed-span gaps.
drawdowns(returns: pd.DataFrame) -> pd.DataFrame
¶
Calculate drawdowns from simple returns with continuous observed paths.
rolling_mean(frame: pd.DataFrame, *, window: int, min_periods: int | None = None) -> pd.DataFrame
¶
Calculate rolling means with complete windows by default.
rolling_standard_deviation(frame: pd.DataFrame, *, window: int, min_periods: int | None = None) -> pd.DataFrame
¶
Calculate sample rolling standard deviations.
rolling_volatility(returns: pd.DataFrame, *, window: int, periods_per_year: float, min_periods: int | None = None) -> pd.DataFrame
¶
Annualize sample rolling return volatility with an explicit scale.
rolling_zscore(frame: pd.DataFrame, *, window: int, min_periods: int | None = None) -> pd.DataFrame
¶
Calculate rolling sample z-scores.
covariance_matrix(frame: pd.DataFrame) -> pd.DataFrame
¶
Calculate sample covariance with pairwise complete observations.
correlation_matrix(frame: pd.DataFrame) -> pd.DataFrame
¶
Calculate Pearson correlation with pairwise complete observations.
_change_inputs(frame: pd.DataFrame, periods: int) -> tuple[pd.DataFrame, int]
¶
_rolling_counts(window: int, min_periods: int | None) -> tuple[int, int]
¶
_require_positive(frame: pd.DataFrame) -> None
¶
_reject_internal_gaps(frame: pd.DataFrame) -> None
¶
Market analysis¶
persistra.analysis.market
¶
Analysis for normalized market observations.
BarSet
dataclass
¶
Validated bars and their acquisition provenance.
TopOfBookSet
dataclass
¶
Validated top-of-book snapshots and provenance.
Missing and one-sided quotes are valid. Locked and crossed quotes are retained with
bid_ask diagnostics. A size without its corresponding price is invalid.
rolling_volatility(returns: pd.DataFrame, *, window: int, periods_per_year: float, min_periods: int | None = None) -> pd.DataFrame
¶
Annualize sample rolling return volatility with an explicit scale.
midprice(book: TopOfBookSet) -> pd.DataFrame
¶
Calculate bid-ask midprices while preserving missing sides.
absolute_spread(book: TopOfBookSet) -> pd.DataFrame
¶
Calculate ask minus bid while preserving missing sides.
relative_spread(book: TopOfBookSet) -> pd.DataFrame
¶
Calculate absolute spread divided by midprice.
bar_range(bars: BarSet) -> pd.DataFrame
¶
Calculate high minus low for each normalized bar.
true_range(bars: BarSet) -> pd.DataFrame
¶
Calculate true range with previous close within each normalized bar path.
volume_summary(bars: BarSet) -> pd.Series
¶
Summarize available normalized volume observations.
realized_volatility(returns: pd.DataFrame, *, window: int, periods_per_year: float) -> pd.DataFrame
¶
Calculate annualized realized volatility from explicit returns.
session_coverage(bars: BarSet) -> pd.DataFrame
¶
Describe observed bar labels without inferring expected sessions.
_bar_identity(bars: BarSet) -> pd.DataFrame
¶
Historical option analysis¶
persistra.analysis.options
¶
Analysis of observed historical option chains.
AnalysisError
¶
Bases: PersistraError, ValueError
Raised when data violates a mathematical assumption.
OptionChain
dataclass
¶
Contracts and observations for one historical chain.
Missing and one-sided quotes are valid. Locked and crossed quotes are retained with
bid_ask diagnostics. A size without its corresponding price is invalid.
OptionType
¶
Bases: StrEnum
Option contract sides.
filter_chain(chain: OptionChain, *, expiration: date | None = None, option_type: OptionType | str | None = None, minimum_strike: float | None = None, maximum_strike: float | None = None, contract_ids: Iterable[str] | None = None) -> OptionChain
¶
Return a chain restricted by explicit contract terms.
days_to_expiration(chain: OptionChain) -> pd.DataFrame
¶
Calculate whole calendar days from chain date to expiration.
moneyness(chain: OptionChain, *, underlying_price: float) -> pd.DataFrame
¶
Calculate spot divided by strike for each observed contract.
log_moneyness(chain: OptionChain, *, underlying_price: float) -> pd.DataFrame
¶
Calculate the natural log of spot divided by strike.
option_midprice(chain: OptionChain) -> pd.DataFrame
¶
Calculate observed bid-ask midprices without filling missing quotes.
option_absolute_spread(chain: OptionChain) -> pd.DataFrame
¶
Calculate observed ask minus bid.
option_relative_spread(chain: OptionChain) -> pd.DataFrame
¶
Calculate absolute spread divided by midprice.
intrinsic_value(chain: OptionChain, *, underlying_price: float) -> pd.DataFrame
¶
Calculate intrinsic value from one explicit underlying price.
time_value(chain: OptionChain, *, underlying_price: float, option_value: str = 'mark') -> pd.DataFrame
¶
Subtract intrinsic value from one explicit observed option-value field.
chain_summary(chain: OptionChain) -> pd.DataFrame
¶
Summarize observed contracts by expiration and option type.
implied_volatility_smile(chain: OptionChain, *, expiration: date, option_type: OptionType | str | None = None) -> pd.DataFrame
¶
Prepare observed implied volatility across strikes for one expiration.
implied_volatility_surface(chain: OptionChain) -> pd.DataFrame
¶
Prepare observed implied volatility without fitting or interpolation.
greek_profile(chain: OptionChain, greek: str, *, expiration: date | None = None, option_type: OptionType | str | None = None) -> pd.DataFrame
¶
Prepare one provider-supplied Greek across observed strikes.
_joined(chain: OptionChain) -> pd.DataFrame
¶
_positive_price(value: float) -> float
¶
Economic and rate analysis¶
persistra.analysis.economics
¶
Analysis for economic and interest-rate series.
_MATURITY_YEARS = {'3month': 0.25, '2year': 2.0, '5year': 5.0, '7year': 7.0, '10year': 10.0, '30year': 30.0}
module-attribute
¶
AnalysisError
¶
Bases: PersistraError, ValueError
Raised when data violates a mathematical assumption.
SeriesSet
dataclass
¶
One validated scalar series and its provenance.
require_integer(value: object, *, name: str, minimum: int | None = None) -> int
¶
Return a normalized integer after enforcing an optional inclusive minimum.
numeric_frame(frame: pd.DataFrame) -> pd.DataFrame
¶
Copy a wide frame after requiring finite, non-boolean numeric observations.
basis_point_change(values: pd.DataFrame, *, rate_unit: str, periods: int = 1) -> pd.DataFrame
¶
Calculate rate changes in basis points from an explicit input unit.
growth_rate(values: pd.DataFrame, *, lag: int = 1) -> pd.DataFrame
¶
Calculate fractional growth over one explicit positive lag.
yield_curve(series: Iterable[SeriesSet], *, period_label: str) -> pd.DataFrame
¶
Build one observed Treasury curve without interpolation.
yield_curve_history(series: Iterable[SeriesSet]) -> pd.DataFrame
¶
Pivot observed Treasury values while preserving missing maturities.