---
title: "HCAMatrixBrowser Quick Start"
date: "`r BiocStyle::doc_date()`"
vignette: |
  %\VignetteIndexEntry{HCAMatrixBrowser Quick Start}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
output:
  BiocStyle::html_document:
    toc_float: true
Package: HCAMatrixBrowser
---

# Installation

## HCAMatrixBrowser and HCABrowser

First install the `HCABrowser` to be able to query for `bundle_fqid`
identifiers.

```{r,eval=FALSE}
if (!requireNamespace("BiocManager", quietly = TRUE)
    install.packages("BiocManager")

BiocManager::install("HCABrowser")
BiocManager::install("HCAMatrixBrowser")
```

Load packages:

```{r,include=TRUE,results="hide",message=FALSE,warning=FALSE}
library(HCABrowser)
library(HCAMatrixBrowser)
```

# Constructing a query using the `HCABrowser`

*Warning*. `HCABrowser` queries under construction.

```{r,eval=FALSE}
hcabrowser <- HCABrowser::HCABrowser()

res <- hcabrowser %>% filter(
    library_construction_approach.ontology == "EFO:0008931" &
    paired_end == True &
    specimen_from_organism_json.biomaterial_core.ncbi_taxon_id == 9606
)

(bundle_fqids <- res %>% pullBundles)
```

Alternatively, we can provide our own bundle identifiers as a character
vector:

```{r}
bundle_fqids <-
    c("ffd3bc7b-8f3b-4f97-aa2a-78f9bac93775.2019-05-14T122736.345000Z",
    "f69b288c-fabc-4ac8-b50c-7abcae3731bc.2019-05-14T120110.781000Z",
    "f8ba80a9-71b1-4c15-bcfc-c05a50660898.2019-05-14T122536.545000Z",
    "fd202a54-7085-406d-a92a-aad6dd2d3ef0.2019-05-14T121656.910000Z",
    "fffe55c1-18ed-401b-aa9a-6f64d0b93fec.2019-05-17T233932.932000Z")
```

# Downloading HCA expression matrix data

First, we create an HCA Matrix API object with the use of the `HCAMatrix`
function:

```{r}
hca <- HCAMatrix()
```


## v0 Service (legacy)

By default, the `loadHCAMatrix` function from `HCAMatrixBrowser` uses
the loom format as output. See the 'Supported formats' section below
for more details.

* format: [loom](http://loompy.org/)

```{r}
(lex <- loadHCAMatrix(hca, bundle_fqids = bundle_fqids,
    format = "loom"))
```

* Column annotations (`colnames`): "CellID"

```{r}
head(colnames(lex))
```

## v1 Service

The newer v1 matrix service allows users to apply filters to the matrix
requests. This is convenient for narrowing down the data to a set of
features.

Filters can be created using the API object and the filter function:

```{r}
hca1 <- filter(hca, bundle_uuid == "ffd3bc7b-8f3b-4f97-aa2a-78f9bac93775")
```

We can have a look at the created filters using the `filters` function on
the API object:

```{r}
filters(hca1)
```

To request the download, we can use the `loadHCAMatrix` function as well:

*Note*. Now the bundle_fqids argument is left empty.

```{r}
loadHCAMatrix(hca1, format = "loom")
```

### Supported formats

The matrix service allows you to request three different file formats:

1. loom (default)
2. mtx
3. csv

These can be requested by changing the `format` argument in the `loadHCAMatrix`
function. For more details, see our "Generating HCAMatrix queries with the API"
vignette.

## `filter` operations

Recent changes to the `HCAMatrixBrowser` package, allow us to make use
of the built-in API functionality. We can use one or more filters to
specify a particular query in the HCAMatrix API.

In this example, we use the existing `bundle_fqids` character vector
to generate a filter and apply it to the API class object (`hca`).

```{r}
hca2 <- filter(hca, dss_bundle_fqid %in% bundle_fqids)
```

### `filters`

We use the `filters` function to get a view of the applied filters.

```{r}
filters(hca2)
```

For more information on filters, see the `HCAMatrix` vignette titled
'Generating HCAMatrix queries with the API'.

### Sending the query

Once we have prepared the appropriate filters, we can send the query
off to the HCA Matrix Service to get generate a response.

**Note**. We don't need to do much more than supplying the HCA API object
and a particular data format (default is `loom`).

```{r}
loadHCAMatrix(hca2)
```