Skip to content

About

This repository contains the analysis pipeline used in the publication "From Perception to Appraisal: Hierarchical Responses to Natural and Built Features in Urban Environments" (Zähme et al., 2025)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

From Perception to Appraisal: Brain Responses to Natural and Built Features in Urban Environments (Zaehme et al., 2026) -- Analysis Scripts

Low-level features example Segmentation overlay example

This repository contains the analysis pipeline used in the publication "From Perception to Appraisal: Brain Responses to Natural and Built Features in Urban Environments" for investigating neural correlates of urban environment perception using EEG event-related potentials (ERPs), low-level visual features, and subjective ratings.

Overview

This project contains scripts for:

  • Preprocessing EEG data: Preprocessing pipeline (using BeMoBIL pipeline) plus extraction of Event-related potentials (P1, N1, P300, LPP)
  • Extracting Visual features of Urban Scenes: Low-level features and semantic segmentation
  • Statistical analysis: Linear mixed-effects models (LMMs) examining relationships between neural, visual, and subjective measures

Repository Structure

perception2appraisal_analyses/
├── README.md                           
├── llvf_example.png                    # Example low-level feature visualization
├── segmentations_overlay_example.png   # Example segmentation overlay
│
├── data/                               # Processed data files (zipped)
│   ├── llvfs.zip                       # Pre-extracted low-level visual features
│   ├── peaks.zip                       # Per-stimulus ERP peak amplitudes by electrode
│   ├── segmentation.zip                # Semantic segmentation results
│   └── subjective_ratings.zip          # Participant ratings
│
├── EEG_preprocessing/                  # MATLAB preprocessing pipeline for EEG data
│   ├── bemobil_pipeline.m              # Core BeMoBIL preprocessing
│   ├── EEG_Preprocessing_Zaehmeetal.m  # Main preprocessing script
│   ├── README.md                       # Detailed preprocessing documentation
│   ├── config/                         # Configuration files
│   │   ├── eventsStimScale.mat         # Event Names
│   │   └── ua_config.m                 # BeMoBIL pipeline config file
│   └── functions/                      # Custom MATLAB functions
│       ├── eeglab_parse_key_val.m     
│       ├── exportERPs.m
│       ├── extractAndSaveAverages.m
│       └── extractAndSavePeaks.m
│
├── image_feature_extraction/           # Visual feature extraction (Python)
│   ├── low_level_features_berman.ipynb # Low-level visual feature extraction
│   ├── depth.ipynb                     # Depth estimation analysis
│   ├── segmentation.ipynb              # Semantic segmentation notebook
│   ├── segmentation_ade.py             # SegFormer ADE20K inference script
│   ├── utils.py                        # Shared utility functions
│   ├── requirements.txt                # Python dependencies
│   └── segmentation_evaluation/        # IoU-based segmentation quality evaluation
│       ├── IoU.py                      # Intersection-over-Union computation
│       ├── IoU_visualization.py        # IoU result visualization
│       ├── brush_strokes/              # Manual rater annotations (Rater1/, Rater2/)
│       ├── config/                     # Rater task configuration (JSON)
│       └── images/                     # Reference images for evaluation
│
└── statistical_analyses/               # R statistical analysis scripts
    ├── 01_data_preparation.R           # Data merging and cleaning
    ├── 02_lme_semseg_llvf.R           # LMMs for ratings ~ visual features
    └── 03_lme_erp_subj.R              # LMMs for ratings~erp relationships

Getting Started

Prerequisites

For Python Analysis (Visual Features)

  • Python 3.13.3 (see requirements.txt for all dependencies)
  • Key packages: PyTorch, torchvision, transformers, scikit-image, pandas, numpy

For MATLAB Preprocessing (EEG)

For R Statistical Analysis

  • R (4.0 or later)
  • Packages: dplyr, readr, readxl, tidyr, lme4, lmerTest

Data

  • Raw EEG data in BIDS format can be downloaded from the corresponding OpenNeuro repository. Analysis-ready datasets are included in the repository under 'statistical_analyses/prepared_data/'

Installation

  1. Clone the repository:

    git clone https://github.com/BeMoBIL/neurourbanism.git
    cd neurourbanism
  2. Set up Python environment:

    # Create virtual environment (optional but recommended)
    python -m venv venv
    source venv/bin/activate  # On Windows: venv\Scripts\activate
    
    # Install dependencies
    pip install -r requirements.txt
  3. Set up MATLAB environment:

    • Install EEGLAB and BeMoBIL Pipeline
    • Update paths in EEG_preprocessing/config/ua_config.m
    • See EEG_preprocessing/README.md for detailed instructions
  4. Set up R environment:

    # Install required packages
    install.packages(c("dplyr", "readr", "readxl", "tidyr", "lme4", "lmerTest"))

Workflow

1. EEG Preprocessing (MATLAB)

The raw EEG data (BIDS format, available on OpenNeuro: ds006850) is preprocessed using the BeMoBIL pipeline:

Output: ERP peak amplitudes extracted to data/peaks/*.csv

See EEG_preprocessing/README.md for detailed preprocessing steps.

2. Visual Feature Extraction (Python)

Low-Level Visual Features

Extract edge density, contrast, brightness, and other low-level features:

# Run low_level_features_berman.ipynb
jupyter notebook low_level_features_berman.ipynb

Depth Estimation

Estimate depth maps from urban scene images:

# Run depth.ipynb
jupyter notebook depth.ipynb

Semantic Segmentation

Extract semantic image contents using the SegFormer-B5 model pretrained on the ADE20K dataset.

jupyter notebook segmentation.ipynb

Output: Visual feature matrices ready for statistical analysis (also included pre-calculated in 'statistical_analyses/prepared_data/')

The folder image_feature_extraction/segmentation_evaluation additionaly contains manual labels created by two separate human labelers for a subset of 12 stimulus images. These were created to evaluate the model's performance on the stimulus material used in the study. The folder also contains scripts to calculate and visualize IoU metrics, as well as the 12 images that were used for evaluation.

3. Data Integration and Statistical Analysis (R)

Step 1: Prepare combined dataset

source("statistical_analyses/01_data_preparation.R")

Merges ERP peaks, subjective ratings, sociodemographics, and segmentation data.

Step 2: Analyze visual features

source("statistical_analyses/02_lme_semseg_llvf.R")

Linear mixed-effects models examining relationships between semantic segmentation/low-level features and ERPs.

Step 3: Analyze ERP-subjective relationships

source("statistical_analyses/03_lme_erp_subj.R")

Linear mixed-effects models examining relationships between ERPs and subjective ratings.

Data Description

EEG Data

See OpenNeuro repository for detailed description of dataset.

Subjective Ratings

Participants rated urban scenes on 9 dimensions (Likert scales):

  • SAM Arousal
  • SAM Valence
  • SAM Dominance
  • Beauty (Schönheit)
  • Fascination (Faszination)
  • Hominess (Heimeligkeit)
  • Openness (Offenheit)
  • Safety (Sicherheit)
  • Stress

Citation

This code accompanies the paper:

Zähme et al. (2026). From Perception to Appraisal: Brain Responses to Natural and Built Features in Urban Environments. Under Review.

If you use this code, please cite the paper once published. Preprint: https://doi.org/10.1101/2025.10.31.685763

Related Resources

Contact

For questions or issues, please contact the repository maintainers.


Last updated: April 2026

About

This repository contains the analysis pipeline used in the publication "From Perception to Appraisal: Hierarchical Responses to Natural and Built Features in Urban Environments" (Zähme et al., 2025)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages