rtoot

:mammoth: R package to interact with the mastodon API

https://github.com/gesistsa/rtoot

Science Score: 57.0%

This score indicates how likely this project is to be science-related based on various indicators:

✓
CITATION.cff file
Found CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
✓
DOI references
Found 4 DOI reference(s) in README
○
Academic publication links
○
Committers with academic emails
○
Institutional organization owner
○
JOSS paper metadata
○
Scientific vocabulary similarity
Low similarity (17.7%) to scientific vocabulary

Keywords

mastodon mastodon-api rstats rstats-package

Keywords from Contributors

reproducibility

Last synced: 6 months ago · JSON representation ·

Repository

:mammoth: R package to interact with the mastodon API

Basic Info

Host: GitHub
Owner: gesistsa
License: other
Language: R
Default Branch: main
Homepage: https://gesistsa.github.io/rtoot/
Size: 8.44 MB

Statistics

Stars: 106
Watchers: 5
Forks: 19
Open Issues: 9
Releases: 7

Topics

mastodon mastodon-api rstats rstats-package

Created over 3 years ago · Last pushed 6 months ago

Metadata Files

Readme Changelog License Code of conduct Citation

README.Rmd

---
output: github_document
---



```{r, include = FALSE}
knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>",
    fig.path = "man/figures/README-",
    out.width = "100%"
)
```

# rtoot 


[![CRAN status](https://www.r-pkg.org/badges/version/rtoot)](https://CRAN.R-project.org/package=rtoot)
[![CRAN Downloads](https://cranlogs.r-pkg.org/badges/rtoot)](https://CRAN.R-project.org/package=rtoot)
[![R-CMD-check](https://github.com/gesistsa/rtoot/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/gesistsa/rtoot/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/gesistsa/rtoot/branch/main/graph/badge.svg)](https://app.codecov.io/gh/gesistsa/rtoot?branch=main)

[![Codecov test coverage](https://codecov.io/gh/gesistsa/rtoot/graph/badge.svg)](https://app.codecov.io/gh/gesistsa/rtoot)


Interact with the [mastodon API](https://docs.joinmastodon.org/api/) from R.
Get started by reading `vignette("rtoot")`.

Please cite this package as:

Schoch, D. & Chan, C-h., (2023). Rtoot: Collecting and Analyzing Mastodon Data. Mobile Media & Communication, [https://doi.org/10.1177/20501579231176678](https://doi.org/10.1177/20501579231176678).

For a BibTeX entry, use the output from `citation("rtoot")`.

## Installation

To get the current released version from CRAN:

```{r eval = FALSE}
install.packages("rtoot")
```


You can install the development version of rtoot from GitHub:

```{r install, eval=FALSE}
pak::pak("gesistsa/rtoot")
```

## Authenticate

First you should set up your own credentials (see also `vignette("auth")`)

```{r aut, eval=FALSE}
auth_setup()
```
The mastodon API allows different access levels. Setting up a token with your own account grants you the most access.

## Instances

In contrast to twitter, mastodon is not a single instance, but a federation of different servers.
You sign up at a specific server (say "mastodon.social") but can still communicate with others from other servers (say "fosstodon.org"). The existence of different instances makes API calls more complex.
For example, some calls can only be made within your own instance (e.g `get_timeline_home()`), others can access all instances but you need to specify the instance as a parameter (e.g. `get_timeline_public()`).

A list of active instances can be obtained with `get_fedi_instances()`. The results are sorted by number of users.

General information about an instance can be obtained with `get_instance_general()`

```{r, eval = FALSE}
get_instance_general(instance = "mastodon.social")
```

`get_instance_activity()` shows the activity for the last three months and `get_instance_trends()` the trending hashtags of the week.

```{r, eval = FALSE}
get_instance_activity(instance = "mastodon.social")
get_instance_trends(instance = "mastodon.social")
```

## Get toots

To get the most recent toots of a specific instance use `get_timeline_public()`
```{r, eval = FALSE}
get_timeline_public(instance = "mastodon.social")
```

To get the most recent toots containing a specific hashtag use `get_timeline_hashtag()`

```{r, eval = FALSE}
get_timeline_hashtag(hashtag = "rstats", instance = "mastodon.social")
```

The function `get_timeline_home()` allows you to get the most recent toots from your own timeline.

```{r, eval = FALSE}
get_timeline_home()
```

## Get accounts

`rtoot` exposes several account level endpoints. Most require the account id instead of the username as an input. There is, to our knowledge, no straightforward way of obtaining the account id. With the package you can get the id via `search_accounts()`.

```{r, eval=FALSE}
search_accounts("schochastics")
```

*(Future versions will allow to use the username and user id interchangeably)*

Using the id, you can get the followers and following users with `get_account_followers()` and
`get_account_following()` and statuses with `get_account_statuses()`.

```{r, eval = FALSE}
id <- "109302436954721982"
get_account_followers(id)
get_account_following(id)
get_account_statuses(id)
```


## Posting statuses

You can post toots with:
```{r, eval = FALSE}
post_toot(status = "my first rtoot #rstats")
```

It can also include media and alt_text.

```{r, eval = FALSE}
post_toot(
    status = "my first rtoot #rstats", media = "path/to/media",
    alt_text = "description of media"
)
```

You can mark the toot as sensitive by setting `sensitive = TRUE` and add a spoiler text with `spoiler_text`.

*(Be aware that excessive automated posting is frowned upon (or even against the ToS) in many instances. Make sure to check the ToS of your instance and be mindful when using this function.)*

## Streaming

`rtoot` allows to stream statuses from three different streams.
To get any public status on any instance use `stream_timeline_public()`
```{r, eval = FALSE}
stream_timeline_public(timeout = 30, file_name = "public.json")
```
the timeout parameter is the time in seconds data should be streamed (set to `Inf` for indefinite streaming). If just the local timeline is needed, use `local=TRUE` and set an instance (or use your own provided by the token).

`stream_timeline_hashtag()` streams all statuses containing a specific hashtag

```{r, eval = FALSE}
stream_timeline_hashtag("rstats", timeout = 30, file_name = "rstats_public.json")
```

The statuses are directly written to file as json. The function `parse_stream()` can be used
to read in and convert a json to a data frame.

## Pagination

All relevant functions in the package support pagination of results if the `limit` parameter is larger than the default page size (which is 40 in most cases). In this case, you may get more results than requested since the pages are always fetched as a whole. If you for example request 70 records, you will get 80 back, given that many records exist.


## Code of Conduct

Please note that the rtoot project is released with a [Contributor Code of Conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). By contributing to this project, you agree to abide by its terms.

Owner

Name: Transparent Social Analytics
Login: gesistsa
Kind: organization
Location: Germany

Repositories: 2
Profile: https://github.com/gesistsa

Open Science Tools maintained by Transparent Social Analytics Team, GESIS

Citation (CITATION.cff)

# --------------------------------------------
# CITATION file created with {cffr} R package
# See also: https://docs.ropensci.org/cffr/
# --------------------------------------------
 
cff-version: 1.2.0
message: 'To cite package "rtoot" in publications use:'
type: software
license: MIT
title: 'rtoot: Collecting and Analyzing Mastodon Data'
version: 0.3.4.9000
doi: 10.1177/20501579231176678
abstract: 'An implementation of calls designed to collect and organize Mastodon data
  via its Application Program Interfaces (API), which can be found at the following
  URL: <https://docs.joinmastodon.org/>.'
authors:
- family-names: Schoch
  given-names: David
  email: david@schochastics.net
  orcid: https://orcid.org/0000-0003-2952-4812
- family-names: Chan
  given-names: Chung-hong
  email: chainsawtiney@gmail.com
  orcid: https://orcid.org/0000-0002-6232-7530
preferred-citation:
  type: article
  title: 'Rtoot: Collecting and Analyzing Mastodon Data'
  authors:
  - family-names: Schoch
    given-names: David
    email: david@schochastics.net
    orcid: https://orcid.org/0000-0003-2952-4812
  - family-names: Chan
    given-names: Chung-hong
    email: chainsawtiney@gmail.com
    orcid: https://orcid.org/0000-0002-6232-7530
  year: '2023'
  url: https://github.com/gesistsa/rtoot
  journal: Mobile Media & Communication
  doi: 10.1177/20501579231176678
repository: https://CRAN.R-project.org/package=rtoot
repository-code: https://github.com/gesistsa/rtoot
url: https://gesistsa.github.io/rtoot/
contact:
- family-names: Schoch
  given-names: David
  email: david@schochastics.net
  orcid: https://orcid.org/0000-0003-2952-4812
keywords:
- mastodon
- mastodon-api
- rstats
- rstats-package
references:
- type: software
  title: 'R: A Language and Environment for Statistical Computing'
  notes: Depends
  url: https://www.R-project.org/
  authors:
  - name: R Core Team
  institution:
    name: R Foundation for Statistical Computing
    address: Vienna, Austria
  year: '2024'
  version: '>= 3.6'
- type: software
  title: clipr
  abstract: 'clipr: Read and Write from the System Clipboard'
  notes: Imports
  url: http://matthewlincoln.net/clipr/
  repository: https://CRAN.R-project.org/package=clipr
  authors:
  - family-names: Lincoln
    given-names: Matthew
    email: matthew.d.lincoln@gmail.com
    orcid: https://orcid.org/0000-0002-4387-3384
  year: '2024'
- type: software
  title: curl
  abstract: 'curl: A Modern and Flexible Web Client for R'
  notes: Imports
  url: https://jeroen.r-universe.dev/curl
  repository: https://CRAN.R-project.org/package=curl
  authors:
  - family-names: Ooms
    given-names: Jeroen
    email: jeroen@berkeley.edu
    orcid: https://orcid.org/0000-0002-4035-0289
  year: '2024'
- type: software
  title: dplyr
  abstract: 'dplyr: A Grammar of Data Manipulation'
  notes: Imports
  url: https://dplyr.tidyverse.org
  repository: https://CRAN.R-project.org/package=dplyr
  authors:
  - family-names: Wickham
    given-names: Hadley
    email: hadley@posit.co
    orcid: https://orcid.org/0000-0003-4757-117X
  - family-names: François
    given-names: Romain
    orcid: https://orcid.org/0000-0002-2444-4226
  - family-names: Henry
    given-names: Lionel
  - family-names: Müller
    given-names: Kirill
    orcid: https://orcid.org/0000-0002-1416-3412
  - family-names: Vaughan
    given-names: Davis
    email: davis@posit.co
    orcid: https://orcid.org/0000-0003-4777-038X
  year: '2024'
- type: software
  title: httr
  abstract: 'httr: Tools for Working with URLs and HTTP'
  notes: Imports
  url: https://httr.r-lib.org/
  repository: https://CRAN.R-project.org/package=httr
  authors:
  - family-names: Wickham
    given-names: Hadley
    email: hadley@posit.co
  year: '2024'
- type: software
  title: jsonlite
  abstract: 'jsonlite: A Simple and Robust JSON Parser and Generator for R'
  notes: Imports
  url: https://jeroen.r-universe.dev/jsonlite
  repository: https://CRAN.R-project.org/package=jsonlite
  authors:
  - family-names: Ooms
    given-names: Jeroen
    email: jeroen@berkeley.edu
    orcid: https://orcid.org/0000-0002-4035-0289
  year: '2024'
- type: software
  title: tibble
  abstract: 'tibble: Simple Data Frames'
  notes: Imports
  url: https://tibble.tidyverse.org/
  repository: https://CRAN.R-project.org/package=tibble
  authors:
  - family-names: Müller
    given-names: Kirill
    email: kirill@cynkra.com
    orcid: https://orcid.org/0000-0002-1416-3412
  - family-names: Wickham
    given-names: Hadley
    email: hadley@rstudio.com
  year: '2024'
- type: software
  title: knitr
  abstract: 'knitr: A General-Purpose Package for Dynamic Report Generation in R'
  notes: Suggests
  url: https://yihui.org/knitr/
  repository: https://CRAN.R-project.org/package=knitr
  authors:
  - family-names: Xie
    given-names: Yihui
    email: xie@yihui.name
    orcid: https://orcid.org/0000-0003-0645-5666
  year: '2024'
- type: software
  title: rmarkdown
  abstract: 'rmarkdown: Dynamic Documents for R'
  notes: Suggests
  url: https://pkgs.rstudio.com/rmarkdown/
  repository: https://CRAN.R-project.org/package=rmarkdown
  authors:
  - family-names: Allaire
    given-names: JJ
    email: jj@posit.co
  - family-names: Xie
    given-names: Yihui
    email: xie@yihui.name
    orcid: https://orcid.org/0000-0003-0645-5666
  - family-names: Dervieux
    given-names: Christophe
    email: cderv@posit.co
    orcid: https://orcid.org/0000-0003-4474-2498
  - family-names: McPherson
    given-names: Jonathan
    email: jonathan@posit.co
  - family-names: Luraschi
    given-names: Javier
  - family-names: Ushey
    given-names: Kevin
    email: kevin@posit.co
  - family-names: Atkins
    given-names: Aron
    email: aron@posit.co
  - family-names: Wickham
    given-names: Hadley
    email: hadley@posit.co
  - family-names: Cheng
    given-names: Joe
    email: joe@posit.co
  - family-names: Chang
    given-names: Winston
    email: winston@posit.co
  - family-names: Iannone
    given-names: Richard
    email: rich@posit.co
    orcid: https://orcid.org/0000-0003-3925-190X
  year: '2024'
- type: software
  title: testthat
  abstract: 'testthat: Unit Testing for R'
  notes: Suggests
  url: https://testthat.r-lib.org
  repository: https://CRAN.R-project.org/package=testthat
  authors:
  - family-names: Wickham
    given-names: Hadley
    email: hadley@posit.co
  year: '2024'
  version: '>= 3.0.0'
- type: software
  title: rstudioapi
  abstract: 'rstudioapi: Safely Access the RStudio API'
  notes: Suggests
  url: https://rstudio.github.io/rstudioapi/
  repository: https://CRAN.R-project.org/package=rstudioapi
  authors:
  - family-names: Ushey
    given-names: Kevin
    email: kevin@rstudio.com
  - family-names: Allaire
    given-names: JJ
    email: jj@posit.co
  - family-names: Wickham
    given-names: Hadley
    email: hadley@posit.co
  - family-names: Ritchie
    given-names: Gary
    email: gary@posit.co
  year: '2024'
- type: software
  title: vcr
  abstract: 'vcr: Record ''HTTP'' Calls to Disk'
  notes: Suggests
  url: https://github.com/ropensci/vcr/
  repository: https://CRAN.R-project.org/package=vcr
  authors:
  - family-names: Chamberlain
    given-names: Scott
    email: sckott@protonmail.com
    orcid: https://orcid.org/0000-0003-1444-9135
  - family-names: Wolen
    given-names: Aaron
    orcid: https://orcid.org/0000-0003-2542-2202
  - family-names: Salmon
    given-names: Maëlle
    orcid: https://orcid.org/0000-0002-2815-0399
  - family-names: Possenriede
    given-names: Daniel
    orcid: https://orcid.org/0000-0002-6738-9845
  year: '2024'
  version: '>= 0.6.0'
identifiers:
- type: url
  value: https://github.com/gesistsa/rtoot/

GitHub Events

Total

Issues event: 15
Watch event: 5
Delete event: 6
Issue comment event: 47
Push event: 28
Pull request review event: 1
Pull request event: 17
Fork event: 4
Create event: 8

Last Year

Issues event: 15
Watch event: 5
Delete event: 6
Issue comment event: 47
Push event: 28
Pull request review event: 1
Pull request event: 17
Fork event: 4
Create event: 8

Committers

Last synced: 6 months ago

All Time

Total Commits: 233
Total Committers: 12
Avg Commits per committer: 19.417
Development Distribution Score (DDS): 0.438

Past Year

Commits: 22
Committers: 6
Avg Commits per committer: 3.667
Development Distribution Score (DDS): 0.409

Top Committers

Name	Email	Commits
schochastics	d**d@s**t	131
chainsawriot	c**y@g**m	88
JBGruber	g**r@e**e	4
David Lawrence Miller	g**b@n**t	2
glilienthal	g****l	1
Urs Wilke	u**e@g**m	1
Tim Schatto-Eckrodt	k**h@p**e	1
Scott Chamberlain	s**t@f**m	1
Nic Crane	t**c@g**m	1
MikeJohnPage	3****e	1
Lluís Revilla	l****s	1
Arthur Mühl	a**l@g**g	1

Committer Domains (Top 20 + Academic)

gesis.org: 1 fastmail.com: 1 posteo.de: 1 ninepointeightone.net: 1 europa-uni.de: 1 schochastics.net: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time

Total issues: 28
Total pull requests: 28
Average time to close issues: 12 days
Average time to close pull requests: 1 day
Total issue authors: 15
Total pull request authors: 9
Average comments per issue: 2.29
Average comments per pull request: 0.71
Merged pull requests: 23
Bot issues: 0
Bot pull requests: 0

Past Year

Issues: 12
Pull requests: 15
Average time to close issues: 1 day
Average time to close pull requests: about 14 hours
Issue authors: 8
Pull request authors: 6
Average comments per issue: 2.25
Average comments per pull request: 0.53
Merged pull requests: 11
Bot issues: 0
Bot pull requests: 0

View more stats

Top Authors

Issue Authors

schochastics (7)
chainsawriot (5)
marcohhu (2)
llrs (2)
glilienthal (2)
rempsyc (1)
smach (1)
vidonne (1)
drmowinckels (1)
Kudusch (1)
rgaiacs (1)
moodymudskipper (1)
cviehmann (1)
pbulsink (1)
thisisnic (1)

Pull Request Authors

chainsawriot (16)
schochastics (6)
MikeJohnPage (2)
llrs (2)
Kudusch (2)
glilienthal (2)
ArthurMuehl (1)
thisisnic (1)
sckott (1)

Top Labels

Issue Labels

v0.4.0 (2) enhancement (1) bug (1) planned later (1)

Pull Request Labels

Packages

Total packages: 1
Total downloads:
- cran 573 last-month
Total docker downloads: 21,613

Total dependent packages: 0
Total dependent repositories: 2
Total versions: 9
Total maintainers: 1

cran.r-project.org: rtoot

Collecting and Analyzing Mastodon Data

Homepage: https://gesistsa.github.io/rtoot/
Documentation: http://cran.r-project.org/web/packages/rtoot/rtoot.pdf
License: MIT + file LICENSE
Latest release: 0.3.6
published 7 months ago

Versions: 9
Dependent Packages: 0
Dependent Repositories: 2
Downloads: 573 Last month
Docker Downloads: 21,613

Rankings

Docker downloads count: 0.6%

Stargazers count: 4.0%

Forks count: 5.8%

Average: 11.8%

Downloads: 12.9%

Dependent repos count: 19.1%

Dependent packages count: 28.6%

Maintainers (1)

david@schochastics.net

Last synced: 6 months ago

Dependencies

DESCRIPTION cran

httr * imports
jsonlite * imports

.github/workflows/R-CMD-check.yaml actions

actions/checkout v3 composite
r-lib/actions/check-r-package v2 composite
r-lib/actions/setup-pandoc v2 composite
r-lib/actions/setup-r v2 composite
r-lib/actions/setup-r-dependencies v2 composite

.github/workflows/pkgdown.yaml actions

JamesIves/github-pages-deploy-action v4.4.1 composite
actions/checkout v3 composite
r-lib/actions/setup-pandoc v2 composite
r-lib/actions/setup-r v2 composite
r-lib/actions/setup-r-dependencies v2 composite

.github/workflows/test-coverage.yaml actions

actions/checkout v3 composite
actions/upload-artifact v3 composite
r-lib/actions/setup-r v2 composite
r-lib/actions/setup-r-dependencies v2 composite