pysurprise 1.0.0__tar.gz

pysurprise-1.0.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include pyproject.toml
+include setup.py
+include pysurprise/LICENSE
+include pysurprise/README.md
+recursive-include pysurprise/csrc *.cpp *.h *.hpp
+recursive-include pysurprise/src *.py
+recursive-include net_examples *.pairs

pysurprise-1.0.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: pysurprise
+Version: 1.0.0
+Summary: Python bindings for the Surprise network community structure metric
+Author: José Marín
+Maintainer-email: Rodrigo Aldecoa <raldecoa@ibv.csic.es>, Ignacio Marín <imarin@ibv.csic.es>
+License-Expression: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/raldecoa/SurpriseMe
+Project-URL: Repository, https://github.com/raldecoa/SurpriseMe
+Project-URL: Issues, https://github.com/raldecoa/SurpriseMe/issues
+Keywords: networks,community-detection,surprise,graph,clustering,bioinformatics
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: algorithms
+Requires-Dist: infomap>=2.0; extra == "algorithms"
+Requires-Dist: igraph>=0.10; extra == "algorithms"
+Provides-Extra: infomap
+Requires-Dist: infomap>=2.0; extra == "infomap"
+Provides-Extra: igraph
+Requires-Dist: igraph>=0.10; extra == "igraph"
+
+# pySurprise
+
+Python package for computing the **Surprise** metric and running community
+detection algorithms on complex networks.
+
+Surprise quantifies the quality of a partition of a complex network into
+communities using a cumulative hypergeometric distribution. Higher values
+indicate a more *surprising* (i.e. better) community structure.
+
+**pySurprise** wraps the original C++ Surprise computation via pybind11 for
+maximum performance, and provides Python access to **7 clustering algorithms**
+from the [SurpriseMe](https://github.com/raldecoa/SurpriseMe) project.
+
+## Installation
+
+```bash
+pip install pysurprise
+```
+
+To use the clustering algorithms that depend on optional packages:
+
+```bash
+# Install all algorithm dependencies
+pip install pysurprise[algorithms]
+
+# Or individually
+pip install pysurprise[infomap]   # for Infomap
+pip install pysurprise[igraph]    # for RN
+```
+
+### From source
+
+```bash
+git clone https://github.com/raldecoa/SurpriseMe.git
+cd SurpriseMe
+pip install .
+```
+
+## Quick start
+
+```python
+import pysurprise
+
+# Define edges (undirected, listed once)
+edges = [(0, 1), (0, 2), (0, 3), (1, 2), (1, 3), (2, 3),
+         (3, 4), (4, 5), (4, 6), (4, 7), (5, 6), (5, 7), (6, 7)]
+
+# Partition: node i belongs to community partition[i]
+partition = [0, 0, 0, 0, 1, 1, 1, 1]
+
+value = pysurprise.surprise(edges, partition)
+print(f"Surprise = {value}")
+```
+
+### Using string labels
+
+```python
+edges = [("a", "b"), ("a", "c"), ("b", "c"),
+         ("c", "d"), ("d", "e"), ("d", "f"), ("e", "f")]
+
+partition = {"a": 0, "b": 0, "c": 0, "d": 1, "e": 1, "f": 1}
+
+value = pysurprise.surprise(edges, partition)
+```
+
+### Low-level access
+
+If you already have the four Surprise parameters (F, M, n, p):
+
+```python
+from pysurprise import compute_surprise
+
+F = 28.0   # total possible pairs: N*(N-1)/2
+M = 12.0   # intra-community possible pairs
+n = 13.0   # total edges
+p = 12.0   # intra-community edges
+
+value = compute_surprise(F, M, n, p)
+```
+
+## Clustering algorithms
+
+`pysurprise.algorithms` exposes the 7 community detection algorithms from
+SurpriseMe, ready to use from Python:
+
+```python
+from pysurprise import algorithms
+import pysurprise
+
+# Run a single algorithm
+partition = algorithms.cpm(edges)
+score = pysurprise.surprise(edges, partition)
+
+# Run all 7 algorithms and compare
+results = algorithms.run_all(edges)
+for name, part in results.items():
+    s = pysurprise.surprise(edges, part)
+    print(f"{name}: {s:.4f}")
+```
+
+| Algorithm | Function | Reference |
+|-----------|----------|-----------|
+| **CPM** | `algorithms.cpm()` | Traag et al., *Phys. Rev. E* 84 (2011) |
+| **Infomap** | `algorithms.infomap()` | Rosvall & Bergstrom, *PNAS* 105 (2008) |
+| **RB** | `algorithms.rb()` | Reichardt & Bornholdt, *Phys. Rev. E* 74 (2006) |
+| **RN** | `algorithms.rn()` | Ronhovde & Nussinov, *Phys. Rev. E* 81 (2010) |
+| **RNSC** | `algorithms.rnsc()` | King et al., *Bioinformatics* 20 (2004) |
+| **SCluster** | `algorithms.scluster()` | Aldecoa & Marín, *PLoS ONE* 5 (2010) |
+| **UVCluster** | `algorithms.uvcluster()` | Arnau et al., *Bioinformatics* 21 (2005) |
+
+All functions accept `edges: list[(str, str)]` and return
+`dict[str, int]` (node → community).
+
+## API Reference
+
+| Function | Description |
+|---|---|
+| `surprise(edges, partition)` | High-level: compute Surprise from edges and partition (list or dict) |
+| `compute_surprise(F, M, n, p)` | Low-level: compute Surprise from the four parameters directly |
+| `surprise_from_partition(edges, partition)` | C++ binding: int-indexed edges and partition list |
+| `surprise_from_partition_dict(edges, partition)` | C++ binding: string-labelled edges and partition dict |
+| `log_hyper_probability(F, M, n, j)` | Single hypergeometric probability term (log10) |
+| `algorithms.run_all(edges)` | Run all 7 clustering algorithms and return results |
+
+## Parameters
+
+- **F**: Total number of possible node pairs = N×(N−1)/2
+- **M**: Sum of intra-community possible pairs = Σ s_i×(s_i−1)/2
+- **n**: Total number of edges in the network
+- **p**: Number of intra-community edges
+
+## Credits
+
+**Developed by** José Marín.
+
+**Based on the original Surprise metric and SurpriseMe software by:**
+
+> Aldecoa R, Marín I (2011). *Deciphering network community structure by Surprise.*
+> PLoS ONE 6(9): e24195.
+
+> Aldecoa R, Marín I (2013). *Surprise maximization reveals the community structure
+> of complex networks.* Scientific Reports 3, 1060.
+
+The C++ Surprise computation and bundled clustering algorithms originate from
+the [SurpriseMe](https://github.com/raldecoa/SurpriseMe) project by
+Rodrigo Aldecoa and Ignacio Marín.
+
+## License
+
+GPL-3.0-or-later. See [LICENSE](LICENSE).

pysurprise-1.0.0/README

@@ -0,0 +1,166 @@
+* SurpriseMe - An integrated tool for network community structure
+characterization using Surprise maximization * 
+----------------------------------------------------------------------
+
+SurpriseMe is a free, open source software for detecting community structure
+in networks. The program uses Surprise to evaluate the outputs of 7 high-
+quality community detection algorithms. It also generates distance matrices
+that allow to visualize the relationships among the solutions generated.
+
+You can find more information here:
+
+  arxiv.org/abs/1310.2357
+
+  
+License
+=======
+
+Copyright (C) 2013  Rodrigo Aldecoa and Ignacio Marín
+This software is distributed under the GNU General Public License
+version 3.0 (GPLv3). You should have received a copy of this license
+with the program. Also, it can be found online at
+http://www.opensource.org/licenses/gpl-3.0.html.
+
+Version
+=======
+
+SupriseMe 1.0
+
+
+Interesting related papers
+==========================
+
+For more information about Surprise, please check out:
+
+* "Deciphering network community structure by Surprise".
+  Rodrigo Aldecoa and Ignacio Marín.
+  PloS ONE 6, e24195 (2011).
+  http://www.plosone.org/article/info%3Adoi%2F10.1371%2Fjournal.pone.0024195
+  
+
+and:
+
+* "Surprise maximization reveals the community structure of complex networks".
+  Rodrigo Aldecoa and Ignacio Marín.
+  Scientific Reports 3, 1060 (2013).
+  http://www.nature.com/srep/2013/130114/srep01060/full/srep01060.html
+
+
+
+Programs included in this distribution
+======================================
+
+The following algorithms are included in SurpriseMe. If you use their solutions
+in your publications, please cite them appropriately:
+
+CPM: "Narrow scope for resolution-limit-free community detection"
+     Traag VA, Van Dooren P, Nesterov Y
+     Phys. Rev. E 84, 016114 (2011)
+
+Infomap: "Maps of random walks on complex networks reveal community structure"
+	 Rosvall M, Bergstrom CT
+	 Proc. Natl. Acad. Sci. USA 105, 1118 (2008)
+
+RB: "Statistical mechanics of community detection"
+    Reichardt J, Bornholdt S
+    Phys. Rev. E 74, 016110 (2006)
+
+RN: "Local resolution-limit-free Potts model for community detection"
+    Ronhovde P, Nussinov Z
+    Phys. Rev. E 81, 046114 (2010)
+
+RNSC: "Protein complex prediction via cost-based clustering"
+      King AD, Przulj N, Jurisica I
+      Bioinformatics 20, 3013 (2004)
+
+SCluster: "Jerarca: efficient analysis of complex networks using hierarchical clustering"
+	  Aldecoa R, Marin I
+	  Plos ONE 5, e11585 (2010)
+
+UVCluster: "Iterative cluster analysis of protein interaction data"
+	   Arnau V, Mars S, Marin I
+	   Bioinformatics 21, 364 (2005)
+	   (and also the same reference as SCluster)
+
+
+Compilation
+===========
+
+Note: The code should compile in any Linux distribution using its basic,
+standard libraries (g++, make...).
+
+
+Unzip the tar.gz file and enter the directory:
+
+  tar -xvzf SurpriseMe.tar.gz
+  cd SurpriseMe
+
+Build and compile the program:
+
+  make
+
+
+
+Usage
+=====
+
+Once the program is compiled, just run:
+
+  ./SurpriseMe.pl networkFile
+  
+where networkFile is the file containing the network to be analyzed.
+Each line of network_file should be of the form
+
+  id_1 id_2
+
+if node with id_1 is connected with node with id_2. Links are assumed 
+bidirectional, so that if id_1 id_2 is present in networkFile then 
+id_2 id_1 should not be present. Some examples of this format can be
+seen in the net_examples folder.
+
+
+Example:
+./SurpriseMe net_examples/sample.pairs
+
+
+
+Output files
+=============
+
+The execution of the program creates the following files:
+
+- networkFile.S			Contains the value of Surprise for the 
+				solution of each algorithm.
+				
+- networkFile_algorithm.part	Partition obtained by an algorithm.
+				Each line contains the name of a node
+				and its corresponding community
+				
+- networkFile_VI.meg		MEGA (www.megasoftware.net) input file.
+				Contains the distance matrix of all
+				solutions. Uses the Variation of
+				Information as a distance between partitions.
+				
+- networkFile_1-NMI.meg		MEGA (www.megasoftware.net) input file.
+				Contains the distance matrix of all
+				solutions. Uses (1 minus the Normalized
+				Mutual Information) as a distance between
+				partitions.
+				
+
+How to run only certain algorithms
+==================================
+
+You can modify line 27 in SurpriseMe.pl in order to run only a few algorithms.
+By default, the program runs all of them. Just remove from the array @algs
+those you want to exclude from the analysis.
+
+
+				
+Resources. Report bugs or suggestions
+=====================================
+
+* Homepage: https://github.com/raldecoa/SurpriseMe
+
+* Email: Rodrigo Aldecoa <raldecoa (at) ibv.csic.es>
+	 Ignacio Marín   <imarin (at) ibv.csic.es>

pysurprise-1.0.0/net_examples/karate.pairs

@@ -0,0 +1,78 @@
+2 1
+3 1
+4 1
+5 1
+6 1
+7 1
+8 1
+9 1
+11 1
+12 1
+13 1
+14 1
+18 1
+20 1
+22 1
+32 1
+3 2
+4 2
+8 2
+14 2
+18 2
+20 2
+22 2
+31 2
+4 3
+8 3
+9 3
+10 3
+14 3
+28 3
+29 3
+33 3
+8 4
+13 4
+14 4
+7 5
+11 5
+7 6
+11 6
+17 6
+17 7
+31 9
+33 9
+34 9
+34 10
+34 14
+33 15
+34 15
+33 16
+34 16
+33 19
+34 19
+34 20
+33 21
+34 21
+33 23
+34 23
+26 24
+28 24
+30 24
+33 24
+34 24
+26 25
+28 25
+32 25
+32 26
+30 27
+34 27
+34 28
+32 29
+34 29
+33 30
+34 30
+33 31
+34 31
+33 32
+34 32
+34 33