Merge pull request #1410 from PAIR-code/dev

Merge dev to main for v1.1
PAIR-code · Feb 21, 2024 · 11b1748 · 11b1748
2 parents 1866bc3 + 9bd3a60
commit 11b1748
Show file tree

Hide file tree

Showing 118 changed files with 3,456 additions and 362 deletions.
diff --git a/.gitignore b/.gitignore
@@ -15,5 +15,6 @@ docs/documentation/.doctrees/**
 
 **/.DS_Store
 .dalle-venv/
+.tydi-venv/
 .venv/
 .vscode/
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1 +1,2 @@
 recursive-include lit_nlp/client/build/default *.js* *.gif *.html *.png *.svg
+include lit_nlp/examples/datasets/prompt_examples.jsonl
diff --git a/RELEASE.md b/RELEASE.md
@@ -1,5 +1,66 @@
 # Learning Interpretability Tool Release Notes
 
+## Release 1.1
+
+This release provides the capabilities to interpret and debug the behaviors of
+Generative AI models in LIT. Specifically, we added sequence salience, which
+explains the impact of the preceding tokens on the generated tokens produced by
+the GenAI models. Major changes include:
+* An `LM salience` module in the LIT UI that computes generations, tokenization,
+and sequence salience on-demand;
+* Computation of sequence salience at different granularities, from the smallest
+possible level of tokens, to more interpretable larger spans, such as words,
+sentences, lines, or paragraphs.
+* Support of OSS modeling frameworks, including KerasNLP and Hugging Face
+Transformers for sequence salience computation.
+This release would not have been possible without the work of our contributors.
+Many thanks to:
+[Ryan Mullins](https://github.com/RyanMullins),
+[Ian Tenney](https://github.com/iftenney),
+[Bin Du](https://github.com/bdu91), and
+[Cibi Arjun](https://github.com/cpka145).
+
+### New Stuff
+* LM salience module in the LIT UI -
+[ab294bd](https://github.com/PAIR-code/lit/commit/ab294bd3e15675c0e63e5a16ffe4b8cd4941c94f)
+[5cffc4d](https://github.com/PAIR-code/lit/commit/5cffc4d933e611587b00c25861c911d5f734fa22)
+[40bb57a](https://github.com/PAIR-code/lit/commit/40bb57a2531257c38137188090a24e70d47581c8)
+[d3980cc](https://github.com/PAIR-code/lit/commit/d3980cc5414e1f9be895defc4f967bee8a2480fc)
+[406fbc7](https://github.com/PAIR-code/lit/commit/406fbc7690ee72f6f96ecf68f1238822ae8951c2)
+[77583e7](https://github.com/PAIR-code/lit/commit/77583e74236aa443a21ad0779b0ab9c023821b93)
+[a758f98](https://github.com/PAIR-code/lit/commit/a758f98c5153f23955b0190a75dc1258ba57b645)
+* Sequence salience for decoder-only LM, with support for GPT-2 and KerasNLP -
+[27e6901](https://github.com/PAIR-code/lit/commit/27e6901164044c0d33658603369a55600da0b202)
+[80cf699](https://github.com/PAIR-code/lit/commit/80cf699f92cd77d58cb2a2a60b9314010b1f336c)
+[1df3ba8](https://github.com/PAIR-code/lit/commit/1df3ba8449e865edb5806c10c8054c246d1e38e3)
+[b6ab352](https://github.com/PAIR-code/lit/commit/b6ab3522b301810cab3c75723f3fe0dabf829577)
+[c97a710](https://github.com/PAIR-code/lit/commit/c97a710416538906ea6b269f90264c0602a15593)
+* Prompt examples for sequence salience -
+[4f19891](https://github.com/PAIR-code/lit/commit/4f1989180ee570642285682f843242be5bffb9ef)
+[000c844](https://github.com/PAIR-code/lit/commit/000c84486ed61439c98dbfdd92959bdbb6f5119f)
+[34aa110](https://github.com/PAIR-code/lit/commit/34aa110c36fe0c7ec670f06662078d2f572c79c6)
+[ca032ff](https://github.com/PAIR-code/lit/commit/ca032ffb3196e71fd0a7a09118635ca6dafc8153)
+
+
+### Non-breaking Changes, Bug Fixes, and Enhancements
+* Improvements to display various fields and their default ranges -
+[8a3f366](https://github.com/PAIR-code/lit/commit/8a3f366816833ead164ecfca778b465ef6d074bb)
+[e63b674](https://github.com/PAIR-code/lit/commit/e63b67484fc7f4dbfa3484126c355350d2127bf7)
+[d274508](https://github.com/PAIR-code/lit/commit/d2745088966c4ac31a3755f55096eeb8193c5a91)
+* Allow only displaying the UI layouts provided by users -
+[a219863](https://github.com/PAIR-code/lit/commit/a21986342d83ae64d58607e337fab9db7736242a)
+* Internal dependency changes -
+[f254fa8](https://github.com/PAIR-code/lit/commit/f254fa8500d6267278fa3dc32fb4bbf56beb7cf7)
+[724bdee](https://github.com/PAIR-code/lit/commit/724bdee1f9ea45ce998b9031eea4ad1169299efb)
+[2138bd9](https://github.com/PAIR-code/lit/commit/2138bd920e72553f9c920ba489962c8649738574)
+* Fix issues with adding more than one example from counterfactual generators -
+[d4302bd](https://github.com/PAIR-code/lit/commit/d4302bd6bfc7e4c778ba0e96397ac620242a8d21)
+* Fix issues with loading `SimpleSentimentModel` -
+[ac8ed59](https://github.com/PAIR-code/lit/commit/ac8ed5902a2c96019ea1137b5138d48017fabf4e)
+* Notebook widget improvements -
+[cdf79eb](https://github.com/PAIR-code/lit/commit/cdf79eb9048be3e6798e916d5e1ac4cc294929b0)
+* Docs updates
+
 ## Release 1.0
 
 This is a major release, covering many new features and API changes from the

diff --git a/docs/documentation/_images/sequence-salience-selections.png b/docs/documentation/_images/sequence-salience-selections.png
diff --git a/docs/documentation/_images/sequence-salience-vis.png b/docs/documentation/_images/sequence-salience-vis.png
diff --git a/docs/documentation/_images/tabular-feature-attribution.png b/docs/documentation/_images/tabular-feature-attribution.png
diff --git a/docs/documentation/_sources/api.md.txt b/docs/documentation/_sources/api.md.txt
@@ -807,8 +807,7 @@ _See the [examples](https://github.com/PAIR-code/lit/blob/main/lit_nlp/examples)
 
 ### Available types
 
-The full set of `LitType`s is defined in
-[types.py](https://github.com/PAIR-code/lit/blob/main/lit_nlp/api/types.py), and summarized
+The full set of `LitType`s is defined in [types.py](https://github.com/PAIR-code/lit/blob/main/lit_nlp/api/types.py). Numeric types such as `Integer` and `Scalar` have predefined ranges that can be overridden using corresponding `min_val` and `max_val` attributes as seen [here](https://github.com/PAIR-code/lit/blob/main/lit_nlp/examples/datasets/penguin_data.py;l=19-22;rcl=574999438). The different types available in LIT are summarized
 in the table below.
 
 Note: Bracket syntax, such as `<float>[num_tokens]`, refers to the shapes of
@@ -828,7 +827,7 @@ Name                      | Description
 `TokenTopKPreds`          | Predicted tokens and their scores, as from a language model or seq2seq model.                                                                                         | `list[list[tuple[str, float]]]`
 `Boolean`                 | Boolean value.                                                                                                                                                        | `bool`
 `Scalar`                  | Scalar numeric value.                                                                                                                                                 | `float`
-`Integer`                 | Integer value.                                                                                                                                                        | `int`
+`Integer`                 | Integer, with a default range from -32768 to +32767. value.                                                                                                                                                        | `int`
 `ImageBytes`              | Image, represented by a base64 encoded string. LIT also provides `JPEGBytes` and `PNGBytes` types for those specific encodings.                                       | `str`
 `RegressionScore`         | Scalar value, treated as a regression target or prediction.                                                                                                           | `float`
 `ReferenceScores`         | Scores for one or more reference texts.                                                                                                                               | `list[float]`

diff --git a/docs/documentation/_sources/components.md.txt b/docs/documentation/_sources/components.md.txt
@@ -1,6 +1,6 @@
 # Components and Features
 
-<!--* freshness: { owner: 'lit-dev' reviewed: '2023-08-07' } *-->
+<!--* freshness: { owner: 'lit-dev' reviewed: '2024-02-20' } *-->
 
 <!-- [TOC] placeholder - DO NOT REMOVE -->
 
@@ -264,55 +264,9 @@ module in the LIT UI, which allows for comparison of multiple methods at once:
 For a demo with a BERT-based classifier, see https://pair-code.github.io/lit/demos/glue.html and navigate to the
 "Explanations" tab.
 
-Currently, salience is supported for classification ( `MulticlassPreds`) and
-regression (`RegressionScore`) outputs, though we hope to support seq2seq models
-soon.
-
-#### Note on Target Selection
-
-For all salience methods, we require that the class to explain is given as a
-label field in the input. For example, if the input example is:
-
-```
-{"text": "this movie was terrible!", "label": "0"}
-```
-
-Our model should return gradients with respect to the class 0. Conversely, we
-might want to ask what features would encourage the model to predict a different
-class. If we select class 1 from the UI:
-
-![Target Selection](./images/components/salience-target-select.png){w=400px align=center}
-
-Then the model will receive a modified input with this target:
-
-```
-{"text": "this movie was terrible!", "label": "1"}
-```
-
-To support this, the model should have the label field in the `input_spec`:
-
-```
-def input_spec(self) -> types.Spec:
-  return {
-    'text': lit_types.TextSegment(),
-    'label': lit_types.CategoryLabel(..., required=False),
-    ...
-  }
-```
-
-and have an output field which references this using `parent=`:
-
-```
-def output_spec(self) -> types.Spec:
-  return {
-    'probas': lit_types.MulticlassPreds(..., parent="label"),
-    ...
-  }
-```
-
-You don't have to call the field "label", and it's okay if this field isn't
-present in the *dataset* - as long as it's something that the model will
-recognize and use as the target to derive gradients.
+Currently, salience is supported for classification ( `MulticlassPreds`),
+regression (`RegressionScore`) and generation (`GeneratedText` or
+`GeneratedTextCandidates`) outputs.
 
 ### Gradient Norm
 
@@ -433,7 +387,84 @@ can increase the number of samples:
 LIME works out-of-the-box with any classification (`MulticlassPreds`) or
 regression/scoring (`RegressionScore`) model.
 
-### Salience Clustering
+### Target Selection on Classification Output
+
+For all salience methods, we require that the class to explain is given as a
+label field in the input. For example, if the input example is:
+
+```
+{"text": "this movie was terrible!", "label": "0"}
+```
+
+Our model should return gradients with respect to the class 0. Conversely, we
+might want to ask what features would encourage the model to predict a different
+class. If we select class 1 from the UI:
+
+![Target Selection](./images/components/salience-target-select.png){w=400px align=center}
+
+Then the model will receive a modified input with this target:
+
+```
+{"text": "this movie was terrible!", "label": "1"}
+```
+
+To support this, the model should have the label field in the `input_spec`:
+
+```
+def input_spec(self) -> types.Spec:
+  return {
+    'text': lit_types.TextSegment(),
+    'label': lit_types.CategoryLabel(..., required=False),
+    ...
+  }
+```
+
+and have an output field which references this using `parent=`:
+
+```
+def output_spec(self) -> types.Spec:
+  return {
+    'probas': lit_types.MulticlassPreds(..., parent="label"),
+    ...
+  }
+```
+
+You don't have to call the field "label", and it's okay if this field isn't
+present in the *dataset* - as long as it's something that the model will
+recognize and use as the target to derive gradients.
+
+### Sequence salience
+
+Sequence salience generalizes the salience methods mentioned above to
+text-to-text generative models and explains the impact of the preceding tokens
+on the generated tokens. Currently, we support sequence salience computation for
+various OSS modeling frameworks, including KerasNLP and Hugging Face
+Transformers.
+
+Sequence salience in the LIT UI provides multiple options for analysis,
+including:
+
+*   running the salience methods on the text from the dataset (target) or from
+    the model (response).
+*   computing the sequence salience through [Gradient Norm](#gradient-norm) or
+    [Gradient-dot-Input](#gradient-dot-input).
+*   selecting different granularity levels for salience analysis, from the
+    smallest possible level of tokens, to more interpretable larger spans, such
+    as words, sentences, lines, or paragraphs.
+
+(a) Options for sequence salience.                                                                 | (b) Sequence salience visualization.
+-------------------------------------------------------------------------------------------------- | ------------------------------------
+![Sequence salience selections](./images/components/sequence-salience-selections.png){w=650px align=center} | ![Sequence salience vis](./images/components/sequence-salience-vis.png){w=650px align=center}
+
+
+**Code:**
+
+* Demo: [`lm_salience_demo.py`](https://github.com/PAIR-code/lit/blob/main/lit_nlp/examples/lm_salience_demo.py)
+* KerasNLP model wrappers: [`instrumented_keras_lms.py`](https://github.com/PAIR-code/lit/blob/main/lit_nlp/examples/models/instrumented_keras_lms.py)
+* Transformers model wrappers: [`pretrained_lms.py`](https://github.com/PAIR-code/lit/blob/main/lit_nlp/examples/models/pretrained_lms.py)
+
+
+## Salience Clustering
 
 LIT includes a basic implementation of the salience clustering method from
 [Ebert et al. 2022](https://arxiv.org/abs/2211.05485), which uses k-means on a
@@ -448,6 +479,18 @@ salience method, and run using the "Apply" button. The result will be a set of
 top tokens for each cluster, as in Table 6 of
 [the paper](https://arxiv.org/pdf/2211.05485.pdf).
 
+## Tabular Feature Attribution
+
+Tabular feature attribution seeks to understand the importance of a column of
+data on a model's predictions. LIT's tabular feature attribution module supports
+this analysis using the [SHAP interpreter](https://github.com/slundberg/shap).
+Please check out
+[our tutorial](https://pair-code.github.io/lit/tutorials/tab-feat-attr/) to
+learn more about how to use this module to analyze feature importance in the
+[Penguins demo](https://pair-code.github.io/lit/demos/penguins.html).
+
+![Tabular feature attribution module module](./images/components/tabular-feature-attribution.png){w=500px align=center}
+
 ## Pixel-based Salience
 
 LIT also supports pixel-based salience methods, for models that take images as

diff --git a/docs/documentation/_sources/index.md.txt b/docs/documentation/_sources/index.md.txt
@@ -1,6 +1,6 @@
 # Learning Interpretability Tool (LIT)
 
-<!--* freshness: { owner: 'lit-dev' reviewed: '2022-12-02' } *-->
+<!--* freshness: { owner: 'lit-dev' reviewed: '2023-09-26' } *-->
 
 <!-- [TOC] placeholder - DO NOT REMOVE -->
 

diff --git a/docs/documentation/_static/scripts/furo.js.map b/docs/documentation/_static/scripts/furo.js.map
diff --git a/docs/documentation/_static/styles/furo.css.map b/docs/documentation/_static/styles/furo.css.map
diff --git a/docs/documentation/api.html b/docs/documentation/api.html
@@ -5,7 +5,7 @@
     <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
 <link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Frontend Developer Guide" href="frontend_development.html" /><link rel="prev" title="Components and Features" href="components.html" />
 
-    <!-- Generated with Sphinx 7.2.6 and Furo 2023.09.10 -->
+    <!-- Generated with Sphinx 7.2.6 and Furo 2024.01.29 -->
         <title>LIT Python API - 🔥LIT 1.0 documentation</title>
       <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=a746c00c" />
     <link rel="stylesheet" type="text/css" href="_static/styles/furo.css?v=135e06be" />
@@ -939,8 +939,7 @@ <h3>An In-Depth Example<a class="headerlink" href="#an-in-depth-example" title="
 </section>
 <section id="available-types">
 <h3>Available types<a class="headerlink" href="#available-types" title="Link to this heading">#</a></h3>
-<p>The full set of <code class="docutils literal notranslate"><span class="pre">LitType</span></code>s is defined in
-<a class="reference external" href="https://github.com/PAIR-code/lit/blob/main/lit_nlp/api/types.py">types.py</a>, and summarized
+<p>The full set of <code class="docutils literal notranslate"><span class="pre">LitType</span></code>s is defined in <a class="reference external" href="https://github.com/PAIR-code/lit/blob/main/lit_nlp/api/types.py">types.py</a>. Numeric types such as <code class="docutils literal notranslate"><span class="pre">Integer</span></code> and <code class="docutils literal notranslate"><span class="pre">Scalar</span></code> have predefined ranges that can be overridden using corresponding <code class="docutils literal notranslate"><span class="pre">min_val</span></code> and <code class="docutils literal notranslate"><span class="pre">max_val</span></code> attributes as seen <a class="reference external" href="https://github.com/PAIR-code/lit/blob/main/lit_nlp/examples/datasets/penguin_data.py;l=19-22;rcl=574999438">here</a>. The different types available in LIT are summarized
 in the table below.</p>
 <p>Note: Bracket syntax, such as <code class="docutils literal notranslate"><span class="pre">&lt;float&gt;[num_tokens]</span></code>, refers to the shapes of
 NumPy arrays where each element inside the brackets is an integer.</p>
@@ -1002,7 +1001,7 @@ <h3>Available types<a class="headerlink" href="#available-types" title="Link to
 <td><p><code class="docutils literal notranslate"><span class="pre">float</span></code></p></td>
 </tr>
 <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">Integer</span></code></p></td>
-<td><p>Integer value.</p></td>
+<td><p>Integer, with a default range from -32768 to +32767. value.</p></td>
 <td><p><code class="docutils literal notranslate"><span class="pre">int</span></code></p></td>
 </tr>
 <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">ImageBytes</span></code></p></td>