API reference

Everything below is importable from the top-level package, for example statespacecheck.event_diagnostics.

Per-spike diagnostics

The paper's method: HPD overlap, KL divergence and the rank-based predictive p-value for every spike, thresholds from a baseline period, and flagging.

• EventDiagnostics: Per-event diagnostic values: HPD overlap, KL divergence and the p-value.
• EventFlags: Per-event flags returned by flag_events.
• baseline_threshold: Estimate a flagging threshold from baseline per-event diagnostic values.
• event_diagnostics: Compute HPD overlap, KL divergence, and predictive p-value for every event.
• event_likelihood: Normalize event intensities over the state space.
• event_weighted_predictive: Compute the state distribution of the next event.
• flag_events: Flag events whose diagnostics indicate poor local fit.
• mark_predictive_pvalue: Exact predictive p-value of each event's observed mark.
• predictive_mark_probabilities: Compute the predictive probability of each mark for the next event.

Continuous marks

The per-spike diagnostics, with the predictive p-value by Monte Carlo, for marks that cannot be enumerated, such as the waveform features of clusterless decoding.

• MarkModel: A marked point-process observation model, as the continuous-mark functions take it.
• MarkPredictiveCheck: Result of monte_carlo_mark_pvalue.
• clusterless_event_diagnostics: Compute HPD overlap, KL divergence, and predictive p-value for events with any marks.
• monte_carlo_mark_pvalue: Monte Carlo predictive p-value of each event's observed mark.

Comparing distributions

HPD overlap and KL divergence between a state distribution and a likelihood, for each row; used per spike by event_diagnostics and clusterless_event_diagnostics, or per time bin with a whole-bin likelihood (an extension beyond the paper).

• hpd_overlap: Compute overlap between HPD regions of state distribution and likelihood.
• kl_divergence: Compute Kullback-Leibler divergence between state distribution and likelihood.

Highest-density regions

The regions HPD overlap compares.

• highest_density_region: Compute boolean mask indicating highest density region membership.

Predictive densities and Monte Carlo checks

An extension beyond the paper: predictive densities of whole time bins and a Monte Carlo predictive p-value with a user-supplied sampler.

• log_predictive_density: Compute log predictive density directly in log-space using logsumexp.
• predictive_density: Compute predictive density by integrating state dist with obs likelihood.
• predictive_pvalue: Compute predictive p-value via Monte Carlo sampling.

Flagging time series

An extension beyond the paper: flagging runs of time bins and aggregating over periods. For per-spike values use flag_events.

• aggregate_over_period: Aggregate metric values over specified time period.
• combine_flags: Majority-vote combination of multiple boolean flag arrays.
• find_low_overlap_intervals: Find runs of at least min_len time points with HPD overlap at or below a threshold.
• flag_extreme_kl: Flag times where KL divergence is extreme relative to the rest of the recording.
• flag_extreme_pvalues: Flag time points whose predictive p-value is at or below a cutoff.
• flag_low_overlap: Flag times where HPD overlap is at or below a threshold.

Plotting

An extension beyond the paper: time-series plots of the diagnostics.

• plot_diagnostics: Plot HPD overlap, KL divergence (with its robust z-score), and p-values.

Types and constants

• DistributionArray: the type of the float64 arrays the functions return, numpy.typing.NDArray[numpy.float64]. Inputs may be any array-like.
• DEFAULT_COVERAGE: the default coverage of HPD regions, 0.95, as in the paper.
• LogMarkIntensity and MarkSampler: the types of the model functions a MarkModel holds.