ChatStat

ChatStat is an R package to get data from online chat platforms, in tidy formats. It currently only supports Matrix, but more backends are planned.

Discussion

Come talk in #rmatrixstats:matrix.org to discuss ChatStat or get help using it!

If you’re new to R and are interested in learning more, you can join the R Matrix Space too!

Installation

You can install the development version of ChatStat from GitHub with:

# install.packages("remotes")
remotes::install_github("GregSutcliffe/ChatStat")

If you’re new to R, go with this approach:

# install R from your package manager
(dnf / apt / pacman / etc) r
# make a working dir
mkdir chatstats && cd chatstats
# start r
R

# virtual package environment
install.packages("renv")
renv::init()
# install ChatStat
install.packages("remotes")
remotes::install_github("GregSutcliffe/ChatStat")

Which will set up a new renv environment with ChatStat installed and ready to use.

Because the report generation depends on a lot of packages, you may find this takes a while!

Usage

Authentication

You will need your access_token and your homeserver URL, and optionally a port if your homeserver is non-standard:

# Authentication
Sys.setenv('token' = 'syt_foobarbaz',
            'host' = 'matrix.org')

Getting some room data

To retrieve room data initially, use get_rooms() like in the following example.

library(ChatStat)

room_ids <- c(
  "!layMvdZSboJeKiyTAL:matrix.org", # #rmeta:matrix.org
  "!FeFZUTDOtgIlOUoYhq:matrix.org", # #rstats:matrix.org
  "!zSgZAViSMVQLIqRgOv:matrix.org"  # #rmatrixstats:matrix.org
)

rooms <- get_rooms(room_ids, since = "2022-01-01")

This will store the result in rooms which we can take a look at:

> rooms
Matrix room state since 2022-01-01 

 Room ID                          Event count
 !layMvdZSboJeKiyTAL:matrix.org   39
 !FeFZUTDOtgIlOUoYhq:matrix.org   24
 !zSgZAViSMVQLIqRgOv:matrix.org   186

And if we dig into the rooms object, we can get a table of the event data:

> rooms$events
# A tibble: 249 × 8
   room         id    time                type  sender message_type body 
   <chr>        <chr> <dttm>              <chr> <chr>  <chr>        <chr>
 1 !FeFZUTDOtg… $164… 2022-01-04 09:12:19 m.ro… @chri… m.text       "If …
 2 !FeFZUTDOtg… $164… 2022-01-04 12:04:28 m.re… @gwmn… NA            NA  
 3 !FeFZUTDOtg… $164… 2022-01-04 18:38:00 m.re… @samf… NA            NA  
 4 !FeFZUTDOtg… $164… 2022-01-10 13:07:21 m.re… @fede… NA            NA  
...

Making a report

This is what you really came for! Once you have a rooms object, you can call:

> ChatStat::render_report(rooms)
Output created: chatstat_report.html

This will create an HTML report in the current directory (or you can specify a path), which will look something like:

Obviously you can also do whatever you like with the raw data, see the Wiki for an example of raw processing with ggplot2

Saving / Loading

The rooms object can saved via saveRDS(rooms,'./rooms.rds') and loaded later with rooms <- readRDS('./rooms.rds').

Updating

A rooms object that has been created using get_rooms() can be updated later using update_room() which will add events that happened in the mean time.

rooms_new <- update_rooms(rooms)

Contributing

Contributions welcome! Please report issues as you find them, send pull requests if you wish, or just come chat in the Matrix discussion room!