/
quickstart.txt
145 lines (83 loc) · 6.64 KB
/
quickstart.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
Introduction
=============
**StellarGraph** is a Python library for machine learning on graph-structured (or equivalently, network-structured) data.
Graph-structured data represent entities, e.g., people, as nodes (or equivalently, vertices),
and relationships between entities, e.g., friendship, as links (or equivalently, edges). Nodes and links may have associated attributes such as age, income, time when a friendship was established, etc. StellarGraph supports analysis of both homogeneous networks (with nodes and links of one type) and heterogeneous networks (with more than one type of nodes and/or links).
The StellarGraph library implements several state-of-the-art algorithms for applying machine learning methods to discover patterns and answer questions using graph-structured data.
The StellarGraph library can be used to solve tasks using graph-structured data, such as:
- Representation learning for nodes and edges, to be used for visualisation and various downstream machine learning tasks;
- Classification and attribute inference of nodes or edges;
- Link prediction.
We provide `Examples <https://github.com/stellargraph/stellargraph/tree/master/demos/>`_ of using ``StellarGraph`` to solve such tasks using several real-world datasets.
Getting Started
================
To get started with StellarGraph you'll need data structured as homogeneous or heterogeneous graph, including attributes for the entities represented as graph nodes.
`NetworkX <https://networkx.github.io/>`_ is used to represent the graph and `Pandas <https://pandas.pydata.org/>`_, `Scikit-Learn <http://scikit-learn.org/>`_, and/or `Numpy <http://www.numpy.org/>`_ can be used to are used to store node attributes.
Detailed and narrated `examples <https://github.com/stellargraph/stellargraph/tree/master/demos/>`_ of various machine learning workflows on network data, supported by StellarGraph, from data ingestion into graph structure to inference, are given in the `demos` directory of this repository.
Requirements
-------------
Main requirements (all requirements are in ``requirements.txt``)
* Python 3.6 (http://python.org)
* Keras (https://keras.io)
* NetworkX (https://networkx.github.io)
* Scikit-learn (http://scikit-learn.org/)
Installation
-------------
StellarGraph is a Python 3 library and requires Python version 3.6 to function (note that the library uses Keras with the Tensorflow backend, and thus does not currently work in python 3.7). The required Python version can be downloaded and installed from `python.org <http://python.org/>`_. Alternatively, use the Anaconda Python environment, available from `anaconda.com <https://www.anaconda.com/download/>`_.
The StellarGraph library can be installed in one of two ways, described next.
Install StellarGraph using ``pip``:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To install StellarGraph library from `PyPi <http://pypi.org>`_ using ``pip``, execute the following command::
pip install stellargraph
Some of the examples require installing additional dependencies as well as `stellargraph`.
To install these dependencies using ``pip``, execute the following command::
pip install stellargraph[demos]
Install StellarGraph from Github source:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Install a git client, for example install the XCode git client by typing::
git --install
First, clone the StellarGraph repository using ``git``::
git clone https://github.com/stellargraph/stellargraph.git
Then, ``cd`` to the StellarGraph folder, and install the libraray by executing the following commands::
cd stellargraph
pip install -r requirements.txt
pip install .
Other requirements are the NetworkX library (to create and modify graphs and networks), numpy (to manipulate numeric arrays), pandas (to manipulate tabular data), and gensim (to use the Word2Vec model), scikit-learn (to prepare datasets for machine learning), and matplotlib (for plotting).
Examples
=========
Getting the datasets
---------------------
The StellarGraph examples require datasets to work. They are not supplied with stellargraph, and need to be downloaded separately.
CORA dataset
^^^^^^^^^^^^^
This dataset can be downloaded from https://linqs-data.soe.ucsc.edu/public/lbc/cora.tgz
Download and unzip the `cora.tgz <https://linqs-data.soe.ucsc.edu/public/lbc/cora.tgz>`_ file to a location on your computer and pass this location as a command line argument to the example scripts, as detailed below.
Running the GraphSAGE Cora Node Classification Example
--------------------------------------------------------
* Install the ``stellargraph`` Python library, explained in the previous section.
* If you haven't already done so, clone the StellarGraph repository using ``git``::
git clone https://github.com/stellargraph/stellargraph.git
* Download and decompress the CORA dataset (see `Getting the datasets` above).
* Change to the Cora node classification directory under demos::
cd /path/to/stellargraph/demos/node-classification-graphsage
* Run the example script and specify the location of the downloaded CORA dataset with the following command::
python graphsage-cora-example.py -l <path_to_cora_dataset>
* Additional arguments can be specified that change the GraphSAGE model and training parameters, a description of these arguments is displayed using the help option to the script::
python cora-example.py --help
Running the GraphSAGE Cora Link Prediction Example
---------------------------------------------------
* Install the ``stellargraph`` Python library, explained in the previous section.
* If you haven't already done so, clone the StellarGraph repository using ``git``::
git clone https://github.com/stellargraph/stellargraph.git
* Download and decompress the CORA dataset (see `Getting the datasets` above).
* Change to the Cora link prediction directory under demos::
cd /path/to/stellargraph/demos/link-prediction-graphsage
* Run the example script and specify the location of the downloaded CORA dataset with the following command::
python cora-links-example.py -l <path_to_cora_dataset>
* Additional arguments can be specified that change the GraphSAGE model and training parameters, a description of these arguments is displayed using the help option to the script::
python cora-links-example.py --help
Running Other Examples
------------------------
There are several other examples in the ``demos`` directory. Read the `README.md <https://raw.githubusercontent.com/stellargraph/stellargraph/develop/demos/README.md>`_ in the ``demos`` directory to find out more.
.. _`Installing Git`: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
.. _`Python on HomeBrew`: https://docs.brew.sh/Homebrew-and-Python.html