omnixai.explainers.timeseries.counterfactual package

ce

The basic counterfactual explainer for time series tasks.

mace

The Model-Agnostic Counterfactual Explanation (MACE) designed for time series tasks.

omnixai.explainers.timeseries.counterfactual.ce module

The basic counterfactual explainer for time series tasks.

class omnixai.explainers.timeseries.counterfactual.ce.CounterfactualOptimizer(x0, ts_len, bounds, threshold, predict_function, gamma=None, c=10.0, kappa=0.0, smooth_weight=0.001, binary_search_steps=5, learning_rate=0.01, num_iterations=1000, grad_clip=1000.0, grid_size=1000.0, **kwargs)

Bases: object

The optimizer for the counterfactual explainer for time series anomaly detection.

Parameters

  • x0 – The input time series reshaped in one dimension.

  • ts_len – The length of the time series.

  • bounds – The upper and lower bounds of each value in x0.

  • threshold – The threshold to determine whether an instance is anomalous, e.g., anomaly score > threshold.

  • predict_function – The prediction function for computing anomaly scores.

  • gamma – The denominator of the regularization term, e.g., |x - x0| / gamma. gamma will be set to 1 if it is None.

  • c – The weight of the hinge loss term.

  • kappa – The parameter in the hinge loss function.

  • smooth_weight – The weight of the smoothness regularization term, e.g., |x(t) - x(t-1)|.

  • binary_search_steps – The number of iterations to adjust the weight of the loss term.

  • learning_rate – The learning rate.

  • num_iterations – The maximum number of iterations during optimization.

  • grad_clip – The value for clipping gradients.

  • grid_size – The number of bins in each dimension in x0 for computing numerical gradients.

optimize(revise=True, verbose=True)

Generates counterfactual examples.

Returns

The counterfactual example or None if no counterfactual example is found.

Return type

np.ndarray or None

class omnixai.explainers.timeseries.counterfactual.ce.CounterfactualExplainer(training_data, predict_function, mode='anomaly_detection', threshold=None, **kwargs)

Bases: ExplainerBase

The basic counterfactual explainer for time series anomaly detection or forecasting.

Parameters

  • training_data (Timeseries) – The data used to initialize the explainer.

  • predict_function (Callable) – The prediction function corresponding to the model to explain. The inputs of predict_function should be a batch (list) of time series, i.e., a Timeseries instance. The outputs of predict_function are anomaly scores (higher scores imply more anomalous) for anomaly detection or predicted values for forecasting.

  • mode (str) – The task type, e.g., anomaly_detection or forecasting.

  • threshold (Optional[float]) – The threshold to determine whether an instance is anomalous, e.g., anomaly score > threshold.

  • kwargs – Additional parameters for CounterfactualOptimizer.

explanation_type = 'local'
alias = ['ce', 'counterfactual']
explain(X, **kwargs)

Generates the counterfactual examples for the input instances.

Parameters

  • X (Timeseries) – An instance of Timeseries representing one input instance or a batch of input instances.

  • kwargs – Additional parameters for CounterfactualOptimizer.

Return type

CFExplanation

Returns

The counterfactual explanations for all the input instances.

omnixai.explainers.timeseries.counterfactual.mace module

The Model-Agnostic Counterfactual Explanation (MACE) designed for time series tasks.

class omnixai.explainers.timeseries.counterfactual.mace.MACEExplainer(training_data, predict_function, mode='anomaly_detection', threshold=None, **kwargs)

Bases: ExplainerBase

The Model-Agnostic Counterfactual Explanation (MACE) developed by Yang et al. Please cite the paper MACE: An Efficient Model-Agnostic Framework for Counterfactual Explanation. This is a special version designed for time series anomaly detection and forecasting.

Parameters

  • training_data (Timeseries) – The data used to initialize the explainer.

  • predict_function (Callable) – The prediction function corresponding to the model to explain. The inputs of predict_function should be a batch (list) of time series, i.e., a Timeseries instance. The outputs of predict_function are anomaly scores (higher scores imply more anomalous) for anomaly detection or predicted values for forecasting.

  • mode (str) – The task type, e.g., anomaly_detection or forecasting.

  • threshold (Optional[float]) – The threshold to determine whether an instance is anomalous, e.g., anomaly score > threshold.

explanation_type = 'local'
alias = ['mace']
explain(X, **kwargs)

Generates the counterfactual examples for the input instances.

Parameters

  • X (Timeseries) – An instance of Timeseries representing one input instance or a batch of input instances.

  • kwargs – Additional parameters for MACE, e.g., “learning_rate” - the learning rate for RL, “batch_size” - the number of samples for RL, “num_iterations” - the number of optimization steps.

Return type

CFExplanation

Returns

The counterfactual explanations for all the input instances.