{"id":13585056,"url":"https://github.com/joweich/chat-miner","last_synced_at":"2025-05-14T19:09:48.140Z","repository":{"id":41291851,"uuid":"437398468","full_name":"joweich/chat-miner","owner":"joweich","description":"Parsers and visualizations for chats","archived":false,"fork":false,"pushed_at":"2025-04-05T20:19:21.000Z","size":3158,"stargazers_count":577,"open_issues_count":1,"forks_count":58,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-04-13T15:55:57.671Z","etag":null,"topics":["chat","facebook-messenger","messenger","parser","python","signal","telegram","whatsapp","whatsapp-statistics","wordcloud"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joweich.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-12-11T22:05:49.000Z","updated_at":"2025-04-01T14:56:38.000Z","dependencies_parsed_at":"2023-02-18T19:31:18.211Z","dependency_job_id":"ea60f2a9-b785-4be7-8b51-7c7145f53ecf","html_url":"https://github.com/joweich/chat-miner","commit_stats":{"total_commits":117,"total_committers":23,"mean_commits":5.086956521739131,"dds":0.4700854700854701,"last_synced_commit":"57c3818ccfb4374c49c804498a3bf9ba24531489"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joweich%2Fchat-miner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joweich%2Fchat-miner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joweich%2Fchat-miner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joweich%2Fchat-miner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joweich","download_url":"https://codeload.github.com/joweich/chat-miner/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254209859,"owners_count":22032897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chat","facebook-messenger","messenger","parser","python","signal","telegram","whatsapp","whatsapp-statistics","wordcloud"],"created_at":"2024-08-01T15:04:42.791Z","updated_at":"2025-05-14T19:09:47.256Z","avatar_url":"https://github.com/joweich.png","language":"Python","funding_links":[],"categories":["Python","python"],"sub_categories":[],"readme":"\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"doc/_static/logo-wide-dark.png\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"doc/_static/logo-wide-light.png\"\u003e\n  \u003cimg alt=\"chat-miner: turn your chats into artwork\" src=\"doc/_static/logo-wide-light.png\"\u003e\n\u003c/picture\u003e\n\n-----------------\n\n# chat-miner: turn your chats into artwork\n\n[![PyPI Version](https://img.shields.io/pypi/v/chat-miner.svg)](https://pypi.org/project/chat-miner/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Downloads](https://static.pepy.tech/badge/chat-miner/month)](https://pepy.tech/project/chat-miner)\n[![codecov](https://codecov.io/gh/joweich/chat-miner/branch/main/graph/badge.svg?token=6EQF0YNGLK)](https://codecov.io/gh/joweich/chat-miner)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\n-----------------\n\n**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.\n\n\n## 1. Installation\nLatest release including dependencies can be installed via PyPI:\n```sh\npip install chat-miner\n```\n\nIf you're interested in contributing, running the latest source code, or just like to build everything yourself:\n```sh\ngit clone https://github.com/joweich/chat-miner.git\ncd chat-miner\npip install .\n```\n\n## 2. Exporting chat logs\nHave a look at the official tutorials for [WhatsApp](https://faq.whatsapp.com/1180414079177245/), [Signal](https://github.com/carderne/signal-export), [Telegram](https://telegram.org/blog/export-and-more), [Facebook Messenger](https://www.facebook.com/help/messenger-app/713635396288741), or [Instagram Chats](https://help.instagram.com/181231772500920) to learn how to export chat logs for your platform.\n\n## 3. Parsing\nFollowing code showcases the ``WhatsAppParser`` module.\nThe usage of ``SignalParser``, ``TelegramJsonParser``, ``FacebookMessengerParser``, and ``InstagramJsonParser`` follows the same pattern.\n```python\nfrom chatminer.chatparsers import WhatsAppParser\n\nparser = WhatsAppParser(FILEPATH)\nparser.parse_file()\ndf = parser.parsed_messages.get_df(as_pandas=True) # as_pandas=False returns polars dataframe\n```\n**Note:**\nDepending on your source system, Python requires to convert the filepath to a raw string.\n```python\nimport os\nFILEPATH = r\"C:\\Users\\Username\\chat.txt\" # Windows\nFILEPATH = \"/home/username/chat.txt\" # Unix\nassert os.path.isfile(FILEPATH)\n\n```\n\n## 4. Visualizing\n```python\nimport chatminer.visualizations as vis\nimport matplotlib.pyplot as plt\n```\n### 4.1 Heatmap: Message count per day\n```python\nfig, ax = plt.subplots(2, 1, figsize=(9, 3))\nax[0] = vis.calendar_heatmap(df, year=2020, cmap='Oranges', ax=ax[0])\nax[1] = vis.calendar_heatmap(df, year=2021, linewidth=0, monthly_border=True, ax=ax[1])\n```\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"examples/heatmap.svg\"\u003e\n\u003c/p\u003e\n\n### 4.2 Sunburst: Message count per daytime\n```python\nfig, ax = plt.subplots(1, 2, figsize=(7, 3), subplot_kw={'projection': 'polar'})\nax[0] = vis.sunburst(df, highlight_max=True, isolines=[2500, 5000], isolines_relative=False, ax=ax[0])\nax[1] = vis.sunburst(df, highlight_max=False, isolines=[0.5, 1], color='C1', ax=ax[1])\n```\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"examples/sunburst.svg\"\u003e\n\u003c/p\u003e\n\n### 4.3 Wordcloud: Word frequencies\n```python\nfig, ax = plt.subplots(figsize=(8, 3))\nstopwords = ['these', 'are', 'stopwords']\nkwargs={\"background_color\": \"white\", \"width\": 800, \"height\": 300, \"max_words\": 500}\nax = vis.wordcloud(df, ax=ax, stopwords=stopwords, **kwargs)\n```\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"examples/wordcloud.svg\"\u003e\n\u003c/p\u003e\n\n### 4.4 Radarchart: Message count per weekday\n```python\nif not vis.is_radar_registered():\n\tvis.radar_factory(7, frame=\"polygon\")\nfig, ax = plt.subplots(1, 2, figsize=(7, 3), subplot_kw={'projection': 'radar'})\nax[0] = vis.radar(df, ax=ax[0])\nax[1] = vis.radar(df, ax=ax[1], color='C1', alpha=0)\n```\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"examples/radar.svg\"\u003e\n\u003c/p\u003e\n\n## 5. Command Line Interface\nThe CLI supports parsing chat logs into csv files.\nAs of now, you **can't** create visualizations from the CLI directly.\n\nExample usage:\n```bash\n$ chatminer -p whatsapp -i exportfile.txt -o output.csv\n```\n\nUsage guide:\n```\nusage: chatminer [-h] [-p {whatsapp,instagram,facebook,signal,telegram}] [-i INPUT] [-o OUTPUT]\n\noptions:\n  -h, --help \n                        Show this help message and exit\n  -p {whatsapp,instagram,facebook,signal,telegram}, --parser {whatsapp,instagram,facebook,signal,telegram}\n                        The platform from which the chats are imported\n  -i INPUT, --input INPUT\n                        Input file to be processed\n  -o OUTPUT, --output OUTPUT\n                        Output file for the results\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoweich%2Fchat-miner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoweich%2Fchat-miner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoweich%2Fchat-miner/lists"}