README.Rmd

---
output:
  github_document:
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = FALSE,
  comment = "",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# 🕸  linxreport - LINX HTML Reporter

`{linxreport}` is an R package for generating a HTML report with
results from the `LINX` structural variant tool from the Hartwig
Medical Foundation - see documentation for LINX at
<https://github.com/hartwigmedical/hmftools/tree/master/linx>.

For useful functions for parsing and processing `LINX` results,
see <https://umccr.github.io/linxreport/reference>.

**NOTE**

`{linxreport}` does not run any analyses!
It simply parses the outputs from LINX
and displays them in tables and tabs. No optimisations are performed.

**CAUTION**

The HTML report size depends on the number of LINX plots!
We have encountered samples with hundreds of plots which has resulted in
HTML files in excess of 200Mb in size.

## 📦 Installation

- Install current `main` version from GitHub with:

```r
remotes::install_github("umccr/linxreport")
```

- Or if used inside a conda environment:

```bash
conda install r-linxreport -c conda-forge -c bioconda
```

## ✨ Usage

You can generate a HTML report within an R session, or from the command line.

### R

The `linx_rmd` function takes as inputs the directories to the LINX tables
and plots, along with the file prefix (`sample`) and the path to output the
HTML to. See `?linx_rmd` for more.

```{r eval=FALSE}
d <- system.file("extdata", package = "linxreport")
linxreport::linx_rmd(
  sample = "subject_a.tumor",
  table_dir = file.path(d, "tables"),
  plot_dir = file.path(d, "plots"),
  out_file = tempfile(fileext = ".html"),
  quiet = TRUE
)
```

### CLI

The `linxreport.R` script is available to generate the HTML report via the
command line:
Quick example:

```bash
linxreport.R \
  --sample subject_a.tumor \
  --plot inst/extdata/plots \
  --table inst/extdata/tables \
  --out subject_a.tumor_linx_report.html
```

**TIP**

- If you're using the conda package, the `linxreport.R` command will already be set up
inside an activated conda environment.
- If you're _not_ using the conda package, you need to export the
`linxreport/inst/cli/` directory to your `PATH` in order to use `linxreport.R`.

See below for required arguments.

```{bash eval=FALSE}
linxr_cli=$(Rscript -e 'x <- system.file("cli", package = "linxreport"); cat(x, "\n")' | xargs)
export PATH="${linxr_cli}:${PATH}"
```

```{bash prompt=TRUE, echo=FALSE}
linxr_cli=$(Rscript -e 'x = system.file("cli", package = "linxreport"); cat(x, "\n")' | xargs)
export PATH="${linxr_cli}:${PATH}"
echo "linxreport.R --version" & linxreport.R --version
echo ""
echo "linxreport.R --help" & linxreport.R --help
```