rex === .. py:module:: rex Functions --------- .. autoapisummary:: rex.try_preprocess rex.load_and_preprocess_data rex.predict_target rex.calculate_responsibility rex.analyze rex._explanation rex.get_prediction_func_from_args rex.explanation Module Contents --------------- .. py:function:: try_preprocess(args, model_shape, device) Makes an attempt to preprocess input data as required for the model. Data preprocessing is based on file extension and (possibly) user-defined mode. File extensions in ``[".jpg", ".jpeg", ".png", ".tif", ".tiff"]`` are treated as images, ".npy" and ".mat" are treated as Numpy arrays, and ".nii" are treated as nifti files. For any other file extension, we create a ``Data`` object without pre-processing. :param args: configuration values for ReX :param model_shape: shape of the input tensor of the model, as returned by :py:func:`~rex_xai.explanation.get_prediction_func_from_args()` :param device: as returned by :py:func:`~rex_xai._utils.get_device()` :returns: the processed input data :rtype: Data .. py:function:: load_and_preprocess_data(model_shape, device, args) Loads input data from filepath and does preprocessing. Uses a custom preprocesssing function if this is defined in ``args.script.preprocess``, otherwise :py:func:`~rex_xai.explanation.try_preprocess()`. :param model_shape: shape of the input tensor of the model, as returned by :py:func:`~rex_xai.explanation.get_prediction_func_from_args()` :param device: as returned by :py:func:`~rex_xai._utils.get_device()` :param args: configuration values for ReX :returns: the processed input data :rtype: Data .. py:function:: predict_target(data, args, prediction_func) Predicts classification of input data, using given prediction function. Uses ``prediction_func`` to identify the classification of the input data and return this as the target classification for ReX. :param data: processed input data object :param args: configuration values for ReX :param prediction_func: prediction function for the model :returns: the predicted target classification and confidence :rtype: Prediction .. py:function:: calculate_responsibility(data, args, prediction_func, custom_height=None, custom_width=None) Calculates ResponsibilityMaps for input data using given args. Runs :py:func:`~rex_xai.responsibility.causal_explanation` for ``args.iters`` iterations, and returns a ResponsibilityMaps object and a dictionary containing some statistics about the calculation process. The ResponsibilityMaps object by default only includes the responsibility map that matches the classification of the input data. Set ``keep_all_maps`` to ``True`` to retain all maps. :param data: processed input data object :param args: configuration values for ReX :param prediction_func: prediction function for the model :param keep_all_maps: whether to retain all :py:class:`~rex_xai.resp_maps.ResponsibilityMaps`, or just the one that matches the target classification. :returns: tuple containing - ResponsibilityMaps: ResponsibilityMaps for the given data, prediction function, and args. - dict: statistics for the call of this function that generated the ResponsibilityMaps object .. py:function:: analyze(exp, data_mode) Analyzes an Explanation. Analyzes the area ratio, entropy difference, insertion and deletion curves for an Explanation object, prints them, and returns them. :param exp: Explanation object as returned by :py:func:`~rex_xai.explanation._explanation` :param data_mode: Mode of the input data. Entropy of the responsibility map calculated if ``data_mode`` is "RGB". If ``data_mode'' is ``spectral'' then spectral entropy is calculated. :returns: tuple containing - area (float) - entropy (float) - insertion_curve (float) - deletion_curve (float) .. py:function:: _explanation(args, model_shape, prediction_func, device, db = None, path = None) Takes a CausalArgs object and model information and returns a Explanation. Takes a CausalArgs object, model shape and prediction function and returns an Explanation. Depending on the input ``args``, optionally produces output plots, analyses the output explanation, and/or writes results to a database. :param args: configuration values for ReX :param model_shape: shape of the input tensor of the model, as returned by :py:func:`~rex_xai.explanation.get_prediction_func_from_args()` :param prediction_func: as returned by :py:func:`~rex_xai.explanation.get_prediction_func_from_args()` :param device: as returned by :py:func:`~rex_xai._utils.get_device()` :param db: None or as returned by :py:func:`~rex_xai.database.initialise_rex_db()` :returns: An :py:class:`~rex_xai.extraction.Explanation` object containing the causal reponsibility explanation calculated using the given ``args``. :rtype: Explanation .. py:function:: get_prediction_func_from_args(args) Takes a CausalArgs object and gets the prediction function and model shape. If ``args.script`` specifies a prediction function and model shape, returns these. Otherwise gets the prediction function and model shape from the provided model file. :param args: configuration values for ReX :returns: tuple containing - ``prediction_func`` - ``model_shape`` :raises RuntimeError: if an onnx inference instance cannot be created from the provided model file. .. py:function:: explanation(args, device, db = None) Takes a CausalArgs object and returns a Explanation. Takes a CausalArgs object and returns either an Explanation, or a list of Explanations if the input ``args.path`` is a directory rather than a path to a single file. :param args: configuration values for ReX :param device: as returned by :py:func:`~rex_xai._utils.get_device()` :param db: None or as returned by :py:func:`~rex_xai.database.initialise_rex_db()` :returns: An :py:class:`~rex_xai.extraction.Explanation` object containing the causal reponsibility explanation calculated using the given ``args``. :rtype: Explanation