Signal correlation and similarity¶

Compare matching profiles or scalar features from different channels after merging the feature tables. The implementation compares the supplied numerical values; it does not establish molecular interaction or correct misregistration.

ic.batch_calculate_signal_correlation_features(
    ic.merged_features, ["C2", "C3"],
    [(["normalized_axial_intensity"],
      ["pearson", "spearman", "manders"])],
)

The dataframe must contain both C2_<feature> and C3_<feature>. The helper considers channel combinations and writes columns using the underlying function name, for example C2_C3_normalized_axial_intensity_pearson_correlation_coefficient.

Correlation selectors and output function suffixes¶
Selector	Output suffix	Calculation / interpretation
`manders`	`manders_overlap_coefficient`	Uncentered sum(ab) / sqrt(sum(a²)sum(b²)); equal-length profiles; zero energy is undefined.
`pearson`	`pearson_correlation_coefficient`	Linear correlation via scipy.stats.pearsonr; constant profiles are undefined.
`li_icq`	`li_icq`	2 × (fraction of positive products of mean-centered signals - 0.5).
`ratio`	`ratio`	Finite scalar a/b; zero denominator gives NaN.
`spearman`	`spearman_rank_correlation`	Rank correlation via scipy.stats.spearmanr.
`kendall`	`kendall_tau`	Rank association via scipy.stats.kendalltau.
`distance_corr`	`distance_correlation`	Biased sample distance correlation using separately centered pairwise distances; 0–1; constant profiles give NaN.
`covariance`	`covariance`	Sample covariance np.cov(a,b)[0,1]; retains product intensity units.
`n_cross_corr`	`normalized_cross_correlation`	Zero-lag mean-centered dot product divided by nstd(a)std(b). Supply NumPy arrays for subtraction.
`entropy_diff`	`entropy_difference`	Absolute difference of scipy.stats.entropy values; meaningful for nonnegative distributions.
`kurtosis_ratio`	`kurtosis_ratio`	Absolute kurtosis(a)/kurtosis(b); zero denominator gives NaN.
`skewness_product`	`skewness_product`	Product of the two profile skewness statistics.
`zero_crossings_diff`	`zero_crossings_difference`	Absolute difference in adjacent sign-change counts; raw profiles are not mean-centered.
`fft_peak_ratio`	`fft_peak_ratio`	Largest FFT magnitude ratio, excluding the DC component; zero denominator gives NaN.
`fft_energy_ratio`	`fft_energy_ratio`	Ratio of summed squared FFT magnitudes, including DC; zero denominator gives NaN.
`histogram_intersection`	`histogram_intersection`	Shared-bin, separately probability-normalized histogram overlap; 0–1; unequal lengths allowed.
`cosine_similarity`	`cosine_similarity`	dot(a,b)/(norm(a)*norm(b)); zero norm is undefined.

Interpretation and input checks¶

Most methods require lists or arrays with more than one sample. ratio expects finite scalars and returns NaN for a zero denominator. Invalid, empty, nonfinite, or unconvertible inputs are initially marked missing. Most paired profile metrics require aligned arrays of equal length; their checks are not uniform, so supply compatible one-dimensional profiles.

Constant profiles can make correlation undefined. Pearson and rank methods may return NaN with a numerical-library warning; zero norms invalidate cosine or overlap denominators. Distance correlation explicitly returns NaN for constant profiles. Histogram intersection uses common bins and separately normalized sample counts, and can compare unequal-length profiles.

The Li ICQ implementation multiplies the conventional centered fraction by 2, giving its own -1 to 1 scale. The manders selector calculates an uncentered overlap coefficient; it is not a pair of thresholded Manders M1/M2 fractions. Covariance retains units of the input product. Entropy requires meaningful nonnegative distributions; negative background-subtracted profiles need careful interpretation. See bactoscoop.signalcorrelation.SignalCorrelation.