--- title: "wallaroo.explainability" type: docs linkTitle: "wallaroo.explainability" ---
def truncate(v: Any, num_char: int = 256) -> str:
@dataclass
class WindowRequestInput:

WindowRequestInput(start: Optional[str], end: Optional[str], num_samples: Optional[int])

WindowRequestInput(start: Optional[str], end: Optional[str], num_samples: Optional[int])
class ExplainabilityConfigList(builtins.list):

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

##### Inherited Members

builtins.list
  list
  clear
  copy
  append
  insert
  extend
  pop
  remove
  index
  count
  reverse
  sort

class ExplainabilityRequestList(builtins.list):

Adds a _repr_html_ to a list of explainability requests.

##### Inherited Members

builtins.list
  list
  clear
  copy
  append
  insert
  extend
  pop
  remove
  index
  count
  reverse
  sort

@dataclass
class FeatureBounds:

FeatureBounds(min: float, max: float, xs: List[float])

FeatureBounds(min: float, max: float, xs: List[float])
@dataclass
class ExplainabilityConfig:

This class specifies an explainability configuration that can be used to later submit explainability requests which cause the server to do the analysis and create explainability results.

ExplainabilityConfig are necessary to ensure the explainability pipeline is created and is deployed and so that various requests are processed in the same manner and can be compared.

id, status, feature_bounds and reference_pipeline_version are optional and will be filled out when processed and saved to the database.

workspace id must match the users/pipelines workspace and reference_pipeline_version must refer to a valid pipeline version that the user has access too.

num_points specifies how many samples to take when varying the values of a feature for the PDP/ICE analysis through the feature_bounds.

feature_names are convinince for the user. output_names is not currently used.

ExplainabilityConfig( id: Optional[uuid.UUID], workspace_id: int, status: Optional[Dict[str, Any]], reference_pipeline_version: str, explainability_pipeline_version: Optional[str], num_points: int = 10, feature_names: Optional[List[str]] = None, feature_bounds: Optional[Dict[str, wallaroo.explainability.FeatureBounds]] = None, output_names: Optional[List[str]] = None)
num_points: int = 10
feature_names: Optional[List[str]] = None
feature_bounds: Optional[Dict[str, wallaroo.explainability.FeatureBounds]] = None
output_names: Optional[List[str]] = None
def list_explainability_requests(self) -> List[wallaroo.explainability.ExplainabilityRequest]:

List the explainability requests we've created.

def get_explainability_request( self, expr: Union[str, wallaroo.explainability.ExplainabilityConfig]) -> Optional[wallaroo.explainability.ExplainabilityRequest]:

Get the full explainability result whether completed or not.

def submit_explainability_request( self, reference_start: Optional[datetime.datetime] = None, reference_end: Optional[datetime.datetime] = None, reference_num_samples: Optional[int] = None, use_reference: Optional[bool] = True, window_start: Optional[datetime.datetime] = None, window_end: Optional[datetime.datetime] = None, window_num_samples: Optional[int] = None, adhoc_data: Union[List[List[float]], numpy.ndarray, pandas.core.frame.DataFrame, NoneType] = None):

Submit an analysis on reference or adhoc data using a particular config

def maybe_format_date(d: Optional[datetime.datetime]) -> Optional[str]:
@dataclass
class ExplainabilityRequest:

This class outlines what should be submitted to start the explainability analysis with a particular config.

The request can be to analyze reference data, historical data from the ref pipeline, or new adhoc data submitted with the request or both.

id and status are optional and are filled in by the processing steps.

If the request has use_reference_data = True, num_sample inference logs are sampled from between the start and end dates or the entire (last 100_000) inferences.

ExplainabilityRequest( id: Optional[uuid.UUID], workspace_id: int, explainability_config_id: Optional[uuid.UUID] = None, status: Optional[Dict[str, Any]] = None, reference_config: Optional[wallaroo.explainability.WindowRequestInput] = None, window_config: Optional[wallaroo.explainability.WindowRequestInput] = None, use_adhoc_data: bool = False, adhoc_data: Optional[List[List[float]]] = None)
explainability_config_id: Optional[uuid.UUID] = None
status: Optional[Dict[str, Any]] = None
reference_config: Optional[wallaroo.explainability.WindowRequestInput] = None
window_config: Optional[wallaroo.explainability.WindowRequestInput] = None
use_adhoc_data: bool = False
adhoc_data: Optional[List[List[float]]] = None
def get_explainability_result(self) -> Optional[wallaroo.explainability.ExplainabilityResult]:

Get the full explainability result whether completed or not.

@dataclass
class PDPResult:

This class holds the PDP/ICE part of the results. PDP/ICE results are generated for each observation by holding all but one feature constant, varying that feature and analyzing that prediction. Thus the results are per inference per feature.

feature_name is the feature that this result is for. xs is the list of x values that the feature was varied through.

pdp_vals is the list of resulting values. model, shap and feature expected values are the mean/expected values for that model, shap and feature.

PDPResult( feature_name: str, ice_vals: numpy.ndarray, pdp_vals: List[float], model_expected_value: List[float], shap_expected_value: List[float], feature_expected_value: List[float])
@dataclass
class WindowResult:

WindowResult(data: numpy.ndarray, shap_values: numpy.ndarray, base_values: numpy.ndarray, pdp_results: List[wallaroo.explainability.PDPResult])

WindowResult( data: numpy.ndarray, shap_values: numpy.ndarray, base_values: numpy.ndarray, pdp_results: List[wallaroo.explainability.PDPResult])
def find_pdp_result( window_result: wallaroo.explainability.WindowResult, feature_name: str) -> wallaroo.explainability.PDPResult:

Gets the pdp result object for the specified feature.

@dataclass
class ExplainabilityResult:

This class holds the explainability result created by processing an explainability request.

id and status are optional and will be filled in by processing. The id will be the same as the request id since the results are stored in minio.

num_inferences and num_batches are nice to know status information and could be brought into the status object in the future.

reference and adhoc data are the actual inferences used in the analysis.

reference and adhoc shap values are the shap values for each feature for each prediction.

base_values are the expected value for each prediction. These values will all be the same so may be changed to a single float in the future.

pdp results are a list of pdp/ice results for each feature.

ExplainabilityResult( id: Optional[uuid.UUID], workspace_id: int, explainability_config_id: uuid.UUID, num_inferences: int, num_batches: int, compute_time: float, status: Dict[str, Any], feature_names: List[str], feature_bounds: Dict[str, wallaroo.explainability.FeatureBounds], reference_result: Optional[wallaroo.explainability.WindowResult], window_result: Optional[wallaroo.explainability.WindowResult], adhoc_result: Optional[wallaroo.explainability.WindowResult])
reference_color = array([0.49803922, 0.76862745, 0.98823529])
window_color = array([0.98823529, 0.49803922, 0.76862745])
def feature_effects(self) -> pandas.core.frame.DataFrame:

Returns a dataframe summarizing the mean feature effects of the reference data as well as the feature effects for each adhoc inference.

def effect_summary(self) -> pandas.core.frame.DataFrame:

Returns a dataframe with the expected/mean values and the shap adjustments.

def check_status(self) -> bool:

Ensure we've completed before trying to plot anything.

def plot_feature_effects( self, mode: str = 'mean', top_n=0, plot_reference=True, plot_window=True, plot_adhoc=True):

Creates a bar plot of the mean or max abs feature effects.

def plot_ice_values( self, feature_name: str, plot_reference=True, plot_window=True, plot_adhoc=True):

Creates a combination ICE plot for the adhoc data if any in custom colors and the reference data if any in translucent blue.

def plot_all_features( self, title='Feature Effect per Inference', plot_reference=True, plot_window=True, plot_adhoc=True, top_n: int = 0):

Creates a 'bee swarm' plot of all/each feature effect.

def plot_feature_values_vs_shap_values( self, feature_name: str, plot_reference=True, plot_window=True, plot_adhoc=True):

Creates a scatter plot of the feature vs shap values. adhoc data if any is in custom colors. reference data in translucent blue.

def build_window_result(data) -> Optional[wallaroo.explainability.WindowResult]:
def build_explainability_result(data):

Convinience function to parse json into the full result object we want.