Multivariate chart

daspi.plotlib.chart.MultivariateChart(source, target, feature='', hue='', shape='', size='', col='', row='', dodge=False, stretch_figsize=False, categorical_feature=False, target_on_y=True, colors=None, markers=None, n_size_bins=CATEGORY.N_SIZE_BINS)

Bases: SingleChart

Represents a chart visualization that handles multiple variables simultaneously.

This class extends the functionality of SingleChart to create visualizations for multiple variables, allowing for comparisons and insights across different dimensions.

PARAMETER	DESCRIPTION
source	The source data for the chart. TYPE: DataFrame
target	The target variable (dependent variable). TYPE: str
feature	The feature variable (independent variable), by default ''. TYPE: str DEFAULT: ''
hue	The hue variable (color grouping), by default ''. TYPE: str DEFAULT: ''
shape	The shape variable (marker grouping), by default ''. TYPE: str DEFAULT: ''
size	The size variable (marker size grouping), by default ''. TYPE: str DEFAULT: ''
col	The column variable for facetting, by default ''. TYPE: str DEFAULT: ''
row	The row variable for facetting, by default ''. TYPE: str DEFAULT: ''
dodge	Whether to dodge categorical variables, by default False. TYPE: bool DEFAULT: False
stretch_figsize	If True, the height and width of the figure are stretched based on the number rows and columns in the axes grid. If a float is provided, the figure size is stretched by the given factor. If a tuple of two floats is provided, the figure size is stretched by the given factors for the x and y axis, respectively. by default False. TYPE: bool | float | Tuple[float, float] DEFAULT: False
categorical_feature	Whether the feature variable is categorical. If dodge is True, this will be automatically set to True, by default False. TYPE: bool DEFAULT: False
target_on_y	Flag indicating whether the target variable is plotted on the y-axis, by default True TYPE: bool DEFAULT: True
colors	Tuple of unique colors used for hue categories as hex or str, by default CATEGORY.PALETTE. TYPE: Tuple[str, ...] | None DEFAULT: None
markers	Tuple of markers used for shape marker categories as strings, by default CATEGORY.MARKERS. TYPE: Tuple[str, ...] DEFAULT: None
n_size_bins	Number of bins for the size range, by default CATEGORY.N_SIZE_BINS. TYPE: int DEFAULT: N_SIZE_BINS

Examples:

import daspi as dsp
df = dsp.load_dataset('iris')

chart = dsp.MultivariateChart(
        source=df,
        target='length',
        feature='width',
        hue='species',
        col='leaf',
        markers=('x',)
    ).plot(
        dsp.GaussianKDEContour
    ).plot(
        dsp.Scatter
    ).label(
        feature_label='leaf width (cm)',
        target_label='leaf length (cm)',
    )

col = col instance-attribute

The column variable for facetting (if applicable).

row = row instance-attribute

The row variable for facetting (if applicable).

row_labels = self.unique_labels(self.row) instance-attribute

Labels corresponding to categorical values in the row variable.

col_labels = self.unique_labels(self.col) instance-attribute

Labels corresponding to categorical values in the column variable.

row_or_col_changed property

Check whether the current variate belongs to a new row or column relative to the last variate

plot(plotter, *, skip_variate=[], kw_call={}, kw_where={}, **kwds)

Plot the chart using the specified plotter.

This method generates a subset of the source data specific to each axes and then uses this data for the specified plotter.

PARAMETER	DESCRIPTION
plotter	The type of plotter to use. TYPE: Type[Plotter]
skip_variate	A list of variate names to skip during the grouping. If provided, these variates will not be included in the groupby operation. Default is None TYPE: List[str] DEFAULT: []
kw_call	Additional keyword arguments for the plotter call method. TYPE: Dict[str, Any] DEFAULT: {}
kw_where	Do not use this argument in this instance. TYPE: dict DEFAULT: {}
**kwds	Additional keyword arguments for the plotter object. Here you can set the plotter specific initialization parameters. Do not override the standard parameters color, marker, target_on_y, size (marker size) and width (for categorical feature plots). These parameters are handled automatically by the class. For more flexibility, use the JointChart class. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
Self	The updated MultivariateChart object.

stripes(stripes=[], *, mean=False, median=False, control_limits=False, spec_limits=SpecLimits(), confidence=None, strategy='norm', agreement=6, **kwds)

Plot location and spread width lines, specification limits and/or confidence interval areas as stripes on each Axes. The location and spread (and their confidence bands) represent the data per axes.

PARAMETER	DESCRIPTION
stripes	Additional non-predefined stripes to be added to the chart, by default []. TYPE: List[Stripe] DEFAULT: []
mean	Whether to plot the mean value of the plotted data on the axes, by default False. TYPE: bool DEFAULT: False
median	Whether to plot the median value of the plotted data on the axes, by default False. TYPE: bool DEFAULT: False
control_limits	Whether to plot control limits representing the process spread, by default False. TYPE: bool DEFAULT: False
spec_limits	If provided, specifies the specification limits. Default is SpecLimits(). TYPE: Tuple[float] DEFAULT: SpecLimits()
confidence	The confidence level between 0 and 1, by default None. TYPE: float DEFAULT: None
strategy	Which strategy should be used to determine the control limits (process spread): - eval: The strategy is determined according to the given evaluate function. If none is given, the internal evaluate method is used. - fit: First, the distribution that best represents the process data is searched for and then the agreed process spread is calculated - norm: it is assumed that the data is subject to normal distribution. The variation tolerance is then calculated as agreement * standard deviation - data: The quantiles for the process variation tolerance are read directly from the data. Default is 'norm'. TYPE: (eval, fit, norm, data) DEFAULT: 'eval'
agreement	Specify the tolerated process variation for which the control limits are to be calculated. - If int, the spread is determined using the normal distribution agreementsigma, e.g. agreement = 6 -> 6sigma ~ covers 99.75 % of the data. The upper and lower permissible quantiles are then calculated from this. - If float, the value must be between 0 and 1.This value is then interpreted as the acceptable proportion for the spread, e.g. 0.9973 (which corresponds to ~ 6 sigma) Default is 6 because SixSigma ;-) TYPE: int or float DEFAULT: 6
**kwds	Additional keyword arguments for configuring StripesFacets. DEFAULT: {}

RETURNS	DESCRIPTION
SingleChart	The instance of the SingleChart with the specified stripes plotted on the axes.

Notes

This method plots stripes on the chart axes to represent statistical measures such as mean, median, control limits, and specification limits. The method provides options to customize the appearance and behavior of the stripes using various parameters and keyword arguments.

label(*, fig_title='', sub_title='', feature_label='', target_label='', info=False, row_title='', col_title='', feature_formatter=None, target_formatter=None, feature_angle=0.0, target_angle=0.0, feature_align='center', target_align='center')

Add labels and titles to the multivariate chart with advanced formatting.

This method sets various labels and titles for the multivariate chart, including figure title, subtitle, axis labels, row and column titles, and provides extensive formatting control for tick labels across all subplots in the faceted grid.

PARAMETER	DESCRIPTION
fig_title	The main title for the entire figure, displayed at the top, by default ''. TYPE: str DEFAULT: ''
sub_title	The subtitle for the entire figure, displayed below the main title, by default ''. TYPE: str DEFAULT: ''
feature_label	The label for the feature variable axis across all subplots, by default ''. If set to True, the feature variable name will be used. If set to False or None, no label will be added. TYPE: str | bool | None DEFAULT: ''
target_label	The label for the target variable axis across all subplots, by default ''. If set to True, the target variable name will be used. If set to False or None, no label will be added. TYPE: str | bool | None DEFAULT: ''
info	Additional information to display on the chart. If True, the date and user information will be automatically added at the lower left corner of the figure. If a string is provided, it will be shown next to the date and user, separated by a comma. By default, no additional information is displayed. TYPE: bool | str DEFAULT: False
row_title	The title for the row facet variable, displayed on the right side of the figure. If not provided and row faceting is used, the row variable name will be used automatically, by default ''. TYPE: str DEFAULT: ''
col_title	The title for the column facet variable, displayed at the top of the figure above the column labels. If not provided and column faceting is used, the column variable name will be used automatically, by default ''. TYPE: str DEFAULT: ''
feature_formatter	Formatter for the feature axis tick labels applied to all subplots that share the feature axis. Supports multiple input types for maximum flexibility: String format templates: Simple format strings using Python's string formatting syntax (e.g., '{:.2f}', '{:.1e}', '${:.0f}', '{:.1%}') Callable functions: Custom functions that take one or two arguments and return formatted strings Matplotlib Formatters: Any matplotlib.ticker.Formatter instance for advanced formatting control None: Use matplotlib's default formatting Applied consistently across all subplots for uniform appearance. By default, None. TYPE: Formatter | Callable | str | None DEFAULT: None
target_formatter	Formatter for the target axis tick labels applied to all subplots that share the target axis. Same options and behavior as feature_formatter. By default, None. TYPE: Formatter | Callable | str | None DEFAULT: None
feature_angle	Rotation angle for feature axis tick labels in degrees, applied to all subplots. Positive values rotate counter-clockwise, negative values rotate clockwise. The chart automatically adjusts margins to accommodate rotated labels across the entire grid. By default, 0.0 (no rotation). TYPE: float DEFAULT: 0.0
target_angle	Rotation angle for target axis tick labels in degrees, applied to all subplots. Same behavior as feature_angle but for the target axis. By default, 0.0 (no rotation). TYPE: float DEFAULT: 0.0
feature_align	Alignment for feature axis tick labels applied to all subplots that share the feature axis. 'center' aligns the label center with the tick, 'left' aligns the left edge, 'right' aligns the right edge. Particularly useful with rotated labels. By default, 'center'. TYPE: (center, right, left) DEFAULT: 'center'
target_align	Alignment for target axis tick labels applied to all subplots that share the target axis. For horizontal target axes, this controls horizontal alignment. For vertical target axes, this maps to vertical alignment: 'center' centers the label, 'left' maps to 'bottom', 'right' maps to 'top'. By default, 'center'. TYPE: (center, right, left) DEFAULT: 'center'

RETURNS	DESCRIPTION
MultivariateChart	The instance of the MultivariateChart with updated labels and titles for method chaining.

Examples:

Basic multivariate chart labeling:

chart.label(
    fig_title='Sales Analysis by Region and Quarter',
    sub_title='2024 Performance Data',
    feature_label='Sales Amount ($)',
    target_label='Customer Count',
    row_title='Geographic Region',
    col_title='Quarter',
    info='Source: Sales database'
)

Formatting across all subplots:

# Currency formatting for feature, percentage for target
chart.label(
    feature_formatter='${:,.0f}',  # $1,234
    target_formatter='{:.1%}',     # 12.3%
    feature_angle=30,              # Rotate currency labels
    feature_align='right'          # Right-align rotated labels
)

Custom formatters for scientific data:

def scientific_formatter(value):
    if abs(value) >= 1000:
        return f'{value:.1e}'  # Scientific notation
    return f'{value:.2f}'      # Regular decimal

chart.label(
    fig_title='Experimental Results',
    feature_formatter=scientific_formatter,
    target_formatter='{:.3f}',
    col_title='Treatment Group',
    row_title='Time Point'
)

Handling long category names in faceted plots:

chart.label(
    fig_title='Product Performance Analysis',
    feature_formatter=lambda x: x.replace('_', ' ').title(),
    feature_angle=45,              # Diagonal for readability
    feature_align='right',         # Better alignment when rotated
    target_formatter='${:,.0f}K',  # Thousands with currency
    row_title='Product Category',
    col_title='Sales Channel'
)

Notes

• All formatting options are applied consistently across the entire subplot grid for uniform appearance
• Row and column titles are automatically inferred from faceting variables if not explicitly provided
• The chart automatically adjusts spacing and margins to accommodate rotated labels across all subplots
• String formatters are automatically converted to matplotlib-compatible formatters and applied to all relevant axes
• Formatting respects axis sharing - shared axes get consistent formatting