Update docs

Author: NilsWinter

docs/getting-started.md

@@ -47,15 +47,19 @@ X_2 = X[:, 3:6]
 
 # Create a project
 project = PhotonaiProject(project_folder="example_project")
+```
 
+You can now add multiple analyses that e.g. use different sets of features. You need to pass the data (X, y) as if
+you were to call .fit() on a hyperpipe. The data arrays are then saved to disk which makes it easy to access them
+when running an analysis or performing the permutation test. This also makes it easy to simply rsync everything
+to an HPC cluster and run analyses there. Instead of creating a hyperpipe during runtime, you pass the location
+of a Python script that contains a function (hyperpipe constructor) that creates the PHOTONAI Hyperpipe you want
+to use in this project.
+```python
 # ---------------------------------------------------------------------
 # 1) Register analyses
 # ---------------------------------------------------------------------
-for name, current_X in [
-    ("all_features", X),
-    ("first_feature_set", X_1),
-    ("second_feature_set", X_2),
-]:
+for name, current_X in [("all_features", X), ("first_feature_set", X_1), ("second_feature_set", X_2)]:
     project.add(
         name=name,
         X=current_X,
@@ -65,51 +69,86 @@ for name, current_X in [
     )
 
 project.list_analyses()
+```
+Your PHOTONAI Hyperpipe constructor might look something like this.
+```python
+from photonai import Hyperpipe, PipelineElement
+from sklearn.model_selection import KFold
+
+
+def create_hyperpipe():
+    my_pipe = Hyperpipe('',
+                        optimizer='grid_search',
+                        metrics=['accuracy', 'precision', 'recall'],
+                        best_config_metric='accuracy',
+                        outer_cv=KFold(n_splits=10),
+                        inner_cv=KFold(n_splits=2),
+                        verbosity=1,
+                        project_folder='')
+
+    # Add transformer elements
+    my_pipe += PipelineElement("StandardScaler", hyperparameters={},
+                               test_disabled=True, with_mean=True, with_std=True)
+
+    my_pipe += PipelineElement("PCA", test_disabled=False)
+
+    # Add estimator
+    my_pipe += PipelineElement("SVC", hyperparameters={'kernel': ['linear', 'rbf']},
+                               gamma='scale', max_iter=10000)
 
+    return my_pipe
+```
+
+Now, when you want to run an analysis, you can refer to it by its name and simply call .run(). You can
+perform a permutation test in the same way.
+```python
 # ---------------------------------------------------------------------
 # 2) Run analyses
 # ---------------------------------------------------------------------
-for name in ["all_features", "first_feature_set", "second_feature_set"]:
-    project.run(name=name)
+project.run(name="all_features")
+project.run(name="first_feature_set")
+project.run(name="second_feature_set")
 
 # ---------------------------------------------------------------------
 # 3) Run permutation tests (local example)
 # ---------------------------------------------------------------------
 # Use a small number of permutations for testing; increase for real studies.
-for name in ["all_features", "first_feature_set", "second_feature_set"]:
-    project.run_permutation_test(name=name, n_perms=10, overwrite=True)
+project.run_permutation_test(name="all_features", n_perms=1000)
+project.run_permutation_test(name="first_feature_set", n_perms=1000)
+project.run_permutation_test(name="second_feature_set", n_perms=1000)
+```
 
+If you want to compare two PHOTONAI analyses, you can use the .compare_analyses() method which either uses
+the Nadeau-Bengio corrected t-test or relies on the permutations that have been computed in the individual 
+significance test of each analysis.
+```python
 # ---------------------------------------------------------------------
 # 4) Statistical comparison of analyses
 # ---------------------------------------------------------------------
 # For the Nadeau–Bengio test you must provide n_train and n_test as used
 # during cross-validation. Here we give a simple example.
-n_samples = X.shape[0]
-n_train = int(0.8 * n_samples)
-n_test = n_samples - n_train
-
 # Compare two analyses (Nadeau–Bengio corrected t-test)
 project.compare_analyses(
     first_analysis="first_feature_set",
     second_analysis="second_feature_set",
     method="nadeau-bengio",
-    n_train=n_train,
-    n_test=n_test,
+    n_train=9,
+    n_test=1,
 )
 
 # Compare two analyses (permutation-based)
 project.compare_analyses(
     first_analysis="all_features",
     second_analysis="second_feature_set",
     method="permutation",
-    n_perms=10,
+    n_perms=1000,
 )
 
 # Compare all pairs at once (optional)
 multi_results = project.compare_multiple_analyses(
     analyses=["all_features", "first_feature_set", "second_feature_set"],
     method="permutation",
-    n_perms=10,
+    n_perms=1000,
 )
 print(multi_results.head())
 ```

docs/report.md

@@ -1,7 +1,20 @@
 # Generate an HTML report for your project
 
-## Showcase
+## Example code
+You can generate an HTML report that summarizes all of your analyses for a project. This makes it easy to get
+a quick overview of all results but you can also access more detailed results for every analysis.
+
+```python
+# load an existing project
+project = PhotonaiProject(name='breast_cancer', directory='./')
 
+# then call the collect_results and write_report() function
+project.collect_results()
+project.write_report()
+```
+
+## Showcase
+Here, you can see how such an HTML report looks like. Simply click through the individual tabs and look at the results.
 <iframe src="../static/example_report.html"
         width="100%" height="700px"
         sandbox="allow-scripts allow-same-origin"