Metadata-Version: 2.4
Name: psycomm
Version: 1.1.1
Summary: Subject-level community detection on psychometric questionnaire data.
Author-email: Arianna Armanetti <ariannaarmanetti@gmail.com>
License: psycomm -- Attribution License (v1)
        ===================================
        
        Copyright (c) 2026 Arianna Armanetti
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to use,
        copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
        the Software, subject to the following conditions:
        
        1. ATTRIBUTION TO THE PACKAGE
           The above copyright notice and this permission notice shall be included in
           all copies or substantial portions of the Software. Any work, publication
           or product that uses the Software (in whole or in part, including modified
           versions) must include a visible acknowledgement of the psycomm package
           and a citation to the original repository:
        
               Armanetti, A. psycomm: community detection in psychometric data.
               https://github.com/ariannaarmanetti/psycomm
        
        2. ATTRIBUTION TO THE REFERENCE PAPER
           Any academic publication or technical report that uses the Software for
           scientific results must additionally cite the reference paper that the
           Software implements:
        
               Armanetti, A. et al. Community detection in subject-subject networks from psychometrics data. (manuscript in preparation).
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
        ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
        WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
        
Project-URL: Homepage, https://github.com/ariannaarmanetti/psycomm
Project-URL: Issues, https://github.com/ariannaarmanetti/psycomm/issues
Keywords: community detection,psychometrics,factor analysis,clustering,consensus,leiden,louvain,potts
Classifier: Programming Language :: Python :: 3
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22
Requires-Dist: scipy>=1.9
Requires-Dist: pandas>=1.5
Requires-Dist: scikit-learn>=1.1
Requires-Dist: joblib>=1.2
Requires-Dist: matplotlib>=3.5
Requires-Dist: igraph>=0.10
Requires-Dist: leidenalg>=0.9
Requires-Dist: openpyxl>=3.0
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: jupyter; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install psycomm
```

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

## Quick start

```python
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

```python
# 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:

```bibtex
@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 `arianna.armanetti@imtlucca.it` for information.

## License

See [LICENSE](LICENSE). Free to use with attribution to both the package and
the reference paper.

## Tutorials

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