smftools.analysis.compute.autocorrelation

autocorrelation.py — NaN-aware binary autocorrelation over irregularly spaced positions.

Core functions

binary_autocorrelation_with_spacing Per-read ACF over gapped binary positions. weighted_mean_autocorr Combine per-read ACF curves with lag-count weights. compute_replicate_curve Coverage-filter a matrix then compute its mean ACF. compute_single_molecule_periodicity Per-read LS via ACF intermediate (ensemble method). compute_single_molecule_periodicity_direct Per-read LS directly on raw signal (direct method).

These functions are independent of project constants. Pass positions, matrices, and threshold values as explicit parameters.

Functions

binary_autocorrelation_with_spacing(row, ...)	NaN-aware autocorrelation over irregularly spaced binary positions.
compute_replicate_curve(mat, positions[, ...])	Coverage-filter a read × position matrix then compute its weighted mean ACF.
compute_single_molecule_periodicity(mat, ...)	Per-read Lomb-Scargle periodicity from individual ACF curves.
compute_single_molecule_periodicity_direct(...)	Per-read Lomb-Scargle periodicity directly from raw C-site binary signal.
weighted_mean_autocorr(ac_matrix, counts_matrix)	Combine read-wise ACF curves using lag-specific pair counts as weights.

smftools.analysis.compute.autocorrelation.binary_autocorrelation_with_spacing(row, positions, max_lag=1000, return_counts=False)

NaN-aware autocorrelation over irregularly spaced binary positions.

Return type:

ndarray | tuple[ndarray, ndarray]

Parameters

row : 1-D float array (values 0/1/NaN); NaN = no coverage at that position. positions : 1-D int array of TSS-centred coordinates matching row. max_lag : maximum lag in base pairs to compute. return_counts : if True, return (ac, counts) where counts[lag] = number of pairs.

Returns

ac : float32 array of length (max_lag + 1); NaN where counts == 0. counts : int64 array of length (max_lag + 1) [only if return_counts=True]

smftools.analysis.compute.autocorrelation.weighted_mean_autocorr(ac_matrix, counts_matrix, min_count_per_lag=10)

Combine read-wise ACF curves using lag-specific pair counts as weights.

Return type:

tuple[ndarray, ndarray]

Parameters

ac_matrix : (n_reads × n_lags) float; NaN where a read had no pairs at that lag. counts_matrix : (n_reads × n_lags) int; number of pairs per read per lag. min_count_per_lag : lags with fewer total pairs are set to NaN in the output.

Returns

mean_ac : 1-D float array of length n_lags total_counts : 1-D int array of length n_lags

smftools.analysis.compute.autocorrelation.compute_replicate_curve(mat, positions, max_lag=1000, min_col_coverage=0.05, min_row_coverage=0.05, min_reads=5, min_count_per_lag=10)

Coverage-filter a read × position matrix then compute its weighted mean ACF.

Return type:

tuple[ndarray, ndarray] | None

Parameters

mat : (n_reads × n_positions) float; NaN = no coverage. positions : TSS-centred int coordinates matching mat columns.

Returns (mean_ac, total_counts) or None if too few reads survive filtering.

smftools.analysis.compute.autocorrelation.compute_single_molecule_periodicity(mat, positions, max_lag=1000, min_col_coverage=0.05, min_row_coverage=0.05, nrl_search_bp=(150, 250), period_range_bp=(80, 400))

Per-read Lomb-Scargle periodicity from individual ACF curves.

Coverage-filters columns as in compute_replicate_curve(), then for each surviving read computes its own ACF (binary_autocorrelation_with_spacing()) and runs ls_periodicity.analyze_ls_periodicity() on it directly — no pooling across reads.

Reads with too few finite lags or no detectable peak in nrl_search_bp are dropped (see ls_periodicity.MIN_FINITE_LAGS).

Return type:

DataFrame

Parameters

mat : (n_reads × n_positions) float; NaN = no coverage. positions : TSS-centred int coordinates matching mat columns.

Returns

pd.DataFrame with one row per surviving read and columns: row_index (index into the input mat first axis), n_finite_lags, ls_nrl_bp, ls_snr, ls_peak_power, ls_fwhm_bp.

smftools.analysis.compute.autocorrelation.compute_single_molecule_periodicity_direct(mat, positions, min_col_coverage=0.05, min_row_coverage=0.05, nrl_search_bp=(150, 250), period_range_bp=(150, 250), poly_degree=2, min_sites=40)

Per-read Lomb-Scargle periodicity directly from raw C-site binary signal.

Runs LS on each read's accessibility signal without an ACF intermediate step. A polynomial detrend removes slow accessibility gradients along the locus. More reliable than compute_single_molecule_periodicity() for sparse single-molecule data where per-read ACF curves have few pairs per lag.

Return type:

DataFrame

Parameters

mat : (n_reads × n_positions) float; NaN = no coverage. positions : TSS-centred int coordinates matching mat columns.

Returns

pd.DataFrame with one row per surviving read and columns: row_index, n_sites, ls_nrl_bp, ls_snr, ls_peak_power, ls_fwhm_bp, ls_freqs (array), ls_power (array). Drop ls_freqs/ls_power before saving to CSV.