![icorr](logo.png)

# Identity Correlation Value

This package contains all the components necessary for performing an identity correlation analysis. The identity correlation value (Icorr) is a scale-invariant measure of the total deviation from the identity line, with a slope of 1 and an origin intercept of 0 (Y = 1X+0). This is a special case of Pearson correlation, which instead quantifies any linear relationship.

The identity correlation value is derived from a linear transformation of the dissimilarity metric D (icorr = 1-2D). D is the average squared perpendicular distance of all data point pairs (x_i, y_i) to the identity line, which is normalized to the summed variance of X and Y. In the end, the Icorr value ranges between 1 (coherence), 0 (dis-coherence), and -1 (anti-coherence). Depending on the specific 2D configuration OMEGA, one can calculate a p-value for the null hypothesis icorr=0.

A detailed description of this approach can be found in the supplementary notes of Bayer et al. 2025, where it is used to measure kinase-substrate relationships in the experimental perturbation potency dimensions of kinase inhibitors. If you use identity correlation analysis in your work, please cite us.

# Installation

We have registered this package on pypi. To install, it simply do:

```sh
$ pip install icorr
```

# Example usage

```py
import icorr

# some toy data x and y
x = np.random.normal(loc=0, scale=2, size=30)
y = np.random.normal(loc=0, scale=2, size=30)

icv = icorr.identity_correlation(x, y)
omega = icorr.omega(x,y)

# Calculate p values either by numerical (slow) or beta (fast) approximation
p_value = pvalues_numerical_approximation(icv, omega)
fdr_correction = pvalues_beta_approximation(icv, omega)

# Plot the x and y data in a coherence map
icorr.coherence_map(x, y)

# For FDR correction (Benjamini-Hochberg) of many p-values
p_values_adjusted = icorr.fdr_correction(p_values)

# sample and plot a random (H0) icorr distribution given a omega configuration.
random_icvs = icorr.random_sample(omega=(30,5,5,10))
plt.hist(random_icvs, bins=np.linspace(-1, 1, 101))
```


