API Reference

This section provides detailed documentation for all classes and functions in the Demoviz library.

Core Module

Core functionality for demoviz package.

demoviz.core.svg_to_colored_image(svg_path, color, size=(100, 100))

Convert SVG to a colored raster image.

Parameters:

• svg_path (str or Path) – Path to SVG file

• color (tuple) – RGBA color tuple (values 0-1)

• size (tuple, default (100, 100)) – Output image size (width, height)

Returns:

Colored image

Return type:

PIL.Image

Raises:

ImportError – If cairosvg is not installed

class demoviz.core.DemoScatter(icon_size=40, zoom=0.3, custom_icons=None)

Bases: object

Core class for creating demographic scatter plots with human icons.

Parameters:

• icon_size (int, default 40) – Size of icons in pixels

• zoom (float, default 0.3) – Zoom factor for displaying icons

• custom_icons (dict, optional) – Custom icon paths {‘male’: path, ‘female’: path}

ICON_ALIASES = {'M': 'male', 'F': 'female', 'male': 'male', 'female': 'female', 'man': 'male', 'woman': 'female', 1: 'male', 0: 'female', 'baby': 'baby', 'child': 'baby', 'infant': 'baby', 'B': 'baby', 'C': 'baby', 'I': 'baby'}

__init__(icon_size=40, zoom=0.3, custom_icons=None)

plot(ax, x, y, icon_type=None, colors=None, jitter=0, **kwargs)

Add human icons to matplotlib axis.

Parameters:

• ax (matplotlib.axes.Axes) – Target axis

• x (array-like) – Data coordinates

• y (array-like) – Data coordinates

• icon_type (str, array-like, or None) – Icon type for each point. If None, uses ‘person’

• colors (color or array-like) – Colors for each icon

• jitter (float, default 0) – Random jitter to add to positions

• **kwargs – Additional arguments (currently unused)

Returns:

The modified axis

Return type:

matplotlib.axes.Axes

clear_cache()

Clear the icon cache.

list_available_icons()

List available icon types.

DemoScatter Class

class demoviz.core.DemoScatter(icon_size=40, zoom=0.3, custom_icons=None)

Bases: object

Core class for creating demographic scatter plots with human icons.

Parameters:

• icon_size (int, default 40) – Size of icons in pixels

• zoom (float, default 0.3) – Zoom factor for displaying icons

• custom_icons (dict, optional) – Custom icon paths {‘male’: path, ‘female’: path}

ICON_ALIASES = {'M': 'male', 'F': 'female', 'male': 'male', 'female': 'female', 'man': 'male', 'woman': 'female', 1: 'male', 0: 'female', 'baby': 'baby', 'child': 'baby', 'infant': 'baby', 'B': 'baby', 'C': 'baby', 'I': 'baby'}

__init__(icon_size=40, zoom=0.3, custom_icons=None)

plot(ax, x, y, icon_type=None, colors=None, jitter=0, **kwargs)

Add human icons to matplotlib axis.

Parameters:

• ax (matplotlib.axes.Axes) – Target axis

• x (array-like) – Data coordinates

• y (array-like) – Data coordinates

• icon_type (str, array-like, or None) – Icon type for each point. If None, uses ‘person’

• colors (color or array-like) – Colors for each icon

• jitter (float, default 0) – Random jitter to add to positions

• **kwargs – Additional arguments (currently unused)

Returns:

The modified axis

Return type:

matplotlib.axes.Axes

clear_cache()

Clear the icon cache.

list_available_icons()

List available icon types.

Functions

demoviz.core.svg_to_colored_image(svg_path, color, size=(100, 100))

Convert SVG to a colored raster image.

Parameters:

• svg_path (str or Path) – Path to SVG file

• color (tuple) – RGBA color tuple (values 0-1)

• size (tuple, default (100, 100)) – Output image size (width, height)

Returns:

Colored image

Return type:

PIL.Image

Raises:

ImportError – If cairosvg is not installed

Matplotlib Integration

Matplotlib integration for demoviz.

demoviz.matplotlib_integration.scatter(x, y, sex=None, c=None, s=40, zoom=0.3, jitter=0, ax=None, figsize=None, custom_icons=None, **kwargs)

Create a scatter plot with human icons.

This is the main high-level function for creating demographic scatter plots.

Parameters:

• x (array-like) – Data coordinates

• y (array-like) – Data coordinates

• sex (array-like, optional) – Sex/gender for each point. Accepts ‘M’/’F’, ‘male’/’female’, 1/0, etc. If None, uses generic person icons.

• c (color or array-like, optional) – Colors for icons. Can be single color, array of colors, or values to map.

• s (float, default 40) – Icon size in pixels

• zoom (float, default 0.3) – Icon zoom factor (affects visual size)

• jitter (float, default 0) – Random position jitter to avoid overlapping

• ax (matplotlib.axes.Axes, optional) – Target axis. Creates new figure if None.

• figsize (tuple, optional) – Figure size (width, height) if creating new figure

• custom_icons (dict, optional) – Custom icon paths {‘male’: path, ‘female’: path}

• **kwargs – Additional keyword arguments passed to axis setup

Returns:

The plot axis

Return type:

matplotlib.axes.Axes

Examples

Basic usage: >>> import demoviz as dv >>> ages = [45, 67, 23, 89, 34] >>> scores = [2, 5, 1, 6, 3] >>> sexes = [‘M’, ‘F’, ‘M’, ‘F’, ‘M’] >>> ax = dv.scatter(ages, scores, sex=sexes)

With custom colors: >>> colors = [‘red’, ‘blue’, ‘green’, ‘purple’, ‘orange’] >>> ax = dv.scatter(ages, scores, sex=sexes, c=colors)

With continuous color mapping: >>> severity = [0.2, 0.8, 0.1, 0.9, 0.4] >>> ax = dv.scatter(ages, scores, sex=sexes, c=severity)

demoviz.matplotlib_integration.plot_demographics(data, x, y, sex=None, hue=None, size=None, figsize=(10, 6), title=None, **kwargs)

Create a demographic plot from a DataFrame.

Parameters:

• data (pandas.DataFrame) – Input data

• x (str) – Column names for x and y coordinates

• y (str) – Column names for x and y coordinates

• sex (str, optional) – Column name for sex/gender

• hue (str, optional) – Column name for color mapping

• size (str, optional) – Column name for size mapping (affects zoom)

• figsize (tuple, default (10, 6)) – Figure size

• title (str, optional) – Plot title

• **kwargs – Additional arguments passed to scatter()

Returns:

The plot axis

Return type:

matplotlib.axes.Axes

Examples

>>> import pandas as pd
>>> import demoviz as dv
>>> df = pd.DataFrame({
...     'age': [45, 67, 23, 89],
...     'score': [2, 5, 1, 6],
...     'sex': ['M', 'F', 'M', 'F'],
...     'severity': [0.2, 0.8, 0.1, 0.9]
... })
>>> ax = dv.plot_demographics(df, 'age', 'score', sex='sex', hue='severity')

Seaborn Integration

Seaborn-style integration for demoviz.

demoviz.seaborn_integration.scatterplot(data=None, x=None, y=None, sex=None, hue=None, size=None, style=None, palette=None, sizes=None, size_order=None, hue_order=None, legend='auto', ax=None, **kwargs)

Seaborn-style scatter plot with human icons.

This function mimics seaborn.scatterplot() but uses human icons instead of regular markers.

Parameters:

• data (pandas.DataFrame, optional) – Input data structure

• x (str or array-like) – Variables for x and y coordinates

• y (str or array-like) – Variables for x and y coordinates

• sex (str or array-like, optional) – Variable for icon type (male/female)

• hue (str or array-like, optional) – Variable for color mapping

• size (str or array-like, optional) – Variable for size mapping

• style (str or array-like, optional) – Variable for icon style (currently same as sex)

• palette (palette name, list, or dict, optional) – Colors to use for hue levels

• sizes (list, dict, or tuple, optional) – Sizes to use for size levels

• size_order (list, optional) – Order for size levels

• hue_order (list, optional) – Order for hue levels

• legend ("auto", "brief", "full", or False) – How to draw the legend

• ax (matplotlib.axes.Axes, optional) – Target axis

• **kwargs – Additional arguments passed to base scatter function

Returns:

The plot axis

Return type:

matplotlib.axes.Axes

demoviz.seaborn_integration.relplot(data=None, x=None, y=None, sex=None, hue=None, size=None, col=None, row=None, kind='scatter', **kwargs)

Figure-level interface for drawing relational plots with human icons.

This is a simplified version of seaborn.relplot() that supports human icons. Currently only supports kind=’scatter’.

demoviz.seaborn_integration.demographic_plot(*args, **kwargs)

Alias for scatterplot. Deprecated - use scatterplot instead.