Skip to content

DensityCurve

DensityCurve

Bases: SpreadOpacity, TransformPlotter

Base class for plotting a probability density curve along the feature axis.

This class holds all the logic shared by the density-curve plotters (data grouping, optional quantile highlighting, filling and drawing). Subclasses only need to implement :meth:estimate, which computes the sequence of target values and the corresponding density estimation for one feature group:

  • GaussianKDE estimates the density non-parametrically from the raw data and controls the curve width via margin.
  • FittedDensity fits (or assumes) a distribution according to strategy and evaluates its PDF, controlling the curve width via agreements instead of margin.

If cumulative is set to True, the cumulative distribution (CDF) is plotted instead of the density (PDF). Subclasses may override :meth:estimate_cumulative to compute the CDF directly (e.g. from a fitted distribution's analytic cdf); by default it is derived by numerically integrating :meth:estimate.

PARAMETER DESCRIPTION
source

Pandas long format DataFrame containing the data source for the plot.

TYPE: pandas DataFrame

target

Column name of the target variable for the plot.

TYPE: str

feature

Column name of the feature variable for the plot, by default ''. Please note that this class is designed for univariate plots, so by default, all curves will be drawn on the same feature axis. If you want to draw curves on different feature axes, change the "ignore_feature" parameter to False and provide a feature column in the source DataFrame.

TYPE: str DEFAULT: ''

stretch

Factor by which the curve was stretched in height, by default 1.

TYPE: float DEFAULT: 1

height

Height of the density curve at its maximum. If None, it will be determined automatically, by default None.

TYPE: float | None DEFAULT: None

skip_na

Flag indicating whether to skip missing values in the feature grouped data, by default None - None, no missing values are skipped - 'all', grouped data is skipped if all values are missing - 'any', grouped data is skipped if any value is missing

TYPE: Literal['none', 'all', 'any'] DEFAULT: None

ignore_feature

Flag indicating whether the feature axis should be ignored. If True, all curves have base 0 on the feature axis, by default True

TYPE: bool DEFAULT: True

margin

Margin for the sequence as factor of data range (max - min ). If margin is 0, The two ends of the estimated density curve then show the minimum and maximum value. Default is 0.

TYPE: float DEFAULT: 0

fill

Flag whether to fill in the curves, by default True. Has no effect if cumulative is True: the area under a CDF has no meaningful interpretation as probability mass (unlike a PDF), so it is never filled.

TYPE: bool DEFAULT: True

agreements

Specifies the tolerated process variation for calculating quantiles. These quantiles are used to represent the filled area with different opacity, thus highlighting the quantiles.If you want the filled area to be uniform without highlighting the quantiles, provide an empty tuple. This argument is only taken into account if fill is set to True. The agreements can be either integers or floats, determining the process variation tolerance in the following ways: - If integers, the quantiles are determined using the normal distribution (agreement * σ), e.g., agreement = 6 covers ~99.75% of the data. - If floats, values must be between 0 and 1, interpreted as acceptable proportions for the quantiles, e.g., 0.9973 corresponds to ~6σ. - If empty tuple, the filled area is uniform without highlighting the quantiles.

Default is DEFAULT.AGREEMENTS = (2, 4, 6), corresponding to (±1σ, ±2σ, ±3σ).

TYPE: tuple[float, ...] or tuple[int, ...] DEFAULT: AGREEMENTS

strategy

Which strategy should be used to determine the quantiles used for highlighting, see SpreadOpacity. Default is 'data'.

TYPE: (eval, fit, norm, data) DEFAULT: 'eval'

possible_dists

Distributions to which the data may be subject, see SpreadOpacity. Default is DIST.COMMON.

TYPE: tuple of strings or rv_continous DEFAULT: COMMON

cumulative

If True, the cumulative distribution (CDF) is plotted instead of the density (PDF), 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

color

Color to be used to draw the artists. If None, the first color is taken from the color cycle, by default None.

TYPE: str | None DEFAULT: None

n_points

Number of points the density estimation and sequence should have, by default KD_SEQUENCE_LEN (defined in constants.py).

TYPE: int DEFAULT: KD_SEQUENCE_LEN

ax

The axes object for the plot. If None, the current axes is fetched using plt.gca(). If no axes are available, a new one is created. Defaults to None.

TYPE: Axes | None DEFAULT: None

visible_spines

Specifies which spines are visible, the others are hidden. If 'none', no spines are visible. If None, the spines are drawn according to the stylesheet. Defaults to None.

TYPE: Literal['target', 'feature', 'none'] | None DEFAULT: None

hide_axis

Specifies which axes should be hidden. If None, both axes are displayed. Defaults to None.

TYPE: Literal['target', 'feature', 'both'] | None DEFAULT: None

**kwds

Additional keyword arguments that have no effect and are only used to catch further arguments that have no use here (occurs when this class is used within chart objects).

DEFAULT: {}

cumulative = cumulative instance-attribute

Flag whether the cumulative distribution (CDF) is plotted instead of the density (PDF).

n_points = n_points instance-attribute

Number of points that have the density estimation and its sequence.

margin = margin instance-attribute

Margin for the sequence as factor of data range (max - min ). If margin is 0, The two ends of the estimated density curve then show the minimum and maximum value.

fill = fill instance-attribute

Flag whether to fill in the curves

kw_default property

Default keyword arguments for plotting (read-only)

height property

Height of the density curve at its maximum.

stretch property

Factor by which the curve was stretched in height

highlight_quantiles property

Flag indicating whether the quantiles should be highlighted. Always False for cumulative curves: the area under a CDF has no meaningful interpretation as probability mass (unlike a PDF), so quantile fill bands would shade a large area for a small probability range and be visually misleading.

estimate

Compute the sequence of target values and the corresponding density estimation for one feature group. Must be implemented by subclasses.

PARAMETER DESCRIPTION
feature_data

Base location (offset) of feature axis coming from feature_grouped generator.

TYPE: float | int

target_data

Feature grouped target data used for transformation, coming from feature_grouped generator.

TYPE: pandas Series

RETURNS DESCRIPTION
sequence

Data points at regular intervals used as target data.

TYPE: 1D array

estimation

Density estimation values used as feature data.

TYPE: 1D array

estimate_cumulative

Compute the sequence of target values and the corresponding cumulative distribution (CDF) for one feature group.

The default implementation numerically integrates :meth:estimate (trapezoidal rule) and rescales the result to span from feature_data to feature_data + stretch (or height). Subclasses may override this to compute the CDF directly, e.g. from a fitted distribution's analytic cdf.

PARAMETER DESCRIPTION
feature_data

Base location (offset) of feature axis coming from feature_grouped generator.

TYPE: float | int

target_data

Feature grouped target data used for transformation, coming from feature_grouped generator.

TYPE: pandas Series

RETURNS DESCRIPTION
sequence

Data points at regular intervals used as target data.

TYPE: 1D array

estimation

Cumulative distribution values used as feature data.

TYPE: 1D array

transform

Perform the transformation on the target data by estimating its density (or cumulative distribution, if cumulative is True). To obtain a uniform curve, a sequence is generated with a specific number of points in the same range (min to max) as the target data.

PARAMETER DESCRIPTION
feature_data

Base location (offset) of feature axis coming from feature_grouped generator.

TYPE: float | int

target_data

Feature grouped target data used for transformation, coming from feature_grouped generator.

TYPE: pandas Series

RETURNS DESCRIPTION
data

The transformed data source for the plot. Contains the generated sequence as target data and the estimation as feature data.

TYPE: pandas DataFrame