---
title: "Introduction to msigdbr"
output:
  rmarkdown::html_vignette:
    keep_md: true
vignette: >
  %\VignetteIndexEntry{Introduction to msigdbr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
# reduce the minimum number of characters for the tibble column titles (default: 15)
options(pillar.min_title_chars = 10)
# increase the maximum number of rows printed (default: 20)
options(tibble.print_max = 25)
```

## Overview

Pathway analysis is a common task in genomics research and there are many available R-based software tools.
Depending on the tool, it may be necessary to import the pathways, translate genes to the appropriate species, convert between symbols and IDs, and format the resulting object.

The msigdbr R package provides Molecular Signatures Database (MSigDB) gene sets typically used with the Gene Set Enrichment Analysis (GSEA) software:

* in an R-friendly "[tidy](https://r4ds.had.co.nz/tidy-data.html)" format with one gene pair per row
* for multiple frequently studied model organisms, such as mouse, rat, pig, zebrafish, fly, and yeast, in addition to the original human genes
* as gene symbols as well as NCBI Entrez and Ensembl IDs
* without accessing external resources and requiring an active internet connection

Please be aware that the homologs were computationally predicted for distinct genes.
The full pathways may not be well conserved across species.

## Installation

The package can be installed from [CRAN](https://cran.r-project.org/package=msigdbr).

```{r install-package, eval=FALSE}
install.packages("msigdbr")
```

## Usage

Load package.

```{r load-package, message=FALSE}
library(msigdbr)
```

All gene sets in the database can be retrieved by specifying a species of interest.

```{r msigdbr-mouse-all}
all_gene_sets <- msigdbr(species = "Mus musculus")
head(all_gene_sets)
```

You can retrieve data just for a specific collection/category, such as the hallmark gene sets.

```{r msigdbr-mouse-h}
h_gene_sets <- msigdbr(species = "mouse", category = "H")
head(h_gene_sets)
```

You can specify a sub-category, such as C2 (curated) CGP (chemical and genetic perturbations) gene sets.

```{r msigdbr-mouse-c2}
cgp_gene_sets <- msigdbr(species = "mouse", category = "C2", subcategory = "CGP")
head(cgp_gene_sets)
```

If you require more custom filtering, the `msigdbr()` function output is a data frame that can be manipulated using standard methods.
For example, you can subset to a specific collection/category using `dplyr::filter()`.

```{r filter-h}
all_gene_sets %>%
  dplyr::filter(gs_cat == "H") %>%
  head()
```

## Helper functions

There are `msigdbr_species()` and `msigdbr_collections()` helper functions to assist with setting the `msigdbr()` parameters.

You can check the available species with `msigdbr_species()`. Either scientific or common names are acceptable for the `msigdbr()` function.

```{r species}
msigdbr_species()
```

You can check the available collections with `msigdbr_collections()`.

```{r collections}
msigdbr_collections()
```

## Pathway enrichment analysis

The msigdbr output can be used with various pathway analysis packages.

Use the gene sets data frame for [clusterProfiler](https://bioconductor.org/packages/clusterProfiler/) with genes as Entrez Gene IDs.

```{r cp-entrez, eval=FALSE}
msigdbr_t2g <- msigdbr_df %>%
  dplyr::distinct(gs_name, entrez_gene) %>%
  as.data.frame()
enricher(gene = gene_ids_vector, TERM2GENE = msigdbr_t2g, ...)
```

Use the gene sets data frame for [clusterProfiler](https://bioconductor.org/packages/clusterProfiler/) with genes as gene symbols.

```{r cp-symbols, eval=FALSE}
msigdbr_t2g <- msigdbr_df %>%
  dplyr::distinct(gs_name, gene_symbol) %>%
  as.data.frame()
enricher(gene = gene_symbols_vector, TERM2GENE = msigdbr_t2g, ...)
```

Use the gene sets data frame for [fgsea](https://bioconductor.org/packages/fgsea/).

```{r fgsea, eval=FALSE}
msigdbr_list <- split(x = msigdbr_df$gene_symbol, f = msigdbr_df$gs_name)
fgsea(pathways = msigdbr_list, ...)
```

Use the gene sets data frame for [GSVA](https://bioconductor.org/packages/GSVA/).

```{r gsva, eval=FALSE}
msigdbr_list <- split(x = msigdbr_df$gene_symbol, f = msigdbr_df$gs_name)
gsva(gset.idx.list = msigdbr_list, ...)
```

## Potential questions or concerns

**Which version of MSigDB was used?**

This package was generated with MSigDB v7.5.1.
The MSigDB version is used as the base of the msigdbr CRAN package version.
You can check the installed version with `packageVersion("msigdbr")`.

**Can I download the gene sets directly from MSigDB instead of using this package?**

Yes.
You can then import the GMT files (with `getGmt()` from the `GSEABase` package, for example).
The GMTs only include the human genes, even for gene sets generated from mouse experiments.
If you are working with non-human data, you then have to convert the MSigDB genes to your organism or your genes to human.

**Can I convert between human and mouse genes just by adjusting gene capitalization?**

That will work for most genes, but not all.

**Can I convert human genes to any organism myself instead of using this package?**

Yes.
A popular method is using the `biomaRt` package.
You may still end up with dozens of homologs for some genes, so additional cleanup may be helpful.

**Aren't there already other similar tools?**

There are a few resources that provide some of the msigdbr functionality and served as an inspiration for this package.
[WEHI](https://bioinf.wehi.edu.au/software/MSigDB/) provides MSigDB gene sets in R format for human and mouse.
[MSigDF](https://github.com/stephenturner/msigdf) relies on the WEHI resource, but is converted to a more tidyverse-friendly data frame.
There is a more recent [ToledoEM/msigdf](https://github.com/ToledoEM/msigdf) fork.
These are updated at varying frequencies and may not be based on the latest version of MSigDB.
Since 2022, the GSEA/MSigDB team provides [collections that are natively mouse](https://www.gsea-msigdb.org/gsea/msigdb/mouse/collections.jsp) and don't require orthology conversion.

**What if I have other questions?**

You can submit feedback and report bugs on [GitHub](https://github.com/igordot/msigdbr/issues).

## Details

The Molecular Signatures Database (MSigDB) is a collection of gene sets originally created for use with the Gene Set Enrichment Analysis (GSEA) software.
To cite use of the underlying MSigDB data, reference Subramanian, Tamayo, et al. (2005, PNAS) and one or more of the following as appropriate: Liberzon, et al. (2011, Bioinformatics), Liberzon, et al. (2015, Cell Systems), and also the source for the gene set.

Gene homologs are provided by HUGO Gene Nomenclature Committee at the European Bioinformatics Institute which integrates the orthology assertions predicted for human genes by eggNOG, Ensembl Compara, HGNC, HomoloGene, Inparanoid, NCBI Gene Orthology, OMA, OrthoDB, OrthoMCL, Panther, PhylomeDB, TreeFam and ZFIN.
For each human equivalent within each species, only the ortholog supported by the largest number of databases is used.

For information on how to cite cite an R package such as msigdbr, you can execute `citation("msigdbr")`.