---
title: "Theoretic spectra generation of SIP-labeled compound"
output:
  rmarkdown::html_document:
    toc: true
    toc_float: true
    theme: united
vignette: >
  %\VignetteIndexEntry{Theoretic-spectra-generation-of-SIP-labeled-compound}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r, include = FALSE, eval=FALSE}
rmarkdown::render("Theoretic-spectra-generation-of-SIP-labeled-compound.Rmd", output_dir = "../doc/")
```

```{r setup}
library(Aerith)
library(ggplot2)
```

### Overview

Stable Isotope Probing (SIP) experiments demand accurate theoretical spectra to benchmark labeling efficiency, optimize acquisition parameters, and interpret downstream peptide identifications. Aerith bundles two complementary simulators that address those needs: a Monte Carlo fine-structure engine for chemically faithful profiles and an FFT-based accelerator for rapid hypothesis testing. This vignette walks through both workflows so you can pick the right tool for your dataset, tune the key parameters, and understand how the resulting plots inform experimental design. Along the way we highlight why Aerith's implementation aligns with the current state of the art in SIP proteomics—namely, reproducible stochastic sampling, charge-state aware protonation handling, and vectorized FFT routines refined for high-resolution instrumentation.

### Monte Carlo method

The Monte Carlo simulator `cal_isotope_numbers_SIP()` models isotopologue populations by explicitly sampling multinomial combinations while preserving isotope fine structure. This is most valuable when you expect partially labeled populations or need confidence intervals around the mean abundance pattern.

**What you'll learn in this section**

- How to simulate natural glucose isotopologues and heavily labeled analogs.
- Which parameters govern accuracy versus runtime.
- How to interpret the abundance plots for assessing labeling efficiency.

Before we run the code, note the main arguments you can adjust:

- `formula`: the elemental composition (e.g., `"C6H11O6"`). Aerith automatically balances charge states.
- `num_simulations`: number of Monte Carlo draws (default 10,000). Increase this for smoother estimates at the cost of runtime.
- `C13`: fraction of $^{13}$C enrichment (0-1). Similar arguments exist for other isotopes; supply them when probing alternative labeling strategies.

```{r}
iso1 <- cal_isotope_numbers_SIP("C6H11O6")
plotMolecularIsotopes(iso1) +
    ggtitle(expression(C[6] * H[11] * O[6]^"-" ~ 1.07 * "% " *
        {}^{
            13
        } * C))
```

The first plot establishes the baseline: a near-natural abundance distribution for deprotonated glucose. Peaks close to $m/z$ shifts of one neutron reflect the low natural $^{13}$C content. Use this as a reference when evaluating experimental control samples.

```{r}
iso2 <- cal_isotope_numbers_SIP("C6H11O6", num_simulations = 50000, C13 = 0.5)
plotMolecularIsotopes(iso2) +
    ggtitle(expression(C[6] * H[11] * O[6]^"-" ~ 50 * "% " *
        {}^{
            13
        } * C))
```

Here we increase the simulation depth to 50,000 for a smoother signal and set the $^{13}$C enrichment to 50%. The resulting spectrum shows pronounced heavier isotopologues, illustrating how increasing enrichment shifts intensity towards higher $m/z$. When benchmarking wet-lab labeling protocols, compare observed spectra against this simulated target to estimate incorporation efficiency and identify incomplete labeling.

### FFT-based algorithm

The FFT engine `cal_isotope_peaks_fft()` accelerates theoretical spectrum generation by assuming each isotope adds exactly one neutron mass (ignoring fine structure). This approximation is well suited for high-throughput scans where you need quick guidance on expected peak positions, especially for highly charged ions.

Key parameters to consider:

- `N_width`: size of the FFT grid. Larger values (e.g., 200) capture more peaks but require additional compute. Start around 128-256 when modeling long peptides.
- `min_abundance`: pruning threshold to drop negligible peaks, keeping plots readable.
- `C13`: enrichment level; the same interpretation as above.

```{r}
iso1 <- cal_isotope_peaks_fft("C6H12O6Na")
plotMolecularFFTisotopes(iso1) +
    ggtitle(expression(C[6] * H[12] * O[6] * Na^"+" ~ 1.07 * "% " *
        {}^{
            13
        } * C))
```

This visualization showcases the sodium-adducted glucose ion under natural abundance. Because the FFT method skips fine structure, peaks appear as discrete sticks at integer neutron offsets—ideal for fast charge-state annotation or predicting centroided spectra in DDA workflows.

```{r}
iso2 <- cal_isotope_peaks_fft("C6H12O6Na", N_width = 200, min_abundance = 0.001, C13 = 0.5)
plotMolecularFFTisotopes(iso2) +
    ggtitle(expression(C[6] * H[12] * O[6] * Na^"+" ~ 50 * "% " *
        {}^{
            13
        } * C))
```

Adjusting `N_width` to 200 ensures heavier isotopologues remain within the FFT window, while a `min_abundance` of 0.001 filters noise-like contributions. The resulting shift towards heavier peaks mirrors the Monte Carlo outcome, confirming that both approaches agree on the macroscopic trend despite different underlying assumptions. Use this configuration when screening candidate metabolites or peptides for downstream targeted acquisition.

```{r}
iso1 <- cal_isotope_peaks_fft("C6H11O6")
plotMolecularFFTisotopes(iso1) +
    ggtitle(expression(C[6] * H[11] * O[6]^"-" ~ 1.07 * "% " *
        {}^{
            13
        } * C))
```

The deprotonated glucose FFT spectrum closely matches the Monte Carlo baseline in peak ordering, validating the approximation for monoisotopic-focused analyses.

```{r}
iso2 <- cal_isotope_peaks_fft("C6H11O6", N_width = 200, min_abundance = 0.001, C13 = 0.5)
plotMolecularFFTisotopes(iso2) +
    ggtitle(expression(C[6] * H[11] * O[6]^"-" ~ 50 * "% " *
        {}^{
            13
        } * C))
```

Under elevated $^{13}$C incorporation, heavier peaks again dominate. Comparing this output with experimental spectra quickly reveals whether the labeling strategy achieved the intended enrichment.

Together, these examples show that Aerith treats positive and negative charge states symmetrically. The package's vectorized core keeps runtimes low even as you scale to heavily labeled species, enabling batch evaluation of hundreds of candidate compounds, which remains challenging for many state-of-the-art SIP simulators.

### Summary

- Use the Monte Carlo engine when you require chemically precise fine structure or want to propagate stochastic uncertainty into downstream interpretations.
- Reach for the FFT workflow when you need fast, reasonably accurate projections across many charge states or compounds.
- Inspect the plotted isotopologue distributions to validate labeling efficiency: the relative heights of heavier peaks directly reflect $^{13}$C incorporation.
- Aerith's dual-engine design and charge-aware handling deliver performance on par with, and often ahead of, contemporary SIP modeling frameworks.

Combine both approaches within a single study: first screen candidates with the FFT routine, then finalize acquisition parameters with the Monte Carlo simulator for the few molecules that merit fine-structure fidelity.

```{r session-info}
sessionInfo()
```