voyagerpy.plotting.scatter#

voyagerpy.plotting.scatter(x: str, y: str, color_by: str | None = None, ax: Axes | None = None, cmap: str | None = None, legend: bool = True, legend_kwargs: Dict[str, Any] | None = None, data: DataFrame | None = None, labels: Dict[str, Any] | None = None, rc_context: Dict[str, Any] | None = None, fitline_kwargs: Dict[str, Any] | None = None, contour_kwargs: Dict[str, Any] | None = None, figsize: Tuple[float, float] | None = None, is_categorical: bool | None = None, aspect: None | float | str = None, **scatter_kwargs) → Axes#

Create a scatter plot of x vs y.

This function wraps matplotlib.pyplot.scatter() and adds a few features. If fitline_kwargs is not None, a linear model is fit to the data and the fit line is plotted. If contour_kwargs is not None, a contour plot is added to the axes. If color_by is not None, the points are colored by the values in color_by. To pass keyword arguments to matplotlib scatter function, use scatter_kwargs.

If the dtype of the data in color_by is categorical, or if is_categorical is True, the data is interpreted as categorical, resulting in a legend being shown if legend is True. Otherwise, it is interpreted as continuous, resulting in a colorbar being shown if legend is True.

Parameters:

  • x (str) – The column name in data to use for the x-axis. Can also be array-like/

  • y (str) – The column name in data to use for the y-axis. Can also be array-like.

  • color_by (Optional[str], optional) – The column name in data to use for coloring the points, by default None. Can also be array-like.

  • ax (Optional[Axes], optional) – The axes to plot on, by default None

  • cmap (Optional[str], optional) – The colormap to use, by default None

  • legend (bool, optional) – Whether to show a legend or not, by default True. Depending on the data, either a legend or a colorbar is shown.

  • legend_kwargs (Optional[Dict[str, Any]], optional) – Additional keyword arguments for the creation of the legend/colorbar, by default None.

  • data (Optional[DataFrame], optional) – Mappable, with x, y, and color_by as keys if they are strings, by default None.

  • labels (Optional[Dict[str, Any]], optional) –

    The labels to use for the axis, by default None. The keys used are:

    • xlabel: The label for the x-axis.

    • ylabel: The label for the y-axis.

    • title: The title of the plot.

  • rc_context (Optional[Dict[str, Any]], optional) – Additional styling using matplotlib’s matplotlib.plt.rc_context(), by default None.

  • fitline_kwargs (Optional[Dict[str, Any]], optional) – Keyword arguments to pass to plot_fitline(), by default None. If not None, plot a fitted line through the data. An empty dict results in the default arguments being used.

  • contour_kwargs (Optional[Dict[str, Any]], optional) – Keyword arduments to pass to contour_plot(), by default None. If not None, plot a contour plot of the data. An empty dict results in the default arguments being used.

  • figsize (Optional[Tuple[float, float]], optional) – If ax is None, create a figure with figsize figsize, by default None

  • is_categorical (Optional[bool], optional) – Force the interpretation of the color data to be categorical, by default None

  • aspect (Union[None, float, str], optional) – Set the aspect of the axes, by default None

Returns:

The axes with the scatter plot added.

Return type:

Axes

Raises:

ValueError – data is None and any of x, y, or color_by is a string.