Refactored Code for SEMB

Author: ReactiveXYZ-Jackie

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "python.pythonPath": "/Users/jackiezhang/miniconda2/envs/gemslab/bin/python"
+}

README.md

@@ -0,0 +1,62 @@
+# The Structural EMBedding library (SEMB)
+
+**Authors: GEMS Lab Team @ University of Michigan**
+
+This SEMB library allows fast onboarding to explore structural embedding of graph data using hetereogenous methods, with a unified API interface and a modular codebase enabling easy intergration of 3rd party methods and datasets.
+
+The library itself has already included a set of popular methods and datasets ready for use immediately.
+
+The library requires *Python 3.7+*.
+
+## Getting started
+
+Make sure you are using *Python 3.7+* for all below!
+
+### Installation
+`python setup.py install` (TODO: Pip support will be added soon)
+
+### Import and load a dataset
+```py
+from semb.data import load, get_dataset_ids
+# explore all datasets (both built in and extended by 3rd party)
+ids = get_dataset_ids()
+# load a dataset
+graph = load(ids[0])
+```
+
+### Import and load a method
+```py
+from semb.methods import load, get_method_ids
+# explore all methods (both built in and extended by 3rd party)
+ids = ge_method_ids()
+# load a method, returns a constructor for a method's base class
+Method = load(ids[0])
+# create and run a method.
+# NOTE: except for the first "graph" arg, everything other argument MUST be in keyword form!
+method = Method(graph, a=1, b=2, c=3, ...)
+method.train()
+embeddings = method.get_embeddings()
+```
+
+## Extending SEMB
+
+First make sure the `semb` library is installed.
+
+### Developing 3rd party Dataset extension
+
+- Create a Python 3.7+ [package](https://packaging.python.org/tutorials/packaging-projects/) with a name in form of `semb-dataset[$YOUR_CHOSEN_DATASET_ID]`
+- Within the package root directory, make sure `__init__.py` is present
+- Create a `dataset.py` and make a `Method` class that inherits from `from semb.data import BaseDataset` and implement the required methods. See `src/datasets/airports/dataset.py` for more details.
+- Install the package via `setup.py` or pip.
+- Now the dataset is loadable by the main client program that uses `semb`!
+
+### Developing 3rd party Method extension
+
+- Create a Python 3.7+ [package](https://packaging.python.org/tutorials/packaging-projects/) with a name in form of `semb-method[$YOUR_CHOSEN_METHOD_ID]`
+- Within the package root directory, make sure `__init__.py` is present
+- Create a `dataset.py` and make a `Dataset` class that inherits from `from semb.data import BaseDataset` and implement the required methods. See `src/methods/node2vec/method.py` for more details.
+- Install the package via `setup.py` or pip.
+- Now the method is load-able by the main client program that uses `semb`!
+
+### Note
+For both `dataset` and `method` extensions, make sure the `get_id()` to be overridden and returns the same id as your chosen id in your package name.

build/lib/src/__init__.py

@@ -0,0 +1,3 @@
+from .data import Dataset, BaseDataProvider
+
+from .loader import load, get_dataset_ids

build/lib/src/data/__init__.py

@@ -0,0 +1,22 @@
+from collections import namedtuple
+from typing import List
+from os import path
+from ..exceptions import UnimplementedException
+
+# TODO: add more buildtin datasets below
+# FIXME: fix the current relative path into remote file url
+SAMPLE_DATA_PATH = path.join(path.dirname(__file__), '../../sample-data')
+
+# the Data type for all supported data sets
+Dataset = namedtuple('Dataset', ['name', 'description', 'format', 'src_url'])
+
+# the base class for all new data providers
+class BaseDataProvider(object):
+    
+    def provideId(self) -> str:
+        raise UnimplementedException(
+            "Please implement the provideId() method to register the unique id for your datasets")
+
+    def provideDatasets(self) -> List[Dataset]:
+        raise UnimplementedException(
+            "Please implement the provideDatasets() method for registering dataset details")

build/lib/src/data/data.py

@@ -0,0 +1,34 @@
+import networkx as nx
+import requests
+from requests_file import FileAdapter
+from os import path
+
+from ..exceptions import DatasetNotExistException
+
+# repository for all data sets
+DATASETS = {}
+
+# dynamically export all included datasets 
+def _find_builtin_datasets(methods):
+    pass
+
+# TODO: add support to register 3rd party extension methods automatically by searching the installed packages
+def _find_external_datasets(methods):
+    pass
+
+_find_builtin_datasets(DATASETS)
+_find_external_datasets(DATASETS)
+
+def get_dataset_ids():
+    global DATASETS
+    return list(DATASETS.keys())
+
+def load(dataset_id):
+    """
+    For a data item, loads from its source and convert to a graph
+
+    Args:
+        dataset_id (str): unique id to load the dataset from
+    """
+    # TODO
+    pass

build/lib/src/data/loader.py

@@ -0,0 +1 @@
+#TODO: what to put here?

build/lib/src/evaluations/__init__.py

@@ -0,0 +1,11 @@
+class UnimplementedException(Exception):
+    pass
+
+class DatasetNotExistException(Exception):
+    pass
+
+class DatasetFormatNotAllowedException(Exception):
+    pass
+
+class MethodKeywordUnAllowedException(Exception):
+    pass

build/lib/src/exceptions.py

@@ -0,0 +1,5 @@
+# export BaseDriver to be used for 3rd party extension
+from .method import BaseMethod
+
+# export method loader
+from .loader import load, get_method_ids