---
title: "Get started"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Get started}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
eval = TRUE,
echo = TRUE,
comment = "#>"
)
```
## Introduction
Scientific journals operate over a broad spectrum of publishing strategies,
from strictly for-profit, to non-profit, and in-between business models
(e.g. for-profit but academic friendly journals). Scientific publishing is
increasingly dominated by for-profit journals, many of which attract prestige
and submissions through high impact factors (McGill 2024). In contrast,
non-profit journals – those that reinvest revenue into the academic community –
struggle to maintain visibility despite offering more equitable publishing
models.
The R package `fairpub` aims to provide a user-friendly toolbox to investigate
the fairness of a research (article, bibliographic list, citation list,
etc.). The fairness is measured according to two dimensions:
- the **Business model** of the journal: for-profit vs. non-profit
- the **Academic friendly** status of the journal: yes or no
A journal with a non-profit business model is fairer than an academic friendly
journal with a for-profit business model. But the later is still fairer than a
non-academic friendly journal with a for-profit business model.
This information comes from the
[DAFNEE database](https://dafnee.isem-evolution.fr/), a Database of Academia
Friendly jourNals in Ecology and Evolution.
**Note:** the package `fairpub` provides a subset of the original
[DAFNEE database](https://dafnee.isem-evolution.fr/)
(fields "Ecology", "Evolution/Systematics", "General" and "Organisms").
We are currently working to increase this list of journals.
The package `fairpub` also implements the method proposed by Beck _et al._
(2026): the strategic citation. By deliberately choosing to cite relevant
articles from non-profit journals when multiple references would be equally
valid, researchers can contribute to increasing their visibility and future
impact factor. This method is implemented in the `fp_compute_citation_ratio()`
function and can answer the question
**How fair am I when I cite previous works?** by
computing the fairness ratio on the references cited in a manuscript.
The `fp_compute_citation_ratio()` function can also be used to answer the
question **How fair is my publication list?** by computing the fairness ratio
on the bibliography of an author.
## Setup
Let's explore the features of `fairpub` but first let's load and attach the
`fairpub` package:
```{r setup}
library(fairpub)
```
Some functions of `fairpub` query the [OpenAlex](https://openalex.org/)
bibliographic database by using the
[`openalexR`](https://docs.ropensci.org/openalexR/) package. As recommended by
the OpenAlex API [documentation](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication#the-polite-pool),
it's a good practice to send your email address to each query made by
`openalexR`.
Use the function `options()` to store your email address as a global variable
available for the current session:
```{r 'setup_oa_api', eval=FALSE}
options(openalexR.mailto = 'your_email@mail.com')
```
**Note:** no registration is required on the OpenAlex website.
## Journal fairness
The function `fp_get_journal_fairness()` of the package `fairpub` queries the DAFNEE
database to retrieve the fairness of a journal.
```{r 'fp_get_journal_fairness-1', eval=FALSE}
fp_get_journal_fairness(journal = "Science")
#> journal fairness
#> 1 Science Non-profit and academic friendly
```
This function returns a two-column `data.frame` with the name of the journal and
the fairness status of the journal. This fairness status can have the following
three values:
- Non-profit and academic friendly
- For-profit and academic friendly
- For-profit and non-academic friendly
This function searches for an exact match (case insensitive) but if the journal
is not found, a fuzzy search returns the three best candidates (low distance
between characters). For instance:
```{r 'fp_get_journal_fairness-2', eval=FALSE}
fp_get_journal_fairness(journal = "Science of Nature")
#> No exact match found!
#> The fuzzy search returns these three best candidates:
#> 'The Science of Nature'
#> 'Science Advances'
#> 'People and Nature'
```
Then, user can run this same function with the correct spelling:
```{r 'fp_get_journal_fairness-3', eval=FALSE}
fp_get_journal_fairness(journal = "The Science of Nature")
#> journal fairness
#> 1 The Science of Nature For-profit and non-academic friendly
```
**Note:** as mentioned before, the list of DAFNEE journals included in `fairpub`
is not exhaustive, and it's possible that many journals are missing.
## Article fairness
The function `fp_get_article_fairness()` of the package `fairpub` is dedicated to
retrieve the fairness of a scientific article. This function first queries the
[OpenAlex](https://openalex.org/) bibliographic database to find the journal
name from the DOI (digital object identifier) of the article. Then, the journal
name is used to query the DAFNEE database to get the fairness status.
**Note:** even if this function works at the article level, this fairness status
is associated to the journal. In other words, all articles published in the same
journal will have the same fairness status.
```{r 'fp_get_article_fairness-1', eval=FALSE}
fp_get_article_fairness(doi = "10.1126/science.162.3859.1243")
#> journal fairness
#> 1 Science Non-profit and academic friendly
```
The output is identical to the output of `fp_get_journal_fairness()`, i.e. a
two-column `data.frame`.
**Note:** if the article is not found in OpenAlex, the output will be:
```{r 'fp_get_article_fairness-2', eval=FALSE}
fp_get_article_fairness(doi = "10.xxxx/xxxx")
#> journal fairness
#> 1 NA Record not found in OpenAlex
```
**Note:** if the article is found in OpenAlex but the journal is absent from DAFNEE,
the output will be:
```{r 'fp_get_article_fairness-3', eval=FALSE}
fp_get_article_fairness(doi = "10.21105/joss.05753")
#> journal fairness
#> 1 The Journal of Open Source Software Record not found in DAFNEE database
```
## Citation ratio
One core function of `fairpub` is `fp_compute_citation_ratio()`. It computes the fairness
ratio of a list of references cited in a manuscript. This ratio can be used by
the author to replace some for-profit citations by fairer citations (e.g.
citations of articles published in non-profit journals). Of course, if the findings
of two studies are similar.
This function uses one argument: a vector of DOI. The `fairpub` package provides
the `fp_extract_doi()` function that reads a BibTeX file and extracts all
available DOI.
Let's use the function `fp_extract_doi()` with the BibTeX file provided as
an example in `fairpub`.
```{r 'fp_extract_doi-1'}
# Path to the BibTeX provided by 'fairpub' ----
filename <- system.file(
file.path("extdata", "references.bib"),
package = "fairpub"
)
# Extract DOI from this BibTeX file ----
doi_list <- fp_extract_doi(file = filename)
doi_list
```
**Note:** make sure to check your references, especially the DOI field. In this
example, some references don't have a DOI (book, book chapter, etc.). The
`fp_extract_doi()` function don't remove these references to provide
a full report (see below the output of the `fp_compute_citation_ratio()` function).
Now we have a vector of DOI, we can use the `fp_compute_citation_ratio()` function to
compute the fairness ratio of this list.
```{r 'fp_compute_citation_ratio-1', eval=FALSE}
fp_compute_citation_ratio(doi = doi_list)
#> $summary
#> metric value
#> 1 Total references 38
#> 2 References with DOI 33
#> 3 Deduplicated references 33
#> 4 References found in OpenAlex 33
#> 5 References found in DAFNEE 11
#> 6 Non-profit and academic friendly references 9
#> 7 For-profit and academic friendly references 2
#> 8 For-profit and non-academic friendly references 0
#>
#> $ratios
#> Non-profit and academic friendly For-profit and academic friendly
#> 0.82 0.18
#> For-profit and non-academic friendly
#> 0.00
```
This function returns a two-element `list`:
- `summary`: a two-column `data.frame` with the number of references remaining
after each step of the workflow
- `ratio`: a three-element `vector` with the value of the three fairness ratios
In this example, this list of references has a fairness ratio
(`Non-profit and academic friendly`) of 82%. But this value must be interpreted
with caution. Indeed this ratio has been computed on 29% (11 over 38) of the
references, because the journal of 27 articles is not indexed in the DAFNEE
database.
**Note:** as mentioned before, we are currently working to improve the list of
journals indexed in the DAFNEE database.
## Author ratio
It's possible to use the `fp_compute_citation_ratio()` function to compute the fairness
ratio of all publications of an author. In that case, the list of DOI should
contain all articles published by this author.
## References
Beck M, Annasawmy P, Birre D, Busana M, Casajus N, Coux C, Marino C, Mouquet N, Nicvert L, Oliveira BF, Petit-Cailleux C, Tortosa A, Unkule M, Vagnon C & Veytia D (2026) Citation self-awareness for a fairer academic publishing landscape. **BioScience**. DOI: [10.1093/biosci/biag028](https://doi.org/10.1093/biosci/biag028).
McGill B (2024) The state of academic publishing in 3 graphs, 6 trends, and 4 thoughts.
URL: [https://dynamicecology.wordpress.com](https://dynamicecology.wordpress.com/2024/04/29/the-state-of-academic-publishing-in-3-graphs-5-trends-and-4-thoughts/).