Skip to content

Commit

Permalink
update readme with pip package badge
Browse files Browse the repository at this point in the history
  • Loading branch information
@j6k4m8
j6k4m8 committed Jan 11, 2021
1 parent 1a3c7db commit 28e2f97
Showing 1 changed file with 14 additions and 19 deletions.
33 changes: 14 additions & 19 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
<a href="https://github.com/aplbrain/grandiso-networkx/actions"><img alt="GitHub Workflow Status" src="https://img.shields.io/github/workflow/status/aplbrain/grandiso-networkx/Python%20package?style=for-the-badge"></a>
<a href="https://bossdb.org/tools/DotMotif"><img src="https://img.shields.io/badge/Pretty Dope-👌-00ddcc.svg?style=for-the-badge" /></a>
<img alt="GitHub" src="https://img.shields.io/github/license/aplbrain/grandiso-networkx?style=for-the-badge">
<a href="https://pypi.org/project/grandiso/"><img alt="PyPI" src="https://img.shields.io/pypi/v/grandiso?style=for-the-badge"></a>
</p>

Subgraph 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.
Expand All @@ -15,7 +16,6 @@ It performs favorably compared to other pure-python (and even some non-pure-pyth

<img width="485" alt="image" src="https://user-images.githubusercontent.com/693511/96184546-a35e0380-0f06-11eb-8475-1921e8f94256.png">


## Example Usage

```python
Expand Down Expand Up @@ -54,20 +54,18 @@ len(find_motifs(motif, host))

For 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.


## All Arguments to `find_motifs`

| Argument | Type | Default | Description |
|----------|------|---------|-------------|
| `motif` | `nx.Graph` | | The motif to search for. Either a `nx.Graph` or `nx.DiGraph`. You can also pass something `networkx.Graph`-flavored, like a [grand.Graph](https://github.com/aplbrain/grand). |
| `host` | `nx.Graph` | | The "haystack" graph to search within. Either a `nx.Graph` or `nx.DiGraph`. You can also pass something `networkx.Graph`-flavored, like a [grand.Graph](https://github.com/aplbrain/grand). |
| `interestingness` | `dict` | `None` | A lookup dictionary that assigns a floating number between 0 and 1 to each node in the `motif` graph. Nodes with values closest to 1 will be preferred when the candidate-mapper advances the exploration front. If this doesn't make sense to you, you can ignore this argument entirely. If none is provided, this will default to a uniform interestness metric where all nodes are considered equally. |
| `count_only` | `bool` | `False` | Whether to return only a count of motifs, rather than a list of mappings. If you set this to `True`, you will get back an integer result, not a list of dicts. |
| `directed` | `bool` | `None` | Whether to enforce a directed/undirected search. True means enforce directivity; False means enforce undirected search. The default (None) will guess based upon your motif and host. |
| `profile` | `bool` | `False` | Whether to slow down execution but give you a better idea of where your RAM usage is going. This is better ignored unless you're debugging something particularly nuanced. |
| `isomorphisms_only` | `bool` | `False` | Whether to search only for isomorphisms. In other words, whether to search for edges that exist in the node-induced subgraph. |
| `hints` | `List[Dict[Hashable, Hashable]]` | A list of valid candidate mappings to use as the starting seeds for new maps. See _Using Hints_, below. |

| Argument | Type | Default | Description |
| ------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `motif` | `nx.Graph` | | The motif to search for. Either a `nx.Graph` or `nx.DiGraph`. You can also pass something `networkx.Graph`-flavored, like a [grand.Graph](https://github.com/aplbrain/grand). |
| `host` | `nx.Graph` | | The "haystack" graph to search within. Either a `nx.Graph` or `nx.DiGraph`. You can also pass something `networkx.Graph`-flavored, like a [grand.Graph](https://github.com/aplbrain/grand). |
| `interestingness` | `dict` | `None` | A lookup dictionary that assigns a floating number between 0 and 1 to each node in the `motif` graph. Nodes with values closest to 1 will be preferred when the candidate-mapper advances the exploration front. If this doesn't make sense to you, you can ignore this argument entirely. If none is provided, this will default to a uniform interestness metric where all nodes are considered equally. |
| `count_only` | `bool` | `False` | Whether to return only a count of motifs, rather than a list of mappings. If you set this to `True`, you will get back an integer result, not a list of dicts. |
| `directed` | `bool` | `None` | Whether to enforce a directed/undirected search. True means enforce directivity; False means enforce undirected search. The default (None) will guess based upon your motif and host. |
| `profile` | `bool` | `False` | Whether to slow down execution but give you a better idea of where your RAM usage is going. This is better ignored unless you're debugging something particularly nuanced. |
| `isomorphisms_only` | `bool` | `False` | Whether to search only for isomorphisms. In other words, whether to search for edges that exist in the node-induced subgraph. |
| `hints` | `List[Dict[Hashable, Hashable]]` | A list of valid candidate mappings to use as the starting seeds for new maps. See _Using Hints_, below. |

## Using Hints

Expand All @@ -93,13 +91,11 @@ motif = nx.DiGraph()
nx.add_path(motif, ["a", "b", "c", "a"])

find_motifs(
motif, host,
motif, host,
hints=[{"A": "a"}, {"A", "a"}]
)
```



## Pseudocode for "Grand-Iso" algorithm

```
Expand Down Expand Up @@ -132,16 +128,15 @@ find_motifs(
coverage run --source=grandiso -m pytest
```


## Citing

If this tool is helpful to your research, please consider citing it with:

```
```bibtex
# https://www.biorxiv.org/content/10.1101/2020.06.08.140533v1
@article{matelsky_2020_dotmotif,
doi = {10.1101/2020.06.08.140533},
url = {https://www.biorxiv.org/content/10.1101/2020.06.08.140533v1},
url = {https://www.biorxiv.org/content/10.1101/2020.06.08.140533v2},
year = 2020,
month = {june},
publisher = {BiorXiv},
Expand Down

0 comments on commit 28e2f97

Please sign in to comment.