Basic Charts

Bar

src.dx.plotting.dex.basic_charts.bar(df, x, y, y2=None, y2_style='bar', horizontal=False, bar_width=None, group_other=False, column_sort_order='asc', column_sort_type='string', pro_bar_mode='combined', combination_mode='avg', show_bar_labels=False, return_view=False, **kwargs)

Generates a DEX bar plot from the given DataFrame.

Parameters:

Name	Type	Description	Default
df		The DataFrame to plot.	required
x	str	The column to use for the x-axis.	required
y	str	The column(s) to use for the primary y-axis.	required
y2	Optional[str]	The column to use for the secondary y-axis.	None
y2_style	DEXSecondMetricstyle	The style to use for the secondary y-axis. ("bar" or "dot")	'bar'
horizontal	bool	Whether to plot the bars horizontally.	False
bar_width	Optional[str]	The column to use for the bar width.	None
group_other	bool	Whether to group the remaining columns into an "Other" category.	False
column_sort_order	DEXSortColumnsByOrder	The order to sort the columns by ("asc" or "desc")	'asc'
column_sort_type	DEXSortColumnsByType	The type of sorting to use. ("number", "string", or "date")	'string'
pro_bar_mode	DEXProBarModeType	The bar mode to use ("clustered", "combined", or "stacked").	'combined'
combination_mode	DEXCombinationMode	The combination mode to use ("avg", "sum", "min", "median", "max", or "count").	'avg'
show_bar_labels	bool	Whether to show the bar values as labels.	False
return_view	bool	Whether to return a DEXView object instead of render.	False
**kwargs		Additional keyword arguments to pass to the view metadata.	{}

Source code in src/dx/plotting/dex/basic_charts.py

def bar(
    df,
    x: str,
    y: str,
    y2: Optional[str] = None,
    y2_style: options.DEXSecondMetricstyle = "bar",
    horizontal: bool = False,
    bar_width: Optional[str] = None,
    group_other: bool = False,
    column_sort_order: options.DEXSortColumnsByOrder = "asc",
    column_sort_type: options.DEXSortColumnsByType = "string",
    pro_bar_mode: options.DEXProBarModeType = "combined",
    combination_mode: options.DEXCombinationMode = "avg",
    show_bar_labels: bool = False,
    return_view: bool = False,
    **kwargs,
) -> Optional[DEXBarChartView]:
    """
    Generates a DEX bar plot from the given DataFrame.

    Parameters
    ----------
    df: pd.DataFrame
        The DataFrame to plot.
    x: str
        The column to use for the x-axis.
    y: List[str]
        The column(s) to use for the primary y-axis.
    y2: Optional[str]
        The column to use for the secondary y-axis.
    y2_style: DEXSecondMetricstyle
        The style to use for the secondary y-axis. (`"bar"` or `"dot"`)
    horizontal: bool
        Whether to plot the bars horizontally.
    bar_width: Optional[str]
        The column to use for the bar width.
    group_other: bool
        Whether to group the remaining columns into an "Other" category.
    column_sort_order: DEXSortColumnsByOrder
        The order to sort the columns by (`"asc"` or `"desc"`)
    column_sort_type: DEXSortColumnsByType
        The type of sorting to use. (`"number"`, `"string"`, or `"date"`)
    pro_bar_mode: DEXProBarModeType
        The bar mode to use (`"clustered"`, `"combined"`, or `"stacked"`).
    combination_mode: DEXCombinationMode
        The combination mode to use (`"avg"`, `"sum"`, `"min"`, `"median"`, `"max"`, or `"count"`).
    show_bar_labels: bool
        Whether to show the bar values as labels.
    return_view: bool
        Whether to return a `DEXView` object instead of render.
    **kwargs
        Additional keyword arguments to pass to the view metadata.
    """
    raise_for_missing_columns(x, df.columns)

    if not isinstance(y, list):
        y = [y]
    raise_for_missing_columns(y, df.columns)
    y1 = y[0]

    chart_settings = {
        "dim1": x,
        "metric1": y1,
        "bar_projection": "horizontal" if horizontal else "vertical",
        "sort_columns_by": f"{column_sort_order}-col-{column_sort_type}",
        "group_other": group_other,
        "combination_mode": combination_mode,
        "bar_label": "show" if show_bar_labels else "none",
        "selected_bar_metrics": y,
    }
    if bar_width is not None:
        chart_settings["metric3"] = bar_width
    if y2 is not None:
        chart_settings["second_bar_metric"] = y2
        chart_settings["pro_bar_mode"] = pro_bar_mode
        chart_settings["second_metric_style"] = y2_style

    return handle_view(
        df,
        chart_mode="bar",
        chart=chart_settings,
        return_view=return_view,
        **kwargs,
    )

Line

src.dx.plotting.dex.basic_charts.line(df, x, y, line_type='line', split_by=None, multi_axis=False, smoothing=None, use_count=False, bounding_type='absolute', zero_baseline=False, combination_mode='avg', return_view=False, **kwargs)

Generates a DEX line plot from the given DataFrame.

Parameters:

Name	Type	Description	Default
df		The DataFrame to plot.	required
x	str	The column to use for the x-axis.	required
y	Union[List[str], str]	The column(s) to use for the y-axis.	required
line_type	DEXLineType	The line type to use: - "bumparea" - "cumulative" - "line" (default) - "linepercent" - "stackedarea" - "stackedpercent"	'line'
split_by	Optional[str]	The column to use for splitting the lines.	None
multi_axis	bool	Whether to use multiple y-axes.	False
smoothing	Optional[DEXLineSmoothing]	The line smoothing to use: - None (default) - "hourly" - "daily" - "weekly" - "seven_day_moving_average" - "monthly"	None
use_count	bool	Whether to use the DEX_COUNT column for the y-axis.	False
bounding_type	DEXBoundingType	The bounding type to use: - "absolute" (default) - "relative"	'absolute'
zero_baseline	bool	Whether to use a zero base line.	False
combination_mode	DEXCombinationMode	The combination mode to use ("avg", "sum", "min", "median", "max", or "count").	'avg'
return_view	bool	Whether to return a DEXView object instead of render.	False
**kwargs		Additional keyword arguments to pass to the view metadata.	{}

Source code in src/dx/plotting/dex/basic_charts.py

def line(
    df,
    x: str,
    y: Union[List[str], str],
    line_type: options.DEXLineType = "line",
    split_by: Optional[str] = None,
    multi_axis: bool = False,
    smoothing: Optional[options.DEXLineSmoothing] = None,
    use_count: bool = False,
    bounding_type: options.DEXBoundingType = "absolute",
    zero_baseline: bool = False,
    combination_mode: options.DEXCombinationMode = "avg",
    return_view: bool = False,
    **kwargs,
) -> Optional[DEXLineChartView]:
    """
    Generates a DEX line plot from the given DataFrame.

    Parameters
    ----------
    df: pd.DataFrame
        The DataFrame to plot.
    x: str
        The column to use for the x-axis.
    y: Union[List[str], str]
        The column(s) to use for the y-axis.
    line_type: DEXLineType
        The line type to use:
            - `"bumparea"`
            - `"cumulative"`
            - `"line"` (default)
            - `"linepercent"`
            - `"stackedarea"`
            - `"stackedpercent"`
    split_by: Optional[str]
        The column to use for splitting the lines.
    multi_axis: bool
        Whether to use multiple y-axes.
    smoothing: Optional[DEXLineSmoothing]
        The line smoothing to use:
            - `None` (default)
            - `"hourly"`
            - `"daily"`
            - `"weekly"`
            - `"seven_day_moving_average"`
            - `"monthly"`
    use_count: bool
        Whether to use the DEX_COUNT column for the y-axis.
    bounding_type: DEXBoundingType
        The bounding type to use:
            - `"absolute"` (default)
            - `"relative"`
    zero_baseline: bool
        Whether to use a zero base line.
    combination_mode: DEXCombinationMode
        The combination mode to use (`"avg"`, `"sum"`, `"min"`, `"median"`, `"max"`, or `"count"`).
    return_view: bool
        Whether to return a `DEXView` object instead of render.
    **kwargs
        Additional keyword arguments to pass to the view metadata.
    """
    raise_for_missing_columns(x, df.columns)

    if isinstance(y, str):
        y = [y]
    raise_for_missing_columns(y, df.columns)
    if use_count:
        y.append("DEX_COUNT")

    if split_by is not None:
        if str(split_by) not in df.columns:
            raise ValueError(f"Column '{split_by}' not found in DataFrame.")

    chart_settings = {
        "bounding_type": bounding_type,
        "combination_mode": combination_mode,
        "line_smoothing": smoothing or "none",
        "line_type": line_type,
        "multi_axis_line": multi_axis,
        "selected_metrics": y,
        "split_lines_by": split_by,
        "timeseries_sort": x,
        "zero_baseline": zero_baseline,
    }
    logger.debug(f"{chart_settings=}")
    return handle_view(
        df,
        chart_mode="line",
        chart=chart_settings,
        return_view=return_view,
        **kwargs,
    )

Pie

src.dx.plotting.dex.basic_charts.pie(df, y, split_slices_by=None, show_total=True, pie_label_type='rim', pie_label_contents='name', return_view=False, **kwargs)

Generates a DEX pie plot from the given DataFrame.

Parameters:

Name	Type	Description	Default
df		The DataFrame to plot.	required
y	str	The column to use for the slice size.	required
split_slices_by	Optional[str]	The column to use for splitting the slices. If not provided, slices will be split and sized by y.	None
show_total	bool	Whether to show the total.	True
pie_label_type	DEXPieLabelType	The pie label type to use: - "rim" (default) - "annotation" - "center" - "stem" - "none"	'rim'
pie_label_contents	DEXPieLabelContents	The pie label contents to use: - "name" (default) - "value" - "percent" - "name_value" - "name_percent" - "value_percent"	'name'
return_view	bool	Whether to return a DEXView object instead of render.	False
**kwargs		Additional keyword arguments to pass to the view metadata.	{}

Source code in src/dx/plotting/dex/basic_charts.py

def pie(
    df,
    y: str,
    split_slices_by: Optional[str] = None,
    show_total: bool = True,
    pie_label_type: options.DEXPieLabelType = "rim",
    pie_label_contents: options.DEXPieLabelContents = "name",
    return_view: bool = False,
    **kwargs,
) -> Optional[DEXPieChartView]:
    """
    Generates a DEX pie plot from the given DataFrame.

    Parameters
    ----------
    df: pd.DataFrame
        The DataFrame to plot.
    y: str
        The column to use for the slice size.
    split_slices_by: Optional[str]
        The column to use for splitting the slices. If not provided, slices will be split and sized by `y`.
    show_total: bool
        Whether to show the total.
    pie_label_type: DEXPieLabelType
        The pie label type to use:
            - `"rim"` (default)
            - `"annotation"`
            - `"center"`
            - `"stem"`
            - `"none"`
    pie_label_contents: DEXPieLabelContents
        The pie label contents to use:
            - `"name"` (default)
            - `"value"`
            - `"percent"`
            - `"name_value"`
            - `"name_percent"`
            - `"value_percent"`
    return_view: bool
        Whether to return a `DEXView` object instead of render.
    **kwargs
        Additional keyword arguments to pass to the view metadata.
    """
    if split_slices_by is None:
        split_slices_by = y
    raise_for_missing_columns([y, split_slices_by], df.columns)

    chart_settings = {
        "dim1": split_slices_by,
        "metric1": y,
        "show_total": show_total,
        "pie_label_type": pie_label_type,
        "pie_label_contents": pie_label_contents,
    }
    return handle_view(
        df,
        chart_mode="pie",
        chart=chart_settings,
        return_view=return_view,
        **kwargs,
    )

Scatter

src.dx.plotting.dex.basic_charts.scatter(df, x, y, size=None, trend_line=None, marginal_graphics=None, formula_display=None, return_view=False, **kwargs)

Generates a DEX scatterplot from the given DataFrame.

Parameters:

Name	Type	Description	Default
df	DataFrame	The DataFrame to plot.	required
x	str	The column to use for the x-axis.	required
y	str	The column to use for the y-axis.	required
size	Optional[str]	The column to use for sizing scatterplot points.	None
trend_line	Optional[DEXTrendlineType]	The type of trendline to use. One of "linear", "exponential", "polynomial", "power", or "logarithmic".	None
marginal_graphics	Optional[DEXSummaryType]	The marginal graphics to use: - boxplot - heatmap - histogram - horizon - joy - ridgeline - violin	None
formula_display	Optional[DEXFormulaDisplay]	The formula display to use: - r2 - formula	None
return_view	bool	Whether to return a DEXView object instead of render.	False
**kwargs		Additional keyword arguments to pass to the view metadata.	{}

Source code in src/dx/plotting/dex/basic_charts.py

def scatter(
    df: pd.DataFrame,
    x: str,
    y: str,
    size: Optional[str] = None,
    trend_line: Optional[options.DEXTrendlineType] = None,
    marginal_graphics: Optional[options.DEXSummaryType] = None,
    formula_display: Optional[options.DEXFormulaDisplay] = None,
    return_view: bool = False,
    **kwargs,
) -> Optional[DEXScatterChartView]:
    """
    Generates a DEX scatterplot from the given DataFrame.

    Parameters
    ----------
    df: pd.DataFrame
        The DataFrame to plot.
    x: str
        The column to use for the x-axis.
    y: str
        The column to use for the y-axis.
    size: Optional[str]
        The column to use for sizing scatterplot points.
    trend_line: Optional[DEXTrendlineType]
        The type of trendline to use. One of `"linear"`, `"exponential"`, `"polynomial"`, `"power"`, or `"logarithmic"`.
    marginal_graphics: Optional[DEXSummaryType]
        The marginal graphics to use:
            - `boxplot`
            - `heatmap`
            - `histogram`
            - `horizon`
            - `joy`
            - `ridgeline`
            - `violin`
    formula_display: Optional[DEXFormulaDisplay]
        The formula display to use:
            - `r2`
            - `formula`
    return_view: bool
        Whether to return a `DEXView` object instead of render.
    **kwargs
        Additional keyword arguments to pass to the view metadata.
    """
    raise_for_missing_columns([x, y], df.columns)

    chart_settings = {
        "metric1": x,
        "metric2": y,
    }
    # if these are present but set to `None`, DEX gets angry
    if trend_line is not None:
        chart_settings["trendLine"] = trend_line
    if size is not None:
        chart_settings["scatterplotSize"] = size
    if marginal_graphics is not None:
        chart_settings["marginalGraphics"] = marginal_graphics
    if formula_display is not None:
        chart_settings["formulaDisplay"] = formula_display

    return handle_view(
        df,
        chart_mode="scatter",
        chart=chart_settings,
        return_view=return_view,
        **kwargs,
    )

Tilemap

src.dx.plotting.dex.map_charts.tilemap(df, lat, lon, icon_opacity=1.0, icon_size=2, icon_size_scale='linear', stroke_color='#000000', stroke_width=2, label_column=None, tile_layer='streets', hover_cols=None, return_view=False, **kwargs)

Generates a DEX tilemap from the given DataFrame.

Parameters:

Name	Type	Description	Default
df		The DataFrame to plot.	required
lat	str	The column to use for the latitude values.	required
lon	str	The column to use for the longitude values.	required
icon_opacity	float	The opacity to use for the icon (0.0 to 1.0)	1.0
icon_size	int	Either: - int: a fixed size to use for the icon (0 to 10) - str: a column name to use for functional sizing	2
icon_size_scale	DEXScale	The scale to use for functional sizing ("linear" or "log")	'linear'
stroke_color	Color	The color to use for the icon stroke.	'#000000'
stroke_width	int	The width to use for the icon stroke.	2
tile_layer	str	The type of tile layer to use. One of "streets", "outdoors", "light", "dark", or "satellite"	'streets'
return_view	bool	Whether to return a DEXView object instead of render.	False
**kwargs		Additional keyword arguments to pass to the view metadata.	{}

Source code in src/dx/plotting/dex/map_charts.py

def tilemap(
    df,
    lat: str,
    lon: str,
    icon_opacity: float = 1.0,
    icon_size: int = 2,
    icon_size_scale: options.DEXScale = "linear",
    stroke_color: Color = "#000000",
    stroke_width: int = 2,
    label_column: Optional[str] = None,
    tile_layer: str = "streets",
    hover_cols: Optional[List[str]] = None,
    return_view: bool = False,
    **kwargs,
) -> Optional[DEXTilemapChartView]:
    """
    Generates a DEX tilemap from the given DataFrame.

    Parameters
    ----------
    df: pd.DataFrame
        The DataFrame to plot.
    lat: str
        The column to use for the latitude values.
    lon: str
        The column to use for the longitude values.
    icon_opacity: float
        The opacity to use for the icon (`0.0` to `1.0`)
    icon_size: Union[int, str]
        Either:
        - int: a fixed size to use for the icon (`0` to `10`)
        - str: a column name to use for functional sizing
    icon_size_scale: DEXScale
        The scale to use for functional sizing (`"linear"` or `"log"`)
    stroke_color: Color
        The color to use for the icon stroke.
    stroke_width: int
        The width to use for the icon stroke.
    tile_layer: str
        The type of tile layer to use. One of `"streets"`, `"outdoors"`, `"light"`, `"dark"`, or `"satellite"`
    return_view: bool
        Whether to return a `DEXView` object instead of render.
    **kwargs
        Additional keyword arguments to pass to the view metadata.
    """
    raise_for_missing_columns([lat, lon], df.columns)

    if isinstance(hover_cols, str):
        hover_cols = [hover_cols]
    if hover_cols is None:
        hover_cols = df.columns
    else:
        raise_for_missing_columns(hover_cols, df.columns)

    if label_column is not None:
        raise_for_missing_columns(label_column, df.columns)

    if isinstance(icon_size, str):
        # referencing a column, treat as functional sizing

        if icon_size not in df.columns:
            # "index" was chosen but isn't in columns, which passes raise_for_missing_columns()
            series = df.index
        else:
            series = df[icon_size]

        series_min = series.min()
        if str(icon_size_scale).lower() == "log":
            series_min = 1

        point_size_opts = {
            "mode": "functional",
            "size": 2,
            "met": icon_size,
            "scale": icon_size_scale,
            "min": series_min,
            "max": series.max(),
            "sizeMin": 1,
            "sizeMax": 10,
        }
    elif isinstance(icon_size, int):
        # fixed sizing, shouldn't matter what we put in here
        point_size_opts = {
            "mode": "fixed",
            "size": icon_size,
            "met": str(lon),
            "scale": icon_size_scale,
            "min": df[str(lon)].min(),
            "max": df[str(lon)].max(),
            "sizeMin": 1,
            "sizeMax": 10,
        }
    else:
        raise ValueError(f"`{type(icon_size)}` is not a valid type for `icon_size`.")

    # determine which columns are numeric and which ones are strings/mixed/etc
    dimension_cols = [col for col in hover_cols if df[col].dtype == "object"]
    metric_cols = [col for col in hover_cols if col not in dimension_cols]

    layer_settings = {
        "lat_dim": lat,
        "long_dim": lon,
        "transparency": icon_opacity,
        "size": icon_size,
        "type": "point",
        "stroke": stroke_color,
        "stroke_width": stroke_width,
        "point_size_opts": point_size_opts,
        "hover_opts": {
            "dims": dimension_cols,
            "mets": metric_cols,
        },
        "tile_layer": tile_layer,
    }
    if label_column is not None:
        layer_settings["show_labels"] = label_column

    chart_settings = {
        "map_mode": "tile",
        "layer_settings": [layer_settings],
    }
    return handle_view(
        df,
        chart_mode="tilemap",
        chart=chart_settings,
        return_view=return_view,
        **kwargs,
    )

Violin

src.dx.plotting.dex.summary_charts.violin(df, split_by, metric, bins=30, show_interquartile_range=False, column_sort_order='asc', column_sort_type='string', return_view=False, **kwargs)

Generates a DEX violin plot from the given DataFrame.

Parameters:

Name	Type	Description	Default
df	DataFrame	The DataFrame to plot.	required
split_by	str	The column to use for splitting the data.	required
metric	str	The column to use to show distribution and density.	required
bins	int	The number of bins to use for the violin plot.	30
show_interquartile_range	bool	Whether to show the interquartile range.	False
column_sort_order	DEXSortColumnsByOrder	The order to sort the columns by. ("asc" or "desc")	'asc'
column_sort_type	DEXSortColumnsByType	The type of sorting to use. ("number", "string", or "date")	'string'
return_view	bool	Whether to return a DEXView object instead of render.	False
**kwargs		Additional keyword arguments to pass to the view metadata.	{}

Source code in src/dx/plotting/dex/summary_charts.py

def violin(
    df: pd.DataFrame,
    split_by: str,
    metric: str,
    bins: int = 30,
    show_interquartile_range: bool = False,
    column_sort_order: options.DEXSortColumnsByOrder = "asc",
    column_sort_type: options.DEXSortColumnsByType = "string",
    return_view: bool = False,
    **kwargs,
) -> Optional[DEXViolinChartView]:
    """
    Generates a DEX violin plot from the given DataFrame.

    Parameters
    ----------
    df: pd.DataFrame
        The DataFrame to plot.
    split_by: str
        The column to use for splitting the data.
    metric: str
        The column to use to show distribution and density.
    bins: int
        The number of bins to use for the violin plot.
    show_interquartile_range: bool
        Whether to show the interquartile range.
    column_sort_order: DEXSortColumnsByOrder
        The order to sort the columns by. (`"asc"` or `"desc"`)
    column_sort_type: DEXSortColumnsByType
        The type of sorting to use. (`"number"`, `"string"`, or `"date"`)
    return_view: bool
        Whether to return a `DEXView` object instead of render.
    **kwargs
        Additional keyword arguments to pass to the view metadata.
    """
    if str(column_sort_order).lower() == "asc":
        sort_order = "desc"
    elif str(column_sort_order).lower() == "desc":
        sort_order = "asc"
    chart_params = dict(
        summary_bins=bins,
        sort_columns_by=f"{sort_order}-col-{column_sort_type}",
        violin_iqr=show_interquartile_range,
    )
    return summary(
        df,
        split_by=split_by,
        metric=metric,
        summary_type="violin",
        chart_params=chart_params,
        return_view=return_view,
        **kwargs,
    )

Wordcloud

src.dx.plotting.dex.basic_charts.wordcloud(df, word_column, size, text_format='sentence', word_rotation=None, random_coloring=False, return_view=False, **kwargs)

Generates a DEX wordcloud from the given DataFrame.

Parameters:

Name	Type	Description	Default
df	DataFrame	The DataFrame to plot.	required
word_column	str	The column to use for the words in the cloud.	required
size	str	The column to use for the size of the words in the cloud.	required
text_format	DEXTextDataFormat	The format of the text data. Either "sentence" or "token".	'sentence'
word_rotation	Optional[DEXWordRotate]	The rotation to use for the words in the cloud (45, 90, "jitter", or None).	None
random_coloring	bool	Whether to use random coloring for the words in the cloud.	False
return_view	bool	Whether to return a DEXView object instead of render.	False
**kwargs		Additional keyword arguments to pass to the view metadata.	{}

Source code in src/dx/plotting/dex/basic_charts.py

def wordcloud(
    df: pd.DataFrame,
    word_column: str,
    size: str,
    text_format: options.DEXTextDataFormat = "sentence",
    word_rotation: Optional[options.DEXWordRotate] = None,
    random_coloring: bool = False,
    return_view: bool = False,
    **kwargs,
) -> Optional[DEXWordcloudChartView]:
    """
    Generates a DEX wordcloud from the given DataFrame.

    Parameters
    ----------
    df: pd.DataFrame
        The DataFrame to plot.
    word_column: str
        The column to use for the words in the cloud.
    size: str
        The column to use for the size of the words in the cloud.
    text_format: DEXTextDataFormat
        The format of the text data. Either `"sentence"` or `"token"`.
    word_rotation: Optional[DEXWordRotate]
        The rotation to use for the words in the cloud (`45`, `90`, `"jitter"`, or `None`).
    random_coloring: bool
        Whether to use random coloring for the words in the cloud.
    return_view: bool
        Whether to return a `DEXView` object instead of render.
    **kwargs
        Additional keyword arguments to pass to the view metadata.
    """
    raise_for_missing_columns([word_column, size], df.columns)

    chart_settings = {
        "text_data_format": text_format,
        "token_metric": size,
        "word_data": word_column,
        "word_color": "random" if random_coloring else "none",
        "word_rotate": word_rotation if word_rotation else "none",
    }
    return handle_view(
        df,
        chart_mode="wordcloud",
        chart=chart_settings,
        return_view=return_view,
        **kwargs,
    )

Chart Name

Coming soon!