API Reference

Visualizer

class exploralytics.Visualizer(color='#94C973', height=768, width=1366, template='simple_white', colorscale=['rgb(161, 105, 40)', 'rgb(189, 146, 90)', 'rgb(214, 189, 141)', 'rgb(237, 234, 194)', 'rgb(181, 200, 184)', 'rgb(121, 167, 172)', 'rgb(40, 135, 161)'], texts_font_style: str | None = None, title_bold: bool = False)

Bases: object

A class to create and customize data visualizations using Plotly.

This class provides methods to generate various plots with consistent styling and formatting. It allows customization of plot colors, dimensions, templates, and other visual elements.

color

Color code for plot elements (default: “#94C973”)

Type:

str

height

Height of the plot in pixels (default: 768)

Type:

int

width

Width of the plot in pixels (default: 1366)

Type:

int

template

Plotly template name (default: “simple_white”)

Type:

str

colorscale

Colorscale for the plot (default: px.colors.diverging.Earth)

Type:

list

texts_font_style

Font style for text elements in the plot (default: None)

Type:

str, optional

title_bold

Flag to set the plot title in bold (default: False)

Type:

bool

__init__(color='#94C973', height=768, width=1366, template='simple_white', colorscale=px.colors.diverging.Earth, texts_font_style=None, title_bold=False)

Initializes the Visualizer with the specified parameters.

plot_correlation_map(df: DataFrame, title: str = 'How correlated the numerical values are?', subtitle: str = 'Correlation matrix of columns with numerical data type', footer: str | None = None) → Figure

Create a correlation matrix heatmap showing relationships between numerical columns.

Generates a triangular heatmap visualization where each cell shows the correlation between two variables. Only shows the lower triangle to avoid redundancy. Includes hover text and annotations for correlation values.

Parameters:

• df (pandas.DataFrame) – Input dataframe containing the numerical columns to correlate

• title (str, optional) – Main title for the plot (default: ‘How correlated the numerical values are?’)

• subtitle (str, optional) – Subtitle to display below main title (default: ‘Correlation matrix of columns with numerical data type’)

• footer (str, optional) – Text to show at bottom of plot

Returns:

Figure containing the correlation heatmap

Return type:

plotly.graph_objects.Figure

plot_correlation_with_target(df: DataFrame, target_column: str, title: str = 'How correlated the features are with the target?', subtitle: str = 'Correlation coefficient of each feature', footer: str | None = None) → Figure

Create a horizontal bar chart showing how each feature correlates with a target variable.

This visualization helps identify which features have strong positive or negative relationships with the target variable. Positive correlations are shown in blue, negative in light red. Values range from -1 (perfect negative correlation) to 1 (perfect positive correlation).

Parameters:

• df (pandas.DataFrame) – Input dataframe containing numerical columns to analyze

• target_column (str) – Name of the column to compare other features against

• title (str, optional) – Main title for the plot (default: ‘How correlated the features are with the target?’)

• subtitle (str, optional) – Subtitle to display below main title (default: ‘Correlation coefficient of each feature’)

• footer (str, optional) – Text to show at bottom of plot

Returns:

Interactive bar chart showing correlation coefficients

Return type:

plotly.graph_objects.Figure

plot_dot(df: DataFrame, x_col: str, y_col: str, title: str = 'How are the categories distributed?', subtitle: str = 'Dot plot of categories', footer: str | None = None, add_hline_at: tuple[str, float] | None = None, top_n: int | None = None, highlight_top_n: tuple[int, str] | None = None, highlight_low_n: tuple[int, str] | None = None) → Figure

Create a dot plot showing values as dots with connecting lines to x-axis.

This plot shows values as dots above their categories, with vertical lines connecting each dot to its category on the x-axis. Can highlight highest/lowest values with different colors and show a reference line at a specific value.

Parameters:

• df (pandas.DataFrame) – Data to plot

• x_col (str) – Column name for categories on x-axis

• y_col (str) – Column name for values shown as dot heights

• title (str, optional) – Main title of plot

• subtitle (str, optional) – Subtitle shown below main title

• footer (str, optional) – Text to show at bottom of plot

• add_hline_at (tuple[str, float], optional) – Reference line (label, value) to add

• top_n (int, optional) – Number of dots to show, ordered by value

• highlight_top_n (tuple[int, str], optional) – (number, color) for highlighting highest values

• highlight_low_n (tuple[int, str], optional) – (number, color) for highlighting lowest values

Returns:

Interactive dot plot figure

Return type:

plotly.graph_objects.Figure

plot_hbar(df: DataFrame, x_col: str, y_col: str | None = None, title: str = 'How distributed are the categories?', subtitle: str = 'Horizontal bar plot of categories', footer: str | None = None, add_hline: bool = False, top_n: int | None = None, highlight_top_n: tuple[int, str] | None = None, highlight_low_n: tuple[int, str] | None = None) → Figure

Create a horizontal bar plot with optional highlighting and statistics.

Shows either value counts of a single column or relationship between two columns. Can highlight top/bottom values and show mean line. Bars can be limited to show only top N values.

Parameters:

• df (pandas.DataFrame) – The data to plot

• x_col (str) – Name of column to show on y-axis of plot

• y_col (str, optional) – Name of column for bar lengths. If None, shows value counts of x_col

• title (str, optional) – Main title of plot (default: “How distributed are the categories?”)

• subtitle (str, optional) – Subtitle shown below main title (default: “Horizontal bar plot of categories”)

• footer (str, optional) – Text to show at bottom of plot

• top_n (int, optional) – Number of bars to show. If None, shows all

• add_hline (bool, optional) – Whether to add mean line (default: False)

• highlight_top_n (tuple, optional) – Tuple of (n, hex color code) to highlight top n bars

• highlight_low_n (tuple, optional) – Tuple of (n, hex color code) to highlight bottom n bars

Returns:

Interactive horizontal bar plot

Return type:

plotly.graph_objects.Figure

plot_histograms(df: DataFrame, specific_cols: list[str] = [], num_cols: int = 1, title: str = 'How distributed the numerical values are?', subtitle: str = 'Histogram of each column with numerical data type', footer: str | None = None, show_mean: bool = False, show_median: bool = False) → Figure

Create multiple histogram subplots for numerical columns in a dataframe.

Creates a grid of histograms showing the distribution of numerical data. Can optionally show mean and median lines on each histogram.

Parameters:

• df (pandas.DataFrame) – Input dataframe containing the data to plot

• specific_cols (list, optional) – List of specific columns to plot (default: empty list, plots all numerical columns)

• num_cols (int, optional) – Number of columns in the subplot grid (default: 1)

• title (str, optional) – Main title of the plot

• subtitle (str, optional) – Subtitle of the plot

• footer (str, optional) – Text to show at bottom of plot

• show_mean (bool, optional) – Whether to show mean line on histograms (default: False)

• show_median (bool, optional) – Whether to show median line on histograms (default: False)

• font_family (str, optional) – Font family for text elements (default: None)

• title_bold (bool, optional) – Whether to make title text bold (default: False)

Returns:

Figure containing the histogram subplots

Return type:

plotly.graph_objects.Figure

Utility Functions

exploralytics.visualize.utils.add_footer(fig: Figure, footer_text: str, footer_url: str | None = None, footer_font_size: int = 10, footer_color: str = 'gray', y_offset: float = -0.19, x_offset: float = 0) → Figure

Add a footer to a Plotly figure with optional clickable link.

Parameters:

• fig (plotly.graph_objects.Figure) – The figure to add the footer to

• footer_text (str) – The text to display in the footer

• footer_url (str, optional) – URL to link to in the footer. If provided, makes footer clickable

• footer_font_size (int, optional) – Size of the footer text (default: 10)

• footer_color (str, optional) – Color of the footer text (default: “gray”)

• y_offset (float, optional) – Vertical position of footer relative to plot (default: -0.20)

• x_offset (float, optional) – Horizontal position of footer relative to plot (default: 0)

Returns:

Figure with added footer

Return type:

plotly.graph_objects.Figure

exploralytics.visualize.utils.highlight_bars_colors(highlight_top_n: tuple, highlight_low_n: tuple, data_length: DataFrame)

Create color array for highlighted bars.

Parameters:

• highlight_top_n (tuple or None) – (n, color) for top n bars

• highlight_low_n (tuple or None) – (n, color) for bottom n bars

• data_length (int) – Total number of bars

Returns:

List of colors for each bar

Return type:

list

exploralytics.visualize.utils.identify_num_rows(columns: list[str], desired_num_col: int) → int

Calculate how many rows are needed to display a set of plots in a grid layout.

Determines the number of rows needed to fit all plots when organizing them into columns. Handles both when plots divide evenly into columns and when they don’t.

Parameters:

• columns (list) – List of items that need to be arranged in a grid

• desired_num_col (int) – Number of columns to arrange the plots into

Returns:

Number of rows needed for the grid layout

Return type:

int