#-------------------------------------------------------------
#
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.
#
#-------------------------------------------------------------

# This builtin function implements SliceLine, a linear-algebra-based
# ML model debugging technique for finding the top-k data slices where
# a trained models performs significantly worse than on the overall
# dataset. For a detailed description and experimental results, see:
# Svetlana Sagadeeva, Matthias Boehm: SliceLine: Fast, Linear-Algebra-based
# Slice Finding for ML Model Debugging.(SIGMOD 2021)
#
# INPUT:
# ------------------------------------------------------------------------------
# X        Feature matrix in recoded/binned representation
# e        Error vector of trained model
# k        Number of subsets required
# maxL     maximum level L (conjunctions of L predicates), 0 unlimited
# minSup   minimum support (min number of rows per slice)
# alpha    weight [0,1]: 0 only size, 1 only error
# tpEval   flag for task-parallel slice evaluation,
#          otherwise data-parallel
# tpBlksz  block size for task-parallel execution (num slices)
# selFeat  flag for removing one-hot-encoded features that don't satisfy
#          the initial minimum-support constraint and/or have zero error
# verbose  flag for verbose debug output
# ------------------------------------------------------------------------------
#
# OUTPUT:
# ------------------------------------------------------------------------------
# TK    top-k slices (k x ncol(X) if successful)
# TKC   score, total/max error, size of slices (k x 4)
# D     debug matrix, populated with enumeration stats if verbose
# ------------------------------------------------------------------------------

m_slicefinder = function(Matrix[Double] X, Matrix[Double] e, Int k = 4,
    Int maxL = 0, Int minSup = 32, Double alpha = 0.5, Boolean tpEval = TRUE,
    Int tpBlksz = 16, Boolean selFeat = FALSE, Boolean verbose = FALSE)
  return(Matrix[Double] TK, Matrix[Double] TKC, Matrix[Double] D)
{
  # rediction to sliceLine for backwards compatibility
  [TK,TKC,D] = sliceLine(X=X, e=e, k=k, maxL=maxL, minSup=minSup, alpha=alpha,
                 tpEval=tpEval, tpBlksz=tpBlksz, selFeat=selFeat, verbose=verbose)
}

