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

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(biocohort)
```

This article shows the path most studies take: a manifest file becomes a
`Cohort`, the cohort answers questions about who has what sample, and it
writes the sample sheet a pipeline expects.

## From a manifest to a cohort

A manifest is one row per sample. Four columns carry the shape of the study:
`subject_id`, `assay`, `sample_id`, and `role`. Every other column is
metadata, either about the subject (`species`, `genotype`, `sex`, ...) or
about the sample (`fastq_1`, `fastq_2`, `lane`, ...).

```{r}
dir <- tempfile()
dir.create(dir)
writeLines(
  c(
    "subject_id,species,genotype,sex,assay,sample_id,role,fastq_1,fastq_2",
    "R1,rat,WT,F,wes,T1,tumor,t1_R1.fq.gz,t1_R2.fq.gz",
    "R1,rat,WT,F,wes,N1,normal,n1_R1.fq.gz,n1_R2.fq.gz",
    "R2,rat,KO,M,wes,T2,tumor,t2_R1.fq.gz,t2_R2.fq.gz",
    "R2,rat,KO,M,wes,N2,normal,n2_R1.fq.gz,n2_R2.fq.gz"
  ),
  file.path(dir, "manifest.csv")
)

parsed <- read_manifest(file.path(dir, "manifest.csv"))
parsed$subject_tbl
parsed$sample_map
```

`read_manifest()` reads every column as text, so an id like `007` keeps its
leading zero. Build the cohort from the parsed tables:

```{r}
cohort <- cohort_new(parsed$subject_tbl, parsed$sample_map)
cohort
```

## A wide table instead

Some studies keep one row per subject, with one id column per assay. Turn
that into the long form with `manifest_from_wide()` before building a cohort:

```{r}
wide <- data.frame(
  subject_id = c("R1", "R2"),
  species = "rat",
  wes_tumor_id = c("T1", "T2"),
  wes_normal_id = c("N1", "N2"),
  stringsAsFactors = FALSE
)

id_cols <- data.frame(
  column = c("wes_tumor_id", "wes_normal_id"),
  assay = c("wes", "wes"),
  role = c("tumor", "normal"),
  stringsAsFactors = FALSE
)

manifest_from_wide(wide, id_cols)
```

## Reading the cohort back

The accessors return plain tibbles, so the rest of a script can use ordinary
dplyr code.

```{r}
subjects(cohort)
samples(cohort, assay = "wes")
completeness(cohort, wide = TRUE)
```

`cohort_filter()` keeps a subset of subjects and returns a cohort that is
still valid:

```{r}
cohort_filter(cohort, genotype == "KO")
```

## Writing a pipeline sample sheet

`sample_sheet()` writes the sample list in the shape a pipeline expects.
Built-in templates cover a few common nf-core pipelines:

```{r}
sample_sheet_templates()
sample_sheet(cohort, template = "nf-core/sarek", assay = "wes")
```

## Registering an analysis

An `AnalysisSpec` records where an analysis writes its output and how to
read it back. `load_analysis()` then resolves the path for every subject or
pair and reads what it finds.

```{r}
spec <- analysis_spec_new(
  name = "somatic_vars",
  assay = "wes",
  level = "pair",
  path_template = file.path(dir, "{pair_id}.tsv")
)
cohort <- analysis_register(cohort, spec)
analysis_list(cohort)
```

## Saving and loading a cohort

```{r}
cohort_save(cohort, file.path(dir, "cohort.rds"))
reread <- cohort_read(file.path(dir, "cohort.rds"))
identical(subjects(cohort), subjects(reread))
```

A study with more than a manifest, a few paths, and a couple of analyses is
easier to keep in one YAML file. See `?read_study_yaml` for the file format.

## Translating features across species

`translate()` moves a feature table from one species or genome build to
another. Coordinate features go through a liftover backend. Gene features go
through an ortholog backend. See `?translate` and `?liftover_intervals` for
the full set of options, including how to register a custom backend.

## Where to go next

- The [Glossary](glossary.html) article defines the terms used across the
  package.
- The [Naming conventions](naming-conventions.html) article lists the
  standard names for columns, objects, and files.