Visualization

Import public plotting functions from persistra.viz. Every function returns one caller-owned plotly.graph_objects.Figure. Composite views use named Plotly subplots. Functions do not change global templates or renderers.

General plots

persistra.viz.general

General Plotly figures for explicit wide data.

correlation_matrix(frame: pd.DataFrame) -> pd.DataFrame

Calculate Pearson correlation with pairwise complete observations.

coverage_summary(frame: pd.DataFrame) -> pd.DataFrame

Summarize observed and missing labels for each column.

rebase(frame: pd.DataFrame, *, base: float = 100) -> pd.DataFrame

Rebase each column to its first observed positive level.

comparison_yscale(frame: pd.DataFrame, requested: Literal['auto', 'linear', 'log']) -> Literal['linear', 'log']

Select log scaling when positive terminal values differ by at least 10x.

figure(*, title: str | None = None) -> go.Figure

Create one figure with Persistra's local presentation policy.

finish_figure(result: go.Figure, *, xlabel: str, ylabel: str, title: str | None = None, showlegend: bool | None = None) -> go.Figure

Apply common labels and interaction defaults to a figure.

plot_wide_series(frame: pd.DataFrame, *, ylabel: str) -> go.Figure

Plot wide-frame columns after caller-specific scale validation.

plot_series(frame: pd.DataFrame, *, ylabel: str = 'Value') -> go.Figure

Plot each wide-frame column as one line.

plot_rebased(frame: pd.DataFrame, *, base: float = 100, yscale: Literal['auto', 'linear', 'log'] = 'auto') -> go.Figure

Plot rebased columns with automatic or explicit axis scaling.

plot_distribution(values: pd.Series, *, bins: int = 30) -> go.Figure

Plot a histogram of finite observed values.

plot_rolling_statistic(frame: pd.DataFrame, *, statistic_name: str) -> go.Figure

Plot an already calculated rolling statistic.

plot_correlation(frame: pd.DataFrame) -> go.Figure

Plot pairwise correlations with complete-observation counts.

plot_coverage(frame: pd.DataFrame) -> go.Figure

Plot observed coverage for each wide-frame column.

_require_comparable_scale(frame: pd.DataFrame) -> None

Market plots

persistra.viz.market

Plotly figures for normalized market observations.

BarSet dataclass

Validated bars and their acquisition provenance.

comparison_yscale(frame: pd.DataFrame, requested: Literal['auto', 'linear', 'log']) -> Literal['linear', 'log']

Select log scaling when positive terminal values differ by at least 10x.

figure(*, title: str | None = None) -> go.Figure

Create one figure with Persistra's local presentation policy.

finish_figure(result: go.Figure, *, xlabel: str, ylabel: str, title: str | None = None, showlegend: bool | None = None) -> go.Figure

Apply common labels and interaction defaults to a figure.

plot_wide_series(frame: pd.DataFrame, *, ylabel: str) -> go.Figure

Plot wide-frame columns after caller-specific scale validation.

sampled_positions(length: int, *, maximum_ticks: int = 8) -> list[int]

Return evenly sampled positions including both endpoints.

series_style(position: int) -> tuple[str, str, str]

Return one deterministic color, dash style, and marker.

temporal_values(values: pd.Index) -> pd.Index

Convert period labels to their temporal starts for plotting.

plot_series(frame: pd.DataFrame, *, ylabel: str = 'Value') -> go.Figure

Plot each wide-frame column as one line.

plot_candlesticks(bars: BarSet, *, yscale: Literal['auto', 'linear', 'log'] = 'auto') -> go.Figure

Plot OHLC candles with volume and discontinuity-aware scaling.

plot_returns(returns: pd.DataFrame) -> go.Figure

Plot explicit return series.

plot_cumulative_returns(values: pd.DataFrame, *, yscale: Literal['auto', 'linear', 'log'] = 'auto') -> go.Figure

Plot cumulative paths with automatic or explicit axis scaling.

plot_drawdowns(values: pd.DataFrame) -> go.Figure

Plot already calculated drawdowns.

plot_rolling_volatility(values: pd.DataFrame) -> go.Figure

Plot already calculated annualized rolling volatility.

plot_bid_ask_history(history: pd.DataFrame) -> go.Figure

Plot bid and ask history from more than one stored snapshot.

plot_spread_history(history: pd.DataFrame) -> go.Figure

Plot absolute spread history from more than one stored snapshot.

_history(frame: pd.DataFrame) -> None

_price_discontinuities(frame: pd.DataFrame) -> list[tuple[int, float]]

Locate adjacent open-to-previous-close gaps of at least twofold.

_mark_missing_observations(result: go.Figure, frame: pd.DataFrame) -> None

Historical option plots

persistra.viz.options

Plotly figures for observed historical option chains.

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.

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.

implied_volatility_smile(chain: OptionChain, *, expiration: date, option_type: OptionType | str | None = None) -> pd.DataFrame

Prepare observed implied volatility across strikes for one expiration.

figure(*, title: str | None = None) -> go.Figure

Create one figure with Persistra's local presentation policy.

finish_figure(result: go.Figure, *, xlabel: str, ylabel: str, title: str | None = None, showlegend: bool | None = None) -> go.Figure

Apply common labels and interaction defaults to a figure.

sampled_positions(length: int, *, maximum_ticks: int = 8) -> list[int]

Return evenly sampled positions including both endpoints.

series_style(position: int) -> tuple[str, str, str]

Return one deterministic color, dash style, and marker.

plot_option_chain_prices(chain: OptionChain) -> go.Figure

Plot observed option marks across strikes by expiration and side.

plot_option_volume_open_interest(chain: OptionChain) -> go.Figure

Plot observed option volume and open interest by strike.

plot_implied_volatility_smile(chain: OptionChain, *, expiration: date, option_type: str | None = None) -> go.Figure

Plot observed implied volatility across strikes.

plot_implied_volatility_surface(chain: OptionChain) -> go.Figure

Plot observed implied volatility as a three-dimensional surface.

plot_greek_profile(chain: OptionChain, greek: str, *, expiration: date | None = None, option_type: str | None = None) -> go.Figure

Plot one provider-supplied Greek across observed strikes.

_group_label(expiration: Any, option_type: Any) -> str

_contract_label(expiration: Any, strike: Any, option_type: Any) -> str

_format_strike(value: Any) -> str

_group_style(position: int, observations: int) -> tuple[str, str, str]

Economic plots

persistra.viz.economics

Plotly figures for scalar and yield-curve data.

SeriesSet dataclass

One validated scalar series and its provenance.

figure(*, title: str | None = None) -> go.Figure

Create one figure with Persistra's local presentation policy.

finish_figure(result: go.Figure, *, xlabel: str, ylabel: str, title: str | None = None, showlegend: bool | None = None) -> go.Figure

Apply common labels and interaction defaults to a figure.

marker_interval(length: int, *, maximum_markers: int = 18) -> int

Limit visible markers while retaining deterministic positions.

sampled_positions(length: int, *, maximum_ticks: int = 8) -> list[int]

Return evenly sampled positions including both endpoints.

plot_series(frame: pd.DataFrame, *, ylabel: str = 'Value') -> go.Figure

Plot each wide-frame column as one line.

plot_scalar_series(series: SeriesSet) -> go.Figure

Plot one normalized commodity or economic series.

plot_series_change(values: pd.DataFrame, *, ylabel: str = 'Change') -> go.Figure

Plot already calculated scalar-series changes.

plot_yield_curve(curve: pd.DataFrame) -> go.Figure

Plot one observed yield curve without interpolation.

plot_yield_curve_history(history: pd.DataFrame) -> go.Figure

Plot observed yield history as a noninterpolated heatmap.

_period_label(value: Any) -> str

Signal research plots

persistra.viz.research

Plotly figures for cross-sectional signal research results.

InformationCoefficientStatistic = Literal['pearson', 'rank']

InformationCoefficientAggregation = Literal['mean', 'median']

GroupStatistic = Literal['mean_signal', 'signal_standard_deviation', 'mean_forward_return', 'pearson', 'rank']

CapacityStatistic = Literal['volume_count', 'total_volume', 'median_volume', 'minimum_volume']

BenchmarkStatistic = Literal['mean_candidate', 'mean_benchmark', 'mean_difference', 'tracking_error', 'win_rate', 'correlation']

BenchmarkComparison dataclass

Candidate results compared with one aligned benchmark series.

GroupSignalResult dataclass

Signal and forward-return statistics for time-varying classifications.

InformationCoefficientResult dataclass

Pearson and rank information coefficients with pairwise sample counts.

QuantilePortfolioResult dataclass

Quantile returns, formation weights, linear costs, and diagnostics.

require_integer(value: object, *, name: str, minimum: int | None = None) -> int

Return a normalized integer after enforcing an optional inclusive minimum.

figure(*, title: str | None = None) -> go.Figure

Create one figure with Persistra's local presentation policy.

finish_figure(result: go.Figure, *, xlabel: str, ylabel: str, title: str | None = None, showlegend: bool | None = None) -> go.Figure

Apply common labels and interaction defaults to a figure.

plot_wide_series(frame: pd.DataFrame, *, ylabel: str) -> go.Figure

Plot wide-frame columns after caller-specific scale validation.

set_figure_title(result: go.Figure, title: str) -> go.Figure

Place a title and horizontal legend in separate top-margin regions.

plot_cumulative_returns(values: pd.DataFrame, *, yscale: Literal['auto', 'linear', 'log'] = 'auto') -> go.Figure

Plot cumulative paths with automatic or explicit axis scaling.

plot_returns(returns: pd.DataFrame) -> go.Figure

Plot explicit return series.

plot_signal_distribution(signals: pd.DataFrame, *, date: pd.Timestamp, groups: pd.DataFrame | None = None, bins: int = 20) -> go.Figure

Plot one explicit cross-section as a histogram or group box comparison.

plot_signal_ranks(ranks: pd.DataFrame, *, date: pd.Timestamp) -> go.Figure

Plot already calculated cross-sectional ranks for one explicit date.

plot_group_comparison(result: GroupSignalResult, *, statistic: GroupStatistic = 'mean_forward_return') -> go.Figure

Plot one group statistic through time with explicit horizon and coverage.

plot_information_coefficients(result: InformationCoefficientResult, *, statistic: InformationCoefficientStatistic = 'rank', rolling: int | None = None) -> go.Figure

Plot ICs through time and expose pairwise counts and missing coverage.

plot_information_coefficient_horizons(results: Sequence[InformationCoefficientResult], *, statistic: InformationCoefficientStatistic = 'rank', aggregation: InformationCoefficientAggregation = 'mean') -> go.Figure

Compare one aggregate IC across explicit, unique forward horizons.

plot_quantile_returns(result: QuantilePortfolioResult) -> go.Figure

Plot gross quantile forward returns with explicit definitions.

plot_cumulative_quantile_returns(result: QuantilePortfolioResult) -> go.Figure

Plot compounded one-observation quantile returns without overlapping labels.

plot_quantile_spread(result: QuantilePortfolioResult) -> go.Figure

Plot the top-minus-bottom forward-return spread.

plot_quantile_counts(result: QuantilePortfolioResult) -> go.Figure

Plot the effective asset count in every quantile through time.

plot_quantile_turnover(result: QuantilePortfolioResult) -> go.Figure

Plot one-way turnover for every signal quantile.

plot_quantile_capacity(result: QuantilePortfolioResult, *, statistic: CapacityStatistic = 'total_volume') -> go.Figure

Plot one explicit capacity-oriented volume statistic by quantile.

_quantile_weighting_label(result: QuantilePortfolioResult) -> str

plot_stability_comparison(values: pd.Series, *, statistic_name: str, comparison_name: str, counts: pd.Series | None = None) -> go.Figure

Plot a caller-defined period, universe, split, or benchmark comparison.

plot_benchmark_comparison(result: BenchmarkComparison, *, statistic: BenchmarkStatistic = 'mean_difference') -> go.Figure

Plot one candidate-versus-benchmark summary with pairwise counts.

_panel(frame: pd.DataFrame, *, name: str) -> pd.DataFrame

_numeric_series(values: pd.Series, *, name: str) -> pd.Series

_aligned_groups(groups: pd.DataFrame, signals: pd.DataFrame) -> pd.DataFrame

_date_position(index: pd.Index, date: pd.Timestamp) -> int

_require_columns(frame: pd.DataFrame, columns: set[str], *, name: str) -> None

_quantile_frame(frame: pd.DataFrame) -> pd.DataFrame

_label(value: str) -> str

_date_label(value: pd.Timestamp) -> str

_annotate_counts(result: go.Figure, counts: pd.Series) -> None

_annotate_quantile_coverage(result: go.Figure, counts: pd.DataFrame) -> None

Portfolio and backtest plots

persistra.viz.portfolio

Plotly figures for portfolio construction and vectorized backtests.

PortfolioResult = PortfolioConstructionResult | BacktestResult

WeightKind = Literal['target', 'unconstrained', 'realized', 'ending']

BacktestResult dataclass

Reconciled portfolio-level backtest paths and benchmark comparisons.

PortfolioConstructionResult dataclass

Transparent unconstrained and final target portfolio weights.

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.

figure(*, title: str | None = None) -> go.Figure

Create one figure with Persistra's local presentation policy.

finish_figure(result: go.Figure, *, xlabel: str, ylabel: str, title: str | None = None, showlegend: bool | None = None) -> go.Figure

Apply common labels and interaction defaults to a figure.

plot_wide_series(frame: pd.DataFrame, *, ylabel: str) -> go.Figure

Plot wide-frame columns after caller-specific scale validation.

set_figure_title(result: go.Figure, title: str) -> go.Figure

Place a title and horizontal legend in separate top-margin regions.

temporal_values(values: pd.Index) -> pd.Index

Convert period labels to their temporal starts for plotting.

plot_cumulative_returns(values: pd.DataFrame, *, yscale: Literal['auto', 'linear', 'log'] = 'auto') -> go.Figure

Plot cumulative paths with automatic or explicit axis scaling.

plot_drawdowns(values: pd.DataFrame) -> go.Figure

Plot already calculated drawdowns.

plot_returns(returns: pd.DataFrame) -> go.Figure

Plot explicit return series.

plot_rolling_volatility(values: pd.DataFrame) -> go.Figure

Plot already calculated annualized rolling volatility.

plot_portfolio_weights(result: PortfolioResult, *, kind: WeightKind = 'target', include_cash: bool = True) -> go.Figure

Plot one explicit target, unconstrained, realized, or ending weight panel.

plot_portfolio_exposures(result: PortfolioResult) -> go.Figure

Plot long, short, gross, net, and residual-cash exposures.

plot_constraint_utilization(result: PortfolioConstructionResult) -> go.Figure

Plot construction constraint use relative to each implemented limit.

plot_predicted_volatility(result: PortfolioConstructionResult) -> go.Figure

Plot covariance-implied annualized volatility and configured controls.

plot_risk_contributions(result: PortfolioConstructionResult) -> go.Figure

Plot covariance risk contributions reported for target portfolios.

plot_backtest_returns(result: BacktestResult, *, include_benchmarks: bool = True) -> go.Figure

Plot reconciled net returns with optional simulated benchmarks.

plot_backtest_performance(result: BacktestResult, *, include_benchmarks: bool = True, yscale: Literal['auto', 'linear', 'log'] = 'auto') -> go.Figure

Plot cumulative net performance with optional simulated benchmarks.

plot_backtest_drawdowns(result: BacktestResult, *, include_benchmarks: bool = True) -> go.Figure

Plot strategy drawdown with optional benchmark drawdowns.

plot_backtest_rolling_volatility(result: BacktestResult, *, window: int, periods_per_year: float, include_benchmarks: bool = True) -> go.Figure

Calculate and plot annualized rolling volatility under explicit parameters.

plot_portfolio_turnover(result: PortfolioResult) -> go.Figure

Plot reported one-way turnover through time.

plot_transaction_costs(result: BacktestResult) -> go.Figure

Plot total transaction-cost return deductions through time.

plot_return_attribution(result: BacktestResult, *, groups: Mapping[Any, str] | None = None, include_cash: bool = True) -> go.Figure

Plot reconciled period gross-return attribution by asset or supplied group.

plot_cost_attribution(result: BacktestResult, *, groups: Mapping[Any, str] | None = None) -> go.Figure

Plot reconciled transaction-cost attribution by asset or supplied group.

plot_rebalance_diagnostics(result: BacktestResult) -> go.Figure

Plot target-versus-realized rebalance differences and blocked assets.

_add_named_reference(result: go.Figure, value: float, *, name: str, color: str, dash: str) -> None

_weight_panel(result: PortfolioResult, *, kind: WeightKind) -> tuple[pd.DataFrame, pd.Series]

_aggregate_attribution(frame: pd.DataFrame, *, groups: Mapping[Any, str] | None) -> pd.DataFrame

_timing_title(result: BacktestResult) -> str