WinTSR

Window-aware attribution that scores temporal and feature relevance jointly. See the quickstart for a minimal example or the integration cookbook for model-specific recipes.

tslens.WinTSR

WinTSR(model: Union[Attribution, Callable], legacy_normalize: bool = False)

Bases: Occlusion

Windowed Temporal Saliency Rescaling.

A two-stage interpretation method for time series models. Stage one computes a time-relevance score per time step by occluding whole time steps. Stage two computes a feature-relevance score only on the time steps that clear a relevance threshold, using a sliding window that respects temporal dependencies. The two are multiplied to give the final attribution.

Parameters:

Name	Type	Description	Default
model	Union[Attribution, Callable]	the model to interpret. Either a plain callable / nn.Module taking (batch, seq_len, n_features), or an already-constructed Captum/tint :class:~captum.attr._utils.attribution.Attribution instance to use as the inner method. A bare model is wrapped in :class:tint.attr.Occlusion, which is the configuration reported in the paper.	required
legacy_normalize	bool	reproduce the exact time-relevance normalization of the original research code. That code normalized every sample in the batch by sample 0's min/max (an amax(...)[0] slip left over from torch.max) instead of normalizing each sample independently. Thresholding is unaffected -- it is a per-row quantile, invariant to a shared affine transform -- but the final attribution magnitudes are. Defaults to False (per-sample normalization). Set to True to reproduce numbers from the paper's artifact exactly.	False

Example

import torch from tslens import WinTSR explainer = WinTSR(model) attr = explainer.attribute( ... inputs=torch.randn(8, 96, 7), ... baselines=torch.zeros(8, 96, 7), ... )

attribute

attribute(inputs: TensorOrTupleOfTensorsGeneric, sliding_window_shapes: Optional[Union[Tuple[int, ...], Tuple[Tuple[int, ...], ...]]] = None, strides: Union[None, int, Tuple[int, ...], Tuple[Union[int, Tuple[int, ...]], ...]] = None, baselines: BaselineType = None, target: TargetType = None, additional_forward_args: Any = None, threshold: float = 0.0, normalize: bool = True, perturbations_per_eval: int = 1, show_progress: bool = False, unflatten: bool = True, **kwargs: Any) -> TensorOrTupleOfTensorsGeneric

Compute WinTSR attributions.

Parameters:

Name	Type	Description	Default
inputs	TensorOrTupleOfTensorsGeneric	tensor or tuple of tensors shaped (batch, seq_len, n_features). All inputs must share the time dimension.	required
sliding_window_shapes	Optional[Union[Tuple[int, ...], Tuple[Tuple[int, ...], ...]]]	window shape per input, excluding the batch dimension. Defaults to all-ones (one time step, one feature), the setting used in the paper.	None
strides	Union[None, int, Tuple[int, ...], Tuple[Union[int, Tuple[int, ...]], ...]]	step size of the sliding window. Defaults to the window shape.	None
baselines	BaselineType	replacement values for occluded regions. Defaults to zero.	None
target	TargetType	output index to attribute, for multi-output models.	None
additional_forward_args	Any	extra arguments passed to the model.	None
threshold	float	quantile in [0, 1) of the time-relevance score below which time steps are skipped in stage two. Higher is faster and sparser; 0.0 keeps every time step.	0.0
normalize	bool	min-max normalize the time-relevance scores.	True
perturbations_per_eval	int	number of perturbations batched per forward. Only supported for single-output models; anything returning more than one output per example must leave this at 1. This is an upstream limitation of tint's FeatureAblation.	1
show_progress	bool	display a progress bar.	False
unflatten	bool	return attributions shaped (batch, n_output, seq_len, n_features). The underlying computation produces a flat (batch * n_output, seq_len, n_features); set to False for that raw layout. This is a pure reshape -- the values are identical either way.	True

Returns:

Type	Description
TensorOrTupleOfTensorsGeneric	Attributions shaped (batch, n_output, seq_len, n_features), or
TensorOrTupleOfTensorsGeneric	(batch * n_output, seq_len, n_features) when unflatten is
TensorOrTupleOfTensorsGeneric	False. A tuple of these if inputs was a tuple.

get_time_relevance_score

get_time_relevance_score(inputs: TensorOrTupleOfTensorsGeneric, baselines: BaselineType = None, target: TargetType = None, additional_forward_args: Any = None, perturbations_per_eval: int = 1, show_progress: bool = False)

Stage one: occlude whole time steps to score temporal relevance.