Add data directory documentation with structure and acquisition instructions

Author: HAM41

data/README.md

@@ -0,0 +1,106 @@
+# Data Directory
+
+This directory contains neural and behavioral data for the ClickDV project. The data is organized by animal subjects and recording sessions.
+
+## Directory Structure
+
+```
+data/
+├── README.md                    # This file
+├── raw/                        # Raw neural data files (.mat format)
+│   ├── A324/                   # Subject A324 data
+│   │   ├── 2023-07-27/
+│   │   │   └── A324_pycells_20230727.mat
+│   │   └── 2023-07-28/
+│   │       └── A324_pycells_20230728.mat
+│   ├── A327/                   # Subject A327 data
+│   │   ├── 2023-09-09/
+│   │   │   └── A327_pycells_20230909.mat
+│   │   ├── 2023-09-10/
+│   │   │   └── A327_pycells_20230910.mat
+│   │   ├── 2023-09-11/
+│   │   │   └── A327_pycells_20230911.mat
+│   │   └── 2023-09-12/
+│   │       └── A327_pycells_20230912.mat
+│   ├── C211/                   # Subject C211 data
+│   │   ├── 2024-01-03/
+│   │   │   └── C211_pycells_20240103.mat
+│   │   ├── 2024-01-04/
+│   │   │   └── C211_pycells_20240104.mat
+│   │   ├── 2024-01-05/
+│   │   │   └── C211_pycells_20240105.mat
+│   │   ├── 2024-01-06/
+│   │   │   └── C211_pycells_20240106.mat
+│   │   ├── 2024-01-07/
+│   │   │   └── C211_pycells_20240107.mat
+│   │   ├── 2024-01-08/
+│   │   │   └── C211_pycells_20240108.mat
+│   │   └── 2024-01-10/
+│   │       └── C211_pycells_20240110.mat
+│   └── Copy of twoarmedbandit_trainingrecordings.csv
+└── processed/                  # Processed data outputs
+    ├── aligned_sessions/       # Time-aligned neural activity
+    ├── click_times/           # Extracted click timing data
+    └── decision_variables/    # Computed decision variables
+```
+
+## Data Format
+
+### Raw Data Files
+- **Format**: MATLAB `.mat` files
+- **Naming Convention**: `{ANIMAL_ID}_pycells_{YYYYMMDD}.mat`
+- **Content**: Neural spike times, behavioral timestamps, trial information
+
+### Key Data Fields
+Each `.mat` file contains:
+- `raw_spike_time_s`: Raw neural spike times in seconds
+- `filt_spike_time`: Filtered spike times (quality-approved units)
+- `clicks_on`: Click event timestamps
+- `cpoke_in`/`cpoke_out`: Center poke entry/exit times
+- `spoke`: Side poke timestamps (choice indicators)
+- `feedback`: Trial feedback timestamps
+- `region`: Brain region labels (e.g., 'ADS', 'NAc', 'MGB')
+- `hemisphere`: Recording hemisphere ('left'/'right')
+
+## Data Acquisition
+
+### For New Users
+1. **Contact**: Obtain data access from the Brody-Daw lab. I received this from Julie Charlton.
+2. **Download**: Request access to the lab's data repository
+3. **Placement**: Download files into the appropriate `data/raw/ANIMAL_ID/DATE/` directories
+4. **Verification**: Ensure file naming follows the convention above
+
+### Data Sources
+- **Origin**: Brody-Daw lab, Princeton University
+- **Recording Type**: Multi-unit neural recordings during two-armed bandit task
+- **Species**: Rat behavioral experiments
+- **Recording Regions**: Anterior Dorsal Striatum (ADS), Nucleus Accumbens (NAc), others
+
+### File Sizes
+- Individual session files: ~10-50 MB each
+- Total raw data: ~500 MB
+- Processed outputs: Variable, typically <100 MB
+
+## Setup Instructions
+
+1. **Create directory structure**:
+   ```bash
+   mkdir -p data/raw data/processed/aligned_sessions data/processed/click_times data/processed/decision_variables
+   ```
+
+2. **Obtain raw data**:
+   - Contact lab for data access credentials
+   - Download session files to appropriate `data/raw/ANIMAL_ID/DATE/` folders
+   - Verify file integrity and naming conventions
+
+3. **Processed data**:
+   - Will be generated by running analysis scripts
+   - Intermediate outputs saved in `processed/` subdirectories
+   - Can be regenerated from raw data as needed
+
+## Notes
+
+- Raw data files are ignored by git (see `.gitignore`)
+- Only commit processed outputs that are small and essential
+- For reproducibility, document any data preprocessing steps
+- Consider using data versioning tools (DVC) for larger datasets