Reports of Drift Values

tables

get_drift_tables(dimension_drift_loaders, periods=None, dimensions=None, metrics=None, semantic_score_key='magnitude', syntactic_content_score_key='magnitude', syntactic_style_score_key='magnitude', lexical_score_key='magnitude', thematic_score_key='magnitude', fill_diagonal=np.nan, sort_periods=True, aggregate_by=None, aggregation_func=np.nanmean, absolute_values=True, min_values=1, normalize='minmax', **kwargs)

Generate drift tables for specified dimensions and metrics.

This function computes drift tables for given dimensions and metrics using the provided drift loaders. It supports aggregation, normalization, and filtering of the results.

Parameters:

Name	Type	Description	Default
dimension_drift_loaders	dict	Dictionary mapping dimensions to their respective drift loading functions.	required
periods	list	Periods to consider. Defaults to None.	None
dimensions	list	Dimensions to include. If None, all dimensions in dimension_drift_loaders are used. Defaults to None.	None
metrics	list	Metrics to compute. Defaults to ["mmd", "cos", "ks", "kl", "js", "log"].	None
semantic_score_key	str	Key for semantic scores in drift data. Defaults to "magnitude".	'magnitude'
syntactic_content_score_key	str	Key for syntactic content scores in drift data. Defaults to "magnitude".	'magnitude'
syntactic_style_score_key	str	Key for syntactic style scores in drift data. Defaults to "magnitude".	'magnitude'
lexical_score_key	str	Key for lexical scores in drift data. Defaults to "magnitude".	'magnitude'
thematic_score_key	str	Key for thematic scores in drift data. Defaults to "magnitude".	'magnitude'
fill_diagonal	float	Value used to fill the diagonal of the tables. Defaults to np.nan.	nan
sort_periods	bool	Whether to sort periods before generating tables. Defaults to True.	True
aggregate_by	(None, metric, dimension)	Aggregation level. Defaults to None.	None
aggregation_func	callable	Function used for aggregation. Defaults to np.nanmean.	nanmean
absolute_values	bool	Whether to use absolute values for scores. Defaults to True.	True
min_values	int	Minimum number of values required for aggregation. Defaults to 1.	1
normalize	(None, minmax, zscore)	Normalization method. Defaults to "minmax".	None
**kwargs		Additional keyword arguments.	{}

Returns:

Type	Description
dict or DataFrame	Dictionary of drift tables grouped by dimension and metric, or an aggregated table depending on aggregate_by.

Raises:

Type	Description
ValueError	If invalid dimensions are provided.
ValueError	If aggregate_by is not one of None, "metric", or "dimension".
ValueError	If normalize is not one of None, "minmax", or "zscore".

heatmaps

generate_magnitude_heatmaps(meta_tables, export=True, period_labels=None, base_filename='', figsize=(8, 6), cmap='RdYlGn_r', fmt='.3f', title='', **kwargs)

Generate heatmaps to visualize drift magnitude from meta tables.

This function supports three input structures: a single DataFrame, a dictionary mapping dimensions to DataFrames, or a nested dictionary mapping dimensions and metrics to DataFrames.

Parameters:

Name	Type	Description	Default
meta_tables	DataFrame or dict	Input data used to generate heatmaps. Supported formats are: A single DataFrame. A dictionary with dimensions as keys and DataFrames as values. A nested dictionary with dimensions as keys, metrics as sub-keys, and DataFrames as values.	required
export	bool	Whether to export the generated heatmaps as SVG files. Defaults to True.	True
period_labels	list	Labels applied to the table periods. Defaults to None.	None
base_filename	str	Base filename used when exporting heatmaps. Defaults to an empty string.	''
figsize	tuple	Figure size in inches. Defaults to (8, 6).	(8, 6)
cmap	str	Colormap used for the heatmaps. Defaults to "RdYlGn_r".	'RdYlGn_r'
fmt	str	Format used for heatmap cell annotations. Defaults to ".3f".	'.3f'
title	str	Title used for the generated heatmaps. Defaults to an empty string.	''
**kwargs		Additional keyword arguments.	{}

Returns:

Type	Description
Figure or dict or None	Generated heatmap figure or figures. A single Figure if meta_tables is a DataFrame. A dictionary of Figures if meta_tables is a dictionary. None if meta_tables is empty or has an unsupported structure.

Notes

• This function applies period labels using _apply_period_labels and generates each heatmap using _plot_heatmap.
• Warnings are logged for empty tables, invalid tables, or unsupported meta_tables structures.

plot_aggregated_dimension_values_heatmap(tables, period_labels=None, dimensions_order=None, dimension_labels=None, dimension_short_names=None, title='Multidimensional discourse drift by dimension', cmap_name='RdYlGn_r', figsize=(26, 8), filename=None, show_values=True, export=False, **kwargs)

Plot a heatmap to visualize multidimensional discourse drift across dimensions and periods.

This function generates a heatmap where each cell represents the drift score between two periods for different dimensions. The heatmap supports customization of labels, colormaps, displayed values, and export options.

Parameters:

Name	Type	Description	Default
tables	dict	Dictionary where keys are dimension names and values are pandas DataFrames containing drift scores. DataFrame indices and columns represent periods.	required
period_labels	dict	Mapping between period identifiers and display labels. Defaults to None.	None
dimensions_order	list	Order of dimensions displayed in the heatmap. If None, uses the order of tables.keys(). Defaults to None.	None
dimension_labels	dict	Mapping between dimension names and full display labels. Defaults to predefined labels.	None
dimension_short_names	dict	Mapping between dimension names and abbreviated labels. Defaults to predefined short names.	None
title	str	Heatmap title. Defaults to "Multidimensional discourse drift by dimension".	'Multidimensional discourse drift by dimension'
cmap_name	str	Name of the matplotlib colormap. Defaults to "RdYlGn_r".	'RdYlGn_r'
figsize	tuple	Figure size in inches. Defaults to (26, 8).	(26, 8)
filename	str	Output file path used when exporting the heatmap. Defaults to None.	None
show_values	bool	Whether to display drift values inside heatmap cells. Defaults to True.	True
export	bool	Whether to export the heatmap to a file. Defaults to False.	False
**kwargs		Additional keyword arguments for customization.	{}

Returns:

Type	Description
tuple	Tuple containing the matplotlib Figure and Axes objects.

Notes

• Drift scores are expected to be normalized between 0 and 1.
• Diagonal cells comparing the same period are displayed with a dash ("—").
• If export is True and filename is provided, the heatmap is exported as an SVG file.