ParallelCoords

Each record as a polyline across one axis per dimension. The Parallel Coordinates guide shows every feature on real data; this page is the contract: the function, the shape of its data, the keys style takes, and the constant each parameter accepts.

Function

datachart.charts.ParallelCoords

ParallelCoords(
    data: (
        list[ParallelCoordsDataPointAttrs]
        | list[list[ParallelCoordsDataPointAttrs]]
    ),
    *,
    title: str | None = None,
    xlabel: str | None = None,
    ylabel: str | None = None,
    subtitle: str | list[str | None] | None = None,
    emphasis: (
        EMPHASIS | str | list[str | None] | None
    ) = None,
    emphasis_rule: EmphasisRuleAttrs | None = None,
    figsize: FIG_SIZE | tuple[float, float] | None = None,
    show_legend: bool | None = None,
    legend: LegendSettingAttrs | None = None,
    show_grid: SHOW_GRID | str | bool | None = None,
    aspect_ratio: ASPECT_RATIO | str | None = None,
    style: (
        ParallelCoordsStyleAttrs
        | list[ParallelCoordsStyleAttrs | None]
        | None
    ) = None,
    dimensions: list[str] | list[list[str]] | None = None,
    hue: str | list[str | None] | None = None,
    category_orders: dict[str, list[str]] | None = None,
    texts: (
        TextSettingAttrs
        | list[TextSettingAttrs]
        | list[
            TextSettingAttrs | list[TextSettingAttrs] | None
        ]
        | None
    ) = None
) -> plt.Figure

Creates the parallel coordinates chart.

Parallel coordinates draw each record as a polyline across one vertical axis per dimension. Use it to explore multivariate data: clusters show as bundles of similar lines, and correlations between neighboring dimensions show as parallel or crossing segments. Works best with a handful of dimensions; color the records by group with hue to compare groups.

Examples:

>>> from datachart.charts import ParallelCoords
>>> figure = ParallelCoords(
...     data=[
...         {"sepal_length": 5.1, "sepal_width": 3.5, "petal_length": 1.4, "petal_width": 0.2, "species": "setosa"},
...         {"sepal_length": 4.9, "sepal_width": 3.0, "petal_length": 1.4, "petal_width": 0.2, "species": "setosa"},
...         {"sepal_length": 7.0, "sepal_width": 3.2, "petal_length": 4.7, "petal_width": 1.4, "species": "versicolor"},
...     ],
...     title="Iris Dataset",
...     hue="species",
...     dimensions=["sepal_length", "sepal_width", "petal_length", "petal_width"],
...     show_legend=True
... )

PARAMETER	DESCRIPTION
`data`	The data points for the chart. Each data point is a dictionary where keys are dimension names and values are numeric or string values. Can optionally include a hue key for categorical coloring. TYPE: `list[ParallelCoordsDataPointAttrs] \| list[list[ParallelCoordsDataPointAttrs]]`
`title`	The title of the chart. TYPE: `str \| None` DEFAULT: `None`
`xlabel`	The x-axis label. TYPE: `str \| None` DEFAULT: `None`
`ylabel`	The y-axis label. TYPE: `str \| None` DEFAULT: `None`
`subtitle`	The subtitle(s) for individual charts. TYPE: `str \| list[str \| None] \| None` DEFAULT: `None`
`emphasis`	The emphasis role(s), aligned with the data rows (a single value applies to every row): "background" mutes a row (theme muted color, lowered alpha, thinner line, behind the others, no hue legend entry), "highlight" bolds it and brings it to the front among the data rows, None leaves it unchanged. TYPE: `EMPHASIS \| str \| list[str \| None] \| None` DEFAULT: `None`
`emphasis_rule`	A rule that highlights the data rows matching it and mutes the rest: `{"above": v}` or `{"below": v}` (strict), `{"between": (lo, hi)}` (inclusive), `{"top": n}` or `{"bottom": n}`, read against each row's numeric `hue` value; no `hue`, or a non-numeric one, raises. An explicit `emphasis` role wins, and a count ranks across the rows of every chart. The rule takes no `by`. See `EmphasisRuleAttrs`. TYPE: `EmphasisRuleAttrs \| None` DEFAULT: `None`
`figsize`	The size of the figure. TYPE: `FIG_SIZE \| tuple[float, float] \| None` DEFAULT: `None`
`show_legend`	Whether to show the legend (for hue categories). TYPE: `bool \| None` DEFAULT: `None`
`legend`	The per-figure legend setting: title, location, column count and alignment; each field falls back to the theme. See `LegendSettingAttrs`. TYPE: `LegendSettingAttrs \| None` DEFAULT: `None`
`show_grid`	Which grid lines to show (e.g., "both", "x", "y"); `False` draws none. TYPE: `SHOW_GRID \| str \| bool \| None` DEFAULT: `None`
`aspect_ratio`	The aspect ratio of the axes ("auto" or "equal"). See `ASPECT_RATIO`. TYPE: `ASPECT_RATIO \| str \| None` DEFAULT: `None`
`style`	Style configuration(s) for the lines. TYPE: `ParallelCoordsStyleAttrs \| list[ParallelCoordsStyleAttrs \| None] \| None` DEFAULT: `None`
`dimensions`	List of dimension names to include and their order. If None, all columns (except hue) are auto-detected. With several data sets, a flat list applies to every set and a list of lists gives one list per set; every set shares one axis, so the lists must be equal. TYPE: `list[str] \| list[list[str]] \| None` DEFAULT: `None`
`hue`	The key name in data for line coloring. String values color categorically: data points with the same hue value get the same color from `color_parallel_hue`. Numeric values color continuously along the theme's `color_parallel_hue_continuous` ramp, which spans every row, muted ones included. TYPE: `str \| list[str \| None] \| None` DEFAULT: `None`
`category_orders`	Dictionary mapping dimension names to lists of category values in the desired order. Example: {"rating": ["Low", "Medium", "High"]}. Categories not in the list will be appended at the end (sorted). TYPE: `dict[str, list[str]] \| None` DEFAULT: `None`
`texts`	Text annotation(s) to draw. TYPE: `TextSettingAttrs \| list[TextSettingAttrs] \| list[TextSettingAttrs \| list[TextSettingAttrs] \| None] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`plt.Figure`	The figure containing the parallel coordinates chart.

Data

Each record in data is a ParallelCoordsDataPointAttrs; the hue parameter renames its keys.

datachart.typings.ParallelCoordsDataPointAttrs

Bases: TypedDict

The data point attributes for the parallel coordinates chart.

A dictionary where keys are dimension names and values are numeric values. Can optionally include a 'hue' key for categorical coloring.

ATTRIBUTE	DESCRIPTION
`hue`	The category for color grouping. TYPE: `str \| None`

Style

style takes the keys of ParallelCoordsStyleAttrs. The chart also reads the shared groups it draws: text annotations (TextStyleAttrs). Every key falls back to the theme, so the same keys set the default look through config.

datachart.typings.ParallelCoordsStyleAttrs

Bases: TypedDict

The typing for the parallel coordinates chart style.

ATTRIBUTE	DESCRIPTION
`plot_parallel_color`	The line color. TYPE: `str \| None`
`plot_parallel_alpha`	The alpha value of the lines. TYPE: `float \| None`
`plot_parallel_width`	The line width. TYPE: `int \| float \| None`
`plot_parallel_style`	The line style. TYPE: `LINE_STYLE \| str \| None`
`plot_parallel_marker`	The marker style for data points. TYPE: `LINE_MARKER \| str \| None`
`plot_parallel_zorder`	The draw order of data lines. TYPE: `int \| None`
`plot_parallel_axis_color`	The vertical axis line color. TYPE: `str \| None`
`plot_parallel_axis_width`	The vertical axis line width. TYPE: `int \| float \| None`
`plot_parallel_axis_zorder`	The vertical axis line draw order. TYPE: `int \| None`
`plot_parallel_tick_color`	The tick mark color. TYPE: `str \| None`
`plot_parallel_tick_width`	The tick mark line width. TYPE: `int \| float \| None`
`plot_parallel_tick_length`	The tick mark length. TYPE: `float \| None`
`plot_parallel_tick_label_size`	The tick label font size. TYPE: `int \| float \| None`
`plot_parallel_tick_label_color`	The tick label font color. TYPE: `str \| None`
`plot_parallel_tick_label_bg_color`	The tick label background color; `None` draws no box and strokes the label with the value halo instead. TYPE: `str \| None`
`plot_parallel_tick_label_bg_alpha`	The tick label background alpha. TYPE: `float \| None`
`plot_parallel_dim_label_size`	The dimension label font size. TYPE: `int \| float \| None`
`plot_parallel_dim_label_color`	The dimension label font color. TYPE: `str \| None`
`plot_parallel_dim_label_rotation`	The dimension label rotation. TYPE: `int \| float \| None`
`plot_parallel_dim_label_pad`	The dimension label padding from axis. TYPE: `int \| float \| None`

Constants

The parameters that accept a constant, with the class in datachart.constants that lists its values.

Parameter	Constant
`emphasis`	`EMPHASIS`
`figsize`	`FIG_SIZE`
`legend={"location": ..., "alignment": ...}`	`LEGEND_LOCATION`, `LEGEND_ALIGN`
`show_grid`	`SHOW_GRID`
`aspect_ratio`	`ASPECT_RATIO`