Initial commit.

Author: benjaminkraus

.gitignore

@@ -0,0 +1,2 @@
+*~
+*.asv

Example.mlx

@@ -0,0 +1,36 @@
+# Colored Trajectory Plot
+
+Version: 1.0
+
+This chart creates a multi-color line based on a 2D trajectory with
+corresponding color data.
+
+## Syntax
+* `colorTrajectoryPlot(x,y)` create a multi-color line plot following the 2D path specified by the coordinates x and y using the index of each coordinate to determine the color of the line. x and y must be numeric vectors of equal length.
+* `colorTrajectoryPlot(x,y,c)` create a multi-color line plot following the 2D path specified by the coordinates x and y using values from c to determine the color of the line at each coordinate. x, y, and c must be numeric vectors of equal length.
+* `colorTrajectoryPlot()` create a multi-color line plot using only name-value pairs.
+* `colorTrajectoryPlot(___,Name,Value)` specifies additional options for the multi-color line plot using one or more name-value pair arguments. Specify the options after all other input arguments.
+* `colorTrajectoryPlot(parent,___)` creates the multi-color line plot in the specified parent.
+* `h = colorTrajectoryPlot(___)` returns the colorTrajectoryPlot object. Use h to modify properties of the plot after creating it.
+
+## Name-Value Pair Arguments/Properties
+* `XData` (n x 1 numeric vector) x-coordinates of the trajectory.
+* `YData` (n x 1 numeric vector) y-coordintaes of the trajectory.
+* `ColorData` (n x 1 numeric vector) data used to determine the color of the line.
+* `Colormap` (m x 3 matrix of RGB triplets) colormap used to convert `ColorData` into colors.
+* `ColorLimits` (1 x 2 numeric vector) limits used to convert `ColorData` into colors.
+* `ColorLimitsMode` (`'auto'` or '`manual'`) mode for the color limits.
+* `ColorbarVisible` (scalar `matlab.lang.OnOffSwitchState`) display the colorbar or not.
+* `LineWidth` (scalar positive double) line width of the trajectory.
+* `TitleText` (n x 1 string vector) title of the plot.
+* `SubtitleText` (n x 1 string vector) subtitle of the plot.
+* `ColorbarLabel` (n x 1 string vector) label on the colorbar.
+
+## Example
+Create a multi-color trajectory plot using x, y, and color data generated by the helper script `randomWalk`.
+```
+[x,y,c] = randomWalk;
+c = colorTrajectoryPlot(x,y,c);
+c.ColorbarLabel = "Firing Rate (Hz)";
+colormap(hot(256))
+```

README.md

@@ -0,0 +1,6 @@
+# Reporting Security Vulnerabilities 
+
+If you believe you have discovered a security vulnerability, please report it to 
+[security@mathworks.com](mailto:security@mathworks.com). Please see 
+[MathWorks Vulnerability Disclosure Policy for Security Researchers](https://www.mathworks.com/company/aboutus/policies_statements/vulnerability-disclosure-policy.html) 
+for additional information. 

SECURITY.md

@@ -0,0 +1,341 @@
+classdef colorTrajectoryPlot < matlab.graphics.chartcontainer.ChartContainer & ...
+        matlab.graphics.chartcontainer.mixin.Colorbar
+    %colorTrajectoryPlot Create a multi-color trajectory plot
+    %   colorTrajectoryPlot(x,y) create a multi-color line plot following
+    %   the 2D path specified by the coordinates x and y using the index of
+    %   each coordinate to determine the color of the line. x and y must be
+    %   numeric vectors of equal length.
+    %
+    %   colorTrajectoryPlot(x,y,c) create a multi-color line plot following
+    %   the 2D path specified by the coordinates x and y using values from
+    %   c to determine the color of the line at each coordinate. x, y, and
+    %   c must be numeric vectors of equal length.
+    %
+    %   colorTrajectoryPlot() create a multi-color line plot using only
+    %   name-value pairs.
+    %
+    %   colorTrajectoryPlot(___,Name,Value) specifies additional options
+    %   for the multi-color line plot using one or more name-value pair
+    %   arguments. Specify the options after all other input arguments.
+    %
+    %   colorTrajectoryPlot(parent,___) creates the multi-color line plot
+    %   in the specified parent.
+    %
+    %   h = colorTrajectoryPlot(___) returns the colorTrajectoryPlot
+    %   object. Use h to modify properties of the plot after creating it.
+    
+    %   Copyright 2020-2021 The MathWorks, Inc.
+    
+    properties
+        % x-coordinates of the trajectory.
+        XData (:,1) double = []
+        
+        % y-coordintaes of the trajectory.
+        YData (:,1) double = []
+        
+        % Data used to determine the color of the line.
+        ColorData (:,1) double = []
+        
+        % Title of the plot.
+        TitleText (:,1) string = ""
+        
+        % Subtitle of the plot.
+        SubtitleText (:,1) string = ""
+        
+        % Line width of the trajectory.
+        LineWidth (1,1) {mustBeNumeric, mustBePositive} = 0.5
+        
+        % Label on the colorbar.
+        ColorbarLabel (:,1) string = ""
+    end
+    
+    properties (Dependent)
+        % Colormap Colormap used to convert `ColorData` into colors.
+        Colormap (:,3) double {mustBeNonempty, mustBeInRange(Colormap,0,1)} = get(groot, 'factoryFigureColormap')
+        
+        % Limits used to convert `ColorData` into colors.
+        ColorLimits (1,2) double {mustBeLimits} = [0 1]
+        
+        % Mode for the color limits.
+        ColorLimitsMode (1,:) char {mustBeAutoManual} = 'auto'
+    end
+    
+    properties (Access = protected)
+        SaveAxesState struct = []
+    end
+    
+    properties (Access = private, Transient, NonCopyable)
+        TrajectoryLine (:,1) matlab.graphics.primitive.Patch
+    end
+    
+    methods
+        function obj = colorTrajectoryPlot(varargin)
+            %
+            
+            % Initialize list of arguments
+            args = varargin;
+            leadingArgs = cell(0);
+            
+            % Check if the first input argument is a graphics object to use as parent.
+            if ~isempty(args) && isa(args{1},'matlab.graphics.Graphics')
+                % colorTrajectoryPlot(parent, ___)
+                leadingArgs = args(1);
+                args = args(2:end);
+            end
+            
+            % Check for optional positional arguments.
+            if ~isempty(args) && isnumeric(args{1})
+                if numel(args) >= 2 && mod(numel(args), 2) == 0 ...
+                        && isnumeric(args{2})
+                    % colorTrajectoryPlot(x, y, Name, Value)
+                    x = args{1};
+                    y = args{2};
+                    
+                    % Verify x and y are the same length.
+                    assert(numel(x) == numel(y), ...
+                        'colorTrajectoryPlot:DataLengthMismatch',...
+                        'y must be the same length as x.');
+                    
+                    % Add x and y to the input arguments.
+                    leadingArgs = [leadingArgs {'XData', x, 'YData', y}];
+                    args = args(3:end);
+                elseif numel(args) >= 3 && mod(numel(args), 2) == 1 ...
+                        && isnumeric(args{2}) && isnumeric(args{3})
+                    % colorTrajectoryPlot(x, y, c, Name, Value)
+                    x = args{1};
+                    y = args{2};
+                    c = args{3};
+                    
+                    % Verify x and y are the same length.
+                    assert(numel(x) == numel(y), ...
+                        'colorTrajectoryPlot:DataLengthMismatch',...
+                        'y must be the same length as x.');
+                    
+                    % Verify x and c are the same length.
+                    assert(numel(c) == numel(y), ...
+                        'colorTrajectoryPlot:DataLengthMismatch',...
+                        'c must be the same length as x.');
+                    
+                    % Add x, y, and c to the input arguments.
+                    leadingArgs = [leadingArgs {'XData', x, 'YData', y, 'ColorData', c}];
+                    args = args(4:end);
+                else
+                    error('colorTrajectoryPlot:InvalidSyntax', 'Specify both x and y coordinates.');
+                end
+            end
+            
+            % Combine positional arguments with name/value pairs.
+            args = [leadingArgs args];
+            
+            % Call superclass constructor method
+            obj@matlab.graphics.chartcontainer.ChartContainer(args{:});
+            
+            % Supress output unless it is requested.
+            if nargout == 0
+                clear obj
+            end
+        end
+    end
+    
+    methods (Access = protected)
+        function setup(obj)
+            % Configure the axes.
+            ax = obj.getAxes();
+            ax.NextPlot = 'replacechildren';
+            ax.DataAspectRatio = [1 1 1];
+            ax.Box = 'on';
+            ax.XTick = [];
+            ax.YTick = [];
+            axis(ax,'tight')
+            
+            % Create a patch to show the trajectory.
+            obj.TrajectoryLine = patch(ax, 'Faces',[], 'Vertices', [], ...
+                'FaceColor', 'none', 'EdgeColor', 'interp');
+            
+            % Restore any saved axes state.
+            loadAxesState(obj)
+        end
+        
+        function update(obj)
+            % Verify that the data properties are consistent with one
+            % another.
+            showChart = verifyDataProperties(obj);
+            obj.TrajectoryLine.Visible = showChart;
+            
+            % Abort early if not visible due to invalid data.
+            if ~showChart
+                return
+            end
+            
+            % Update the vertices and faces on the patch.
+            obj.TrajectoryLine.Vertices = [obj.XData obj.YData; NaN NaN];
+            obj.TrajectoryLine.Faces = 1:numel(obj.XData)+1;
+            
+            % Update the color of the patch.
+            colorData = obj.ColorData;
+            if isempty(colorData)
+                colorData = (1:numel(obj.XData))';
+            end
+            obj.TrajectoryLine.FaceVertexCData = [colorData; NaN];
+            
+            % Update the patch line width.
+            obj.TrajectoryLine.LineWidth = obj.LineWidth;
+            
+            % Update the title/subtitle and colorbar label.
+            title(getAxes(obj), obj.TitleText, obj.SubtitleText);
+            if obj.ColorbarVisible
+                ylabel(getColorbar(obj), obj.ColorbarLabel);
+            end
+        end
+        
+        function showChart = verifyDataProperties(obj)
+            % XData and YData must be the same length.
+            n = numel(obj.XData);
+            showChart = numel(obj.YData) == n;
+            if ~showChart
+                warning('colorTrajectoryPlot:DataLengthMismatch',...
+                    'YData must be the same length as XData.');
+                return
+            end
+            
+            % ColorData and must be empty or the same length as XData.
+            showChart = isempty(obj.ColorData) || numel(obj.ColorData) == n;
+            if ~showChart
+                warning('colorTrajectoryPlot:DataLengthMismatch',...
+                    'ColorData must be empty or the same length as XData.');
+                return
+            end
+        end
+        
+        function loadAxesState(obj)
+            state = obj.SaveAxesState;
+            
+            if isfield(state, 'Colormap')
+                obj.Colormap = state.Colormap;
+            end
+            
+            if isfield(state, 'ColorLimits')
+                obj.ColorLimits = state.ColorLimits;
+            end
+            
+            if isfield(state, 'ColorbarVisible') && state.ColorbarVisible
+                obj.ColorbarVisible = state.ColorbarVisible;
+            end
+            
+            % Reset the SaveAxesState for the next save.
+            obj.SaveAxesState = [];
+        end
+        
+        function groups = getPropertyGroups(obj)
+            if ~isscalar(obj)
+                % List for array of objects
+                groups = getPropertyGroups@matlab.mixin.CustomDisplay(obj);
+            else
+                % List for scalar object
+                propList = cell(1,0);
+                
+                % Add the title, if not empty or missing.
+                nonEmptyTitle = obj.TitleText ~= "" & ~ismissing(obj.TitleText);
+                if any(nonEmptyTitle)
+                    propList = {'TitleText'};
+                end
+                
+                % Add the subtitle, if not empty or missing.
+                nonEmptySubtitle = obj.SubtitleText ~= "" & ~ismissing(obj.SubtitleText);
+                if any(nonEmptySubtitle)
+                    propList{end+1} = 'SubtitleText';
+                end
+                
+                % Add either ColorData or XData and YData.
+                if isempty(obj.ColorData)
+                    propList(end+1:end+2) = {'XData','YData'};
+                else
+                    propList(end+1:end+3) = {'ColorData','ColorLimits','ColorbarLabel'};
+                end
+                
+                groups = matlab.mixin.util.PropertyGroup(propList);
+            end
+        end
+    end
+    
+    methods
+        function title(obj, varargin)
+            [t, st] = title(getAxes(obj), varargin{:});
+            obj.TitleText = t.String;
+            obj.SubtitleText = st.String;
+        end
+        
+        function subtitle(obj, varargin)
+            ax = getAxes(obj);
+            st = subtitle(ax, varargin{:});
+            obj.SubtitleText = st.String;
+        end
+    end
+    
+    methods
+        function set.Colormap(obj, map)
+            ax = getAxes(obj);
+            ax.Colormap = map;
+        end
+        
+        function map = get.Colormap(obj)
+            ax = getAxes(obj);
+            map = ax.Colormap;
+        end
+        
+        function set.ColorLimits(obj, limits)
+            ax = getAxes(obj);
+            ax.CLim = limits;
+        end
+        
+        function limits = get.ColorLimits(obj)
+            ax = getAxes(obj);
+            limits = ax.CLim;
+        end
+        
+        function set.ColorLimitsMode(obj, mode)
+            ax = getAxes(obj);
+            ax.CLimMode = mode;
+        end
+        
+        function mode = get.ColorLimitsMode(obj)
+            ax = getAxes(obj);
+            mode = ax.CLimMode;
+        end
+        
+        function state = get.SaveAxesState(obj)
+            state = obj.SaveAxesState;
+            
+            if isempty(state)
+                % Create a 1x1 struct.
+                state = struct();
+                
+                % Add fields to the struct for each axes property to store.
+                ax = getAxes(obj);
+                if ax.ColormapMode == "manual"
+                    state.Colormap = obj.Colormap;
+                end
+                
+                if obj.ColorLimitsMode == "manual"
+                    state.ColorLimits = obj.ColorLimits;
+                end
+                
+                state.ColorbarVisible = obj.ColorbarVisible;
+            end
+        end
+    end
+end
+
+function mustBeLimits(limits)
+
+if numel(limits) ~= 2 || limits(2) <= limits(1)
+    throwAsCaller(MException('colorTrajectoryPlot:InvalidLimits', 'Specify limits as two increasing values.'))
+end
+
+end
+
+function mustBeAutoManual(mode)
+
+mustBeMember(mode, {'auto','manual'})
+
+end