# Python SpeakEasy2 package
Provides the SpeakEasy2 community detection algorithm to cluster graph's stored as igraph's data type. The algorithm is described in the [Genome Biology article](https://genomebiology.biomedcentral.com/articles/10.1186/s13059-023-03062-0).
This uses a rewrite of the algorithm used in the publication, to see a comparison to the original implementation see [the benchmarks](https://github.com/SpeakEasy-2/libspeakeasy2/tree/master/benchmarks)
Example:
```python
import igraph as ig
import speakeasy2 as se2
g = ig.Graph.Famous("Zachary")
memb = se2.cluster(g)
```
Membership is returned as an `igraph.clustering.VertexClustering` object.
Use `print` to view the membership:
```python
print(memb)
```
```python
Clustering with 34 elements and 9 clusters
[0] 0, 1, 2, 3, 7, 12, 13, 17, 19, 21
[1] 14, 15, 18, 20, 22, 32, 33
[2] 8, 30
[3] 26, 29
[4] 11
[5] 23, 24, 25, 27, 31
[6] 9
[7] 28
[8] 4, 5, 6, 10, 16
```
Or to convert to a python list for use outside of `igraph` run `memb.membership`.
From the results, a node ordering can be computed to group nodes in a community together. This can be used as an index and works to display the community structure using a heatmap to view the adjacency matrix.
```python
ordering = se2.order_nodes(g, memb)
```
SpeakEasy 2 can work with weighted graphs by either passing weights as a list with length equal to the number of edges or by using the igraph attribute table.
```python
g.es["weight"] = [1 for _ in range(g.ecount())]
memb = se2.cluster(g)
```
By default, SpeakEasy 2 will check if there is an edge attribute associated with the graph named `weight` and use those as weights. If you want to use a different edge attribute, pass the name of the attribute.
```python
memb = se2.cluster(g, weights="tie_strength")
```
Or if a graph has a weight edge attribute but you don't want to use them, explicitly pass `None` to the `weights` keyword argument.
Subclustering can be used to detect hierarchical community structure.
```python
memb = se2.cluster(g, subcluster=2)
```
The number determines how many levels to perform community detection at. The default 1 means only to perform community detection at the top level (i.e. no subclustering). When subclustering, membership will be a list of `igraph.VertexClustering` objects, the top level membership will be the object at index 0.
A few other useful keywords arguments are `max_threads`, `verbose`, and `seed`. The `max_thread` keyword determines how many processors SpeakEasy 2 is allowed to use. By default the value returned by OpenMP is used. To prevent parallel processing, explicitly pass `max_threads = 1` to the method.
The `verbose` option will cause the algorithm to print out some information about the process.
For reproducible results, the `seed` option sets the seed of the random number generator. Note: this is a random number generator managed by the underlying C library and is independent of other random number generators that might have been set in python.
## Installation
speakeasy2 is available from pypi so it can be installed with `pip` or other package managers.
```bash
pip install --user speakeasy2
```
## Building from source
Compilation depends on a C compiler, CMake, and (optionally) ninja.
Since the `igraph` package is supplied by the vendored SE2 C library, after cloning the source directory, submodules most be recursively initialized.
```bash
git clone "https://github.com/SpeakEasy-2/python-speakeasy2"
cd python-speakeasy2
git submodule update --init --recursive
```
The CMake calls are wrapped into the python build logic in the `build_script.py` (this is a `poetry` specific method for building C extensions).
This allows the package to be built using various python build backends.
Since this package uses poetry, the suggested way to build the package is invoking `poetry build` and `poetry install`, which will install in development mode.
For convenience, the provided `Makefile` defines the `install` target to do this and `clean-dist` to clear all generated files (as well as other targets, see the file for more).
It should now be possible to run scripts through `poetry`:
```bash
poetry run ipython path/to/script.py
```
Or enter a python repository with the private environment activate in the same way.
```bash
poetry run ipython
```
If you don't want to use `poetry`, it's possible to build with other method in their standard way.
For example `python -m build` or `pip install --editable .` should both work.
Raw data
{
"_id": null,
"home_page": null,
"name": "speakeasy2",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "network, community detection, cluster, graph",
"author": "David R Connell",
"author_email": "davidconnell12@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/9d/49/eedb63d49800bc461aa3a4f54c69fed99a7ecc1268fa5f6131849f99b178/speakeasy2-0.1.7.tar.gz",
"platform": null,
"description": "# Python SpeakEasy2 package\n\n\n\n\n\nProvides the SpeakEasy2 community detection algorithm to cluster graph's stored as igraph's data type. The algorithm is described in the [Genome Biology article](https://genomebiology.biomedcentral.com/articles/10.1186/s13059-023-03062-0).\n\nThis uses a rewrite of the algorithm used in the publication, to see a comparison to the original implementation see [the benchmarks](https://github.com/SpeakEasy-2/libspeakeasy2/tree/master/benchmarks)\n\nExample:\n\n```python\n import igraph as ig\n import speakeasy2 as se2\n\n g = ig.Graph.Famous(\"Zachary\")\n memb = se2.cluster(g)\n```\n\nMembership is returned as an `igraph.clustering.VertexClustering` object.\nUse `print` to view the membership:\n\n```python\nprint(memb)\n```\n\n```python\nClustering with 34 elements and 9 clusters\n[0] 0, 1, 2, 3, 7, 12, 13, 17, 19, 21\n[1] 14, 15, 18, 20, 22, 32, 33\n[2] 8, 30\n[3] 26, 29\n[4] 11\n[5] 23, 24, 25, 27, 31\n[6] 9\n[7] 28\n[8] 4, 5, 6, 10, 16\n```\n\nOr to convert to a python list for use outside of `igraph` run `memb.membership`.\n\nFrom the results, a node ordering can be computed to group nodes in a community together. This can be used as an index and works to display the community structure using a heatmap to view the adjacency matrix.\n\n```python\nordering = se2.order_nodes(g, memb)\n```\n\nSpeakEasy 2 can work with weighted graphs by either passing weights as a list with length equal to the number of edges or by using the igraph attribute table.\n\n```python\ng.es[\"weight\"] = [1 for _ in range(g.ecount())]\nmemb = se2.cluster(g)\n```\n\nBy default, SpeakEasy 2 will check if there is an edge attribute associated with the graph named `weight` and use those as weights. If you want to use a different edge attribute, pass the name of the attribute.\n\n```python\nmemb = se2.cluster(g, weights=\"tie_strength\")\n```\n\nOr if a graph has a weight edge attribute but you don't want to use them, explicitly pass `None` to the `weights` keyword argument.\n\nSubclustering can be used to detect hierarchical community structure.\n\n```python\nmemb = se2.cluster(g, subcluster=2)\n```\n\nThe number determines how many levels to perform community detection at. The default 1 means only to perform community detection at the top level (i.e. no subclustering). When subclustering, membership will be a list of `igraph.VertexClustering` objects, the top level membership will be the object at index 0.\n\nA few other useful keywords arguments are `max_threads`, `verbose`, and `seed`. The `max_thread` keyword determines how many processors SpeakEasy 2 is allowed to use. By default the value returned by OpenMP is used. To prevent parallel processing, explicitly pass `max_threads = 1` to the method.\n\nThe `verbose` option will cause the algorithm to print out some information about the process.\n\nFor reproducible results, the `seed` option sets the seed of the random number generator. Note: this is a random number generator managed by the underlying C library and is independent of other random number generators that might have been set in python.\n\n## Installation\n\nspeakeasy2 is available from pypi so it can be installed with `pip` or other package managers.\n\n```bash\npip install --user speakeasy2\n```\n\n## Building from source\n\nCompilation depends on a C compiler, CMake, and (optionally) ninja.\n\nSince the `igraph` package is supplied by the vendored SE2 C library, after cloning the source directory, submodules most be recursively initialized.\n\n```bash\ngit clone \"https://github.com/SpeakEasy-2/python-speakeasy2\"\ncd python-speakeasy2\ngit submodule update --init --recursive\n```\n\nThe CMake calls are wrapped into the python build logic in the `build_script.py` (this is a `poetry` specific method for building C extensions).\nThis allows the package to be built using various python build backends.\nSince this package uses poetry, the suggested way to build the package is invoking `poetry build` and `poetry install`, which will install in development mode.\n\nFor convenience, the provided `Makefile` defines the `install` target to do this and `clean-dist` to clear all generated files (as well as other targets, see the file for more).\n\nIt should now be possible to run scripts through `poetry`:\n\n```bash\npoetry run ipython path/to/script.py\n```\n\nOr enter a python repository with the private environment activate in the same way.\n\n```bash\npoetry run ipython\n```\n\nIf you don't want to use `poetry`, it's possible to build with other method in their standard way.\nFor example `python -m build` or `pip install --editable .` should both work.\n\n",
"bugtrack_url": null,
"license": "GPLv3+",
"summary": "SpeakEasy2 community detection algorithm",
"version": "0.1.7",
"project_urls": {
"Repository": "https://github.com/SpeakEasy-2/python-speakeasy2"
},
"split_keywords": [
"network",
" community detection",
" cluster",
" graph"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2450c1b671b61bf2525b8196177cc65dd0e085bb31e1259c85b5f3af283330eb",
"md5": "04175e3f2ff0c72a9ddd84a53c49c997",
"sha256": "68ee97f31afdabe2281c28ec46ba34de1d8d5258984c45b6fd60ca5dce31efdb"
},
"downloads": -1,
"filename": "speakeasy2-0.1.7-cp310-cp310-macosx_13_0_x86_64.whl",
"has_sig": false,
"md5_digest": "04175e3f2ff0c72a9ddd84a53c49c997",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 298137,
"upload_time": "2025-09-05T03:14:15",
"upload_time_iso_8601": "2025-09-05T03:14:15.525908Z",
"url": "https://files.pythonhosted.org/packages/24/50/c1b671b61bf2525b8196177cc65dd0e085bb31e1259c85b5f3af283330eb/speakeasy2-0.1.7-cp310-cp310-macosx_13_0_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "dc28544923d42f0d45a1661dad07c86a45a7d060f8b6f53761face991be125cb",
"md5": "c8388987b6347bd0644e527a220539fc",
"sha256": "c4763a940e4a2faa1194585f7de079eb9f33dc488127929da7e17cc4080f3ed2"
},
"downloads": -1,
"filename": "speakeasy2-0.1.7-cp310-cp310-macosx_15_0_arm64.whl",
"has_sig": false,
"md5_digest": "c8388987b6347bd0644e527a220539fc",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 300705,
"upload_time": "2025-09-05T03:14:17",
"upload_time_iso_8601": "2025-09-05T03:14:17.418474Z",
"url": "https://files.pythonhosted.org/packages/dc/28/544923d42f0d45a1661dad07c86a45a7d060f8b6f53761face991be125cb/speakeasy2-0.1.7-cp310-cp310-macosx_15_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ebb05bccf02126baa76b868728ef7a8abfc63223d8a2bc9c63c45e194e8769a7",
"md5": "5c586c3a8b8c4f824bc5bfd37d12e466",
"sha256": "a23ac30d771cd6e3a3e3326bfa495e6703a85d3d5c6bcb02d37bf4c27686f02a"
},
"downloads": -1,
"filename": "speakeasy2-0.1.7-cp310-cp310-manylinux_2_39_x86_64.whl",
"has_sig": false,
"md5_digest": "5c586c3a8b8c4f824bc5bfd37d12e466",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 345451,
"upload_time": "2025-09-05T03:14:19",
"upload_time_iso_8601": "2025-09-05T03:14:19.096149Z",
"url": "https://files.pythonhosted.org/packages/eb/b0/5bccf02126baa76b868728ef7a8abfc63223d8a2bc9c63c45e194e8769a7/speakeasy2-0.1.7-cp310-cp310-manylinux_2_39_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "52f71b88869bd65de65a356a0bdd6a338ffdc3c27c40efa810ede1e27ee52125",
"md5": "6738dd5dda0189348f9da514ec05ce6f",
"sha256": "78ef2c0cd10846563ddc24ead725f26dec207e9b0c221fa377fcc6d4afd463b3"
},
"downloads": -1,
"filename": "speakeasy2-0.1.7-cp311-cp311-macosx_13_0_x86_64.whl",
"has_sig": false,
"md5_digest": "6738dd5dda0189348f9da514ec05ce6f",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 304650,
"upload_time": "2025-09-05T03:14:20",
"upload_time_iso_8601": "2025-09-05T03:14:20.540417Z",
"url": "https://files.pythonhosted.org/packages/52/f7/1b88869bd65de65a356a0bdd6a338ffdc3c27c40efa810ede1e27ee52125/speakeasy2-0.1.7-cp311-cp311-macosx_13_0_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b4231c97ba2a6725d002d1c737a79e63d88b7c10560c879a60f957f49c4c51d9",
"md5": "694937f20598ef0ae271af89a75b29cd",
"sha256": "4e78c9aca0fe5e3a1288f9866c814a5fbec19f92c59f55643847b7dddd74679e"
},
"downloads": -1,
"filename": "speakeasy2-0.1.7-cp311-cp311-macosx_15_0_arm64.whl",
"has_sig": false,
"md5_digest": "694937f20598ef0ae271af89a75b29cd",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 300705,
"upload_time": "2025-09-05T03:14:21",
"upload_time_iso_8601": "2025-09-05T03:14:21.935853Z",
"url": "https://files.pythonhosted.org/packages/b4/23/1c97ba2a6725d002d1c737a79e63d88b7c10560c879a60f957f49c4c51d9/speakeasy2-0.1.7-cp311-cp311-macosx_15_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "175f76858a7d9de70e9504e11933037ed56d82db3a337dc131fb1c5766958aac",
"md5": "f06e1fd126e91f36f5bb14ba38b6642f",
"sha256": "d697f95156406ae7c0f37a7b9c4b4c31383c45c6729f9b96a9bddb305c36dd50"
},
"downloads": -1,
"filename": "speakeasy2-0.1.7-cp311-cp311-manylinux_2_39_x86_64.whl",
"has_sig": false,
"md5_digest": "f06e1fd126e91f36f5bb14ba38b6642f",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 345757,
"upload_time": "2025-09-05T03:14:23",
"upload_time_iso_8601": "2025-09-05T03:14:23.135801Z",
"url": "https://files.pythonhosted.org/packages/17/5f/76858a7d9de70e9504e11933037ed56d82db3a337dc131fb1c5766958aac/speakeasy2-0.1.7-cp311-cp311-manylinux_2_39_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6bc75877c55cf6b9e028e9c4f1433fe85319ee6e6ae9be468e24c909af3ee344",
"md5": "2cc36101e30eaab6dc97407c6cc11c61",
"sha256": "261034bc66dba935fdca852e1a43900699fd56f0e0c58b62f6d658b56f881a27"
},
"downloads": -1,
"filename": "speakeasy2-0.1.7-cp312-cp312-macosx_13_0_x86_64.whl",
"has_sig": false,
"md5_digest": "2cc36101e30eaab6dc97407c6cc11c61",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 304655,
"upload_time": "2025-09-05T03:14:24",
"upload_time_iso_8601": "2025-09-05T03:14:24.789991Z",
"url": "https://files.pythonhosted.org/packages/6b/c7/5877c55cf6b9e028e9c4f1433fe85319ee6e6ae9be468e24c909af3ee344/speakeasy2-0.1.7-cp312-cp312-macosx_13_0_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9015acab55c045d078bc12552434e72d53a48a3504056fc61b3551ea4d62c12d",
"md5": "2770d757d5471e1edfbd5f453c02bfc1",
"sha256": "8a4c82b39fe0ce67a0d1605533b04e3711fa944102129262ba8c28ea835308f6"
},
"downloads": -1,
"filename": "speakeasy2-0.1.7-cp312-cp312-macosx_15_0_arm64.whl",
"has_sig": false,
"md5_digest": "2770d757d5471e1edfbd5f453c02bfc1",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 300710,
"upload_time": "2025-09-05T03:14:26",
"upload_time_iso_8601": "2025-09-05T03:14:26.433655Z",
"url": "https://files.pythonhosted.org/packages/90/15/acab55c045d078bc12552434e72d53a48a3504056fc61b3551ea4d62c12d/speakeasy2-0.1.7-cp312-cp312-macosx_15_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bc990070740a31ffab8f6e921744fad7c3e1e7285811036c78d1a51e9dd94190",
"md5": "ede565a29fd39abe0386dac87a8f9cb8",
"sha256": "f1cc1298f4e9c33111049fcaff24c24b4ec1039aedafdee508e277676230a09f"
},
"downloads": -1,
"filename": "speakeasy2-0.1.7-cp312-cp312-manylinux_2_39_x86_64.whl",
"has_sig": false,
"md5_digest": "ede565a29fd39abe0386dac87a8f9cb8",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 345947,
"upload_time": "2025-09-05T03:14:28",
"upload_time_iso_8601": "2025-09-05T03:14:28.068417Z",
"url": "https://files.pythonhosted.org/packages/bc/99/0070740a31ffab8f6e921744fad7c3e1e7285811036c78d1a51e9dd94190/speakeasy2-0.1.7-cp312-cp312-manylinux_2_39_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "028a93865e76ce46996da766051b739b4f15ad8f981e0f64c9d8f6463c5f6b9a",
"md5": "f77975dc8468cc6a36744a38215e23cf",
"sha256": "fac5f7f014b9d6bcd03eeea948b31c3838e39e9201e325966dfc261f40f99b94"
},
"downloads": -1,
"filename": "speakeasy2-0.1.7-cp313-cp313-macosx_13_0_x86_64.whl",
"has_sig": false,
"md5_digest": "f77975dc8468cc6a36744a38215e23cf",
"packagetype": "bdist_wheel",
"python_version": "cp313",
"requires_python": ">=3.10",
"size": 304619,
"upload_time": "2025-09-05T03:14:29",
"upload_time_iso_8601": "2025-09-05T03:14:29.672043Z",
"url": "https://files.pythonhosted.org/packages/02/8a/93865e76ce46996da766051b739b4f15ad8f981e0f64c9d8f6463c5f6b9a/speakeasy2-0.1.7-cp313-cp313-macosx_13_0_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1d4b08f17448473a9b98362afebc10383d90f0397f82008222a3e90d8f30a09e",
"md5": "df25313b020e97c53b80d5ddda1ea64e",
"sha256": "157a288635afaa16145ca88f890ffdd33c666ec92e3c4d9899cd90fe04929d1b"
},
"downloads": -1,
"filename": "speakeasy2-0.1.7-cp313-cp313-macosx_15_0_arm64.whl",
"has_sig": false,
"md5_digest": "df25313b020e97c53b80d5ddda1ea64e",
"packagetype": "bdist_wheel",
"python_version": "cp313",
"requires_python": ">=3.10",
"size": 300688,
"upload_time": "2025-09-05T03:14:31",
"upload_time_iso_8601": "2025-09-05T03:14:31.737278Z",
"url": "https://files.pythonhosted.org/packages/1d/4b/08f17448473a9b98362afebc10383d90f0397f82008222a3e90d8f30a09e/speakeasy2-0.1.7-cp313-cp313-macosx_15_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "448683d08d2723155d77f3069351a8b5f3bcbec08d86ca999ca09c7eef557cd7",
"md5": "4fc6763a61e18be40c6a5d29b2df50a3",
"sha256": "662d944923537cd2cc4ddc9ef6f09aa504c632e9fc4c713d3048e8a11dcc9496"
},
"downloads": -1,
"filename": "speakeasy2-0.1.7-cp313-cp313-manylinux_2_39_x86_64.whl",
"has_sig": false,
"md5_digest": "4fc6763a61e18be40c6a5d29b2df50a3",
"packagetype": "bdist_wheel",
"python_version": "cp313",
"requires_python": ">=3.10",
"size": 345993,
"upload_time": "2025-09-05T03:14:32",
"upload_time_iso_8601": "2025-09-05T03:14:32.995442Z",
"url": "https://files.pythonhosted.org/packages/44/86/83d08d2723155d77f3069351a8b5f3bcbec08d86ca999ca09c7eef557cd7/speakeasy2-0.1.7-cp313-cp313-manylinux_2_39_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9d49eedb63d49800bc461aa3a4f54c69fed99a7ecc1268fa5f6131849f99b178",
"md5": "3e7dcf5c9f002b154adb5dbd278bccde",
"sha256": "9591c5b877c94906a6b997d6d9509d41377ae24e40e1918e4492a568a16996ef"
},
"downloads": -1,
"filename": "speakeasy2-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "3e7dcf5c9f002b154adb5dbd278bccde",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 2646516,
"upload_time": "2025-09-05T03:14:34",
"upload_time_iso_8601": "2025-09-05T03:14:34.435201Z",
"url": "https://files.pythonhosted.org/packages/9d/49/eedb63d49800bc461aa3a4f54c69fed99a7ecc1268fa5f6131849f99b178/speakeasy2-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-05 03:14:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SpeakEasy-2",
"github_project": "python-speakeasy2",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "speakeasy2"
}
JSON
