Add headless CARTO and EnSiteX importer integration workflow

README.md

@@ -1,3 +1,6 @@
 # OpenEP
 
 OpenEP supports the import and analysis of electroanatomic mapping data in Matlab
+
+For headless CARTO and EnSiteX conversion, validation, status reporting and
+TRE integration, see [docs/tre_importer_integration.md](docs/tre_importer_integration.md).

addForceData.m

@@ -0,0 +1,17 @@
+function userdata = addForceData(userdata)
+
+time = zeros(size(userdata.rf.originaldata.ablparams.time));
+force = zeros(size(userdata.rf.originaldata.ablparams.time));
+axialangle = zeros(size(userdata.rf.originaldata.ablparams.time));
+lateralangle = zeros(size(userdata.rf.originaldata.ablparams.time));
+position = zeros(size(userdata.rf.originaldata.ablparams.time));
+
+forcedata.time = time;
+forcedata.force = force;
+forcedata.axialangle = axialangle;
+forcedata.lateralangle = lateralangle;
+forcedata.position = position;
+
+userdata.rf.originaldata.force = forcedata;
+
+end

addLocationPoints.m

@@ -0,0 +1,55 @@
+function userdata = addLocationPoints(userdata, X, tags, names)
+% ADDLOCATIONPOINTS Manually add location points to data
+%
+% Usage:
+%   userdata = addLocationPoints(userdata, X, tags, names)
+% Where:
+%   userdata  - the OpenEP data structure
+%   X  - locations
+%   tags  - tags
+%   names - names
+%
+% addLocationPoints does not accept parameter value pairs
+%
+% ADDLOCATIONPOINTS Manually add location points to data
+%
+% Author: Steven Williams (2024)
+% Modifications -
+%
+% Info on Code Testing:
+% ---------------------------------------------------------------
+% % copy and paste co-ordinates from a CSV file
+% tags = cell(size(X,1), 1);
+% tags(:) = {'ablation'};
+% names = cell(size(X,1), 1);
+% names(:) = {'abl'};
+% userdata = addLocationPoints(userdata, X, tags, names)
+% ---------------------------------------------------------------
+%
+% ---------------------------------------------------------------
+% code
+% ---------------------------------------------------------------
+
+numPointsToAdd = size(X, 1);
+
+for i = 1:numPointsToAdd
+userdata.electric.tags{end+1} = tags{i};
+userdata.electric.names{end+1} = [names{i} num2str(i)];
+userdata.electric.egmX(end+1,:) = X(i,:);
+userdata.electric.egm(end+1,:) = NaN;
+userdata.electric.egmRef(end+1,:) = NaN(1,1000);
+userdata.electric.annotations.woi(end+1,:) = [NaN NaN];
+userdata.electric.annotations.referenceAnnot(end+1,:) = NaN;
+userdata.electric.annotations.mapAnnot(end+1,:) = NaN;
+userdata.electric.voltages.bipolar(end+1,:) = NaN;
+
+tr = getMesh(userdata, 'type', 'triangulation');
+surfX = findclosestvertex(tr, X(i,:), true);
+userdata.electric.egmSurfX(end+1,:) = userdata.surface.triRep.X(surfX,:);
+userdata.electric.LATs(end+1,:) = NaN;
+userdata.electric.electrodeNames_uni(end+1,:) = NaN;
+userdata.electric.include(end+1) = false;
+userdata.electric.discarded(end+1) = true;
+
+
+end

batchConvert.m

@@ -44,11 +44,30 @@ function batchConvert(inputDir, outputDir)
    % Store comment about what we have done
    userdata.notes{end+1} = [date ': data set converted using batchConvert.m'];
 
+   % If force data does not exist, add it please
+   if isfield(userdata, 'rf')
+       if isempty(userdata.rf)
+           userdata = addForceData(userdata);
+       end
+       if ~isfield(userdata.rf.originaldata, 'force')
+           userdata = addForceData(userdata);
+           disp(' ... fake force data added')
+           userdata.notes{end+1} = [date ': fake forcedata added during batchConvert.m'];
+       end
+   else
+       userdata.rf = [];
+   end
+
+   % If force data does not exist, add it please
+   if isempty(userdata.surface.uni_imp_frc)
+       userdata.surface.uni_imp_frc = NaN(size(userdata.surface.triRep.X));
+   end
+
    % We save as -v7 because it's faster to load in OpenEP-py than -v7.3,
    % and the saved file is significantly smaller compared to -v6 files.
    outputFile = [outputDir filesep() allFiles{i}];
    disp(['saving file: ' outputFile])
-   save(outputFile, 'userdata', '-v7');
+   save(outputFile, 'userdata', '-v7.3');
 
 end
 

calculatePeak2PeakVoltage.m

@@ -0,0 +1,37 @@
+function V = calculatePeak2PeakVoltage( egms, refAnnot, woi )
+% CALCULATEPEAK2PEAKVOLTAGE Calcualtes peak to peak voltages
+%
+% Usage:
+%   V = calculatePeak2PeakVoltage( egms, refAnnot, woi )
+% Where:
+%   egms      - the electrograms
+%   refAnnot  - the reference annotation, in samples
+%   woi       - the window of interest, relative to the refAnnot, in samples
+%   V         - the output voltages
+%
+% CALCULATEPEAK2PEAKVOLTAGE does not accept parameter-value pairs
+%
+% CALCULATEPEAK2PEAKVOLTAGE Detailed description goes here
+%
+% Author: Steven Williams (2025)
+% Modifications -
+%
+% Info on Code Testing:
+% ---------------------------------------------------------------
+% test code
+% ---------------------------------------------------------------
+%
+% ---------------------------------------------------------------
+% code
+% ---------------------------------------------------------------
+
+nEgm = size(egms,1);
+V = NaN(nEgm,1);
+for iEgm = 1:nEgm
+
+    sampleRange = refAnnot(iEgm)+woi(iEgm,1):refAnnot(iEgm)+woi(iEgm,2);
+    thisEgm = egms(iEgm, sampleRange);
+    V(iEgm) = max(thisEgm) - min(thisEgm);
+
+end
+end

changelog.md

@@ -29,12 +29,13 @@ This section documents changes which have been merged into develop and will form
 - importcarto_mem.m
     - no longer has to check the electrode name for each point as this is
       taken from read_ecgfile_v4
+- ability to read latest Carto data (new format without redundancy)
 
-
 ### Fixed
 - Fixed issue with multiple colour bars
 - Fixed issue #70 for setting tolerance when identifying in/out points in the mesh
 - Geodesic distance calculator now configured for both Ubuntu and MacOSX platforms
 - Tidied importcarto_mem default directories
 - Sped up xml reading
-- Sped up read_meshfile
+- Sped up read_meshfile
+- Fixed bug in getEarliestActivationSite/getLatestActivationSite when handling datasets written by EP Workbench

comparestructure.m

@@ -1,108 +1,111 @@
-function [result, commentary] = comparestructure(a,b)
-% COMPARESTRUCTURE.
-% Usage:
-%   [result, commentary] = comparestructure(a,b)
-% Inputs:
-%   a,b  - input structures to compare
-% Outputs:
-%   result  - logical
-%   commentary - a cellarray of text messages explaining the differences
-%
-% Author: Nick Linton (2023)
-% Modifications - 
-
-% Info on Code Testing:
-						% ---------------------
-                        % test code
-                        % ---------------------
-
-% ---------------------------------------------------------------
-% code
-% ---------------------------------------------------------------
-
-
-    local_addmsg(0, 'reset');
-
-    if isequal(a,b)
-        result = true;
-        commentary = '';
-    	return
-    else
-        result = false;
-        local_compare(a,b,0)
-        commentary = local_addmsg(0, 'retrieve');
-    end
-end
-
-function local_compare(a,b,level)
-    fieldnamesA = sort(fieldnames(a));
-    fieldnamesB = sort(fieldnames(b));
-    fieldNamesAll = unique([fieldnamesA;fieldnamesB]);
-
-    badNamesA = false(size(fieldNamesAll));
-    badNamesB = false(size(fieldNamesAll));
-    if ~isequal(fieldnamesA, fieldnamesB)
-        for i = 1:numel(fieldNamesAll)
-            if ~any(matches(fieldnamesB, fieldNamesAll{i}))
-                badNamesA(i) = true;
-                local_addmsg(['.' fieldnamesA{i} ' is not in the second structure']);
-            end
-            if ~any(matches(fieldnamesA, fieldNamesAll{i}))
-                badNamesB(i) = true;
-                local_addmsg(['.' fieldnamesA{i} ' is not in the second structure']);
-            end
-        end
-    end
-
-    level = level + 1;
-% now go through the fieldNames that are shared.
-    sharedFieldNames = fieldNamesAll(~badNamesA & ~badNamesB);
-    for i = 1:numel(sharedFieldNames)
-        f = sharedFieldNames{i};
-        if ~strcmp(class(a.(f)),class(b.(f)))
-            local_addmsg(level, ['.' f ' does not have the same class']);
-        else
-            switch class(a.(f))
-                case 'struct'
-                    local_addmsg(level, ['.' f ]);
-                    local_compare(a.(f),b.(f),level)
-                otherwise
-                    aData = a.(f);
-                    bData = b.(f);
-                    isSizeOK = isequal(size(a.(f)),size(b.(f)));
-                    isNumelOK = isequal(numel(a.(f)),numel(b.(f)));
-                    isContentOK = false;
-                    if isNumelOK
-                        isContentOK = isequaln(a.(f)(:),b.(f)(:));
-                    end
-                    if isSizeOK && isContentOK
-                        % do nothing - all good
-                        local_addmsg(level, ['.' f '  - correct']);
-                    elseif ~isContentOK
-                        local_addmsg(level, ['.' f ' - &&&ERROR&&& has different CONTENT']);
-                    else
-                        local_addmsg(level, ['.' f ' - &&&ERROR&&& has different DIMENSIONS but similar content']);
-                    end
-            end
-        end
-    end
-end
-
-function msgAll = local_addmsg(level, msg)
-    persistent msgStore
-
-    verbose = true;
-    switch msg
-        case 'reset'
-            msgStore = {};
-        case 'retrieve'
-            msgAll = msgStore;
-        otherwise
-            indent = repmat('  ',1,level);
-            if verbose
-                disp([indent,msg])
-            end
-            msgStore = [msgStore; [indent,msg]];
-    end
-    msgAll = msgStore;
-end
+function [result, commentary] = comparestructure(a,b)
+% COMPARESTRUCTURE.
+% Usage:
+%   b = myfunction(a)
+% Inputs:
+%   a  - input
+% Outputs:
+%   b  - output
+%
+% MYFUNCTION detailed description.
+%
+% Author: Nick Linton (2021)
+% Modifications - 
+
+% Info on Code Testing:
+						% ---------------------
+                        % test code
+                        % ---------------------
+
+% ---------------------------------------------------------------
+% code
+% ---------------------------------------------------------------
+
+
+    local_addmsg(0, 'reset');
+
+    if isequal(a,b)
+        result = true;
+        commentary = '';
+    	return
+    else
+        result = false;
+        local_compare(a,b,0)
+        commentary = local_addmsg(0, 'retrieve');
+    end
+end
+
+function local_compare(a,b,level)
+    fieldnamesA = sort(fieldnames(a));
+    fieldnamesB = sort(fieldnames(b));
+    fieldNamesAll = unique([fieldnamesA;fieldnamesB]);
+
+    badNamesA = false(size(fieldNamesAll));
+    badNamesB = false(size(fieldNamesAll));
+    if ~isequal(fieldnamesA, fieldnamesB)
+        for i = 1:numel(fieldNamesAll)
+            if ~any(matches(fieldnamesB, fieldNamesAll{i}))
+                badNamesA(i) = true;
+                local_addmsg(level, ['.' fieldNamesAll{i} ' is not in the second structure']);
+            end
+            if ~any(matches(fieldnamesA, fieldNamesAll{i}))
+                badNamesB(i) = true;
+                local_addmsg(level, ['.' fieldNamesAll{i} ' is not in the first structure']);
+            end
+        end
+    else
+        local_addmsg(level, 'the order of the fields are different');
+    end
+
+    %level = level + 1;
+% now go through the fieldNames that are shared.
+    sharedFieldNames = fieldNamesAll(~badNamesA & ~badNamesB);
+    for i = 1:numel(sharedFieldNames)
+        f = sharedFieldNames{i};
+        if ~strcmp(class(a.(f)),class(b.(f)))
+            local_addmsg(level, ['.' f ' does not have the same class']);
+        else
+            switch class(a.(f))
+                case 'struct'
+                    local_addmsg(level, ['.' f ]);
+                    local_compare(a.(f),b.(f),level+1)
+                otherwise
+                    aData = a.(f);
+                    bData = b.(f);
+                    isSizeOK = isequal(size(a.(f)),size(b.(f)));
+                    isNumelOK = isequal(numel(a.(f)),numel(b.(f)));
+                    isContentOK = false;
+                    if isNumelOK
+                        isContentOK = isequaln(a.(f)(:),b.(f)(:));
+                    end
+                    if isSizeOK && isContentOK
+                        % do nothing - all good
+                        local_addmsg(level, ['.' f '  - correct']);
+                    elseif ~isContentOK
+                        local_addmsg(level, ['.' f ' - &&&ERROR&&& has different CONTENT']);
+                    else
+                        local_addmsg(level, ['.' f ' - &&&ERROR&&& has different DIMENSIONS but similar content']);
+                    end
+            end
+        end
+    end
+end
+
+function msgAll = local_addmsg(level, msg)
+    persistent msgStore
+
+    verbose = true;
+    switch msg
+        case 'reset'
+            msgStore = {};
+        case 'retrieve'
+            msgAll = msgStore;
+        otherwise
+            indent = repmat('  ',1,level);
+            if verbose
+                disp([indent,msg])
+            end
+            msgStore = [msgStore; [indent,msg]];
+    end
+    msgAll = msgStore;
+end