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

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

This vignette describes the four experiment types in `glyexp`:
"glycomics", "glycoproteomics", "traitomics", and "traitproteomics".
You can check your experiment type using `get_exp_type()`.

```{r setup}
library(glyexp)
library(glyrepr)
```

## Why Experiment Types Matter

Experiment types refer to:

1. A label stored in the `exp_type` field of your `experiment()` object's metadata
2. The expected structure of your variable information table

When your experiment has a specific type, glycoverse functions know what to expect from your data structure.
These are guidelines rather than strict rules.

**Note:** If you're not using `glydet` or `glymotif`, you can skip the `traitomics` and `traitproteomics` sections.

## The Four Experiment Types

The `glyexp` package recognizes four distinct experiment types:

- **"glycomics"**: Glycan-focused experiments
- **"glycoproteomics"**: Glycans with protein context
- **"traitomics"**: Derived traits from glycan data
- **"traitproteomics"**: Derived traits at the protein level

The first two are standard glycobiology experiments. When you use `glyread` to import data, it automatically determines the type.

The last two are unique to the glycoverse ecosystem - they result from functions in `glymotif` or `glydet`.

### Glycomics

"glycomics" is the most straightforward type.
Each row in the variable information table represents a single glycan (or a spectrum match for MS data).

Expected columns in variable information table:

- `glycan_composition`: Glycan composition as a `glyrepr::glycan_composition()` object
- `glycan_structure`: (Optional) Glycan structure as a `glyrepr::glycan_structure()` object

```{r}
get_var_info(real_experiment2)
```

### Glycoproteomics

"glycoproteomics" adds protein context.
Each row represents a glycopeptide or glycoform, indicating not just what glycans are present but where they're attached.

Variable information table should include:

- `protein`: Protein UniProt accession (character string)
- `protein_site`: Glycosylation site position on the protein (integer)
- `glycan_composition`: Glycan composition as a `glyrepr::glycan_composition()` object
- `glycan_structure`: (Optional) Glycan structure as a `glyrepr::glycan_structure()` object

```{r}
get_var_info(real_experiment)
```

### Traitomics

Both `traitomics` and `traitproteomics` emerge when you transform data
using `glydet::derive_traits()` or `glymotif::quantify_motifs()`.

When you apply `derive_traits()` to a `glycomics` experiment, you get a `traitomics` experiment.
Instead of measuring individual glycans, you're looking at derived traits - higher-level summaries of your glycan data.

The variable information table is flexible - no mandatory columns. Common columns include:

- A `trait` column (from `derive_traits()`)
- A `motif` column (from `quantify_motifs()`)

### Traitproteomics

When you apply `derive_traits()` to a `glycoproteomics` experiment, you get a `traitproteomics` experiment.
Instead of tracking individual glycans at each protein site, you measure derived traits at each site.

Essential columns:

- `protein`: Protein UniProt accession (character string)
- `protein_site`: Glycosylation site position (integer)

Plus:

- A `trait` column (from `derive_traits()`)
- A `motif` column (from `quantify_motifs()`)

In `glycoproteomics`, different sites can have different glycan repertoires.
In `traitproteomics`, every site is scored on the same set of traits or motifs -
standardized metrics across glycosylation sites.

## Do You Need to Worry About Experiment Types?

Not really! Experiment types work behind the scenes. You'll encounter them in:

1. **Documentation** - References to specific experiment types
2. **Error messages** - Like "Expecting a `glycoproteomics` experiment, but got a `traitproteomics` experiment"

Different functions have different expectations:

- `glymotif::quantify_motifs()` requires `glycomics` or `glycoproteomics` data
- `glystats::gly_enrich_go()` expects `glycoproteomics` or `traitproteomics` experiments

**When to set experiment type:** Manually when creating an experiment object using `experiment()`.
Set the `exp_type` field to match your data structure.

**Warning:** Do not manually modify the `exp_type` field after creation.
This breaks the contract between your data and glycoverse functions.