Skip to main content

Lean parsers and visualizations for chat data.

Project description

chat-miner: turn your chats into artwork

chat-miner: turn your chats into artwork

PyPI Version License: MIT Downloads codecov Code style: black


chat-miner provides lean parsers for every major platform transforming chats into dataframes. Artistic visualizations allow you to explore your data and create artwork from your chats.

1. Installation

Latest release including dependencies can be installed via PyPI:

pip install chat-miner

If you're interested in contributing, running the latest source code, or just like to build everything yourself:

git clone https://github.com/joweich/chat-miner.git
cd chat-miner
pip install .

2. Exporting chat logs

Have a look at the official tutorials for WhatsApp, Signal, Telegram, Facebook Messenger, or Instagram Chats to learn how to export chat logs for your platform.

3. Parsing

Following code showcases the WhatsAppParser module. The usage of SignalParser, TelegramJsonParser, FacebookMessengerParser, and InstagramJsonParser follows the same pattern.

from chatminer.chatparsers import WhatsAppParser

parser = WhatsAppParser(FILEPATH)
parser.parse_file()
df = parser.parsed_messages.get_df(as_pandas=True) # as_pandas=False returns polars dataframe

Note: Depending on your source system, Python requires to convert the filepath to a raw string.

import os
FILEPATH = r"C:\Users\Username\chat.txt" # Windows
FILEPATH = "/home/username/chat.txt" # Unix
assert os.path.isfile(FILEPATH)

4. Visualizing

import chatminer.visualizations as vis
import matplotlib.pyplot as plt

4.1 Heatmap: Message count per day

fig, ax = plt.subplots(2, 1, figsize=(9, 3))
ax[0] = vis.calendar_heatmap(df, year=2020, cmap='Oranges', ax=ax[0])
ax[1] = vis.calendar_heatmap(df, year=2021, linewidth=0, monthly_border=True, ax=ax[1])

4.2 Sunburst: Message count per daytime

fig, ax = plt.subplots(1, 2, figsize=(7, 3), subplot_kw={'projection': 'polar'})
ax[0] = vis.sunburst(df, highlight_max=True, isolines=[2500, 5000], isolines_relative=False, ax=ax[0])
ax[1] = vis.sunburst(df, highlight_max=False, isolines=[0.5, 1], color='C1', ax=ax[1])

4.3 Wordcloud: Word frequencies

fig, ax = plt.subplots(figsize=(8, 3))
stopwords = ['these', 'are', 'stopwords']
kwargs={"background_color": "white", "width": 800, "height": 300, "max_words": 500}
ax = vis.wordcloud(df, ax=ax, stopwords=stopwords, **kwargs)

4.4 Radarchart: Message count per weekday

if not vis.is_radar_registered():
	vis.radar_factory(7, frame="polygon")
fig, ax = plt.subplots(1, 2, figsize=(7, 3), subplot_kw={'projection': 'radar'})
ax[0] = vis.radar(df, ax=ax[0])
ax[1] = vis.radar(df, ax=ax[1], color='C1', alpha=0)

5. Natural Language Processing

5.1 Add Sentiment

from chatminer.nlp import add_sentiment

df_sentiment = add_sentiment(df)

5.2 Example Plot: Sentiment per Author in Groupchat

df_grouped = df_sentiment.groupby(['author', 'sentiment']).size().unstack(fill_value=0)
ax = df_grouped.plot(kind='bar', stacked=True, figsize=(8, 3))

6. Command Line Interface

The CLI supports parsing chat logs into csv files. As of now, you can't create visualizations from the CLI directly.

Example usage:

$ chatminer -p whatsapp -i exportfile.txt -o output.csv

Usage guide:

usage: chatminer [-h] [-p {whatsapp,instagram,facebook,signal,telegram}] [-i INPUT] [-o OUTPUT]

options:
  -h, --help 
                        Show this help message and exit
  -p {whatsapp,instagram,facebook,signal,telegram}, --parser {whatsapp,instagram,facebook,signal,telegram}
                        The platform from which the chats are imported
  -i INPUT, --input INPUT
                        Input file to be processed
  -o OUTPUT, --output OUTPUT
                        Output file for the results

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

chat_miner-0.5.4.tar.gz (13.0 kB view details)

Uploaded Source

Built Distribution

chat_miner-0.5.4-py3-none-any.whl (13.6 kB view details)

Uploaded Python 3

File details

Details for the file chat_miner-0.5.4.tar.gz.

File metadata

  • Download URL: chat_miner-0.5.4.tar.gz
  • Upload date:
  • Size: 13.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for chat_miner-0.5.4.tar.gz
Algorithm Hash digest
SHA256 116510ce7f1166fba78698f637d69a305b87dbf0e687a05b58dffb83396341ca
MD5 3f948d1cf6ff3336d3a075318d9b82e9
BLAKE2b-256 47ff5ce0117919d65b03dd7879db7819eebd05a45f88e134d40637445ea05b8b

See more details on using hashes here.

File details

Details for the file chat_miner-0.5.4-py3-none-any.whl.

File metadata

  • Download URL: chat_miner-0.5.4-py3-none-any.whl
  • Upload date:
  • Size: 13.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for chat_miner-0.5.4-py3-none-any.whl
Algorithm Hash digest
SHA256 8899fff7a8059ad3d5dd8841bd812ae4f056488c3168556d5a6d986cdb3e8a05
MD5 4b64fef7f43333e24a7bd6b76201be56
BLAKE2b-256 1e276b366d660fd905642c3c7412ade4aa2eb20ca0c9d5826acf49ca9ab9e321

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page