whatstk.graph

Plot tools using plotly.

Import plot (by plotly) to plot figures.

>>> from whatstk.graph import plot

whatstk.graph.base

Build plotly-compatible figures.

Classes:

FigureBuilder([df, chat])

Generate a variety of figures from your loaded chat.

class whatstk.graph.base.FigureBuilder(df: DataFrame | None = None, chat: BaseChat | None = None)

Bases: object

Generate a variety of figures from your loaded chat.

Integrates feature extraction and visualization logic to automate data plots.

Note: Either df or chat must be provided.

Parameters:

• df (pandas.DataFrame, optional) – Chat data. Atribute df of a chat loaded using Chat. If a value is given, chat is ignored.

• chat (Chat, optional) – Chat data. Object obtained when chat loaded using Chat. Required if df is None.

Attributes:

user_color_mapping	Get mapping between user and color.
usernames	Get list with users available in given chat.

Methods:

user_interventions_count_linechart([...])	Plot number of user interventions over time.
user_message_responses_flow([title])	Get the flow of message responses.
user_message_responses_heatmap([norm, title])	Get the response matrix heatmap.
user_msg_length_boxplot([title, xlabel])	Generate figure with boxplots of each user's message length.

property user_color_mapping: Dict[str, str]

Get mapping between user and color.

Each user is assigned a color automatically, so that this color is preserved for that user in all to-be-generated plots.

Returns:

dict – Mapping from username to color (rgb).

user_interventions_count_linechart(date_mode: str = 'date', msg_length: bool = False, cumulative: bool = False, all_users: bool = False, title: str = 'User interventions count', xlabel: str = 'Date/Time') → Figure

Plot number of user interventions over time.

Parameters:

• date_mode (str, optional) –

  Choose mode to group interventions by. Defaults to 'date'. Available modes are:

  • 'date': Grouped by particular date (year, month and day).

  • 'hour': Grouped by hours.

  • 'month': Grouped by months.

  • 'weekday': Grouped by weekday (i.e. monday, tuesday, …, sunday).

  • 'hourweekday': Grouped by weekday and hour.

• msg_length (bool, optional) – Set to True to count the number of characters instead of number of messages sent.

• cumulative (bool, optional) – Set to True to obtain commulative counts.

• all_users (bool, optional) – Obtain number of interventions of all users combined. Defaults to False.

• title (str, optional) – Title for plot. Defaults to “User interventions count”.

• xlabel (str, optional) – x-axis label title. Defaults to “Date/Time”.

Returns:

plotly.graph_objs.Figure – Plotly Figure.

See also

• get_interventions_count

• fig_scatter_time

Example

>>> from whatstk import WhatsAppChat
>>> from whatstk.graph import plot, FigureBuilder
>>> from whatstk.data import whatsapp_urls
>>> chat = WhatsAppChat.from_source(filepath=whatsapp_urls.LOREM)
>>> fig = FigureBuilder(chat=chat).user_interventions_count_linechart(cumulative=True)
>>> plot(fig)

user_message_responses_flow(title: str = 'Message flow') → Figure

Get the flow of message responses.

A response from user X to user Y happens if user X sends a message right after a message from user Y.

Uses a Sankey diagram.

Parameters:

title (str, optional) – Title for plot. Defaults to “Message flow”.

Returns:

plotly.graph_objs.Figure – Plotly Figure.

See also

• get_response_matrix

• fig_sankey

Example

>>> from whatstk import WhatsAppChat
>>> from whatstk.graph import plot, FigureBuilder
>>> from whatstk.data import whatsapp_urls
>>> chat = WhatsAppChat.from_source(filepath=whatsapp_urls.LOREM)
>>> fig = FigureBuilder(chat=chat).user_message_responses_flow()
>>> plot(fig)

user_message_responses_heatmap(norm: str = 'absolute', title: str = 'Response matrix') → Figure

Get the response matrix heatmap.

A response from user X to user Y happens if user X sends a message right after a message from user Y.

Parameters:

• norm (str, optional) –

  Specifies the type of normalization used for reponse count. Can be:

  • 'absolute': Absolute count of messages.

  • 'joint': Normalized by total number of messages sent by all users.

  • 'sender': Normalized per sender by total number of messages sent by user.

  • 'receiver': Normalized per receiver by total number of messages sent by user.

• title (str, optional) – Title for plot. Defaults to “Response matrix”.

Returns:

plotly.graph_objs.Figure – Plotly Figure.

See also

• get_response_matrix

• fig_heatmap

Example

>>> from whatstk import WhatsAppChat
>>> from whatstk.graph import plot, FigureBuilder
>>> from whatstk.data import whatsapp_urls
>>> chat = WhatsAppChat.from_source(filepath=whatsapp_urls.LOREM)
>>> fig = FigureBuilder(chat=chat).user_message_responses_heatmap()
>>> plot(fig)

user_msg_length_boxplot(title: str = 'User message length', xlabel: str = 'User') → Figure

Generate figure with boxplots of each user’s message length.

Parameters:

• title (str, optional) – Title for plot. Defaults to “User message length”.

• xlabel (str, optional) – x-axis label title. Defaults to “User”.

Returns:

dict – Dictionary with data and layout. Plotly compatible.

See also

• fig_boxplot_msglen

Example

>>> from whatstk import WhatsAppChat
>>> from whatstk.graph import plot, FigureBuilder
>>> from whatstk.data import whatsapp_urls
>>> chat = WhatsAppChat.from_source(filepath=whatsapp_urls.LOREM)
>>> fig = FigureBuilder(chat=chat).user_msg_length_boxplot()
>>> plot(fig)

property usernames: BaseChat

Get list with users available in given chat.

Returns:

list – List with usernames available in chat DataFrame.

whatstk.graph.figures

Build Plotly compatible Figures.

whatstk.graph.figures.boxplot

Boxplot figures.

Functions:

fig_boxplot_msglen(df[, username_to_color, ...])

Visualize boxplot.

whatstk.graph.figures.boxplot.fig_boxplot_msglen(df: DataFrame, username_to_color: Dict[str, str] | None = None, title: str = '', xlabel: str | None = None) → Figure

Visualize boxplot.

Parameters:

• df (pandas.DataFrame) – Chat data.

• username_to_color (dict, optional) –

• title (str, optional) – Title for plot. Defaults to “”.

• xlabel (str, optional) – x-axis label title. Defaults to None.

Returns:

plotly.graph_objs.Figure

whatstk.graph.figures.heatmap

Heatmap plot figures.

Functions:

fig_heatmap(df_matrix[, title])

Generate heatmap figure from NxN matrix.

whatstk.graph.figures.heatmap.fig_heatmap(df_matrix: DataFrame, title: str = '') → Figure

Generate heatmap figure from NxN matrix.

Parameters:

• df_matrix (pandas.DataFrame) – Matrix as DataFrame. Index values and column values must be equal.

• title (str) – Title of plot. Defaults to “”.

Returns:

plotly.graph_objs.Figure

whatstk.graph.figures.sankey

Sankey plot figures.

Functions:

fig_sankey(label, color, source, target, value)

Generate sankey image.

whatstk.graph.figures.sankey.fig_sankey(label: List[str], color: List[str], source: List[str], target: List[str], value: List[int], title: str = '') → Figure

Generate sankey image.

Parameters:

• label (list) – List with node labels.

• color (list) – List with node colors.

• source (list) – List with link source id.

• target (list) – List with linke target id.

• value (list) – List with link value.

• title (str, optional) – Title. Defaults to “”.

Returns:

plotly.graph_objs.Figure

whatstk.graph.figures.scatter

Scatter plot figures.

Functions:

fig_scatter_time(user_data[, ...])

Obtain Figure to plot using plotly.

whatstk.graph.figures.scatter.fig_scatter_time(user_data: DataFrame, username_to_color: Dict[str, str] | None = None, title: str = '', xlabel: str | None = None) → Figure

Obtain Figure to plot using plotly.

user_data must be a pandas.DataFrame with timestamps as index and a column for each user. You can easily generate suitable user_data using the function get_interventions_count (disclaimer: not compatible with date_mode='hourweekday').

Parameters:

• user_data (pandas.DataFrame) – Input data. Shape nrows x ncols, where nrows = number of timestaps and ncols = number of users.

• username_to_color (dict, optional) –

• title (str, optional) – Title of figure. Defaults to “”.

• xlabel (str, optional) – x-axis label title. Defaults to None.

Returns:

plotly.graph_objs.Figure

See also

• get_interventions_count

whatstk.graph.figures.utils

Utils for library plots.

Functions:

hex_color_palette(n_colors)

Get palette of n_colors color hexadecimal codes.

whatstk.graph.figures.utils.hex_color_palette(n_colors: int) → List[str]

Get palette of n_colors color hexadecimal codes.

Parameters:

n_colors (int) – Size of the color palette.