tau-community-detection 1.2.9

Community detection via Louvain/Leiden + Genetic Algorithm

TAU Community Detection

tau-community-detection implements TAU, an evolutionary community detection algorithm that couples genetic search with Leiden refinements. It is designed for scalable graph clustering with configurable hyper-parameters and multiprocessing support.

---

Highlights

• Evolutionary search: Maintains a population of candidate partitions and applies crossover/mutation tailored for graph clustering.
• Leiden optimization: Refines every candidate with Leiden to ensure modularity gains.
• Multiprocessing aware: Utilises worker pools for population optimization.
• Deterministic options: Accepts a user-specified random seed for reproducibility.
• Simple API: Access everything through the TauClustering class.

---

Installation

The project targets Python 3.10 or newer.

pip install tau-community-detection

To work from a clone, install the package in editable mode inside a virtual environment:

git clone https://github.com/HillelCharbit/community_TAU.git
cd community_TAU
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

---

Quick Start (Python API)

from tau_community_detection import TauClustering
import networkx as nx

if __name__ == "__main__":
    # --- Scenario 1: Performance / Large Graphs (Recommended) ---
    # Load directly from file (supports .graph, .edgelist, .ncol)
    # This is memory-efficient as it avoids loading the graph twice.
    tau = TauClustering("path/to/graph", population_size=40, max_generations=20)
    clustering = tau.run()

    print(f"Modularity: {clustering.modularity:.4f}")
    print(f"Communities: {len(clustering)}")


    # --- Scenario 2: Integration with Existing Code ---
    # Pass your existing NetworkX or iGraph object directly.
    G = nx.erdos_renyi_graph(n=1000, p=0.01, seed=42)

    tau_nx = TauClustering(G, population_size=40, max_generations=20)
    clustering, stats = tau_nx.run(track_stats=True)

    print(f"Modularity: {clustering.modularity:.4f}")

Need detailed per-generation metrics? Call run(track_stats=True) to receive (vertex_clustering, generation_stats).

To see progress in real-time or customize workers, pass a TauConfig object:

from tau_community_detection import TauConfig
# ...
config = TauConfig(verbose=True, worker_count=4)
tau = TauClustering("path/to/graph", ..., config=config)

---

Graph input

To optimize for very large graphs or when using many worker processes, it is recommended to pass a file path (e.g., to an .graph, .ncol, or .edgelist file) directly to TauClustering rather than a pre-loaded graph object. This allows efficient memory sharing.

Supported input:

• File path to a graph in common NetworkX or igraph format (auto-detects weighting and structure).
• Already-loaded networkx.Graph or igraph.Graph objects.

By default, the loader auto-detects whether the graph is weighted based on the file or graph structure. You can override this by setting TauConfig(is_weighted=True/False) when constructing TauClustering.

See the Quick Start section above for usage examples.

---

Configuration

All algorithm hyper-parameters live on the TauConfig dataclass. You can pass a custom configuration instance to TauClustering or adjust attributes on the default one. Key fields include:

• worker_count: number of parallel processes (defaults to CPU count, capped by population size).
• population_size: number of partitions maintained per generation (default: 60).
• max_generations: upper bound on evolutionary iterations (default: 500).
• verbose: set to True for progress logging (default: False).
• stopping_generations / stopping_jaccard: convergence checks based on membership stability.
• random_seed: makes runs reproducible across processes.

See src/tau_community_detection/config.py for the complete list.

---

Development

pip install -r requirements-dev.txt
make lint
make test

To build local distributions:

make build

Continuous Integration

• GitHub Actions run lint, tests, and package builds on pushes and pull requests.
• Set the CODECOV_TOKEN secret to upload coverage reports.

Publishing

1. Bump the version in setup.cfg/pyproject.toml and commit.
2. Tag the release with git tag vX.Y.Z && git push --tags.
3. Run the Publish Package workflow (defaults to TestPyPI). For PyPI, supply the pypi input and ensure PYPI_API_TOKEN is set. Use TEST_PYPI_API_TOKEN for dry runs.

---

Reference & Citation

If you use TAU in your research, please cite the original algorithm paper:

From Leiden to Tel-Aviv University (TAU): exploring clustering solutions via a genetic algorithm Gal Gilad and Roded Sharan. PNAS Nexus, Volume 2, Issue 6, June 2023. DOI: 10.1093/pnasnexus/pgad180

BibTeX:

@article{gilad2023tau,
  title={From Leiden to Tel-Aviv University (TAU): exploring clustering solutions via a genetic algorithm},
  author={Gilad, Gal and Sharan, Roded},
  journal={PNAS Nexus},
  volume={2},
  number={6},
  pages={pgad180},
  year={2023},
  publisher={Oxford University Press}
}

---

License & Versioning

Current Version: 1.2.8 License: This project is licensed under the MIT License.

See the Changelog for a detailed history of changes and updates.