Run an Analysis¶
If you're ready to run an analysis, that's because you already installed mastoscore and set up your analysis with a mastoscore.ini file. There's an example.ini file that shows you what the options are. You can also go to the code repo and look at the ini/ directory to see some of the actual INI files I use at various times. Be warned that the features and syntax changed over time. I didn't go back to old INI files and update them to work with new syntax. So the monsterdon-20241124.ini file, for example, won't work with version 1.0.0 because features got implemented that make some of its options invalid.
For now, because it's finicky, I recommend running four steps one-by-one.
The command line takes a minimum of 2 arguments: the INI file and the action you want to do. It also takes an optional --debug parameter that will display some information. Without the --debug option, it's pretty quiety. With --debug=info you get informative progress messages. With --debug=debug you get a lot of noise.
1. Fetch¶
First, you go fetch all the toots related to your hashtag. This will take time. For #monsterdon, my laptop connects to around 113 different servers, fetching 40 toots at a time. Thanks to the way federation works, you end up fetching the same toots many times! On a Monsterdon Sunday, there are often around 2000 toots. But the fetch module will frequently fetch 80,000 or more. That's because when someone at mastodon.social toots something related to #monsterdon it is federated to a lot of servers. All 113 servers will send me a copy of that toot. There's a bunch of work in the fetch module to de-duplicate and handle all that. Fetching those 80,000 toots takes my laptop around 26 minutes. On the other hand, some less popular watch parties like #iliketowatch and #kungfusat will complete in a minute or less.
mastoscore --debug=info mastoscore.ini fetch
When this is done, you'll have a bunch of JSON files in your journaldir directory, organized in a hierarchical structure based on the event date (YYYY/MM/DD). For example, if your event is on April 9, 2025, the files will be stored in journaldir/2025/04/09/.
The file structure looks like:
journaldir/
├── YYYY/
│ ├── MM/
│ │ ├── DD/
│ │ │ ├── hashtag-YYYYMMDD-server1.json
│ │ │ ├── hashtag-YYYYMMDD-server2.json
│ │ │ └── ...
2. Analyse¶
Analyse is its own phase, but it's not useful to run by itself right now. It will load all the JSON files, de-duplicate them and do its analysis of top toots and such, and then just dump the results to stdout. Running post will run analyse and then post about it. So most of the time I don't run this by itself.
mastoscore mastoscore.ini analyse
3. Post¶
Do the analysis and then post about it. I recommend setting dry_run to True until you're confident in it. Note that I developed this on infosec.exchange, which allows 11,000 characters in a toot. It's likely that if you're on a server with the standard limit of 500 characters, this won't work. It would be useful to support that case.
mastoscore mastoscore.ini post
4. Graph¶
This will generate a graph file showing the timeline of toots over time. The graph will be saved in a dedicated graphs directory with the naming pattern graphs/hashtag-YYYYMMDD.png. For example, if you're analyzing the hashtag monsterdon for April 9, 2025, the graph will be saved as graphs/monsterdon-20250409.png.
mastoscore mastoscore.ini graph
5. Generate a Word Cloud¶
This will generate a word cloud based on the content of the toots. The word cloud will be saved in the graphs directory with the naming pattern graphs/wordcloud-hashtag-YYYYMMDD-hashtag_fix.png, where hashtag_fix is the method used to handle the hashtag in the word cloud (as-is, remove, or reduce).
mastoscore mastoscore.ini wordcloud
6. Post Graphs¶
This will post the generated graph and wordcloud images to Mastodon:
mastoscore mastoscore.ini postgraphs
The system includes fallback mechanisms if directories can't be created or files can't be written to the preferred locations. For example, if the graphs directory can't be created, files will be saved to the journal directory instead.
Running Tests¶
If you're developing or modifying Mastoscore, you can run the test suite to ensure everything is working correctly. See the Testing section for more details.
# Run all tests
python -m pytest
# Run with coverage reporting
python -m pytest --cov=mastoscore