# Topological Graph Features
Topological feature calculators infrastructure.
## Calculating Features
This package helps one to calculate features for a given graph. All features are implemented in python codes,
and some features have also an accelerated version written in C++. Among the accelerated features, one can find
a code for calculating 3- and 4-motifs using VDMC, a distributed algorithm to calculate 3- and 4-motifs in a
GPU-parallelized way.
## Versions
- Last version: 0.1.55 (most recommended)
## What Features Can Be Calculated Here?
The set of all vertex features implemented in graph-measures is the following:
| Feature | Feature's name in code | Is available in gpu? | Output size for directed graph | Output size for undirected graph |
|----------------------------------------|----------------------------------------|----------------------|--------------------------------|----------------------------------|
| Average neighbor degree | average_neighbor_degree | NO | N x 1 | N x 1 |
| Degree^ | degree | NO | N x 2 | N x 1 |
| In degree | in_degree | NO | N x 1 | - - - - - - - |
| Out degree | out_degree | NO | N x 1 | - - - - - - - |
| Louvain^^ | louvain | NO | - - - - - - - | N x 1 |
| Hierarchy energy | hierarchy_energy | NO | | |
| Motifs3 | motif3 | YES | N x 13 | N x 2 |
| Motifs4 | motif4 | YES | N x 199 | N x 6 |
| K core | k_core | YES | N x 1 | N x 1 |
| Attraction basin | attractor_basin | YES | N x 1 | - - - - - - - |
| Page Rank | page_rank | YES | N x 1 | N x 1 |
| Fiedler vector | fiedler_vector | NO | - - - - - - - | N x 1 |
| Closeness centrality | closeness_centrality | NO | N x 1 | N x 1 |
| Eccentricity | eccentricity | NO | N x 1 | N x 1 |
| Load centrality | load_centrality | NO | N x 1 | N x 1 |
| BFS moments | bfs_moments | NO | N x 2 | N x 2 |
| Flow | flow | YES | N x 1 | - - - - - - - |
| Betweenness centrality | betweenness_centrality | NO | N x 1 | N x 1 |
| Communicability betweenness centrality | communicability_betweenness_centrality | NO | - - - - - - - | N x ? |
| Eigenvector centrality | eigenvector_centrality | NO | N x 1 | N x 1 |
| Clustering coefficient | clustering_coefficient | NO | N x 1 | N x 1 |
| Square clustering coefficient | square_clustering_coefficient | NO | N x 1 | N x 1 |
| Generalized degree | generalized_degree | NO | - - - - - - - | N x 16 |
| All pairs shortest path length | all_pairs_shortest_path_length | NO | N x N | N x N |
^ Degree - In the undirected case return the sum of the in degree and the out degree. <br>
^^Louvain - Implement Louvain community detection method, then associate to each vertex the number of vertices in its community.
Aside from those, there are some other [edge features](https://github.com/AmitKabya/graph-measures/tree/master/src/graphMeasures/features_algorithms/edges).
Some more information regarding the features can be found in the files of [features_meta](https://github.com/AmitKabya/graph-measures/blob/master/src/graphMeasures/features_meta).
## Dependencies
```
setuptools
networkx==2.6.3
pandas
numpy
matplotlib
scipy
scikit-learn
python-louvain
bitstring
future
torch
```
## How To Use The Accelerated Version (CPU/GPU)?
Both versions currently are not supported with the pip installation. \
To use the accelerated version, one must use <b>*Linux* operation system</b> and <b>*Anaconda* distribution</b>, with the follow the next steps:
1. Go to the [package's GitHub website](https://github.com/AmitKabya/graph-measures) and manually download:
- The directory `graphMeasures`.
- The python file `runMakefileACC.py`.
*You might need to download a zip of the repository and extract the necessary files.*
2. Place both the file and the directory inside your project, and run `runMakefileACC.py`.
3. Move to the *boost environment*: `conda activate boost` (The environment was created in step 2).
4. Use the package as explained in the section `How To Use?`
## Installation Through pip
The full functionality of the package is currently available on a Linux machine, with a Conda environment.
- Linux + Conda<br>1. Go to base environment<br>2. If pip is not installed on your env, install it. Then, use pip to install the package
- Otherwise, pip must be installed.
```commandline
pip install graph-measures
```
**Note:** On Linux+Conda the installation might take longer (about 5-10 minuets) due to the compilation of the c++ files.
## How To Use?
Even though one has installed the package as `graph-measures`, The package should be imported from the code as `graphMesaures`. Hence, use:
```python
from graphMeasures import FeatureCalculator
```
## Calculating Features
There are two main methods to calculate features:
1. Using [FeatureCalculator](https://github.com/louzounlab/graph-measures/blob/master/graphMeasures/features_for_any_graph.py) (**recommended**): \
A class for calculating any requested features on a given graph. \
The graph is input to this class as a text-like file of edges, with a comma delimiter, or a networkx _Graph_ object.
For example, the graph [example_graph.txt](https://github.com/louzounlab/graph-measures/blob/master/graphMeasures/measure_tests/example_graph.txt) is the following file:
```
0,1
0,2
1,3
3,2
```
Now, an implementation of feature calculations on this graph looks like this:
```python
import os
from graphMeasures import FeatureCalculator
# set of features to be calculated
feats = ["motif3", "louvain"]
# path to the graph's edgelist or nx.Graph object
graph = os.path.join("measure_tests", "example_graph.txt")
# The path in which one would like to save the pickled features calculated in the process.
dir_path = ""
# More options are shown here. For information about them, refer to the file.
ftr_calc = FeatureCalculator(path, feats, dir_path=dir_path, acc=True, directed=False,
gpu=True, device=0, verbose=True)
# Calculates the features. If one do not want the features to be saved,
# one should set the parameter 'should_dump' to False (set to True by default).
# If the features was already saved, you can set force_build to be True.
ftr_calc.calculate_features(force_build=True)
features = ftr_calc.get_features() # return pandas Dataframe with the features
```
<!-- More information can be found in [features_for_any_graph.py](https://github.com/AmitKabya/graph-measures/blob/master/src/graphMeasures/features_for_any_graph.py). \-->
**Note:** If one set `acc=True` without using a Linux+Conda machine, an exception will be thrown.\
**Note:** If one set `gpu=True` without using a Linux+Conda machine that has cuda available on it, an exception will be thrown.
<br />
<br />
2. Using graphMeasure <a href="https://github.com/louzounlab/graph-measures/blob/master/OTHERS.md">without FeatureCalculator</a> (**less recommended**).
[//]: # (2. Using graphMeasure [without FeatureCalculator](https://github.com/louzounlab/graph-measures/blob/master/OTHERS.md) (**less recommended**).)
<br />
## Edges motifs:
For now, you can calculate only motifs for edges. Unfortunately, you will have to do it separately from the nodes features.
There are two options for motif calculation - python version, and accelerated version (in CPP).
The python version is always available, but the accelerated version available only on linux machine
(the makefile targets linux, but the code should work for any os). Anyway, if you have a suitable machine,
the accelerated version is more recommended.
To run the accelerated version you should do:
1. Copy the graphMeasures directory to your project (available in this branch).
2. Open terminal in `graphMeasures/edges_features/acc_features/acc/`
3. Run the command `make`. If the makefile ends normally, a so file should be in a dir named bin.
Execution example:
```python
import networkx as nx
from graphMeasures.edges_features.feature_calculator import FeatureCalculator
path = "./data/graph.txt"
gnx = nx.read_edgelist(path, delimiter=",", create_using=nx.DiGraph)
# acc signs if we will use the accelerated version.
calculator = FeatureCalculator(["motif3", "motif4"], gnx, acc=True)
calculator.build()
# The result will be a pandas Dataframe named calculator.df.
print(calculator.df)
```
## Contact us
This package was written by [Yolo lab's](https://yolo.math.biu.ac.il/) team from Bar-Ilan University. \
For questions, comments or suggestions you can contact louzouy@math.biu.ac.il.
[//]: # (### Ouptput)
[//]: # (graphMeasures uses ```networkx```'s ```networkx.convert_node_labels_to_integers``` function, and then calculates the features. )
[//]: # (That's why the output matrix is ordered by the new nodes labels (from 0 to n-1) and not by the original labels.)
[//]: # ()
[//]: # (graphMeasures sometimes return the output columns not in the order they were inserted. The )
Raw data
{
"_id": null,
"home_page": "https://github.com/louzounlab/graph-measures",
"name": "graph-measures",
"maintainer": "Ziv Naim",
"docs_url": null,
"requires_python": ">=3.6.8",
"maintainer_email": "zivnaim3@gmail.com",
"keywords": "gpu,graph,topological-features-calculator",
"author": "Itay Levinas",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/6b/24/fa07389553f22b98b17bfc9a2edd4017f20a9373d7bfa64d3fbba8c9d8c7/graph-measures-0.1.57.tar.gz",
"platform": null,
"description": "# Topological Graph Features\r\n\r\nTopological feature calculators infrastructure.\r\n\r\n## Calculating Features\r\nThis package helps one to calculate features for a given graph. All features are implemented in python codes, \r\nand some features have also an accelerated version written in C++. Among the accelerated features, one can find \r\na code for calculating 3- and 4-motifs using VDMC, a distributed algorithm to calculate 3- and 4-motifs in a \r\nGPU-parallelized way.\r\n\r\n## Versions\r\n- Last version: 0.1.55 (most recommended)\r\n\r\n## What Features Can Be Calculated Here?\r\nThe set of all vertex features implemented in graph-measures is the following:\r\n\r\n| Feature | Feature's name in code | Is available in gpu? | Output size for directed graph | Output size for undirected graph |\r\n|----------------------------------------|----------------------------------------|----------------------|--------------------------------|----------------------------------|\r\n| Average neighbor degree | average_neighbor_degree | NO | N x 1 | N x 1 |\r\n| Degree^ | degree | NO | N x 2 | N x 1 |\r\n| In degree | in_degree | NO | N x 1 | - - - - - - - |\r\n| Out degree | out_degree | NO | N x 1 | - - - - - - - |\r\n| Louvain^^ | louvain | NO | - - - - - - - | N x 1 |\r\n| Hierarchy energy | hierarchy_energy | NO | | |\r\n| Motifs3 | motif3 | YES | N x 13 | N x 2 |\r\n| Motifs4 | motif4 | YES | N x 199 | N x 6 |\r\n| K core | k_core | YES | N x 1 | N x 1 |\r\n| Attraction basin | attractor_basin | YES | N x 1 | - - - - - - - |\r\n| Page Rank | page_rank | YES | N x 1 | N x 1 |\r\n| Fiedler vector | fiedler_vector | NO | - - - - - - - | N x 1 |\r\n| Closeness centrality | closeness_centrality | NO | N x 1 | N x 1 |\r\n| Eccentricity | eccentricity | NO | N x 1 | N x 1 |\r\n| Load centrality | load_centrality | NO | N x 1 | N x 1 |\r\n| BFS moments | bfs_moments | NO | N x 2 | N x 2 |\r\n| Flow | flow | YES | N x 1 | - - - - - - - |\r\n| Betweenness centrality | betweenness_centrality | NO | N x 1 | N x 1 |\r\n| Communicability betweenness centrality | communicability_betweenness_centrality | NO | - - - - - - - | N x ? |\r\n| Eigenvector centrality | eigenvector_centrality | NO | N x 1 | N x 1 |\r\n| Clustering coefficient | clustering_coefficient | NO | N x 1 | N x 1 |\r\n| Square clustering coefficient | square_clustering_coefficient | NO | N x 1 | N x 1 |\r\n| Generalized degree | generalized_degree | NO | - - - - - - - | N x 16 |\r\n| All pairs shortest path length | all_pairs_shortest_path_length | NO | N x N | N x N |\r\n\r\n^ Degree - In the undirected case return the sum of the in degree and the out degree. <br>\r\n^^Louvain - Implement Louvain community detection method, then associate to each vertex the number of vertices in its community.\r\n\r\nAside from those, there are some other [edge features](https://github.com/AmitKabya/graph-measures/tree/master/src/graphMeasures/features_algorithms/edges).\r\nSome more information regarding the features can be found in the files of [features_meta](https://github.com/AmitKabya/graph-measures/blob/master/src/graphMeasures/features_meta).\r\n\r\n## Dependencies\r\n```\r\nsetuptools\r\nnetworkx==2.6.3\r\npandas\r\nnumpy\r\nmatplotlib\r\nscipy\r\nscikit-learn\r\npython-louvain\r\nbitstring\r\nfuture\r\ntorch\r\n```\r\n\r\n## How To Use The Accelerated Version (CPU/GPU)?\r\nBoth versions currently are not supported with the pip installation. \\\r\nTo use the accelerated version, one must use <b>*Linux* operation system</b> and <b>*Anaconda* distribution</b>, with the follow the next steps:\r\n1. Go to the [package's GitHub website](https://github.com/AmitKabya/graph-measures) and manually download:\r\n\r\n - The directory `graphMeasures`.\r\n - The python file `runMakefileACC.py`.\r\n\r\n *You might need to download a zip of the repository and extract the necessary files.*\r\n2. Place both the file and the directory inside your project, and run `runMakefileACC.py`.\r\n3. Move to the *boost environment*: `conda activate boost` (The environment was created in step 2).\r\n4. Use the package as explained in the section `How To Use?`\r\n\r\n## Installation Through pip\r\nThe full functionality of the package is currently available on a Linux machine, with a Conda environment.\r\n- Linux + Conda<br>1. Go to base environment<br>2. If pip is not installed on your env, install it. Then, use pip to install the package\r\n- Otherwise, pip must be installed.\r\n```commandline\r\npip install graph-measures\r\n```\r\n**Note:** On Linux+Conda the installation might take longer (about 5-10 minuets) due to the compilation of the c++ files.\r\n## How To Use?\r\nEven though one has installed the package as `graph-measures`, The package should be imported from the code as `graphMesaures`. Hence, use:\r\n```python\r\nfrom graphMeasures import FeatureCalculator\r\n```\r\n## Calculating Features\r\n\r\nThere are two main methods to calculate features:\r\n1. Using [FeatureCalculator](https://github.com/louzounlab/graph-measures/blob/master/graphMeasures/features_for_any_graph.py) (**recommended**): \\\r\nA class for calculating any requested features on a given graph. \\\r\nThe graph is input to this class as a text-like file of edges, with a comma delimiter, or a networkx _Graph_ object. \r\nFor example, the graph [example_graph.txt](https://github.com/louzounlab/graph-measures/blob/master/graphMeasures/measure_tests/example_graph.txt) is the following file: \r\n ```\r\n 0,1\r\n 0,2\r\n 1,3\r\n 3,2\r\n ```\r\n Now, an implementation of feature calculations on this graph looks like this:\r\n ```python\r\n import os\r\n from graphMeasures import FeatureCalculator\r\n \r\n # set of features to be calculated\r\n feats = [\"motif3\", \"louvain\"]\r\n \r\n # path to the graph's edgelist or nx.Graph object\r\n graph = os.path.join(\"measure_tests\", \"example_graph.txt\")\r\n \r\n # The path in which one would like to save the pickled features calculated in the process. \r\n dir_path = \"\" \r\n \r\n # More options are shown here. For information about them, refer to the file.\r\n ftr_calc = FeatureCalculator(path, feats, dir_path=dir_path, acc=True, directed=False,\r\n gpu=True, device=0, verbose=True)\r\n \r\n # Calculates the features. If one do not want the features to be saved,\r\n # one should set the parameter 'should_dump' to False (set to True by default).\r\n # If the features was already saved, you can set force_build to be True. \r\n ftr_calc.calculate_features(force_build=True)\r\n features = ftr_calc.get_features() # return pandas Dataframe with the features \r\n ``` \r\n <!-- More information can be found in [features_for_any_graph.py](https://github.com/AmitKabya/graph-measures/blob/master/src/graphMeasures/features_for_any_graph.py). \\-->\r\n **Note:** If one set `acc=True` without using a Linux+Conda machine, an exception will be thrown.\\\r\n **Note:** If one set `gpu=True` without using a Linux+Conda machine that has cuda available on it, an exception will be thrown.\r\n<br />\r\n<br />\r\n2. Using graphMeasure <a href=\"https://github.com/louzounlab/graph-measures/blob/master/OTHERS.md\">without FeatureCalculator</a> (**less recommended**).\r\n\r\n[//]: # (2. Using graphMeasure [without FeatureCalculator](https://github.com/louzounlab/graph-measures/blob/master/OTHERS.md) (**less recommended**).)\r\n<br />\r\n\r\n## Edges motifs:\r\nFor now, you can calculate only motifs for edges. Unfortunately, you will have to do it separately from the nodes features.\r\nThere are two options for motif calculation - python version, and accelerated version (in CPP).\r\nThe python version is always available, but the accelerated version available only on linux machine \r\n(the makefile targets linux, but the code should work for any os). Anyway, if you have a suitable machine,\r\nthe accelerated version is more recommended.\r\n\r\nTo run the accelerated version you should do:\r\n1. Copy the graphMeasures directory to your project (available in this branch).\r\n2. Open terminal in `graphMeasures/edges_features/acc_features/acc/`\r\n3. Run the command `make`. If the makefile ends normally, a so file should be in a dir named bin.\r\n\r\nExecution example:\r\n```python\r\nimport networkx as nx\r\nfrom graphMeasures.edges_features.feature_calculator import FeatureCalculator\r\n\r\npath = \"./data/graph.txt\"\r\ngnx = nx.read_edgelist(path, delimiter=\",\", create_using=nx.DiGraph)\r\n# acc signs if we will use the accelerated version.\r\ncalculator = FeatureCalculator([\"motif3\", \"motif4\"], gnx, acc=True) \r\ncalculator.build()\r\n\r\n# The result will be a pandas Dataframe named calculator.df.\r\nprint(calculator.df)\r\n```\r\n\r\n\r\n## Contact us\r\nThis package was written by [Yolo lab's](https://yolo.math.biu.ac.il/) team from Bar-Ilan University. \\\r\nFor questions, comments or suggestions you can contact louzouy@math.biu.ac.il.\r\n\r\n[//]: # (### Ouptput)\r\n\r\n[//]: # (graphMeasures uses ```networkx```'s ```networkx.convert_node_labels_to_integers``` function, and then calculates the features. )\r\n\r\n[//]: # (That's why the output matrix is ordered by the new nodes labels (from 0 to n-1) and not by the original labels.)\r\n\r\n[//]: # ()\r\n[//]: # (graphMeasures sometimes return the output columns not in the order they were inserted. The )\r\n \r\n",
"bugtrack_url": null,
"license": "GPL",
"summary": "A python package for calculating topological graph features on cpu/gpu",
"version": "0.1.57",
"split_keywords": [
"gpu",
"graph",
"topological-features-calculator"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "c93f3044ed82d8162bfd250a9f7cac5e",
"sha256": "1578b7bcfcc22d40c58ca2ec6ff96fbabce696b983b56d0cf7bd5e6e09b58b0b"
},
"downloads": -1,
"filename": "graph_measures-0.1.57-cp310-cp310-win_amd64.whl",
"has_sig": false,
"md5_digest": "c93f3044ed82d8162bfd250a9f7cac5e",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.6.8",
"size": 119170,
"upload_time": "2022-12-11T14:26:13",
"upload_time_iso_8601": "2022-12-11T14:26:13.943828Z",
"url": "https://files.pythonhosted.org/packages/fe/e6/d328a2421afa5c550a3be76881f92ee3715bda5274957d64ad96c03748cb/graph_measures-0.1.57-cp310-cp310-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "3afee75bd051de4895645e8c3869d034",
"sha256": "f89e3d947b1f5de80fac2301df9db898b371d6f29a66e4cde86d2a80a640cdc7"
},
"downloads": -1,
"filename": "graph-measures-0.1.57.tar.gz",
"has_sig": false,
"md5_digest": "3afee75bd051de4895645e8c3869d034",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6.8",
"size": 386410,
"upload_time": "2022-12-11T14:26:17",
"upload_time_iso_8601": "2022-12-11T14:26:17.368197Z",
"url": "https://files.pythonhosted.org/packages/6b/24/fa07389553f22b98b17bfc9a2edd4017f20a9373d7bfa64d3fbba8c9d8c7/graph-measures-0.1.57.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-11 14:26:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "louzounlab",
"github_project": "graph-measures",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "setuptools",
"specs": []
},
{
"name": "networkx",
"specs": [
[
"==",
"2.6.3"
]
]
},
{
"name": "pandas",
"specs": []
},
{
"name": "numpy",
"specs": []
},
{
"name": "matplotlib",
"specs": []
},
{
"name": "scipy",
"specs": []
},
{
"name": "scikit-learn",
"specs": []
},
{
"name": "python-louvain",
"specs": []
},
{
"name": "bitstring",
"specs": []
},
{
"name": "future",
"specs": []
},
{
"name": "torch",
"specs": []
}
],
"lcname": "graph-measures"
}
JSON
