{"id":13688792,"url":"https://github.com/aplbrain/grandiso-networkx","last_synced_at":"2025-10-31T07:32:08.442Z","repository":{"id":45320829,"uuid":"286553966","full_name":"aplbrain/grandiso-networkx","owner":"aplbrain","description":"Performant, pure-Python subgraph isomorphism and monomorphism search (aka \"motif search\")","archived":false,"fork":false,"pushed_at":"2024-08-16T11:20:41.000Z","size":179,"stargazers_count":58,"open_issues_count":7,"forks_count":10,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-02-09T14:13:14.102Z","etag":null,"topics":["algorithm","aplbrain","bossdb","connectomics","dotmotif","grand-graphs","grand-iso","graphs","network","network-analysis","network-biology","subgraph-isomorphism","ullman","vf2"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aplbrain.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2020-08-10T18:46:38.000Z","updated_at":"2024-12-30T13:01:39.000Z","dependencies_parsed_at":"2023-02-08T19:00:31.247Z","dependency_job_id":"9575d0a3-8722-46a3-9b1e-1b9caf03fbca","html_url":"https://github.com/aplbrain/grandiso-networkx","commit_stats":{"total_commits":66,"total_committers":5,"mean_commits":13.2,"dds":0.4545454545454546,"last_synced_commit":"f9be813d2c9a127ac717d83e09d1eb13ab8469f8"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aplbrain%2Fgrandiso-networkx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aplbrain%2Fgrandiso-networkx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aplbrain%2Fgrandiso-networkx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aplbrain%2Fgrandiso-networkx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aplbrain","download_url":"https://codeload.github.com/aplbrain/grandiso-networkx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239147046,"owners_count":19589529,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algorithm","aplbrain","bossdb","connectomics","dotmotif","grand-graphs","grand-iso","graphs","network","network-analysis","network-biology","subgraph-isomorphism","ullman","vf2"],"created_at":"2024-08-02T15:01:22.820Z","updated_at":"2025-10-31T07:32:08.052Z","avatar_url":"https://github.com/aplbrain.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\u003ch1 align=center\u003eGrand Isomorphisms\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://codecov.io/gh/aplbrain/grandiso-networkx/\"\u003e\u003cimg alt=\"Codecov\" src=\"https://img.shields.io/codecov/c/github/aplbrain/grandiso-networkx?style=for-the-badge\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/aplbrain/grandiso-networkx/actions\"\u003e\u003cimg alt=\"GitHub Workflow Status\" src=\"https://img.shields.io/github/actions/workflow/status/aplbrain/grandiso-networkx/python-package.yml?branch=master\u0026style=for-the-badge\"\u003e\u003c/a\u003e\u003ca href=\"https://bossdb.org/tools/DotMotif\"\u003e\u003cimg src=\"https://img.shields.io/badge/Pretty Dope-👌-00ddcc.svg?style=for-the-badge\" /\u003e\u003c/a\u003e\n\u003cimg alt=\"GitHub\" src=\"https://img.shields.io/github/license/aplbrain/grandiso-networkx?style=for-the-badge\"\u003e\n\u003ca href=\"https://pypi.org/project/grandiso/\"\u003e\u003cimg alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/grandiso?style=for-the-badge\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nSubgraph isomorphism is a resource-heavy (but branch-parallelizable) algorithm that is hugely impactful for large graph analysis. SotA algorithms for this (Ullmann, VF2, BB-Graph) are heavily RAM-bound, but this is due to a large number of small processes each of which hold a small portion of a traversal tree in memory.\n\n_Grand-Iso_ is a subgraph isomorphism algorithm that exchanges this resource-limitation for a parallelizable partial-match queue structure.\n\nIt performs favorably compared to other pure-python (and even some non-pure-python!) implementations:\n\n\u003cimg width=\"485\" alt=\"image\" src=\"https://user-images.githubusercontent.com/693511/96184546-a35e0380-0f06-11eb-8475-1921e8f94256.png\"\u003e\n\nSee the [wiki](https://github.com/aplbrain/grandiso-networkx/wiki) for more documentation.\n\n## Example Usage\n\n```python\nfrom grandiso import find_motifs\nimport networkx as nx\n\nhost = nx.fast_gnp_random_graph(10, 0.5)\n\nmotif = nx.Graph()\nmotif.add_edge(\"A\", \"B\")\nmotif.add_edge(\"B\", \"C\")\nmotif.add_edge(\"C\", \"D\")\nmotif.add_edge(\"D\", \"A\")\n\nlen(find_motifs(motif, host))\n```\n\nDirected graph support:\n\n```python\nfrom grandiso import find_motifs\nimport networkx as nx\n\nhost = nx.fast_gnp_random_graph(10, 0.5, directed=True)\n\nmotif = nx.DiGraph()\nmotif.add_edge(\"A\", \"B\")\nmotif.add_edge(\"B\", \"C\")\nmotif.add_edge(\"C\", \"D\")\nmotif.add_edge(\"D\", \"A\")\n\nlen(find_motifs(motif, host))\n```\n\n## Counts-only\n\nFor very large graphs, you may use a good chunk of RAM not only on the queue of hypotheses, but also on the list of results. If all you care about is the NUMBER of results, you should pass `count_only=True` to the `find_motifs` function. This will dramatically reduce your RAM overhead on higher-count queries.\n\nThere are many other arguments that you can pass to the motif search algorithm. For a full list, see [here](https://github.com/aplbrain/grandiso-networkx/wiki/Algorithm-Arguments).\n\n\n## Hacking on this repo\n\n### Running Tests\n\n```shell\ncoverage run --source=grandiso -m pytest\n```\n\n## Citing\n\nIf this tool is helpful to your research, please consider citing it with:\n\n```bibtex\n# https://doi.org/10.1038/s41598-021-91025-5\n@article{Matelsky_Motifs_2021, \n    title={{DotMotif: an open-source tool for connectome subgraph isomorphism search and graph queries}},\n    volume={11}, \n    ISSN={2045-2322}, \n    url={http://dx.doi.org/10.1038/s41598-021-91025-5}, \n    DOI={10.1038/s41598-021-91025-5}, \n    number={1}, \n    journal={Scientific Reports}, \n    publisher={Springer Science and Business Media LLC}, \n    author={Matelsky, Jordan K. and Reilly, Elizabeth P. and Johnson, Erik C. and Stiso, Jennifer and Bassett, Danielle S. and Wester, Brock A. and Gray-Roncal, William},\n    year={2021}, \n    month={Jun}\n}\n```\n\n---\n\n\u003cp align=center\u003e\u003cb\u003eMade with 💙 at \u003ca href=\"https://jhuapl.edu\"\u003e\u003cimg alt=\"JHU APL\" src=\"https://user-images.githubusercontent.com/693511/116814564-9b268800-ab27-11eb-98bb-dfddb2e405a1.png\" height=\"23px\" /\u003e\u003c/a\u003e\u003c/b\u003e\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faplbrain%2Fgrandiso-networkx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faplbrain%2Fgrandiso-networkx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faplbrain%2Fgrandiso-networkx/lists"}