Data Classes

class inseq.data.data_utils.TensorWrapper

Wrapper for tensors and lists of tensors to allow for easy access to their attributes.

__getitem__(subscript)

By default, idiomatic slicing is used for the sequence dimension across batches. For batching use slice_batch instead.

Batching

class inseq.data.batch.BatchEncoding(input_ids: Tensor[Tensor], input_tokens: Sequence[Sequence[str]], attention_mask: Tensor[Tensor], baseline_ids: Optional[Tensor[Tensor]])

Output produced by the tokenization process using encode().

input_ids

Batch of token ids with shape [batch_size, longest_seq_length]. Extra tokens for each sentence are padded, and truncation to max_seq_length is performed.

Type:

torch.Tensor

input_tokens

List of lists containing tokens for each sentence in the batch.

Type:

list(list(str))

attention_mask

Batch of attention masks with shape [batch_size, longest_seq_length]. 1 for positions that are valid, 0 for padded positions.

Type:

torch.Tensor

baseline_ids

Batch of reference token ids with shape [batch_size, longest_seq_length]. Used for attribution methods requiring a baseline input (e.g. IG).

Type:

torch.Tensor, optional

class inseq.data.batch.BatchEmbedding(input_embeds: Optional[Tensor[Tensor]] = None, baseline_embeds: Optional[Tensor[Tensor]] = None)

Embeddings produced by the embedding process using embed().

input_embeds

Batch of token embeddings with shape [batch_size, longest_seq_length, embedding_size] for each sentence in the batch.

Type:

torch.Tensor

baseline_embeds

Batch of reference token embeddings with shape [batch_size, longest_seq_length, embedding_size] for each sentence in the batch.

Type:

torch.Tensor, optional

class inseq.data.batch.Batch(encoding: BatchEncoding, embedding: BatchEmbedding)

Batch of input data for the attribution model.

encoding

Output produced by the tokenization process using encode().

Type:

BatchEncoding

embedding

Embeddings produced by the embedding process using embed().

Type:

BatchEmbedding

All attribute fields are accessible as properties (e.g. batch.input_ids corresponds to

batch.encoding.input_ids)

class inseq.data.batch.EncoderDecoderBatch(sources: Batch, targets: Batch)

Batch of input data for the encoder-decoder attribution model, including information for the source text and the target prefix.

sources

Batch of input data for the source text.

Type:

Batch

targets

Batch of input data for the target prefix.

Type:

Batch

class inseq.data.batch.DecoderOnlyBatch(encoding: BatchEncoding, embedding: BatchEmbedding)

Input batch adapted for decoder-only attribution models, including information for the target prefix.

Attributions

class inseq.data.attribution.FeatureAttributionSequenceOutput(source: List[TokenWithId], target: List[TokenWithId], source_attributions: Optional[Union[Tensor[Tensor], Tensor[Tensor]]] = None, target_attributions: Optional[Union[Tensor[Tensor], Tensor[Tensor]]] = None, step_scores: Optional[Dict[str, Tensor[Tensor]]] = None, sequence_scores: Optional[Dict[str, Tensor[Tensor]]] = None, attr_pos_start: int = 0, attr_pos_end: Optional[int] = None, _aggregator: Optional[Union[AggregatorPipeline, Type[Aggregator]]] = None, _dict_aggregate_fn: Optional[Dict[str, Any]] = None)

Output produced by a standard attribution method.

source

Tokenized source sequence.

Type:

list of TokenWithId

target

Tokenized target sequence.

Type:

list of TokenWithId

source_attributions

Tensor of shape (source_len, target_len) plus an optional third dimension if the attribution is granular (e.g. gradient attribution) containing the attribution scores produced at each generation step of the target for every source token.

Type:

SequenceAttributionTensor

target_attributions

Tensor of shape (target_len, target_len), plus an optional third dimension if the attribution is granular containing the attribution scores produced at each generation step of the target for every token in the target prefix.

Type:

SequenceAttributionTensor, optional

step_scores

Dictionary of step scores produced alongside attributions (one per generation step).

Type:

dict[str, SingleScorePerStepTensor], optional

sequence_scores

Dictionary of sequence scores produced alongside attributions (n per generation step, as for attributions).

Type:

dict[str, MultipleScoresPerStepTensor], optional

classmethod from_step_attributions(attributions: List[FeatureAttributionStepOutput], tokenized_target_sentences: Optional[List[List[TokenWithId]]] = None, pad_id: Optional[Any] = None, has_bos_token: bool = True, attr_pos_end: Optional[int] = None) → List[FeatureAttributionSequenceOutput]

Converts a list of FeatureAttributionStepOutput objects containing multiple examples outputs per step into a list of FeatureAttributionSequenceOutput with every object containing all step outputs for an individual example.

Raises:

ValueError – If the number of sequences in the attributions is not the same for all input sequences.

Returns:

List of FeatureAttributionSequenceOutput objects.

Return type:

List[FeatureAttributionSequenceOutput]

show(min_val: Optional[int] = None, max_val: Optional[int] = None, display: bool = True, return_html: Optional[bool] = False, aggregator: Optional[Union[AggregatorPipeline, Type[Aggregator]]] = None, do_aggregation: bool = True, **kwargs) → Optional[str]

Visualize the attributions.

Parameters:

• min_val (int, optional, defaults to None) – Minimum value in the color range of the visualization. If None, the minimum value of the attributions across all visualized examples is used.

• max_val (int, optional, defaults to None) – Maximum value in the color range of the visualization. If None, the maximum value of the attributions across all visualized examples is used.

• display (bool, optional, defaults to True) – Whether to display the visualization. Can be set to False if the visualization is produced and stored for later use.

• return_html (bool, optional, defaults to False) – Whether to return the HTML code of the visualization.

• aggregator (AggregatorPipeline, optional, defaults to None) – Aggregates attributions before visualizing them. If not specified, the default aggregator for the class is used.

• do_aggregation (bool, optional, defaults to True) – Whether to aggregate the attributions before visualizing them. Allows to skip aggregation if the attributions are already aggregated.

Returns:

The HTML code of the visualization if return_html is set to True, otherwise None.

Return type:

str

weight_attributions(step_fn_id: str)

Weights attribution scores in place by the value of the selected step function for every generation step.

Parameters:

step_fn_id (str) – The id of the step function to use for weighting the attributions (e.g. probability)

class inseq.data.attribution.FeatureAttributionStepOutput(source_attributions: ~typing.Optional[~typing.Union[~torch.Tensor[~torch.Tensor], ~torch.Tensor[~torch.Tensor]]] = None, step_scores: ~typing.Optional[~typing.Dict[str, ~torch.Tensor[~torch.Tensor]]] = None, target_attributions: ~typing.Optional[~typing.Union[~torch.Tensor[~torch.Tensor], ~torch.Tensor[~torch.Tensor]]] = None, sequence_scores: ~typing.Optional[~typing.Dict[str, ~torch.Tensor[~torch.Tensor]]] = None, source: ~typing.Optional[~typing.Sequence[~typing.Sequence[~inseq.utils.typing.TokenWithId]]] = None, prefix: ~typing.Optional[~typing.Sequence[~typing.Sequence[~inseq.utils.typing.TokenWithId]]] = None, target: ~typing.Optional[~typing.Sequence[~typing.Sequence[~inseq.utils.typing.TokenWithId]]] = None, _sequence_cls: ~typing.Type[~inseq.data.attribution.FeatureAttributionSequenceOutput] = <class 'inseq.data.attribution.FeatureAttributionSequenceOutput'>)

Output of a single step of feature attribution, plus extra information related to what was attributed.

remap_from_filtered(target_attention_mask: Tensor[Tensor]) → None

Remaps the attributions to the original shape of the input sequence.

class inseq.data.attribution.FeatureAttributionOutput(sequence_attributions: ~typing.List[~inseq.data.attribution.FeatureAttributionSequenceOutput], step_attributions: ~typing.Optional[~typing.List[~inseq.data.attribution.FeatureAttributionStepOutput]] = None, info: ~typing.Dict[str, ~typing.Any] = <factory>)

Output produced by the AttributionModel.attribute method.

sequence_attributions

List containing all attributions performed on input sentences (one per input sentence, including source and optionally target-side attribution).

Type:

list of FeatureAttributionSequenceOutput

step_attributions

List containing all step attributions (one per generation step performed on the batch), returned if output_step_attributions=True.

Type:

list of FeatureAttributionStepOutput, optional

info

Dictionary including all available parameters used to perform the attribution.

Type:

dict with str keys and any values

aggregate(aggregator: Optional[Union[AggregatorPipeline, Type[Aggregator]]] = None, **kwargs) → FeatureAttributionOutput

Aggregate the sequence attributions using one or more aggregators.

Parameters:

aggregator (AggregatorPipeline or Type[Aggregator], optional) – Aggregator or pipeline to use. If not provided, the default aggregator for every sequence attribution is used.

Returns:

Aggregated attribution output

Return type:

FeatureAttributionOutput

get_scores_dicts(aggregator: Optional[Union[AggregatorPipeline, Type[Aggregator]]] = None, do_aggregation: bool = True, **kwargs) → List[Dict[str, Dict[str, Dict[str, float]]]]

Get all computed scores (attributions and step scores) for all sequences as a list of dictionaries.

Returns:

List containing one dictionary per sequence. Every dictionary contains the keys “source_attributions”, “target_attributions” and “step_scores”. For each of these keys, the value is a dictionary with generated tokens as keys, and for values a final dictionary. For “step_scores”, the keys of the final dictionary are the step score ids, and the values are the scores. For “source_attributions” and “target_attributions”, the keys of the final dictionary are respectively source and target tokens, and the values are the attribution scores.

Return type:

list(dict)

This output is intended to be easily converted to a pandas DataFrame. The following example produces a list of DataFrames, one for each sequence, matching the source attributions that would be visualized by out.show().

`python dfs = [pd.DataFrame(x["source_attributions"]) for x in out.get_scores_dicts()] `

static load(path: PathLike, decompress: bool = False) → FeatureAttributionOutput

Load saved attribution output into a new FeatureAttributionOutput object.

Parameters:

• path (str) – Path to the JSON file containing the saved attribution output. Note that the file must have been saved with the save() method with use_primitives=False in order to be loaded correctly.

• decompress (bool, optional, defaults to False) – If True, the input file is decompressed using gzip.

Returns:

Loaded attribution output

Return type:

FeatureAttributionOutput

classmethod merge_attributions(attributions: List[FeatureAttributionOutput]) → FeatureAttributionOutput

Merges multiple FeatureAttributionOutput objects into a single one.

Merging is allowed only if the two outputs match on the fields specified in _merge_match_info_fields.

Parameters:

attributions (list(FeatureAttributionOutput)) – The FeatureAttributionOutput objects to be merged.

Returns:

Merged object

Return type:

FeatureAttributionOutput

save(path: PathLike, overwrite: bool = False, compress: bool = False, ndarray_compact: bool = True, use_primitives: bool = False, split_sequences: bool = False) → None

Save class contents to a JSON file.

Parameters:

• path (os.PathLike) – Path to the folder where the attribution output will be stored (e.g. ./out.json).

• overwrite (bool, optional, defaults to False) – If True, overwrite the file if it exists, raise error otherwise.

• compress (bool, optional, defaults to False) – If True, the output file is compressed using gzip. Especially useful for large sequences and granular attributions with umerged hidden dimensions.

• ndarray_compact (bool, optional, defaults to True) – If True, the arrays for scores and attributions are stored in a compact b64 format. Otherwise, they are stored as plain lists of floats.

• use_primitives (bool, optional, defaults to False) – If True, the output is stored as a list of dictionaries with primitive types (e.g. int, float, str). Note that an attribution saved with this option cannot be loaded with the load method.

• split_sequences (bool, optional, defaults to False) – If True, the output is split into multiple files, one per sequence. The file names are generated by appending the sequence index to the given path (e.g. ./out.json with two sequences -> ./out_0.json, ./out_1.json)

show(min_val: Optional[int] = None, max_val: Optional[int] = None, display: bool = True, return_html: Optional[bool] = False, aggregator: Optional[Union[AggregatorPipeline, Type[Aggregator]]] = None, **kwargs) → Optional[str]

Visualize the sequence attributions.

Parameters:

• min_val (int, optional) – Minimum value for color scale.

• max_val (int, optional) – Maximum value for color scale.

• display (bool, optional) – If True, display the attribution visualization.

• return_html (bool, optional) – If True, return the attribution visualization as HTML.

• aggregator (AggregatorPipeline or Type[Aggregator], optional) – Aggregator or pipeline to use. If not provided, the default aggregator for every sequence attribution is used.

Returns:

Attribution visualization as HTML if return_html=True, None otherwise.

Return type:

str

class inseq.data.attribution.GradientFeatureAttributionSequenceOutput(source: List[TokenWithId], target: List[TokenWithId], source_attributions: Optional[Union[Tensor[Tensor], Tensor[Tensor]]] = None, target_attributions: Optional[Union[Tensor[Tensor], Tensor[Tensor]]] = None, step_scores: Optional[Dict[str, Tensor[Tensor]]] = None, sequence_scores: Optional[Dict[str, Tensor[Tensor]]] = None, attr_pos_start: int = 0, attr_pos_end: Optional[int] = None, _aggregator: Optional[Union[AggregatorPipeline, Type[Aggregator]]] = None, _dict_aggregate_fn: Optional[Dict[str, Any]] = None)

Raw output of a single sequence of gradient feature attribution. Adds the convergence delta and default L2 + normalization merging of attributions to the base class.

class inseq.data.attribution.GradientFeatureAttributionStepOutput(source_attributions: ~typing.Optional[~typing.Union[~torch.Tensor[~torch.Tensor], ~torch.Tensor[~torch.Tensor]]] = None, step_scores: ~typing.Optional[~typing.Dict[str, ~torch.Tensor[~torch.Tensor]]] = None, target_attributions: ~typing.Optional[~typing.Union[~torch.Tensor[~torch.Tensor], ~torch.Tensor[~torch.Tensor]]] = None, sequence_scores: ~typing.Optional[~typing.Dict[str, ~torch.Tensor[~torch.Tensor]]] = None, source: ~typing.Optional[~typing.Sequence[~typing.Sequence[~inseq.utils.typing.TokenWithId]]] = None, prefix: ~typing.Optional[~typing.Sequence[~typing.Sequence[~inseq.utils.typing.TokenWithId]]] = None, target: ~typing.Optional[~typing.Sequence[~typing.Sequence[~inseq.utils.typing.TokenWithId]]] = None, _sequence_cls: ~typing.Type[~inseq.data.attribution.FeatureAttributionSequenceOutput] = <class 'inseq.data.attribution.GradientFeatureAttributionSequenceOutput'>)

Raw output of a single step of gradient feature attribution. Adds the convergence delta to the base class.

Aggregators

class inseq.data.aggregator.DispatchableDict(default: Optional[Any] = None, *args, **kwargs)

Used to pass specific values to field-specific calls of the aggregate function in Aggregator.

DispatchableDict dictionary objects won’t be passed as a whole to all field-specific functions called by Aggregator.aggregate, and instead only the values with the name of the corresponding field will be used. When these are missing, the default field of DispatchableDict will be used as fallback.

class inseq.data.aggregator.Aggregator

abstract classmethod end_aggregation_hook(tensors: TensorWrapper, **kwargs)

Hook called at the end of the aggregation process.

Use to ensure that the final product of aggregation is compliant with the requirements of individual aggregators.

abstract classmethod post_aggregate_hook(tensors: TensorWrapper, **kwargs)

Hook called right after the aggregation function is called.

Verifies that the aggregated object has the correct properties.

abstract classmethod pre_aggregate_hook(tensors: TensorWrapper, **kwargs)

Hook called right before the aggregation function is called.

Use to ensure a prerequisite that is functional of previous aggregation steps and fundamental to the aggregation process (e.g. the aggregatable object produced by the previous step has correct shapes).

abstract classmethod start_aggregation_hook(tensors: TensorWrapper, **kwargs)

Hook called at the start of the aggregation process.

Use to ensure a prerequisite that is independent of previous aggregation steps and fundamental to the aggregation process (e.g. parameters are of the correct type). Will avoid performing aggregation steps before returning an error.

class inseq.data.aggregator.AggregatorPipeline(aggregators: List[Type[Aggregator]])

class inseq.data.aggregator.AggregableMixin

aggregate(aggregator: Optional[Union[AggregatorPipeline, Type[Aggregator]]] = None, **kwargs) → AggregableMixin

Aggregate attributions using the default or provided aggregator.

Parameters:

aggregator (AggregatorPipeline or Type[Aggregator], optional) – Aggregator pipeline to use. If not provided, the default aggregator pipeline is used.

Returns:

The aggregated output class.

Return type:

AggregableMixin

class inseq.data.aggregator.SequenceAttributionAggregator

Aggregates sequence attributions using a custom function. By default, the identity function is used.

Represent the identity aggregator for the FeatureAttributionSequenceOutput class.

Parameters:

• attr (FeatureAttributionSequenceOutput) – The attribution object to aggregate.

• aggregate_fn (Callable, optional) – Function used to aggregate sequence attributions. Defaults to summing over the last dimension and renormalizing by the norm of the source(+target) attributions for granular attributions, no aggregation for token-level attributions.

classmethod end_aggregation_hook(attr: TensorWrapper, **kwargs)

Hook called at the end of the aggregation process.

Use to ensure that the final product of aggregation is compliant with the requirements of individual aggregators.

classmethod post_aggregate_hook(attr, **kwargs)

Hook called right after the aggregation function is called.

Verifies that the aggregated object has the correct properties.

class inseq.data.aggregator.ContiguousSpanAggregator

Reduces sequence attributions across one or more contiguous spans.

Parameters:

• attr (FeatureAttributionSequenceOutput) – The attribution object to aggregate.

• aggregate_fn (Callable, optional) – Function used to aggregate sequence attributions. Defaults to the highest absolute value score across the aggregated span, with original sign preserved (e.g. [0.3, -0.7, 0.1] -> -0.7).

• source_spans (tuple of [int, int] or sequence of tuples of [int, int], optional) – Spans to aggregate over for the source sequence. Defaults to no aggregation performed.

• target_spans (tuple of [int, int] or sequence of tuples of [int, int], optional) – Spans to aggregate over for the target sequence. Defaults to no aggregation performed.

classmethod aggregate(attr, aggregate_fn: Optional[Union[Callable, Dict[str, Any]]] = None, source_spans: Optional[Union[Tuple[int, int], Sequence[Tuple[int, int]]]] = None, target_spans: Optional[Union[Tuple[int, int], Sequence[Tuple[int, int]]]] = None, **kwargs)

Spans can be:

1. A list of the form [pos_start, pos_end] including the contiguous positions of tokens that

   are to be aggregated, if all values are integers and len(span) < len(original_seq)

2. A list of the form [(pos_start_0, pos_end_0), (pos_start_1, pos_end_1)], same as above but

   for multiple contiguous spans.

classmethod end_aggregation_hook(attr: TensorWrapper, **kwargs)

Hook called at the end of the aggregation process.

Use to ensure that the final product of aggregation is compliant with the requirements of individual aggregators.

classmethod start_aggregation_hook(attr, source_spans=None, target_spans=None, **kwargs)

Hook called at the start of the aggregation process.

Use to ensure a prerequisite that is independent of previous aggregation steps and fundamental to the aggregation process (e.g. parameters are of the correct type). Will avoid performing aggregation steps before returning an error.

class inseq.data.aggregator.SubwordAggregator

Aggregates over subwords by automatic detecting contiguous subword spans.

Parameters:

• attr (FeatureAttributionSequenceOutput) – The attribution object to aggregate.

• aggregate_fn (Callable, optional) – Function to aggregate over the subwords. Defaults to the highest absolute value score across the aggregated span, with original sign preserved (e.g. [0.3, -0.7, 0.1] -> -0.7).

• aggregate_source (bool, optional) – Whether to aggregate over the source sequence. Defaults to True.

• aggregate_target (bool, optional) – Whether to aggregate over the target sequence. Defaults to True.

• special_symbol (str, optional) – Symbol used to identify subwords. Defaults to ‘▁’, used by SentencePiece. If is_suffix_symbol=True, then this symbol is used to identify parts to be aggregated (e.g. # in WordPiece, [‘phen’, ‘##omen’, ‘##al’]). Otherwise, it identifies the roots that should be preserved (e.g. ▁ in SentencePiece, [’▁phen’, ‘omen’, ‘al’]).

• is_suffix_symbol (bool, optional) – Whether the special symbol is used to identify suffixes or prefixes. Defaults to False.

classmethod aggregate(attr, aggregate_fn: Optional[Union[Callable, Dict[str, Any]]] = None, aggregate_source: bool = True, aggregate_target: bool = True, special_symbol: str = '▁', is_suffix_symbol: bool = False, **kwargs)

Spans can be:

1. A list of the form [pos_start, pos_end] including the contiguous positions of tokens that

   are to be aggregated, if all values are integers and len(span) < len(original_seq)

2. A list of the form [(pos_start_0, pos_end_0), (pos_start_1, pos_end_1)], same as above but

   for multiple contiguous spans.

class inseq.data.aggregator.PairAggregator

Aggregates two FeatureAttributionSequenceOutput object into a single one containing the diff.

Parameters:

• attr (FeatureAttributionSequenceOutput) – The starting attribution object.

• paired_attr (FeatureAttributionSequenceOutput) – The attribution object with whom the diff is computed, representing a change from attr_start (e.g. minimal pair edit).

• aggregate_fn (Callable, optional) – Function to aggregate elementwise values of the pair. Defaults to the difference between the two elements.

classmethod pre_aggregate_hook(attr, paired_attr, **kwargs)

Hook called right before the aggregation function is called.

Use to ensure a prerequisite that is functional of previous aggregation steps and fundamental to the aggregation process (e.g. the aggregatable object produced by the previous step has correct shapes).