# HG changeset patch
# User Nicholas R. Jankowski <jankowskin@asme.org>
# Date 1504116379 14400
#      Wed Aug 30 14:06:19 2017 -0400
# Node ID 43fb7295dc6af94aee1faf9e1165b5cbcd7341c5
# Parent  a315ac23dc6cc13db97eb84f0dc96e32a46cc67e
Implemented missing axis tick and label functions (bug #51839)

* /scripts/plot/appearance/xticks.m, yticks.m, zticks.m, rticks.m, thetaticks.m, xticklabels.m, yticklabels.m, zticklabels.m: new function m-files
* /scripts/plot/appearance/module.mk: added new files to scripts_general_FCN_FILES list
* /doc/interpreter/plot.txi: added doc reference to both setst of m-files
* /NEWS: added m-files under 'Other new functions added in 4.4'

diff -r a315ac23dc6c -r 43fb7295dc6a NEWS
--- a/NEWS	Tue Aug 29 15:42:47 2017 -0700
+++ b/NEWS	Wed Aug 30 14:06:19 2017 -0400
@@ -43,6 +43,14 @@
       hgtransform
       humps
       repelem
+	  rticks
+	  thetaticks
+	  xticks
+	  xticklabels
+	  yticks
+	  yticklabels
+	  zticks
+	  zticklabels
 
  ** Deprecated functions.
 
diff -r a315ac23dc6c -r 43fb7295dc6a doc/interpreter/plot.txi
--- a/doc/interpreter/plot.txi	Tue Aug 29 15:42:47 2017 -0700
+++ b/doc/interpreter/plot.txi	Wed Aug 30 14:06:19 2017 -0400
@@ -283,6 +283,35 @@
 @findex zlim
 @DOCSTRING(xlim)
 
+The @code{xticks}, @code{yticks}, @code{zticks}, @code{rticks}, and
+@code{thetaticks} functions may be used to get or set the tick mark locations
+and modes on the respective axis.  Each has the same form, although mode 
+options are not currently avaliable for @code{rticks}, and @code{thetaticks}. 
+
+@c FIXME: update this section if polarplot and polar axes changes change the
+@c        associated axis properties
+@anchor{XREFyticks}
+@anchor{XREFzticks}
+@anchor{XREFrticks}
+@anchor{XREFthetaticks}
+@findex yticks
+@findex zticks
+@findex rticks
+@findex thetaticks
+@DOCSTRING(xticks)
+
+The @code{xticklabels}, @code{yticklabels}, and @code{zticklabels} functions
+may be used to get or set the label assigned to each tick location and the
+labeling mode on the respective axis.  Each has the same form. 
+
+@c FIXME: update this section if polarplot and polar axes changes change the
+@c        associated axis properties. currently no r or theta label functions
+@anchor{XREFyticklabels}
+@anchor{XREFzticklabels}
+@findex yticklabels
+@findex zticklabels
+@DOCSTRING(xticklabels)
+
 @node Two-dimensional Function Plotting
 @subsubsection Two-dimensional Function Plotting
 @cindex plotting, two-dimensional functions
diff -r a315ac23dc6c -r 43fb7295dc6a scripts/plot/appearance/module.mk
--- a/scripts/plot/appearance/module.mk	Tue Aug 29 15:42:47 2017 -0700
+++ b/scripts/plot/appearance/module.mk	Wed Aug 30 14:06:19 2017 -0400
@@ -25,18 +25,27 @@
   %reldir%/material.m \
   %reldir%/orient.m \
   %reldir%/pbaspect.m \
+  %reldir%/rticks.m \
   %reldir%/shading.m \
   %reldir%/specular.m \
   %reldir%/text.m \
+  %reldir%/tticks.m \
   %reldir%/title.m \
   %reldir%/view.m \
   %reldir%/whitebg.m \
   %reldir%/xlabel.m \
   %reldir%/xlim.m \
+  %reldir%/xticks.m \
+  %reldir%/xticklabels.m \
   %reldir%/ylabel.m \
   %reldir%/ylim.m \
+  %reldir%/yticks.m \
+  %reldir%/yticklabels.m \
   %reldir%/zlabel.m \
   %reldir%/zlim.m
+  %reldir%/zticks.m \
+  %reldir%/zticklabels.m \
+  
 
 %canon_reldir%dir = $(fcnfiledir)/plot/appearance
 
diff -r a315ac23dc6c -r 43fb7295dc6a scripts/plot/appearance/rticks.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/plot/appearance/rticks.m	Wed Aug 30 14:06:19 2017 -0400
@@ -0,0 +1,122 @@
+## Copyright (C) 2017 Nicholas Jankowski
+## 
+## This program is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or
+## (at your option) any later version.
+## 
+## This program is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+## 
+## You should have received a copy of the GNU General Public License
+## along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*- 
+## @deftypefn  {} {@var{values} =} rticks
+## @deftypefnx {} rticks (@var{'values'})
+## @deftypefnx {} {@dots =} rticks (@var{hax}, @dots{})
+## Query or set the properties related to tick values on the r-axis of the 
+## current axis. 
+##
+## When @code{rticks} is called without argument, @code{rticks} returns the
+## current locations as specified in the @var{rtick} axis property. These values
+## can be changed by calling @code{rticks} with a vector of tick values. Note:
+## ascending order is not required. 
+##
+## If the first argument @var{hax} is an axes handle, then operate on
+## this axis rather than the current axes returned by @code{gca}.
+## 
+## Requesting a return value when calling @code{rticks} to set a property value
+## will result in an error. 
+##
+## NOTE:  Octave does not currently have polaraxes obects implented. It is
+## not currently possible to query or set a 'mode' for the @var{rtick} property
+## as can be done with equivalent functions for @var{x}, @var{y} and @var{z}
+## axes.
+##
+## @seealso{thetaticks, xticks, yticks, zticks, polar, get, set}
+## @end deftypefn
+
+## Author: Nicholas Jankowski <jankowskin@asme.org>
+## Created: 2017-08-24
+
+function [retval] = rticks (varargin)
+  
+  #identify and set input values, shortcut simple cases
+
+  switch nargin
+    case 0
+      retval = get (gca , "rtick"); #will error if no rtick exists.
+      return;  
+
+    case 1
+      axis_to_use = gca;
+      option = varargin{1};
+    
+    case 2
+      #if 2 inputs, first must specify an axis handle.
+      if (~ishandle (varargin{1}) || ishandle (varargin{2}))    
+        print_usage;
+      else
+        axis_to_use = varargin{1};
+        option = varargin{2};
+      endif
+      
+    otherwise
+      print_usage;
+      
+  endswitch
+  
+ # axis and option are set, perform requested actions based on 'option' class
+  if (ishandle (option))
+    retval = get (option, "rtick");
+    
+  elseif (ischar (option))
+    error("mode is currently not implemented for the rtick property")
+## FIXME:  enable mode options if/when they are enabled in polar or polarplot 
+##    option = tolower (option);
+##    switch option
+##      case "mode"
+##        retval = get (axis_to_use, "rtickmode");
+##
+##      case {"auto", "manual"}
+##        if (nargout > 0)
+##          error (["too many output arguments requested for option: ", option]);
+##        else
+##          set (axis_to_use, "rtickmode", option);
+##        endif
+##      otherwise 
+##        error (["invalid option "", option, """]);
+##    endswitch
+  
+  elseif (isnumeric (option))
+    if (nargout > 0)
+      error ("too many output arguments requested");
+    else  
+     ## NOTE: Matlab errors if tick points are not in ascending order. Octave 
+     ## permits out of order tick points, so error is not produced.
+     set (axis_to_use, "rtick", option);
+     
+    endif
+  else
+    print_usage;  
+  endif
+
+endfunction
+
+## Test input validation
+
+%!test
+%! hf = figure ("visible", "off");
+%! unwind_protect
+%! polar (linspace (0, pi, 20), rand(20,1));
+%!   hax = gca;
+%!   vals1 = rticks;
+%!   assert (rticks (hax), vals1);
+%!   rticks (hax, [0 0.25 0.75 1 2]);
+%!   assert (rticks (hax), [0 0.25 0.75 1 2]);
+%! unwind_protect_cleanup
+%!   close (hf);
+%! end_unwind_protect
\ No newline at end of file
diff -r a315ac23dc6c -r 43fb7295dc6a scripts/plot/appearance/thetaticks.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/plot/appearance/thetaticks.m	Wed Aug 30 14:06:19 2017 -0400
@@ -0,0 +1,125 @@
+## Copyright (C) 2017 Nicholas Jankowski
+## 
+## This program is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or
+## (at your option) any later version.
+## 
+## This program is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+## 
+## You should have received a copy of the GNU General Public License
+## along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*- 
+## @deftypefn  {} {@var{values} =} thetaticks
+## @deftypefnx {} thetaticks (@var{'values'})
+## @deftypefnx {} {@dots =} thetaticks (@var{hax}, @dots{})
+## Query or set the properties related to tick values on the r-axis of the 
+## current axis. 
+##
+## When @code{thetaticks} is called without argument, @code{thetaticks} returns the
+## current locations as specified in the @var{ttick} axis property. These values
+## can be changed by calling @code{thetaticks} with a vector of tick values. Note:
+## ascending order is not required. 
+##
+## If the first argument @var{hax} is an axes handle, then operate on
+## this axis rather than the current axes returned by @code{gca}.
+## 
+## Requesting a return value when calling @code{thetaticks} to set a property value
+## will result in an error. 
+##
+## NOTE:  Octave does not currently have polaraxes obects implented. It is
+## not currently possible to query or set a 'mode' for the @var{ttick} property
+## as can be done with equivalent functions for @var{x}, @var{y} and @var{z}
+## axes.
+##
+## @seealso{thetaticks, xticks, yticks, zticks, polar, get, set}
+## @end deftypefn
+
+## Author: Nicholas Jankowski <jankowskin@asme.org>
+## Created: 2017-08-24
+
+function [retval] = thetaticks (varargin)
+  
+  #identify and set input values, shortcut simple cases
+  ## FIXME: update function to work with polaraxes objects once that function
+  ##       is implement in octave. for compatibilty with matlab this may need
+  ##       to function with both the property names ttick and thetatick
+
+  switch nargin
+    case 0
+      retval = get (gca , "ttick"); #will error if no rtick exists.
+      return;  
+
+    case 1
+      axis_to_use = gca;
+      option = varargin{1};
+    
+    case 2
+      #if 2 inputs, first must specify an axis handle.
+      if (~ishandle (varargin{1}) || ishandle (varargin{2}))    
+        print_usage;
+      else
+        axis_to_use = varargin{1};
+        option = varargin{2};
+      endif
+      
+    otherwise
+      print_usage;
+      
+  endswitch
+  
+ # axis and option are set, perform requested actions based on 'option' class
+  if (ishandle (option))
+    retval = get (option, "ttick");
+    
+  elseif (ischar (option))
+    error ("mode is currently not implemented for the ttick property")
+## FIXME:  enable mode options if/when they are enabled in polar or polarplot 
+##    option = tolower (option);
+##    switch option
+##      case "mode"
+##        retval = get (axis_to_use, "ttickmode");
+##
+##      case {"auto", "manual"}
+##        if (nargout > 0)
+##          error (["too many output arguments requested for option: ", option]);
+##        else
+##          set (axis_to_use, "ttickmode", option);
+##        endif
+##      otherwise 
+##        error (["invalid option: ", option]);
+##    endswitch
+  
+  elseif (isnumeric (option))
+    if (nargout > 0)
+      error ("too many output arguments requested");
+    else  
+     ## NOTE: Matlab errors if tick points are not in ascending order. Octave 
+     ## permits out of order tick points, so error is not produced.
+     set (axis_to_use, "ttick", option);
+     
+    endif
+  else
+    print_usage;  
+  endif
+
+endfunction
+
+## Test input validation
+
+%!test
+%! hf = figure ("visible", "off");
+%! unwind_protect
+%! polar (linspace (0, pi, 20), rand(20,1));
+%!   hax = gca;
+%!   vals1 = thetaticks;
+%!   assert (thetaticks (hax), vals1);
+%!   thetaticks (hax, [0 45 90 135 180]);
+%!   assert (thetaticks (hax), [0 45 90 135 180]);
+%! unwind_protect_cleanup
+%!   close (hf);
+%! end_unwind_protect
\ No newline at end of file
diff -r a315ac23dc6c -r 43fb7295dc6a scripts/plot/appearance/xticklabels.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/plot/appearance/xticklabels.m	Wed Aug 30 14:06:19 2017 -0400
@@ -0,0 +1,153 @@
+## Copyright (C) 2017 Nicholas Jankowski
+## 
+## This program is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or
+## (at your option) any later version.
+## 
+## This program is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+## 
+## You should have received a copy of the GNU General Public License
+## along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*- 
+## @deftypefn  {} {@var{values} =} xticklabels
+## @deftypefnx {} {@var{mode} =} xticklabels (@var{'mode'})
+## @deftypefnx {} xticklabels (@var{'values'})
+## @deftypefnx {} xticklabels (@var{'mode'})
+## @deftypefnx {} {@dots =} xticklabels (@var{hax}, @dots{})
+## Query or set the properties related to labels for the x-axis tick marks of 
+## the current axis. 
+##
+## When @code{xticklabels} is called without argument, @code{xticklabels}
+## returns a cell array containing the current x-axis tick labels as specified
+## in the @var{xticklabel} axis property. These values can be changed by calling
+## @code{xticklabels} with a cell array of characters. Note: a vector of numbers
+## will be mapped to a cell array of characters. If fewer labels are specified 
+## than the current number of ticks, blank labels will be appended to the array.
+##
+## When called with argument @var{'mode'}, @code{xticklabels} returns the
+## current value of the axis property @var{'xticklabelmode'}, which should 
+## return either @var{'auto'} or @var{'manual'}.  This property can be changed
+## by calling @code{xticklabels} with either @var{'auto'} or @var{'manual'}.
+## Note: changing the @var{xticklabel_values} will also set both properties
+## @var{'xtickmode'} and @var{'xticklabelmode'} to @var{'manual'}.
+##
+## If the first argument @var{hax} is an axes handle, then operate on
+## this axis rather than the current axes returned by @code{gca}.
+##
+## Requesting a return value when calling @code{xticklabels} to set a property value
+## will result in an error. 
+##
+## @seealso{xticks, yticklabels, zticklabels, get, set}
+## @end deftypefn
+
+## Author: Nicholas Jankowski <jankowskin@asme.org>
+## Created: 2017-08-24
+
+function [retval] = xticklabels (varargin)
+  
+  #identify and set input values, shortcut simple cases
+
+  switch nargin
+    case 0
+      retval = get (gca , "xticklabel"); #will error if no xticklabel exists.
+      return;  
+
+    case 1
+      axis_to_use = gca;
+      option = varargin{1};
+    
+    case 2
+      #if 2 inputs, first must specify an axis handle.
+      if (~ishandle (varargin{1}) || ishandle (varargin{2}))    
+        print_usage;
+      else
+        axis_to_use = varargin{1};
+        option = varargin{2};
+      endif
+      
+    otherwise
+      print_usage;
+      
+  endswitch
+  
+ # axis and option are set, perform requested actions based on 'option' class
+  if (ishandle (option))
+    retval = get (option, "xticklabel");
+    
+  elseif (ischar (option))
+    option = tolower (option);
+    switch option
+      case "mode"
+        retval = get (axis_to_use, "xticklabelmode");
+
+      case {"auto", "manual"}
+        if (nargout > 0)
+          error (["too many output arguments requested for option: ", option]);
+        else
+          set (axis_to_use, "xticklabelmode", option);
+        endif
+      otherwise 
+        error (["invalid option: ", option]);
+    endswitch
+  
+  elseif (iscell (option) || isnumeric (option))
+    if (nargout > 0)
+      error ("too many output arguments requested");
+    else  
+      #if numeric convert to cell array of chars
+      if (isnumeric (option))
+        # NOTE: Matlab accepts a cell array, but non-vector numeric array  will
+        # simply produce a black set of labels without error or warning.
+        # this implementation allows for a numeric array, which is handled in
+        # the same order as Matlab handles a cell array
+        option = num2cell (option(:));
+        
+      endif
+
+      # convert any numeric elements to characters, make it a 1D cell array.
+      option = cellfun (@num2str, option, "UniformOutput", false)(:);
+      
+      # pad with blank cell entries if needed
+
+      option((numel (option) + 1):(numel (xticks (axis_to_use)))) = {""};
+                  
+      set (axis_to_use, "xticklabel", option);
+
+      # setting labels sets both tick and ticklabel mode to manual
+      set (axis_to_use, "xticklabelmode", "manual");
+      set (axis_to_use, "xtickmode", "manual");
+
+    endif
+  else
+    print_usage;  
+  endif
+
+endfunction
+
+## Test input validation
+
+%!test
+%! hf = figure ("visible", "off");
+%! unwind_protect
+%!   set (gca, "xticklabelmode", "auto");
+%!   hax = gca;
+%!   vals1 = xticklabels;
+%!   assert (xticklabels (hax), vals1);
+%!   mode1 = xticklabels ("mode");
+%!   assert (xticklabels (hax, "mode"), mode1);
+%!   xticklabels (hax, "manual");
+%!   assert (xticklabels (hax, "mode"), "manual");
+%!   xticklabels (hax, "auto");
+%!   assert (xticks (hax, "mode"), "auto");
+%!   xticklabels (hax, {"1", "2", "3", "4", "5", "6"});
+%!   assert (xticklabels (hax), {"1"; "2"; "3"; "4"; "5"; "6"});
+%!   assert (xticklabels (hax, "mode"), "manual");
+%!   assert (xticks (hax, "mode"), "manual");
+%! unwind_protect_cleanup
+%!   close (hf);
+%! end_unwind_protect
diff -r a315ac23dc6c -r 43fb7295dc6a scripts/plot/appearance/xticks.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/plot/appearance/xticks.m	Wed Aug 30 14:06:19 2017 -0400
@@ -0,0 +1,131 @@
+## Copyright (C) 2017 Nicholas Jankowski
+## 
+## This program is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or
+## (at your option) any later version.
+## 
+## This program is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+## 
+## You should have received a copy of the GNU General Public License
+## along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*- 
+## @deftypefn  {} {@var{values} =} xticks
+## @deftypefnx {} {@var{mode} =} xticks (@var{'mode'})
+## @deftypefnx {} xticks (@var{'values'})
+## @deftypefnx {} xticks (@var{'mode'})
+## @deftypefnx {} {@dots =} xticks (@var{hax}, @dots{})
+## Query or set the properties related to tick values on the x-axis of the 
+## current axis. 
+##
+## When @code{xticks} is called without argument, @code{xticks} returns the
+## current locations as specified in the @var{xtick} axis property. These values
+## can be changed by calling @code{xticks} with a vector of tick values. Note:
+## ascending order is not required. 
+##
+## When called with argument @var{'mode'}, @code{xticks} returns the current 
+## value of the axis property @var{'xtickmode'}, which should return either 
+## @var{'auto'} or @var{'manual'}.  This property can be changed by calling 
+## @code{xticks} with either @var{'auto'} or @var{'manual'}. Note: changing the
+## @var{xtick_values} will also set the property @var{'xtickmode'} to 
+## @var{'manual'}.
+##
+## If the first argument @var{hax} is an axes handle, then operate on
+## this axis rather than the current axes returned by @code{gca}.
+##
+## Requesting a return value when calling @code{xticks} to set a property value
+## will result in an error. 
+##
+## @seealso{xticklabels, yticks, zticks, rticks, thetaticks, get, set}
+## @end deftypefn
+
+## Author: Nicholas Jankowski <jankowskin@asme.org>
+## Created: 2017-08-24
+
+function [retval] = xticks (varargin)
+  
+  #identify and set input values, shortcut simple cases
+
+  switch nargin
+    case 0
+      retval = get (gca , "xtick"); #will error if no xtick exists.
+      return;  
+
+    case 1
+      axis_to_use = gca;
+      option = varargin{1};
+    
+    case 2
+      #if 2 inputs, first must specify an axis handle.
+      if (~ishandle (varargin{1}) || ishandle (varargin{2}))    
+        print_usage;
+      else
+        axis_to_use = varargin{1};
+        option = varargin{2};
+      endif
+      
+    otherwise
+      print_usage;
+      
+  endswitch
+  
+ # axis and option are set, perform requested actions based on 'option' class
+  if (ishandle (option))
+    retval = get (option, "xtick");
+    
+  elseif (ischar (option))
+    option = tolower(option);
+    switch option
+      case "mode"
+        retval = get (axis_to_use, "xtickmode");
+
+      case {"auto", "manual"}
+        if (nargout > 0)
+          error (["too many output arguments requested for option: ", option]);
+        else
+          set (axis_to_use, "xtickmode", option);
+        endif
+      otherwise 
+        error (["invalid option: ", option]);
+    endswitch
+  
+  elseif (isnumeric (option))
+    if (nargout > 0)
+      error ("too many output arguments requested");
+    else  
+     ## NOTE: Matlab errors if tick points are not in ascending order. Octave 
+     ## permits out of order tick points, so error is not produced.
+     set (axis_to_use, "xtick", option);
+     
+    endif
+  else
+    print_usage;  
+  endif
+
+endfunction
+
+## Test input validation
+
+%!test
+%! hf = figure ("visible", "off");
+%! unwind_protect
+%!   set (gca, "xtickmode", "auto");
+%!   hax = gca;
+%!   vals1 = xticks;
+%!   assert (xticks (hax), vals1);
+%!   mode1 = xticks ("mode");
+%!   assert (xticks (hax, "mode"), mode1);
+%!   xticks (hax, "manual");
+%!   assert (xticks (hax, "mode"), "manual");
+%!   xticks (hax, "auto");
+%!   assert (xticks (hax, "mode"), "auto");
+%!   xticks (hax, [1 2 3 4]);
+%!   assert (xticks (hax), [1 2 3 4]);
+%!   assert (xticks (hax, "mode"), "manual");
+%! unwind_protect_cleanup
+%!   close (hf);
+%! end_unwind_protect
\ No newline at end of file
diff -r a315ac23dc6c -r 43fb7295dc6a scripts/plot/appearance/yticklabels.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/plot/appearance/yticklabels.m	Wed Aug 30 14:06:19 2017 -0400
@@ -0,0 +1,153 @@
+## Copyright (C) 2017 Nicholas Jankowski
+## 
+## This program is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or
+## (at your option) any later version.
+## 
+## This program is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+## 
+## You should have received a copy of the GNU General Public License
+## along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*- 
+## @deftypefn  {} {@var{values} =} yticklabels
+## @deftypefnx {} {@var{mode} =} yticklabels (@var{'mode'})
+## @deftypefnx {} yticklabels (@var{'values'})
+## @deftypefnx {} yticklabels (@var{'mode'})
+## @deftypefnx {} {@dots =} yticklabels (@var{hax}, @dots{})
+## Query or set the properties related to labels for the x-axis tick marks of 
+## the current axis. 
+##
+## When @code{yticklabels} is called without argument, @code{yticklabels}
+## returns a cell array containing the current x-axis tick labels as specified
+## in the @var{yticklabel} axis property. These values can be changed by calling
+## @code{yticklabels} with a cell array of characters. Note: a vector of numbers
+## will be mapped to a cell array of characters. If fewer labels are specified 
+## than the current number of ticks, blank labels will be appended to the array.
+##
+## When called with argument @var{'mode'}, @code{yticklabels} returns the
+## current value of the axis property @var{'yticklabelmode'}, which should 
+## return either @var{'auto'} or @var{'manual'}.  This property can be changed
+## by calling @code{yticklabels} with either @var{'auto'} or @var{'manual'}.
+## Note: changing the @var{yticklabel_values} will also set both properties
+## @var{'ytickmode'} and @var{'yticklabelmode'} to @var{'manual'}.
+##
+## If the first argument @var{hax} is an axes handle, then operate on
+## this axis rather than the current axes returned by @code{gca}.
+##
+## Requesting a return value when calling @code{yticklabels} to set a property value
+## will result in an error. 
+##
+## @seealso{yticks, xticklabels, zticklabels, get, set}
+## @end deftypefn
+
+## Author: Nicholas Jankowski <jankowskin@asme.org>
+## Created: 2017-08-24
+
+function [retval] = yticklabels (varargin)
+  
+  #identify and set input values, shortcut simple cases
+
+  switch nargin
+    case 0
+      retval = get (gca , "yticklabel"); #will error if no yticklabel exists.
+      return;  
+
+    case 1
+      axis_to_use = gca;
+      option = varargin{1};
+    
+    case 2
+      #if 2 inputs, first must specify an axis handle.
+      if (~ishandle (varargin{1}) || ishandle (varargin{2}))    
+        print_usage;
+      else
+        axis_to_use = varargin{1};
+        option = varargin{2};
+      endif
+      
+    otherwise
+      print_usage;
+      
+  endswitch
+  
+ # axis and option are set, perform requested actions based on 'option' class
+  if (ishandle (option))
+    retval = get (option, "yticklabel");
+    
+  elseif (ischar (option))
+    option = tolower (option);
+    switch option
+      case "mode"
+        retval = get (axis_to_use, "yticklabelmode");
+
+      case {"auto", "manual"}
+        if (nargout > 0)
+          error (["too many output arguments requested for option: ", option]);
+        else
+          set (axis_to_use, "yticklabelmode", option);
+        endif
+      otherwise 
+        error (["invalid option: ", option]);
+    endswitch
+  
+  elseif (iscell (option) || isnumeric (option))
+    if (nargout > 0)
+      error ("too many output arguments requested");
+    else  
+      #if numeric convert to cell array of chars
+      if (isnumeric (option))
+        # NOTE: Matlab accepts a cell array, but non-vector numeric array  will
+        # simply produce a black set of labels without error or warning.
+        # this implementation allows for a numeric array, which is handled in
+        # the same order as Matlab handles a cell array
+        option = num2cell (option(:));
+        
+      endif
+
+      # convert any numeric elements to characters, make it a 1D cell array.
+      option = cellfun (@num2str, option, "UniformOutput", false)(:);
+      
+      # pad with blank cell entries if needed
+
+      option((numel (option) + 1):(numel (yticks (axis_to_use)))) = {""};
+                  
+      set (axis_to_use, "yticklabel", option);
+
+      # setting labels sets both tick and ticklabel mode to manual
+      set (axis_to_use, "yticklabelmode", "manual");
+      set (axis_to_use, "ytickmode", "manual");
+
+    endif
+  else
+    print_usage;  
+  endif
+
+endfunction
+
+## Test input validation
+
+%!test
+%! hf = figure ("visible", "off");
+%! unwind_protect
+%!   set (gca, "yticklabelmode", "auto");
+%!   hax = gca;
+%!   vals1 = yticklabels;
+%!   assert (yticklabels (hax), vals1);
+%!   mode1 = yticklabels ("mode");
+%!   assert (yticklabels (hax, "mode"), mode1);
+%!   yticklabels (hax, "manual");
+%!   assert (yticklabels (hax, "mode"), "manual");
+%!   yticklabels (hax, "auto");
+%!   assert (yticks (hax, "mode"), "auto");
+%!   yticklabels (hax, {"1", "2", "3", "4", "5", "6"});
+%!   assert (yticklabels (hax), {"1"; "2"; "3"; "4"; "5"; "6"});
+%!   assert (yticklabels (hax, "mode"), "manual");
+%!   assert (yticks (hax, "mode"), "manual");
+%! unwind_protect_cleanup
+%!   close (hf);
+%! end_unwind_protect
\ No newline at end of file
diff -r a315ac23dc6c -r 43fb7295dc6a scripts/plot/appearance/yticks.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/plot/appearance/yticks.m	Wed Aug 30 14:06:19 2017 -0400
@@ -0,0 +1,131 @@
+## Copyright (C) 2017 Nicholas Jankowski
+## 
+## This program is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or
+## (at your option) any later version.
+## 
+## This program is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+## 
+## You should have received a copy of the GNU General Public License
+## along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*- 
+## @deftypefn  {} {@var{values} =} yticks
+## @deftypefnx {} {@var{mode} =} yticks (@var{'mode'})
+## @deftypefnx {} yticks (@var{'values'})
+## @deftypefnx {} yticks (@var{'mode'})
+## @deftypefnx {} {@dots =} yticks (@var{hax}, @dots{})
+## Query or set the properties related to tick values on the y-axis of the 
+## current axis. 
+##
+## When @code{yticks} is called without argument, @code{yticks} returns the
+## current locations as specified in the @var{ytick} axis property. These values
+## can be changed by calling @code{yticks} with a vector of tick values. Note:
+## ascending order is not required. 
+##
+## When called with argument @var{'mode'}, @code{yticks} returns the current 
+## value of the axis property @var{'ytickmode'}, which should return either 
+## @var{'auto'} or @var{'manual'}.  This property can be changed by calling 
+## @code{yticks} with either @var{'auto'} or @var{'manual'}. Note: changing the
+## @var{ytick_values} will also set the property @var{'ytickmode'} to 
+## @var{'manual'}.
+##
+## If the first argument @var{hax} is an axes handle, then operate on
+## this axis rather than the current axes returned by @code{gca}.
+##
+## Requesting a return value when calling @code{yticks} to set a property value
+## will result in an error. 
+##
+## @seealso{yticklabels, xticks, zticks, rticks, thetaticks, get, set}
+## @end deftypefn
+
+## Author: Nicholas Jankowski <jankowskin@asme.org>
+## Created: 2017-08-24
+
+function [retval] = yticks (varargin)
+  
+  #identify and set input values, shortcut simple cases
+
+  switch nargin
+    case 0
+      retval = get (gca , "ytick"); #will error if no ytick exists.
+      return;  
+
+    case 1
+      axis_to_use = gca;
+      option = varargin{1};
+    
+    case 2
+      #if 2 inputs, first must specify an axis handle.
+      if (~ishandle (varargin{1}) || ishandle (varargin{2}))    
+        print_usage;
+      else
+        axis_to_use = varargin{1};
+        option = varargin{2};
+      endif
+      
+    otherwise
+      print_usage;
+      
+  endswitch
+  
+ # axis and option are set, perform requested actions based on 'option' class
+  if (ishandle (option))
+    retval = get (option, "ytick");
+    
+  elseif (ischar (option))
+    option = tolower (option);
+    switch option
+      case "mode"
+        retval = get (axis_to_use, "ytickmode");
+
+      case {"auto", "manual"}
+        if (nargout > 0)
+          error (["too many output arguments requested for option: ", option]);
+        else
+          set (axis_to_use, "ytickmode", option);
+        endif
+      otherwise 
+        error (["invalid option: ", option]);
+    endswitch
+  
+  elseif (isnumeric (option))
+    if (nargout > 0)
+      error ("too many output arguments requested");
+    else  
+     ## NOTE: Matlab errors if tick points are not in ascending order. Octave 
+     ## permits out of order tick points, so error is not produced.
+     set (axis_to_use, "ytick", option);
+     
+    endif
+  else
+    print_usage;  
+  endif
+
+endfunction
+
+## Test input validation
+
+%!test
+%! hf = figure ("visible", "off");
+%! unwind_protect
+%!   set (gca, "ytickmode", "auto");
+%!   hax = gca;
+%!   vals1 = yticks;
+%!   assert (yticks (hax), vals1);
+%!   mode1 = yticks ("mode");
+%!   assert (yticks (hax, "mode"), mode1);
+%!   yticks (hax, "manual");
+%!   assert (yticks (hax, "mode"), "manual");
+%!   yticks (hax, "auto");
+%!   assert (yticks (hax, "mode"), "auto");
+%!   yticks (hax, [1 2 3 4]);
+%!   assert (yticks (hax), [1 2 3 4]);
+%!   assert (yticks (hax, "mode"), "manual");
+%! unwind_protect_cleanup
+%!   close (hf);
+%! end_unwind_protect
\ No newline at end of file
diff -r a315ac23dc6c -r 43fb7295dc6a scripts/plot/appearance/zticklabels.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/plot/appearance/zticklabels.m	Wed Aug 30 14:06:19 2017 -0400
@@ -0,0 +1,153 @@
+## Copyright (C) 2017 Nicholas Jankowski
+## 
+## This program is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or
+## (at your option) any later version.
+## 
+## This program is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+## 
+## You should have received a copy of the GNU General Public License
+## along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*- 
+## @deftypefn  {} {@var{values} =} zticklabels
+## @deftypefnx {} {@var{mode} =} zticklabels (@var{'mode'})
+## @deftypefnx {} zticklabels (@var{'values'})
+## @deftypefnx {} zticklabels (@var{'mode'})
+## @deftypefnx {} {@dots =} zticklabels (@var{hax}, @dots{})
+## Query or set the properties related to labels for the x-axis tick marks of 
+## the current axis. 
+##
+## When @code{zticklabels} is called without argument, @code{zticklabels}
+## returns a cell array containing the current x-axis tick labels as specified
+## in the @var{zticklabel} axis property. These values can be changed by calling
+## @code{zticklabels} with a cell array of characters. Note: a vector of numbers
+## will be mapped to a cell array of characters. If fewer labels are specified 
+## than the current number of ticks, blank labels will be appended to the array.
+##
+## When called with argument @var{'mode'}, @code{zticklabels} returns the
+## current value of the axis property @var{'zticklabelmode'}, which should 
+## return either @var{'auto'} or @var{'manual'}.  This property can be changed
+## by calling @code{zticklabels} with either @var{'auto'} or @var{'manual'}.
+## Note: changing the @var{zticklabel_values} will also set both properties
+## @var{'ztickmode'} and @var{'zticklabelmode'} to @var{'manual'}.
+##
+## If the first argument @var{hax} is an axes handle, then operate on
+## this axis rather than the current axes returned by @code{gca}.
+##
+## Requesting a return value when calling @code{zticklabels} to set a property value
+## will result in an error. 
+##
+## @seealso{zticks, xticklabels, zticklabels, get, set}
+## @end deftypefn
+
+## Author: Nicholas Jankowski <jankowskin@asme.org>
+## Created: 2017-08-24
+
+function [retval] = zticklabels (varargin)
+  
+  #identify and set input values, shortcut simple cases
+
+  switch nargin
+    case 0
+      retval = get (gca , "zticklabel"); #will error if no zticklabel exists.
+      return;  
+
+    case 1
+      axis_to_use = gca;
+      option = varargin{1};
+    
+    case 2
+      #if 2 inputs, first must specify an axis handle.
+      if (~ishandle (varargin{1}) || ishandle (varargin{2}))    
+        print_usage;
+      else
+        axis_to_use = varargin{1};
+        option = varargin{2};
+      endif
+      
+    otherwise
+      print_usage;
+      
+  endswitch
+  
+ # axis and option are set, perform requested actions based on 'option' class
+  if (ishandle (option))
+    retval = get (option, "zticklabel");
+    
+  elseif (ischar (option))
+    option = tolower (option);
+    switch option
+      case "mode"
+        retval = get (axis_to_use, "zticklabelmode");
+
+      case {"auto", "manual"}
+        if (nargout > 0)
+          error (["too many output arguments requested for option: ", option]);
+        else
+          set (axis_to_use, "zticklabelmode", option);
+        endif
+      otherwise 
+        error (["invalid option: ", option]);
+    endswitch
+  
+  elseif (iscell (option) || isnumeric (option))
+    if (nargout > 0)
+      error ("too many output arguments requested");
+    else  
+      #if numeric convert to cell array of chars
+      if (isnumeric (option))
+        # NOTE: Matlab accepts a cell array, but non-vector numeric array  will
+        # simply produce a black set of labels without error or warning.
+        # this implementation allows for a numeric array, which is handled in
+        # the same order as Matlab handles a cell array
+        option = num2cell (option(:));
+        
+      endif
+
+      # convert any numeric elements to characters, make it a 1D cell array.
+      option = cellfun (@num2str, option, "UniformOutput", false)(:);
+      
+      # pad with blank cell entries if needed
+
+      option((numel (option) + 1):(numel (zticks (axis_to_use)))) = {""};
+                  
+      set (axis_to_use, "zticklabel", option);
+
+      # setting labels sets both tick and ticklabel mode to manual
+      set (axis_to_use, "zticklabelmode", "manual");
+      set (axis_to_use, "ztickmode", "manual");
+
+    endif
+  else
+    print_usage;  
+  endif
+
+endfunction
+
+## Test input validation
+
+%!test
+%! hf = figure ("visible", "off");
+%! unwind_protect
+%!   set (gca, "zticklabelmode", "auto");
+%!   hax = gca;
+%!   vals1 = zticklabels;
+%!   assert (zticklabels (hax), vals1);
+%!   mode1 = zticklabels ("mode");
+%!   assert (zticklabels (hax, "mode"), mode1);
+%!   zticklabels (hax, "manual");
+%!   assert (zticklabels (hax, "mode"), "manual");
+%!   zticklabels (hax, "auto");
+%!   assert (zticks (hax, "mode"), "auto");
+%!   zticklabels (hax, {"1", "2", "3", "4", "5", "6"});
+%!   assert (zticklabels (hax), {"1"; "2"; "3"; "4"; "5"; "6"});
+%!   assert (zticklabels (hax, "mode"), "manual");
+%!   assert (zticks (hax, "mode"), "manual");
+%! unwind_protect_cleanup
+%!   close (hf);
+%! end_unwind_protect
\ No newline at end of file
diff -r a315ac23dc6c -r 43fb7295dc6a scripts/plot/appearance/zticks.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/plot/appearance/zticks.m	Wed Aug 30 14:06:19 2017 -0400
@@ -0,0 +1,131 @@
+## Copyright (C) 2017 Nicholas Jankowski
+## 
+## This program is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or
+## (at your option) any later version.
+## 
+## This program is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+## 
+## You should have received a copy of the GNU General Public License
+## along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*- 
+## @deftypefn  {} {@var{values} =} zticks
+## @deftypefnx {} {@var{mode} =} zticks (@var{'mode'})
+## @deftypefnx {} zticks (@var{'values'})
+## @deftypefnx {} zticks (@var{'mode'})
+## @deftypefnx {} {@dots =} zticks (@var{hax}, @dots{})
+## Query or set the properties related to tick values on the z-axis of the 
+## current axis. 
+##
+## When @code{zticks} is called without argument, @code{zticks} returns the
+## current locations as specified in the @var{ztick} axis property. These values
+## can be changed by calling @code{zticks} with a vector of tick values. Note:
+## ascending order is not required. 
+##
+## When called with argument @var{'mode'}, @code{zticks} returns the current 
+## value of the axis property @var{'ztickmode'}, which should return either 
+## @var{'auto'} or @var{'manual'}.  This property can be changed by calling 
+## @code{zticks} with either @var{'auto'} or @var{'manual'}. Note: changing the
+## @var{ztick_values} will also set the property @var{'ztickmode'} to 
+## @var{'manual'}.
+##
+## If the first argument @var{hax} is an axes handle, then operate on
+## this axis rather than the current axes returned by @code{gca}.
+##
+## Requesting a return value when calling @code{zticks} to set a property value
+## will result in an error. 
+##
+## @seealso{zticklabels, xticks, yticks, rticks, thetaticks, get, set}
+## @end deftypefn
+
+## Author: Nicholas Jankowski <jankowskin@asme.org>
+## Created: 2017-08-24
+
+function [retval] = zticks (varargin)
+  
+  #identify and set input values, shortcut simple cases
+
+  switch nargin
+    case 0
+      retval = get (gca , "ztick"); #will error if no ztick exists.
+      return;  
+
+    case 1
+      axis_to_use = gca;
+      option = varargin{1};
+    
+    case 2
+      #if 2 inputs, first must specify an axis handle.
+      if (~ishandle (varargin{1}) || ishandle (varargin{2}))    
+        print_usage;
+      else
+        axis_to_use = varargin{1};
+        option = varargin{2};
+      endif
+      
+    otherwise
+      print_usage;
+      
+  endswitch
+  
+ # axis and option are set, perform requested actions based on 'option' class
+  if (ishandle (option))
+    retval = get (option, "ztick");
+    
+  elseif (ischar (option))
+    option = tolower (option);
+    switch option
+      case "mode"
+        retval = get (axis_to_use, "ztickmode");
+
+      case {"auto", "manual"}
+        if (nargout > 0)
+          error (["too many output arguments requested for option: ", option]);
+        else
+          set (axis_to_use, "ztickmode", option);
+        endif
+      otherwise 
+        error (["invalid option: ", option]);
+    endswitch
+  
+  elseif (isnumeric (option))
+    if (nargout > 0)
+      error ("too many output arguments requested");
+    else  
+     ## NOTE: Matlab errors if tick points are not in ascending order. Octave 
+     ## permits out of order tick points, so error is not produced.
+     set (axis_to_use, "ztick", option);
+     
+    endif
+  else
+    print_usage;  
+  endif
+
+endfunction
+
+## Test input validation
+
+%!test
+%! hf = figure ("visible", "off");
+%! unwind_protect
+%!   set (gca, "ztickmode", "auto");
+%!   hax = gca;
+%!   vals1 = zticks;
+%!   assert (zticks (hax), vals1);
+%!   mode1 = zticks ("mode");
+%!   assert (zticks (hax, "mode"), mode1);
+%!   zticks (hax, "manual");
+%!   assert (zticks (hax, "mode"), "manual");
+%!   zticks (hax, "auto");
+%!   assert (zticks (hax, "mode"), "auto");
+%!   zticks (hax, [1 2 3 4]);
+%!   assert (zticks (hax), [1 2 3 4]);
+%!   assert (zticks (hax, "mode"), "manual");
+%! unwind_protect_cleanup
+%!   close (hf);
+%! end_unwind_protect
\ No newline at end of file
