Add AI-assissted tutorial experience

.github/copilot-instructions.md

@@ -0,0 +1,47 @@
+# Copilot Instructions for PydFC
+
+You are assisting users with the **PydFC** Python toolbox for dynamic functional connectivity (dFC) analysis.
+
+## Core Principles
+
+- Provide **copy-paste ready code**.
+- Keep answers short, practical, and step-by-step.
+- Prefer minimal working examples using demo data.
+- Use parameters from `examples/dFC_methods_demo.py` unless the user asks to customize.
+- If unsure, recommend the **Sliding Window (SW)** method first.
+
+## Safety Rule
+
+Do NOT modify source code in this repository unless the user explicitly asks for a code change or pull request.
+
+Avoid:
+- editing `pydfc/*`
+- modifying third-party packages
+- suggesting internal patches
+
+Instead, suggest:
+- environment checks
+- reinstall steps
+- parameter changes
+- smaller data subsets
+
+## Interaction Flow
+
+When guiding a new user:
+
+1. Ask whether they want:
+   - State-free method (single subject; fastest start), or
+   - State-based method (multi-subject; requires fitting)
+2. Provide install instructions if needed.
+3. Provide demo data download commands.
+4. Show minimal loading code (`BOLD` or `BOLD_multi`).
+5. Ask which dFC method they want.
+6. Provide one method snippet at a time.
+7. After results: ask if they want to try another method.
+8. Offer to export code into `.ipynb` or `.py`.
+
+## Source of Truth
+
+- `README.rst` → installation
+- `examples/dFC_methods_demo.py` → demo workflow
+- `docs/SKILL.md` → detailed guidance

.github/prompts/01_install.prompt.md

@@ -0,0 +1,13 @@
+# Install PydFC and Set Up Environment
+
+Guide the user through installing PydFC.
+
+## Steps
+
+1. Ask whether they use conda or pip.
+2. Provide installation commands:
+
+```bash
+conda create --name pydfc_env python=3.11
+conda activate pydfc_env
+pip install pydfc

.github/prompts/02_state_free_quickstart.prompt.md

@@ -0,0 +1,12 @@
+# State-Free Quickstart (Single Subject)
+
+Guide the user through the fastest way to run PydFC.
+
+## Steps
+
+1. Confirm PydFC is installed.
+2. Provide demo data download commands.
+
+### Jupyter
+```python
+!curl --create-dirs https://s3.amazonaws.com/openneuro.org/ds002785/derivatives/fmriprep/sub-0001/func/sub-0001_task-restingstate_acq-mb3_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz -o sample_data/sub-0001_bold.nii.gz

.github/prompts/03_state_based_quickstart.prompt.md

@@ -0,0 +1,18 @@
+# State-Based Quickstart (Multi-Subject)
+
+Guide the user through state-based analysis.
+
+## Steps
+
+1. Explain that state-based methods require multiple subjects.
+2. Provide demo data download commands for 5 subjects.
+3. Show minimal `BOLD_multi` loading example.
+4. Ask which method they want:
+   - CAP
+   - SWC
+   - CHMM
+   - DHMM
+   - WINDOWLESS
+5. Offer a short description if they are unsure.
+6. Provide one method snippet.
+7. Ask if they want to try another method.

.github/prompts/04_choose_method.prompt.md

@@ -0,0 +1,20 @@
+# Help Choose a dFC Method
+
+Ask the user:
+
+1. Is your data single-subject or multi-subject?
+2. Do you want:
+   - Continuous connectivity estimates
+   - Discrete brain states
+   - Frequency-specific dynamics
+
+Use answers to recommend:
+
+- SW → simple, continuous
+- TF → frequency-specific
+- CAP → intuitive states
+- SWC → windowed states
+- HMM → temporal modeling
+- WINDOWLESS → avoid window size dependence
+
+Keep explanations short.

.github/prompts/05_troubleshoot.prompt.md

@@ -0,0 +1,16 @@
+# Troubleshooting PydFC
+
+If the user reports an error:
+
+1. Ask for full traceback.
+2. Check:
+   - Python version
+   - PydFC version
+   - missing dependencies
+3. Suggest fixes in order:
+   - reinstall PydFC
+   - reduce nodes / subjects
+   - use SW instead of state-based methods
+   - adjust parameters
+
+Do NOT suggest editing source code.

.github/workflows/test.yml

@@ -58,7 +58,7 @@ jobs:
         -   name: Set up Python ${{ matrix.python-version }}
             uses: actions/setup-python@v5
             with:
-                python-version: ${{ matrix.python-version }}
+                python-version: '3.11'
                 architecture: ${{ matrix.architecture }}
                 allow-prereleases: true
         -   name: Display Python version

.pre-commit-config.yaml

@@ -47,7 +47,7 @@ repos:
         args: [--mapping, '4', --sequence, '4', --offset, '0']
 
 -   repo: https://github.com/macisamuele/language-formatters-pre-commit-hooks
-    rev: v2.12.0
+    rev: v2.14.0
     hooks:
     -   id: pretty-format-toml
         args: [--autofix, --indent, '4']

README.rst

@@ -2,25 +2,133 @@
     :alt: pydfc Logo
     :align: left
     :width: 250px
+
 .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.10161176.svg
     :target: https://zenodo.org/doi/10.5281/zenodo.10161176
+
 .. image:: https://img.shields.io/pypi/v/pydfc.svg
     :target: https://pypi.org/project/pydfc/
-    :alt: Pypi Package
+    :alt: PyPI Package
+
 
 pydfc
 =====
 
 An implementation of several well-known dynamic Functional Connectivity (dFC) assessment methods.
 
-Simply install ``pydfc`` using the following steps:
-  * ``conda create --name pydfc_env python=3.11``
-  * ``conda activate pydfc_env``
-  * ``pip install pydfc``
+Installation
+------------
+
+Simply install ``pydfc`` using the following steps::
+
+    conda create --name pydfc_env python=3.11
+    conda activate pydfc_env
+    pip install pydfc
+
+Examples
+--------
+
+The following example scripts illustrate how to use the toolbox:
+
+- ``examples/dFC_methods_demo.py``
+  Demonstrates how to load data and apply each of the implemented dFC methods individually.
+
+- ``examples/multi_analysis_demo.py``
+  Demonstrates how to apply multiple dFC methods on a dataset and compare their results.
+
+For more details about the implemented methods and the comparison analysis, see our paper:
+
+`On the variability of dynamic functional connectivity assessment methods <https://doi.org/10.1093/gigascience/giae009>`_
+
+    Mohammad Torabi, Georgios D Mitsis, Jean-Baptiste Poline,
+    *GigaScience*, Volume 13, 2024, giae009.
+
+AI-Assisted Tutorial Experience (Optional)
+------------------------------------------
+
+In addition to the example scripts and documentation, **pydfc** provides optional
+AI-assisted learning workflows that can help you explore the toolbox, understand
+dynamic functional connectivity methods, and generate minimal working examples.
+
+These options are entirely optional and do not affect the core functionality of the toolbox.
+
+Using GitHub Copilot Prompts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you use **GitHub Copilot** in VS Code or Visual Studio, you can access guided
+prompts that walk you through installing ``pydfc``, loading demo data, and running
+key dFC methods.
+
+**How to use:**
+
+1. Open the repository in VS Code.
+2. Open *Copilot Chat*.
+3. Run one of the available prompts, for example::
+
+       /01_install
+       /02_state_free_quickstart
+       /03_state_based_quickstart
+       /04_choose_method
+       /05_troubleshoot
+
+These prompts provide a structured, step-by-step tutorial experience and generate
+copy-paste code tailored to common workflows.
+
+We encourage users with Copilot access to try this interactive experience to
+quickly become familiar with the toolbox.
+
+Using Codex, Claude, or Other AI Coding Assistants
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you use **Codex**, **Claude**, or another AI coding assistant, the repository
+includes guidance files designed for AI-assisted workflows:
+
+- ``docs/SKILL.md`` — comprehensive usage guidance and tutorial flow
+- ``agents.md`` — concise agent instructions (if present)
+
+You can point your AI assistant to these files or ask it to follow them when
+guiding you through ``pydfc``.
+
+**Example prompt:**
+
+::
+
+    Use the instructions in docs/SKILL.md to guide me through a minimal PydFC workflow.
+
+Using Any LLM Chat (Copy-Paste Method)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you do not use Copilot, Codex, or Claude, you can still benefit from AI guidance.
+
+**Steps:**
+
+1. Open ``docs/SKILL.md``.
+2. Copy its contents.
+3. Paste it into your preferred LLM chat (e.g., ChatGPT, Claude, Gemini).
+4. Ask questions such as:
+
+   - "Guide me through the state-free quickstart."
+   - "Which dFC method should I use for my dataset?"
+   - "Generate a minimal Sliding Window example."
+
+This provides a portable, copy-paste tutorial experience.
+
+Notes on Privacy and Offline Use
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- The AI-assisted workflows described above operate within your chosen AI environment.
+- No data is sent by **pydfc** itself.
+- Users working with sensitive data should follow their institutional policies
+  when using external AI services.
+
+Recommended First Step
+~~~~~~~~~~~~~~~~~~~~~~
 
-The ``dFC_methods_demo.ipynb`` illustrates how to load data and apply each of the dFC methods implemented in the ``pydfc`` toolbox individually.
-The ``multi_analysis_demo.ipynb`` illustrates how to use the ``pydfc`` toolbox to apply multiple dFC methods at the same time on a dataset and compare their results.
+If you are new to **pydfc**, we recommend starting with:
 
-For more details about the implemented methods and the comparison analysis see `our paper <https://doi.org/10.1093/gigascience/giae009>`_.
+1. ``examples/dFC_methods_demo.py``
+2. The Copilot prompt ``/02_state_free_quickstart`` (if available)
+3. Or the copy-paste method using ``docs/SKILL.md``
 
-  * Mohammad Torabi, Georgios D Mitsis, Jean-Baptiste Poline, On the variability of dynamic functional connectivity assessment methods, GigaScience, Volume 13, 2024, giae009, https://doi.org/10.1093/gigascience/giae009.
+This optional AI-assisted workflow is designed to complement — not replace —
+the documentation and example scripts.

agents.md

@@ -0,0 +1,11 @@
+# PydFC Codex Agent Instructions
+
+Follow the guidance in `docs/SKILL.md`.
+
+Goals:
+- help users install PydFC
+- guide demo workflows
+- provide copy-paste examples
+- do not modify source code unless explicitly requested
+
+Use README and demo notebook as source of truth.