# 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": "https://github.com/SpeakEasy-2/python-speakeasy2",
"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/fc/84/df5281482af575f368d9e279279f2929b9c9b000c4419d1d52e1d925c020/speakeasy2-0.1.3.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.3",
"project_urls": {
"Homepage": "https://github.com/SpeakEasy-2/python-speakeasy2",
"Repository": "https://github.com/SpeakEasy-2/python-speakeasy2"
},
"split_keywords": [
"network",
" community detection",
" cluster",
" graph"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a80a69938a036d6c4281bc82790880ef97fd55aa10963944a46512faed29b6f5",
"md5": "b463a8d1ef7a59a09d5cd89fc21f93cf",
"sha256": "db738637763c302c1fbb547f2a5a70ba9a34f6dacb09ed1ebda9a19d3346f57b"
},
"downloads": -1,
"filename": "speakeasy2-0.1.3-cp310-cp310-macosx_13_0_x86_64.whl",
"has_sig": false,
"md5_digest": "b463a8d1ef7a59a09d5cd89fc21f93cf",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 294463,
"upload_time": "2024-10-29T03:38:17",
"upload_time_iso_8601": "2024-10-29T03:38:17.336274Z",
"url": "https://files.pythonhosted.org/packages/a8/0a/69938a036d6c4281bc82790880ef97fd55aa10963944a46512faed29b6f5/speakeasy2-0.1.3-cp310-cp310-macosx_13_0_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b1b39f5cd95cc9833dd4cacded5bf643cc945c49695ad8f28c7d511c04308902",
"md5": "2bde3cb76c61fb717573eb9d4ca7cd0a",
"sha256": "6bba57f6d06f08097d8ff3f41ed5367b86d76234deecd97c021d298ae4933d27"
},
"downloads": -1,
"filename": "speakeasy2-0.1.3-cp310-cp310-macosx_14_0_arm64.whl",
"has_sig": false,
"md5_digest": "2bde3cb76c61fb717573eb9d4ca7cd0a",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 301602,
"upload_time": "2024-10-29T03:38:19",
"upload_time_iso_8601": "2024-10-29T03:38:19.079434Z",
"url": "https://files.pythonhosted.org/packages/b1/b3/9f5cd95cc9833dd4cacded5bf643cc945c49695ad8f28c7d511c04308902/speakeasy2-0.1.3-cp310-cp310-macosx_14_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "925b858ea04c8db9125c7b8108b756f4daf68b134d9b7bb3b97604929874b57c",
"md5": "1003d76a202e02d485a560454cfa1b82",
"sha256": "ae3d6f18684d4990aa2da5196f51fa1493bb02e70ae4c1a33e8b0f6c232d1eed"
},
"downloads": -1,
"filename": "speakeasy2-0.1.3-cp310-cp310-manylinux_2_35_x86_64.whl",
"has_sig": false,
"md5_digest": "1003d76a202e02d485a560454cfa1b82",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 336209,
"upload_time": "2024-10-29T03:38:20",
"upload_time_iso_8601": "2024-10-29T03:38:20.712764Z",
"url": "https://files.pythonhosted.org/packages/92/5b/858ea04c8db9125c7b8108b756f4daf68b134d9b7bb3b97604929874b57c/speakeasy2-0.1.3-cp310-cp310-manylinux_2_35_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5304b4f240db70c2ea58854d836a4cec0d71ce5cb7e86f526031cfd7b7a79d8b",
"md5": "5c80beec29a80e3a04252b022a48874e",
"sha256": "ccec32ac584520b6cf14a440906f572b9200d8f5309f456ab196302809e6544a"
},
"downloads": -1,
"filename": "speakeasy2-0.1.3-cp311-cp311-macosx_13_0_x86_64.whl",
"has_sig": false,
"md5_digest": "5c80beec29a80e3a04252b022a48874e",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 299901,
"upload_time": "2024-10-29T03:38:22",
"upload_time_iso_8601": "2024-10-29T03:38:22.159424Z",
"url": "https://files.pythonhosted.org/packages/53/04/b4f240db70c2ea58854d836a4cec0d71ce5cb7e86f526031cfd7b7a79d8b/speakeasy2-0.1.3-cp311-cp311-macosx_13_0_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5a14996f0cb61c05bf35176acb5a393200ffb79e513937df8df64eb02eb72889",
"md5": "28d5c0afdab2b90b55a3386064909c64",
"sha256": "56bfba53d78681ad04b8450547ea7554a62c877fc404c6e8d6b1a266ab132067"
},
"downloads": -1,
"filename": "speakeasy2-0.1.3-cp311-cp311-macosx_14_0_arm64.whl",
"has_sig": false,
"md5_digest": "28d5c0afdab2b90b55a3386064909c64",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 301603,
"upload_time": "2024-10-29T03:38:23",
"upload_time_iso_8601": "2024-10-29T03:38:23.688691Z",
"url": "https://files.pythonhosted.org/packages/5a/14/996f0cb61c05bf35176acb5a393200ffb79e513937df8df64eb02eb72889/speakeasy2-0.1.3-cp311-cp311-macosx_14_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3432ec3b84b74f8b464c2ef1279971e65d2fd38544f629be3c5d846df9c3c217",
"md5": "a32dd1ea3b9d74a9a7730c7920b3a829",
"sha256": "4b5bb89e42c4fcf4cd8f2c585f6378c214087add9b7f6cdf8017b59018c8b15e"
},
"downloads": -1,
"filename": "speakeasy2-0.1.3-cp311-cp311-manylinux_2_35_x86_64.whl",
"has_sig": false,
"md5_digest": "a32dd1ea3b9d74a9a7730c7920b3a829",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 336278,
"upload_time": "2024-10-29T03:38:25",
"upload_time_iso_8601": "2024-10-29T03:38:25.190185Z",
"url": "https://files.pythonhosted.org/packages/34/32/ec3b84b74f8b464c2ef1279971e65d2fd38544f629be3c5d846df9c3c217/speakeasy2-0.1.3-cp311-cp311-manylinux_2_35_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "95f4c591cd2cb14234ed3505b584bb92a642e0f5e7c9c7af81988c0f382e0f5c",
"md5": "a711287b256204688c4ea794e5420020",
"sha256": "2f0d714c144699d55513491701ac16dccaa0197e7a8b89aa4f1a7cc2a1b7724a"
},
"downloads": -1,
"filename": "speakeasy2-0.1.3-cp312-cp312-macosx_13_0_x86_64.whl",
"has_sig": false,
"md5_digest": "a711287b256204688c4ea794e5420020",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 299905,
"upload_time": "2024-10-29T03:38:26",
"upload_time_iso_8601": "2024-10-29T03:38:26.704714Z",
"url": "https://files.pythonhosted.org/packages/95/f4/c591cd2cb14234ed3505b584bb92a642e0f5e7c9c7af81988c0f382e0f5c/speakeasy2-0.1.3-cp312-cp312-macosx_13_0_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e10e497102bfd99d141099b323177b27daabdd12e39bc453fb4302c67c5ff9b1",
"md5": "627f20d0fdd008dad1a68fa4884a6ec8",
"sha256": "c79d6a2e9c8dff19d5421ca3a9f9754ae2a584256449d6216d6264a77c8283ea"
},
"downloads": -1,
"filename": "speakeasy2-0.1.3-cp312-cp312-macosx_14_0_arm64.whl",
"has_sig": false,
"md5_digest": "627f20d0fdd008dad1a68fa4884a6ec8",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 301597,
"upload_time": "2024-10-29T03:38:28",
"upload_time_iso_8601": "2024-10-29T03:38:28.084958Z",
"url": "https://files.pythonhosted.org/packages/e1/0e/497102bfd99d141099b323177b27daabdd12e39bc453fb4302c67c5ff9b1/speakeasy2-0.1.3-cp312-cp312-macosx_14_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "21f8455c11ae72e13dc39127b6e2303901b346ef30c3fb39fd408d7b6e63d702",
"md5": "e9756036938eafa9555e405438d1aaf6",
"sha256": "f5fdc90489c165d8b6d33d9faf6fbf2defb763bdcd9dd361d231a9efd8df47ee"
},
"downloads": -1,
"filename": "speakeasy2-0.1.3-cp312-cp312-manylinux_2_35_x86_64.whl",
"has_sig": false,
"md5_digest": "e9756036938eafa9555e405438d1aaf6",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 336434,
"upload_time": "2024-10-29T03:38:29",
"upload_time_iso_8601": "2024-10-29T03:38:29.044469Z",
"url": "https://files.pythonhosted.org/packages/21/f8/455c11ae72e13dc39127b6e2303901b346ef30c3fb39fd408d7b6e63d702/speakeasy2-0.1.3-cp312-cp312-manylinux_2_35_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8de6eb50846299b035511237a78686ab69955c9c682461c6bcea23e38ab28ec4",
"md5": "da5dd60e0df78fb3356777bd52787962",
"sha256": "2a2063e2568d2cbf531b5630e0810ef648e8362921a67c1d148a06d0af516fb5"
},
"downloads": -1,
"filename": "speakeasy2-0.1.3-cp313-cp313-macosx_13_0_x86_64.whl",
"has_sig": false,
"md5_digest": "da5dd60e0df78fb3356777bd52787962",
"packagetype": "bdist_wheel",
"python_version": "cp313",
"requires_python": ">=3.10",
"size": 299890,
"upload_time": "2024-10-29T03:38:30",
"upload_time_iso_8601": "2024-10-29T03:38:30.316554Z",
"url": "https://files.pythonhosted.org/packages/8d/e6/eb50846299b035511237a78686ab69955c9c682461c6bcea23e38ab28ec4/speakeasy2-0.1.3-cp313-cp313-macosx_13_0_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3a0f659fc6cf5c97fb865db85cf191b45f05bca8d41d15af481979c322e923eb",
"md5": "d0e5494a901e7e2f43a6f1fdcd1de59c",
"sha256": "517af9ada55bcc704d57c8fe847c6a952c798149889c7710226867cd15dd22a8"
},
"downloads": -1,
"filename": "speakeasy2-0.1.3-cp313-cp313-macosx_14_0_arm64.whl",
"has_sig": false,
"md5_digest": "d0e5494a901e7e2f43a6f1fdcd1de59c",
"packagetype": "bdist_wheel",
"python_version": "cp313",
"requires_python": ">=3.10",
"size": 301586,
"upload_time": "2024-10-29T03:38:31",
"upload_time_iso_8601": "2024-10-29T03:38:31.749015Z",
"url": "https://files.pythonhosted.org/packages/3a/0f/659fc6cf5c97fb865db85cf191b45f05bca8d41d15af481979c322e923eb/speakeasy2-0.1.3-cp313-cp313-macosx_14_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "77daf34ff0a76af464402c13f839aef35a0cd94e464148210016e532287c21cd",
"md5": "c495f89e5d19e250d83cd4d6a38d79c3",
"sha256": "948d3b864fd19e0f3b889cd40f0346d67d95f6fa9c62f34e4469ab3dbae7ea8e"
},
"downloads": -1,
"filename": "speakeasy2-0.1.3-cp313-cp313-manylinux_2_35_x86_64.whl",
"has_sig": false,
"md5_digest": "c495f89e5d19e250d83cd4d6a38d79c3",
"packagetype": "bdist_wheel",
"python_version": "cp313",
"requires_python": ">=3.10",
"size": 336474,
"upload_time": "2024-10-29T03:38:32",
"upload_time_iso_8601": "2024-10-29T03:38:32.992165Z",
"url": "https://files.pythonhosted.org/packages/77/da/f34ff0a76af464402c13f839aef35a0cd94e464148210016e532287c21cd/speakeasy2-0.1.3-cp313-cp313-manylinux_2_35_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fc84df5281482af575f368d9e279279f2929b9c9b000c4419d1d52e1d925c020",
"md5": "eaba53befb7ab5eeb4cb8c460a57d791",
"sha256": "2c4cf24e8d3ec2fac465fab0eaf25247789e1ca0272da23098e57268681a46d1"
},
"downloads": -1,
"filename": "speakeasy2-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "eaba53befb7ab5eeb4cb8c460a57d791",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 2686728,
"upload_time": "2024-10-29T03:38:33",
"upload_time_iso_8601": "2024-10-29T03:38:33.986945Z",
"url": "https://files.pythonhosted.org/packages/fc/84/df5281482af575f368d9e279279f2929b9c9b000c4419d1d52e1d925c020/speakeasy2-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-29 03:38:33",
"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
