---
title: "Introduction to `immunarch`"
author: '<b>ImmunoMind</b> – improving design of T-cell therapies using multi-omics and AI. Research and biopharma partnerships, more details: <a href="https://immunomind.com/">immunomind.com</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, mainly tailored to 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](https://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 during installation, take a look at the [Installation Troubleshooting](https://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(c("devtools", "pkgload")) # skip this if you already installed these packages
devtools::install_github("immunomind/immunarch")
devtools::reload(pkgload::inst("immunarch"))
```


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

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

You can find the list of releases of `immunarch` here: https://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, k-mer analysis and public repertoire analysis see "Tutorials".


## Installation troubleshooting

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

If you run into 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 most recent one. 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 reinstall the packages that were built under the previous R versions. In the example above those would be the packages `httr` and `usethis`. In order to reinstall 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 the packages that need to be reinstalled 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 other issues, for instance some old packages can't be updated, or you see an error message such as `ld: warning: directory not found for option` or `ld: library not found for -lgfortran`, [this link](https://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](https://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](https://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 encounter issues with the package installation, or if you want to change the folder for R packages, feel free to check [this forum post](https://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 reopen 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](https://github.com/r-lib/devtools/issues/1941) for help.

9. If you cannot install dependencies for `immunarch`, please consider 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", "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 any of the troubles still persist, let us know via [GitHub](https://github.com/immunomind/immunarch/issues) (preferably) or [support@immunomind.io](mailto:support@immunomind.io) (in case of private data).