# kamitanilab/genericobjectdecoding architecture

> Architecture diagram of the GitHub repository kamitanilab/genericobjectdecoding, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kamitanilab/genericobjectdecoding
- Repository: https://github.com/kamitanilab/genericobjectdecoding

## Overview

##### Project Type and Purpose
- This is an academic/demo repository for “Generic Object Decoding” from fMRI data using hierarchical visual features.
- It provides data organization and two parallel analysis pipelines (Matlab and Python) that replicate experiments from Horikawa & Kamitani (2017).

##### File‐Structure Analysis
- Top‐level:
- code/ (contains two subfolders matlab/ and python/)
- data/ (holds raw & preprocessed fMRI data references, stimulus tables, CNN model definitions)
- docs/ (GitHub Pages site content)
- code/matlab/ uses:
- analysis_*.m scripts for Category Identification, Feature Prediction, Accuracy
- conversion, figure‐export, volume‐export utilities
- lib/ contains two major libraries: SPR_2009_12_17 (sparse regression tools) and mex_prog_2010‐06‐21 (compiled MEX functions)
- code/python/ implements equivalent analyses in Python, plus:
- god_config.py for global settings
- makedata_features.py to assemble feature datasets
- conversion scripts to import Matlab results
- createfigure.py to reproduce publication figures
- data/ holds:
- stimulus tables (.tsv/.csv) and category mappings
- CNN model definitions (Caffe prototxt under data/cnn)
- ImageNet test/training lists and related metadata
- README files in each directory describe dependencies and usage.

##### Architecture Insights from README
- External data sources: OpenNeuro (raw fMRI), Figshare (preprocessed fMRI & image features), private stimulus‐image requests.
- Both pipelines expect the same base data schema and converge on figure‐generation.

##### Main Components
a. Data Layer
- External repositories: OpenNeuro, Figshare, Stimulus‐image server (request form)
- Local data folder: stimulus tables, image URLs, CNN prototxt, category label files
b. Processing Layer
- Matlab Pipeline
– SPR sparse‐regression submodule
– MEX accelerated functions (mex_prog)
– Analysis scripts → decoded feature outputs
- Python Pipeline
– Data‐preparation (makedata_features)
– Analysis scripts mirroring Matlab logic
– Merge & postprocess results, plus figure routines
c. Model Layer
- Hierarchical feature extractor: Caffe “bvlc_reference_caffenet” (data/cnn)
- Feature representations (fc6 activations, etc.)
d. Output Layer
- Decoding results (CSV/MAT files)
- Publication‐quality figures (PNG/PDF)
- Logs & intermediate result files

##### Relationships and Data Flow
- Stimulus tables + fMRI data → both Matlab & Python pipelines
- Caffe model definitions → feature‐extraction subroutines → analysis scripts
- Matlab outputs → conversion script for Python → merged analysis
- Final outputs from either pipeline → createfigure modules → figure files

##### Architectural Patterns & Design Principles
- Modular, language‐parallel pipelines share the same data schema
- Separation of concerns:
- Data ingestion & conversion
- Core decoding algorithms (SPR library / custom scripts)
- Visualization & export
- Reuse of established libraries (SPR_2009, MEX modules, Caffe)
- Extensibility: additional analysis scripts can be plugged into either pipeline

##### Elements
- Clear component names: “SPR_2009 Library,” “MEX Prog Module,” “makedata_features.py,” “Caffe prototxt”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data Layer
    subgraph "External Data"
        EN1["OpenNeuro (raw fMRI)"]:::data
        EN2["Figshare (preprocessed fMRI & image features)"]:::data
        EN3["Stimulus-Image Server"]:::data
    end

    %% Local Data Layer
    LocalData["Local Data"]:::data
    subgraph "Stimulus & Metadata"
        DT1["stimulus_ImageNetTest.tsv"]:::data
        DT2["stimulus_ImageNetTraining.tsv"]:::data
        DT3["category_GODImagery.tsv"]:::data
        DT4["imageURL_test.csv"]:::data
        DT5["imageURL_training.csv"]:::data
        DT6["imageID_test.csv"]:::data
        DT7["imageID_training.csv"]:::data
    end
    subgraph "Caffe Models"
        C1["bvlc_reference_caffenet.prototxt"]:::model
        C2["generator.prototxt"]:::model
    end
    LocalData --> DT1
    LocalData --> C1

    %% Processing Layer
    subgraph "Matlab Pipeline"
        L7["SPR_2009 Library"]:::library
        L8["MEX Prog Module"]:::library
        L1["analysis_CategoryIdentification.m"]:::matlab
        L2["analysis_FeaturePrediction.m"]:::matlab
        L3["analysis_FeaturePredictionAccuracy.m"]:::matlab
        L4["convert_decodedfeatures.m"]:::matlab
        L5["createfigure.m"]:::matlab
        L6["export_volume.m"]:::matlab
    end

    subgraph "Python Pipeline"
        P0["god_config.py"]:::python
        P1["makedata_features.py"]:::python
        P2["analysis_CategoryIdentification.py"]:::python
        P3["analysis_FeaturePrediction.py"]:::python
        P4["analysis_FeaturePredictionMergeResults.py"]:::python
        P5["convertdata_MatlabResults.py"]:::python
        P6["createfigure.py"]:::python
    end

    %% Output Layer
    subgraph "Output"
        O1["decoded_results (CSV/MAT)"]:::output
        O2["figures (PNG/PDF)"]:::output
        O3["logs & intermediates"]:::output
    end

    %% Data Flows
    EN1 -->|"fMRI raw data"|LocalData
    EN2 -->|"preprocessed fMRI & features"|LocalData
    EN3 -->|"stimulus images"|LocalData

    LocalData -->|"stimulus tables & fMRI"|L1
    LocalData -->|"stimulus tables & fMRI"|P1

    C1 -->|"model definitions"|L2
    C1 -->|"model definitions"|P3

    L7 -->|"sparse regression tools"|L1
    L7 -->|"sparse regression tools"|L2
    L7 -->|"sparse regression tools"|L3
    L8 -->|"MEX functions"|L1
    L8 -->|"MEX functions"|L2
    L8 -->|"MEX functions"|L3

    L1 -->|"decoded features"|L4
    L2 -->|"decoded features"|L4
    L3 -->|"decoded features"|L4

    L4 -->|"converted features"|P5
    P5 -->|"imported Matlab results"|P4

    P1 -->|"feature datasets"|P2
    P2 -->|"feature matrices"|P4
    P3 -->|"feature matrices"|P4

    P4 -->|"merged decoded labels"|P6
    L5 -->|"publication figures"|O2
    P6 -->|"publication figures"|O2

    L4 -->|"decoded results"|O1
    P4 -->|"decoded results"|O1

    L6 -->|"exported volumes"|O3

    %% Click Events
    click DT1 "https://github.com/kamitanilab/genericobjectdecoding/blob/master/data/stimulus_ImageNetTest.tsv"
    click DT2 "https://github.com/kamitanilab/genericobjectdecoding/blob/master/data/stimulus_ImageNetTraining.tsv"
    click DT3 "https://github.com/kamitanilab/genericobjectdecoding/blob/master/data/category_GODImagery.tsv"
    click DT4 "https://github.com/kamitanilab/genericobjectdecoding/blob/master/data/imageURL_test.csv"
    click DT5 "https://github.com/kamitanilab/genericobjectdecoding/blob/master/data/imageURL_training.csv"
    click DT6 "https://github.com/kamitanilab/genericobjectdecoding/blob/master/data/imageID_test.csv"
    click DT7 "https://github.com/kamitanilab/genericobjectdecoding/blob/master/data/imageID_training.csv"
    click C1 "https://github.com/kamitanilab/genericobjectdecoding/blob/master/data/cnn/bvlc_reference_caffenet/bvlc_reference_caffenet.prototxt"
    click C2 "https://github.com/kamitanilab/genericobjectdecoding/blob/master/data/cnn/fc6/generator.prototxt"
    click L1 "https://github.com/kamitanilab/genericobjectdecoding/blob/master/code/matlab/analysis_CategoryIdentification.m"
    click L2 "https://github.com/kamitanilab/genericobjectdecoding/blob/master/code/matlab/analysis_FeaturePrediction.m"
    click L3 "https://github.com/kamitanilab/genericobjectdecoding/blob/master/code/matlab/analysis_FeaturePredictionAccuracy.m"
    click L4 "https://github.com/kamitanilab/genericobjectdecoding/blob/master/code/matlab/convert_decodedfeatures.m"
    click L5 "https://github.com/kamitanilab/genericobjectdecoding/blob/master/code/matlab/createfigure.m"
    click L6 "https://github.com/kamitanilab/genericobjectdecoding/blob/master/code/matlab/export_volume.m"
    click L7 "https://github.com/kamitanilab/genericobjectdecoding/tree/master/code/matlab/lib/SPR_2009_12_17/"
    click L8 "https://github.com/kamitanilab/genericobjectdecoding/tree/master/code/matlab/lib/mex_prog_2010-06-21/"
    click P0 "https://github.com/kamitanilab/genericobjectdecoding/blob/master/code/python/god_config.py"
    click P1 "https://github.com/kamitanilab/genericobjectdecoding/blob/master/code/python/makedata_features.py"
    click P2 "https://github.com/kamitanilab/genericobjectdecoding/blob/master/code/python/analysis_CategoryIdentification.py"
    click P3 "https://github.com/kamitanilab/genericobjectdecoding/blob/master/code/python/analysis_FeaturePrediction.py"
    click P4 "https://github.com/kamitanilab/genericobjectdecoding/blob/master/code/python/analysis_FeaturePredictionMergeResults.py"
    click P5 "https://github.com/kamitanilab/genericobjectdecoding/blob/master/code/python/convertdata_MatlabResults.py"
    click P6 "https://github.com/kamitanilab/genericobjectdecoding/blob/master/code/python/createfigure.py"

    %% Styles
    classDef data fill:#9f6,stroke:#333,stroke-width:1px
    classDef model fill:#b9f,stroke:#333,stroke-width:1px
    classDef matlab fill:#6bf,stroke:#333,stroke-width:1px
    classDef python fill:#f96,stroke:#333,stroke-width:1px
    classDef library fill:#48f,stroke:#333,stroke-width:1px
    classDef output fill:#ccc,stroke:#333,stroke-width:1px
```
