diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 76fc799..6bfefd9 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -10,6 +10,24 @@ You are assisting users with the **PydFC** Python toolbox for dynamic functional - Use parameters from `examples/dFC_methods_demo.py` unless the user asks to customize. - If unsure, recommend the **Sliding Window (SW)** method first. +## Context + +Refer to `docs/DFC_METHODS_CONTEXT.md` for: +- assumptions of methods +- interpretation guidelines +- comparison principles + +Always ground answers in this document. + +Also use `docs/PAPER_KNOWLEDGE_BASE.md` as paper-grounded context for assumptions, implementation details, and method tradeoffs. + +## Deep Mode + +When user asks about methods: +- Explain assumptions +- Explain expected behavior +- Avoid oversimplified answers + ## Safety Rule Do NOT modify source code in this repository unless the user explicitly asks for a code change or pull request. @@ -45,3 +63,16 @@ When guiding a new user: - `README.rst` → installation - `examples/dFC_methods_demo.py` → demo workflow - `docs/SKILL.md` → detailed guidance +- `docs/DFC_METHODS_CONTEXT.md` → assumptions, interpretation, comparison principles +- `docs/PAPER_KNOWLEDGE_BASE.md` → paper-derived implementation details and pros/cons + +## Citation and Attribution + +Content in this repository is derived from: + +Torabi et al., 2024 +On the variability of dynamic functional connectivity assessment methods +GigaScience +https://doi.org/10.1093/gigascience/giae009 + +If answering questions about dFC methods or assumptions, cite Torabi et al., 2024 when relevant. diff --git a/.github/prompts/00_prompts_index.prompt.md b/.github/prompts/00_prompts_index.prompt.md new file mode 100644 index 0000000..f55e122 --- /dev/null +++ b/.github/prompts/00_prompts_index.prompt.md @@ -0,0 +1,52 @@ +# PydFC Prompt Index + +Use this index to select the right prompt for the user intent. + +## Prompt Map + +1. `01_install.prompt.md` +- Use when user needs environment setup and installation. +- Output style: short setup steps and commands. + +2. `02_choose_method.prompt.md` +- Use when user asks which method to choose. +- Asks about data type and analysis goals before recommending. + +3. `03_state_free_quickstart.prompt.md` +- Use for single-subject, fastest-first workflow. +- Focus methods: SW, TF. + +4. `04_state_based_quickstart.prompt.md` +- Use for multi-subject workflows requiring state fitting. +- Focus methods: CAP, SWC, CHMM, DHMM, WINDOWLESS. + +5. `05_paper_method_qa.prompt.md` +- Use for paper-grounded questions on assumptions, implementation details, expected behavior, and pros/cons. +- Best for deep comparison questions. + +6. `06_troubleshoot.prompt.md` +- Use for runtime errors, dependency issues, or confusing output behavior. +- Prioritize non-invasive fixes and parameter adjustments. + +## Shared Grounding Rules + +For method questions, ground answers in: +- `docs/DFC_METHODS_CONTEXT.md` +- `docs/PAPER_KNOWLEDGE_BASE.md` + +Deep mode behavior: +- Explain assumptions +- Explain expected behavior +- Avoid oversimplified answers + +Citation rule: +- If answering questions about dFC methods or assumptions, cite Torabi et al., 2024 when relevant. + +## Suggested Routing + +1. Install first-time users: `01_install.prompt.md` +2. Unsure which method: `02_choose_method.prompt.md` +3. Single-subject quick demo: `03_state_free_quickstart.prompt.md` +4. Multi-subject state analysis: `04_state_based_quickstart.prompt.md` +5. Paper-based conceptual questions: `05_paper_method_qa.prompt.md` +6. Errors or unstable runs: `06_troubleshoot.prompt.md` diff --git a/.github/prompts/01_install.prompt.md b/.github/prompts/01_install.prompt.md index 496d4bc..59be4ca 100644 --- a/.github/prompts/01_install.prompt.md +++ b/.github/prompts/01_install.prompt.md @@ -2,6 +2,12 @@ Guide the user through installing PydFC. +## Context Sources + +Use these when the user asks method or paper questions during setup: +- `docs/DFC_METHODS_CONTEXT.md` +- `docs/PAPER_KNOWLEDGE_BASE.md` + ## Steps 1. Ask whether they use conda or pip. @@ -11,3 +17,8 @@ Guide the user through installing PydFC. conda create --name pydfc_env python=3.11 conda activate pydfc_env pip install pydfc +``` + +3. If they ask which method to start with, recommend SW as the default first run. +4. If they ask method assumptions/pros/cons, ground the answer in the context sources and avoid oversimplified claims. +5. If discussing paper-derived method assumptions, cite Torabi et al., 2024 when relevant. diff --git a/.github/prompts/02_choose_method.prompt.md b/.github/prompts/02_choose_method.prompt.md new file mode 100644 index 0000000..fb49832 --- /dev/null +++ b/.github/prompts/02_choose_method.prompt.md @@ -0,0 +1,40 @@ +# Help Choose a dFC Method + +## Context Sources + +Refer to: +- `docs/DFC_METHODS_CONTEXT.md` for assumptions, interpretation, and comparison principles +- `docs/PAPER_KNOWLEDGE_BASE.md` for paper-grounded implementation details and tradeoffs + +Always ground recommendations in these documents. + +## Deep Mode + +When user asks about methods: +- Explain assumptions +- Explain expected behavior +- Avoid oversimplified answers + +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 + +## Response Rules + +1. Explain why each suggested method fits the user goal. +2. For method comparisons, lead with assumptions and likely behavioral differences. +3. Do not claim there is a universally best method. +4. Cite Torabi et al., 2024 when using paper-derived assumptions or tradeoffs. diff --git a/.github/prompts/02_state_free_quickstart.prompt.md b/.github/prompts/02_state_free_quickstart.prompt.md deleted file mode 100644 index 2b80ad7..0000000 --- a/.github/prompts/02_state_free_quickstart.prompt.md +++ /dev/null @@ -1,12 +0,0 @@ -# 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 diff --git a/.github/prompts/03_state_based_quickstart.prompt.md b/.github/prompts/03_state_based_quickstart.prompt.md deleted file mode 100644 index 463d1ff..0000000 --- a/.github/prompts/03_state_based_quickstart.prompt.md +++ /dev/null @@ -1,18 +0,0 @@ -# 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. diff --git a/.github/prompts/03_state_free_quickstart.prompt.md b/.github/prompts/03_state_free_quickstart.prompt.md new file mode 100644 index 0000000..c8bd204 --- /dev/null +++ b/.github/prompts/03_state_free_quickstart.prompt.md @@ -0,0 +1,32 @@ +# State-Free Quickstart (Single Subject) + +Guide the user through the fastest way to run PydFC. + +## Context Sources + +Refer to: +- `docs/DFC_METHODS_CONTEXT.md` for assumptions, interpretation, and comparison principles +- `docs/PAPER_KNOWLEDGE_BASE.md` for paper-grounded implementation details and tradeoffs + +Always ground method explanations in these documents. + +## Deep Mode + +When user asks about methods: +- Explain assumptions +- Explain expected behavior +- Avoid oversimplified answers + +## 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 +``` + +3. Show minimal loading code for `BOLD` and ask whether they want SW or TF. +4. If the user asks SW vs TF, explain assumptions and expected behavior from the context sources. +5. Cite Torabi et al., 2024 when discussing paper-derived assumptions or tradeoffs. diff --git a/.github/prompts/04_choose_method.prompt.md b/.github/prompts/04_choose_method.prompt.md deleted file mode 100644 index 723c6c9..0000000 --- a/.github/prompts/04_choose_method.prompt.md +++ /dev/null @@ -1,20 +0,0 @@ -# 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. diff --git a/.github/prompts/04_state_based_quickstart.prompt.md b/.github/prompts/04_state_based_quickstart.prompt.md new file mode 100644 index 0000000..6072b53 --- /dev/null +++ b/.github/prompts/04_state_based_quickstart.prompt.md @@ -0,0 +1,39 @@ +# State-Based Quickstart (Multi-Subject) + +Guide the user through state-based analysis. + +## Context Sources + +Refer to: +- `docs/DFC_METHODS_CONTEXT.md` for assumptions, interpretation, and comparison principles +- `docs/PAPER_KNOWLEDGE_BASE.md` for paper-grounded implementation details and tradeoffs + +Always ground method explanations in these documents. + +## Deep Mode + +When user asks about methods: +- Explain assumptions +- Explain expected behavior +- Avoid oversimplified answers + +## 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. + +## Method Guidance Rules + +1. Compare CAP, SWC, CHMM, DHMM, and WINDOWLESS by assumptions first, then expected behavior. +2. Do not claim one method is universally best. +3. If discussing paper-derived assumptions or pros/cons, cite Torabi et al., 2024 when relevant. diff --git a/.github/prompts/05_paper_method_qa.prompt.md b/.github/prompts/05_paper_method_qa.prompt.md new file mode 100644 index 0000000..a243bd7 --- /dev/null +++ b/.github/prompts/05_paper_method_qa.prompt.md @@ -0,0 +1,38 @@ +# Paper-Grounded dFC Methods Q&A (Deep Mode) + +Use this prompt when the user asks questions from/about the paper, including implementation details, assumptions, expected behavior, and pros/cons of dFC methods. + +## Required Context Sources + +Always use: +- `docs/DFC_METHODS_CONTEXT.md` +- `docs/PAPER_KNOWLEDGE_BASE.md` + +## Core Behavior + +1. Answer with paper-grounded reasoning. +2. Explain method assumptions explicitly before conclusions. +3. Explain expected behavior and likely differences across methods. +4. Avoid oversimplified statements and avoid claiming one method is universally best. +5. If user asks for comparison, organize by: + - assumptions + - expected behavior + - pros/cons + - implications for interpretation + +## Preferred Response Pattern + +1. Briefly restate the user's method question. +2. State assumptions for each method involved. +3. Explain expected behavior and what disagreements across methods mean. +4. Give practical recommendation conditioned on the user's analysis goal. +5. Add citation when relevant. + +## Citation Rule + +If answering questions about dFC methods or assumptions, cite: + +Torabi et al., 2024 +On the variability of dynamic functional connectivity assessment methods +GigaScience +https://doi.org/10.1093/gigascience/giae009 diff --git a/.github/prompts/05_troubleshoot.prompt.md b/.github/prompts/06_troubleshoot.prompt.md similarity index 50% rename from .github/prompts/05_troubleshoot.prompt.md rename to .github/prompts/06_troubleshoot.prompt.md index a6fa439..e4c69b9 100644 --- a/.github/prompts/05_troubleshoot.prompt.md +++ b/.github/prompts/06_troubleshoot.prompt.md @@ -1,5 +1,11 @@ # Troubleshooting PydFC +## Context Sources + +If troubleshooting includes method behavior/assumption confusion, refer to: +- `docs/DFC_METHODS_CONTEXT.md` +- `docs/PAPER_KNOWLEDGE_BASE.md` + If the user reports an error: 1. Ask for full traceback. @@ -14,3 +20,5 @@ If the user reports an error: - adjust parameters Do NOT suggest editing source code. + +If the issue is conceptual (for example, why two methods disagree), explain assumptions and expected behavior differences and cite Torabi et al., 2024 when relevant. diff --git a/README.rst b/README.rst index 3e394fb..e774b97 100644 --- a/README.rst +++ b/README.rst @@ -50,6 +50,12 @@ In addition to the example scripts and documentation, **pydfc** provides optiona AI-assisted learning workflows that can help you explore the toolbox, understand dynamic functional connectivity methods, and generate minimal working examples. +If you are unsure which dFC method fits your analysis, or you are not sure how to +start your journey with dFC assessment, we highly encourage trying the AI-assisted +tutorial experience. It is designed to combine guidance from both the codebase and +our paper, so you can move from first steps to informed method choices with more +confidence. + These options are entirely optional and do not affect the core functionality of the toolbox. Using GitHub Copilot Prompts @@ -59,23 +65,44 @@ 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. +The prompt set now includes a **paper-grounded deep mode** for method questions, +so users can ask about assumptions, implementation details, expected behavior, +and pros/cons with answers grounded in: + +- ``docs/DFC_METHODS_CONTEXT.md`` +- ``docs/PAPER_KNOWLEDGE_BASE.md`` + **How to use:** 1. Open the repository in VS Code. 2. Open *Copilot Chat*. -3. Run one of the available prompts, for example:: +3. Type ``/`` and run one of the available prompts:: + /00_prompts_index /01_install - /02_state_free_quickstart - /03_state_based_quickstart - /04_choose_method - /05_troubleshoot + /02_choose_method + /03_state_free_quickstart + /04_state_based_quickstart + /05_paper_method_qa + /06_troubleshoot + +4. Start with ``/00_prompts_index`` if you want a fast routing guide to choose + the best prompt for your goal. + +**What is new in this prompt experience:** + +- ``/02_choose_method`` now appears right after install, so users can pick a + method path early. +- ``/05_paper_method_qa`` is dedicated to paper-based method Q&A. +- ``/06_troubleshoot`` is now the final step in the sequence. +- Method answers are configured for deeper, assumption-first explanations and + include citation guidance for Torabi et al., 2024 when relevant. 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. +If you have Copilot access, we strongly recommend this interactive path for a +friendly and practical onboarding experience. Using Codex, Claude, or Other AI Coding Assistants ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -85,6 +112,10 @@ includes guidance files designed for AI-assisted workflows: - ``docs/SKILL.md`` — comprehensive usage guidance and tutorial flow - ``agents.md`` — concise agent instructions (if present) +- ``docs/DFC_METHODS_CONTEXT.md`` — assumptions, interpretation, and method + comparison principles +- ``docs/PAPER_KNOWLEDGE_BASE.md`` — paper-grounded implementation notes, + expected behavior, and pros/cons You can point your AI assistant to these files or ask it to follow them when guiding you through ``pydfc``. @@ -127,8 +158,10 @@ Recommended First Step If you are new to **pydfc**, we recommend starting with: 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`` +2. The Copilot prompt ``/00_prompts_index`` to pick your path quickly +3. The Copilot prompt ``/02_choose_method`` followed by + ``/03_state_free_quickstart`` (if available) +4. Or the copy-paste method using ``docs/SKILL.md`` This optional AI-assisted workflow is designed to complement — not replace — the documentation and example scripts. diff --git a/agents.md b/agents.md index dce14db..5f3eec5 100644 --- a/agents.md +++ b/agents.md @@ -8,4 +8,34 @@ Goals: - provide copy-paste examples - do not modify source code unless explicitly requested +## Context + +Refer to `docs/DFC_METHODS_CONTEXT.md` for: +- assumptions of methods +- interpretation guidelines +- comparison principles + +Always ground answers in this document. + +Also use `docs/PAPER_KNOWLEDGE_BASE.md` as paper-grounded context. + +## Deep Mode + +When user asks about methods: +- Explain assumptions +- Explain expected behavior +- Avoid oversimplified answers + Use README and demo notebook as source of truth. + +## Citation and Attribution + +Content in this repository is derived from: + +Torabi et al., 2024 +On the variability of dynamic functional connectivity assessment methods +GigaScience +https://doi.org/10.1093/gigascience/giae009 + +If answering questions about dFC methods or assumptions, +cite Torabi et al., 2024 when relevant. diff --git a/docs/DFC_METHODS_CONTEXT.md b/docs/DFC_METHODS_CONTEXT.md new file mode 100644 index 0000000..c866774 --- /dev/null +++ b/docs/DFC_METHODS_CONTEXT.md @@ -0,0 +1,273 @@ +# Dynamic Functional Connectivity (dFC) Methods — Context & Guidance + +## 📌 Source + +This document summarizes the methodology, assumptions, and findings from: + +**Torabi et al., 2024 — "On the variability of dynamic functional connectivity assessment methods"** +(See paper: https://doi.org/10.1093/gigascience/giae009) + +--- + +## 🧠 Core Concept + +Dynamic Functional Connectivity (dFC) measures how functional connectivity between brain regions evolves over time using fMRI BOLD signals. + +⚠️ Key challenge: +There is **no ground truth**, and results depend heavily on the chosen method. + +--- + +## 🚨 Key Insight (VERY IMPORTANT) + +* Variability across dFC methods is **comparable to variability over time or across subjects** +* Therefore: + +> ⚠️ Method choice can affect results as much as the biological signal itself + +--- + +## 🧩 Method Taxonomy + +### 1. State-Free Methods + +* Sliding Window (SW) +* Time-Frequency (TF) + +**Characteristics:** + +* Continuous estimation of FC +* No assumption of discrete states +* Capture subject-specific variability + +**Pros:** + +* Flexible +* High temporal resolution (TF especially) + +**Cons:** + +* Sensitive to noise +* No explicit state structure + +--- + +### 2. State-Based Methods (Temporal Models) + +* Clustering +* Continuous HMM (CHMM) +* Discrete HMM (DHMM) + +**Characteristics:** + +* Assume recurring FC states +* Model temporal transitions + +**Pros:** + +* Capture temporal dependencies +* Interpretable state transitions + +**Cons:** + +* Strong assumptions (number of states, Markovian structure) +* Smoother dynamics (may miss fast changes) + +--- + +### 3. State-Based Methods (Non-Temporal / Instantaneous) + +* CAP +* Window-less (dictionary learning) + +**Characteristics:** + +* No temporal ordering assumption +* Allow instantaneous reconfiguration + +**Pros:** + +* Capture rapid changes +* Fewer temporal constraints + +**Cons:** + +* Ignore temporal continuity +* May be less physiologically realistic + +--- + +## 🔬 Fundamental Assumptions Across Methods + +| Assumption | Methods | +| ------------------------- | ------------------------ | +| Local temporal dependency | SW, TF, Clustering, HMM | +| Temporal ordering matters | SW, TF, Clustering, HMM | +| Discrete states exist | CAP, Clustering, HMM, WL | +| Smooth transitions | HMM only | +| No temporal structure | CAP, WL | + +--- + +## 📊 Key Empirical Findings + +### 1. Methods cluster into 3 groups + +* Group A: Clustering, CHMM, DHMM +* Group B: CAP, Window-less +* Group C: Sliding Window, Time-Frequency + +👉 Methods within a group produce **similar results**, but across groups differ strongly. + +--- + +### 2. Spatial vs Temporal Behavior + +* Spatial patterns → relatively consistent across methods +* Temporal dynamics → **much less consistent** + +👉 Interpretation: + +> Methods agree on *what networks look like*, but not *when they occur* + +--- + +### 3. Analytical Flexibility Problem + +Most studies: + +* Use **only one method** +* Do not justify method choice + +👉 This is a major limitation in the field. + +--- + +## 🧠 Recommended Usage Principles + +### ✅ 1. Encourage using multiple methods + +At least one from each group: + +* Temporal model (e.g., HMM) +* Instantaneous model (e.g., CAP) +* Continuous model (e.g., TF or SW) + +--- + +### ✅ 2. Interpret results conditional on assumptions + +Example: + +* If method assumes smooth transitions → expect slower dynamics +* If method ignores temporal order → expect rapid switching + +--- + +### ✅ 3. Do NOT compare results naively across methods + +Different methods: + +* Produce different distributions +* Have different output formats +* Encode different statistical orders (1st vs 2nd) + +--- + +### ✅ 4. Be explicit about: + +* Number of states (for. SWC, CAP, CHMM, DHMM, WL) +* Window size (for SW, SWC, DHMM) +* Frequency scales (for TF) +* Model type (for HMM) + +--- + +## 🤖 Guidance for LLM / Copilot Agents + +When answering user questions: + +### 1. Always clarify: + +* Which method is being used +* What assumptions it implies + +--- + +### 2. When comparing methods: + +* Highlight assumption differences +* Explain expected differences in results + +--- + +### 3. When user asks "which method is better": + +Respond with: + +> There is no universally best method — different methods capture different aspects of dFC. + +--- + +### 4. When user analyzes results: + +Encourage: + +* Multi-method validation +* Cross-method consistency checks + +--- + +### 5. When generating code or pipelines: + +Ensure: + +* Method assumptions are documented +* Hyperparameters are exposed +* Results are comparable across methods + +--- + +## ⚠️ Common Misinterpretations + +❌ “dFC patterns are ground truth representations” +✔ They are **method-dependent estimates** + +❌ “Different methods should agree” +✔ Disagreement is expected and informative + +❌ “Higher accuracy = better method” +✔ Depends on what aspect of dFC is captured and your question + +--- + +## 🧪 Role of PydFC + +PydFC enables: + +* easy use and implementation of a variety of dFC methods +* Multi-method analysis +* Standardized comparison +* Exploration of analytical flexibility + +👉 It is designed to **prevent single-method bias** + +--- + +## 📚 Citation Requirement + +If this knowledge is used: + +> Always cite: +> Torabi et al., 2024 — On the variability of dynamic functional connectivity assessment methods + +--- + +## 🔚 Summary + +* dFC is highly method-dependent +* No single method captures full dynamics +* Multi-analysis is essential +* Interpretation must consider assumptions + +--- diff --git a/docs/PAPER_KNOWLEDGE_BASE.md b/docs/PAPER_KNOWLEDGE_BASE.md new file mode 100644 index 0000000..7eca81c --- /dev/null +++ b/docs/PAPER_KNOWLEDGE_BASE.md @@ -0,0 +1,85 @@ +# Paper Knowledge Base for dFC Method Guidance + +## Source Paper + +Torabi et al., 2024 +On the variability of dynamic functional connectivity assessment methods +GigaScience +https://doi.org/10.1093/gigascience/giae009 + +## Copyright and Attribution + +Content in this repository is derived from: + +Torabi et al., 2024 +On the variability of dynamic functional connectivity assessment methods +GigaScience +https://doi.org/10.1093/gigascience/giae009 + +## Purpose + +Use this document as a paper-grounded knowledge base for answering questions about dynamic functional connectivity (dFC) methods, assumptions, expected behavior, and interpretation. + +## Method Families + +1. State-free: Sliding Window (SW), Time-Frequency (TF) +2. State-based temporal: Clustering, Continuous HMM (CHMM), Discrete HMM (DHMM) +3. State-based non-temporal/instantaneous: CAP, Window-less (WL) + +## Assumptions by Family + +1. State-free methods: +- assume local temporal structure in short windows or frequency bands +- do not impose a discrete-state model by default + +2. State-based temporal methods: +- assume recurring FC states +- assume temporal transitions are informative +- HMM variants assume Markovian transition dynamics + +3. State-based non-temporal methods: +- assume recurring patterns/states can be extracted without strong temporal continuity constraints +- emphasize instantaneous configuration changes + +## Expected Behavior + +1. SW/TF typically provide continuous time-varying FC estimates and may be more sensitive to fast changes and noise. +2. Temporal state models (Clustering/HMM) often provide smoother, state-structured trajectories and clearer transition summaries. +3. CAP/WL can reveal rapid reconfiguration patterns but may not encode temporal continuity explicitly. + +## Pros and Cons (Paper-Grounded) + +1. State-free (SW/TF) +- Pros: flexible continuous tracking, useful for temporal detail +- Cons: sensitivity to parameter choices and noise, no explicit state-transition model + +2. State-based temporal (Clustering/HMM) +- Pros: interpretable state sequences and transitions, captures recurring organization +- Cons: stronger modeling assumptions (state count, transition model), may smooth out fast events + +3. State-based non-temporal (CAP/WL) +- Pros: can capture abrupt or instantaneous reconfiguration, fewer temporal constraints +- Cons: weaker temporal continuity modeling + +## Comparison Principles + +1. No universally best dFC method; each captures different aspects of dynamics. +2. Cross-method differences are expected and informative, not necessarily errors. +3. Method-driven variability can be comparable to temporal or between-subject variability. +4. Interpret findings conditional on assumptions and hyperparameters. + +## LLM Grounding Rules + +When answering questions about dFC methods: + +1. Ground explanations in `docs/DFC_METHODS_CONTEXT.md` and this file. +2. State assumptions before conclusions. +3. Explain expected behavior and likely differences across methods. +4. Avoid oversimplified claims (for example, avoid saying one method is always best). +5. Cite Torabi et al., 2024 when relevant. + +## Suggested Citation Language + +If answering questions about dFC methods or assumptions, cite: + +Torabi et al., 2024. On the variability of dynamic functional connectivity assessment methods. GigaScience. https://doi.org/10.1093/gigascience/giae009 diff --git a/docs/SKILL.md b/docs/SKILL.md index 8e762b9..d8867da 100644 --- a/docs/SKILL.md +++ b/docs/SKILL.md @@ -29,6 +29,24 @@ Help the user: Keep the interaction simple and copy-paste oriented. +## Context + +Refer to `docs/DFC_METHODS_CONTEXT.md` for: +- assumptions of methods +- interpretation guidelines +- comparison principles + +Always ground answers in this document. + +Also use `docs/PAPER_KNOWLEDGE_BASE.md` for paper-based implementation details, assumptions, and pros/cons. + +## Deep Mode + +When user asks about methods: +- Explain assumptions +- Explain expected behavior +- Avoid oversimplified answers + ## Interaction Flow Follow this sequence: @@ -49,6 +67,19 @@ Follow this sequence: - `README.rst` for install commands - `examples/dFC_methods_demo.py` for data download and method examples +- `docs/DFC_METHODS_CONTEXT.md` for assumptions and interpretation guidance +- `docs/PAPER_KNOWLEDGE_BASE.md` for paper-grounded method tradeoffs + +## Citation and Attribution + +Content in this repository is derived from: + +Torabi et al., 2024 +On the variability of dynamic functional connectivity assessment methods +GigaScience +https://doi.org/10.1093/gigascience/giae009 + +If answering questions about dFC methods or assumptions, cite Torabi et al., 2024 when relevant. ## Installation (from README)