A minimal, dependency-light Python port of the Image Intraclass Correlation Coefficient (I2C2) and a univariate ICC(2), ported from the R packages used in a test–retest reliability analysis.
The I2C2 math follows Shou et al. (2013), Quantifying the reliability of image replication studies: the image intraclass correlation coefficient (I2C2), Cognitive, Affective, & Behavioral Neuroscience 13(4):714–24, doi:10.3758/s13415-013-0196-0.
Pure numpy + pandas — no scipy/statsmodels required.
pip install -e . # editable install from a clone
# or just use the single module directly:
pip install numpy pandas # and drop i2c2.py next to your code| Function | What it does |
|---|---|
i2c2(y, id, visit, demean=True) |
Multivariate image ICC (trace method); returns lambda, Kx, Ku |
i2c2_mc_ci(y, id, visit, ...) |
Subject-level bootstrap confidence interval |
icc2_lme(dv, grp, data) |
Univariate ICC(2) from a random-intercept REML fit |
icc_calc(df) |
Long→wide convenience wrapper (pivot + I2C2 + CI) |
Internal helpers check_id_visit and demean_matrix are included. This is a
deliberately minimal port — only the functions needed for the analysis, no
deprecated helpers or unused options.
import pandas as pd
import i2c2
# long format: one row per (subject, session, feature)
df = pd.read_csv("my_icc_df.csv") # columns: values, ses, sub, + an edge index
res, ci = i2c2.icc_calc(df)
print(res["lambda"], ci)
# or call directly on a wide n-by-p matrix (rows = subject x visit):
out = i2c2.i2c2(y, id=subjects, visit=sessions, demean=True)
out["lambda"]pytest -q # standard
python3 test_i2c2.py # no-pytest fallback (uses minipytest.py)The suite checks structural properties (row-order invariance, de-mean behavior),
a deterministic fixed-seed regression value, and icc2_lme against the
closed-form ANOVA/REML ICC(2) on balanced data. These run on synthetic data and
need no external files.
Three additional tests validate against a real dataset and are skipped automatically if that CSV is not present (it is not distributed — see below).
i2c2() reproduces the R I2C2()$lambda exactly (verified to 1e-7 against a
held-out dataset).
The bootstrap CI is statistically equivalent to R's but not bit-identical:
the cluster-bootstrap procedure is the same, but numpy's RNG differs from R's
sample(), so the resampled draws — and thus the exact percentile endpoints —
differ slightly. Pass a fixed rseed for reproducibility.
icc2_lme fits y ~ 1 + (1|grp) by REML (implemented in numpy) and matches
nlme::lme's closed-form REML variance components exactly on balanced data.
No data ships with this repository. .gitignore excludes *.csv and *.ipynb
so collaborator data and notebooks are never committed. Point the functions at
your own long-format dataframe (values, ses, sub, and a per-observation
edge index).
GPL-3.0-or-later. This is a derivative work:
i2c2,i2c2_mc_ci,resample_id,check_id_visit,demean_matrixare a Python translation of the R package I2C2 (GPL-2) by Haochang Shou, Seonjoo Lee, John Muschelli, Ani Eloyan, and colleagues — https://github.com/muschellij2/I2C2.icc2_lmefollows the documented behavior of multilevel::ICC2.lme (GPL ≥ 2) by Paul Bliese.
Because the port translates GPL-2 source, the combined work is distributed under
the GPL (v3 chosen for forward compatibility). See LICENSE for the full text.
minipytest.py is a tiny shim so the tests run where pytest can't be
installed; delete it if you have pytest.