Extend absoluteToRelativeEvents with robust event filtering, trial inference, and flexible trial-start reference modes (#3)

* Initial plan

* feat: extend absoluteToRelativeEvents with name-value modes and trial inference

Co-authored-by: Nabarb <23075957+Nabarb@users.noreply.github.com>

* chore: address code review feedback for absoluteToRelativeEvents

Co-authored-by: Nabarb <23075957+Nabarb@users.noreply.github.com>

* feat: make absoluteToRelativeEvents accept name-value args and robustly handle trial bounds

Replace inputParser with a name-value arguments interface for absoluteToRelativeEvents, add an input validator for trialStartReference, and expose inferTrialFromBounds as a named option. Improve robustness when pairing trial start/end timestamps by trimming unmatched leading ends or trailing starts and only keeping properly ordered start/end pairs. Minor tidy-ups to variable formatting.

* feat: standardize event structure and improve event handling logic

Update the Events_ struct to use PascalCase fields (Name, Trial, Data) and refine the absoluteToRelativeEvents utility with trial skipping and improved trial inference. Ensure addEvents remaps trial IDs to a consecutive range and update PCA/GPFA to correctly calculate explained variance during projection.

* feat: add cumulative arclength and update trial indexing in NeuralEmbedding

Update the arclength utility to return cumulative segment distances. Refine trial selection logic in NeuralEmbedding to use direct indices for event lookup, ensure tMask is consistently stored as a column vector, and increase event marker visibility in visualizations.

* feat: add plotEventDensity to visualize event distribution along arclength

Adds a method to compute and plot the density of events relative to the normalized arclength of neural trajectories. The method uses weighted kernel density estimation to account for non-uniform arclength velocity and provides multi-event visualization using the gramm library.

* feat: optimize plotEventDensity performance and robustness

Refactors the density calculation to process trials in a single pass and replaces expensive distance calculations with vectorized interpolation. Improves robustness by adding checks for finite arclengths and minimum data points for kernel density estimation.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Nabarb <23075957+Nabarb@users.noreply.github.com>
Co-authored-by: fbarban <federico.barban@unige.it>
Co-authored-by: Fede <fedbarban+github@gmail.com>

Author: Copilot

+embedding/GPFA.m

@@ -1,4 +1,4 @@
-function [E,ProjMatrix,VarExplained]= GPFA(D,pars,W, VarExplained)
+function [E,ProjMatrix,VarExplained]= GPFA(D,pars,W)
 if nargin < 3
     [W, VarExplained] = deal([]);
 end

+embedding/PCA.m

@@ -1,4 +1,4 @@
-function [E,ProjMatrix,ProjMatrixInv,VarExplained] = PCA(D,pars,W, VarExplained)
+function [E,ProjMatrix,ProjMatrixInv,VarExplained] = PCA(D,pars,W)
 
 if nargin < 3
     [W, VarExplained] = deal([]);
@@ -12,8 +12,13 @@
 end
 if pars.projectOnly
     E = embedding.PCA.project(D,W);
+    Winv = W{1}';
+    data = [D{:}];
+    VarExplained = NeuralEmbedding.explainedVar(Winv * [E{:}], data);
+    VarExplained = {VarExplained(2,1)};
+
     ProjMatrix = W;
-    ProjMatrixInv = {W{1}'};
+    ProjMatrixInv = {Winv};
 else
     [E,ProjMatrix,VarExplained] = embedding.PCA.reduce(D_,pars.numPC);
     E = cellfun(@(e)e(1:pars.numPC,:),E,'UniformOutput',false);

+metrics/+compute/arclength.m

@@ -1,4 +1,4 @@
-function [arclen,seglen] = arclength(px,py,varargin)
+function [arclen,seglen,cumarclen] = arclength(px,py,varargin)
 % arclength: compute arc length of a space curve, or any curve represented as a sequence of points
 % usage: [arclen,seglen] = arclength(px,py)         % a 2-d curve
 % usage: [arclen,seglen] = arclength(px,py,pz)      % a 3-d space curve
@@ -156,6 +156,7 @@
 % compute the chordal linear arclengths
 seglen = sqrt(sum(diff(data,[],1).^2,2));
 arclen = sum(seglen);
+cumarclen = cumsum(seglen);
 
 % we can quit if the method was 'linear'.
 if strcmpi(method,'linear')
@@ -209,6 +210,7 @@
 
 % and sum the segments
 arclen = sum(seglen);
+cumarclen = cumsum(seglen);
 
 % ==========================
 %   end main function