matplotalt package

Module contents

chart_descriptions module

class chart_descriptions.AreaDescription(ax, fig=None, **kwargs)

Bases: ChartDescription

The class for generating area plot descriptions. Has functions to automatically generate descriptions for encodings, axes, annotations, statistics, trends and the overall chart. Infers chart data, encodings, etc… from the figure attributes.

ax

The axis object for the chart to describe

Type:

matplotlib.axes._subplots.AxesSubplot

fig

The figure object for the chart to describe. If no figure is given, it is inferred from plt.gcf()

Type:

matplotlib.figure.Figure, optional

\*\*kwargs

Used to manually specify chart_type, data, and other details of chart descriptions including number of signifigant figures, max line width, etc…

Type:

optional

get_encodings_desc(max_color_desc_count=4, sig_figs=4, **kwargs)

See get_stats_desc(). Additionally includes descriptions of any vertical and horizontal lines in the form: ‘There are vertical lines at x={vertical_line_xs}’

get_stats_desc(stats=['min_y', 'max_y', 'mean_y'], stat_axis='y', **kwargs)

See get_stats_desc()

See get_trends_desc()

class chart_descriptions.BarDescription(ax, fig=None, **kwargs)

Bases: ChartDescription

The class for generating bar chart / histogram descriptions. Has functions to automatically generate descriptions for encodings, axes, annotations, statistics, trends and the overall chart. Infers chart data, encodings, etc… from the figure attributes.

ax

The axis object for the chart to describe

Type:

matplotlib.axes._subplots.AxesSubplot

fig

The figure object for the chart to describe. If no figure is given, it is inferred from plt.gcf()

Type:

matplotlib.figure.Figure, optional

\*\*kwargs

Used to manually specify chart_type, data, and other details of chart descriptions including number of signifigant figures, max line width, etc…

Type:

optional

get_encodings_desc(*args, **kwargs)

See get_encodings_desc()

get_stats_desc(stats=['numpts', 'min', 'max', 'mean'], stat_axis=None, **kwargs)

See get_stats_desc()

See get_trends_desc()

class chart_descriptions.BoxplotDescription(ax, fig=None, **kwargs)

Bases: ChartDescription

The class for generating boxplot descriptions. Has functions to automatically generate descriptions for encodings, axes, annotations, statistics, trends and the overall chart. Infers chart data, encodings, etc… from the figure attributes.

ax

The axis object for the chart to describe

Type:

matplotlib.axes._subplots.AxesSubplot

fig

The figure object for the chart to describe. If no figure is given, it is inferred from plt.gcf()

Type:

matplotlib.figure.Figure, optional

\*\*kwargs

Used to manually specify chart_type, data, and other details of chart descriptions including number of signifigant figures, max line width, etc…

Type:

optional

get_axes_desc(*args, **kwargs)

See get_axes_desc()

get_data_as_md_table(**kwargs)
get_encodings_desc(*args, **kwargs)

See get_encodings_desc()

get_stats_desc(stats=['median', 'iqr', 'outliers'], max_outliers_desc=4, sig_figs=4, **kwargs)

Return a description of the provided statistics for each box.

stats

The statistics to compute and describe. Currently supported options include: [“median”, “quartiles”, “iqr”, “outliers”]

Type:

array_like

max_outliers_desc

The maximum number of outlier points to list in descriptions. Defaults to 4

Type:

int, optional

Returns:

The descriptions of each given stat

Return type:

str

TODO

class chart_descriptions.ChartDescription(ax, fig=None, chart_type=None)

Bases: object

The top-level class for chart descriptions. Has functions to generate descriptions for encodings, axes, annotations, and the overall chart without assuming the chart type.

ax

The axis object for the chart to describe

Type:

matplotlib.axes._subplots.AxesSubplot

fig

The figure object for the chart to describe. If no figure is given, it is inferred from plt.gcf()

Type:

matplotlib.figure.Figure, optional

chart_type

The chart type of the figure to describe. Defaults to None

Type:

str, optional

sig_figs

The number of signifigant figures to use in chart descriptions. Defaults to 4

Type:

int

max_color_desc_count

The max number of color encodings to include in chart descriptions. Defaults to 4

Type:

int

Returns:

None

get_annotations_desc(include_coords=False, max_annotations_desc=5, sig_figs=4)

Return descriptions of all annotations in the figure with the form: ‘An annotation reads: {annotation_text}’

include_coords

Whether the annotations coordinates should be included in the description. If True, descriptions add the line ‘near x={ano_x_pos}, y={ano_y_pos}’ before the annotation text.

Type:

bool, optional

Returns:

The descriptions of each annotation

Return type:

str

get_axes_desc(ax_names=None, sig_figs=4)

Return a description of the chart’s axes in the form: ‘{ax_label} is plotted on the {ax_name}-axis from {min} to {max}.’ If an axis does not have a label, descriptions are of the form: ‘the {ax_name} ranges from {min} to {max}’

ax_names

The names of the axes to describe (e.g. [“x”, “y”, “z”]). If none are given, all axes with data will be described. Defaults to None

Type:

list[str], optional

Returns:

The axes description

Return type:

str

get_chart_desc(desc_level=2, **kwargs)

Return a description of the chart of the form:

‘{chart type + title description}

{axes description} {encodings description} {annotations description} {statistics description} {trends description}’

based on the given description level

get_chart_dict()
get_chart_type_desc()

Return a description of the current chart type of the form: ‘A {formatted chart_type} titled {chart_title}’

get_data_as_md_table(max_rows=20, max_cols=20, sig_figs=4)
get_encodings_desc(max_color_desc_count=4, mark_type=None, sig_figs=4)

Return a description of the color encodings for each variable in the figure of the form: ‘{variable_name} is plotted in {variable_color}’ If the number of variables to describe exceeds the max_color_desc_count, descriptions are of the form: ‘{num_variables} {object_name} are plotted for {[all variable names]}’ (e.g. ‘12 groups of points are plotted for Jan, Feb,…’)

Returns:

The description of each variable’s color encoding

Return type:

str

get_stats_desc(stats=[], max_var_stats=5, max_outliers_desc=4, stat_axis=None, sig_figs=4)

Given data and labels from the figure, return a description of the provided statistics along the given axis.

ax_name_to_data

A dictionary mapping each axis name to its (n, d) data for each variable, e.g. {“x”: [[1, 2, 3], [1, 2, 3]], “y”: [[0.112, 0.415, 0.734], [0.225, 0.123, 0.849]]} If there is only one variable data can also be shape (d) e.g. {“x”: [1, 2, 3], “y”: [0.112, 0.415, 0.734]}

Type:

dict[str -> array_like]

ax_name_to_ticklabels

A dictionary mapping each axis name to its (n, d) or (d) ticklabels

Type:

dict[str -> array_like]

stats

The statistics to compute and describe. Currently supported options include: [“min”, “max”, “mean”, “median”, “std”, “outliers”, “linearfit”, “numpts”]

Type:

array_like

var_idx

The data index of the variable to describe in the given (n, d) axis data. If None is given, assumes data is of shape (d)

Type:

int, optional

stat_axis

The axis to compute statistics along. E.g. if “y” is given, then statistics will be computed using the data in ax_name_to_data[“y”]. Axes can also be specified for individual statistics by appending ‘_{ax_name}’ to the stat name. For instance, ‘max_x’ will compute the max along the x-axis.

Type:

str, optional

max_outliers_desc

The maximum number of outlier points to list in descriptions. Defaults to 4

Type:

int, optional

Raises:

ValueError – if given an unsupported statistic

Returns:

A list of the descriptions of each given stat

Return type:

list[str]

parse_annotations()
parse_axes()
parse_data(ax_name_to_data, mark_type)
parse_encodings(var_labels=None)
parse_title()
class chart_descriptions.ContourDescription(ax, fig=None, **kwargs)

Bases: ChartDescription

The class for generating contour plot descriptions. Has functions to automatically generate descriptions for encodings, axes, annotations, statistics, trends and the overall chart. Infers chart data, encodings, etc… from the figure attributes.

ax

The axis object for the chart to describe

Type:

matplotlib.axes._subplots.AxesSubplot

fig

The figure object for the chart to describe. If no figure is given, it is inferred from plt.gcf()

Type:

matplotlib.figure.Figure, optional

\*\*kwargs

Used to manually specify chart_type, data, and other details of chart descriptions including number of signifigant figures, max line width, etc…

Type:

optional

get_data_as_md_table(*args, **kwargs)
get_encodings_desc(*args, **kwargs)

See get_encodings_desc()

get_stats_desc(stats=['max_center'], sig_figs=4, **kwargs)

Return a description of the provided statistics for each box.

stats

The statistics to compute and describe. Currently supported options include: [“centers”]

Type:

array_like

Returns:

The descriptions of each given stat

Return type:

str

class chart_descriptions.HeatmapDescription(ax, fig=None, **kwargs)

Bases: ChartDescription

The class for generating heatmap descriptions. Has functions to automatically generate descriptions for encodings, axes, annotations, statistics, trends and the overall chart. Infers chart data, encodings, etc… from the figure attributes.

ax

The axis object for the chart to describe

Type:

matplotlib.axes._subplots.AxesSubplot

fig

The figure object for the chart to describe. If no figure is given, it is inferred from plt.gcf()

Type:

matplotlib.figure.Figure, optional

\*\*kwargs

Used to manually specify chart_type, data, and other details of chart descriptions including number of signifigant figures, max line width, etc…

Type:

optional

get_chart_type_desc()

Return a description of the current heatmap title of the form: ‘A {heatmap_width}x{heatmap_height} titled {heatmap_title}’

get_stats_desc(stats=['min_z', 'max_z', 'mean_z'], stat_axis='z', **kwargs)

See get_stats_desc()

class chart_descriptions.ImageDescription(ax, fig=None, **kwargs)

Bases: ChartDescription

The class for generating image descriptions (e.g. those created with plt.imshow). Has functions to automatically generate descriptions for encodings, axes, annotations, statistics, trends and the overall chart. Infers chart data, encodings, etc… from the figure attributes.

ax

The axis object for the chart to describe

Type:

matplotlib.axes._subplots.AxesSubplot

fig

The figure object for the chart to describe. If no figure is given, it is inferred from plt.gcf()

Type:

matplotlib.figure.Figure, optional

\*\*kwargs

Used to manually specify chart_type, data, and other details of chart descriptions including number of signifigant figures, max line width, etc…

Type:

optional

get_chart_type_desc()

Return a description of the current heatmap title of the form: ‘A {heatmap_width}x{heatmap_height} titled {heatmap_title}’

get_stats_desc(stats=['min_z', 'max_z', 'mean_z'], stat_axis='z', **kwargs)

See get_stats_desc()

class chart_descriptions.LineDescription(ax, fig=None, **kwargs)

Bases: ChartDescription

The class for generating line plot descriptions. Has functions to automatically generate descriptions for encodings, axes, annotations, statistics, trends and the overall chart. Infers chart data, encodings, etc… from the figure attributes.

ax

The axis object for the chart to describe

Type:

matplotlib.axes._subplots.AxesSubplot

fig

The figure object for the chart to describe. If no figure is given, it is inferred from plt.gcf()

Type:

matplotlib.figure.Figure, optional

\*\*kwargs

Used to manually specify chart_type, data, and other details of chart descriptions including number of signifigant figures, max line width, etc…

Type:

optional

get_encodings_desc(max_color_desc_count=4, sig_figs=4, **kwargs)

See get_stats_desc(). Additionally includes descriptions of any vertical and horizontal lines in the form: ‘There are vertical lines at “x”={vertical_line_xs}’

get_stats_desc(stats=['min_y', 'max_y', 'mean_y'], stat_axis='y', **kwargs)

See get_stats_desc()

See get_trends_desc()

class chart_descriptions.PieDescription(ax, fig=None, max_slices_desc=15, **kwargs)

Bases: ChartDescription

The class for generating pie chart descriptions. Has functions to automatically generate descriptions for encodings, axes, annotations, statistics, trends and the overall chart. Infers chart data, encodings, etc… from the figure attributes.

ax

The axis object for the chart to describe

Type:

matplotlib.axes._subplots.AxesSubplot

fig

The figure object for the chart to describe. If no figure is given, it is inferred from plt.gcf()

Type:

matplotlib.figure.Figure, optional

max_slices_desc

The maximum number of slices to name in the description. Defaults to 15.

Type:

int, optional

\*\*kwargs

Used to manually specify chart_type, data, and other details of chart descriptions including number of signifigant figures, max line width, etc…

Type:

optional

get_axes_desc(sig_figs=4)

Return a description of the pie chart’s axes in the form: ‘{ax_label} is plotted with {num_wedges} wedges: {wedge_label} ({wedge_percentage}), …’ If an axis does not have a label, descriptions are of the form: ‘There are {num_wedges} wedges: {wedge_label} ({wedge_percentage}), …’ If there are no labels for the wedges, does not list the wedges with their percentages

Returns:

The axes description

Return type:

str

get_data_as_md_table(max_rows=20, max_cols=20, sig_figs=4)
get_encodings_desc(*args, **kwargs)

Returns nothing

get_stats_desc(stats=['min', 'max', 'mean'], stat_axis='x', **kwargs)

See get_stats_desc()

See get_trends_desc()

parse_encodings(var_labels=None)
class chart_descriptions.ScatterDescription(ax, fig=None, **kwargs)

Bases: ChartDescription

The class for generating 2D scatter plot descriptions. Has functions to automatically generate descriptions for encodings, axes, annotations, statistics, trends and the overall chart. Infers chart data, encodings, etc… from the figure attributes.

ax

The axis object for the chart to describe

Type:

matplotlib.axes._subplots.AxesSubplot

fig

The figure object for the chart to describe. If no figure is given, it is inferred from plt.gcf()

Type:

matplotlib.figure.Figure, optional

\*\*kwargs

Used to manually specify chart_type, data, and other details of chart descriptions including number of signifigant figures, max line width, etc…

Type:

optional

get_stats_desc(stats=['numpts', 'mean_x', 'mean_y', 'linearfit', 'outliers'], stat_axis=None, **kwargs)

See get_stats_desc()

parse_encodings(var_labels=None)
class chart_descriptions.StripDescription(ax, fig=None, **kwargs)

Bases: ChartDescription

The class for generating strip plot descriptions. Has functions to automatically generate descriptions for encodings, axes, annotations, statistics, trends and the overall chart. Infers chart data, encodings, etc… from the figure attributes.

ax

The axis object for the chart to describe

Type:

matplotlib.axes._subplots.AxesSubplot

fig

The figure object for the chart to describe. If no figure is given, it is inferred from plt.gcf()

Type:

matplotlib.figure.Figure, optional

\*\*kwargs

Used to manually specify chart_type, data, and other details of chart descriptions including number of signifigant figures, max line width, etc…

Type:

optional

get_stats_desc(stats=['numpts', 'median', 'outliers'], stat_axis=None, **kwargs)

See get_stats_desc()

TODO

parse_encodings(var_labels=None)

matplotalt_helpers module

matplotalt_helpers.assert_equal_shapes(arrays)

Raises a value error if the given arrays do not all have the same shape

matplotalt_helpers.create_md_table(headers_to_data, sig_figs=4)
matplotalt_helpers.create_new_cell(contents)

Creates a new code cell in jupyter with the given contents

matplotalt_helpers.format_float(f, sig_figs=4, tol=1e-10)

returns the float as a string with the given number of signifigant figures

matplotalt_helpers.format_float_list(l, sig_figs)

Returns the given list as ‘a, b, c, …, and d’ with each element rounded to the given number of signifigant figures

matplotalt_helpers.format_list(l)

Returns the given list as ‘a, b, c, …, and d’

matplotalt_helpers.format_str(s)
matplotalt_helpers.gcf_as_pil_img()
matplotalt_helpers.get_ax_ticks_scale(ax_ticks, r_thresh=0.97)
matplotalt_helpers.get_color_name(color_input)

Converts hex codes and rgb triplets to a color name like ‘darkblue’

matplotalt_helpers.hex_to_rgb(h)

Convert hex code to rgb triplet

matplotalt_helpers.idx_pt_desc(idxs, chart_dict, var_name, excluded_axis, sig_figs=4)
matplotalt_helpers.infer_model_chart_type(ax=None, model='KaiNylund/chart-classifier-tiny')
matplotalt_helpers.infer_single_axis(ax=None)
matplotalt_helpers.insert_line_breaks(text, max_line_width=80)

Breaks the given text into lines of max length max_line_width

matplotalt_helpers.is_date(s)

Returns True if string is a date.

matplotalt_helpers.is_notebook()
matplotalt_helpers.is_number(s)

Returns True if string is a number.

matplotalt_helpers.pillow_image_to_base64_string(img)

Convert PIL png to base64 string

matplotalt_helpers.url_safe(s)