laminr.Rmd

---
title: "Get started"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Get started}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
# whether or not this code will be used to
# actually upload results to the LaminDB instance
# -> testuser1 is a test account that cannot upload results
submit_eval <- laminr:::.get_user_settings()$handle != "testuser1"
```

This vignette introduces the basic **{laminr}** workflow.

# Setup

Install **{laminr}** from CRAN:

```r
install.packages("laminr", dependencies = TRUE)
```

Set up the Python environment:

```r
laminr::install_lamindb()
```

Set the default LaminDB instance:

```r
laminr::lamin_connect("<owner>/<name>")
```

This instance acts as the default instance for everything that follows.
Any data and tracking information will be added to it.

See `vignette("setup", package = "laminr")` for more details.

# Start your analysis

Load **{laminr}** to get started.

```{r library}
library(laminr)
```

Create your default database `db` object for this R session:

```{r connect-default}
db <- connect()
```

It is used to manage all datasets and metadata entities.

LaminDB tracks which code is used to create data.
To track the current source code, run:

```{r track, eval = submit_eval}
db$track("I8BlHXFXqZOG0000")
```

<div class="alert alert-info" role="alert">
**Tip**

The UID (here `"I8BlHXFXqZOG0000"`) is obtained by running `db$track()` and copying the UID from the output.
</div>

# Connect to other instances

It is possible to connect to any LaminDB instance for reading data.
Connect to the public CELLxGENE instance:

```{r connect-cellxgene}
cellxgene <- connect("laminlabs/cellxgene")
cellxgene
```

# Download a dataset

Artifacts are objects that bundle data and associated metadata.
An artifact can be any file or folder but is typically a dataset.

```{r get-artifact}
artifact <- cellxgene$Artifact$get("7dVluLROpalzEh8mNyxk")
artifact
```

<div class="alert alert-info" role="alert">
**Tip**

You can view detailed information about this dataset on LaminHub: https://lamin.ai/laminlabs/cellxgene/artifact/7dVluLROpalzEh8mNyxk.

You can search and query more CELLxGENE datasets here: https://lamin.ai/laminlabs/cellxgene/artifacts.
</div>

To download the dataset and load it into memory, run:

```{r load-artifact}
adata <- artifact$load()
adata
```

This artifact contains an [`AnnData`](https://anndata.readthedocs.io) object.

<div class="alert alert-info" role="alert">
**Tip**

If you prefer a path to a local file or folder, call `path <- artifact$cache()`.
</div>

# Work with the dataset

Once you have loaded a dataset you can perform any analysis with it as you would normally.
Here, marker genes are calculated for each of the provided cell type labels using [**{Seurat}**](https://satijalab.org/seurat/).

```{r create-seurat}
library(Seurat)

# Create a Seurat object
seurat_obj <- CreateSeuratObject(
  counts = as(Matrix::t(adata$X), "CsparseMatrix"),
  meta.data = adata$obs
)
# Add gene metadata
seurat_obj[["RNA"]] <- AddMetaData(
  GetAssay(seurat_obj), adata$var
)
# Set cell identities to the provided cell type annotation
Idents(seurat_obj) <- "cell_type"
# Normalise the data
seurat_obj <- NormalizeData(seurat_obj)
# Test for marker genes (the output is a data.frame)
markers <- FindAllMarkers(
  seurat_obj,
  features = Features(seurat_obj)[1:100] # Only test a few features for speed
)
# Display the marker genes
knitr::kable(markers)
# Plot the marker genes
DotPlot(seurat_obj, features = unique(markers$gene)) +
  ggplot2::theme(axis.text.x = ggplot2::element_text(angle = 90, vjust = 0.5))
```

# Slice a TileDB-SOMA array store

When artifacts contain TileDB-SOMA array stores they can be opened and sliced using the [**{tiledbsoma}** package](https://single-cell-data.github.io/TileDB-SOMA/index.html).

```{r slice-tiledbsoma, eval = requireNamespace("tiledbsoma", quietly = TRUE)}
# Set some environment variables to avoid an issue with {tiledbsoma}
# https://github.com/chanzuckerberg/cellxgene-census/issues/1261
Sys.setenv(TILEDB_VFS_S3_REGION = "us-west-2")
Sys.setenv(AWS_DEFAULT_REGION = "us-west-2")
Sys.setenv(TILEDB_VFS_S3_NO_SIGN_REQUEST = "true")

# Define a filter to select specific cells
value_filter <- paste(
  "tissue == 'brain' &&",
  "cell_type %in% c('microglial cell', 'neuron') &&",
  "suspension_type == 'cell' &&",
  "assay == '10x 3\\' v3'"
)

# Get the artifact containing the CELLxGENE Census TileDB-SOMA store
census_artifact <- cellxgene$Artifact$get("FYMewVq5twKMDXVy0001")
# Open the SOMACollection
soma_collection <- census_artifact$open()
# Slice the store to get a SOMADataFrame containing metadata for the cells of interest
cell_metadata <- soma_collection$get("census_data")$get("homo_sapiens")$obs$read(value_filter = value_filter)
# Concatenate the results to an arrow::Table
cell_metadata <- cell_metadata$concat()
# Convert to a data.frame
cell_metadata <- cell_metadata$to_data_frame()

cell_metadata
```

# Save the results

Save results as new artifacts to the default LaminDB instance.

```{r save-results, eval = submit_eval}
seurat_path <- tempfile(fileext = ".rds")
saveRDS(seurat_obj, seurat_path)

db$Artifact$from_df(
  markers,
  description = "Marker genes for renal cell carcinoma dataset"
)$save()

db$Artifact$from_path(
  seurat_path,
  description = "Seurat object for renal cell carcinoma dataset"
)$save()
```

# Mark the analysis as finished

Mark the analysis run as finished to create a time stamp and upload source code to the hub.

```{r finish, eval = submit_eval}
db$finish()
```

## Save a notebook report (not needed for `.R` scripts)

Save a run report of your notebook (`.Rmd` or `.qmd` file) to your instance:

1. Render the notebook to HTML

- In RStudio, click the "Knit" button
- **OR** From the command line, run:

  ```bash
  Rscript -e 'rmarkdown::render("laminr.Rmd")'
  ```

- **OR** Use the `rmarkdown` package in R:

  ```r
  rmarkdown::render("laminr.Rmd")
  ```

2. Save it to your LaminDB instance using the `lamin` CLI:

```bash
lamin save laminr.Rmd
```

# Further reading

For more details about how **{laminr}** works see `vignette("concepts_features", package = "laminr")`.