🧠 PopConn

PopConn is a Python toolkit for constructing and analyzing population-level covariance connectomes—brain networks derived from inter-subject correlation of brain region metrics like gray matter volume or diffusion measures.

📊 Overview

Category	Badges
📚 Docs
🧪 Tests & Coverage
🐍 Version	Coming soon on PyPI
🎨 Styling
📄 License

✨ Features

📈 Compute covariance connectomes from either wide or long-format data
🔁 Perform permutation-based group comparisons with the GroupComparator
🧱 Build reusable pipelines using the CovConn class
🔬 Plug in custom statistical metrics (e.g., matrix difference, Frobenius norm)
📊 Designed for neuroimaging research, aging, and population-level modeling

📦 Installation

git clone https://github.com/GalKepler/popconn.git
cd popconn
poetry install

🚀 Quick Start

import pandas as pd
from popconn.core import CovConn

# long-format dataframe with: subject_id, region, value
df = pd.read_csv("data/long_format_metrics.csv")

conn = CovConn(df, long_format=True)
covariance_matrix = conn.compute_covariance()

🎯 Compare Groups with Permutation Testing

from popconn.stats.comparator import GroupComparator
from popconn.stats.metrics import correlation_matrix_difference

comparator = GroupComparator(
    data=df,
    group_col="group",
    long_format=True,
    subject_col="subject_id",
    region_col="region",
    value_col="value"
)

results = comparator.run_permutation_test(
    stat_func=correlation_matrix_difference,
    n_permutations=1000,
    return_distribution=True
)

results["p_values"]

📘 Tutorials

🧠 CovConn Tutorial Notebook
📊 Group Comparison Notebook

🧪 Testing

poetry run pytest

To run all linters:

poetry run ruff check .
poetry run black --check .
poetry run isort --check-only .

🧬 Use Cases

Comparing covariance networks between groups (e.g., young vs. old adults)
Identifying stable communities via bootstrapped clustering
Visualizing subnetwork structures in population brain data
Tracking network change across time or skill acquisition

🙌 Credits

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.