PARTIAL_CORR

This function measures the association between two variables while controlling for one or more covariates.

For variables X and Y adjusted for covariates Z, the partial correlation is the correlation between residuals:

r_{XY\cdot Z} = \mathrm{corr}(\varepsilon_X, \varepsilon_Y)

where \varepsilon_X and \varepsilon_Y are residuals after regressing X and Y on Z. This can isolate direct linear or rank-based association from confounding effects.

Excel Usage

=PARTIAL_CORR(data, x, y, covar, x_covar, y_covar, pcorr_method, pcorr_alternative)
  • data (list[list], required): Input table as a 2D range with a header row followed by data rows.
  • x (str, required): Name of the first variable column.
  • y (str, required): Name of the second variable column.
  • covar (str, optional, default: null): Optional covariate name or comma-separated covariate names.
  • x_covar (str, optional, default: null): Optional covariates to control only in x (comma-separated names).
  • y_covar (str, optional, default: null): Optional covariates to control only in y (comma-separated names).
  • pcorr_method (str, optional, default: “pearson”): Correlation method.
  • pcorr_alternative (str, optional, default: “two-sided”): Alternative hypothesis for the p-value computation.

Returns (float): Partial correlation coefficient r.

Example 1: Partial correlation controlling one covariate

Inputs:

data x y covar
x y z x y z
1 2 0
2 3 1
3 5 1
4 4 2
5 7 3
6 8 3

Excel formula:

=PARTIAL_CORR({"x","y","z";1,2,0;2,3,1;3,5,1;4,4,2;5,7,3;6,8,3}, "x", "y", "z")

Expected output:

0.673891

Example 2: Semi-partial using x_covar only

Inputs:

data x y x_covar pcorr_method
x y z x y z spearman
1 3 1
2 3 1
3 4 2
4 6 3
5 7 3
6 9 4

Excel formula:

=PARTIAL_CORR({"x","y","z";1,3,1;2,3,1;3,4,2;4,6,3;5,7,3;6,9,4}, "x", "y", "z", "spearman")

Expected output:

0.121268

Example 3: Multiple covariates as comma-separated names

Inputs:

data x y covar
x y z1 z2 x y z1, z2
1 2 0 1
2 3 1 2
3 5 1 3
4 4 2 2
5 7 3 5
6 8 3 6

Excel formula:

=PARTIAL_CORR({"x","y","z1","z2";1,2,0,1;2,3,1,2;3,5,1,3;4,4,2,2;5,7,3,5;6,8,3,6}, "x", "y", "z1, z2")

Expected output:

0.727688

Example 4: Partial correlation with one-sided alternative

Inputs:

data x y covar pcorr_alternative
x y z x y z greater
1 2 1
2 4 1
3 6 2
4 7 2
5 9 3
6 11 3

Excel formula:

=PARTIAL_CORR({"x","y","z";1,2,1;2,4,1;3,6,2;4,7,2;5,9,3;6,11,3}, "x", "y", "z", "greater")

Expected output:

0.96225

Python Code

import pandas as pd
import pingouin as pg

def partial_corr(data, x, y, covar=None, x_covar=None, y_covar=None, pcorr_method='pearson', pcorr_alternative='two-sided'):
    """
    Compute partial or semi-partial correlation between two variables.

    See: https://pingouin-stats.org/generated/pingouin.partial_corr.html

    This example function is provided as-is without any representation of accuracy.

    Args:
        data (list[list]): Input table as a 2D range with a header row followed by data rows.
        x (str): Name of the first variable column.
        y (str): Name of the second variable column.
        covar (str, optional): Optional covariate name or comma-separated covariate names. Default is None.
        x_covar (str, optional): Optional covariates to control only in x (comma-separated names). Default is None.
        y_covar (str, optional): Optional covariates to control only in y (comma-separated names). Default is None.
        pcorr_method (str, optional): Correlation method. Valid options: Pearson, Spearman. Default is 'pearson'.
        pcorr_alternative (str, optional): Alternative hypothesis for the p-value computation. Valid options: Two-sided, Less, Greater. Default is 'two-sided'.

    Returns:
        float: Partial correlation coefficient r.
    """
    try:
        def to2d(value):
            return [[value]] if not isinstance(value, list) else value

        def parse_names(value):
            if value is None:
                return None
            text = str(value).strip()
            if text == "":
                return None
            names = [part.strip() for part in text.split(",") if part.strip()]
            if len(names) == 0:
                return None
            return names if len(names) > 1 else names[0]

        matrix = to2d(data)
        if not isinstance(matrix, list) or len(matrix) < 2 or not all(isinstance(row, list) for row in matrix):
            return "Error: Invalid input - data must be a 2D list with header and rows"

        headers = [str(col).strip() for col in matrix[0]]
        if len(headers) == 0 or any(col == "" for col in headers):
            return "Error: Invalid input - header row must contain non-empty column names"

        width = len(headers)
        records = []
        for row in matrix[1:]:
            values = list(row)
            if len(values) < width:
                values = values + [None] * (width - len(values))
            elif len(values) > width:
                values = values[:width]
            records.append(values)

        frame = pd.DataFrame(records, columns=headers)

        covar_arg = parse_names(covar)
        x_covar_arg = parse_names(x_covar)
        y_covar_arg = parse_names(y_covar)

        if covar_arg is None and x_covar_arg is None and y_covar_arg is None:
            return "Error: Invalid input - provide covar, x_covar, or y_covar"
        if covar_arg is not None and (x_covar_arg is not None or y_covar_arg is not None):
            return "Error: Invalid input - use covar or x_covar/y_covar, not both"

        result = pg.partial_corr(
            data=frame,
            x=str(x),
            y=str(y),
            covar=covar_arg,
            x_covar=x_covar_arg,
            y_covar=y_covar_arg,
            method=str(pcorr_method),
            alternative=str(pcorr_alternative),
        )

        if "r" not in result.columns or len(result.index) == 0:
            return "Error: Unable to compute partial correlation"

        return float(result.loc[result.index[0], "r"])
    except Exception as e:
        return f"Error: {str(e)}"

Online Calculator

Input table as a 2D range with a header row followed by data rows.
Name of the first variable column.
Name of the second variable column.
Optional covariate name or comma-separated covariate names.
Optional covariates to control only in x (comma-separated names).
Optional covariates to control only in y (comma-separated names).
Correlation method.
Alternative hypothesis for the p-value computation.