# dylansutterlin/isc_hypnotic_suggestions architecture

> Architecture diagram of the GitHub repository dylansutterlin/isc_hypnotic_suggestions, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dylansutterlin/isc_hypnotic_suggestions
- Repository: https://github.com/dylansutterlin/isc_hypnotic_suggestions

## Overview

ISC_hypnotic_suggestions is a research codebase for analyzing intersubject fMRI responses to verbal hypnotic suggestions, including pain-modulation comparisons. Its main workflow configures an experiment, prepares or loads fMRI time series, extracts atlas-based signals, computes ISC and related statistics, then saves and visualizes results. Separate scripts cover first-level GLM, behavioral association/RSA, and multivariate analyses. The graph reflects documented capabilities and sampled code; some links are omitted where excerpts do not establish runtime wiring.

Main entry points: [`scripts/main_isc.py`](https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/scripts/main_isc.py) (ISC analysis runner), [`scripts/preproc_timeseries.py`](https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/scripts/preproc_timeseries.py) (Time-series preprocessing), [`scripts/run_glm.py`](https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/scripts/run_glm.py) (First-level GLM), [`src/isc_utils.py`](https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/src/isc_utils.py) (ISC utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_config["Experiment configuration"]
  node_setup["Experiment setup<br/>[setup_base.py]"]
  node_setup_variants["Analysis setups"]
end

subgraph group_fmri["fMRI preparation"]
  node_preproc["Time-series preprocessing"]
  node_glm["First-level GLM<br/>[run_glm.py]"]
  node_qc["Quality control<br/>[qc_utils.py]"]
  node_atlas["Atlas and ROI tools<br/>[Atlas_class.py]"]
  node_glm_utils["GLM utilities<br/>[glm_utils.py]"]
end

subgraph group_analysis["Similarity analyses"]
  node_isc_runner["ISC analysis runner<br/>[main_isc.py]"]
  node_isc_utils["ISC utilities<br/>[isc_utils.py]"]
  node_iscf["ISFC analysis<br/>[main_isc.py]"]
  node_permutation["Permutation tests<br/>[main_isc.py]"]
end

subgraph group_behavior["Behavioral and MVPA"]
  node_behavior_prep["Behavioral preparation<br/>[preproc_utils.py]"]
  node_rsa["ISC-RSA analysis"]
  node_mvpa["MVPA and RSA<br/>[rsa_isc_mvpa.py]"]
end

subgraph group_outputs["Results and visualization"]
  node_results["Analysis results"]
  node_isc_visuals["ISC visualization"]
  node_rsa_visuals["RSA visualization"]
  node_perm_visuals["Permutation visualization<br/>[visu_perm.py]"]
end

node_researcher(("Researcher"))
node_fmriprep_data["Preprocessed fMRI"]
node_behavior_data["Behavioral measures"]

node_researcher -->|"selects setup"| node_setup_variants
node_setup_variants -->|"configures"| node_setup
node_researcher -->|"runs analysis"| node_isc_runner
node_setup -->|"controls options"| node_isc_runner
node_fmriprep_data -->|"provides scans"| node_preproc
node_preproc -->|"saves time series"| node_results
node_preproc -->|"checks data"| node_qc
node_fmriprep_data -->|"provides scans"| node_glm
node_glm -->|"uses"| node_glm_utils
node_glm -->|"saves contrasts"| node_results
node_isc_runner -->|"extracts ROI signals"| node_atlas
node_isc_runner -->|"computes ISC"| node_isc_utils
node_isc_runner -->|"saves analyses"| node_results
node_isc_runner -.->|"runs optionally"| node_iscf
node_isc_runner -->|"runs tests"| node_permutation
node_behavior_data -->|"provides measures"| node_behavior_prep
node_rsa -->|"loads measures"| node_behavior_prep
node_rsa -->|"computes similarity"| node_isc_utils
node_mvpa -->|"uses metrics"| node_isc_utils
node_results -->|"loads ISC results"| node_isc_visuals
node_results -->|"loads RSA results"| node_rsa_visuals
node_results -->|"loads test results"| node_perm_visuals
node_isc_visuals -->|"saves figures"| node_results
node_rsa_visuals -->|"saves figures"| node_results
node_perm_visuals -->|"saves maps"| node_results

click node_setup "https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/setups/setup_base.py"
click node_setup_variants "https://github.com/dylansutterlin/isc_hypnotic_suggestions/tree/main/setups"
click node_preproc "https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/scripts/preproc_timeseries.py"
click node_glm "https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/scripts/run_glm.py"
click node_qc "https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/src/qc_utils.py"
click node_atlas "https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/src/Atlas_class.py"
click node_isc_runner "https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/scripts/main_isc.py"
click node_isc_utils "https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/src/isc_utils.py"
click node_iscf "https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/scripts/main_isc.py"
click node_permutation "https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/scripts/main_isc.py"
click node_glm_utils "https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/src/glm_utils.py"
click node_behavior_prep "https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/src/preproc_utils.py"
click node_rsa "https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/scripts/rsa-isc_ext_model.py"
click node_mvpa "https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/scripts/rsa_isc_mvpa.py"
click node_isc_visuals "https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/scripts/visualization_isc.py"
click node_rsa_visuals "https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/visu_scripts/visu_rsa-isc_ext_model.py"
click node_perm_visuals "https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/visu_perm.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_setup,node_setup_variants toneBlue
class node_preproc,node_glm,node_qc,node_atlas,node_glm_utils toneAmber
class node_isc_runner,node_isc_utils,node_iscf,node_permutation toneMint
class node_behavior_prep,node_rsa,node_mvpa toneRose
class node_results,node_isc_visuals,node_rsa_visuals,node_perm_visuals,node_researcher,node_fmriprep_data,node_behavior_data toneIndigo
```

## Components

### Experiment configuration

- [Experiment setup](https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/setups/setup_base.py): `setups/setup_base.py`
- [Analysis setups](https://github.com/dylansutterlin/isc_hypnotic_suggestions/tree/main/setups): `setups`

### fMRI preparation

- [Time-series preprocessing](https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/scripts/preproc_timeseries.py): `scripts/preproc_timeseries.py`
- [First-level GLM](https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/scripts/run_glm.py): `scripts/run_glm.py`
- [Quality control](https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/src/qc_utils.py): `src/qc_utils.py`
- [Atlas and ROI tools](https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/src/Atlas_class.py): `src/Atlas_class.py`
- [GLM utilities](https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/src/glm_utils.py): `src/glm_utils.py`

### Similarity analyses

- [ISC analysis runner](https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/scripts/main_isc.py): `scripts/main_isc.py`
- [ISC utilities](https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/src/isc_utils.py): `src/isc_utils.py`
- [ISFC analysis](https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/scripts/main_isc.py): `scripts/main_isc.py`
- [Permutation tests](https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/scripts/main_isc.py): `scripts/main_isc.py`

### Behavioral and MVPA

- [Behavioral preparation](https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/src/preproc_utils.py): `src/preproc_utils.py`
- [ISC-RSA analysis](https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/scripts/rsa-isc_ext_model.py): `scripts/rsa-isc_ext_model.py`
- [MVPA and RSA](https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/scripts/rsa_isc_mvpa.py): `scripts/rsa_isc_mvpa.py`

### Results and visualization

- **Analysis results**
- [ISC visualization](https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/scripts/visualization_isc.py): `scripts/visualization_isc.py`
- [RSA visualization](https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/visu_scripts/visu_rsa-isc_ext_model.py): `visu_scripts/visu_rsa-isc_ext_model.py`
- [Permutation visualization](https://github.com/dylansutterlin/isc_hypnotic_suggestions/blob/main/visu_perm.py): `visu_perm.py`

### Other components

- **Researcher**
- **Preprocessed fMRI**
- **Behavioral measures**

## Connections

- Researcher → Analysis setups: selects setup
- Analysis setups → Experiment setup: configures
- Researcher → ISC analysis runner: runs analysis
- Experiment setup → ISC analysis runner: controls options
- Preprocessed fMRI → Time-series preprocessing: provides scans
- Time-series preprocessing → Analysis results: saves time series
- Time-series preprocessing → Quality control: checks data
- Preprocessed fMRI → First-level GLM: provides scans
- First-level GLM → GLM utilities: uses
- First-level GLM → Analysis results: saves contrasts
- ISC analysis runner → Atlas and ROI tools: extracts ROI signals
- ISC analysis runner → ISC utilities: computes ISC
- ISC analysis runner → Analysis results: saves analyses
- ISC analysis runner → ISFC analysis: runs optionally
- ISC analysis runner → Permutation tests: runs tests
- Behavioral measures → Behavioral preparation: provides measures
- ISC-RSA analysis → Behavioral preparation: loads measures
- ISC-RSA analysis → ISC utilities: computes similarity
- MVPA and RSA → ISC utilities: uses metrics
- Analysis results → ISC visualization: loads ISC results
- Analysis results → RSA visualization: loads RSA results
- Analysis results → Permutation visualization: loads test results
- ISC visualization → Analysis results: saves figures
- RSA visualization → Analysis results: saves figures
- Permutation visualization → Analysis results: saves maps