---
title: "Infer species" 
author: "<h4>Author: <i>Brian M. Schilder</i></h4>" 
date: "<h4>Most recent update: <i>`r format( Sys.Date(), '%b-%d-%Y')`</i></h4>"
output:
  BiocStyle::html_document:
vignette: >
    %\VignetteIndexEntry{Infer species} 
    %\usepackage[utf8]{inputenc}
    %\VignetteEngine{knitr::rmarkdown}
---
  
# Installation

```{r, eval=FALSE}
if (!requireNamespace("BiocManager", quietly = TRUE))
     install.packages("BiocManager") 
# orthogene is only available on Bioconductor>=3.14
if(BiocManager::version()<"3.14") 
  BiocManager::install(update = TRUE, ask = FALSE)

BiocManager::install("orthogene")
```

```{r setup}
library(orthogene)

data("exp_mouse")
# Setting to "homologene" for the purposes of quick demonstration.
# We generally recommend using method="gprofiler" (default).
method <- "homologene"  
```

# Introduction

It's not always clear whether a dataset is using the
original species gene names, 
human gene names, or some other species' gene names.

`infer_species` takes a list/matrix/data.frame with genes and 
infers the species that they best match to!

For the sake of speed, the genes extracted from `gene_df` 
are tested against genomes from only the following 6 `test_species` by default:
- human
- monkey
- rat
- mouse
- zebrafish
- fly
 
However, you can supply your own list of `test_species`, which will
be automatically be mapped and standardised using `map_species`.

# Examples

## Mouse genes

### Infer the species

```{r}
matches <- orthogene::infer_species(gene_df = exp_mouse, 
                                    method = method)
```

## Rat genes

### Create example data

To create an example dataset, turn the gene names into rat genes.

```{r}
exp_rat <- orthogene::convert_orthologs(gene_df = exp_mouse, 
                                        input_species = "mouse", 
                                        output_species = "rat",
                                        method = method)
```

### Infer the species  

```{r}
matches <- orthogene::infer_species(gene_df = exp_rat, 
                                    method = method)
```

## Human genes

### Create example data  

To create an example dataset, turn the gene names into human genes.

```{r}
exp_human <- orthogene::convert_orthologs(gene_df = exp_mouse, 
                                          input_species = "mouse", 
                                          output_species = "human",
                                          method = method)
```

### Infer the species  

```{r}
matches <- orthogene::infer_species(gene_df = exp_human, 
                                    method = method)
```


# Additional `test_species`

You can even supply `test_species` with the name of one of the R packages that
`orthogene` gets orthologs from. This will test against all species available 
in that particular R package.

For example, by setting `test_species="homologene"` we automatically test for 
% gene matches in each of the 20+ species available in `homologene`.

```{r}
matches <- orthogene::infer_species(gene_df = exp_human, 
                                    test_species = method, 
                                    method = method)
```


# Session Info 

<details> 

```{r Session Info}
utils::sessionInfo()
```

</details>  
<br>