smftools.analysis.compute.ls_periodicity

ls_periodicity.py — Lomb-Scargle periodogram utilities for nucleosome analysis.

Two input modes

ACF-based (ensemble): ls_periodogram_from_autocorr / analyze_ls_periodicity

Input: (lags, autocorr) pairs derived from a weighted-mean ACF curve. Best for replicate-level curves where many reads contribute to each lag.

Direct-signal (per-read): ls_periodogram_from_signal / analyze_ls_periodicity_direct

Input: (positions, signal) — raw C_site_binary values at genomic positions. Polynomial-detrends to remove slow accessibility gradients, then runs LS directly without an ACF intermediate step. More reliable for sparse single-molecule data where the per-read ACF has few pairs per lag.

Key difference from FFT

FFT: zero-pads NaN lags → gaps alter spectral shape and SNR. LS: drops NaN lags entirely → spectrum reflects only observed data.

Usage

result = analyze_ls_periodicity(lags, ac_values) # ACF path result = analyze_ls_periodicity_direct(positions, signal) # direct path # Both return None on failure, else dict with ls_nrl_bp, ls_snr, ls_peak_power, # ls_peak_power_raw, ls_fwhm_bp, ls_freqs, ls_power, ls_power_raw

Functions

analyze_fft_periodicity(lags, ac_vals[, ...])	FFT periodicity analysis on a smoothed autocorrelation curve.
analyze_ls_periodicity(lags, ac_vals[, ...])	Full LS periodicity analysis on a (lag, autocorr) sequence.
analyze_ls_periodicity_direct(positions, signal)	Full LS periodicity analysis on raw C-site binary signal (direct method).
find_peak_ls(freqs, power[, nrl_search_bp, ...])	Find the dominant LS peak in the NRL search band.
fwhm_ls(freqs, power, peak_idx)	Estimate FWHM in base pairs for a spectral peak.
ls_periodogram_from_autocorr(lags, ac_vals)	Compute Lomb-Scargle periodogram from (lag, autocorr) pairs.
ls_periodogram_from_signal(positions, signal)	Lomb-Scargle periodogram from raw C-site binary signal at genomic positions.
psd_from_autocorr(mean_ac, lags[, pad_factor])	FFT power spectrum from an autocorrelation curve, zero-filling NaN lags.
rolling_mean_nan(x[, window])	Centered rolling mean that ignores NaNs.
snr_ls(power, peak_idx[, exclude_bins])	Estimate SNR around a spectral peak.

smftools.analysis.compute.ls_periodicity.ls_periodogram_from_autocorr(lags, ac_vals, period_range_bp=(150, 250))

Compute Lomb-Scargle periodogram from (lag, autocorr) pairs.

Returns (freqs, power_norm, power_raw) or (None, None, None) on failure.

Return type:

tuple[ndarray, ndarray, ndarray] | tuple[None, None, None]

smftools.analysis.compute.ls_periodicity.find_peak_ls(freqs, power, nrl_search_bp=(150, 250), prominence_frac=0.05)

Find the dominant LS peak in the NRL search band.

Return type:

tuple[float, int] | tuple[None, None]

smftools.analysis.compute.ls_periodicity.fwhm_ls(freqs, power, peak_idx)

Estimate FWHM in base pairs for a spectral peak.

Return type:

float

smftools.analysis.compute.ls_periodicity.snr_ls(power, peak_idx, exclude_bins=5)

Estimate SNR around a spectral peak. Returns (snr, peak_power, bg_median).

Return type:

tuple[float, float, float]

smftools.analysis.compute.ls_periodicity.analyze_ls_periodicity(lags, ac_vals, nrl_search_bp=(150, 250), period_range_bp=(150, 250))

Full LS periodicity analysis on a (lag, autocorr) sequence.

Returns dict with keys: ls_nrl_bp, ls_snr, ls_peak_power, ls_peak_power_raw, ls_fwhm_bp, ls_freqs, ls_power, ls_power_raw — or None on failure.

Return type:

dict | None

smftools.analysis.compute.ls_periodicity.ls_periodogram_from_signal(positions, signal, period_range_bp=(150, 250), poly_degree=2, min_sites=40)

Lomb-Scargle periodogram from raw C-site binary signal at genomic positions.

Runs LS directly on the (positions, signal) pairs without an ACF intermediate. A polynomial of degree poly_degree is subtracted to remove slow accessibility gradients before the spectral analysis.

Return type:

tuple[ndarray, ndarray, ndarray] | tuple[None, None, None]

Parameters

positions : 1-D array of genomic coordinates (bp, TSS-centred). signal : 1-D float array of C_site_binary values (0/1/NaN); NaN = not covered. period_range_bp : (min_period, max_period) in bp for the frequency grid. poly_degree : degree of detrending polynomial (default 2). min_sites : minimum finite sites required to attempt scoring.

Returns

(freqs, power_norm, power_raw) on success, or (None, None, None) on failure. Uses the same frequency grid as ls_periodogram_from_autocorr() so find_peak_ls(), snr_ls(), and fwhm_ls() apply unchanged.

smftools.analysis.compute.ls_periodicity.analyze_ls_periodicity_direct(positions, signal, nrl_search_bp=(150, 250), period_range_bp=(150, 250), poly_degree=2, min_sites=40)

Full LS periodicity analysis on raw C-site binary signal (direct method).

Equivalent to analyze_ls_periodicity() but takes (positions, signal) instead of (lags, ac_vals). Returns the same dict structure so downstream callers (peak-power histograms, NRL barplots) are interchangeable.

Return type:

dict | None

Parameters

positions : 1-D array of genomic coordinates (bp, TSS-centred). signal : 1-D float array of C_site_binary values (0/1/NaN).

Returns

dict with keys: ls_nrl_bp, ls_snr, ls_peak_power, ls_peak_power_raw, ls_fwhm_bp, ls_freqs, ls_power, ls_power_raw — or None on failure.

smftools.analysis.compute.ls_periodicity.rolling_mean_nan(x, window=25)

Centered rolling mean that ignores NaNs.

Return type:

ndarray

smftools.analysis.compute.ls_periodicity.psd_from_autocorr(mean_ac, lags, pad_factor=4)

FFT power spectrum from an autocorrelation curve, zero-filling NaN lags.

Return type:

tuple[ndarray, ndarray]

smftools.analysis.compute.ls_periodicity.analyze_fft_periodicity(lags, ac_vals, smoothing_window=25, nrl_search_bp=(150, 250))

FFT periodicity analysis on a smoothed autocorrelation curve.

Return type:

dict | None