smftools.tools.spatial_autocorrelation

smftools.tools.spatial_autocorrelation#

Functions

analyze_autocorr_matrix(autocorr_matrix, ...)

Analyze autocorrelation matrix and extract periodicity metrics.

binary_autocorrelation_with_spacing(row, ...)

Compute autocorrelation over genomic spacing.

bootstrap_periodicity(autocorr_matrix, ...)

Bootstrap periodicity metrics from autocorrelation matrices.

estimate_snr(power, peak_idx[, exclude_bins])

Estimate signal-to-noise ratio around a spectral peak.

find_peak_in_nrl_band(freqs, power[, ...])

Find the peak frequency in the nucleosome repeat length band.

fit_exponential_envelope(sample_lags, heights)

Fit an exponential envelope to sampled autocorrelation peaks.

fwhm_freq_to_bp(freqs, power, peak_idx)

Estimate FWHM in base pairs for a spectral peak.

psd_from_autocorr(mean_ac, lags[, pad_factor])

Compute a power spectral density from autocorrelation.

random_fill_nans(X)

Fill NaNs with random values in-place.

rolling_autocorr_metrics(X, positions[, ...])

Slide a genomic window across positions and compute periodicity metrics.

sample_autocorr_at_harmonics(mean_ac, lags, ...)

Sample autocorrelation heights at NRL harmonics.

weighted_mean_autocorr(ac_matrix, counts_matrix)

Compute weighted mean autocorrelation per lag.
smftools.tools.spatial_autocorrelation.random_fill_nans(X)#

Fill NaNs with random values in-place.

Parameters:

X (ndarray[Any, dtype[floating]]) -- Input array containing NaNs.

Returns:

Array with NaNs replaced by random values.

Return type:

numpy.ndarray

smftools.tools.spatial_autocorrelation.binary_autocorrelation_with_spacing(row, positions, max_lag=1000, assume_sorted=True, normalize='sum', return_counts=False)#

Compute autocorrelation over genomic spacing.

Parameters:

  • row (ndarray[Any, dtype[floating]]) -- Values per position (NaN = missing).

  • positions (ndarray[Any, dtype[integer]]) -- Genomic coordinates for each column of row.

  • max_lag (int (default: 1000)) -- Max genomic lag (inclusive).

  • assume_sorted (bool (default: True)) -- Whether positions are sorted.

  • normalize (str (default: 'sum')) -- "sum" or "pearson" normalization.

  • return_counts (bool (default: False)) -- Whether to return lag counts alongside autocorrelation.

Returns:

Autocorrelation values and optionally counts per lag.

Return type:

numpy.ndarray | tuple[numpy.ndarray, numpy.ndarray]

smftools.tools.spatial_autocorrelation.weighted_mean_autocorr(ac_matrix, counts_matrix, min_count=20)#

Compute weighted mean autocorrelation per lag.

Parameters:

  • ac_matrix -- Autocorrelation matrix per molecule.

  • counts_matrix -- Pair counts per lag.

  • min_count (default: 20) -- Minimum total count required to keep a lag.

Returns:

Mean autocorrelation and total counts.

Return type:

tuple[numpy.ndarray, numpy.ndarray]

smftools.tools.spatial_autocorrelation.psd_from_autocorr(mean_ac, lags, pad_factor=4)#

Compute a power spectral density from autocorrelation.

Parameters:
Returns:

Frequencies and power values.

Return type:

tuple[numpy.ndarray, numpy.ndarray]

smftools.tools.spatial_autocorrelation.find_peak_in_nrl_band(freqs, power, nrl_search_bp=(120, 260), prominence_frac=0.05)#

Find the peak frequency in the nucleosome repeat length band.

Parameters:
Returns:

Peak frequency and index, or (None, None).

Return type:

tuple[float | None, int | None]

smftools.tools.spatial_autocorrelation.fwhm_freq_to_bp(freqs, power, peak_idx)#

Estimate FWHM in base pairs for a spectral peak.

Parameters:
Returns:

FWHM in bp and left/right frequencies.

Return type:

tuple[float, float, float]

smftools.tools.spatial_autocorrelation.estimate_snr(power, peak_idx, exclude_bins=5)#

Estimate signal-to-noise ratio around a spectral peak.

Parameters:

  • power (ndarray[Any, dtype[floating]]) -- Power values.

  • peak_idx (int) -- Index of the peak.

  • exclude_bins (int (default: 5)) -- Bins to exclude around the peak when estimating background.

Returns:

SNR, peak power, and background median.

Return type:

tuple[float, float, float]

smftools.tools.spatial_autocorrelation.sample_autocorr_at_harmonics(mean_ac, lags, nrl_bp, max_harmonics=6)#

Sample autocorrelation heights at NRL harmonics.

Parameters:
Returns:

Sampled lags and heights.

Return type:

tuple[numpy.ndarray, numpy.ndarray]

smftools.tools.spatial_autocorrelation.fit_exponential_envelope(sample_lags, heights, counts=None)#

Fit an exponential envelope to sampled autocorrelation peaks.

Parameters:
Returns:

(xi, A, slope, r2).

Return type:

tuple[float, float, float, float]

smftools.tools.spatial_autocorrelation.analyze_autocorr_matrix(autocorr_matrix, counts_matrix, lags, nrl_search_bp=(120, 260), pad_factor=4, min_count=20, max_harmonics=6)#

Analyze autocorrelation matrix and extract periodicity metrics.

Parameters:

  • autocorr_matrix (ndarray[Any, dtype[floating]]) -- Autocorrelation values per molecule.

  • counts_matrix (ndarray[Any, dtype[integer]]) -- Pair counts per lag.

  • lags (ndarray[Any, dtype[floating]]) -- Lag values in base pairs.

  • nrl_search_bp (tuple[int, int] (default: (120, 260))) -- NRL search band in base pairs.

  • pad_factor (int (default: 4)) -- Padding factor for FFT.

  • min_count (int (default: 20)) -- Minimum total count to retain a lag.

  • max_harmonics (int (default: 6)) -- Maximum harmonics to sample.

Returns:

Metrics including NRL, SNR, and PSD summaries.

Return type:

dict

smftools.tools.spatial_autocorrelation.bootstrap_periodicity(autocorr_matrix, counts_matrix, lags, n_boot=200, **kwargs)#

Bootstrap periodicity metrics from autocorrelation matrices.

Parameters:
Returns:

Bootstrapped metric arrays and per-iteration metrics.

Return type:

dict

smftools.tools.spatial_autocorrelation.rolling_autocorr_metrics(X, positions, site_label=None, window_size=2000, step=500, max_lag=800, min_molecules_per_window=10, nrl_search_bp=(120, 260), pad_factor=4, min_count_for_mean=20, max_harmonics=6, n_jobs=1, verbose=False, return_window_results=False, fixed_nrl_bp=None)#

Slide a genomic window across positions and compute periodicity metrics.

Parameters:

  • X (ndarray[Any, dtype[floating]]) -- Binary site matrix for a group (sample × reference × site_type).

  • positions (ndarray[Any, dtype[integer]]) -- Genomic coordinates for columns of X.

  • site_label (str | None (default: None)) -- Label for the site type.

  • window_size (int (default: 2000)) -- Window width in bp.

  • step (int (default: 500)) -- Slide step in bp.

  • max_lag (int (default: 800)) -- Max lag (bp) to compute autocorr out to.

  • min_molecules_per_window (int (default: 10)) -- Minimum molecules required per window.

  • nrl_search_bp (tuple[int, int] (default: (120, 260))) -- NRL search band in base pairs.

  • pad_factor (int (default: 4)) -- Padding factor for FFT.

  • min_count_for_mean (int (default: 20)) -- Minimum count for mean autocorrelation.

  • max_harmonics (int (default: 6)) -- Maximum harmonics to sample.

  • n_jobs (int (default: 1)) -- Number of parallel jobs (joblib if available).

  • verbose (bool (default: False)) -- Whether to log progress.

  • return_window_results (bool (default: False)) -- Whether to return per-window analyzer outputs.

  • fixed_nrl_bp (float | None (default: None)) -- If provided, use a fixed NRL in bp for analysis.

Returns:

Window-level metrics, with optional raw analyzer outputs.

Return type:

pandas.DataFrame | tuple[pandas.DataFrame, list[dict]]