Skip to content

README.md

Latest commit

 

History

History
176 lines (121 loc) · 4.95 KB

README.md

File metadata and controls

176 lines (121 loc) · 4.95 KB
Raw

Eye-vs-Face Project Repository

Analysis code, model training, and figure-generation notebooks for the manuscript. The repository is organized into reusable code, analysis notebooks, and generated outputs.

Repository Structure

.
├── data/                  # Preprocessed + intermediate data (download from figshare)
├── analysis/
│   ├── code/              # Reusable analysis code
│   └── notebooks/         # Analysis notebooks
│       └── weights/       # Saccade model weights
├── figures/               # Generated figures
├── images/                # Static manuscript images
├── paper/                 # figures.ipynb for manuscript figures
├── README.md
└── requirements.txt

Hardware Configuration

The analyses and models in this repository were run on the following system:

  • OS: Linux 5.15.0-139-generic
  • Python version: 3.10.13
  • CPU Model: Intel(R) Xeon(R) W-3365 CPU @ 2.70GHz
  • Architecture: x86_64
  • Cores: 64
  • RAM: 251.31 GB
  • GPU: NVIDIA GeForce RTX 4090

Setup/Installation Instructions (< 5 min)

To reproduce the results, clone the repository:

git clone https://github.com/MouseLand/eye-vs-face
cd eye-vs-face

Next, download the dataset from the provided Figshare link and organize the files so that the directory structure matches the repository layout described in the README (e.g., data/, paper/, analysis/, etc.).

After cloning the repository and downloading the data, create the Conda environment:

conda create -n eye_vs_face python=3.10
conda activate eye_vs_face
pip install -r requirements.txt

Next, run the notebooks in the recommended execution order to reproduce the paper analyses as decribed in the analysis/readme.md. Alternatively, run the paper/figures.ipynb notebook to generate final results/figures for the manuscript.

Directory Overview

data/

Preprocessed and intermediate files required for analysis. Data downloaded from figshare will be placed here. Figshare download structure:

  • npz_data

    • xpos: neuron x-position
    • ypos: neuron y-position
    • spks: neurons x time
    • face_svd
    • face_eye_svd
    • pose_x_coord: keypoints x-coordinate
    • pose_y_coord: keypoints y-coordinate
    • pupil_x_small: pupil x-position
    • pupil_y_small: pupil y-position
    • pupil_area_small: pupil area
    • blink_small: blink trace
    • neural_frames_list
    • cam_frames_list
    • tcam: camera timestamps
    • tneural: neural timestamps
    • iplane
    • stat
    • running_speed
    • running_time
    • pupil_x_polar
    • pupil_y_polar
    • axis_info

  • cam_data

    • Raw camera recordings from the behavioral setup. Also contains different cropped versions of the videos.

  • saccade_labels

    • Detected saccade events using the uneye model.

  • cam_proc

    • Processed behavior video output using Facemap software.

  • retinotopy

    • Retinotopy results for the light condition recordings.

paper/

Contains figures.ipynb, which generates all manuscript figures.

analysis/

Please see [analysis/readme.md](https://figshare.com/your-dataset-link for details on running notebook code and estimated time for each notebook.

analysis/code/ (< 15 min)

Reusable Python modules:

  • get_keypoints_psth.py — Keypoints aligned to saccades (Fig. 3)
  • get_saccades.py — Dataset-wide saccade compilation
  • get_running_psth.py — Running analyses (Fig. 3)
  • nonlinear_modelv3.py — Model definitions and training
  • helper_functions.py — Utilities
  • pupil_dark_helpers*.py — Preprocessing

All are imported by notebooks except: get_keypoints_psth.py, get_saccades.py, and get_running_psth.py, which must be run directly:

python filename.py

analysis/notebooks/

Main analysis and modeling notebooks:

  • generate_svds.ipynb
  • geom_to_deg_saccade.ipynb
  • run_predictions.ipynb
  • tuning_curves.ipynb
  • keypoints_prediction.ipynb
  • saccade_video.ipynb
  • UnEye.ipynb

figures/

Exported figure panels from paper/figures.ipynb.

images/

Static images used in manuscript figures.

Reproducibility Notes

  • Ensure file paths are correct relative to the repository root.
  • Some notebooks depend on outputs generated by earlier notebooks.
  • Random seeds should be fixed where applicable for exact replication.

External Dependencies

Script for generating some intermediate datasets are not included in this repository. This includes:

  • Original saccade labels generated using the Andersson weights from the uneye model

The dataset can be reproduced by following the instructions provided in the respective GitHub repositories:

Please refer to the above repository for installation instructions and dataset generation procedures before running the dependent analysis steps in this project.