FigureBuilder

whatstk provides this object to ease the generation of insightfull plots from your chat. FigureBuilder contains several methods to generate different plots. It assigns a unique color to each user, so that a user can be easily identified in all plots.

To insantiate it, you just need to provide the chat (as pandas.DataFrame or BaseChat-API-compliant object).

class whatstk.FigureBuilder(df=None, chat=None)[source]

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

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='date', msg_length=False, cumulative=False, all_users=False, title='User interventions count', xlabel='Date/Time', cummulative=None)[source]

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”.
  • cummulative (bool, optional) – Deprecated, use cumulative.
Returns:

plotly.graph_objs.Figure – Plotly Figure.

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='Message flow')[source]

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.

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='absolute', title='Response matrix')[source]

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.

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='User message length', xlabel='User')[source]

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.

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

Get list with users available in given chat.

Returns:list – List with usernames available in chat DataFrame.