Merge pull request #27 from catalystneuro/Neuropixels/convert-locatio…

…n-to-be-readable-in-Python

[Neuropixels] Add MATLAB script to convert "location" in "SU" struct to be readable in Python

src/constantinople_lab_to_nwb/schierek_embargo_2024/mat_utils/convertSULocationToString.m

@@ -0,0 +1,50 @@
+% MATLAB script to process all .mat files in a specified directory,
+% checking for 'SU' structure and converting 'location' to a plain string if it exists
+
+% Specify the path to your directory containing the .mat files
+folderPath = '/Volumes/T9/Constantinople/Ephys Data/'; % Replace with your actual folder path
+
+% Get a list of all .mat files in the directory
+files = dir(fullfile(folderPath, '**', '*.mat'));
+matFiles = fullfile({files.folder}, {files.name});
+
+% Loop through each .mat file in the directory
+for k = 1:length(matFiles)
+    matFilePath = fullfile(folderPath, matFiles(k));
+    matFilePath = char(matFiles{k});  % Ensure it is a character array
+    % Load the .mat file
+    try
+        data = load(matFilePath);
+    catch ME
+        % Handle the error
+        disp(['An error occurred: ', ME.message]);
+        continue
+    end
+
+    % Check if 'SU' structure exists in the loaded data
+    if isfield(data, 'SU')
+        SU = data.SU;  % Get the SU structure
+        numUnits = length(SU);
+
+        % Iterate over each unit in the SU structure
+        for i = 1:numUnits
+            if isfield(SU{i}, 'location')
+                % Check and convert location if it is a cell array
+                if iscell(SU{i}.location) && ~isempty(SU{i}.location)
+                    locationStr = SU{i}.location{1}; % Extract first element if it is a cell
+                else
+                    locationStr = SU{i}.location;
+                end
+                SU{i}.location = locationStr;
+            end
+        end
+
+        S = data.S;
+        save(matFilePath, 'S', 'SU');
+        disp(['Processed and saved: ', matFilePath]);
+            % Clear variables to free up workspace
+        clear SU;
+        clear S;
+        clear data;
+    end
+end

src/constantinople_lab_to_nwb/schierek_embargo_2024/schierek_embargo_2024_notes.md

@@ -31,6 +31,73 @@ The "SU" struct is a cell array of all individual cells simultaneously recorded
   - `AP` – anterior/posterior neuropixels probe location relative to Bregma
   - `ML` – medial/lateral neuropixels probe location relative to Bregma
 
+#### MATLAB `SU` `location` field converter
+
+The "location" field in some of the processed ephys data files (e.g. `E003_2022-08-01.mat`) when reading in Python shows up as a `MatlabOpaque` object.
+To make the location field readable in Python, please use the `schierek_embargo_2024/mat_utils/convertSULocationToString.m` utility script to convert the location field to a string.
+
+This script processes .mat files containing the location field within `SU` structures to ensure compatibility with Python.
+The script:
+1) Recursively searches through a specified directory for .mat files,
+2) Loads each file and processes the 'SU' struct if present (skipping files without 'SU' struct)
+3) Converts location fields from MATLAB data types (cell arrays, strings) to character arrays to ensure compatibility with Python
+4) Preserves the original 'S' structure while saving the modified data ('SU' and 'S') back to the .mat file
+
+Run this script in MATLAB to process all ephys .mat data files **before** converting to NWB.
+
+```matlab
+% MATLAB script to process all .mat files in a specified directory,
+% checking for 'SU' structure and converting 'location' to a plain string if it exists
+
+% Specify the path to your directory containing the .mat files
+folderPath = '/Volumes/T9/Constantinople/Ephys Data/'; % Replace with your actual folder path
+
+% Get a list of all .mat files in the directory
+files = dir(fullfile(folderPath, '**', '*.mat'));
+matFiles = fullfile({files.folder}, {files.name});
+
+% Loop through each .mat file in the directory
+for k = 1:length(matFiles)
+    matFilePath = fullfile(folderPath, matFiles(k));
+    matFilePath = char(matFiles{k});  % Ensure it is a character array
+    % Load the .mat file
+    try
+        data = load(matFilePath);
+    catch ME
+        % Handle the error
+        disp(['An error occurred: ', ME.message]);
+        continue
+    end
+
+    % Check if 'SU' structure exists in the loaded data
+    if isfield(data, 'SU')
+        SU = data.SU;  % Get the SU structure
+        numUnits = length(SU);
+
+        % Iterate over each unit in the SU structure
+        for i = 1:numUnits
+            if isfield(SU{i}, 'location')
+                % Check and convert location if it is a cell array
+                if iscell(SU{i}.location) && ~isempty(SU{i}.location)
+                    locationStr = SU{i}.location{1}; % Extract first element if it is a cell
+                else
+                    locationStr = SU{i}.location;
+                end
+                SU{i}.location = locationStr;
+            end
+        end
+
+        S = data.S;
+        save(matFilePath, 'S', 'SU');
+        disp(['Processed and saved: ', matFilePath]);
+            % Clear variables to free up workspace
+        clear SU;
+        clear S;
+        clear data;
+    end
+end
+```
+
 ### Processed behavior data
 
 The processed behavior data is stored in custom .mat files (e.g. `J076_2023-12-12.mat`) with the following fields: