chaotic_pfc.analysis.stats¶

Statistical analysis of Lyapunov sweep results.

Provides quick programmatic access to the full sweep dataset: summary tables, regime classification, parameter ranking, and comparisons across windows, filter types, and Kaiser beta sweeps.

Return types¶

All public functions that return dict have corresponding TypedDict definitions in this module so that IDE autocompletion and mypy can statically verify the result shape:

SummaryRow — one row of summary_table()
FilterTypeAggregate — output of compare_filter_types()
OptimalParams — one entry of optimal_parameters()
LmaxDistribution — output of lmax_distribution()
CorrelationMatrix — output of correlation_matrix()
BootstrapConfidence — one entry of bootstrap_confidence()

Functions

`area_summary`(sweep_result)	Compute chaotic-area coverage for a single sweep.
`best_chaos_preserving`([data_dir, top_n])	Rank sweeps by percentage of chaotic grid points (descending).
`beta_curve`([data_dir, filter_type])	Return (betas, pct_chaotic) arrays for a single filter type.
`beta_summary`([data_dir])	Aggregate per-β statistics for each filter type.
`bootstrap_confidence`([data_dir, ...])	Bootstrap 95% CI for mean λ_max per filter type.
`chaos_margin`([data_dir, window, filter_type])	For each order, compute the width of the chaotic region in cutoff space.
`compare_filter_types`([data_dir])	Aggregate statistics per filter type across all windows.
`consolidate_kaiser`(sweep_results)	Keep only the best Kaiser β per filter type, by chaotic point count.
`correlation_matrix`([data_dir])	Spearman correlation between (order, cutoff, λ_max) across all sweeps.
`export_summary_json`([data_dir, output])	Write the full summary table to a JSON file.
`kaiser_beta_optimal`(sweep_results[, ...])	Report the best Kaiser β per filter type with extended statistics.
`lmax_distribution`([data_dir, bins])	Histogram of λ_max values per filter type.
`lmax_statistics`(sweep_result[, region, ...])	Compute descriptive statistics of \(\lambda_{\max}\) for a subset of grid points.
`load_all_sweeps`([sweep_dir])	Load every `variables_lyapunov.npz` under sweep_dir.
`optimal_parameters`([data_dir, window, ...])	Find the (order, cutoff) pairs with the highest λ_max.
`rank_configurations`(sweep_results[, ...])	Rank every (filter_type, window) combination by chaotic grid-point count.
`summary_table`([data_dir])	Return one row per sweep with key statistics.
`sweet_spot_per_filter`(sweep_results)	Identify the grid point with the highest \(\lambda_{\max}\) per filter type.
`top_k_per_filter`(sweep_results[, k, ...])	Return the top-k configurations for each filter type.
`transition_boundary`([data_dir, window, ...])	Find the cutoff where each order transitions from non-chaotic to chaotic.

Classes

`AreaSummary`	Chaotic-area breakdown for a single `SweepResult`.
`BootstrapConfidence`	Bootstrap 95% CI entry for one filter type.
`ConfigRank`	One entry of `rank_configurations()`.
`CorrelationMatrix`	Spearman correlation results from `correlation_matrix()`.
`FilterTypeAggregate`	Aggregate statistics for a single filter type.
`KaiserBetaOptimal`	Best Kaiser β per filter type (by chaotic area).
`LmaxDistribution`	Distribution statistics for lambda_max per filter type.
`LmaxStats`	Descriptive statistics of \(\lambda_{\max}\) for a subset of points.
`OptimalParams`	One optimal (order, cutoff) pair from `optimal_parameters()`.
`SummaryRow`	One row of `summary_table()`.
`SweetSpot`	Single grid point with the highest \(\lambda_{\max}\) for one filter type.

class chaotic_pfc.analysis.stats.SummaryRow[source]¶

Bases: TypedDict

One row of summary_table().

window: str¶

filter_type: str¶

n_orders: int¶

n_cutoffs: int¶

pct_chaotic: float¶

pct_periodic: float¶

pct_divergent: float¶

mean_lmax: float¶

max_lmax: float¶

beta: float | None¶

class chaotic_pfc.analysis.stats.FilterTypeAggregate[source]¶

Bases: TypedDict

Aggregate statistics for a single filter type.

n_sweeps: int¶

mean_pct_chaotic: float¶

mean_pct_periodic: float¶

mean_pct_divergent: float¶

mean_lmax: float¶

class chaotic_pfc.analysis.stats.OptimalParams[source]¶

Bases: TypedDict

One optimal (order, cutoff) pair from optimal_parameters().

window: str¶

filter_type: str¶

order: int¶

cutoff: float¶

lmax: float¶

class chaotic_pfc.analysis.stats.LmaxDistribution[source]¶

Bases: TypedDict

Distribution statistics for lambda_max per filter type.

Returned by lmax_distribution().

hist: list[float]¶

edges: list[float]¶

mean: float¶

std: float¶

skewness: float¶

n: int¶

class chaotic_pfc.analysis.stats.CorrelationMatrix[source]¶

Bases: TypedDict

Spearman correlation results from correlation_matrix().

order_vs_lmax: float¶

cutoff_vs_lmax: float¶

n: int¶

class chaotic_pfc.analysis.stats.BootstrapConfidence[source]¶

Bases: TypedDict

Bootstrap 95% CI entry for one filter type.

mean: float¶

ci_low: float¶

ci_high: float¶

n: int¶

class chaotic_pfc.analysis.stats.AreaSummary[source]¶

Bases: TypedDict

Chaotic-area breakdown for a single SweepResult.

Returned by area_summary().

n_chaotic: int¶

n_periodic: int¶

n_divergent: int¶

n_total: int¶

pct_chaotic: float¶

pct_chaotic_finite: float¶

class chaotic_pfc.analysis.stats.LmaxStats[source]¶

Bases: TypedDict

Descriptive statistics of \(\lambda_{\max}\) for a subset of points.

Returned by lmax_statistics().

mean: float¶

median: float¶

std: float¶

min: float¶

max: float¶

ci_95_low: float¶

ci_95_high: float¶

n_used: int¶

class chaotic_pfc.analysis.stats.ConfigRank[source]¶

Bases: TypedDict

One entry of rank_configurations().

Ranks a (filter_type, window) combination by chaotic-area coverage. Kaiser-beta sweeps include the beta value and a synthetic window key.

rank: int¶

filter_type: str¶

window: str¶

n_chaotic: int¶

pct_chaotic: float¶

pct_chaotic_finite: float¶

lmax_mean: float¶

lmax_max: float¶

lmax_std: float¶

lmax_ci_95_low: float¶

lmax_ci_95_high: float¶

beta: float | None¶

class chaotic_pfc.analysis.stats.SweetSpot[source]¶

Bases: TypedDict

Single grid point with the highest \(\lambda_{\max}\) for one filter type.

Returned per filter type by sweet_spot_per_filter().

filter_type: str¶

window: str¶

n_z: int¶

omega_c: float¶

lmax: float¶

lmax_ci_95_low: float | None¶

lmax_ci_95_high: float | None¶

class chaotic_pfc.analysis.stats.KaiserBetaOptimal[source]¶

Bases: TypedDict

Best Kaiser β per filter type (by chaotic area).

Returned by kaiser_beta_optimal().

filter_type: str¶

beta: float¶

n_chaotic: int¶

pct_chaotic_finite: float¶

lmax_mean: float¶

lmax_max: float¶

chaotic_pfc.analysis.stats.summary_table(data_dir='data/sweeps')[source]¶

Return one row per sweep with key statistics.

Each row is a SummaryRow with: window, filter_type, n_orders, n_cutoffs, pct_chaotic, pct_periodic, pct_divergent, mean_lmax, max_lmax, beta (Kaiser only).

This is the foundation of all downstream analyses — every other public function in this module either calls or derives from this table.

Parameters:: data_dir (str | Path)
Return type:: list[SummaryRow]

chaotic_pfc.analysis.stats.area_summary(sweep_result)[source]¶

Compute chaotic-area coverage for a single sweep.

Classifies each grid point (order, cutoff) as chaotic (\(\lambda_{\max} > 0\), finite), periodic (\(\lambda_{\max} \le 0\), finite), or divergent (NaN or Inf). Returns absolute counts and two complementary percentages: one over the full grid, another excluding divergent points so the chaotic proportion is not artificially deflated by parameter regions where the FIR filter itself becomes ill-conditioned.

Parameters:: sweep_result (SweepResult) – A loaded sweep.
Returns:: Counts and percentages for the three dynamical regimes.
Return type:: AreaSummary

chaotic_pfc.analysis.stats.lmax_statistics(sweep_result, region='chaotic', n_bootstrap=1000, seed=42)[source]¶

Compute descriptive statistics of \(\lambda_{\max}\) for a subset of grid points.

Filters the sweep grid by dynamical regime then computes mean, median, standard deviation, min, max, and a bootstrap 95% confidence interval for the mean.

Parameters:

sweep_result (SweepResult)
region ({"chaotic", "all_finite", "periodic"}) – Subset of grid points to include: * "chaotic" — only points with \(\lambda_{\max} > 0\) (finite) * "all_finite" — all finite points (excludes NaN/Inf) * "periodic" — only points with \(\lambda_{\max} \le 0\) (finite)
n_bootstrap (int) – Number of bootstrap resamples (default 1000).
seed (int) – RNG seed for reproducibility (default 42).

Returns:

Descriptive statistics including bootstrap 95% CI. When fewer than 3 valid points exist, the CI fields are NaN.

Return type:

LmaxStats

chaotic_pfc.analysis.stats.load_all_sweeps(sweep_dir='data/sweeps')[source]¶

Load every variables_lyapunov.npz under sweep_dir.

Returns a dict keyed by (filter_type, window) for non-Kaiser sweeps or (filter_type, "kaiser_<beta>") for Kaiser beta-sweeps. Results are cached in memory so repeated calls are free.

Parameters:: sweep_dir (str | Path) – Root directory containing per-configuration subdirectories and an optional kaiser/<filter_type>/beta_<N> subtree.
Returns:: Mapping from (filter_type, window_key) to SweepResult.
Return type:: dict

chaotic_pfc.analysis.stats.rank_configurations(sweep_results, bootstrap_seed=42)[source]¶

Rank every (filter_type, window) combination by chaotic grid-point count.

Parameters:

sweep_results (dict[tuple[str, str], SweepResult]) – Mapping from (filter_type, window_key) to a loaded sweep. Typically obtained via load_all_sweeps().
bootstrap_seed (int) – RNG seed forwarded to lmax_statistics() (default 42).

Returns:

Descending by n_chaotic. Rank is 1-indexed.

Return type:

list of ConfigRank

chaotic_pfc.analysis.stats.top_k_per_filter(sweep_results, k=3, bootstrap_seed=42)[source]¶

Return the top-k configurations for each filter type.

Calls rank_configurations() internally, then groups the global ranking by filter_type, keeping at most k entries per group.

Parameters:

sweep_results (dict[tuple[str, str], SweepResult]) – Mapping from (filter_type, window_key) to loaded sweeps.
k (int) – Maximum number of entries per filter type (default 3).
bootstrap_seed (int) – Forwarded to rank_configurations().

Returns:

Keys are filter types; values are lists of at most k ConfigRank entries, ordered by descending n_chaotic.

Return type:

dict of str → list of ConfigRank

chaotic_pfc.analysis.stats.consolidate_kaiser(sweep_results)[source]¶

Keep only the best Kaiser β per filter type, by chaotic point count.

Non-Kaiser windows are passed through unchanged. This produces a balanced dataset where each window family appears once per filter type, making window-to-window comparisons fair.

Parameters:: sweep_results (dict[tuple[str, str], SweepResult]) – Mapping from load_all_sweeps().
Returns:: Same shape as sweep_results, but with at most one Kaiser entry per filter_type (the β with the most chaotic points).
Return type:: dict

chaotic_pfc.analysis.stats.kaiser_beta_optimal(sweep_results, bootstrap_seed=42)[source]¶

Report the best Kaiser β per filter type with extended statistics.

Parameters:

sweep_results (dict[tuple[str, str], SweepResult]) – Mapping from load_all_sweeps().
bootstrap_seed (int) – Forwarded to lmax_statistics().

Return type:

dict of str → KaiserBetaOptimal

chaotic_pfc.analysis.stats.sweet_spot_per_filter(sweep_results)[source]¶

Identify the grid point with the highest \(\lambda_{\max}\) per filter type.

For each filter type, scans all available window sweeps and returns the exact (N_z, omega_c, window) where lambda_max is globally maximal.

The 95% confidence interval is computed from the per-point standard deviation h_std and n_initial metadata via the t-distribution. If h_std is NaN or n_initial is unavailable, the CI fields are None.

Parameters:: sweep_results (dict[tuple[str, str], SweepResult]) – Mapping from (filter_type, window_key) to loaded sweeps.
Returns:: One entry per filter type that has at least one finite point.
Return type:: dict of str → SweetSpot

chaotic_pfc.analysis.stats.best_chaos_preserving(data_dir='data/sweeps', top_n=5)[source]¶

Rank sweeps by percentage of chaotic grid points (descending).

Returns the top_n entries with the most chaotic coverage.

Parameters:

data_dir (str | Path)
top_n (int)

Return type:

list[SummaryRow]

chaotic_pfc.analysis.stats.compare_filter_types(data_dir='data/sweeps')[source]¶

Aggregate statistics per filter type across all windows.

Returns a dict keyed by filter type ("lowpass", …) with each value being a FilterTypeAggregate containing mean percentages and lambda_max across all windows that use that filter type.

Parameters:: data_dir (str | Path)
Return type:: dict[str, FilterTypeAggregate]

chaotic_pfc.analysis.stats.optimal_parameters(data_dir='data/sweeps', window=None, filter_type=None, top_n=3)[source]¶

Find the (order, cutoff) pairs with the highest λ_max.

Filters results by window and filter_type if given.

Parameters:

data_dir (str | Path)
window (str | None)
filter_type (str | None)
top_n (int)

Return type:

list[OptimalParams]

chaotic_pfc.analysis.stats.export_summary_json(data_dir='data/sweeps', output='data/analysis_summary.json')[source]¶

Write the full summary table to a JSON file.

Parameters:

data_dir (str | Path)
output (str | Path)

Return type:

Path

chaotic_pfc.analysis.stats.beta_summary(data_dir='data/sweeps/kaiser')[source]¶

Aggregate per-β statistics for each filter type.

Returns a nested dict: {filter_type: {beta: {pct_chaotic, mean_lmax, ...}}}

Parameters:: data_dir (str | Path)
Return type:: dict[str, dict[float, dict]]

chaotic_pfc.analysis.stats.beta_curve(data_dir='data/sweeps/kaiser', filter_type='lowpass')[source]¶

Return (betas, pct_chaotic) arrays for a single filter type.

Useful for plotting the β-dependence of chaotic coverage. Returns empty arrays when filter_type is absent from the data.

Parameters:

data_dir (str | Path)
filter_type (str)

Return type:

tuple[ndarray[tuple[Any, …], dtype[_ScalarT]], ndarray[tuple[Any, …], dtype[_ScalarT]]]

chaotic_pfc.analysis.stats.lmax_distribution(data_dir='data/sweeps', bins=50)[source]¶

Histogram of λ_max values per filter type.

Returns:

{filter_type: {"hist": counts, "edges": bin_edges, "mean": float, "std": float, "skewness": float, "n": int}}

Return type:

dict

Parameters:

data_dir (str | Path)
bins (int)

chaotic_pfc.analysis.stats.transition_boundary(data_dir='data/sweeps', window=None, filter_type='lowpass')[source]¶

Find the cutoff where each order transitions from non-chaotic to chaotic.

For each order, returns the first cutoff (lowest frequency) where λ_max > 0, or NaN if no chaotic point exists.

Returns:

orders (ndarray) – Filter orders.
cutoffs (ndarray) – First chaotic cutoff per order (NaN if never chaotic).

Parameters:

data_dir (str | Path)
window (str | None)
filter_type (str)

Return type:

tuple[ndarray[tuple[Any, …], dtype[_ScalarT]], ndarray[tuple[Any, …], dtype[_ScalarT]]]

chaotic_pfc.analysis.stats.chaos_margin(data_dir='data/sweeps', window=None, filter_type='lowpass')[source]¶

For each order, compute the width of the chaotic region in cutoff space.

Returns:

orders (ndarray)
widths (ndarray) – Fraction of cutoffs where λ_max > 0 per order.

Parameters:

data_dir (str | Path)
window (str | None)
filter_type (str)

Return type:

tuple[ndarray[tuple[Any, …], dtype[_ScalarT]], ndarray[tuple[Any, …], dtype[_ScalarT]]]

chaotic_pfc.analysis.stats.correlation_matrix(data_dir='data/sweeps')[source]¶

Spearman correlation between (order, cutoff, λ_max) across all sweeps.

Returns:: {"order_vs_lmax": rho, "cutoff_vs_lmax": rho, "n": int}
Return type:: dict
Parameters:: data_dir (str | Path)

chaotic_pfc.analysis.stats.bootstrap_confidence(data_dir='data/sweeps', n_bootstrap=1000, seed=42)[source]¶

Bootstrap 95% CI for mean λ_max per filter type.

Returns:

{filter_type: {"mean": float, "ci_low": float, "ci_high": float}}

Return type:

dict

Parameters:

data_dir (str | Path)
n_bootstrap (int)
seed (int)