Repository: wwu-mmll/photonai_graph (language: python)

Issue:
Revise documentation
Please only change inline documentation scince #21
Revise documentation
Please only change inline documentation scince #21
Feature/documentation update



Discussion / hints:
Please use numpy comment style only!
#43 updates:

- [X] New color scheme
- [x] New images
- [x] New menu structure
- [x] Fixed codehighlighting
- [x] Fixed admonitions
- [x] Fixed page edit uri
- [x] New code font
Please use numpy comment style only!
#43 updates:

- [X] New color scheme
- [x] New images
- [x] New menu structure
- [x] Fixed codehighlighting
- [x] Fixed admonitions
- [x] Fixed page edit uri
- [x] New code font


Fix patch:
diff --git a/documentation/docs/dynamic_utils.md b/documentation/docs/api/dynamic_utils.md
similarity index 95%
rename from documentation/docs/dynamic_utils.md
rename to documentation/docs/api/dynamic_utils.md
index f56ee7f..35e8754 100644
--- a/documentation/docs/dynamic_utils.md
+++ b/documentation/docs/api/dynamic_utils.md
@@ -2,7 +2,7 @@
 
 A module focused on functions and constructors for dynamic graph data.
 
-!!! warning "Warning" 
+!!! danger "Warning" 
     Currently under development and constantly evolving. Use with caution.
 
 ## CofluctTransform
diff --git a/documentation/docs/examples/graph_construction_examples.md b/documentation/docs/api/examples/graph_construction_examples.md
similarity index 100%
rename from documentation/docs/examples/graph_construction_examples.md
rename to documentation/docs/api/examples/graph_construction_examples.md
diff --git a/documentation/docs/graph_construction.md b/documentation/docs/api/graph_construction.md
similarity index 100%
rename from documentation/docs/graph_construction.md
rename to documentation/docs/api/graph_construction.md
diff --git a/documentation/docs/graph_convnets.md b/documentation/docs/api/graph_convnets.md
similarity index 100%
rename from documentation/docs/graph_convnets.md
rename to documentation/docs/api/graph_convnets.md
diff --git a/documentation/docs/graph_embeddings.md b/documentation/docs/api/graph_embeddings.md
similarity index 100%
rename from documentation/docs/graph_embeddings.md
rename to documentation/docs/api/graph_embeddings.md
diff --git a/documentation/docs/graph_kernels.md b/documentation/docs/api/graph_kernels.md
similarity index 100%
rename from documentation/docs/graph_kernels.md
rename to documentation/docs/api/graph_kernels.md
diff --git a/documentation/docs/graph_measures.md b/documentation/docs/api/graph_measures.md
similarity index 100%
rename from documentation/docs/graph_measures.md
rename to documentation/docs/api/graph_measures.md
diff --git a/documentation/docs/graph_utilities.md b/documentation/docs/api/graph_utilities.md
similarity index 100%
rename from documentation/docs/graph_utilities.md
rename to documentation/docs/api/graph_utilities.md
diff --git a/documentation/docs/API.md b/documentation/docs/api/introduction.md
similarity index 73%
rename from documentation/docs/API.md
rename to documentation/docs/api/introduction.md
index 55fcb15..96b2be1 100644
--- a/documentation/docs/API.md
+++ b/documentation/docs/api/introduction.md
@@ -28,11 +28,31 @@ classDiagram-v2
 ## Predictor Classes
 Predictor objects are the actual learning algorithm of the respective pipeline.
 Therefore each predictor has to provide at least a `fit()` and a `predict()` function.
+
+PHOTONAI Graph provides predefined models for classification and regression.
+
+### Classification
 ```mermaid
 classDiagram-v2
     class Predictor{
     +fit()
     +predict()
     }
-    Predictor <|-- GraphNeuralNetwork  
+    Predictor <|-- DglModel  
+    DglModel <|-- GCNClassifierModel
+    DglModel <|-- SGConvClassifierModel
+    DglModel <|-- GATClassifierModel
 ```
+
+### Regression
+```mermaid
+classDiagram-v2
+    class Predictor{
+    +fit()
+    +predict()
+    }
+    Predictor <|-- DglModel 
+    DglModel <|-- GCNRegressorModel
+    DglModel <|-- SGConvRegressorModel
+    DglModel <|-- GATRegressorModel
+```
\ No newline at end of file
diff --git a/documentation/docs/assets/img/visualization_brain_edge_t.png b/documentation/docs/assets/img/visualization_brain_edge_t.png
new file mode 100644
index 0000000..d824a66
Binary files /dev/null and b/documentation/docs/assets/img/visualization_brain_edge_t.png differ
diff --git a/documentation/docs/stylesheets/material.css b/documentation/docs/assets/stylesheets/material.css
similarity index 100%
rename from documentation/docs/stylesheets/material.css
rename to documentation/docs/assets/stylesheets/material.css
diff --git a/documentation/docs/extending_photonai_graph.md b/documentation/docs/extending_photonai_graph.md
new file mode 100644
index 0000000..d39c07d
--- /dev/null
+++ b/documentation/docs/extending_photonai_graph.md
@@ -0,0 +1,1 @@
+Todo
\ No newline at end of file
diff --git a/documentation/docs/getting_started.md b/documentation/docs/getting_started.md
index b6e45a3..0916667 100644
--- a/documentation/docs/getting_started.md
+++ b/documentation/docs/getting_started.md
@@ -1,20 +1,31 @@
 # Getting started
 
-In order to get started, you will need connectivity matrices or data, that is already graph data. For this introduction we will assume that you are using connectivity matrices.
+In order to get started, you will need connectivity matrices or data, that is already graph data. 
+For this introduction we will assume that you are using connectivity matrices.
 
-## Loading your matrices
+## 1. Loading data
+PHOTONAI Graph offers a plethora of different methods for loading your data.
 
-If you are using dense matrices, photonai-graph assumes that they have a certain shape: They should come as numpy matrices or array with the dimensions **Subjects x nodes x nodes x modalities (optional)**. If you are using matlab files, from NBS, CONN or other popular neuroimaging connectivity toolboxes, you will have to import them. An example function on how to import matlab data matrices can be seen [here](https://github.com/BenisFarmen/connectivity_loading/blob/master/load_functions.py). 
+As this toolbox is build with neuro scientists in mind, the first example will cover the case of connectivity matrices.
+However, PHOTONAI Graph is not limited to connectivity matrices.
 
-With such a function you can then load your data.
+If you are using matlab files, from NBS, CONN or other popular neuroimaging connectivity toolboxes, you will have to 
+import them. An example function on how to import matlab data matrices is contained in PHOTONAI Graph.
+We cannot guarante that this function is correctly loading your data. If in doubt please write your own importer.
+
+!!! info 
+    If you are using dense matrices, photonai-graph assumes that they have a certain shape: 
+    They should come as numpy matrices or array with the dimensions *Subjects x nodes x nodes x modalities (optional)*. 
+
+With such a function you can then load your data:
 
 ```python
-from  connectivity_loading import load_conn
+from connectivity_loading import load_conn
 
 matrices = load_conn('/path/to/your/data.mat')
 ```
 
-## Load your labels
+## 2. Load your labels
 
 Now you can load your labels. Make sure that your labels match the number of subjects.
 
@@ -25,7 +36,7 @@ df = pd.read_csv('/path/to/labels.csv')
 labels = df['your_label']
 ```
 
-## Set up pipeline
+## 3. Set up pipeline
 
 Now you can set up a photon pipeline. You will need to instantiate a Hyperpipe class which manages your validation settings for hyperparameter optimization. Then you can add elements to the pipeline.
 
@@ -43,6 +54,11 @@ my_pipe = Hyperpipe('basic_gmeasure_pipe',
 
 Having chosen the pipeline settings, you can now add elements to your pipeline. Here we first add a constructor to threshold our connectivity matrices, then a measure transformer to extract graph measures which will then be used by the SVM to estimate the label.
 
+!!! info
+    Since PHOTONAI Graph is based on PHOTONAI, a nested cross validation is evaluated by default. You are also able to 
+    add more transformers and estimators already contained in PHOTONAI. For more information pleas read the documentation
+    of [PHOTONAI](https://wwu-mmll.github.io/photonai/).
+
 ```python
 my_pipe.add(PipelineElement('GraphConstructorThreshold',
                             hyperparameters={'threshold': 0.8}))
@@ -62,13 +78,17 @@ After setting up a desired pipeline, you will only have to fit it on your data.
 my_pipe.fit(matrices, labels)
 ```
 
-## Evaluate pipeline
+## 4. Evaluate pipeline
 
-After fitting your pipeline you can now evaluate the pipeline by uploading your json results file to the photon explorer. You can also use your trained model to predict on different data.
+Since PHOTONAI Graph is based on PHOTONAI, you can use the inspection and visualization functions of PHOTONAI.
+These are documented <a target='_blank' href='https://wwu-mmll.github.io/photonai/getting_started/output/'>here</a>.
+
+Especially uploading the generated `photon_result_file.json` to the <a target='_blank' href='https://explorer.photon-ai.com/'>PHOTONAI Explorer</a>
+can become very handy when evaluating your models.
+ You can also use your trained model to predict on different data.
 
 ```python
 ext_data = load_conn('/path/to/your/other_data.mat')
 
 my_pipe.predict(ext_data)
 ```
-
diff --git a/documentation/docs/index.md b/documentation/docs/index.md
index 9df1fc7..653778f 100644
--- a/documentation/docs/index.md
+++ b/documentation/docs/index.md
@@ -7,6 +7,15 @@ This is an extension module to the PHOTONAI Python toolbox. With PHOTONAI Graph,
 
 ## Background
 
-Graphs structures can be found in many different fields from social networks, to molecular graphs to brain networks. They are very common in biology and neuroscience, for example in the area of connectomics. Graphs provide a natural representation of networks and allow for the study of their properties. In order to make use of the special information that the graph structure provides, different machine learning techniques have been developed. PHOTONAI Graph integrates a lot of these algorithms into the PHOTON framework and makes out-of-the-box models available for the study of graphs.
+Graphs structures can be found in many different fields from social networks, to molecular graphs to brain networks. 
+They are very common in biology and neuroscience, for example in the area of connectomics. 
 
-This allows researchers from a variety of fields to use graph machine learning techniques for their projects and to build pipelines and evaluate them within a few lines of code.
\ No newline at end of file
+![](assets/img/visualization_brain_edge_t.png)
+
+Graphs provide a natural
+representation of networks and allow for the study of their properties. In order to make use of the special information
+that the graph structure provides, different machine learning techniques have been developed. PHOTONAI Graph integrates
+a lot of these algorithms into the PHOTON framework and makes out-of-the-box models available for the study of graphs.
+
+This allows researchers from a variety of fields to use graph machine learning techniques for their projects and to 
+build pipelines and evaluate them within a few lines of code.
\ No newline at end of file
diff --git a/documentation/docs/installation.md b/documentation/docs/installation.md
index aed2d15..2e5b8fc 100644
--- a/documentation/docs/installation.md
+++ b/documentation/docs/installation.md
@@ -1,11 +1,20 @@
 # Installation
 The bare installation of PHOTONAI Graph will get you up and running with machine learning graph analysis.
-Some analysis may require additional packages. PHOTONAI Graph will inform you about these requirements if needed.
+
+!!! info
+    Some analysis may require additional packages. PHOTONAI Graph will inform you about these requirements if needed.
+    If you want to install them in advance please read [additional packages](#additional-packages).
 
 
 ## Prerequisites
 We recommend using [anaconda](https://www.anaconda.com/) environments. Alternatively you can simply use virtual environments or install PHOTONAI Graph system wide.
 
+PHOTONAI Graph is currently tested with python 3.9
+```shell
+conda create -n photonai_graph
+conda activate photonai_graph
+conda install python=3.9
+```
 ## Installation via PIP
 
 The PHOTONAI Graph library can simply be installed via pip:
@@ -28,10 +37,9 @@ You can verify your installation by starting python and runnning:
 
 ```python
 import photonai_graph
-print(photonai_graph.__version__)
 ```
 
-This should not return an error but the currently installed version number of PHOTONAI Graph.
+If this command does not raise an error, you are ready to go.
 
 ## Additional packages
 To be able to use all modules of the toolbox you have to install these additional packages:
diff --git a/documentation/docs/load_and_save.md b/documentation/docs/load_and_save.md
new file mode 100644
index 0000000..131a456
--- /dev/null
+++ b/documentation/docs/load_and_save.md
@@ -0,0 +1,9 @@
+PHOTONAI Graph offers various methods for saving and loading graphs.
+Additionally, there are transformation functions for converting the graphs from one format into another.
+
+!!! info
+    If a specific format is required for your analysis, PHOTONAI Graph will try to automatically
+    convert your input graphs.
+## Loading graphs
+
+## Saving graphs
\ No newline at end of file
diff --git a/documentation/docs/workflow.md b/documentation/docs/workflow.md
index dabc90b..0a193ba 100644
--- a/documentation/docs/workflow.md
+++ b/documentation/docs/workflow.md
@@ -1,6 +1,14 @@
 # Workflow
 
-The starting point for PHOTON Graph can be either connectivity matrices or data that is already in a graph format (networkx, dgl, sparse/dense adjacency matrices). Depending on your starting point, there are different ways in which you will you will have set up your pipeline. In the case that you have connectivity matrices, you will need to use graph constructors to turn those connectivity matrices into adjacency matrices. After can choose from different options of doing machine learning with your graph data.
+The starting point for PHOTON Graph can be either connectivity matrices or data that is already in a graph 
+format. Depending on your starting point, there are different 
+ways in which you will you will have set up your pipeline. In the case that you have connectivity matrices, 
+you will need to use graph constructors to turn those connectivity matrices into adjacency matrices. 
+After that you can choose from different options of doing machine learning with your graph data.
+
+!!! info
+    PHOTONAI Graph offers various methods to load your graph data in existing formats. For example, you can simply
+    load nx or dgl graphs. For more information about supported formats see [load and save](load_and_save.md).
 
 ```mermaid
 graph TD
@@ -17,19 +25,90 @@ graph TD
 
 ### Connectivity matrices
 
-If you have connectivity matrices as your starting point, these might be noisy and densely connected, as for example in the case of resting state functional connectivity in the area of neuroscience. In order to reduce the amount connections and possibly reduce noise, one could threshold the graph so weak connections will be discarded. This is not the only possible way to construct adjacency matrices, and many more methods have been implemented, which can be found in the graph constructor section.
+If you have connectivity matrices as your starting point, these might be noisy and densely connected, 
+as for example in the case of resting state functional connectivity in the area of neuroscience. 
+In order to reduce the amount connections and possibly reduce noise, one could threshold the graph so 
+weak connections will be discarded. 
+
+```python
+import numpy as np
+from photonai_graph.GraphConstruction import GraphConstructorThreshold
+
+# Generate dummy data
+example_graph = np.ones((20, 20, 20))
+example_target = np.eye(20)
+
+# Init GraphConstructorThreshold object
+constructor = GraphConstructorThreshold(threshold=0.1)
+constructor.fit(example_graph, example_target)
+
+# Create graph from matrix
+graph = constructor.transform(example_graph)
+```
+
+!!! info
+    This is not the only possible way to construct adjacency matrices, 
+    and many more methods have been implemented, which can be found in the [graph constructor section](api/graph_construction.md).
 
 After transforming your matrix, using a graph constructor you can then use this matrix to do machine learning with it.
 
 ### Machine Learning on Graphs
 
-Once you have a graph structure, you can then use this graph structure to do machine learning on it in a variety of ways. One option would be to extract graph measures and use these graph measures to do classical machine learning on them. The measures preserve graph information, that would be lost if only looking at node values for example. Depending on the measure it might contain global or local graph information. A similar idea applies to graph embeddings and kernels. They provide lower-dimensional representations of the graph structure, while still preserving graph information. The resulting embedding/kernel transformation can then be used to do classical machine learning.
+Once you have a graph structure, you can then use this graph structure to do machine learning on it in a variety of ways.
+
+!!! note
+    Before running the analysis make sure if it should run using classical machine learning or deep learning with graph
+    neural networks.
+
+#### Classical Machine Learning
+For classical Machine Learning approaches we have to extract features from the graphs.
+PHOTONAI Graph offers different options for extracting features:
 
-In contrast Graph Neural Nets are modified neural networks, that learn directly on graphs and make use of graph information. Here different architectures are available, and no transformation step is required prior to the network. Similar to classical machine learning algorithms
+??? tip "[Graph Embeddings](api/graph_embeddings.md)"
+
+    Graph Embeddings are a way to learn a low dimensional representation of a graph. 
+    Through a graph embedding a graph can be represented in low dimensional form, while preserving graph
+    information. This low-dimensional representation can then be used for training classic machine learning algorithms
+    that would otherwise make no use of the graph information.
+??? tip "[Graph Measures](api/graph_measures.md)"
+
+    Graph measures or metrics are values that capture graph properties like efficiency. 
+    As these measures capture information across the entire graph, or for nodes, edges or subgraphs, 
+    they can be used to study graph properties. 
+    These measures can also be used as a low-dimensional representation of the graph in machine learning tasks.
+??? tip "[Graph Kernels](api/graph_kernels.md)"
+
+    Graph Kernels are learnable functions that map the graph structure into a lower dimensional representation 
+    and are commonly used to solve different problems in graph classification, or regression.
+
+After the data is transformed into a feature representation a standard PHOTONAI pipeline can be used to 
+predict on the graph data. For more details consult the <a href='https://wwu-mmll.github.io/photonai/' target='_blank'>PHOTONAI documentation</a>.
+
+!!! note 
+    All of the <a href='https://wwu-mmll.github.io/photonai/algorithms/estimators/' target='_blank'>PHOTONAI estimators</a>
+    can be used directly with PHOTONAI Graph.
+
+#### Deep Learning
+In contrast, Graph Neural Nets are modified neural networks, that learn directly on graphs and make use of graph 
+information. Here different architectures are available, and no transformation step is required prior to the network.
+
+!!! warning
+    If using Graph Neural Networks your data has to be in graph format. If you extract metadata from your graph
+    using a PHOTONAI Graph transformer, the application of Graph Neural Networks is not possible.
+
+PHOTONAI Graph already provides some [Graph Neural Networks](api/graph_convnets.md). However, additional models can
+be added by [extending PHOTONAI Graph](extending_photonai_graph.md).
 
 ### Building a pipeline
+When building a pipeline, the elements are highly dependent on your input data.
+If the input data is a connectivity matrix this has to be transformed into a graph at first.
+For illustrative purposes the example will consider the case where the input data is a connectivity matrix.
+
+!!! info
+    PHOTONAI Graph provides functions for generation of dummy connectivity matrices.
 
-Before building a pipeline, one has to determine the starting point. For illustrative purposes we will consider the case where one is starting with connectivity matrices. First you pick a graph constructor to turn your matrices into adjacency matrices. Then one has to choose whether transform the graph into a low dimensional representation or to directly use graph neural networks. Using PHOTON Graph this can be done in just a few lines of code.
+The next necessary decision is if the graph should be transformed into features for a subsequent classic
+machine learning pipeline or directly fed into a deep learning model.
 
 #### Example
 
diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml
index 3b9c9a3..50c6221 100644
--- a/documentation/mkdocs.yml
+++ b/documentation/mkdocs.yml
@@ -39,29 +39,32 @@ markdown_extensions:
           format: !!python/name:pymdownx.superfences.fence_code_format
   - codehilite
   - admonition
+  - pymdownx.details
 
 # Site structure
 nav: 
 - Home: 'index.md'
 - Installation: 'installation.md'
 - Getting Started: 'getting_started.md'
-- Workflow: 'workflow.md'
+- PHOTONAI Graph Workflow: 'workflow.md'
+- Load and Save Graphs: 'load_and_save.md'
+- Extending PHOTONAI Graph: 'extending_photonai_graph.md'
 - API:
-  - Introduction: 'API.md'
+  - API Introduction: 'api/introduction.md'
   - Graph Construction:
       - Functions:
-         'graph_construction.md'
+         'api/graph_construction.md'
       - Examples:
-         'examples/graph_construction_examples.md'
-  - Dynamic Utilities: 'dynamic_utils.md'
-  - Graph Measures: 'graph_measures.md'
-  - Graph Embeddings: 'graph_embeddings.md'
-  - Graph Kernels: 'graph_kernels.md'
-  - Graph Neural Networks: 'graph_convnets.md'
-  - Graph Utilities: 'graph_utilities.md'
+         'api/examples/graph_construction_examples.md'
+  - Dynamic Utilities: 'api/dynamic_utils.md'
+  - Graph Measures: 'api/graph_measures.md'
+  - Graph Embeddings: 'api/graph_embeddings.md'
+  - Graph Kernels: 'api/graph_kernels.md'
+  - Graph Neural Networks: 'api/graph_convnets.md'
+  - Graph Utilities: 'api/graph_utilities.md'
 
 extra_css:
-  - stylesheets/material.css
+  - assets/stylesheets/material.css
 
 plugins:
   - mkdocstrings:
@@ -70,5 +73,4 @@ plugins:
           selection:
             docstring_style: numpy
           rendering:
-            show_source: false
-  - git-revision-date-localized
\ No newline at end of file
+            show_source: false
\ No newline at end of file


Test patch:
diff --git a/documentation/docs/graph_test.md b/documentation/docs/api/graph_test.md
similarity index 100%
rename from documentation/docs/graph_test.md
rename to documentation/docs/api/graph_test.md