---
title: "Introduction to `immunarch`"
author: '<a href="http://immunomind.io">ImmunoMind</a>'
date: "support@immunomind.io"
output:
  html_document:
    fig_height: 8
    fig_width: 10
    theme: spacelab
    toc: yes
  pdf_document:
    toc: yes
  word_document:
    toc: yes
---


<!--
%\VignetteEngine{knitr::rmarkdown}
%\VignetteIndexEntry{Introduction to immunarch}
%\VignettePackage{immunarch}
-->


# Introduction
`immunarch` is an R package designed to analyse T-cell receptor (TCR) and B-cell receptor (BCR) repertoires, aimed at medical scientists and bioinformaticians. The mission of `immunarch` is to make immune sequencing data analysis as effortless as possible and help you focus on research instead of coding. Follow us on [Twitter](http://twitter.com/immunomind) for news and updates.


## Installation

### Latest release on CRAN
In order to install `immunarch` execute the following command:

```r
install.packages("immunarch")
```

That's it, you can start using `immunarch` now! See the [Quick Start](#quick-start) section below to dive into immune repertoire data analysis. If you run in any trouble with installation, take a look at the [Installation Troubleshooting](http://immunarch.com/articles/v1_introduction.html#installation-troubleshooting) section.

Note: there are quite a lot of dependencies to install with the package because it installs all the widely-used packages for data analysis and visualisation. You got both the AIRR data analysis framework and the full Data Science package ecosystem with only one command, making `immunarch` the entry-point for single-cell & immune repertoire Data Science.


### Latest release on GitHub
If the above command doesn't work for any reason, try installing `immunarch` directly from its repository:

```r
install.packages("devtools") # skip this if you already installed devtools
devtools::install_github("immunomind/immunarch")
```


### Latest pre-release on GitHub
Since releasing on CRAN is limited to one release per one-two months, you can install the latest pre-release version with bleeding edge features and optimisations directly from the code repository. In order to install the latest pre-release version, you need to execute only two commands:

```r
install.packages("devtools") # skip this if you already installed devtools
devtools::install_github("immunomind/immunarch", ref="dev")
```

You can find the list of releases of `immunarch` here: http://github.com/immunomind/immunarch/releases


## Quick start
The gist of the typical TCR or BCR data analysis workflow can be reduced to the next few lines of code.

### Use `immunarch` data

**1) Load the package and the data**

```r
library(immunarch)  # Load the package into R
data(immdata)  # Load the test dataset
```

**2) Calculate and visualise basic statistics**

```r
repExplore(immdata$data, "lens") %>% vis()  # Visualise the length distribution of CDR3
repClonality(immdata$data, "homeo") %>% vis()  # Visualise the relative abundance of clonotypes
```

**3) Explore and compare T-cell and B-cell repertoires**
```r
repOverlap(immdata$data) %>% vis()  # Build the heatmap of public clonotypes shared between repertoires
geneUsage(immdata$data[[1]]) %>% vis()  # Visualise the V-gene distribution for the first repertoire
repDiversity(immdata$data) %>% vis(.by = "Status", .meta = immdata$meta)  # Visualise the Chao1 diversity of repertoires, grouped by the patient status
```

### Use your own data

```r
library(immunarch)  # Load the package into R
immdata <- repLoad("path/to/your/data")  # Replace it with the path to your data. Immunarch automatically detects the file format.
```

### Advanced methods

For advanced methods such as clonotype annotation, clonotype tracking, kmer analysis and public repertoire analysis see "Tutorials".


## Installation troubleshooting

If you can not install `devtools`, check sections 1 and 2 below.

If you run in any other trouble, try the following steps:

1. Check your R version. Run `version` command in the console to get your R versions. If the R version is below 3.5.0 (for example, `R version 3.1.0`), try updating your R version to the latest one. Check this [this link](https://cran.r-project.org/bin/linux/ubuntu/README.html) if you are on Ubuntu. Note: if you try to install a package after the update and it still fails with the following message:

   ```
   ERROR: dependencies ‘httr’, ‘usethis’ are not available for package ‘devtools’
   * removing ‘/home/ga/R/x86_64-pc-linux-gnu-library/3.5/devtools’
   Warning in install.packages :
     installation of package ‘devtools’ had non-zero exit status
   ```

   it means that you need to re-install packages that were built under the previous R version. In the above example it would be packages `httr` and `usethis`. In order to re-install a package you need to execute the command `install.packages("package_name")`, where `package_name` is the name of the package to update. To find packages that need to be re-installed after updating R, you need to look for installation messages like this in the installation process:

   ```
ERROR: package ‘usethis’ was installed by an R version with different internals; it needs to be reinstalled for use with this R version
   ```


2. Check if your packages are outdated and update them. In RStudio you can run the "Update" button on top of the package list in the "Package" window. In R console you can run the `old.packages()` command to view a list of outdated packages. The following messages indicate that an update is required:

   ```
Error: package ‘dtplyr’ 0.0.3 was found, but >= 1.0.0 is required by ‘immunarch’
Execution halted
ERROR: lazy loading failed for package ‘immunarch’
   ```
   

   ```
byte-compile and prepare package for lazy loading
Error in loadNamespace(j <- i[[1L]], c(lib.loc, .libPaths()), versionCheck = vI[[j]]) : 
  namespace 'ggalluvial' 0.9.1 is being loaded, but >= 0.10.0 is required
Calls: <Anonymous> ... namespaceImportFrom -> asNamespace -> loadNamespace
Execution halted
   ```

3. For Mac users. Make sure to install XCode from App Store first and command line developers tools second by executing the following command in Terminal: `xcode-select –install`

4. For Mac users. If you have issues like old packages can't be updated, or error messages such as `ld: warning: directory not found for option` or `ld: library not found for -lgfortran`, [this link](http://thecoatlessprofessor.com/programming/rcpp-rcpparmadillo-and-os-x-mavericks--lgfortran-and--lquadmath-error/) will help you to fix the issue.

5. For Mac Mojave (1.14) users. If you run into the following error:

   ```
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include/c++/v1/math.h:301:15: fatal error: 'math.h' file not found
#include_next <math.h>
              ^~~~~~~~
   ```

   Open Terminal, execute the following command and try again to install `immunarch`:
   
   ```
sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg -target /
   ```

6. For Linux users. If you have issues with the `igraph` library or have Fortran errors such as:

   ```
** testing if installed package can be loaded from temporary location
Error: package or namespace load failed for 'igraph' in dyn.load(file, DLLpath = DLLpath, ...):
 unable to load shared object '/usr/local/lib/R/site-library/00LOCK-igraph/00new/igraph/libs/igraph.so':
  libgfortran.so.4: cannot open shared object file: No such file or directory
   ```
   
   See [this link](http://ashokragavendran.wordpress.com/2017/10/24/error-installing-rigraph-unable-to-load-shared-object-igraph-so-libgfortran-so-4-cannot-open-shared-object-file-no-such-file-or-directory/) for help.

7. For Linux users. If you have issues with the `rgl` package:
   
   ```
configure: error: missing required header GL/gl.h 
ERROR: configuration failed for package ‘rgl’
   ```
   
   Install "mesa-common-dev" via OS terminal by executing the following command:
   
   ```
apt-get install mesa-common-dev
   ```
   
   Check [this link](http://stackoverflow.com/questions/15292905/how-to-solve-the-error-missing-required-header-gl-gl-h-while-installing-the-p) for more information and other possible workarounds.

7. If you have error messages with `rlang` in them such as:

   ```
   Error: .onLoad failed in loadNamespace() for 'vctrs', details:
   call: env_bind_impl(.env, list3(...), "env_bind()", bind = TRUE)
   error: object 'rlang_env_bind_list' not found
   ```

   Remove the `rlang` package and install it again. This error is often happens after updating R to a newer version, while `rlang` not being properly updated.
   
8. If you have error messages like the following (note the `(converted from warning)` part):

   ```
** byte-compile and prepare package for lazy loading
Error: (converted from warning) package 'ggplot2' was built under R version 3.6.1
Execution halted
ERROR: lazy loading failed for package 'immunarch'
   ```

   Execute the following command in R and try again to install the package:
   
   ```
Sys.setenv(R_REMOTES_NO_ERRORS_FROM_WARNINGS="true")
   ```
   
9. For Windows users. If you have issues with the package installation, or if you want to change the folder for R packages, feel free to check [this forum post](http://community.rstudio.com/t/help-regarding-package-installation-renviron-rprofile-r-libs-r-libs-site-and-r-libs-user-oh-my/13888/8).

9. For Windows users. Make sure to install [Rtools](https://cran.r-project.org/bin/windows/Rtools/). Before installation close RStudio, install Rtools and re-open it afterwards. To check if Rtools installed correctly, run the `devtools::find_rtools()` command (after installing the devtools package). If you have an error, check [this link](http://github.com/r-lib/devtools/issues/1941) for help.

9. If you can not install dependencies for `immunarch`, please try manual installation of all dependencies by executing the following command in R console:
   
   ```
install.packages(c("rematch", "prettyunits", "forcats", "cellranger", "progress", "zip", "backports", "ellipsis", "zeallot", "SparseM", "MatrixModels", "sp", "haven", "curl", "readxl", "openxlsx", "minqa", "nloptr", "RcppEigen", "utf8", "vctrs", "carData", "pbkrtest", "quantreg", "maptools", "rio", "lme4", "labeling", "munsell", "cli", "fansi", "pillar", "viridis", "car", "ellipse", "flashClust", "leaps", "scatterplot3d", "modeltools", "DEoptimR", "digest", "gtable", "lazyeval", "rlang", "scales", "tibble", "viridisLite", "withr", "assertthat", "glue", "magrittr", "pkgconfig", "R6", "tidyselect", "BH", "plogr", "purrr", "ggsci", "cowplot", "ggsignif", "polynom", "fastcluster", "plyr", "abind", "dendextend", "FactoMineR", "mclust", "flexmix", "prabclus", "diptest", "robustbase", "kernlab", "GlobalOptions", "shape", "colorspace", "stringi", "hms", "clipr", "crayon", "httpuv", "mime", "jsonlite", "xtable", "htmltools", "sourcetools", "later", "promises", "gridBase", "RColorBrewer", "yaml", "ggplot2", "dplyr", "dtplyr", "dbplyr", "data.table", "gridExtra", "ggpubr", "pheatma3", "ggrepel", "reshape2", "DBI", "factoextra", "fpc", "circlize", "tidyr", "Rtsne", "readr", "readxl", "shiny", "shinythemes", "treemap", "igraph", "airr", "ggseqlogo", "UpSetR", "stringr", "ggalluvial", "Rcpp"))
   ```
   
9. If you encounter the following error while running the `devtools::install_local` function:

   ```
   In normalizePath(path.expand(path), winslash, mustWork) :
     path[1]="path/to/your/folder/with/immunarch.tar.gz":

   In file.copy(x$path, bundle, recursive = TRUE) :
     problem copying No such file or directory
   ```

   Check your path to the downloaded package archive file. It should not be "path/to/your/folder/with/immunarch.tar.gz", but a path on your PC to the downloaded file, e.g., "C:/Users/UserName/Downloads/immunarch.tar.gz" or "/Users/UserName/Downloads/immunarch.tar.gz".


9. If troubles still persist, let us know via [GitHub](http://github.com/immunomind/immunarch/issues) (preferably) or [support@immunomind.io](mailto:support@immunomind.io) (in case of private data).
