tcav: the sample passes a TensorFlow 1 session and the pins ask for 2.5.1
Code for the TCAV ML interpretability project
At a glance
- What is it?
- TensorFlow's TCAV explains a prediction class in terms of high level concepts rather than input features, learning those concepts from examples and requiring no change to the network. The documentation is the interesting part. setup.py declares 0.2.2 while the last tagged release is 0.2 from 2018, the usage sample passes a session handle that TensorFlow 2 removed, the release procedure still builds a Python 2 wheel, and the page carries three different dependency lists that all disagree.
- Who is it for?
- Use this if you need a class-level explanation in terms of concepts your stakeholders can read, since feature attribution per pixel is not an argument you can have with a domain expert. Skip it if you need a package that tracks current TensorFlow, because the sample call is written against the TensorFlow 1 session API while the requirements file pins 2.5.1.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 116 days ago.
- What is it written in?
- Mainly Jupyter Notebook, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- tensorflow/tcav653 ★ · -2
| Repository | 2026-09-11 | 2026-11-15 |
|---|---|---|
| tensorflow/tcav | 655 | 653 |
-2 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
setup.py declares 0.2.2 and the last tagged release is 0.2
The version in setup.py is 0.2.2. The release list has two entries: 0.1, named Initial release, from 2018-11-14, and 0.2, named API Redesign, from 2018-11-21. There is no 0.2.1 or 0.2.2 tag.
So the patch releases that reached the package index were never cut as GitHub releases, or were cut without one. Either way the two sources of version truth disagree about what the current version is.
The names of the two releases describe a deliberate pivot. Initial release in the first week of November 2018, then an API Redesign a week later. That is an early project changing its public surface within a fortnight of shipping.
The repository is not archived and the last recorded push is 2026-07-22, so there has been recent commit activity on a package whose published version numbers have not moved since 2018.
The usage example passes a session, and requirements.txt pins TensorFlow 2.5.1
The documented call is this:
mytcav = tcav.TCAV(sess,
target,
concepts,
bottlenecks,
act_gen,
alphas,
cav_dir=cav_dir,
num_random_exp=2)
results = mytcav.run()The first positional argument is sess, a TensorFlow session handle. The rest are the target, the concepts, the bottlenecks, the activation generator and the alphas, with a cavity directory and a random experiment count as keywords.
A session object is the TensorFlow 1 interface. The pinned TensorFlow in requirements.txt is 2.5.1, a TensorFlow 2 release, where there is no implicit global graph and no default session to pass. So the one code sample on the page is written against the API of a major version earlier than the one the requirements file asks for.
There is a second, quieter version conflict in the same paragraph. The installation section tells you to pip install tensorflow or tensorflow-gpu, and the GPU package stopped existing as a separate distribution when TensorFlow 2 arrived.
Neither is stated as a caveat anywhere. The README presents the install as two commands and the usage as one constructor call.
The release procedure still builds a Python 2 wheel
The last section of the page is titled how to create a new version of the pip package, and it has three steps. Update the version in setup.py. Run setup.py bdist_wheel twice, once with the py3 python tag and once with the py2 tag. Then run twine upload on the dist directory to upload both packages to PyPI.
A py2 tagged wheel in 2026 is the notable part. There is no explanation of why a Python 2 wheel is still produced, and the py3 instruction does not pin an interpreter either, so the two builds are distinguished only by tag.
The upload step targets the whole dist directory rather than naming the two files, so anything left in that directory from an earlier build goes up with them.
Everything in this section is written against the direct setup.py invocation style that later packaging tools moved away from, which is consistent with the 2018 vintage of the whole page.
TensorFlow is excluded on purpose and numpy is excluded by accident
The install_requires list in setup.py has five entries: matplotlib, Pillow, scikit-learn, scipy and protobuf. Every one of them is a lower bound rather than a pin.
TensorFlow is missing on purpose, and the README explains why. TensorFlow must be installed to use TCAV, but it is not in the pip package install_requires because a user may want either the tensorflow or the tensorflow-gpu package. The instruction is to install the tcav package and then install TensorFlow separately.
numpy is a different case. It is not in install_requires, it is not explained anywhere, and it appears in the README's own requirements bullet list alongside TensorFlow, Pillow, matplotlib, scikit-learn and scipy. So the README tells you numpy is a dependency while the package metadata does not declare it.
pandas is a third case and the odd one out. It is pinned in requirements.txt at 1.0.3, it is in neither install_requires nor the README's bullet list, and nothing in the repository uses it visibly.
Two sections called Requirements, and they do not list the same things
The README has a heading called Requirements under Installation, and a second heading with the same name much further down. They are not the same list.
The first one points at requirements.txt as the list of Python dependencies used in testing TCAV, and says these are all installed during the pip installation with the exception of TensorFlow. So the first section defers to a file rather than listing anything.
The second one is an inline bullet list: tensorflow, numpy, Pillow, matplotlib, scikit-learn and scipy. Six entries, and protobuf is missing from it even though protobuf is in install_requires.
requirements.txt is a third list again, with eight exact pins: matplotlib at 2.2.4, Pillow at 8.2.0, scikit-learn at 0.20.3, scipy at 1.2.1, tensorflow at 2.5.1, numpy at 1.19.2, protobuf at 3.10.0 and pandas at 1.0.3. Three dependency lists on one page, all different, and the one the package actually installs from is the shortest.
Four unit test modules, four separate commands, no runner
There are four test modules named in the README and each is invoked as its own command. Running python with the module flag on tcav.cav_test, then tcav.model_test, then tcav.tcav_test, then tcav.utils_test.
That is a Python standard library unittest layout, where each file is its own entry point, rather than a single suite that discovers them. The consequence is that all four have to be remembered and all four have to pass, and a CI configuration has to list them individually.
The module names map to the four concerns the package covers: the concept activation vectors themselves, the model wrapper, the main TCAV class, and the utilities they share.
The discrete example follows the same hand-held shape. You are told to change directory into tcav/tcav_examples/discrete/, and the KDD99 notebook is given as a path rather than a link.
The design argument is that you do not have to change your network
The page answers a series of questions in the second person, and the last one is the load-bearing claim: do I need to change my network to use TCAV. The answer given is no, with no need to change or retrain the network.
Everything before it supports that. Typical interpretability methods show importance weights on each input feature, such as a pixel. TCAV instead shows the importance of high level concepts such as colour, gender or race for a prediction class. Typical methods need one particular image you are interested in, while TCAV gives an explanation generally true for a class of interest, described as a global explanation.
The concepts are learned from examples rather than declared. To learn a gender concept, TCAV needs a couple of examples of female and something not female. The concepts tested are named as colour, gender, race, textures and others.
The worked example is InceptionV3, showing how much race or gender mattered for its classifications, with the point made that neither label was part of the training input. The authors are Been Kim, Martin Wattenberg, Justin Gilmer, Carrie Cai, James Wexler, Fernanda Viegas and Rory Sayres, and the ICML paper is on arXiv.
FetchDataAndModels.sh sits at the root next to two notebooks
The top level is ten entries and three of them tell you how to get the thing working. There is FetchDataAndModels.sh, a shell script whose name says it fetches the pretrained models the notebook depends on. There is Run_TCAV.ipynb, the step by step guide named in the usage section. And there is Run_TCAV_on_colab.ipynb, the same guide for a hosted environment.
Two notebooks for one tutorial is a deliberate choice rather than duplication. Colab removes the local model download, which is what the shell script is for, so the two cover the two ways in.
The remaining entries are the packaging material: setup.py, requirements.txt, LICENSE, README.md, CONTRIBUTING.md, .gitignore, and the tcav package directory itself.
The setup script reads README.md at build time to produce the long description and declares the package not zip safe, with find_packages discovery and a plain http URL in the metadata rather than an https one.
Editorial conclusion
Use this if you need a class-level explanation in terms of concepts your stakeholders can read, since feature attribution per pixel is not an argument you can have with a domain expert. Skip it if you need a package that tracks current TensorFlow, because the sample call is written against the TensorFlow 1 session API while the requirements file pins 2.5.1. Before you install, read the requirements yourself, since the README carries three different lists and the one the package installs from is the shortest of them, and note that the published version numbers have not moved since 2018 even though the repository is not archived.
Frequently asked questions
What are concept activation vectors?
They are the representation TCAV learns for a high level concept, such as colour, gender, race or a texture, from a couple of positive examples and some negative ones. TCAV then measures how much a given prediction class depends on that concept, rather than reporting importance weights per input feature the way typical attribution methods do.
How do I install TCAV?
Run pip install tcav, and install TensorFlow separately, because it is deliberately left out of the package install_requires so that you can choose between the tensorflow or tensorflow-gpu package. You do not need to change or retrain your network to use TCAV.
Which version of tcav is current?
setup.py declares version 0.2.2, while the recorded GitHub releases are 0.1 from 2018-11-14 and 0.2 from 2018-11-21. There is no 0.2.1 or 0.2.2 tag, so the two sources disagree about the current version. The repository is not archived and its last recorded push is 2026-07-22.
What does TCAV need from TensorFlow?
The documented call passes a session handle as the first argument to the TCAV constructor, which is the TensorFlow 1 interface. The pinned TensorFlow in requirements.txt is 2.5.1, a TensorFlow 2 release where there is no implicit global session to pass, so the page's sample and its requirements file describe different major versions.
How do I run the TCAV unit tests?
There is no single runner. Four modules are invoked separately as commands: the cav_test module, then model_test, then tcav_test, then utils_test. The discrete non-image example is run by changing directory into tcav/tcav_examples/discrete/, with a separate notebook for a model trained on KDD99.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/tensorflow-tcav)Star history chart for your README
[](https://hysenlabs.com/projects/tensorflow-tcav)Was this useful?