Add documentation

Author: NilsWinter

.github/workflows/docs.yml

@@ -0,0 +1,30 @@
+name: Build and deploy docs
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"   # or your preferred version
+
+      - name: Install dependencies
+        run: |
+          pip install mkdocs mkdocs-material mkdocstrings[python] photonai
+
+      - name: Build and deploy
+        run: |
+          mkdocs gh-deploy --force

docs/api.md

@@ -0,0 +1,3 @@
+# API Reference
+
+::: photonai_projects.project.PhotonaiProject

docs/getting-started.md

@@ -0,0 +1,155 @@
+# Getting started
+
+This page shows how to set up a simple PHOTONAI project using
+`PhotonaiProject`, run analyses, perform permutation tests, and
+statistically compare different analyses.
+
+## Installation
+
+Install the package (and PHOTONAI) into your environment:
+
+```bash
+pip install photonai photonai-projects 
+```
+
+## Basic concepts
+A **PhotonaiProject** manages multiple PHOTONAI analyses in a single
+project folder. Each analysis has its own subfolder containing:
+
+- a hyperpipe constructor script (hyperpipe_constructor.py)
+
+- a metadata file (hyperpipe_meta.json)
+
+- a data/ folder with X.npy and y.npy
+
+- (optionally) a permutations/ folder for permutation tests
+
+The typical workflow is:
+
+1. Create a project with PhotonaiProject. 
+2. Add analyses (data + hyperpipe constructor). 
+3. Run analyses to train and evaluate the models. 
+4. Run permutation tests to obtain null distributions. 
+5. Compare analyses statistically.
+
+## Minimal example
+Below is a complete example using the breast cancer dataset from
+scikit-learn. We create three analyses using different feature sets,
+run them, run permutation tests, and then compare them statistically.
+
+
+```python
+from photonai_projects.project import PhotonaiProject
+from sklearn.datasets import load_breast_cancer
+
+# Load example data
+X, y = load_breast_cancer(return_X_y=True)
+
+# Split features into different sets
+X_1 = X[:, :3]
+X_2 = X[:, 3:6]
+
+# Create a project
+project = PhotonaiProject(project_folder="example_project")
+
+# ---------------------------------------------------------------------
+# 1) Register analyses
+# ---------------------------------------------------------------------
+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,
+        y=y,
+        hyperpipe_script="path/to/hyperpipe_constructor.py",
+        name_hyperpipe_constructor="create_hyperpipe",
+    )
+
+project.list_analyses()
+
+# ---------------------------------------------------------------------
+# 2) Run analyses
+# ---------------------------------------------------------------------
+for name in ["all_features", "first_feature_set", "second_feature_set"]:
+    project.run(name=name)
+
+# ---------------------------------------------------------------------
+# 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)
+
+# ---------------------------------------------------------------------
+# 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,
+)
+
+# Compare two analyses (permutation-based)
+project.compare_analyses(
+    first_analysis="all_features",
+    second_analysis="second_feature_set",
+    method="permutation",
+    n_perms=10,
+)
+
+# 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,
+)
+print(multi_results.head())
+```
+
+## Running permutation tests on a SLURM cluster
+For large numbers of permutations, you can distribute them across a
+SLURM array:
+
+```python
+project.prepare_slurm_permutation_test(
+    name="second_feature_set",
+    n_perms=1000,
+    conda_env="my_photonai_env",
+    memory_per_cpu=2,
+    n_jobs=20,
+    run_time="0-02:00:00",
+    random_state=1,
+)
+```
+
+This creates a slurm_job.cmd script in the analysis folder which you
+can submit with:
+
+```bash
+cd example_project/second_feature_set
+sbatch slurm_job.cmd
+```
+
+Each array job will call the Typer CLI entry point run_perm_job and
+execute a subset of permutation runs.
+
+## Next steps
+See the Usage page for more details on:
+
+- how to design your hyperpipe constructor, 
+- how metrics and scorers are handled, 
+- how to interpret the comparison reports.
+
+See the API Reference for the full documentation of PhotonaiProject.

docs/index.md

@@ -0,0 +1,94 @@
+# PHOTONAI Projects Documentation
+
+Welcome to the **PHOTONAI Projects** toolbox — a lightweight framework for organizing, running, and statistically comparing PHOTONAI analyses.
+
+This package helps you:
+
+- create and manage multiple analyses inside a structured project folder  
+- run PHOTONAI Hyperpipes on stored datasets  
+- perform permutation tests (locally or on SLURM clusters)  
+- aggregate permutation results and compute p-values  
+- compare multiple analyses statistically  
+  - **Nadeau–Bengio corrected t-test**  
+  - **Permutation-based tests**
+
+Whether you're running a single experiment or dozens of feature-selection pipelines, this toolbox keeps everything organized, reproducducible, and statistically valid.
+
+---
+
+## Quick links
+
+- **[Getting started](getting-started.md)**
+- **[API Reference](api.md)**
+
+---
+
+## Installation
+
+```bash
+pip install photonai photonai-projects
+```
+
+Or, if installing from a local checkout:
+
+```bash
+pip install -e .
+```
+
+---
+
+## What’s inside the toolbox?
+
+### **Project Management**
+
+Store each analysis in a clean folder structure:
+
+```
+project/
+├── analysis_1/
+│   ├── data/
+│   ├── hyperpipe_constructor.py
+│   └── hyperpipe_meta.json
+├── analysis_2/
+└── ...
+```
+
+### **Execution**
+
+Run any analysis:
+
+```python
+project.run("analysis_name")
+```
+
+### **Permutation Tests**
+
+Generate permutation-based null distributions:
+
+```python
+project.run_permutation_test("analysis_name", n_perms=1000)
+```
+
+### **Statistical Comparison**
+
+Compare analyses using:
+
+- `method="nadeau-bengio"`
+- `method="permutation"`
+
+```python
+project.compare_analyses("A", "B", method="permutation")
+```
+
+### **SLURM Support**
+
+Automatically prepare SLURM array jobs for large permutation workloads.
+
+---
+
+## Additional pages coming soon
+
+- Usage Guide  
+- Writing hyperpipe constructors  
+- Best practices  
+- Reproducibility checklist

docs/stylesheets/pastel-theme.css

@@ -0,0 +1,46 @@
+/* ---------------------------------------------------------
+   Light mode: pastel palette + deep green primary
+--------------------------------------------------------- */
+:root {
+  /* Deep green primary (buttons, header, links) */
+  --md-primary-fg-color: #2e5d50;
+  --md-primary-fg-color--light: #4f7d70;
+  --md-primary-fg-color--dark: #1e3f35;
+
+  /* Pastel teal accent (highlights, focus, active elements) */
+  --md-accent-fg-color: #9ad4c2;
+  --md-accent-fg-color--transparent: rgba(154, 212, 194, 0.2);
+
+  /* Pastel background tones */
+  --md-default-bg-color: #fafcff;           /* very soft off-white */
+  --md-default-fg-color: #2e3c42;
+  --md-default-fg-color--light: #5d6d74;
+
+  /* Code blocks (soft grey background) */
+  --md-code-bg-color: #f3f6f8;
+  --md-code-fg-color: #2a3a3f;
+}
+
+/* ---------------------------------------------------------
+   Dark mode: deep pine green + muted pastel highlights
+--------------------------------------------------------- */
+[data-md-color-scheme="slate"] {
+  --md-hue: 175; /* keeps greenish theme harmony */
+
+  /* Dark pine background */
+  --md-default-bg-color: #0f1a17;
+  --md-default-fg-color: #d8e3dd;
+  --md-default-fg-color--light: #a6b6b0;
+
+  /* Dark mode primary colors */
+  --md-primary-fg-color: #2e5d50;
+  --md-primary-fg-color--light: #4f7d70;
+  --md-primary-fg-color--dark: #1e3f35;
+
+  /* Soft pastel teal accent */
+  --md-accent-fg-color: #9ad4c2;
+
+  /* Code blocks */
+  --md-code-bg-color: #172421;
+  --md-code-fg-color: #dff7f0;
+}