psycomm 1.1.0

Subject-level community detection on psychometric questionnaire data.

psycomm

Subject-level community detection on psychometric questionnaire data.

psycomm is the Python implementation of the pipeline described in the paper Community detection in psychometric questionnaire data (Armanetti et al., forthcoming). Given a subject-by-item response matrix X, the package builds a subject-subject similarity matrix in factor (or item) space, removes a null model from it, runs a modularity-maximisation algorithm to detect communities of respondents, and validates the resulting partition via bootstrap consensus and significance metrics (cloud entropy at variable k, histogram overlap, modularity).

Features

• Dataset generation — mixture-of-FA, mixture-of-binomials, structured FA, dominant-factor (bifactor); reproducible seeds.
• Loaders for the 15 questionnaire datasets used in the paper (big5, hexaco, sd3, mach, acme, iri, ei, dass, cfcs, hsns, msscq, rwas, gcbs, pwe, empathy).
• Similarity in item space or in factor space (FA / PCA) with eight metrics (sqeuclidean default, euclidean, l1, cosine, covariance, mahalanobis, percentile_l1, percentile_l2).
• Null models for the coupling matrix: Newman / configuration model and market-mode removal.
• Detection algorithms: Leiden (default), in-house multi-level Louvain, Potts with simulated annealing.
• Reshuffling null for the data matrix (column-wise permutation, Gaussian copula, FA-generative).
• Consensus clustering with permutation-benchmark residualisation.
• Metrics: loose / strict cloud entropy, variable-k entropy curve, histogram overlap, modularity, eigenvector / community entropy.
• Visualisation helpers for similarity matrices, spectra, consensus matrices, PCA embeddings and entropy curves.

Installation

git clone https://github.com/ariannaarmanetti/psycomm.git
cd psycomm
pip install -e .

leidenalg and igraph are required for the default Leiden detector and are installed automatically.

Quick start

import psycomm as pc

# 1. Generate or load data
X, labels_true, info = pc.generate_mixture_fa(
    N=800, M=60, q=6, K=4, F=4, sigma_within=1.0, seed=0,
)
# or
# X = pc.load_dataset("rwas", "/path/to/datasets")

# 2. Similarity in factor space (squared Euclidean, as in the paper)
S, scores, fa = pc.compute_similarity_fa(X, n_factors=4, metric="sqeuclidean")

# 3. Community detection: market-mode null + Leiden
labels, Q, S_clean = pc.detect_communities(
    S, null_model="marketmode", algorithm="leiden",
)
print(f"detected K = {len(set(labels))}, Q = {Q:.3f}")

# 4. Significance metrics
eigvals, eigvecs = pc.compute_spectrum(S, neig=10)
K = len(set(labels))
H_loose  = pc.cloud_entropy_loose(eigvecs, K)
H_strict = pc.cloud_entropy_strict(eigvecs, K, labels)
overlap  = pc.histogram_overlap(S, labels)
mod      = pc.modularity(S_clean, labels)
print(H_loose, H_strict, overlap, mod)

# 5. Reshuffling null for a permutation test
Xn = pc.reshuffle_subjects(X)
Sn, _, _ = pc.compute_similarity_fa(Xn, n_factors=4)
labels_n, Q_n, _ = pc.detect_communities(Sn, null_model="marketmode")

Public API

# datasets
generate_mixture_fa, generate_mixture_binomial,
generate_structured_ordinal_fa, generate_dominant_factor,
load_dataset, get_number_constructs, SUPPORTED_DATASETS

# similarity
compute_similarity, compute_similarity_fa, fit_factor_analysis,
AVAILABLE_METRICS

# community detection
detect_communities, leiden_communities, louvain_communities, louvain_best,
potts_communities, newman_null, marketmode_null, compute_spectrum

# consensus
consensus_clustering, compute_permuted_benchmark,
final_communities_from_consensus, consensus_diagnostics

# reshuffling nulls
reshuffle_subjects, gaussian_copula_null, fa_generative_null

# metrics
cloud_entropy, cloud_entropy_batch, cloud_entropy_loose, cloud_entropy_strict,
cloud_entropy_k, eigenvector_entropy, community_entropy, histogram_overlap,
modularity, average_community_size, default_k_loose, default_k_strict

# visualisation
viz.plot_similarity, viz.plot_spectrum, viz.plot_consensus_matrix,
viz.plot_community_pca, viz.plot_entropy_curve, viz.plot_similarity_histograms

Citation

If you use psycomm in a publication, please cite both the package and the underlying paper:

@software{psycomm,
  author  = {Armanetti, Arianna},
  title   = {psycomm: community detection in psychometric data},
  year    = {2026},
  url     = {https://github.com/ariannaarmanetti/psycomm},
}

@article{armanetti2026community,
  author  = {Armanetti, Arianna and Cecchetti, Luca and Fried, Eiko and Garlaschelli, Diego and Ibáñez-Berganza, Miguel}
  title   = {Community detection in subject-subject networks from psychometrics data},
  year    = {2026},
  note    = {Manuscript in preparation},
}

Contacts

Feel free to contact [e-mail] for information.

License

See LICENSE. Free to use with attribution to both the package and the reference paper.

Tutorials

A walk-through notebook is available in tutorials/, covering: generating synthetic data, loading a real dataset, computing similarities, running the full detection pipeline, validating partitions with permutation tests, and visualising results.