sharp.ShaRP

class sharp.ShaRP(qoi=None, target_function=None, measure='shapley', sample_size=None, coalition_size=None, replace=False, random_state=None, n_jobs=1, verbose=0, **kwargs)

The ShaRP (Shapley for Rankings and Preferences) class provides a novel framework for explaining the contributions of features to various aspects of ranked outcomes. Built on Shapley values, it quantifies feature importance for rankings, which is fundamentally different from feature importance in classification or regression. This framework is essential for understanding, auditing, and improving algorithmic ranking systems in critical domains such as hiring, education, and lending.

ShaRP extends the Quantitative Input Influence (QII) framework to compute feature contributions to multiple ranking-specific Quantities of Interest (QoIs). These QoIs include: - Score: Contribution of features to an item’s score. - Rank: Impact of features on an item’s rank. - Top-k: Influence of features on whether an item appears in the top-k positions. - Pairwise Preference: Contribution of features to the relative order between two items.

ShaRP uses Shapley values, a cooperative game theory concept, to distribute the “value” of a ranked outcome among the features. For each QoI, the class: - Constructs feature coalitions by masking subsets of features. - Evaluates the impact of these coalitions on the QoI using a payoff function. - Aggregates the marginal contributions of features across all possible coalitions to compute their Shapley values.

This algorithm is an implementation of Shapley for Rankings and Preferences (ShaRP), as presented in [1].

Parameters:

qoistr, optional

The quantity of interest to compute feature contributions for. Options include: - “score” : Contribution to an item’s score. - “rank” : Contribution to an item’s rank. - “top-k” : Contribution to whether an item appears in the top-k. - “pairwise” : Contribution to the relative order between two items. By default, in method fit(), “rank” will be used. If QoI is None, target_function and parameters X and y need to be passed.

target_functionfunction, optional

A custom function defining the outcome of interest for the data. Ignored if qoi is specified.

measurestr, default=”shapley”

The method used to compute feature contributions. Options include: - “set” - “marginal” - “shapley” - “banzhaff”

sample_sizeint, optional

The number of perturbations to apply per data point when calculating feature importance. Default is None, which uses all available samples.

coalition_sizeint, optional

The maximum size of feature coalitions to consider. Default is None, which uses all features except one.

replacebool, default=False

Whether to sample feature values with replacement during perturbation.

random_stateint, RandomState instance, or None, optional

Seed or random number generator for reproducibility. Default is None.

n_jobsint, default=1

Number of jobs to run in parallel for computations. Use -1 to use all available processors.

verboseint, default=0

Verbosity level. Use 0 for no output and higher numbers for more verbose output.

kwargsdict, optional

Additional parameters such as: - X : array-like, reference input data. - y : array-like, target outcomes for the reference data.

Methods

all([X, y])	Provides an explanation for all sample points based on reference dataset
feature(feature[, X, y])	Provides an explanation for all sample points for a specified feature based on reference dataset
fit(X[, y])	Fit a ShaRP model to the given data.
get_metadata_routing()	Get metadata routing of this object.
get_params([deep])	Get parameters for this estimator.
individual(sample[, X, y])	Provides an explanation for individual sample point based on reference dataset
pairwise(sample1, sample2, **kwargs)	Compare two samples, or one sample against a set of samples.
pairwise_set(samples1, samples2, **kwargs)	Pairwise comparison of two samples sets.
set_params(**params)	Set the parameters of this estimator.

Notes

See the original paper: [1] for more details.

References

[1] (1,2)

V. Pliatsika, J. Fonseca, T. Wang, J. Stoyanovich, “ShaRP: Explaining Rankings with Shapley Values”, Under submission.

all(X=None, y=None, **kwargs)

Provides an explanation for all sample points based on reference dataset

Note

set_cols_idx should be passed in kwargs if measure is marginal

Parameters:

featurestr or int

Name or index of the targeted feature

Xarray-like, shape (n_samples, n_features), default=None

Reference dataset used to compute explanations.

yarray-like, shape (n_samples,), default=None

Target variable.

set_cols_idx1D array-like, default=None

Features in the coalition used to construct composite points to estimate feature importance.

coalition_sizeint, default=n_features-1

Maximum number of features used during the construction of composite points.

sample_sizeint, default=n_samples

Maximum number of samples used during the construction of composite points.

Returns:

array-like, shape (n_samples, n_features)

Contribution of each feature to a point’s qoi

feature(feature, X=None, y=None, **kwargs)

Provides an explanation for all sample points for a specified feature based on reference dataset

Note

set_cols_idx should be passed in kwargs if measure is marginal

Parameters:

featurestr or int

Name or index of the targeted feature

Xarray-like, shape (n_samples, n_features), default=None

Reference dataset used to compute explanations.

yarray-like, shape (n_samples,), default=None

Target variable.

set_cols_idx1D array-like, default=None

Features in the coalition used to construct composite points to estimate feature importance.

coalition_sizeint, default=n_features-1

Maximum number of features used during the construction of composite points.

sample_sizeint, default=n_samples

Maximum number of samples used during the construction of composite points.

Returns:

float

Average contributions of a specific feature along all sample points.

fit(X, y=None)

Fit a ShaRP model to the given data.

Parameters:

X: array-like, shape (n_samples, n_features)

Reference dataset used to compute explanations.

y: array-like, shape (n_samples,), default=None

Target variable.

get_metadata_routing()

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:

routingMetadataRequest

A MetadataRequest encapsulating routing information.

get_params(deep=True)

Get parameters for this estimator.

Parameters:

deepbool, default=True

If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

paramsdict

Parameter names mapped to their values.

individual(sample, X=None, y=None, **kwargs)

Provides an explanation for individual sample point based on reference dataset

Note

set_cols_idx should be passed in kwargs if measure is marginal

Parameters:

samplearray-like, shape (n_features,) or int

Sample to calculate explanation for. Can be passed directly or as an index in a reference dataset.

Xarray-like, shape (n_samples, n_features), default=None

Reference dataset used to compute explanations.

yarray-like, shape (n_samples,), default=None

Target variable.

set_cols_idx1D array-like, default=None

Features in the coalition used to construct composite points to estimate feature importance.

coalition_sizeint, default=n_features-1

Maximum number of features used during the construction of composite points.

sample_sizeint, default=n_samples

Maximum number of samples used during the construction of composite points.

Returns:

1D array-like, shape (n_features,)

Influences of each feature on individual sample.

pairwise(sample1, sample2, **kwargs)

Compare two samples, or one sample against a set of samples. If sample1 or sample2 are of type int or list, X also needs to be passed.

Note

set_cols_idx should be passed in kwargs if measure is marginal

Parameters:

sample1array-like or int or list

Sample or indices of samples that are used to calculate contributions.

sample2array-like or int or list

Sample or indices of samples against which contributions are calculated.

Xarray-like, shape (n_samples, n_features), default=None

Reference dataset used to compute explanations.

yarray-like, shape (n_samples,), default=None

Target variable.

set_cols_idx1D array-like, default=None

Features in the coalition used to construct composite points to estimate feature importance.

coalition_sizeint, default=n_features-1

Maximum number of features used during the construction of composite points.

sample_sizeint, default=n_samples

Maximum number of samples used during the construction of composite points.

Returns:

array-like

Contributions of each feature to each sample1 point’s qoi

pairwise_set(samples1, samples2, **kwargs)

Pairwise comparison of two samples sets.

Note

if elements of samples1 or samples2 are of type int or list, X also needs to be passed.

Note

set_cols_idx should be passed in kwargs if measure is marginal

Parameters:

samples1array-like

Set of samples or indices that are used to calculate contributions.

samples2array-like

Set of samples or indices against which contributions are calculated.

Xarray-like, shape (n_samples, n_features), default=None

Reference dataset used to compute explanations.

yarray-like, shape (n_samples,), default=None

Target variable.

set_cols_idx1D array-like, default=None

Features in the coalition used to construct composite points to estimate feature importance.

coalition_sizeint, default=n_features-1

Maximum number of features used during the construction of composite points.

sample_sizeint, default=n_samples

Maximum number of samples used during the construction of composite points.

Returns:

array-like

Contributions for each sample from samples1 against respective sample in

samples2

set_params(**params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:

**paramsdict

Estimator parameters.

Returns:

selfestimator instance

Estimator instance.