Data Requirements

​

Overview

1. Functional Connectivity (FC) Matrices - Brain connectivity graphs from rs-fMRI scans
2. Temporal Label File - Subject labels and visit information with temporal metadata

​

Directory Structure

data/
├── FC_Matrices/              # Functional connectivity matrices
│   ├── sub-XXXXXX_run-01_fc_matrix.npz
│   ├── sub-XXXXXX_run-02_fc_matrix.npz
│   └── ...
├── TADPOLE_TEMPORAL.csv      # Temporal labels and visit data
├── TADPOLE_COMPLETE.csv      # (Optional) Source data for temporal setup
└── TADPOLE_Simplified.csv    # (Optional) Source data for temporal setup

​

FC Matrix Requirements

​

File Format

• Location: data/FC_Matrices/
• Naming Convention: sub-{SUBJECT_ID}_run-{RUN_NUMBER}_fc_matrix.npz
• File Type: NumPy compressed array (.npz)

​

Filename Pattern

sub-XXXXXX_run-XX_fc_matrix.npz

• XXXXXX is the subject ID (6 digits, no underscores)
• XX is the run number (2 digits, zero-padded)

​

NPZ File Contents

import numpy as np

# Create FC matrix
fc_matrix = np.random.randn(116, 116)  # Example: 116 ROIs

# Save with correct key
np.savez('sub-123456_run-01_fc_matrix.npz', arr_0=fc_matrix)

• Default array key: arr_0 (configurable via var_name parameter)
• Matrix must be square (N × N where N = number of ROIs)
• Values represent correlation coefficients between brain regions
• Matrix is automatically symmetrized: (matrix + matrix.T) / 2

​

Matrix Properties

fc_matrix = data[self.var_name]
fc_matrix = (fc_matrix + fc_matrix.T) / 2  # Ensure symmetry

• Dimensions: Typically 116×116 (AAL atlas) or other ROI parcellation
• Values: Correlation coefficients (typically -1 to 1)
• Symmetry: Enforced automatically during loading
• Thresholding: Edges with |value| < threshold are removed (default: 0.2)

​

Label File Requirements

​

File Format

• Filename: TADPOLE_TEMPORAL.csv
• Location: data/
• Format: CSV with header row

​

Required Columns

​

Optional Columns

​

Subject ID Formatting

df['Subject'] = df['Subject'].str.replace('_', '', regex=False)

​

Data Mapping

​

Subject to Graph Mapping

1. Extract subject ID from filename: sub-123456_run-01_fc_matrix.npz → subject 123456, run 01
2. Create full ID: 123456_run01 (underscores in full ID, zero-padded run)
3. Match to CSV: Use subject 123456 for label lookup
4. Assign visit info: Map run number to chronological visit order

for run_idx, (_, visit_row) in enumerate(subject_data.iterrows()):
    run_key = f"{subject}_run{run_idx + 1:02d}"  # Format as run01, run02, etc.
    
    visit_dict[run_key] = {
        'visit_code': visit_row['Visit'],
        'visit_months': visit_row['Months_From_Baseline'],
        'months_to_next': visit_row.get('Months_To_Next_Original', -1)
    }

​

Chronological Visit Ordering

• run-01 → First visit (earliest Visit_Order)
• run-02 → Second visit
• run-03 → Third visit, etc.

​

Label Encoding

​

Classification Labels

• 0: Stable (no cognitive decline)
• 1: Converter (progressed to worse cognitive stage)

​

Label Assignment

# Use the label from the last visit per subject
for subject in df['Subject'].unique():
    subject_data = df[df['Subject'] == subject]
    # Use the last visit's label as the overall subject label
    label_dict[subject] = subject_data.iloc[-1][label_col]

​

Graph Construction

​

Edge Thresholding

A[np.abs(A) < self.threshold] = 0  # Default threshold = 0.2

​

Node Features

if node_features is None:
    # Use normalized identity matrix
    x = torch.eye(N, dtype=torch.float) * 1.0
else:
    x = torch.tensor(node_features, dtype=torch.float)

​

Validation

​

Common Issues

np.savez(filename, arr_0=fc_matrix)  # Not just np.savez(filename, fc_matrix)