Main Functions

The functions described in this section can be called from the top level of the inseq library and implement the base functionalities required for its usage.

inseq.get_version() → str[source]

Returns the current version of the Inseq library.

inseq.list_feature_attribution_methods()[source]

Lists identifiers for all available feature attribution methods. A feature attribution method identifier (e.g. integrated_gradients) can be passed to AttributionModel or load_model() to define a model for attribution.

inseq.list_step_functions() → List[str][source]

Lists identifiers for all available step scores. One or more step scores identifiers can be passed to the attribute() method either to compute scores while attributing (step_scores parameter), or as target function for the attribution, if supported by the attribution method (attributed_fn parameter).

inseq.load_model(model: Union[str, PreTrainedModel], attribution_method: Optional[str] = None, framework: str = 'hf_transformers', **kwargs) → AttributionModel[source]

Factory function to load a model with or without attribution methods.

Parameters:

  • model (Union[ModelIdentifier, ModelClass]) – Either a model identifier (e.g. gpt2 in HF transformers) or an instance of a model class supported by the selected modeling framework.

  • attribution_method (Optional[str], optional, defaults to None) – Identifier for the attribution method to use. If None, the model will be loaded without any attribution methods, which can be added during attribution.

  • framework (str, optional, defaults to β€œhf_transformers”) – The framework to use for loading the model. Currently, only HF transformers is supported.

Returns:

An instance of one of AttributionModel children classes matching the selected framework and model architecture.

Return type:

AttributionModel

inseq.register_step_function(fn: StepScoreFunction, identifier: str, aggregate_map: Optional[Dict[str, Callable[[Tensor], Tensor]]] = None) → None[source]

Registers a function to be used to compute step scores and store them in the FeatureAttributionOutput object. Registered step functions can also be used as attribution targets by gradient-based feature attribution methods.

Parameters:

  • fn (callable) – The function to be used to compute step scores. Default parameters (use kwargs to capture

  • function) (unused ones when defining your) –

    • attribution_model: an AttributionModel instance, corresponding to the model

      used for computing the score.

    • forward_output: the output of the forward pass from the attribution model.

    • encoder_input_ids, decoder_input_ids, encoder_input_embeds,

      decoder_input_embeds, encoder_attention_mask, decoder_attention_mask: all the elements composing the Batch used as context of the model.

    • target_ids: torch.Tensor of target token ids of size (batch_size,) and type long,

      corresponding to the target predicted tokens for the next generation step.

    The function can also define an arbitrary number of custom parameters that can later be provided directly to the model.attribute function call, and it must return a torch.Tensor of size (batch_size,) of float or long. If parameter names conflict with model.attribute ones, pass them as key-value pairs in the step_scores_args dict parameter.

  • identifier (str) – The identifier that will be used for the registered step score.

  • aggregate_map (dict, optional) – An optional dictionary mapping from Aggregator name identifiers to functions taking in input a tensor of shape (batch_size, seq_len) and producing tensors of shape (batch_size, aggregated_seq_len) in output that will be used to aggregate the registered step score when used in conjunction with the corresponding aggregator. E.g. the probability step score uses the aggregate_map {"span_aggregate": lambda x: t.prod(dim=1, keepdim=True)} to aggregate probabilities with a product when aggregating scores over spans.

inseq.show_attributions(attributions: FeatureAttributionSequenceOutput, min_val: Optional[int] = None, max_val: Optional[int] = None, display: bool = True, return_html: Optional[bool] = False) → Optional[str][source]

Core function allowing for visualization of feature attribution maps in console/HTML format.

Parameters:

  • attributions (FeatureAttributionSequenceOutput) – Sequence attributions to be visualized.

  • min_val (Optional[int], optional, defaults to None) – Lower attribution score threshold for color map.

  • max_val (Optional[int], optional, defaults to None) – Upper attribution score threshold for color map.

  • display (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.

Returns:

Returns the HTML output if return_html=True

Return type:

Optional[str]