Merge pull request #373 from theGreatHerrLebert/feature/intensity-variation-timsim-dda

Feature/intensity variation timsim dda

Author: theGreatHerrLebert

imspy/imspy/simulation/resources/docs/documentation.md

@@ -1,130 +1,173 @@
 # TimSim: Proteomics Experiment Simulation on timsTOF
 
-Welcome to the `timsim` user manual. This document provides guidance on how to configure and run 
-proteomics simulations on a virtual timsTOF platform with `timsim`. Each section details a specific group of parameters, 
-explaining how they influence the simulation and how you can adjust them to model your experiment accurately.
+Welcome to the **`timsim` user manual**.  
+This guide explains how to configure and run proteomics simulations on a virtual timsTOF platform.  
+Each section details a parameter group, how it influences the simulation, and how to tune it to match your experiment.
 
 ---
 
 ## Table of Contents
 
-1. [Main Settings](#main-settings)
-2. [Peptide Digestion Settings](#peptide-digestion-settings)
-3. [Peptide Intensity Settings](#peptide-intensity-settings)
-4. [Isotopic Pattern Settings](#isotopic-pattern-settings)
-5. [Signal Distribution Settings](#signal-distribution-settings)
-6. [Noise Settings](#noise-settings)
-7. [Charge State Probabilities](#charge-state-probabilities)
-8. [Performance Settings](#performance-settings)
-9. [Console and Execution](#console-and-execution)
+1. [Main Settings](#main-settings)  
+2. [Peptide Digestion Settings](#peptide-digestion-settings)  
+3. [Peptide Intensity Settings](#peptide-intensity-settings)  
+4. [Isotopic Pattern Settings](#isotopic-pattern-settings)  
+5. [Signal Distribution Settings](#signal-distribution-settings)  
+6. [Noise Settings](#noise-settings)  
+7. [Property Variation Settings](#property-variation-settings)  
+8. [DDA Settings](#dda-settings)  
+9. [Charge State Probabilities](#charge-state-probabilities)  
+10. [Performance Settings](#performance-settings)  
+11. [Console and Execution](#console-and-execution)  
 
 ---
 
 ## Main Settings
 
 ### Parameters
-- **Save Path**: The directory where all simulation outputs, reports, and logs will be stored.
-- **Reference Dataset Path**: The path to a real timsTOF dataset that serves as the template for the simulation’s layout.
-- **FASTA File Path**: The location of the FASTA file containing protein sequences to be digested.
-- **Experiment Name**: A unique identifier for your simulation. This name is used to label output files and reports.
-- **Acquisition Type**: Choose the data acquisition method to simulate. Options include DIA, SYNCHRO, SLICE, and MIDIA.
+| Option | Description |
+|--------|-------------|
+| **Save Path** | Directory where all outputs, reports, and logs are stored. |
+| **Reference Dataset Path** | Path to a real timsTOF dataset that provides the template layout. |
+| **FASTA File Path** | Location of the FASTA file containing protein sequences. |
+| **Experiment Name** | Unique identifier used in output file names. |
+| **Acquisition Type** | Choose among **DIA**, **DDA**, **SYNCHRO**, **SLICE**, or **MIDIA**. |
 
 ### Options
-- **Use Reference Layout**: Use the layout from the reference dataset to mimic realistic instrument parameters.
-- **Load Reference into Memory**: Pre-load the reference dataset into RAM to speed up data access during simulation.
-- **Sample Peptides**: When enabled, peptides are randomly sampled from the digestion process.
-- **Generate Decoys**: Simulate decoy (inverted) peptides as well. Why would you want this? We still search an application!.
-- **Silent Mode**: Run the simulation with minimal console output.
-- **Apply Fragmentation to Ions**: Perform ion fragmentation during the simulation. This option is enabled by default.
-- **Proteome Mixture**: Simulate complex samples by incorporating a mixture of proteomes.
-- **Phospho Mode**: Enable phospho mode to generate a phospho-enriched dataset for testing phosphosite localization algorithms.
+* **Use Reference Layout** – Mimic realistic instrument parameters from the reference dataset.  
+* **Load Reference into Memory** – Pre-load dataset into RAM for faster access.  
+* **Sample Peptides** – Random sampling of peptides after digestion.  
+* **Generate Decoys** – Simulate inverted (decoy) peptides.  
+* **Silent Mode** – Minimal console output.  
+* **Apply Fragmentation to Ions** – Perform ion fragmentation (enabled by default).  
+* **Proteome Mixture** – Mix multiple proteomes for complex samples.  
+* **Phospho Mode** – Generate a phospho-enriched dataset.  
 
 ---
 
 ## Peptide Digestion Settings
 
-### Parameters
-- **Number of Sampled Peptides**: The total number of peptides generated from the in-silico digestion process.
-- **Missed Cleavages**: The maximum number of allowed missed cleavage sites during digestion.
-- **Minimum Peptide Length**: The shortest acceptable peptide length (in amino acids).
-- **Maximum Peptide Length**: The longest acceptable peptide length (in amino acids).
-- **Cleave At**: Specifies the amino acid residues at which the protein is cleaved (e.g., `"KR"` for trypsin).
-- **Restrict**: Specifies residues that inhibit cleavage (e.g., `"P"` to prevent cleavage immediately after a cleavage site).
-- **Amino Acid Modifications**: The path to a TOML file that defines fixed and variable modifications applied during digestion.
+| Parameter | Description |
+|-----------|-------------|
+| **Number of Sampled Peptides** | Total peptides drawn from the in-silico digest. |
+| **Missed Cleavages** | Allowed missed cleavage sites. |
+| **Minimum Peptide Length** | Shortest peptide length (aa). |
+| **Maximum Peptide Length** | Longest peptide length (aa). |
+| **Cleave At** | Cleavage residues (e.g. `KR`). |
+| **Restrict** | Residues that block cleavage (e.g. `P`). |
+| **Amino Acid Modifications** | Path to TOML file with fixed/variable mods. |
+| **Sample Occurrences Randomly** | Toggle random sampling of peptide occurrences. |
 
 ---
 
 ## Peptide Intensity Settings
 
-### Parameters
-Peptide intensity settings are currently simulated with a fixed procedure. If you want to vary the intensity of peptides, 
-connect to a simulation database and adjust the intensity values there directly. Afterward you can re-run the simulation
-using the adapted database as reference.
+*Currently simulated with a fixed procedure.*  
+For custom intensity profiles, edit the simulation database directly and rerun `timsim` with that database as reference.
+
+---
 
 ## Isotopic Pattern Settings
 
-### Parameters
-- **Maximum Number of Isotopes**: The number of isotopic peaks to simulate for each peptide.
-- **Minimum Isotope Intensity**: The threshold intensity below which isotopic peaks are not included.
-- **Centroid Isotopes**: When enabled, the simulation averages peak positions to generate a simplified isotopic pattern. This parameter is enabled by default.
+| Parameter | Description |
+|-----------|-------------|
+| **Maximum Number of Isotopes** | How many isotopic peaks to simulate. |
+| **Minimum Isotope Intensity** | Threshold below which isotopes are skipped. |
+| **Centroid Isotopes** | Average peaks to simplified centroids (enabled by default). |
 
 ---
 
 ## Signal Distribution Settings
 
-### Parameters
-- **Gradient Length**: The total duration of the simulated chromatographic gradient (in seconds).
-- **Mean Std RT**: The average standard deviation of the retention time (RT) distribution, which affects peak widths.
-- **Variance Std RT**: The variance in the RT standard deviation, influencing the variability of the collection of all peak widths.
-- **Mean Skewness**: The average skewness of the RT distribution, which determines the asymmetry of peaks.
-- **Variance Skewness**: The variance in the skewness, influencing the variability of the asymmetry of all peaks.
-- **Z-Score**: Total amount of signal intensity in the chromatogram that needs to be covered before the numerical integration stops.
-- **Target Percentile**: The percentile used to select high-density regions within the RT distribution.
-- **Sampling Step Size**: The resolution for sampling the RT distribution; smaller values yield finer detail but require more computational resources.
+| Parameter | Description |
+|-----------|-------------|
+| **Gradient Length** | Total chromatographic gradient length (s). |
+| **Mean Std RT / Variance Std RT** | Mean and variance of RT peak widths. |
+| **Mean Skewness / Variance Skewness** | Mean and variance of RT peak asymmetry. |
+| **Z-Score** | Fraction of total intensity to cover before integration stops. |
+| **Target Percentile** | Percentile that defines high-density RT regions. |
+| **Sampling Step Size** | RT sampling resolution; smaller = finer detail, slower run. |
+
 ---
 
 ## Noise Settings
 
-### Parameters
-- **Add Noise to Signals**: Enable this option to introduce random noise into signal intensities, mimicking experimental variability.
-- **Add Precursor M/Z Noise**: Adds variability to precursor m/z values to simulate instrument measurement precision.
-- **Precursor Noise PPM**: Specifies the noise level (in parts per million) for precursor m/z values.
-- **Add Fragment M/Z Noise**: Adds noise to fragment m/z values to simulate spectral variation.
-- **Fragment Noise PPM**: Specifies the noise level (in parts per million) for fragment m/z values.
-- **Use Uniform Distribution for M/Z Noise**: When enabled, m/z noise is sampled from a uniform distribution instead of a Gaussian.
-- **Add Real Data Noise**: Incorporate noise profiles derived from real experimental data.
-- **Reference Noise Intensity Max**: The maximum intensity threshold for noise derived from reference data.
-- **Fragment Downsample Factor**: Sets the relative amount fragment ions are downsampled. Take probability is inversely proportional to their intensity.
+| Parameter | Description |
+|-----------|-------------|
+| **Add Noise to Signals** | Inject random intensity noise. |
+| **Add Precursor M/Z Noise** | Variability in precursor m/z values. |
+| **Precursor Noise PPM** | Noise level for precursors (ppm). |
+| **Add Fragment M/Z Noise** | Variability in fragment m/z values. |
+| **Fragment Noise PPM** | Noise level for fragments (ppm). |
+| **Use Uniform Distribution for M/Z Noise** | Uniform instead of Gaussian noise. |
+| **Add Real Data Noise** | Use noise profiles from real datasets. |
+| **Reference Noise Intensity Max** | Max intensity for reference-derived noise. |
+| **Fragment Downsample Factor** | Probability to keep fragments inversely ∝ intensity. |
+| **Add Noise to Frame / Scan Abundance** | Toggle extra abundance noise. |
+
+---
+
+## Property Variation Settings
+
+Feature-level Gaussian jitter applied *after* deterministic peak shaping and noise modeling. Will only be applied
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| **RT Variation σ (s)** | `15` | Std-dev of retention-time apex jitter. |
+| **Ion-Mobility Variation σ (1/K0)** | `0.008` | Std-dev of ion-mobility jitter. |
+| **Intensity Variation σ (relative)** | `0.02` | Relative std-dev applied multiplicatively (≈ ±2 %). |
+
+Set all three to `0` to disable feature jitter completely.
+
+---
+
+## DDA Settings
+
+*Only active when **Acquisition Type** is set to **DDA**.*
+
+| Parameter | Default | Description                                                                                                   |
+|-----------|---------|---------------------------------------------------------------------------------------------------------------|
+| **Precursors Every** | `7` | Distance between MS¹  frames in one cycle (7 = 1 precursor frame followed by 6 fragment frames).              |
+| **Precursor Intensity Threshold** | `500` | Minimum MS¹ intensity for eligibility.                                                                        |
+| **Max Precursors** | `7` | Hard cap on selected precursors per fragment frame.                                                           |
+| **Exclusion Width** | `25` | Number of frames the re-acquisition of the same mz range that had been selected should not be selected again. |
+| **Selection Mode** | `topN` | `topN` (by intensity) or `random`.                                                                            |
+
+> *Features in precursor space are currently not detected from raw-data but taken from the simulation tables, and therefore feature detection is de-facto perfect. 
+> For a more realistic procedure, we are planning to include a feature detection step in the future.*
 
 ---
 
 ## Charge State Probabilities
 
-### Parameters
-- **Binomial Charge Model**: When enabled, the charge state distribution is modeled using a binomial distribution. Only if enabled, the following parameters are considered.
-- **Probability of Charge**: The likelihood that a peptide will adopt a particular charge state.
-- **Minimum Charge Contribution**: The minimum relative contribution required for peptides with a given charge state to be considered in the simulation.
-- **Maximum Charge**: The highest charge state to simulate for peptides.
+| Parameter | Description |
+|-----------|-------------|
+| **Binomial Charge Model** | Uses binomial distribution for charge states. |
+| **Probability of Charge** | Success probability in binomial model. |
+| **Minimum Charge Contribution** | Min relative contribution for a charge state. |
+| **Maximum Charge** | Highest simulated charge state. |
+| **Normalize Charge States** | Ensure kept charge states sum to 1. |
 
 ---
 
 ## Performance Settings
 
-### Parameters
-- **Number of Threads**: The number of parallel threads used for the simulation. Use `-1` to auto-detect all available cores.
-- **Batch Size**: The number of data points processed in each computational batch.
+| Parameter | Description                                   |
+|-----------|-----------------------------------------------|
+| **Number of Threads** | Parallel threads (`-1` = all cores).          |
+| **Batch Size** | Number of TimsFrames to be build in parallel. |
 
 ---
 
 ## Console and Execution (GUI Mode)
 
-### Features
-- **Console Output**: Displays real-time logs, warnings, and progress updates during the simulation.
-- **Run Button**: Initiates the simulation with the current configuration settings.
-- **Cancel Button**: Provides the ability to terminate a running simulation.
-- **Save Config**: Allows you to save your current settings to a TOML file for future use.
-- **Load Config**: Load a previously saved TOML configuration file to quickly restore your simulation settings.
+* **Console Output** – Real-time logs and progress.  
+* **Run Button** – Starts the simulation with current settings.  
+* **Cancel Button** – Terminates a running simulation.  
+* **Save Config** – Store current settings as a TOML file.  
+* **Load Config** – Restore settings from a saved TOML file.  
 
 ---
 
-For additional assistance or troubleshooting, please refer to the tooltips within the GUI application or visit our [GitHub repository](https://github.com/theGreatHerrLebert/rustims) for support.
+For help or troubleshooting, hover over the in-app tool-tips or visit our  
+[GitHub repository](https://github.com/theGreatHerrLebert/rustims).