psycomm 1.1.1

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

pip install psycomm

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.