pcc.h File Reference

The pcc library, a software library dedicated to the computation of estimates of Pearson Correlation Coefficients (PCC). More...

Go to the source code of this file.

Functions
void	pcc_s2s (float *pcc, int samples_length, int ny, float *x, int **y)
	The `pcc_s2s` (s2s for scalar-to-scalar) function estimates the PCC between a floating point random variable \(X\) and a set of \(ny\) integer random variables \(Y_n, 0\le n<ny\), based on samples of each. More...
void	pcc_v2s (float **pcc, int samples_length, int vectors_length, int ny, float **x, int **y)
	The `pcc_v2s` (v2s for vector-to-scalar) function estimates the PCC between a vector floating point random variable (denoted \(X\)) and a set of \(ny\) scalar integer random variables \(Y_n, 0\le n<ny\), based on samples of each. More...

Detailed Description

The pcc library, a software library dedicated to the computation of estimates of Pearson Correlation Coefficients (PCC).

Author

Renaud Pacalet, renau.nosp@m.d.pa.nosp@m.calet.nosp@m.@tel.nosp@m.ecom-.nosp@m.pari.nosp@m.s.fr

Date

2020-05-05

Defines functions to estimate Pearson Correlation Coefficients (PCC) between a random variable \(X\) and a set of \(ny\) random variables \(Y_n, 0\le n<ny\).

These coefficients are statistical tools to evaluate the correlation between random variables. The formula of a PCC between random variables \(X\) and \(Y\) is: \(PCC(X,Y) = [E(X\times Y) - E(X)\times E(Y)] / [\sigma(X)\times\sigma(Y)]\) where \(E(Z)\) is the expectation of random variable \(Z\) and \(\sigma(Z)\) is its standard deviation. The value of the PCC is in range -1 to +1. Values close to 0 indicate no or a weak correlation. Values close to -1 or +1 indicate strong correlations.

Function Documentation

pcc_s2s()

void pcc_s2s	(	float *	pcc,
		int	samples_length,
		int	ny,
		float *	x,
		int **	y
	)

The `pcc_s2s` (s2s for scalar-to-scalar) function estimates the PCC between a floating point random variable \(X\) and a set of \(ny\) integer random variables \(Y_n, 0\le n<ny\), based on samples of each.

The sample of \(X\) is passed as an array x of float values where x[i] is the i-th realization in the sample. The samples of the \(Y_n\) are passed as an array of \(ny\) arrays of int values where y[n][i] is the i-th realization in the sample of \(Y_n\). The length of the samples must be specified and set to the smallest of all samples' lengths. The extra realizations in larger samples, if any, are ignored.

Example of use with samples of length 1000 and 4 \(Y_n\) variables. get_next_x and get_next_y(n) are two functions returning realizations of the \(X\) and \(Y_n\) random variables, respectively:

float *pcc;          // array of float for the result PCCs
float *x;            // array of float for the X sample
int **y;             // array of arrays of int for the samples of the Yn
int ny;              // number of Yn variables
int n;               // index of Yn variables
int samples_length;  // length of samples
int i;               // index of realizations in samples
...
ny = 4;
samples_length = 1000;
...
pcc = malloc(ny * sizeof(float));               // allocate array for the result PCCs
x = malloc(samples_length * sizeof(float));     // allocate array for the X sample
y = malloc(ny * sizeof(int *));                 // allocate array of arrays for the Yn samples
for(n = 0; n < ny; n++) {
  y[n] = malloc(samples_length * sizeof(int));
}
for(i = 0; i < samples_length; i++) {
    x[i] = get_next_x();                        // realization of random variable X
    for(n = 0; n < ny; n++) {
        y[n][i] = get_next_y(n);                // realization of random variable Yn
    }
}
pcc_s2s(pcc, samples_length, ny, x, y);         // compute ny PCC estimates at once
for(n = 0; n < ny; n++) {
  printf("PCC(X,Y%d) = %f\n", n, pcc[n]);       // print PCC(X,Yn)
}
free(pcc);                                      // free array of PCC results
free(x);                                        // free array of X sample
for(n = 0; n < ny; n++) {                       // free arrays of Yn samples
  free(y[n]);
}
free(y);

If there is only one single \(Y\) variable the code can be silghtly simplified:

float pcc;           // result PCC
float *x;            // array of float for the X sample
int *y;              // array of int for the Y sample
int i;               // index of realizations in samples
int samples_length;  // length of samples
...
samples_length = 1000;
...
x = malloc(samples_length * sizeof(float)); // allocate array for the X sample
y = malloc(samples_length * sizeof(int));   // allocate array for the Y sample
for(i = 0; i < samples_length; i++) {
    x[i] = get_next_x();                    // realization of random variable X
    y[i] = get_next_y();                    // realization of random variable Y
}
pcc_s2s(&pcc, samples_length, 1, x, &y);    // compute PCC estimate
printf("PCC(X,Y) = %f\n", pcc);             // print PCC(X,Y)
free(x);                                    // free array of X sample
free(y);                                    // free array of Y sample

Note that, if \(ny>1\), using \(ny\) times this second version is not equivalent to using only once the first version because many operations involving only \(X\) would be re-computated \(ny\) times. If \(ny>1\) always prefer the first version, it is far more efficient.

Parameters

pcc	array of result PCCs, pcc[n] = \(PCC(X,Y_n)\)
samples_length	length of smallest sample
ny	number of \(Yn\) random variables
x	\(X\) sample, x[i] = i-th realization of \(X\)
y	\(Y_n\) samples, y[n][i] = i-th realization of \(Yn\)

pcc_v2s()

void pcc_v2s	(	float **	pcc,
		int	samples_length,
		int	vectors_length,
		int	ny,
		float **	x,
		int **	y
	)

The `pcc_v2s` (v2s for vector-to-scalar) function estimates the PCC between a vector floating point random variable (denoted \(X\)) and a set of \(ny\) scalar integer random variables \(Y_n, 0\le n<ny\), based on samples of each.

Each realization of \(X\) is thus itself an array of float components. Pearson coefficients are computed component-wise of \(X\) and the results are vectors of PCC estimates: \(PCC(X,Y_n)[i]=PCC(X[i],Y_n), 0\le i<\lvert X\rvert, 0\le n<ny\). The sample of \(X\) is passed as an array of arrays of float values where x[i][j] is the j-th component of the i-th realization in the sample of \(X\). The samples of the \(Y_n\) are passed as an array of \(ny\) arrays of int values where y[n][i] is the i-th realization in the sample of \(Y_n, 0\le n<ny\). The length of the samples must be specified and set to the smallest of all samples' lengths. The extra realizations in larger samples, if any, are ignored. Example of use with 500-components vectors, samples of length 1000 and 4 \(Y_n\) variables. get_next_x(j) and get_next_y(n) are two functions returning realizations of the j-th component of \(X\) and of \(Y_n\), respectively:

float **pcc;         // array of arrays of float for the result PCCs
float **x;           // array of arrays of float for the X sample
int **y;             // array of arrays of int for the Yn samples
int i;               // index of realizations in samples
int j;               // index of components in vectors
int n;               // index of Yn variables
int ny;              // number of Yn variables
int samples_length;  // length of samples
int vectors_length;  // length of vectors
...
ny = 4;
samples_length = 1000;
vectors_length = 500;
pcc = malloc(ny * sizeof(float *));              // allocate array of arrays for the result PCCs
for(n = 0; n < ny; n++) {
  pcc[n] = malloc(vectors_length * sizeof(float));
}
x = malloc(samples_length * sizeof(float *));    // allocate array of arrays for the X sample
for(n = 0; n < samples_length; n++) {
  x[n] = malloc(vectors_length * sizeof(float));
}
y = malloc(ny * sizeof(int *));                  // allocate array of arrays for the Yn samples
for(n = 0; n < ny; n++) {
  y[n] = malloc(samples_length * sizeof(int));
}
for(i = 0; i < samples_length; i++) {
  for(j = 0; j < vectors_length; j++) {
    x[i][j] = get_next_x(j);                     // realization of j-th component of random variable X
  }
  for(n = 0; n < ny; n++) {
    y[n][i] = get_next_y(n);                     // realization of random variable Yn
  }
}
pcc_v2s(pcc, samples_length, vectors_length, ny, x, y);
for(n = 0; n < ny; n++) {
  for(j = 0; j < vectors_length; j++) {
    printf("PCC(X[%d],Y%d) = %f\n", j, n, pcc[n][j]);
  }
}
for(n = 0; n < ny; n++) {
  free(pcc[n]);
  free(y[n]);
}
free(pcc);
free(y);
for(i = 0; i < samples_length; i++) {
  free(x[i]);
}
free(x);

Parameters

pcc	array of arrays of result PCCs, pcc[n][j] = j-th component of \(PCC(X,Y_n)\)
samples_length	number of realizations in each sample
vectors_length	length of \(X\) vector random variable
ny	number of \(Yi\) random variables
x	X sample, x[i][j] = j-th component of i-th realization of \(X\)
y	Y sample, y[n][i] = i-th realization of \(Y_n\)