Explainers

Below are the list of explainers that are available in ROSE.

Explainer(Generic Class)

Explainer for Alternating Least Squares of Matrix Factorization for Implicit Feedback Datasets (ALS)

class cornac.explainer.exp_als.Exp_ALS(rec_model, dataset, name='Exp_ALS')[source]

Alternating Least Squares of Matrix Factorization for implicit feedback datasets.

Parameters:

rec_model (object, recommender model) – The recommender model to be explained.
dataset (object, dataset) – The dataset object that is used to explain.
name (string, optional, default: 'Exp_ALS')

References

[1] Y. Hu, Y. Koren, and C. Volinsky, “Collaborative Filtering for Implicit Feedback Datasets,” in 2008 Eighth IEEE International Conference on Data Mining, Pisa, Italy: IEEE, Dec. 2008, pp. 263-272. doi: 10.1109/ICDM.2008.22.

[2] https://github.com/ludovikcoba/recoxplainer/blob/master/recoxplainer/explain/model_based_als_explain.py

explain_one_recommendation_to_user(user_id, item_id, **kwargs)[source]

Provide explanation for one user and one item

Parameters:

user_id (str) – One user’s id.
item_id (str) – One item’s id.
feature_k (int, optional, default:10) – Number of features in explanations created by explainer.

Returns:

explanations – Items and their contributions.

Return type:

dict

Counterfactual Explainable Recommendation (Counter)

Explainer for Explicit Factor Model (EFM_Mod)

class cornac.explainer.exp_efm_mod.Exp_EFM_Mod(rec_model, dataset, name='Exp_EFM_Mod')[source]

Explainer for EFM (Explicit Factor Model) with filter.

Parameters:

rec_model (object, recommender model) – The recommender model to be explained.
dataset (object, dataset) – The dataset object that is used to explain.
name (string, optional, default: 'Exp_EFM_Mod')

References

[1] Yongfeng Zhang, Guokun Lai, Min Zhang, Yi Zhang, Yiqun Liu, and Shaoping Ma. 2014. Explicit factor models for explainable recommendation based on phrase-level sentiment analysis. https://doi.org/10.1145/2600428.2609579

[2] https://github.com/PreferredAI/tutorials/blob/master/recommender-systems/07_explanations.ipynb

explain_one_recommendation_to_user(user_id, item_id, **kwargs)[source]

Get aspect with the highest score of the item, and at the same time, being the user’s most cared aspect.

Parameters:

user_id (str) – One user’s id.
item_id (str) – One item’s id.
feature_k (int, optional, default:3) – Number of features in explanations created by explainer.
threshold (float, optional, default:3.0) – Threshold for the aspect score to be considered in the explanation.

Returns:

explanation – Explanations as a dictionary of aspect and score.

Return type:

dict

Explainer for Explicit Factor Model (EFM)

class cornac.explainer.exp_efm.Exp_EFM(rec_model, dataset, name='Exp_EFM')[source]

Explainer for EFM (Explicit Factor Model).

Parameters:

rec_model (object, recommender model) – The recommender model to be explained.
dataset (object, dataset) – The dataset object that is used to explain.
name (string, optional, default: 'Exp_EFM')

References

[1] Yongfeng Zhang, Guokun Lai, Min Zhang, Yi Zhang, Yiqun Liu, and Shaoping Ma. 2014. Explicit factor models for explainable recommendation based on phrase-level sentiment analysis. https://doi.org/10.1145/2600428.2609579

[2] https://github.com/PreferredAI/tutorials/blob/master/recommender-systems/07_explanations.ipynb

explain_one_recommendation_to_user(user_id, item_id, **kwargs)[source]

Get aspect with the highest score of the item, and at the same time, being the user’s most cared aspect.

Parameters:

user_id (str) – One user’s id.
item_id (str) – One item’s id.
feature_k (int, optional, default:3) – Number of features in explanations created by explainer.

Returns:

explanation – Explanations as a dictionary of aspect and score.

Return type:

dict

Explainers for Explainable Recommendation with Comparative Constraints on Product Aspects (ComparER)

class cornac.explainer.exp_comparer_obj.Exp_ComparERObj(rec_model, dataset, name='Exp_ComparERObj')[source]

Explainer for ComparERObj (Explainable Recommendation with Comparative Constraints on Product Aspects.)

Parameters:

rec_model (object, recommender model) – The recommender model to be explained.
dataset (object, dataset) – The dataset object that is used to explain.
name (string, optional, default: 'Exp_ComparERObj')

References

[1] Trung-Hoang Le and Hady W. Lauw. “Explainable Recommendation with Comparative Constraints on Product Aspects.” ACM International Conference on Web Search and Data Mining (WSDM). 2021.

[2] Yongfeng Zhang, Guokun Lai, Min Zhang, Yi Zhang, Yiqun Liu, and Shaoping Ma. 2014. Explicit factor models for explainable recommendation based on phrase-level sentiment analysis. https://doi.org/10.1145/2600428.2609579

[3] https://github.com/PreferredAI/tutorials/blob/master/recommender-systems/07_explanations.ipynb

explain_one_recommendation_to_user(user_id, item_id, **kwargs)[source]

Get aspect with the highest score of the item, and at the same time, being the user’s most cared aspect.

Parameters:

user_id (str) – One user’s id.
item_id (str) – One item’s id.
feature_k (int, optional, default:3) – Number of features in explanations created by explainer.

Returns:

explanation – Explanations as a dictionary of aspect and score.

Return type:

dict

class cornac.explainer.exp_comparer_obj_mod.Exp_ComparERObj_Mod(rec_model, dataset, name='Exp_EFM_Mod')[source]

Explainer for ComparERObj (Explainable Recommendation with Comparative Constraints on Product Aspects.) with filter.

Parameters:

rec_model (object, recommender model) – The recommender model to be explained.
dataset (object, dataset) – The dataset object that is used to explain.
name (string, optional, default: 'Exp_ComparERObj_Mod')

References

[1] Trung-Hoang Le and Hady W. Lauw. “Explainable Recommendation with Comparative Constraints on Product Aspects.” ACM International Conference on Web Search and Data Mining (WSDM). 2021.

[2] Yongfeng Zhang, Guokun Lai, Min Zhang, Yi Zhang, Yiqun Liu, and Shaoping Ma. 2014. Explicit factor models for explainable recommendation based on phrase-level sentiment analysis. https://doi.org/10.1145/2600428.2609579

[3] https://github.com/PreferredAI/tutorials/blob/master/recommender-systems/07_explanations.ipynb

explain_one_recommendation_to_user(user_id, item_id, **kwargs)[source]

Get aspect with the highest score of the item, and at the same time, being the user’s most cared aspect.

Parameters:

user_id (str) – One user’s id.
item_id (str) – One item’s id.
feature_k (int, optional, default:3) – Number of features in explanations created by explainer.
threshold (float, optional, default:3.0) – Threshold for the aspect score to be considered in the explanation.

Returns:

explanation – Explanations as a dictionary of aspect and score.

Return type:

dict

class cornac.explainer.exp_comparer_sub.Exp_ComparERSub(rec_model, dataset, name='Exp_ComparERSub')[source]

Explainer for Explainable Recommendation with Comparative Constraints on Subjective Aspect-Level Quality

Parameters:

rec_model (object, recommender model) – The recommender model to be explained.
dataset (object, dataset) – The dataset object that is used to explain.
name (string, optional, default: 'Exp_ComparERSub')

References

[1] Trung-Hoang Le and Hady W. Lauw. “Explainable Recommendation with Comparative Constraints on Product Aspects.” ACM International Conference on Web Search and Data Mining (WSDM). 2021.

[2] Explainable Recommendation via Multi-Task Learning in Opinionated Text Data. https://arxiv.org/pdf/1806.03568.pdf

[3] https://github.com/PreferredAI/tutorials/blob/master/recommender-systems/07_explanations.ipynb

explain_one_recommendation_to_user(user_id, item_id, **kwargs)[source]

Get aspect performs best and user’s opinion word of that aspect.

Parameters:

user_id (str) – One user’s id.
item_id (str) – One item’s id.
feature_k (int, optional, default:3) – Number of features in explanations created by explainer.
num_top_opinions (int, optional, default:3) – Number of opinions used to explain each aspect.

Returns:

explanation – Explanations as {aspect: [{opinion: score}, {opinion: score}, …}], aspect: [{opinion: score}, {opinion: score}, …]}

Return type:

dict

Explainer for Explainable Matrix Factorization (EMF)

class cornac.explainer.exp_emf.Exp_EMF(rec_model, dataset, name='Exp_EMF')[source]

Explainer from Explainable Matrix Factorization for Collaborative Filtering. Explains by W matrix in the paper.

Parameters:

rec_model (object, recommender model) – The recommender model to be explained.
dataset (object, dataset) – The dataset object that is used to explain.
name (string, optional, default: 'Exp_EMF')

References

[1] B. Abdollahi and O. Nasraoui, “Explainable Matrix Factorization for Collaborative Filtering,” ACM Press, 2016, pp. 5-6. doi: 10.1145/2872518.2889405.

explain_one_recommendation_to_user(user_id, item_id, **kwargs)[source]

Provide explanation for one user and one item

Parameters:

user_id (str) – One user’s id.
item_id (str) – One item’s id.

Returns:

explanations – The W matrix value of the user and item.

Return type:

float

Explainer for Personalised novel and explainable matrix factorisation (NEMF)

class cornac.explainer.exp_nemf.Exp_NEMF(rec_model, dataset, name='Exp_NEMF')[source]

Explainer for Personalised novel and explainable matrix factorisation. Explains by E matrix in the paper.

Parameters:

rec_model (object, recommender model) – The recommender model to be explained.
dataset (object, dataset) – The dataset object that is used to explain.
name (string, optional, default: 'Exp_NEMF')

References

[1] L. Coba, P. Symeonidis, and M. Zanker, “Personalised novel and explainable matrix factorisation,” Data & Knowledge Engineering, vol. 122, pp. 142-158, Jul. 2019, doi: 10.1016/j.datak.2019.06.003.

explain_one_recommendation_to_user(user_id, item_id, **kwargs)[source]

Provide explanation for one user and one item

Parameters:

user_id (str) – One user’s id.
item_id (str) – One item’s id.

Returns:

explanations – The W matrix value of the user and item.

Return type:

float

Locally Interpretable Model-agnostic Explanations (LIMERS)

class cornac.explainer.exp_limers.Exp_LIMERS(rec_model, dataset, num_samples=100, name='Exp_LIMERS', mode='regression', kernel_width=25, verbose=False, class_names=array(['rec'], dtype='<U3'), feature_selection='highest_weights', random_state=None)[source]

Local Interpretable Model-agnostic Explainer for Recommender System

Parameters:

rec_model (object, recommender model) – The recommender model to be explained.
dataset (object, dataset) – The dataset object that is used to explain.
num_samples (int, optional, default: 100) – Number of samples to be generated for explanation
name (string, optional, default: 'Exp_LIMERS')
mode (string, optional, default: 'regression') – The mode of the explainer. Options: ‘regression’, ‘classification’ Note: ‘classification’ is not implemented
kernel_width (int, optional, default: 25) – Used to fit kernel function
verbose (bool, optional, default: False) – (LIME base) If true, print local prediction values from linear model.
class_names (list, optional, default: np.array(["rec"])) – (LIME base) List of class names (only used for classification)
feature_selection (string, optional, default: 'highest_weights') –
(LIME base) How to select feature_k. Options are:
- ’forward_selection’: iteratively add features to the model. This is costly when feature_k is high
- ’highest_weights’: selects the features that have the highest product of absolute weight * original data point when learning with all the features
- ’lasso_path’: chooses features based on the lasso regularization path
- ’none’: uses all features, ignores feature_k
- ’auto’: uses forward_selection if feature_k <= 6, and ‘highest_weights’ otherwise.
random_state (int or numpy.RandomState, optional, default: None) – (LIME base) An integer or numpy.RandomState that will be used to generate random numbers. If None, the random state will be initialized using the internal numpy seed.

References

[1] Caio Nóbrega and Leandro Marinho. 2019. Towards explaining recommendations through local surrogate models. https://doi.org/10.1145/3297280.3297443

explain_instance(user_idx, item_idx, neighborhood_entity, feature_k=10, labels=(1,), distance_metric='cosine', model_regressor=None)[source]

Provide explanations for one instance of (user_idx, item_idx)

Parameters:

user_idx (int, required) – Index of user to be explained
item_idx (int, required) – Index of item to be explained
neighborhood_entity (string, optional, default: "item") – Rule for selecting samples. Options: “user”, “item”, or ??
labels (list, optional, default: (1,)) – Only the first is used for regression task
feature_k (int, optional, default: 10) – Number of explained features to be displayed
distance_metric (string, optional, default: "cosine") – Used to calculate pairwise similarity
model_regressor (sklearn regressor, optional, default: None) – (LIME base) sklearn regressor to use in explanation. Defaults to Ridge regression if None. Must have model_regressor.coef_ and ‘sample_weight’ as a parameter to model_regressor.fit()

Returns:

ret_exp – Explanation object

Return type:

object, lime.explanation

explain_one_recommendation_to_user(user_id, item_id, feature_k=10, feature_type='features', verbose=True)[source]

Generate explanations for one recommendation

Parameters:

user_id (int, required) – id of user to be explained
item_id (int, required) – id of item to be explained
feature_k (int, optional, default: 10) – Number of features to be included in the output
feature_type (string, optional, default: "features") – If “features”, extract features names as explanation only; if “item”, extract item_id as explanation only
verbose (bool, optional, default: True)

Returns:

explanation – Dataframe of explanations [user_id, item_id, explanations, local_prediction] for one instance

Return type:

pandas.DataFrame

explain_recommendations(recommendations, feature_k=10, feature_type='features', verbose=True)[source]

Generate explanations for a list of recommendations

Parameters:

recommendations (pandas.DataFrame, required) – Dataframe of [user_id, item_id]
feature_k (int, optional, default: 10) – Number of features to be included in the output
feature_type (string, optional, default: "features") – If “features”, extract features names as explanation only; if “item”, extract item_id as explanation only
verbose (bool, optional, default: True)

Returns:

explanations – Dataframe of explanations [user_id, item_id, explanations, local_prediction] for each instance

Return type:

pandas.DataFrame

extract_features(explanation_all_ids, feature_type='features')[source]

Extract features from explanation

Parameters:

explanation_all_ids (list, required) – Feature ids (x) of sorted list of tuples (x,y). Sorted in decreasing absolute value of local weight (y)
feature_type (string, optional, default: "features") – If “features”, extract features names as explanation only; if “item”, extract item_id as explanation only

Returns:

filtered_dict – Dictionary of features and their weights

Return type:

dict

generate_neighborhood(user_idx, item_idx, entity, num_samples)[source]

Generate neighborhood samples for explanation

Parameters:

user_idx (int, required) – Index of user to be explained
item_idx (int, required) – Index of item to be explained
entity (string, optional, default: "item") – Rule for selecting samples. Options: “user”, “item”
num_samples (int, optional, default: 100) – Number of samples to be generated for explanation

Returns:

samples_df – Dataframe of user_id, item_id

Return type:

pandas.DataFrame

Preference-based and local post-hoc explanations for recommender systems (LIRE)

Explainable Recommendation via Multi-Task Learning in Opinionated Text Data (MTER)

class cornac.explainer.exp_mter.Exp_MTER(rec_model, dataset, name='Exp_MTER')[source]

Explainer for MTER (Multi-task Explainable Recommendation).

Parameters:

rec_model (object, recommender model) – The recommender model to be explained.
dataset (object, dataset) – The dataset object that is used to explain.
name (string, optional, default: 'Exp_MTER')

References

[1] Explainable Recommendation via Multi-Task Learning in Opinionated Text Data. https://arxiv.org/pdf/1806.03568.pdf

[2] https://github.com/PreferredAI/tutorials/blob/master/recommender-systems/07_explanations.ipynb

explain_one_recommendation_to_user(user_id, item_id, **kwargs)[source]

Get aspect performs best and user’s opinion word of that aspect.

Parameters:

user_id (str) – One user’s id.
item_id (str) – One item’s id.
feature_k (int, optional, default:3) – Number of features in explanations created by explainer.
num_top_opinions (int, optional, default:3) – Number of opinions used to explain each aspect.

Returns:

explanation – Explanations as {aspect: [{opinion: score}, {opinion: score}, …}], aspect: [{opinion: score}, {opinion: score}, …]}

Return type:

dict

Post-Hoc Explanation for Matrix Factorization (PHI4MF)

class cornac.explainer.exp_phi4mf.Exp_PHI4MF(rec_model, dataset, rec_k=10, min_supp=0.001, min_conf=0.001, min_lift=0.01, name='Exp_PHI4MF')[source]

Post Hoc Interpretability of Latent Factor Models for Recommendation Systems. Explain by generating association rules from the recommendations of the model.

Parameters:

rec_model (object, recommender model) – The recommender model to be explained.
dataset (object, dataset) – The dataset object that is used to explain.
rec_k (int, optional, default: 10) – Number of recommendations to generate association rules.
min_supp (float, optional, default: 0.001) – minimum support for the apriori algorithm
min_conf (float, optional, default: 0.001) – minimum confidence for the apriori algorithm
min_lift (float, optional, default: 0.01) – minimum lift for the apriori algorithm
name (string, optional, default: 'Exp_PHI4MF')

References

[1] Georgina Peake and Jun Wang. 2018. Explanation Mining: Post Hoc Interpretability of Latent Factor Models for Recommendation Systems. In Proceedings of the 24th ACM SIGKDD International Conference on Knowledge Discovery & Data Mining, ACM, London United Kingdom, 2060-2069. DOI:https://doi.org/10.1145/3219819.3220072

explain_one_recommendation_to_user(user_id, item_id, **kwargs)[source]

Provide explanation for one user and one item

Parameters:

user_id (str) – One user’s id.
item_id (str) – One item’s id.
feature_k (int, optional, default:10) – Number of features in explanations created by explainer.

Returns:

explanations – Explanations as a dictionary of antecedents: confidence.

Return type:

dict

Provider-side Interpretability with Counterfactual Explanations in Recommender Systems (PRINCE)

Similar User Explanation for EMF (SU4EMF)

class cornac.explainer.exp_su4emf.Exp_SU4EMF(rec_model, dataset, name='Exp_SU4EMF')[source]

Explainer from Explainable Matrix Factorization for Collaborative Filtering. Explains by rating distribution of similar users.

Parameters:

rec_model (object, recommender model) – The recommender model to be explained.
dataset (object, dataset) – The dataset object that is used to explain.
name (string, optional, default: 'Exp_SU4EMF')

References

[1] B. Abdollahi and O. Nasraoui, “Explainable Matrix Factorization for Collaborative Filtering,” ACM Press, 2016, pp. 5-6. doi: 10.1145/2872518.2889405.

[2] https://github.com/ludovikcoba/recoxplainer/blob/master/recoxplainer/explain/model_based_emf.py

explain_one_recommendation_to_user(user_id, item_id, **kwargs)[source]

Provide explanation for one user and one item

Parameters:

user_id (str) – One user’s id.
item_id (str) – One item’s id.
feature_k (int, optional, default:10) – Number of features in explanations created by explainer.

Returns:

explanations – Key: rating, Value: number of similar users who rated the item with that rating.

Return type:

dict

Explainer for TriRank

class cornac.explainer.exp_trirank.Exp_TriRank(rec_model, dataset, name='Exp_TriRank')[source]

Explainer from TriRank: Review-aware Explainable Recommendation by Modeling Aspects.

Parameters:

rec_model (object, recommender model) – The recommender model to be explained.
dataset (object, dataset) – The dataset object that is used to explain.
name (string, optional, default: 'Exp_TriRank')

References

[1] He, Xiangnan, Tao Chen, Min-Yen Kan, and Xiao Chen. 2014. TriRank: Review-aware Explainable Recommendation by Modeling Aspects. In the 24th ACM international on conference on information and knowledge management (CIKM’15). ACM, New York, NY, USA, 1661-1670. DOI: https://doi.org/10.1145/2806416.2806504

explain_one_recommendation_to_user(user_id, item_id, **kwargs)[source]

Provide explanation for one user and one item

Parameters:

user_id (str) – One user’s id.
item_id (str) – One item’s id.
feature_k (int, optional, default:10) – Number of features in explanations created by explainer.
rank_by (str, optional, default:"item") – Rank by item or user. Options: “item”, “user”.

Returns:

explanations – List of tuples (aspect, item_aspect_score, user_interest) for the user and item pair.

Return type:

list

Explainer for Neural Attentional Rating Regression with Review-level Explanations (NARRE)

class cornac.explainer.exp_narre.Exp_NARRE(rec_model, dataset, name='Exp_NARRE')[source]

Explainer for Neural Attentional Rating Regression with Review-level Explanations (NARRE). Explains the recommendation by the attention scores of the reviews.

Parameters:

rec_model (object, recommender model) – The recommender model to be explained.
dataset (object, dataset) – The dataset object that is used to explain.
name (string, optional, default: 'Exp_NARRE')

References

[1] hen, C., Zhang, M., Liu, Y., & Ma, S. (2018, April). Neural attentional rating regression with review-level explanations. In Proceedings of the 2018 World Wide Web Conference (pp. 1583-1592).

explain_one_recommendation_to_user(user_id, item_id, **kwargs)[source]

Provide explanation for one user and one item

Parameters:

user_id (str) – One user’s id.
item_id (str) – One item’s id.
feature_k (int, optional, default:10) – Number of features in explanations created by explainer.

Returns:

explanations – dictionary with review text as key and attention score as value.

Return type:

dict