Metadata-Version: 2.1
Name: pycosep
Version: 0.2.0
Summary: Travelling Salesman Path - Python wrapper
Home-page: https://github.com/aacevedot/pycosep
Author: Dr. Aldo Acevedo
Author-email: aldo.acevedo.toledo@gmail.com
License: MIT
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Clustering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: numpy>=1.20
Requires-Dist: scipy>=1.6
Requires-Dist: scikit-learn>=0.24
Requires-Dist: networkx>=3.2
Provides-Extra: dev
Requires-Dist: pytest>=6.2; extra == "dev"
Requires-Dist: coverage>=5.5; extra == "dev"
Requires-Dist: flake8>=3.9; extra == "dev"

# Travelling salesman path - Python wrapper

*This Python package is based on the MATLAB implementation available at [biomedical-cybernetics/travelling-salesman-path](https://github.com/biomedical-cybernetics/travelling-salesman-path).*

**Article Source:** [Geometric separability of mesoscale patterns in embedding representation and visualization of multidimensional data and complex networks](https://journals.plos.org/complexsystems/article?id=10.1371/journal.pcsy.0000012). Acevedo A, Wu Y, Traversa FL, Cannistraci CV (2024) Geometric separability of mesoscale patterns in embedding representation and visualization of multidimensional data and complex networks. PLOS Complex Systems 1(2): e0000012. [https://doi.org/10.1371/journal.pcsy.0000012](https://doi.org/10.1371/journal.pcsy.0000012)

## Before starting

This package requires [Concorde](https://www.math.uwaterloo.ca/tsp/concorde.html) to execute calculations. Check the [requirements](https://github.com/aacevedot/pycosep/blob/main/REQUIREMENTS.md) and follow the instructions to install this dependency in your operating system.

## Installation

Run the following to install:

```shell
pip install pycosep
```

## Usage

Computing the community separability of a given embedding.

```python
from sklearn.datasets import load_iris

from pycosep import community_separability
from pycosep.separability_variants import SeparabilityVariant

# Sample data. Details at https://scikit-learn.org/stable/datasets/toy_dataset.html
data = load_iris()

# Community separability variant
#   CPS: centroid projection separability
#   LDPS: linear discriminant projection separability
#   TSPS: travelling salesman projection separability
variant = SeparabilityVariant.TSPS

indices, _ = community_separability.compute_separability(
    embedding=data.data,
    communities=data.target,
    variant=variant)

print(f"AUC index: {indices['auc']}")
print(f"AUPR index: {indices['aupr']}")
print(f"MCC index: {indices['mcc']}")
```

Computing the community separability of a given embedding for 1000 permutations.

```python
from sklearn.datasets import load_iris

from pycosep import community_separability
from pycosep.separability_variants import SeparabilityVariant

# Sample data. Details at https://scikit-learn.org/stable/datasets/toy_dataset.html
data = load_iris()

# Community separability variant
#   CPS: centroid projection separability
#   LDPS: linear discriminant projection separability
#   TSPS: travelling salesman projection separability
variant = SeparabilityVariant.LDPS

# Number of iterations for the Null model
permutations = 1000

index_permutations, _ = community_separability.compute_separability(
    embedding=data.data,
    communities=data.target,
    variant=variant,
    permutations=permutations)

auc_results = index_permutations['auc']
print(f"AUC original value: {auc_results['original_value']}")
print(f"AUC p-value: {auc_results['p_value']}")
print(f"AUC mean: {auc_results['mean']}")
print(f"AUC max: {auc_results['max']}")
print(f"AUC min: {auc_results['min']}")
print(f"AUC standard_deviation: {auc_results['standard_deviation']}")
print(f"AUC standard_error: {auc_results['standard_error']}")

aupr_results = index_permutations['aupr']
print(f"AUPR original value: {aupr_results['original_value']}")
print(f"AUPR p-value: {aupr_results['p_value']}")
print(f"AUPR mean: {aupr_results['mean']}")
print(f"AUPR max: {aupr_results['max']}")
print(f"AUPR min: {aupr_results['min']}")
print(f"AUPR standard deviation: {aupr_results['standard_deviation']}")
print(f"AUPR standard error: {aupr_results['standard_error']}")

mcc_results = index_permutations['mcc']
print(f"MCC original value: {mcc_results['original_value']}")
print(f"MCC p-value: {mcc_results['p_value']}")
print(f"MCC mean: {mcc_results['mean']}")
print(f"MCC max: {mcc_results['max']}")
print(f"MCC min: {mcc_results['min']}")
print(f"MCC standard deviation: {mcc_results['standard_deviation']}")
print(f"MCC standard error: {mcc_results['standard_error']}")
```

## Reporting an issue

For reporting problems, questions, and suggestions; please, use the [Issues](https://github.com/aacevedot/pycosep/issues) section.
