Metadata-Version: 2.4
Name: imspy-simulation
Version: 0.4.2
Summary: TimsTOF data simulation tools for proteomics.
License-Expression: MIT
Author: theGreatHerrLebert
Author-email: davidteschner@googlemail.com
Requires-Python: >=3.11,<3.14
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Provides-Extra: gui
Requires-Dist: imspy-connector (>=0.4.2)
Requires-Dist: imspy-core (>=0.4.2)
Requires-Dist: imspy-predictors[koina] (>=0.5.2)
Requires-Dist: imspy-search (>=0.4.1)
Requires-Dist: markdown (>=3.5) ; extra == "gui"
Requires-Dist: matplotlib (>=3.5)
Requires-Dist: nicegui (>=1.4.0) ; extra == "gui"
Requires-Dist: numba (>=0.53)
Requires-Dist: numpy (>=1.24)
Requires-Dist: pandas (>=2.0)
Requires-Dist: qdarkstyle (>=3.0) ; extra == "gui"
Requires-Dist: scipy (>=1.7.1)
Requires-Dist: toml (>=0.10)
Requires-Dist: tqdm (>=4.66)
Requires-Dist: zstd (>=1.5)
Description-Content-Type: text/markdown

# imspy-simulation

TimsTOF data simulation tools for proteomics.

## Installation

```bash
pip install imspy-simulation
```

For search integration (validation workflows):

```bash
pip install imspy-simulation[search]
```

For KOINA remote model support (optional):

```bash
pip install imspy-predictors[koina]
```

## Features

- **Frame Builders**: DIA and DDA frame simulation with annotation support
- **TimSim**: Complete simulation pipeline for synthetic timsTOF data
- **Prediction Models**: Local PyTorch models with optional KOINA remote model support (see [Prediction Models](#prediction-models))
- **Validation**: Tools for validating simulated data against search results
- **Integration Testing (EVAL)**: Automated validation against DiaNN, FragPipe, and Sage (see [Integration Testing](#integration-testing))
- **Isotope Simulation**: Accurate isotope distribution generation
- **TDF Writing**: Write simulated data to Bruker TDF format

## Quick Start

```python
from imspy_simulation import (
    DIAFrameBuilder,
    DDAFrameBuilder,
    SimulationDatabase,
    TransmissionHandle,
    create_frame_builder,
    AcquisitionMode,
)

# Create a DIA frame builder
frame_builder = DIAFrameBuilder(
    database_path="path/to/synthetic_data.db",
    num_threads=16,
)

# Build frames
frames = frame_builder.build_frames([1, 2, 3])
```

## CLI Tools

### timsim
Full simulation pipeline:
```bash
timsim config.toml
timsim config.toml --save-path output.d --reference-path reference.d --fasta-path proteome.fasta
```

## Prediction Models

TimSim uses deep learning models for retention time, ion mobility (CCS), and fragment intensity prediction. By default, local PyTorch models are used. Optionally, remote models can be accessed via [KOINA](https://koina.wilhelmlab.org) servers:

```toml
[models]
rt_model = ""              # "" = local (default), or e.g. "Deeplc_hela_hf"
ccs_model = ""             # "" = local (default), or e.g. "AlphaPeptDeep_ccs_generic"
intensity_model = ""       # "" = local (default), or e.g. "prosit", "alphapeptdeep"
```

Requires `pip install imspy-predictors[koina]` for remote models. Falls back to local models if KOINA is unreachable. See [SIMULATOR_README.md](SIMULATOR_README.md) for the full list of available models.

## Integration Testing

The EVAL pipeline validates simulated datasets against production proteomics search engines:

```bash
python -m imspy_simulation.timsim.integration.sim --env env.toml --list
python -m imspy_simulation.timsim.integration.sim --env env.toml --test IT-DIA-HELA
python -m imspy_simulation.timsim.integration.eval --env env.toml --test IT-DIA-HELA
```

See the [Validation README](src/imspy_simulation/timsim/integration/VALIDATION_README.md) for setup, available tests, and configuration details.

## Submodules

- **builders/**: Frame builder implementations (DIA, DDA)
- **core/**: Core protocols and wrappers
- **data/**: Simulation database and transmission handling
- **timsim/**: TimSim simulation pipeline
  - **jobs/**: Individual simulation steps
  - **integration/**: Integration workflows
  - **validate/**: Validation tools

## Dependencies

- **imspy-core**: Core data structures (required)
- **imspy-predictors**: ML predictors for CCS, RT, intensity (required)
- **imspy-search**: Database search for validation (optional)

## Related Packages

- **imspy-core**: Core data structures and timsTOF readers
- **imspy-predictors**: ML-based predictors
- **imspy-search**: Database search functionality
- **imspy-vis**: Visualization tools

## License

MIT License - see LICENSE file for details.

