Package: trulens
Welcome to TruLens!TruLens is a cross-framework library for deep learning explainability. It provides a uniform abstraction over a number of different frameworks. It provides a uniform abstraction layer over TensorFlow, PyTorch, and Keras and allows input and internal explanations.This paperis an introduction to the theoretical foundations of the library. We’ve been using TruLens at TruEra across a wide range of real-world use cases to explain deep learning models ranging from time-series RNNs to image and NLP models, and wanted to share the awesomeness with the world.DocumentationQuick UsageTo quickly play around with the TruLens library, check out the following Colab notebooks:PyTorch:TensorFlow 2 / Keras:NLP with PyTorch:NLP with TensorFlow 2 / Keras:InstallationThese installation instructions assume that you have conda installed and added to your path.Create a virtual environment (or modify an existing one).conda create -n "<my_name>" python=3.7  # Skip if using existing environment.
conda activate <my_name>Install dependencies.conda install tensorflow-gpu=1  # Or whatever backend you're using.
conda install keras             # Or whatever backend you're using.
conda install matplotlib        # For visualizations.Install the trulens pip package from PyPI.pip install trulensOverviewAttributionsModel WrappersIn order to support a wide variety of backends with different interfaces for their respective models, TruLens uses its ownModelWrapperclass which provides a general model interface to simplify the implementation of the API functions.
To get the model wrapper, use theget_model_wrappermethod intrulens.nn.models. A model wrapper class exists for each backend that converts a model in the respective backend's format to the general TruLensModelWrapperinterface. The wrappers are found in themodelsmodule, and any model defined using Keras, Pytorch, or Tensorflow should be wrapped before being used with the other API functions that require a model -- all other TruLens functionalities expect models to be an instance oftrulens.nn.models.ModelWrapper.For example,fromtrulens.nn.modelsimportget_model_wrapperwrapped_model=get_model_wrapper(model_defined_via_keras)Attribution MethodsAttribution methods, in the most general sense, allow us to quantify the contribution of particular variables in a model towards a particular behavior of the model.
In many cases, for example, this may simply measure the effect each input variable has on the output of the network.Attribution methods extend theAttributionMethodclass, and many concrete instances are found in thetrulens.nn.attributionmodule.Once an attribution method has been instantiated, its main function is itsattributionsmethod, which returns annp.Arrayof batched items, where each item matches the shape of theinputto the model the attribution method was instantiated with.See themethod comparisondemo for further information on the different types of attribution methods, their uses, and their relationships with one another.Slices, Quantities, and DistributionsIn order to obtain a high degree of flexibility in the types of attributions that can be produced, we implementInternal Influence, which is parameterized by aslice,quantity of interest, anddistribution of interest, explained below.Thesliceessentially defines a layer to use for internal attributions.
The slice for theInternalInfluencemethod can be specified by an instance of theSliceclass in thetrulens.nn.slicesmodule.
ASliceobject specifies two layers: (1) the layer of the variables that we are calculating attributionfor(e.g., the input layer), and (2) the layer whose output defines ourquantity of interest(e.g., the output layer, see below for more on quantities of interest).Thequantity of interest(QoI) essentially defines the model behavior we would like to explain using attributions.
The QoI is a function of the model's output at some layer.
For example, it may select the confidence score for a particular class.
In its most general form, the QoI can be specified by an implementation of theQoIclass in thetrulens.nn.quantitiesmodule.
Several common default implementations are provided in this module as well.Thedistribution of interest(DoI) essentially specifies for which points surrounding each record the calculated attribution should be valid.
The distribution can be specified via an implementation of theDoIclass in thetrulens.nn.distributionsmodule, which is a function taking an input record and producing a list of sample input points to aggregate attribution over.
A few common default distributions implementing theDoIclass can be found in thetrulens.nn.distributionsmodule.SeeAttributions for Different Use Casesfor further explanations of the purpose of these parameters and examples of their usage.VisualizationsIn order to interpret the attributions produced by anAttributionMethod, a few useful visualizers are provided in thetrulens.visualizationsmodule.
While the interface of each visualizer varies slightly, in general, the visualizers are a function taking annp.Arrayrepresenting the attributions returned from anAttributionMethodand producing an image that can be used to interpret the attributions.Contact UsTo communicate with other trulens developers, join ourSlack!CitationTo cite this repository:curl -LH "Accept: application/x-bibtex" https://doi.org/10.5281/zenodo.4495856