Source code for vuecore.engines.plotly.scatter

import pandas as pd
import plotly.express as px
import plotly.graph_objects as go

from vuecore.schemas.basic.scatter import ScatterConfig
from vuecore.utils.statistics import get_density
from .theming import apply_scatter_theme
from .plot_builder import build_plot

# Define parameters handled by the theme script
THEMING_PARAMS = [
    "opacity",
    "log_x",
    "log_y",
    "range_x",
    "range_y",
    "title",
    "subtitle",
    "x_title",
    "y_title",
    "template",
    "width",
    "height",
    "marker_line_width",
    "marker_line_color",
    "color_by_density",
]


[docs] def scatter_preprocess(data, plot_args, config): """ Preprocess data and arguments for scatter plots with density coloring. This function handles special preprocessing for scatter plots, particularly for density-based coloring. Parameters ---------- data : pd.DataFrame The DataFrame containing the plot data. plot_args : dict Dictionary of arguments to be passed to the Plotly Express scatter function. config : ScatterConfig The validated Pydantic model with all scatter plot configurations. Returns ------- tuple A tuple containing: - data : pd.DataFrame The original DataFrame (unchanged). - plot_args : dict The modified plot arguments dictionary with color settings adjusted based on the configuration. Notes ----- When density coloring is enabled, this function calculates density values for the data points and uses them for color mapping, removing any discrete color mapping that might conflict with continuous coloring. """ # Handle density coloring if config.color_by_density: # Calculate density and pass it to the 'color' argument density_values = get_density(data[config.x].values, data[config.y].values) plot_args["color"] = density_values # Remove discrete color mapping for density plots if "color_discrete_map" in plot_args: del plot_args["color_discrete_map"] else: # Use standard group-based coloring plot_args["color"] = config.color return data, plot_args
[docs] def build(data: pd.DataFrame, config: ScatterConfig) -> go.Figure: """ Creates a Plotly scatter plot from a DataFrame and a Pydantic configuration. This function acts as a bridge between the abstract plot definition and the Plotly Express implementation. It translates the validated `ScattereConfig` into the arguments for `plotly.express.scatter` and also forwards any additional, unvalidated keyword arguments from plotly. The resulting figure is then customized with layout and theme settings using `plotly.graph_objects`. (https://plotly.com/python-api-reference/generated/plotly.express.scatter.html). Parameters ---------- data : pd.DataFrame The DataFrame containing the plot data. config : ScatterConfig The validated Pydantic model object with all plot configurations. Returns ------- go.Figure A `plotly.graph_objects.Figure` object representing the scatter plot. """ return build_plot( data=data, config=config, px_function=px.scatter, theming_function=apply_scatter_theme, theming_params=THEMING_PARAMS, preprocess=scatter_preprocess, )