{
"info": {
"author": "PyTorch Team",
"author_email": "",
"bugtrack_url": null,
"classifiers": [
"Development Status :: 4 - Beta",
"Intended Audience :: Developers",
"Intended Audience :: Education",
"Intended Audience :: Science/Research",
"License :: OSI Approved :: BSD License",
"Programming Language :: Python :: 3 :: Only",
"Topic :: Scientific/Engineering"
],
"description": "\n\n
\n\n[](https://anaconda.org/pytorch/captum)\n[](https://pypi.org/project/captum)\n[](https://circleci.com/gh/pytorch/captum)\n\nCaptum is a model interpretability and understanding library for PyTorch.\nCaptum means comprehension in latin and contains general purpose implementations\nof integrated gradients, saliency maps, smoothgrad, vargrad and others for\nPyTorch models. It has quick integration for models built with domain-specific\nlibraries such as torchvision, torchtext, and others.\n\n*Captum is currently in beta and under active development!*\n\n\n#### About Captum\n\nWith the increase in model complexity and the resulting lack of transparency, model interpretability methods have become increasingly important. Model understanding is both an active area of research as well as an area of focus for practical applications across industries using machine learning. Captum provides state-of-the-art algorithms, including Integrated Gradients, to provide researchers and developers with an easy way to understand which features are contributing to a model\u2019s output.\n\nFor model developers, Captum can be used to improve and troubleshoot models by facilitating the identification of different features that contribute to a model\u2019s output in order to design better models and troubleshoot unexpected model outputs.\n\nCaptum helps ML researchers more easily implement interpretability algorithms that can interact with PyTorch models. Captum also allows researchers to quickly benchmark their work against other existing algorithms available in the library.\n\n#### Target Audience\n\nThe primary audiences for Captum are model developers who are looking to improve their models and understand which features are important and interpretability researchers focused on identifying algorithms that can better interpret many types of models.\n\nCaptum can also be used by application engineers who are using trained models in production. Captum provides easier troubleshooting through improved model interpretability, and the potential for delivering better explanations to end users on why they\u2019re seeing a specific piece of content, such as a movie recommendation.\n\n## Installation\n\n**Installation Requirements**\n- Python >= 3.6\n- PyTorch >= 1.2\n\n\n##### Installing the latest release\n\nThe latest release of Captum is easily installed either via\n[Anaconda](https://www.anaconda.com/distribution/#download-section) (recommended):\n```bash\nconda install captum -c pytorch\n```\nor via `pip`:\n```bash\npip install captum\n```\n\n\n##### Installing from latest master\n\nIf you'd like to try our bleeding edge features (and don't mind potentially\nrunning into the occasional bug here or there), you can install the latest\nmaster directly from GitHub:\n```bash\npip install git+https://github.com/pytorch/captum.git\n```\n\n**Manual / Dev install**\n\nAlternatively, you can do a manual install. For a basic install, run:\n```bash\ngit clone https://github.com/pytorch/captum.git\ncd captum\npip install -e .\n```\n\nTo customize the installation, you can also run the following variants of the\nabove:\n* `pip install -e .[insights]`: Also installs all packages necessary for running Captum Insights.\n* `pip install -e .[dev]`: Also installs all tools necessary for development\n (testing, linting, docs building; see [Contributing](#contributing) below).\n* `pip install -e .[tutorials]`: Also installs all packages necessary for running the tutorial notebooks.\n\nTo execute unit tests from a manual install, run:\n```bash\n# running a single unit test\npython -m unittest -v tests.attr.test_saliency\n# running all unit tests\npytest -ra\n```\n\n## Getting Started\nCaptum helps you interpret and understand predictions of PyTorch models by\nexploring features that contribute to a prediction the model makes.\nIt also helps understand which neurons and layers are important for\nmodel predictions.\n\nCurrently, the library uses gradient-based interpretability algorithms\nand attributes contributions to each input of the model with respect to\ndifferent neurons and layers, both intermediate and final.\n\nLet's apply some of those algorithms to a toy model we have created for\ndemonstration purposes.\nFor simplicity, we will use the following architecture, but users are welcome\nto use any PyTorch model of their choice.\n\n\n```\nimport numpy as np\n\nimport torch\nimport torch.nn as nn\n\nfrom captum.attr import (\n GradientShap,\n DeepLift,\n DeepLiftShap,\n IntegratedGradients,\n LayerConductance,\n NeuronConductance,\n NoiseTunnel,\n)\n\nclass ToyModel(nn.Module):\n def __init__(self):\n super().__init__()\n self.lin1 = nn.Linear(3, 3)\n self.relu = nn.ReLU()\n self.lin2 = nn.Linear(3, 2)\n\n # initialize weights and biases\n self.lin1.weight = nn.Parameter(torch.arange(-4.0, 5.0).view(3, 3))\n self.lin1.bias = nn.Parameter(torch.zeros(1,3))\n self.lin2.weight = nn.Parameter(torch.arange(-3.0, 3.0).view(2, 3))\n self.lin2.bias = nn.Parameter(torch.ones(1,2))\n\n def forward(self, input):\n return self.lin2(self.relu(self.lin1(input)))\n```\n\nLet's create an instance of our model and set it to eval mode.\n```\nmodel = ToyModel()\nmodel.eval()\n```\n\nNext, we need to define simple input and baseline tensors.\nBaselines belong to the input space and often carry no predictive signal.\nZero tensor can serve as a baseline for many tasks.\nSome interpretability algorithms such as Integrated\nGradients, Deeplift and GradientShap are designed to attribute the change\nbetween the input and baseline to a predictive class or a value that the neural\nnetwork outputs.\n\nWe will apply model interpretability algorithms on the network\nmentioned above in order to understand the importance of individual\nneurons/layers and the parts of the input that play an important role in the\nfinal prediction.\n\nTo make computations deterministic, let's fix random seeds.\n\n```\ntorch.manual_seed(123)\nnp.random.seed(123)\n```\n\nLet's define our input and baseline tensors. Baselines are used in some\ninterpretability algorithms such as `IntegratedGradients, DeepLift,\nGradientShap, NeuronConductance, LayerConductance, InternalInfluence and\nNeuronIntegratedGradients`.\n\n```\ninput = torch.rand(2, 3)\nbaseline = torch.zeros(2, 3)\n```\nNext we will use `IntegratedGradients` algorithms to assign attribution\nscores to each input feature with respect to the second target output.\n```\nig = IntegratedGradients(model)\nattributions, delta = ig.attribute(input, baseline, target=0, return_convergence_delta=True)\nprint('IG Attributions: ', attributions, ' Convergence Delta: ', delta)\n```\nOutput:\n```\nIG Attributions: tensor([[-0.5922, -1.5497, -1.0067],\n [ 0.0000, -0.2219, -5.1991]])\nConvergence Delta: tensor([2.3842e-07, -4.7684e-07])\n```\nThe algorithm outputs an attribution score for each input element and a\nconvergence delta. The lower the absolute value of the convergence delta the better\nis the approximation. If we choose not to return delta,\nwe can simply not provide `return_convergence_delta` input\nargument. The absolute value of the returned deltas can be interpreted as an\napproximation error for each input sample.\nIt can also serve as a proxy of how accurate the integral approximation for given\ninputs and baselines is.\nIf the approximation error is large, we can try larger number of integral\napproximation steps by setting `n_steps` to a larger value. Not all algorithms\nreturn approximation error. Those which do, though, compute it based on the\ncompleteness property of the algorithms.\n\nPositive attribution score means that the input in that particular position\npositively contributed to the final prediction and negative means the opposite.\nThe magnitude of the attribution score signifies the strength of the contribution.\nZero attribution score means no contribution from that particular feature.\n\nSimilarly, we can apply `GradientShap`, `DeepLift` and other attribution algorithms to the model.\n\nGradient SHAP first chooses a random baseline from baselines' distribution, then\n adds gaussian noise with std=0.09 to each input example `n_samples` times.\nAfterwards, it chooses a random point between each example-baseline pair and\ncomputes the gradients with respect to target class (in this case target=0). Resulting\nattribution is the mean of gradients * (inputs - baselines)\n```\ngs = GradientShap(model)\n\n# We define a distribution of baselines and draw `n_samples` from that\n# distribution in order to estimate the expectations of gradients across all baselines\nbaseline_dist = torch.randn(10, 3) * 0.001\nattributions, delta = gs.attribute(input, stdevs=0.09, n_samples=4, baselines=baseline_dist,\n target=0, return_convergence_delta=True)\nprint('GradientShap Attributions: ', attributions, ' Convergence Delta: ', delta)\n```\nOutput\n```\nGradientShap Attributions: tensor([[-0.1542, -1.6229, -1.5835],\n [-0.3916, -0.2836, -4.6851]])\nConvergence Delta: tensor([ 0.0000, -0.0005, -0.0029, -0.0084, -0.0087, -0.0405, 0.0000, -0.0084])\n\n```\nDeltas are computed for each `n_samples * input.shape[0]` example. The user can,\nfor instance, average them:\n```\ndeltas_per_example = torch.mean(delta.reshape(input.shape[0], -1), dim=1)\n```\nin order to get per example average delta.\n\n\nBelow is an example of how we can apply `DeepLift` and `DeepLiftShap` on the\n`ToyModel` described above. Current implementation of DeepLift supports only\n`Rescale` rule.\nFor more details on alternative implementations, please read DeepLift's\noriginal paper linked below.\n\n```\ndl = DeepLift(model)\nattributions, delta = dl.attribute(input, baseline, target=0, return_convergence_delta=True)\nprint('DeepLift Attributions: ', attributions, ' Convergence Delta: ', delta)\n```\nOutput\n```\nDeepLift Attributions: tensor([[-0.5922, -1.5497, -1.0067],\n [ 0.0000, -0.2219, -5.1991])\nConvergence Delta: tensor([0., 0.])\n```\nDeepLift assigns similar attribution scores as Integrated Gradients to inputs,\nhowever it has lower execution time. Another important thing to remember about\nDeepLift is that it currently doesn't support all non-linear activation types.\nFor more details on limitations of the current implementation, please read\nDeepLift's original paper linked below.\n\nSimilar to integrated gradients, DeepLift returns a convergence delta score\nper input example. The approximation error is then the absolute\nvalue of the convergence deltas and can serve as a proxy of how accurate the\nalgorithm's approximation is.\n\nNow let's look into `DeepLiftShap`. Similar to `GradientShap`, `DeepLiftShap` uses\nbaseline distribution. In the example below, we use the same baseline distribution\nas for `GradientShap`.\n\n```\ndl = DeepLiftShap(model)\nattributions, delta = dl.attribute(input, baseline_dist, target=0, return_convergence_delta=True)\nprint('DeepLiftSHAP Attributions: ', attributions, ' Convergence Delta: ', delta)\n```\nOutput\n```\nDeepLiftShap Attributions: tensor([[-5.9169e-01, -1.5491e+00, -1.0076e+00],\n [-4.7101e-03, -2.2300e-01, -5.1926e+00]], grad_fn=)\nConvergence Delta: tensor([-4.6120e-03, -1.6267e-03, -5.1045e-04, -1.4184e-03, -6.8886e-03,\n -2.2224e-02, 0.0000e+00, -2.8790e-02, -4.1285e-03, -2.7295e-02,\n -3.2349e-03, -1.6265e-03, -4.7684e-07, -1.4191e-03, -6.8889e-03,\n -2.2224e-02, 0.0000e+00, -2.4792e-02, -4.1289e-03, -2.7296e-02])\n```\n`DeepLiftShap` uses `DeepLift` to compute attribution score for each\ninput-baseline pair and averages it for each input across all baselines.\n\nIt computes deltas for each input example-baseline pair, thus resulting to\n`input.shape[0] * baseline.shape[0]` delta values.\n\nSimilar to GradientShap in order to compute example-based deltas we can average them per example:\n```\ndeltas_per_example = torch.mean(delta.reshape(input.shape[0], -1), dim=1)\n```\nIn order to smooth and improve the quality of the attributions we can run\n`IntegratedGradients` and other attribution methods through a `NoiseTunnel`.\n`NoiseTunnel` allows us to use SmoothGrad, SmoothGrad_Sq and VarGrad techniques\nto smoothen the attributions by aggregating them for multiple noisy\nsamples that were generated by adding gaussian noise.\n\nHere is an example how we can use `NoiseTunnel` with `IntegratedGradients`.\n\n```\nig = IntegratedGradients(model)\nnt = NoiseTunnel(ig)\nattributions, delta = nt.attribute(input, nt_type='smoothgrad', stdevs=0.02, n_samples=4,\n baselines=baseline, target=0, return_convergence_delta=True)\nprint('IG + SmoothGrad Attributions: ', attributions, ' Convergence Delta: ', delta)\n```\nOutput\n```\nIG + SmoothGrad Attributions: tensor([[-0.4574, -1.5493, -1.0893],\n [ 0.0000, -0.2647, -5.1619]])\nConvergence Delta: tensor([ 0.0000e+00, 2.3842e-07, 0.0000e+00, -2.3842e-07, 0.0000e+00,\n -4.7684e-07, 0.0000e+00, -4.7684e-07])\n\n```\nThe number of elements in the `delta` tensor is equal to: `n_samples * input.shape[0]`\nIn order to get a example-based delta, we can, for example, average them:\n```\ndeltas_per_example = torch.mean(delta.reshape(input.shape[0], -1), dim=1)\n```\n\nLet's look into the internals of our network and understand which layers\nand neurons are important for the predictions.\n\nWe will start with the neuron conductance. Neuron conductance helps us to identify\ninput features that are important for a particular neuron in a given\nlayer. It decomposes the computation of integrated gradients via the chain rule by\ndefining the importance of a neuron as path integral of the derivative of the output\nwith respect to the neuron times the derivatives of the neuron with respect to the\ninputs of the model.\n\nIn this case, we choose to analyze the first neuron in the linear layer.\n\n```\nnc = NeuronConductance(model, model.lin1)\nattributions = nc.attribute(input, neuron_index=1, target=0)\nprint('Neuron Attributions: ', attributions)\n```\nOutput\n```\nNeuron Attributions: tensor([[ 0.0000, 0.0000, 0.0000],\n [ 1.3358, 0.0000, -1.6811]])\n```\n\nLayer conductance shows the importance of neurons for a layer and given input.\nIt is an extension of path integrated gradients for hidden layers and holds the\ncompleteness property as well.\n\nIt doesn't attribute the contribution scores to the input features\nbut shows the importance of each neuron in selected layer.\n```\nlc = LayerConductance(model, model.lin1)\nattributions, delta = lc.attribute(input, baselines=baseline, target=0, return_convergence_delta=True)\nprint('Layer Attributions: ', attributions, ' Convergence Delta: ', delta)\n```\nOutputs\n```\nLayer Attributions: tensor([[ 0.0000, 0.0000, -3.0856],\n [ 0.0000, -0.3488, -4.9638]], grad_fn=)\nConvergence Delta: tensor([0.0630, 0.1084])\n```\n\nSimilar to other attribution algorithms that return convergence delta, LayerConductance\nreturns the deltas for each example. The approximation error is then the absolute\nvalue of the convergence deltas and can serve as a proxy of how accurate integral\napproximation for given inputs and baselines is.\n\nMore details on the list of supported algorithms and how to apply\nCaptum on different types of models can be found in our tutorials.\n\n\n## Captum Insights\n\nCaptum provides a web interface called Insights for easy visualization and\naccess to a number of our interpretability algorithms.\n\nTo analyze a sample model on CIFAR10 via Captum Insights run\n\n```\npython -m captum.insights.example\n```\n\nand navigate to the URL specified in the output.\n\n\n\nTo build Insights you will need [Node](https://nodejs.org/en/) >= 8.x\nand [Yarn](https://yarnpkg.com/en/) >= 1.5.\n\nTo build and launch from a checkout in a conda environment run\n\n```\nconda install -c conda-forge yarn\nBUILD_INSIGHTS=1 python setup.py develop\npython captum/insights/example.py\n```\n\n## Contributing\nSee the [CONTRIBUTING](CONTRIBUTING.md) file for how to help out.\n\n\n## References\n\n* [Axiomatic Attribution for Deep Networks, Mukund Sundararajan et al. 2017](https://arxiv.org/abs/1703.01365)\n* [Did the Model Understand the Question? Pramod K. Mudrakarta, et al. 2018](https://www.aclweb.org/anthology/P18-1176)\n* [Investigating the influence of noise and distractors on the interpretation of neural networks, Pieter-Jan Kindermans et al. 2016](https://arxiv.org/abs/1611.07270)\n* [SmoothGrad: removing noise by adding noise, Daniel Smilkov et al. 2017](https://arxiv.org/abs/1706.03825)\n* [Local Explanation Methods for Deep Neural Networks Lack Sensitivity to Parameter Values, Julius Adebayo et al. 2018](https://arxiv.org/abs/1810.03307)\n* [Sanity Checks for Saliency Maps, Julius Adebayo et al. 2018](https://arxiv.org/abs/1810.03292)\n* [How Important is a neuron?, Kedar Dhamdhere et al. 2018](https://arxiv.org/abs/1805.12233)\n* [Learning Important Features Through Propagating Activation Differences, Avanti Shrikumar et al. 2017](https://arxiv.org/pdf/1704.02685.pdf)\n* [Computationally Efficient Measures of Internal Neuron Importance, Avanti Shrikumar et al. 2018](https://arxiv.org/pdf/1807.09946.pdf)\n* [A Unified Approach to Interpreting Model Predictions, Scott M. Lundberg et al. 2017](http://papers.nips.cc/paper/7062-a-unified-approach-to-interpreting-model-predictions)\n* [Influence-Directed Explanations for Deep Convolutional Networks, Klas Leino et al. 2018](https://arxiv.org/pdf/1802.03788.pdf)\n* [Towards better understanding of gradient-based attribution methods for deep neural networks, Marco Ancona et al. 2018](https://openreview.net/pdf?id=Sy21R9JAW)\n\n## License\nCaptum is BSD licensed, as found in the [LICENSE](LICENSE) file.\n\n\n",
"description_content_type": "text/markdown",
"docs_url": null,
"download_url": "",
"downloads": {
"last_day": -1,
"last_month": -1,
"last_week": -1
},
"home_page": "https://captum.ai",
"keywords": "Model Interpretability,Model Understanding,Feature Importance,Neuron Importance,PyTorch",
"license": "BSD-3",
"maintainer": "",
"maintainer_email": "",
"name": "captum",
"package_url": "https://pypi.org/project/captum/",
"platform": "",
"project_url": "https://pypi.org/project/captum/",
"project_urls": {
"Documentation": "https://captum.ai",
"Homepage": "https://captum.ai",
"Source": "https://github.com/pytorch/captum",
"conda": "https://anaconda.org/pytorch/captum"
},
"release_url": "https://pypi.org/project/captum/0.1.0/",
"requires_dist": [
"matplotlib",
"numpy",
"torch (>=1.2)",
"flask; extra == 'dev'",
"ipython; extra == 'dev'",
"ipywidgets; extra == 'dev'",
"jupyter; extra == 'dev'",
"pytest; extra == 'dev'",
"pytest-cov; extra == 'dev'",
"black; extra == 'dev'",
"flake8; extra == 'dev'",
"sphinx; extra == 'dev'",
"sphinx-autodoc-typehints; extra == 'dev'",
"flask; extra == 'insights'",
"ipython; extra == 'insights'",
"ipywidgets; extra == 'insights'",
"jupyter; extra == 'insights'",
"pytest; extra == 'test'",
"pytest-cov; extra == 'test'",
"flask; extra == 'tutorials'",
"ipython; extra == 'tutorials'",
"ipywidgets; extra == 'tutorials'",
"jupyter; extra == 'tutorials'",
"torchtext; extra == 'tutorials'",
"torchvision; extra == 'tutorials'"
],
"requires_python": ">=3.6",
"summary": "Model interpretability for PyTorch",
"version": "0.1.0"
},
"last_serial": 5951986,
"releases": {
"0.0.1": [
{
"comment_text": "",
"digests": {
"md5": "ae42d04c09c0635350724f4382a5692d",
"sha256": "08b9934239b9e89f99855105a3432e358ecadcbb9f777fb2e16e1aba1cdba500"
},
"downloads": -1,
"filename": "captum-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ae42d04c09c0635350724f4382a5692d",
"packagetype": "bdist_wheel",
"python_version": "3.7",
"requires_python": null,
"size": 1052,
"upload_time": "2019-09-03T17:33:18",
"url": "https://files.pythonhosted.org/packages/db/bd/6505d86e42cbe5ad7b96607447237ea368b20f98a6959dc7e73582bf5aaf/captum-0.0.1-py3-none-any.whl"
}
],
"0.1.0": [
{
"comment_text": "",
"digests": {
"md5": "36f6d2becfbeecec5cf0cd8538d0981a",
"sha256": "698cd12c2d055c229ddce338597fa73061daf914ea035de048e5824e04ce962a"
},
"downloads": -1,
"filename": "captum-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "36f6d2becfbeecec5cf0cd8538d0981a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 532185,
"upload_time": "2019-10-09T20:48:00",
"url": "https://files.pythonhosted.org/packages/f7/a2/fe37944a50633ffc048918ec0d1e9aafb6ad1e189deb09caae4a6270f2e6/captum-0.1.0-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "4f42e6803bb4ec8bf76e2a934e9bb548",
"sha256": "15d1bd8adaa05edcf7ea31569bb21f625b1859cd326e910178a000b7aeb623b3"
},
"downloads": -1,
"filename": "captum-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "4f42e6803bb4ec8bf76e2a934e9bb548",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 492669,
"upload_time": "2019-10-09T20:48:02",
"url": "https://files.pythonhosted.org/packages/af/cd/737d392edbb04a411f43d366e758dcd3bcd450547b1a9d2eab3746ea23c9/captum-0.1.0.tar.gz"
}
]
},
"urls": [
{
"comment_text": "",
"digests": {
"md5": "36f6d2becfbeecec5cf0cd8538d0981a",
"sha256": "698cd12c2d055c229ddce338597fa73061daf914ea035de048e5824e04ce962a"
},
"downloads": -1,
"filename": "captum-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "36f6d2becfbeecec5cf0cd8538d0981a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 532185,
"upload_time": "2019-10-09T20:48:00",
"url": "https://files.pythonhosted.org/packages/f7/a2/fe37944a50633ffc048918ec0d1e9aafb6ad1e189deb09caae4a6270f2e6/captum-0.1.0-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "4f42e6803bb4ec8bf76e2a934e9bb548",
"sha256": "15d1bd8adaa05edcf7ea31569bb21f625b1859cd326e910178a000b7aeb623b3"
},
"downloads": -1,
"filename": "captum-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "4f42e6803bb4ec8bf76e2a934e9bb548",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 492669,
"upload_time": "2019-10-09T20:48:02",
"url": "https://files.pythonhosted.org/packages/af/cd/737d392edbb04a411f43d366e758dcd3bcd450547b1a9d2eab3746ea23c9/captum-0.1.0.tar.gz"
}
]
}