# Dynamic Community Detection: LAGO
**This library is a python implementation of the LAGO method for dynamic community detection on temporal networks.**
### Getting started using pip
```
pip install dcd-lago
```
## Link Streams and Dynamic Communities
**Link stream** (or stream graph) model enables temporal network to have **perfect temporal precision** of temporal links (also called edges or interactions).
Community detection is an essential task in static network analysis. It consists in grouping nodes so there is more edges within groups than between them.
Adapating this task to temporal networks means that groups may evolve over time and yet be consistent over time.
We call this task **Dynamic Community Detection**.
<div style="text-align: center;">
<img src="img/dcd_example.png" alt="Link Stream example with two dynamic communities" display:block; margin:auto; width="500" />
Figure 1: Link stream made up of 5 nodes (a, ...,e) with time interactions over time represented with vertical dashed lines. Two dynamic communities are displayed in blue and green.
</div>
**LAGO** is a method to detect dynamic communities on link streams which is inspired from most used community detection methods on static graphs. It is based on the greedy optimization of the Longitudinal Modularity, an adaptation of the Modularity quality function for communities on static networks.
## Usage
```python
from lago import LinkStream, lago_communities
```
```python
## Declare time links according to the following format:
# <source node>, <target node>, <time instant>
## Values must be integers
time_links = [
[2, 3, 0],
[0, 1, 2],
[2, 3, 3],
[3, 4, 5],
[2, 3, 6],
[2, 4, 7],
[0, 1, 8],
[1, 2, 9],
[3, 4, 9],
[0, 2, 10],
[1, 2, 11],
[3, 4, 13],
[1, 2, 14],
[2, 4, 16],
[0, 1, 17],
[0, 1, 18],
[2, 3, 18],
[3, 4, 19],
]
```
```python
## Initiate empty temporal network (as a link stream)
my_linkstream = LinkStream()
## Add time links to the link stream
my_linkstream.add_links(time_links)
# NOTE time links can also be imported from txt files with the read_txt() method
## Display linkstream informations
print(f"The link stream consists of {my_linkstream.nb_edges} temporal edges (or time links) accross {my_linkstream.nb_nodes} nodes and {my_linkstream.network_duration} time steps, of which only {my_linkstream.nb_timesteps} contain activity.")
```
```python
## Compute dynamic communities
dynamic_communities = lago_communities(
my_linkstream,
nb_iter=3, # run LAGO 3 times and return best result
)
# Each dynamic community is represented by a list of (<node>, <time instant>)
print(f"{len(dynamic_communities)} dynamic communities have been found")
```
#### Plot Dynamic Communities
```python
from lago import plot_dynamic_communities
fig = plot_dynamic_communities(
linkstream=my_linkstream,
communities=dynamic_communities,
)
fig.show()
```
#### Compute Longitudinal Modularity Score
```python
from lago import longitudinal_modularity
## Compute Longitudinal Modularity score
## (the higher the better / maximum is 1)
long_mod_score = longitudinal_modularity(
my_linkstream,
dynamic_communities,
)
print(f"Dynamic communities detected on the linkstream have a Longitudinal Modularity score of {long_mod_score} ")
```
## Advanced Parameters
LAGO is a greedy method for optimizing Longitudinal Modularity, which is a quality function for dynamic communities on temporal networks. Both have many options which affects both speed and communities shapes.
### Longitudinal Modularity
`lex` (Longitudinal Expectation):
Can be either Joint-Membership (JM) or Mean-Membership (MM). From a theoretical aspect, JM expects dynamic communities to have a very consistent duration of existence, whereas MM allows greater freedom in the temporal evolution of communities. Authors lack perspective on the impact of the choice on real data. Defaults to "MM".
`omega`: Time resolution Parameter indicating the required level of community continuity over time. Higher values lead to more smoothness in communities changes. Defaults to 2.
### LAGO
`refinement`: In greedy search optimization, a refinement strategy can improve results but increases computation time. Defaults to STEM.
| Refinement | Improvement | Time of execution|
| ----------- | ----------- | --------- |
| None | - | - |
| Single Time Node Movements (STNM) | + | +|
| Single Time Edge Movements (STEM) | ++ | ++ |
`refinement_in`: Whether to apply refinement strategy within the main optimization loop or not. If activated, results may be improved but requires more computation time. Defaults to True.
`fast_exploration`: lighter exploration loop. If activated, it significantly reduces the time of execution but may result in poorer results. Defaults to True.
## Feedback
LAGO method and the python library are constantly improving. If you have any questions, suggestions or issues, please add them to [GitHub issues](https://github.com/fondationsahar/dynamic_community_detection/issues).
## References
### LAGO Method
Preprint comming soon.
### Longitudinal Modularity
[*Longitudinal Modularity, a Modularity for Link Streams*](https://rdcu.be/eC5fA)
```
@article{Brabant2025,
title = {Longitudinal modularity, a modularity for link streams},
volume = {14},
ISSN = {2193-1127},
url = {http://dx.doi.org/10.1140/epjds/s13688-025-00529-x},
DOI = {10.1140/epjds/s13688-025-00529-x},
number = {1},
journal = {EPJ Data Science},
publisher = {Springer Science and Business Media LLC},
author = {Brabant, Victor and Asgari, Yasaman and Borgnat, Pierre and Bonifati, Angela and Cazabet, Rémy},
year = {2025},
month = feb
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "dcd-lago",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "lago, networks, temporal networks, modularity, longitudinal modularity, community detection, dynamic community detection",
"author": null,
"author_email": "Victor Brabant <victorbrabant@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/13/a0/a1e2371c3091ca4a328b5e4275637c336a12e585c45d70db2a630d64a6eb/dcd_lago-1.0.1.tar.gz",
"platform": null,
"description": "# Dynamic Community Detection: LAGO\n\n**This library is a python implementation of the LAGO method for dynamic community detection on temporal networks.**\n\n### Getting started using pip\n\n```\npip install dcd-lago\n```\n\n\n## Link Streams and Dynamic Communities\n\n**Link stream** (or stream graph) model enables temporal network to have **perfect temporal precision** of temporal links (also called edges or interactions).\n\nCommunity detection is an essential task in static network analysis. It consists in grouping nodes so there is more edges within groups than between them.\nAdapating this task to temporal networks means that groups may evolve over time and yet be consistent over time. \nWe call this task **Dynamic Community Detection**.\n\n\n<div style=\"text-align: center;\">\n<img src=\"img/dcd_example.png\" alt=\"Link Stream example with two dynamic communities\" display:block; margin:auto; width=\"500\" /> \n\nFigure 1: Link stream made up of 5 nodes (a, ...,e) with time interactions over time represented with vertical dashed lines. Two dynamic communities are displayed in blue and green.\n\n</div>\n\n**LAGO** is a method to detect dynamic communities on link streams which is inspired from most used community detection methods on static graphs. It is based on the greedy optimization of the Longitudinal Modularity, an adaptation of the Modularity quality function for communities on static networks.\n\n## Usage \n\n\n```python\nfrom lago import LinkStream, lago_communities\n```\n\n```python\n## Declare time links according to the following format:\n# <source node>, <target node>, <time instant>\n## Values must be integers\n\ntime_links = [\n [2, 3, 0],\n [0, 1, 2],\n [2, 3, 3],\n [3, 4, 5],\n [2, 3, 6],\n [2, 4, 7],\n [0, 1, 8],\n [1, 2, 9],\n [3, 4, 9],\n [0, 2, 10],\n [1, 2, 11],\n [3, 4, 13],\n [1, 2, 14],\n [2, 4, 16],\n [0, 1, 17],\n [0, 1, 18],\n [2, 3, 18],\n [3, 4, 19],\n]\n```\n\n```python\n## Initiate empty temporal network (as a link stream)\nmy_linkstream = LinkStream()\n\n## Add time links to the link stream\nmy_linkstream.add_links(time_links)\n\n# NOTE time links can also be imported from txt files with the read_txt() method\n\n## Display linkstream informations\nprint(f\"The link stream consists of {my_linkstream.nb_edges} temporal edges (or time links) accross {my_linkstream.nb_nodes} nodes and {my_linkstream.network_duration} time steps, of which only {my_linkstream.nb_timesteps} contain activity.\")\n```\n\n```python\n## Compute dynamic communities\ndynamic_communities = lago_communities(\n my_linkstream,\n nb_iter=3, # run LAGO 3 times and return best result\n )\n\n# Each dynamic community is represented by a list of (<node>, <time instant>)\n\nprint(f\"{len(dynamic_communities)} dynamic communities have been found\")\n```\n\n#### Plot Dynamic Communities\n```python\nfrom lago import plot_dynamic_communities\n\nfig = plot_dynamic_communities(\n linkstream=my_linkstream,\n communities=dynamic_communities,\n )\nfig.show()\n```\n\n#### Compute Longitudinal Modularity Score\n```python\nfrom lago import longitudinal_modularity\n\n## Compute Longitudinal Modularity score\n## (the higher the better / maximum is 1)\nlong_mod_score = longitudinal_modularity(\n my_linkstream, \n dynamic_communities,\n )\n\nprint(f\"Dynamic communities detected on the linkstream have a Longitudinal Modularity score of {long_mod_score} \")\n```\n\n## Advanced Parameters\n\nLAGO is a greedy method for optimizing Longitudinal Modularity, which is a quality function for dynamic communities on temporal networks. Both have many options which affects both speed and communities shapes.\n\n### Longitudinal Modularity\n\n `lex` (Longitudinal Expectation):\nCan be either Joint-Membership (JM) or Mean-Membership (MM). From a theoretical aspect, JM expects dynamic communities to have a very consistent duration of existence, whereas MM allows greater freedom in the temporal evolution of communities. Authors lack perspective on the impact of the choice on real data. Defaults to \"MM\".\n\n `omega`: Time resolution Parameter indicating the required level of community continuity over time. Higher values lead to more smoothness in communities changes. Defaults to 2.\n\n### LAGO\n\n`refinement`: In greedy search optimization, a refinement strategy can improve results but increases computation time. Defaults to STEM.\n\n| Refinement | Improvement | Time of execution| \n| ----------- | ----------- | --------- |\n| None | - | - |\n| Single Time Node Movements (STNM) | + | +|\n| Single Time Edge Movements (STEM) | ++ | ++ |\n\n`refinement_in`: Whether to apply refinement strategy within the main optimization loop or not. If activated, results may be improved but requires more computation time. Defaults to True.\n\n`fast_exploration`: lighter exploration loop. If activated, it significantly reduces the time of execution but may result in poorer results. Defaults to True.\n\n\n\n## Feedback\n\nLAGO method and the python library are constantly improving. If you have any questions, suggestions or issues, please add them to [GitHub issues](https://github.com/fondationsahar/dynamic_community_detection/issues).\n\n## References\n\n### LAGO Method\nPreprint comming soon.\n\n\n### Longitudinal Modularity\n\n[*Longitudinal Modularity, a Modularity for Link Streams*](https://rdcu.be/eC5fA)\n```\n@article{Brabant2025,\n title = {Longitudinal modularity, a modularity for link streams},\n volume = {14},\n ISSN = {2193-1127},\n url = {http://dx.doi.org/10.1140/epjds/s13688-025-00529-x},\n DOI = {10.1140/epjds/s13688-025-00529-x},\n number = {1},\n journal = {EPJ Data Science},\n publisher = {Springer Science and Business Media LLC},\n author = {Brabant, Victor and Asgari, Yasaman and Borgnat, Pierre and Bonifati, Angela and Cazabet, R\u00e9my},\n year = {2025},\n month = feb \n}\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python implementation of the LAGO method for dynamic community detection in temporal networks. Derived functions such as the Longitudinal Modularity are also provided.",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/fondationsahar/dynamic_community_detection",
"Issues": "https://github.com/fondationsahar/dynamic_community_detection/issues"
},
"split_keywords": [
"lago",
" networks",
" temporal networks",
" modularity",
" longitudinal modularity",
" community detection",
" dynamic community detection"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2bc2f3ba95d48450e3ece2b19c3797946092af3b3714e7cc8c05485d7c0f8cc9",
"md5": "bd89538d9812395b0090b4245f6475f6",
"sha256": "5c443de82104709dcf31cb3ea74a25c58ae0aa11a80ec49db90d943e9e4024b0"
},
"downloads": -1,
"filename": "dcd_lago-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bd89538d9812395b0090b4245f6475f6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 15283,
"upload_time": "2025-09-01T09:34:13",
"upload_time_iso_8601": "2025-09-01T09:34:13.296786Z",
"url": "https://files.pythonhosted.org/packages/2b/c2/f3ba95d48450e3ece2b19c3797946092af3b3714e7cc8c05485d7c0f8cc9/dcd_lago-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "13a0a1e2371c3091ca4a328b5e4275637c336a12e585c45d70db2a630d64a6eb",
"md5": "af6567b43b4f75967b652c562cd9abb4",
"sha256": "4c92400da3c7730dd83897f4b173898e94af68fba4ef223a91794b8db825d29a"
},
"downloads": -1,
"filename": "dcd_lago-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "af6567b43b4f75967b652c562cd9abb4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 13817,
"upload_time": "2025-09-01T09:34:14",
"upload_time_iso_8601": "2025-09-01T09:34:14.460753Z",
"url": "https://files.pythonhosted.org/packages/13/a0/a1e2371c3091ca4a328b5e4275637c336a12e585c45d70db2a630d64a6eb/dcd_lago-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-01 09:34:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fondationsahar",
"github_project": "dynamic_community_detection",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "numpy",
"specs": [
[
"==",
"2.4.0"
]
]
},
{
"name": "matplotlib",
"specs": [
[
"==",
"3.10.0"
]
]
}
],
"lcname": "dcd-lago"
}
JSON
