tau-community-detection 1.2.10
Community detection via Louvain/Leiden + Genetic Algorithm
License: MIT
Requires Python: >=3.10

# TAU Community Detection

[![PyPI](https://img.shields.io/pypi/v/tau-community-detection.svg)](https://pypi.org/project/tau-community-detection/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![Downloads](https://static.pepy.tech/badge/tau-community-detection)](https://pepy.tech/project/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.

```bash
pip install tau-community-detection
```

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

```bash
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)

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

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

To build local distributions:

```bash
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](https://doi.org/10.1093/pnasnexus/pgad180)

**BibTeX:**
```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](LICENSE).

See the [Changelog](CHANGELOG.md) for a detailed history of changes and updates.