Metadata-Version: 2.5
Name: ms-qg
Version: 0.12.1
Summary: Queue generation system for mass spectrometry instruments. Generates sample queues with QC injections for XCalibur, Chronos, and Hystar, with B-Fabric LIMS integration for sample loading and workunit upload.
Project-URL: Homepage, https://github.com/fgcz/qg
Project-URL: Documentation, https://fgcz.github.io/qg/
Project-URL: Repository, https://github.com/fgcz/qg
Project-URL: Issues, https://github.com/fgcz/qg/issues
Project-URL: Changelog, https://github.com/fgcz/qg/blob/main/CHANGELOG.md
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: acquisition queue,mass spectrometry,metabolomics,proteomics,quality control,randomization,worklist
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.13
Requires-Dist: cyclopts>=4.4.4
Requires-Dist: fastexcel>=0.11
Requires-Dist: loguru>=0.7.0
Requires-Dist: marimo>=0.23.9
Requires-Dist: plotly>=6.8.0
Requires-Dist: polars
Requires-Dist: pyarrow>=22.0.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: tomli-w>=1.0.0
Provides-Extra: bfabric
Requires-Dist: asgiref>=3.8; extra == 'bfabric'
Requires-Dist: bfabric-asgi-auth; extra == 'bfabric'
Requires-Dist: bfabric-rest-proxy; extra == 'bfabric'
Requires-Dist: bfabric>=1.16.1; extra == 'bfabric'
Requires-Dist: fastapi>=0.128.0; extra == 'bfabric'
Requires-Dist: pydantic-settings>=2.14.2; extra == 'bfabric'
Requires-Dist: python-gitlab>=5.0.0; extra == 'bfabric'
Requires-Dist: pyyaml; extra == 'bfabric'
Requires-Dist: starlette>=0.50.0; extra == 'bfabric'
Requires-Dist: uvicorn; extra == 'bfabric'
Description-Content-Type: text/markdown

# Queue Generation System

[![DOI](https://zenodo.org/badge/1280336047.svg)](https://doi.org/10.5281/zenodo.21040573)
[![bioRxiv](https://img.shields.io/badge/bioRxiv-10.64898%2F2026.07.03.736300-brightgreen)](https://doi.org/10.64898/2026.07.03.736300)

Generate sample queues with QC injections for mass spectrometry instruments (XCalibur, Chronos, Hystar).

## ▶ Try the live demos

**[Launch the queue generator in your browser →](https://apps-dev.bfabric.org/queue-gen-local/)**

**[Launch the config editor in your browser →](https://apps-dev.bfabric.org/queue-gen-editor-local/)**

No install, no account. The queue generator demo lets you upload a CSV/XLSX
sample table (or load a bundled example), pick the instrument / sampler /
pattern, preview the queue, and download it. The config editor demo lets you
inspect, edit, and validate the configuration in the browser.

---

`qg` is a standalone tool: upload a CSV/XLSX sample table in the GUI (or pass a
parameters JSON to the CLI), configure the queue, preview, and download — no
FGCZ/B-Fabric required. It also runs as the FGCZ **B-Fabric portal** app (LIMS order
browsing + workunit upload); see the [B-Fabric guide](docs/bfabric.md).

📖 **Documentation:** [**fgcz.github.io/qg**](https://fgcz.github.io/qg/) — local-app
and editor guides, the queue-generation algorithm, and the configuration reference.

## Installation

```bash
pip install ms-qg              # as a dependency
uv sync --no-group portal      # for development in this repo, B-Fabric-free
```

Requires Python 3.13 or newer.

This installs the local app plus the `qg`, `qg-assign-positions`, and `qg-validate`
CLIs. The core install has no
`bfabric`, `fastapi`, `starlette`, or `python-gitlab` dependency — `import qg`, the
local app, and the CLIs all work without them. For the FGCZ B-Fabric portal,
install the `ms-qg[bfabric]` extra — see the [B-Fabric guide](docs/bfabric.md).

## Quick Start

### Local app — no B-Fabric

```bash
make app-local
# or: qg-app-local
# or: uv run marimo run src/qg/apps/queue_app_local.py
```

Upload a sample table — ready-made examples (vial/plate, single- and
multi-project) live in [`docs/examples/`](docs/examples/) — pick the
instrument / sampler / pattern, preview, and download the queue plus its
parameters JSON. See [`docs/users/local_app.md`](docs/users/local_app.md).

### CLI

```bash
uv run qg config.json -o queue.csv   # generate a queue from a parameters JSON (stdout if no -o)
uv run qg-assign-positions config.json -o positioned.json  # assign/validate physical positions only
uv run qg-validate                   # validate the config files
```

> **Running at FGCZ?** The B-Fabric portal app, its `ms-qg[bfabric]` install, project
> cache seeding, and deployment all live in the [B-Fabric guide](docs/bfabric.md).

## Supported Configurations

### Technologies
- Proteomics
- Metabolomics (with pos/neg polarity)
- Lipidomics (with pos/neg polarity)

### Samplers
| Sampler | Instruments |
|---------|-------------|
| Vanquish | ASTRAL_1, EXPLORIS_3/4/5, QEXACTIVEHF_2, QUANTIVA_1 |
| MClass | ASCEND_1, EXPLORIS_1/2, LUMOS_2, QEXACTIVE_1 |
| Evosep | ASTRAL_1, EXPLORIS_1/2, TIMSTOF_1, TIMSTOFFLEX_1 |

### Output Formats
- XCalibur (`.csv`, `xcalibur` / `xcalibur_sii`)
- Chronos (`.csv`)
- Hystar (`.xml`)

## Queue Parameters JSON

Queue generation takes a JSON file with a `parameters` object (instrument,
sampler, output format, pattern, …) and a nested `queue` object (`batches` plus
`samples`, or `plates`/`cells` for plate input). The canonical schema and
field-by-field reference live in one place:
**[docs/reference/config.md](docs/reference/config.md#queue-parameters-json-input)**.

## Example Output

```csv
File Name,Path,Instrument Method,Position,Inj Vol,Sample Type,Sample Name
20260112_001_C37180_autoQC02dia,D:\Data2San\p37180\Proteomics\ASTRAL_1\cpanse_20260112,C:\Methods\Proteomics\ASTRAL_1\DIA_60min.meth,B:F8,1.0,QC,autoQC02dia
20260112_002_C37180_autoQC01,D:\Data2San\p37180\Proteomics\ASTRAL_1\cpanse_20260112,C:\Methods\Proteomics\ASTRAL_1\DIA_60min.meth,B:F9,2.0,QC,autoQC01
20260112_003_C37180_S852285_HeLa_10ng,D:\Data2San\p37180\Proteomics\ASTRAL_1\cpanse_20260112,C:\Methods\Proteomics\ASTRAL_1\DIA_60min.meth,Y:A1,2.0,Unknown,HeLa_10ng
```

## Configuration Files

Static config lives in `qg_configs/`, grouped under
`core/{structure,position,formatting,methods}/` and `ui/`. The per-file
reference (purpose, columns, examples) is maintained in one place:
**[docs/reference/config.md](docs/reference/config.md)**.
