# 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/55/4b/52806eef3c06046a7110bf398dbd8446793ab203e037e09d98e3b2a182f4/speakeasy2-0.1.5.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.5",
"project_urls": {
"Repository": "https://github.com/SpeakEasy-2/python-speakeasy2"
},
"split_keywords": [
"network",
" community detection",
" cluster",
" graph"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fbe16d4dc48d17ff25a2cce051ad2db087d8723b03c76184b05405dbdab7139c",
"md5": "c9eb103756797b79288009c824c16302",
"sha256": "509b5ada171711a6f47a6468cb5437ecf0dcdedcbe238edfb70d3b7e908db355"
},
"downloads": -1,
"filename": "speakeasy2-0.1.5-cp310-cp310-macosx_13_0_x86_64.whl",
"has_sig": false,
"md5_digest": "c9eb103756797b79288009c824c16302",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 298929,
"upload_time": "2025-02-20T02:25:25",
"upload_time_iso_8601": "2025-02-20T02:25:25.967583Z",
"url": "https://files.pythonhosted.org/packages/fb/e1/6d4dc48d17ff25a2cce051ad2db087d8723b03c76184b05405dbdab7139c/speakeasy2-0.1.5-cp310-cp310-macosx_13_0_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6dd8b15c3c07f4ed47dc552691a130de22e46b97f4cfe834ce51df3164e4d6da",
"md5": "2770245e5ecbb5d2433757984c08bcd7",
"sha256": "facfd087a73374d975ee9cda088e4ced96ab52bc8c422d7ebf844c222e213ac6"
},
"downloads": -1,
"filename": "speakeasy2-0.1.5-cp310-cp310-macosx_14_0_arm64.whl",
"has_sig": false,
"md5_digest": "2770245e5ecbb5d2433757984c08bcd7",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 306811,
"upload_time": "2025-02-20T02:25:28",
"upload_time_iso_8601": "2025-02-20T02:25:28.278789Z",
"url": "https://files.pythonhosted.org/packages/6d/d8/b15c3c07f4ed47dc552691a130de22e46b97f4cfe834ce51df3164e4d6da/speakeasy2-0.1.5-cp310-cp310-macosx_14_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c51f9775a9181b8034fccf0cb528978eed3364fc2770a1d59ed47a612f724600",
"md5": "fcc60725cd5c1ddbf3ea7ce07ebd4173",
"sha256": "11d87b6bea823870704218e860aa186141297e28ef27e556dde2c2d4da5612eb"
},
"downloads": -1,
"filename": "speakeasy2-0.1.5-cp310-cp310-manylinux_2_39_x86_64.whl",
"has_sig": false,
"md5_digest": "fcc60725cd5c1ddbf3ea7ce07ebd4173",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 344829,
"upload_time": "2025-02-20T02:25:29",
"upload_time_iso_8601": "2025-02-20T02:25:29.841963Z",
"url": "https://files.pythonhosted.org/packages/c5/1f/9775a9181b8034fccf0cb528978eed3364fc2770a1d59ed47a612f724600/speakeasy2-0.1.5-cp310-cp310-manylinux_2_39_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "92ae9df4b6f12161f1f6846139802825d6ba92f6cba94656db7eec0e6b992b69",
"md5": "c423dfae528a2c2ff932fe7d04202766",
"sha256": "2785b08336a7ce3ee863142a7ac456e3afd18a3a59bab61b33d765be1a80a247"
},
"downloads": -1,
"filename": "speakeasy2-0.1.5-cp311-cp311-macosx_13_0_x86_64.whl",
"has_sig": false,
"md5_digest": "c423dfae528a2c2ff932fe7d04202766",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 305430,
"upload_time": "2025-02-20T02:25:32",
"upload_time_iso_8601": "2025-02-20T02:25:32.003050Z",
"url": "https://files.pythonhosted.org/packages/92/ae/9df4b6f12161f1f6846139802825d6ba92f6cba94656db7eec0e6b992b69/speakeasy2-0.1.5-cp311-cp311-macosx_13_0_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a6697b4987080fb7ff0b7f31990ec0ecddf75556690b5e17b3f74b374467d8f8",
"md5": "eb205179cb32e4141a9ddbff45769294",
"sha256": "66bcf04b7317371d6c73bc655f7956abf6545607d181b558e0bc4f3f0d29b6c1"
},
"downloads": -1,
"filename": "speakeasy2-0.1.5-cp311-cp311-macosx_14_0_arm64.whl",
"has_sig": false,
"md5_digest": "eb205179cb32e4141a9ddbff45769294",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 306809,
"upload_time": "2025-02-20T02:25:34",
"upload_time_iso_8601": "2025-02-20T02:25:34.273775Z",
"url": "https://files.pythonhosted.org/packages/a6/69/7b4987080fb7ff0b7f31990ec0ecddf75556690b5e17b3f74b374467d8f8/speakeasy2-0.1.5-cp311-cp311-macosx_14_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "739a221b58bf4dc5c70f9dae01efb69382e98df153c4b8c330deee77d4436802",
"md5": "c95f088c7092387c72afbbfe33b75035",
"sha256": "72f9615f5eb86c23795183d3153e05dd9934ee46f59be3eaeb916750261bbb14"
},
"downloads": -1,
"filename": "speakeasy2-0.1.5-cp311-cp311-manylinux_2_39_x86_64.whl",
"has_sig": false,
"md5_digest": "c95f088c7092387c72afbbfe33b75035",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 345138,
"upload_time": "2025-02-20T02:25:35",
"upload_time_iso_8601": "2025-02-20T02:25:35.756510Z",
"url": "https://files.pythonhosted.org/packages/73/9a/221b58bf4dc5c70f9dae01efb69382e98df153c4b8c330deee77d4436802/speakeasy2-0.1.5-cp311-cp311-manylinux_2_39_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c88126f0a53c89293f6919defe401e024858d5a6d1b445c93298f8ed11347aa9",
"md5": "a6aea3963d2e46e9ceb96579dca4d910",
"sha256": "37b8fb5ef5c5e21d73104936488c0d64418a72e0e5f3ed887e67d553571faaeb"
},
"downloads": -1,
"filename": "speakeasy2-0.1.5-cp312-cp312-macosx_13_0_x86_64.whl",
"has_sig": false,
"md5_digest": "a6aea3963d2e46e9ceb96579dca4d910",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 305430,
"upload_time": "2025-02-20T02:25:37",
"upload_time_iso_8601": "2025-02-20T02:25:37.814477Z",
"url": "https://files.pythonhosted.org/packages/c8/81/26f0a53c89293f6919defe401e024858d5a6d1b445c93298f8ed11347aa9/speakeasy2-0.1.5-cp312-cp312-macosx_13_0_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3637d75de0b4d967c088be1134aecb0bb1a7220a4d3fc3a45ab967a138bceb21",
"md5": "1fa72793d39078daf46cd91747eb098d",
"sha256": "a213c67af47dca9449d8fb3234de8ac87779a870ec997bf5dd7bedca4b424ec2"
},
"downloads": -1,
"filename": "speakeasy2-0.1.5-cp312-cp312-macosx_14_0_arm64.whl",
"has_sig": false,
"md5_digest": "1fa72793d39078daf46cd91747eb098d",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 306810,
"upload_time": "2025-02-20T02:25:39",
"upload_time_iso_8601": "2025-02-20T02:25:39.193140Z",
"url": "https://files.pythonhosted.org/packages/36/37/d75de0b4d967c088be1134aecb0bb1a7220a4d3fc3a45ab967a138bceb21/speakeasy2-0.1.5-cp312-cp312-macosx_14_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "12584cd761f666db1ed6a6b960c951afcd62596da61923e631e151bb2ceae48e",
"md5": "6da82c85234f63a0ae09395af5c42bc7",
"sha256": "0c86e86d081a3ef52fbb12da0472e91686a64c2afd223cb872599b1569247e43"
},
"downloads": -1,
"filename": "speakeasy2-0.1.5-cp312-cp312-manylinux_2_39_x86_64.whl",
"has_sig": false,
"md5_digest": "6da82c85234f63a0ae09395af5c42bc7",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 345333,
"upload_time": "2025-02-20T02:25:41",
"upload_time_iso_8601": "2025-02-20T02:25:41.532435Z",
"url": "https://files.pythonhosted.org/packages/12/58/4cd761f666db1ed6a6b960c951afcd62596da61923e631e151bb2ceae48e/speakeasy2-0.1.5-cp312-cp312-manylinux_2_39_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9e96cd1bfeb5bfa2b3ab984a075315ff21e9173068ae5afbef5963d4b70fb124",
"md5": "ee60021883eeab71a1b55b6cc2fcd624",
"sha256": "9c1ce0375f6dd59b4591a28712c3b52c7da4aba7436f7e9419a1c7a4aef26e9d"
},
"downloads": -1,
"filename": "speakeasy2-0.1.5-cp313-cp313-macosx_13_0_x86_64.whl",
"has_sig": false,
"md5_digest": "ee60021883eeab71a1b55b6cc2fcd624",
"packagetype": "bdist_wheel",
"python_version": "cp313",
"requires_python": ">=3.10",
"size": 305401,
"upload_time": "2025-02-20T02:25:45",
"upload_time_iso_8601": "2025-02-20T02:25:45.200249Z",
"url": "https://files.pythonhosted.org/packages/9e/96/cd1bfeb5bfa2b3ab984a075315ff21e9173068ae5afbef5963d4b70fb124/speakeasy2-0.1.5-cp313-cp313-macosx_13_0_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d5ea942e56f412b87222c0281d6e5b4a0dd34831355a4aac90751f63fdf63cb5",
"md5": "7aee43bb987c44577f63fc6178346533",
"sha256": "09c50302c677266775a270710da00c72434ca51a9fe01388d294fd885d509626"
},
"downloads": -1,
"filename": "speakeasy2-0.1.5-cp313-cp313-macosx_14_0_arm64.whl",
"has_sig": false,
"md5_digest": "7aee43bb987c44577f63fc6178346533",
"packagetype": "bdist_wheel",
"python_version": "cp313",
"requires_python": ">=3.10",
"size": 306788,
"upload_time": "2025-02-20T02:25:47",
"upload_time_iso_8601": "2025-02-20T02:25:47.237750Z",
"url": "https://files.pythonhosted.org/packages/d5/ea/942e56f412b87222c0281d6e5b4a0dd34831355a4aac90751f63fdf63cb5/speakeasy2-0.1.5-cp313-cp313-macosx_14_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "20c9f4f6cc198f79e74eb5ae8b1244866a5b8b7cabe288ffd3e9b80ae6d35331",
"md5": "532d49a4321464d6c4f4f24c87ba065f",
"sha256": "d5eeb57672d79da7950104f602911764a6335dcf17a8f1865f8cbe8c79f50e08"
},
"downloads": -1,
"filename": "speakeasy2-0.1.5-cp313-cp313-manylinux_2_39_x86_64.whl",
"has_sig": false,
"md5_digest": "532d49a4321464d6c4f4f24c87ba065f",
"packagetype": "bdist_wheel",
"python_version": "cp313",
"requires_python": ">=3.10",
"size": 345379,
"upload_time": "2025-02-20T02:25:49",
"upload_time_iso_8601": "2025-02-20T02:25:49.256796Z",
"url": "https://files.pythonhosted.org/packages/20/c9/f4f6cc198f79e74eb5ae8b1244866a5b8b7cabe288ffd3e9b80ae6d35331/speakeasy2-0.1.5-cp313-cp313-manylinux_2_39_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "554b52806eef3c06046a7110bf398dbd8446793ab203e037e09d98e3b2a182f4",
"md5": "f3f87512775eab0696a242b9a3f8c97e",
"sha256": "93ef8869c00965bd504c8aa3e8992d075fa93e5346f355991b83fe6fa9a7991b"
},
"downloads": -1,
"filename": "speakeasy2-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "f3f87512775eab0696a242b9a3f8c97e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 2651903,
"upload_time": "2025-02-20T02:25:50",
"upload_time_iso_8601": "2025-02-20T02:25:50.713706Z",
"url": "https://files.pythonhosted.org/packages/55/4b/52806eef3c06046a7110bf398dbd8446793ab203e037e09d98e3b2a182f4/speakeasy2-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-20 02:25:50",
"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"
}