-At the core of `pygrank` lies the concept of *graph signals*, which map graph nodes to scores.
+At the core of `pygrank` lies the concept of *graph signals*, which map graph nodes to numerical scores.
Supervised and unsupervised measures evaluate the predictive/ranking quality
of graph signals.
@@ -23,3 +23,4 @@ Here is a glossary of common concepts sorted alphabetically:
| Personalization | The graph signal inputted in grap filters. This is also known as graph signal priors or the personalization vector. |
| Seeds | Example nodes that are known to belong to a community. |
| Tuning | A process of determining algorithm hyper-parameters that optimize some evaluation measure. |
+
diff --git a/docs/basics/filters.md b/docs/basics/filters.md
index 5fcd351..dc5e28e 100644
--- a/docs/basics/filters.md
+++ b/docs/basics/filters.md
@@ -12,25 +12,20 @@ applies a graph filter, potentially postprocesses its outcome, and eventually ar
-
-## Calling filters
-
Filters are created based on a constructor that takes as input several keyword
arguments affecting how they work. An exhaustive list of ready-to-use graph filters
and their constructors
-found [here](../generated/filters.md). After its initialization, a filter `alg` can run
+found [here](../generated/filters.md).
+More complicated node ranking algorithms can be obtained by applying postprocessors on
+filters. This is covered in the [next section](postprocessors.md).
+After its initialization, a filter `alg` can run
with one of the following two patterns (these are interchangeable):
* `ranks = alg(graph, personalization)`
* `alg(pg.to_signal(graph, personalization))`
-More complicated node ranking algorithms can be obtained by applying postprocessors on
-filters. This is covered in the [next section](postprocessors.md).
-
-
-## Example
-Let us define an personalized PageRank filter. If the personalization is
+As an example, let us define an personalized PageRank filter. If the personalization is
binary (i.e. all nodes have initial scores either 0 or 1) this algorithm
is equivalent to a stochastic Markov process where it starts from the nodes
with initial scores 1, iteratively jumps to neighbors randomly, and has
diff --git a/docs/basics/postprocessors.md b/docs/basics/postprocessors.md
index 2baab02..d364759 100644
--- a/docs/basics/postprocessors.md
+++ b/docs/basics/postprocessors.md
@@ -2,22 +2,15 @@
Filter outcomes of graph often require additional processing steps, for example to perform
normalization, improve their quality, or apply fairness constraints.
-We refer to the improvement of graph filter outcomes as postprocessing,
-and let node ranking algorithms perform any number of postprocessing steps
-on top of base graph filters.
-
-
-## Wrapping filters
-
-Postprocessors wrap base graph filters to affect their outcome. The resulting
+Postptprocessors wrap base filters to improve their outcomes, and the result
node ranking algorithms are called as if they were still filters. The filters
can either be supplied to construcors, or the postprocessors may be initialized
from the rest of their arguments and applied onto filters afterwards with the
-pattern `algorithm = filter >> postprocessor`.
+functional chain pattern `algorithm = filter >> postprocessor`.
An list of ready-to-use postprocessors can be
-found [here](../generated/postprocessors.md). Simplar ones perform
+found [here](../generated/postprocessors.md). Simpler ones perform
normalization, for example to enforce the maximal or the sum
of node scores to be 1. There also exist thresholding schemes, which can be used
for binary community detection, as well as methods to make node
@@ -30,14 +23,11 @@ by providing more example nodes, and for fairness-aware posteriors,
which aim to make node scores adhere to some fairness constraint,
such as disparate impact.
-
-## Example
-
-Let us consider a simple scenario where we want the graph signal outputted
+Let us consider a simple toy scenario where we want the graph signal outputted
by a filter to always be normalized so that its largest node score is one. For
-this, we consider a graph `G`, signal `signal` and filter `alg`,
-and will use the postprocessor `Normalize`. For convenience, some postprocessors supply a
-`transform` method that can be applied on graph signals like so:
+graph `G`, signal `signal` and filter `alg`,
+and can use the postprocessor `Normalize("max")`. For convenience, simpler postprocessors
+like this one supply a method to transform graph signals like so:
```python
scores = alg(graph, signal)
@@ -46,8 +36,8 @@ print(list(normalized_scores.items()))
# [('A', 1.0), ('B', 0.4950000024069947), ('C', 0.9828783455187619), ('D', 0.9540636897749238), ('E', 0.472261528845582)]
```
-However, the pattern that works for **all** postprocessors
-is to wrap base algorithms, like in the following example:
+The pattern that works for **all** postprocessors
+is to wrap base algorithms, like in the following equivalent example:
```python
@@ -57,13 +47,12 @@ print(nscores)
# [('A', 1.0), ('B', 0.4950000024069947), ('C', 0.9828783455187619), ('D', 0.9540636897749238), ('E', 0.472261528845582)]
```
-We now apply more steps to the algorithm by performing
-an element-wise exponential transformation of node scores
-with the postprocessor `Transformer` *before* normalization
-can be achieved as:
+We can add more steps, such as
+an element-wise exponential transformation of scores
+before normalization:
```python
-nealg = alg >> pg.Transformer(pp.exp) >> pg.Normalize("max")
+nealg = alg >> pg.Transformer(pf.exp) >> pg.Normalize("max")
nescores = nealg(graph, signal)
print(nescores)
# [('A', 1.0), ('B', 0.8786683440755908), ('C', 0.9956241609824301), ('D', 0.9883030876536782), ('E', 0.8735657648099558)]
diff --git a/docs/basics/quickstart.md b/docs/basics/quickstart.md
new file mode 100644
index 0000000..b18f4f9
--- /dev/null
+++ b/docs/basics/quickstart.md
@@ -0,0 +1,36 @@
+# Quickstart
+
+1. Install the library with `pip install pygrank`, import it,
+and construct a node ranking algorithm
+(incrementally apply postprocessors with `>>`).
+There are many components and parameters to find
+good configurations; [autotuning](advanced/autotuning.md) may be helpful.
+
+```python
+import pygrank as pg
+
+hk5 = pg.HeatKernel(t=5, normalization="symmetric", renormalize=True) # a graph filter
+hk5_advanced = hk5 >> pg.SeedOversampling() >> pg.Sweep() >> pg.Normalize("max")
+```
+
+2. Automatically load a graph and a community of nodes with some shared attribute.
+You can also use a `networkx` graph.
+Then run the algorithm to get a graph signal that maps nodes to scores, where scores indicate
+structural proximity to community members.
+
+```python
+_, graph, community = next(pg.load_datasets_one_community(["EUCore"]))
+personalization = {node: 1.0 for node in community} # binary or stochastic membership, missing scores are zero
+
+scores = hk5_advanced(graph, personalization) # returns a dict-like pg.GraphSignal
+print(scores) # {'0': 0.3154503251398683, '1': 0.26661671252340463, '2': 0.03700150026429704, ... }
+```
+
+3. Evaluate scores; here we use a stochastic generalization of the unsupervised Conductance measure (that
+can parse scores).
+
+```python
+measure = pg.Conductance() # an evaluation measure
+pg.benchmark_print_line("My conductance", measure(scores)) # pretty
+print("Cite this algorithm as:", hk5_advanced.cite())
+```
diff --git a/docs/index.md b/docs/index.md
index d5b4f1c..bfb02c6 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,58 +1,46 @@
-# pygrank
+# pygrank
+**Fast node ranking algorithms on large graphs.**
-Fast node ranking algorithms on large graphs.
+Graph signals work as both dictionaries and arrays. + They are easy to create and run on efficient backends.
+Fast processing of big graphs; sparse data structures, + extensive caching, and scalable algorithms.
+Combine graph filters with multiple postprocessor components + through a seamless pipeline.
+Run benchmarks, or autotune algorithms + as they run based on supervised or unsupervised measures.
+