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

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.
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.
lmax_distribution([data_dir, bins])	Histogram of λ_max values per filter type.
optimal_parameters([data_dir, window, ...])	Find the (order, cutoff) pairs with the highest λ_max.
summary_table([data_dir])	Return one row per sweep with key statistics.
transition_boundary([data_dir, window, ...])	Find the cutoff where each order transitions from non-chaotic to chaotic.

Classes

BootstrapConfidence	Bootstrap 95% CI entry for one filter type.
CorrelationMatrix	Spearman correlation results from correlation_matrix().
FilterTypeAggregate	Aggregate statistics for a single filter type.
LmaxDistribution	Distribution statistics for lambda_max per filter type.
OptimalParams	One optimal (order, cutoff) pair from optimal_parameters().
SummaryRow	One row of summary_table().

class chaotic_pfc.analysis.stats.SummaryRow

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

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

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

Bases: TypedDict

Distribution statistics for lambda_max per filter type.

n: int

mean: float

std: float

skewness: float

min: float

max: float

p25: float

p50: float

p75: float

class chaotic_pfc.analysis.stats.CorrelationMatrix

Bases: TypedDict

Spearman correlation results from correlation_matrix().

order_vs_lmax: float

cutoff_vs_lmax: float

n: int

class chaotic_pfc.analysis.stats.BootstrapConfidence

Bases: TypedDict

Bootstrap 95% CI entry for one filter type.

mean: float

ci_low: float

ci_high: float

n: int

chaotic_pfc.analysis.stats.summary_table(data_dir='data/sweeps')

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[dict]

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

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[dict]

chaotic_pfc.analysis.stats.compare_filter_types(data_dir='data/sweeps')

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, dict]

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

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[dict]

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

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')

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')

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

Useful for plotting the β-dependence of chaotic coverage.

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)

Histogram of λ_max values per filter type.

Returns:

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

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')

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')

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')

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)

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)