Skip to content

Commit

Permalink
Add docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@gsarti
gsarti committed Aug 8, 2024
1 parent febf463 commit 9744488
Show file tree
Hide file tree
Showing 5 changed files with 397 additions and 197 deletions.
4 changes: 4 additions & 0 deletions docs/source/main_classes/main_functions.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,4 +38,8 @@ functionalities required for its usage.

.. autofunction:: show_attributions

.. autofunction:: show_granular_attributions

.. autofunction:: show_token_attributions

.. autofunction:: merge_attributions
456 changes: 273 additions & 183 deletions examples/inseq_tutorial.ipynb
View file

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions inseq/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ def get_version() -> str:
"explain",
"show_attributions",
"show_granular_attributions",
"show_token_attributions",
"list_feature_attribution_methods",
"list_aggregators",
"list_aggregation_functions",
Expand Down
107 changes: 102 additions & 5 deletions inseq/data/attribution.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -247,11 +247,6 @@ def granular_attribution_visualizer(
]
)
),
# treescope.render_array(
# value,
# axis_labels={0: f"Generated Tokens: {value.shape[0]}"},
# axis_item_labels={0: column_labels},
# ),
),
replace=True,
)
Expand Down Expand Up @@ -525,6 +520,32 @@ def show_granular(
return_html: bool | None = False,
return_figure: bool = False,
) -> str | None:
"""Visualizes granular attribution heatmaps in HTML format.
Args:
min_val (:obj:`int`, *optional*, defaults to None):
Lower attribution score threshold for color map.
max_val (:obj:`int`, *optional*, defaults to None):
Upper attribution score threshold for color map.
max_show_size (:obj:`int`, *optional*, defaults to None):
Maximum dimension size for additional dimensions to be visualized. Default: 20.
show_dim (:obj:`int` or :obj:`str`, *optional*, defaults to None):
Dimension to be visualized along with the source and target tokens. Can be either the dimension index or
the dimension name. Works only if the dimension size is less than or equal to `max_show_size`.
slice_dims (:obj:`dict[int or str, tuple[int, int]]`, *optional*, defaults to None):
Dimensions to be sliced and visualized along with the source and target tokens. The dictionary should
contain the dimension index or name as the key and the slice range as the value.
display (:obj:`bool`, *optional*, defaults to True):
Whether to show the output of the visualization function.
return_html (:obj:`bool`, *optional*, defaults to False):
If true, returns the HTML corresponding to the notebook visualization of the attributions in
string format, for saving purposes.
return_figure (:obj:`bool`, *optional*, defaults to False):
If true, returns the Treescope figure object for further manipulation.
Returns:
`str`: Returns the HTML output if `return_html=True`
"""
from inseq import show_granular_attributions

return show_granular_attributions(
Expand Down Expand Up @@ -553,6 +574,32 @@ def show_tokens(
do_aggregation: bool = True,
**kwargs,
) -> str | None:
"""Visualizes token-level attributions in HTML format.
Args:
attributions (:class:`~inseq.data.attribution.FeatureAttributionSequenceOutput`):
Sequence attributions to be visualized.
min_val (:obj:`int`, *optional*, defaults to None):
Lower attribution score threshold for color map.
max_val (:obj:`int`, *optional*, defaults to None):
Upper attribution score threshold for color map.
display (:obj:`bool`, *optional*, defaults to True):
Whether to show the output of the visualization function.
return_html (:obj:`bool`, *optional*, defaults to False):
If true, returns the HTML corresponding to the notebook visualization of the attributions in string format,
for saving purposes.
return_figure (:obj:`bool`, *optional*, defaults to False):
If true, returns the Treescope figure object for further manipulation.
replace_char (:obj:`dict[str, str]`, *optional*, defaults to None):
Dictionary mapping strings to be replaced to replacement options, used for cleaning special characters.
Default: {}.
wrap_after (:obj:`int` or :obj:`str` or :obj:`list[str]` :obj:`tuple[str]]`, *optional*, defaults to None):
Token indices or tokens after which to wrap lines. E.g. 10 = wrap after every 10 tokens, "hi" = wrap after
word hi occurs, ["." "!", "?"] or ".!?" = wrap after every sentence-ending punctuation.
step_score_highlight (`str`, *optional*, defaults to None):
Name of the step score to use to highlight generated tokens in the visualization. If None, no highlights are
shown. Default: None.
"""
from inseq import show_token_attributions

aggregated = self.aggregate(aggregator, **kwargs) if do_aggregation else self
Expand Down Expand Up @@ -970,6 +1017,32 @@ def show_granular(
return_html: bool = False,
return_figure: bool = False,
) -> str | None:
"""Visualizes granular attribution heatmaps in HTML format.
Args:
min_val (:obj:`int`, *optional*, defaults to None):
Lower attribution score threshold for color map.
max_val (:obj:`int`, *optional*, defaults to None):
Upper attribution score threshold for color map.
max_show_size (:obj:`int`, *optional*, defaults to None):
Maximum dimension size for additional dimensions to be visualized. Default: 20.
show_dim (:obj:`int` or :obj:`str`, *optional*, defaults to None):
Dimension to be visualized along with the source and target tokens. Can be either the dimension index or
the dimension name. Works only if the dimension size is less than or equal to `max_show_size`.
slice_dims (:obj:`dict[int or str, tuple[int, int]]`, *optional*, defaults to None):
Dimensions to be sliced and visualized along with the source and target tokens. The dictionary should
contain the dimension index or name as the key and the slice range as the value.
display (:obj:`bool`, *optional*, defaults to True):
Whether to show the output of the visualization function.
return_html (:obj:`bool`, *optional*, defaults to False):
If true, returns the HTML corresponding to the notebook visualization of the attributions in
string format, for saving purposes.
return_figure (:obj:`bool`, *optional*, defaults to False):
If true, returns the Treescope figure object for further manipulation.
Returns:
`str`: Returns the HTML output if `return_html=True`
"""
out_str = ""
out_figs = []
for attr in self.sequence_attributions:
Expand Down Expand Up @@ -1005,6 +1078,30 @@ def show_tokens(
do_aggregation: bool = True,
**kwargs,
) -> str | None:
"""Visualizes token-level attributions in HTML format.
Args:
min_val (:obj:`int`, *optional*, defaults to None):
Lower attribution score threshold for color map.
max_val (:obj:`int`, *optional*, defaults to None):
Upper attribution score threshold for color map.
display (:obj:`bool`, *optional*, defaults to True):
Whether to show the output of the visualization function.
return_html (:obj:`bool`, *optional*, defaults to False):
If true, returns the HTML corresponding to the notebook visualization of the attributions in string format,
for saving purposes.
return_figure (:obj:`bool`, *optional*, defaults to False):
If true, returns the Treescope figure object for further manipulation.
replace_char (:obj:`dict[str, str]`, *optional*, defaults to None):
Dictionary mapping strings to be replaced to replacement options, used for cleaning special characters.
Default: {}.
wrap_after (:obj:`int` or :obj:`str` or :obj:`list[str]` :obj:`tuple[str]]`, *optional*, defaults to None):
Token indices or tokens after which to wrap lines. E.g. 10 = wrap after every 10 tokens, "hi" = wrap after
word hi occurs, ["." "!", "?"] or ".!?" = wrap after every sentence-ending punctuation.
step_score_highlight (`str`, *optional*, defaults to None):
Name of the step score to use to highlight generated tokens in the visualization. If None, no highlights are
shown. Default: None.
"""
out_str = ""
out_figs = []
for attr in self.sequence_attributions:
Expand Down
26 changes: 17 additions & 9 deletions inseq/data/viz.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -160,21 +160,29 @@ def show_granular_attributions(
Args:
attributions (:class:`~inseq.data.attribution.FeatureAttributionSequenceOutput`):
Sequence attributions to be visualized.
min_val (:obj:`Optional[int]`, *optional*, defaults to None):
Sequence attributions to be visualized. Does not require pre-aggregation.
min_val (:obj:`int`, *optional*, defaults to None):
Lower attribution score threshold for color map.
max_val (`Optional[int]`, *optional*, defaults to None):
max_val (:obj:`int`, *optional*, defaults to None):
Upper attribution score threshold for color map.
display (`bool`, *optional*, defaults to True):
max_show_size (:obj:`int`, *optional*, defaults to None):
Maximum dimension size for additional dimensions to be visualized. Default: 20.
show_dim (:obj:`int` or :obj:`str`, *optional*, defaults to None):
Dimension to be visualized along with the source and target tokens. Can be either the dimension index or
the dimension name. Works only if the dimension size is less than or equal to `max_show_size`.
slice_dims (:obj:`dict[int or str, tuple[int, int]]`, *optional*, defaults to None):
Dimensions to be sliced and visualized along with the source and target tokens. The dictionary should
contain the dimension index or name as the key and the slice range as the value.
display (:obj:`bool`, *optional*, defaults to True):
Whether to show the output of the visualization function.
return_html (`Optional[bool]`, *optional*, defaults to False):
If true, returns the HTML corresponding to the notebook visualization of the attributions in string format,
for saving purposes.
return_figure (`Optional[bool]`, *optional*, defaults to False):
return_html (:obj:`bool`, *optional*, defaults to False):
If true, returns the HTML corresponding to the notebook visualization of the attributions in
string format, for saving purposes.
return_figure (:obj:`bool`, *optional*, defaults to False):
If true, returns the Treescope figure object for further manipulation.
Returns:
`Optional[str]`: Returns the HTML output if `return_html=True`
`str`: Returns the HTML output if `return_html=True`
"""
from inseq.data.attribution import FeatureAttributionSequenceOutput

Expand Down

0 comments on commit 9744488

Please sign in to comment.