function [AX] = plotPartialDependence(model,features,X,varargin)
%PLOTPARTIALDEPENDENCE Partial Dependence Plot for 1-D or 2-D visualization
%
%   plotPartialDependence(MODEL,VAR,DATA) creates a plot of the partial
%   dependence of the response by a blackbox model MODEL on the predictor
%   VAR. The blackbox model to be interpreted can be specified as a
%   function handle. VAR is a scalar containing the index of a predictor
%   or a character array specifying a predictor name. DATA is a matrix or
%   table to be used as predictor data. DATA is required when MODEL is a
%   function handle.
%
%   plotPartialDependence(MODEL,VARS,DATA) creates a partial dependence plot
%   of response by a blackbox model MODEL against two predictors VARS.
%   VARS is either a string or cell array containing two predictor names,
%   or a two-element vector containing the indices of two predictors.
%
%   plotPartialDependence(...,Name,Value) specifies additional options using
%   one or more name-value arguments:
%
%   'Conditional'               'none' (default) instructs the method to create
%                               only a partial dependence plot, 'absolute'
%                               to create an individual conditional
%                               expectation (ICE) plot, and 'centered' to
%                               create an ICE plot with centered data.
%
%   'NumObservationsToSample'   An integer specifying the number
%                               of rows to sample at random from the data set.
%                               The default is to use all rows.
%
%   'QueryPoints'               The points at which to calculate
%                               the partial dependence. For the case of a
%                               single predictor, the value of 'QueryPoints'
%                               must be a column vector. For the case of two
%                               predictors, the value of 'QueryPoints' must be
%                               a 1x2 cell array containing a separate vector
%                               for each predictor. The default is to use 100
%                               points equally spaced across the range of the
%                               predictor.
%
%   'UseParallel'               Can be true to instruct the function to perform
%                               the averaging calculations in parallel (using
%                               parfor), or false (default) to instruct the
%                               function not to use parallel computations.
%
%   'Parent'                    Instructs the method to create a partial
%                               dependence plot using the axes with handle
%                               specified by the value of this parameter.
%                               Default is to create axes in a new figure.
%
%   'CategoricalPredictors'     List of categorical predictors when MODEL
%                               is a function handle. Pass 'CategoricalPredictors'
%                               as one of:
%                               * A numeric vector with indices between 1 and P,
%                                 where P is the number of predictor
%                                 variables.
%                               * A logical vector of length P, where a true
%                               entry means that the corresponding predictor
%                               is a categorical variable.
%                               * 'all', meaning all predictors are categorical.
%                               * A string array or cell array of character
%                                 vectors, where each element in the array is
%                                 the name of a predictor variable. The names
%                                 must match variable names in table DATA.
%                               Default: for a matrix input DATA, no categorical
%                               predictors; for a table DATA, predictors are
%                               treated as categorical if they are character
%                               array, string array, cell arrays of character
%                               vectors, logical, or of type 'categorical'.
%
%   'OutputColumns'             List of output columns of function handle
%                               to be considered for PD. Pass 'OutputColumns'
%                               as one of:
%                               * A numeric vector with indices between 1 and M,
%                                 where M is the number of columns returned as output
%                                 from the function handle MODEL.
%                               * A logical vector of length M, where a true
%                                 entry means that the corresponding output column
%                                 is considered for computing PD.
%                               * 'all', meaning all output columns are considered
%                                 for computing PD.
%                               The default value is 'all'.
%
%   AX = plotPartialDependence(...) returns a handle AX to the axes of the
%   plot.
%
%   See also
%   classreg.learning.classif.FullClassificationModel/plotPartialDependence,
%   classreg.learning.regr.FullRegressionModel/plotPartialDependence.

%   Copyright 2021-2023 The MathWorks, Inc.

[varargin{:}] = convertStringsToChars(varargin{:});

% Verify model is a function handle
isFunctionHandle = isa(model, 'function_handle');
if ~isFunctionHandle
    error(message('stats:responsible:plotPartialDependence:ModelFuncHandle'));
end

% Check inputs with inputParser. This step ensures that only
% allowed Name-Value pairs are passed.
p = inputParser;
addRequired(p,'Model');
addRequired(p,'Var');
addRequired(p,'Data',@(data)validateattributes(data,{'single','double','table'},...
    {'nonempty','2d','real'}));
addParameter(p,'Conditional',{'none' 'absolute' 'centered'});
addParameter(p,'NumObservationsToSample',0);
addParameter(p,'QueryPoints',[]);
addParameter(p,'UseParallel',false);
addParameter(p,'ParentAxisHandle',[]);
addParameter(p,'CategoricalPredictors',[]);
addParameter(p,'OutputColumns',[]);
parse(p,model,features,X,varargin{:});

% Models as Function Handle are treated as classification problems since
% multiple outputs (response/score) can be returned.
classif = true;
label   = [];

% Call the function plotPartialDependence from classreg.learning.impl
ax = responsible.impl.plotPartialDependence(...
    model,features,label,X,classif,varargin{:});
if(nargout > 0)
    AX = ax;
end
end
