mllm_shap.utils package#

Submodules#

mllm_shap.utils.audio module#

Utility functions for audio processing and display.

class mllm_shap.utils.audio.TorchAudioHandler[source]#

Bases: object

Utility class for handling audio content with TorchAudio.

static combine(audio_segments: list[pydub.AudioSegment], target_audio_format: str = 'wav') → bytes[source]#

Combine multiple AudioSegment instances into a single waveform tensor.

Parameters:

  • audio_segments – A list of AudioSegment instances.

  • target_audio_format – The desired audio format for the output (default is “wav”).

Returns:

A bytes object containing the combined audio data.

static from_bytes(audio_content: bytes, audio_format: str = 'mp3') → tuple[Tensor, int][source]#

Prepare audio content for processing.

Parameters:

  • audio_format – The format of the audio content (default is “mp3”).

  • audio_content – The audio content in bytes.

Returns:

A tuple containing the audio tensor and the sample rate.

static to_bytes(waveform: Tensor, sample_rate: int = 24000, audio_format: str = 'wav', mp3_bitrate: str = '192k') → bytes[source]#

Convert a waveform tensor to audio content in bytes.

Parameters:

  • waveform – The audio waveform tensor.

  • sample_rate – The sample rate of the audio (default is TARGET_SAMPLE_RATE).

  • audio_format – The desired audio format (“wav” or “mp3”).

  • mp3_bitrate – The bitrate for MP3 encoding (default is “192k”).

Returns:

The audio content in bytes.

mllm_shap.utils.audio.display_audio(audio_content: bytes) → Audio[source]#

Display audio content in a Jupyter notebook.

Parameters:

audio_content – The audio content in bytes.

mllm_shap.utils.jupyter module#

Utility functions for Jupyter Notebook visualization.

mllm_shap.utils.jupyter.audio_html(content: bytes) → str[source]#

Generate HTML representation for audio content.

Parameters:

content – Audio content in bytes.

Returns:

HTML representation of the audio.

Return type:

str

mllm_shap.utils.jupyter.display_shap_colors_df(df: DataFrame, shap_column_name: str = 'Shapley Value', cmap: str = 'coolwarm', low: float = 0.0, high: float = 1.0, **kwargs: Any) → Styler[source]#

Set background gradient colors for SHAP values in a DataFrame.

Parameters:

  • df – DataFrame containing SHAP values.

  • shap_column_name – Name of the column with SHAP values.

  • cmap – Colormap to use for the gradient.

  • low – Minimum value for the gradient.

  • high – Maximum value for the gradient.

  • **kwargs – Additional arguments for pandas Styler.background_gradient.

Returns:

Styled DataFrame with background gradient.

Return type:

pd.Styler

mllm_shap.utils.jupyter.display_shap_colors_df_audio(df: DataFrame, audio_column_name: str = 'Audio', **kwargs: Any) → Styler[source]#

Set background gradient colors for SHAP values in a DataFrame with audio. Render audio in the specified audio column for jupyter notebooks.

Parameters:

  • df – DataFrame containing SHAP values and audio.

  • audio_column_name – Name of the column with audio.

  • **kwargs – Additional arguments for display_shap_colors_df.

Returns:

Styled DataFrame with background gradient.

Return type:

pd.Styler

mllm_shap.utils.jupyter.plot_distribution(values: Tensor, bins: int = 50, **kwargs: Any) → None[source]#

Plot histogram of SHAP values distribution.

Parameters:

  • values – Tensor of SHAP values.

  • bins – Number of bins for the histogram.

  • **kwargs – Additional arguments for matplotlib.pyplot.hist.

mllm_shap.utils.logger module#

Logging utilities.

mllm_shap.utils.logger.get_logger(name: str) → Logger[source]#

Get a logger with the specified name.

Parameters:

name – The name of the logger.

Returns:

A configured logger instance.

mllm_shap.utils.other module#

General utility functions.

mllm_shap.utils.other.extend_tensor(t: Tensor, target_length: int, fill_value: Any) → Tensor[source]#

Extend a tensor to the target length by appending the fill value.

Parameters:

  • t – The input tensor to be extended.

  • target_length – The desired length of the output tensor.

  • fill_value – The value to use for extension.

Returns:

The extended tensor.

mllm_shap.utils.other.make_consecutive_ids_ignore_zero(t: Tensor) → Tensor[source]#

Renumber non-zero tensor values to consecutive integers starting from 1, preserving the order of first appearance. Zeros remain unchanged.

Parameters:

t – Input tensor with integer IDs.

Returns:

Tensor with renumbered IDs.

mllm_shap.utils.other.raise_connector_error(callable_: Callable[[...], Any], *args: Any, **kwargs: Any) → Any[source]#

Wrapper to raise connector errors with more context.

Parameters:

  • callable – The callable to wrap.

  • *args – Positional arguments for the callable.

  • **kwargs – Keyword arguments for the callable.

Returns:

The result of the callable.

Raises:

RuntimeError – If an error occurs in the callable.

mllm_shap.utils.other.safe_mask(tensor: Tensor, mask: Tensor) → Tensor[source]#

Mask the tensor with the given mask. If mask is empty, return empty Tensor while maintaining the original tensor properties.

Parameters:

  • tensor – The input tensor to be masked.

  • mask – The boolean mask tensor.

Returns:

The masked tensor.

mllm_shap.utils.other.safe_mask_unsqueeze(tensor: Tensor, mask: Tensor) → Tensor[source]#

Mask the tensor with the given mask. If mask is empty, return empty Tensor while maintaining the original tensor properties, and unsqueeze to maintain batch dimension.

Parameters:

  • tensor – The input tensor to be masked.

  • mask – The boolean mask tensor.

Returns:

The masked tensor with batch dimension.

Module contents#

Module for utility functions used project wise, e.g., Jupyter Notebook visualization.