Module artemis.comparison

Classes

class FeatureInteractionMethodComparator

Feature Interaction Method Comparator. It is used for statistical comparison of two different feature interaction methods. Calculates Pearson, Kendall and Spearman rank-correlation and plots one vs one profiles of two methods against each other. Monotonicity of the plot suggest cohesion in results. Both provided methods must be in fitted state.

Attributes

ovo_profiles_comparison_plot : Figure

Matplotlib figure of comparison plots.

correlations_df : pd.DataFrame

Pearson, Kendall and Spearman rank correlation values

References

• https://en.wikipedia.org/wiki/Rank_correlation

Constructor for FeatureInteractionMethodComparator

Expand source code

class FeatureInteractionMethodComparator:
    """
        Feature Interaction Method Comparator.
        It is used for statistical comparison of two different feature interaction methods.
        Calculates Pearson, Kendall and Spearman rank-correlation and plots one vs one profiles of two methods against
        each other. Monotonicity of the plot suggest cohesion in results. Both provided methods must be in fitted state.


        Attributes
        ----------
        ovo_profiles_comparison_plot : Figure
            Matplotlib figure of comparison plots.
        correlations_df : pd.DataFrame
            Pearson, Kendall and Spearman rank correlation values

        References
        ----------
        - https://en.wikipedia.org/wiki/Rank_correlation
        """

    def __init__(self):
        """Constructor for FeatureInteractionMethodComparator"""
        self.ovo_profiles_comparison_plot = None
        self.correlations_df = None

    def summary(self,
                method1: FeatureInteractionMethod,
                method2: FeatureInteractionMethod):
        _assert_fitted_ovo(method1, method2)
        """
        Calculates Feature Interaction Method comparison. 
        Used for asserting stability and cohesion of results for a pair of explanation methods. 

        Parameters
        ----------
        method1 : FeatureInteractionMethod
             First method for comparison
        method2 : FeatureInteractionMethod
             Second method for comparison 
             
        Returns
        -------
        None
        """
        self.correlations_df = self.correlations(method1, method2)
        self.ovo_profiles_comparison_plot = self.comparison_plot(method1, method2, add_correlation_box=True)

    def correlations(self, method1: FeatureInteractionMethod, method2: FeatureInteractionMethod):
        """
        Calculates Pearson, Kendall and Spearman rank correlation DataFrame.

        Parameters
        ----------
        method1 : FeatureInteractionMethod
             First method for comparison
        method2 : FeatureInteractionMethod
             Second method for comparison

        Returns
        -------
        None
        """
        correlations = []
        for correlation_method in dataclasses.fields(CorrelationMethod):
            correlation_method_name = correlation_method.default
            correlations.append(
                {
                    "method": correlation_method_name,
                    "value": self.correlation(method1, method2, correlation_method_name)
                })

        return pd.DataFrame.from_records(correlations)

    def comparison_plot(self,
                        method1: FeatureInteractionMethod,
                        method2: FeatureInteractionMethod,
                        n_labels: int = 3,
                        add_correlation_box: bool = False,
                        figsize: Tuple[float, float] = (8, 6)):
        """
        Creates comparison plot for comparing results of two feature interaction methods. Depending on the parameters
        rank correlation might be included on the plot.

        Parameters
        ----------
        method1 : FeatureInteractionMethod
            First method for comparison
        method2 : FeatureInteractionMethod
            Second method for comparison
        n_labels: int
            Number of pairs of features with the greatest interaction values to show labels of, default = 3
        add_correlation_box: bool
            Flag indicating whether to show rank correlation values on the plot, default = False
        figsize: Tuple[float, float]
            Matplotlib size of the figure, default = (8, 6)


        Returns
        -------
        Figure
        """
        m1_name, m2_name = method1.method, method2.method
        fig, ax = plt.subplots(figsize=figsize)
        ax.set_axisbelow(True)
        plt.grid(True)
        circle_r = 0.2 * min(max(method1._compare_ovo[m1_name]), max(method2._compare_ovo[m2_name]))

        x, y = [], []
        for index, row in method1._compare_ovo.iterrows():

            f1, f2 = row["Feature 1"], row["Feature 2"]
            x_curr, y_curr = row[method1.method], method2.interaction_value(f1, f2)
            x.append(x_curr)
            y.append(y_curr)

            if index < n_labels:
                _add_arrow(ax, circle_r, f1, f2, x_curr, y_curr)

        ax.scatter(x, y, color=InteractionGraphConfiguration.NODE_COLOR)

        if method1._interactions_ascending_order:
            plt.gca().invert_xaxis()
        if method2._interactions_ascending_order:
            plt.gca().invert_yaxis()

        if add_correlation_box:

            corr = self.correlations_df
            if self.correlations_df is None:
                corr = self.correlations(method1, method2)

            _add_correlation_box(ax, corr)

        _title_x_y(ax, m1_name, m2_name)

        return fig, ax

    @staticmethod
    def correlation(
            method1: FeatureInteractionMethod,
            method2: FeatureInteractionMethod,
            correlation_method: str = CorrelationMethod.KENDALL):
        """
        Calculates rank correlation of one vs one profiles using a given correlation method.

        Parameters
        ----------
        method1 : FeatureInteractionMethod
             First method for comparison
        method2 : FeatureInteractionMethod
             Second method for comparison
        correlation_method: str
            Correlation method to use, accepted values are ['pearson', 'kendall', 'spearman'], default = 'kendall'

        Returns
        -------
        value of the correlation
        """

        rank = _rank_interaction_values_encoded(method1, method2)

        return rank.corr(method=correlation_method).iloc[0, 1]

Static methods

def correlation(method1: artemis.interactions_methods._method.FeatureInteractionMethod, method2: artemis.interactions_methods._method.FeatureInteractionMethod, correlation_method: str = 'kendall')

Calculates rank correlation of one vs one profiles using a given correlation method.

Parameters

method1 : FeatureInteractionMethod

First method for comparison

method2 : FeatureInteractionMethod

Second method for comparison

correlation_method : str

Correlation method to use, accepted values are ['pearson', 'kendall', 'spearman'], default = 'kendall'

Returns

value of the correlation

 

Expand source code

@staticmethod
def correlation(
        method1: FeatureInteractionMethod,
        method2: FeatureInteractionMethod,
        correlation_method: str = CorrelationMethod.KENDALL):
    """
    Calculates rank correlation of one vs one profiles using a given correlation method.

    Parameters
    ----------
    method1 : FeatureInteractionMethod
         First method for comparison
    method2 : FeatureInteractionMethod
         Second method for comparison
    correlation_method: str
        Correlation method to use, accepted values are ['pearson', 'kendall', 'spearman'], default = 'kendall'

    Returns
    -------
    value of the correlation
    """

    rank = _rank_interaction_values_encoded(method1, method2)

    return rank.corr(method=correlation_method).iloc[0, 1]

Methods

def comparison_plot(self, method1: artemis.interactions_methods._method.FeatureInteractionMethod, method2: artemis.interactions_methods._method.FeatureInteractionMethod, n_labels: int = 3, add_correlation_box: bool = False, figsize: Tuple[float, float] = (8, 6))

Creates comparison plot for comparing results of two feature interaction methods. Depending on the parameters rank correlation might be included on the plot.

Parameters

method1 : FeatureInteractionMethod

First method for comparison

method2 : FeatureInteractionMethod

Second method for comparison

n_labels : int

Number of pairs of features with the greatest interaction values to show labels of, default = 3

add_correlation_box : bool

Flag indicating whether to show rank correlation values on the plot, default = False

figsize : Tuple[float, float]

Matplotlib size of the figure, default = (8, 6)

Returns

Figure

 

Expand source code

def comparison_plot(self,
                    method1: FeatureInteractionMethod,
                    method2: FeatureInteractionMethod,
                    n_labels: int = 3,
                    add_correlation_box: bool = False,
                    figsize: Tuple[float, float] = (8, 6)):
    """
    Creates comparison plot for comparing results of two feature interaction methods. Depending on the parameters
    rank correlation might be included on the plot.

    Parameters
    ----------
    method1 : FeatureInteractionMethod
        First method for comparison
    method2 : FeatureInteractionMethod
        Second method for comparison
    n_labels: int
        Number of pairs of features with the greatest interaction values to show labels of, default = 3
    add_correlation_box: bool
        Flag indicating whether to show rank correlation values on the plot, default = False
    figsize: Tuple[float, float]
        Matplotlib size of the figure, default = (8, 6)


    Returns
    -------
    Figure
    """
    m1_name, m2_name = method1.method, method2.method
    fig, ax = plt.subplots(figsize=figsize)
    ax.set_axisbelow(True)
    plt.grid(True)
    circle_r = 0.2 * min(max(method1._compare_ovo[m1_name]), max(method2._compare_ovo[m2_name]))

    x, y = [], []
    for index, row in method1._compare_ovo.iterrows():

        f1, f2 = row["Feature 1"], row["Feature 2"]
        x_curr, y_curr = row[method1.method], method2.interaction_value(f1, f2)
        x.append(x_curr)
        y.append(y_curr)

        if index < n_labels:
            _add_arrow(ax, circle_r, f1, f2, x_curr, y_curr)

    ax.scatter(x, y, color=InteractionGraphConfiguration.NODE_COLOR)

    if method1._interactions_ascending_order:
        plt.gca().invert_xaxis()
    if method2._interactions_ascending_order:
        plt.gca().invert_yaxis()

    if add_correlation_box:

        corr = self.correlations_df
        if self.correlations_df is None:
            corr = self.correlations(method1, method2)

        _add_correlation_box(ax, corr)

    _title_x_y(ax, m1_name, m2_name)

    return fig, ax

def correlations(self, method1: artemis.interactions_methods._method.FeatureInteractionMethod, method2: artemis.interactions_methods._method.FeatureInteractionMethod)

Calculates Pearson, Kendall and Spearman rank correlation DataFrame.

Parameters

method1 : FeatureInteractionMethod

First method for comparison

method2 : FeatureInteractionMethod

Second method for comparison

Returns

None

 

Expand source code

def correlations(self, method1: FeatureInteractionMethod, method2: FeatureInteractionMethod):
    """
    Calculates Pearson, Kendall and Spearman rank correlation DataFrame.

    Parameters
    ----------
    method1 : FeatureInteractionMethod
         First method for comparison
    method2 : FeatureInteractionMethod
         Second method for comparison

    Returns
    -------
    None
    """
    correlations = []
    for correlation_method in dataclasses.fields(CorrelationMethod):
        correlation_method_name = correlation_method.default
        correlations.append(
            {
                "method": correlation_method_name,
                "value": self.correlation(method1, method2, correlation_method_name)
            })

    return pd.DataFrame.from_records(correlations)

def summary(self, method1: artemis.interactions_methods._method.FeatureInteractionMethod, method2: artemis.interactions_methods._method.FeatureInteractionMethod)

Expand source code

def summary(self,
            method1: FeatureInteractionMethod,
            method2: FeatureInteractionMethod):
    _assert_fitted_ovo(method1, method2)
    """
    Calculates Feature Interaction Method comparison. 
    Used for asserting stability and cohesion of results for a pair of explanation methods. 

    Parameters
    ----------
    method1 : FeatureInteractionMethod
         First method for comparison
    method2 : FeatureInteractionMethod
         Second method for comparison 
         
    Returns
    -------
    None
    """
    self.correlations_df = self.correlations(method1, method2)
    self.ovo_profiles_comparison_plot = self.comparison_plot(method1, method2, add_correlation_box=True)