Metadata-Version: 2.4
Name: metasheet-guard
Version: 0.1.0
Summary: Experimental-design-aware quality control for sequencing analysis sample sheets.
Author: MetaSheet-Guard contributors
License-Expression: MIT
Project-URL: Homepage, https://qchiujunhao.github.io/metasheet-guard/
Project-URL: Documentation, https://qchiujunhao.github.io/metasheet-guard/
Project-URL: Repository, https://github.com/qchiujunhao/metasheet-guard
Project-URL: Issues, https://github.com/qchiujunhao/metasheet-guard/issues
Keywords: bioinformatics,metadata,sample sheet,sequencing,quality control
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jinja2>=3.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: pre-commit>=3.5; extra == "dev"
Requires-Dist: mkdocs-material>=9.5; extra == "dev"
Dynamic: license-file

# MetaSheet-Guard

[Documentation website](https://qchiujunhao.github.io/metasheet-guard/) |
[Repository](https://github.com/qchiujunhao/metasheet-guard)

MetaSheet-Guard performs experimental-design-aware quality control for sequencing
analysis sample sheets. It targets the analysis-preparation stage: after FASTQ
generation or public metadata collection, but before running workflows such as
Nextflow, Snakemake, nf-core/rnaseq, or custom RNA-seq pipelines.

The current package includes CSV/TSV reading, bundled YAML schemas, validation,
repair provenance, workflow export, JSON/HTML reports, and a
`metasheet-guard` CLI.

## Scope

MetaSheet-Guard is being built to model relationships between biological
samples, sequencing runs, lanes, FASTQ files, replicates, conditions, batches,
and downstream workflow requirements. The current release is intentionally small
and currently supports these first-pass capabilities:

- required columns
- duplicate column names
- schema-defined column aliases
- empty values in required columns
- sample ID and metadata consistency checks
- FASTQ path, extension, gzip, pair, and duplication checks
- sample/run/lane relationship checks
- batch-condition and related design-risk checks
- safe repair with `changes.json` provenance
- nf-core/rnaseq, Snakemake, canonical CSV, and DESeq2 design exports
- bundled `generic-ngs` and `bulk-rnaseq` schemas

## Non-goals

MetaSheet-Guard is not an RNA-seq aligner, quantifier, differential expression
tool, SRA downloader, nf-core/fetchngs replacement, nf-schema replacement,
Illumina BCL Convert or bcl2fastq SampleSheet validator, single-cell object
validator, spatial image validator, or generic CSV validation framework.

## Installation

```bash
pip install -e ".[dev]"
```

## Quickstart

Validate a broken bulk RNA-seq sample sheet and write a JSON report:

```bash
metasheet-guard check examples/broken/missing_required_column.csv \
  --schema bulk-rnaseq \
  --json report.json
```

The command exits with status code `1` when blocking validation errors are found.
For the example above, `report.json` contains a `REQUIRED_COLUMN_MISSING` issue
because the `bulk-rnaseq` schema requires a `condition` column.

Validate a minimal valid example:

```bash
metasheet-guard check examples/valid/bulk_rnaseq_paired.csv \
  --schema bulk-rnaseq
```

Repair safe metadata issues and record provenance:

```bash
metasheet-guard repair examples/broken/condition_case_mixed.csv \
  --schema bulk-rnaseq \
  --out clean.csv \
  --changes changes.json
```

Only safe repairs are implemented. Suggested/inference-based repairs are
reserved for later milestones and currently fail clearly if requested.

Export a cleaned sheet:

```bash
metasheet-guard export examples/valid/bulk_rnaseq_paired.csv \
  --target nf-core-rnaseq \
  --out nfcore_samplesheet.csv
```

## Python API

```python
from metasheet_guard import read_sheet, validate

sheet = read_sheet("examples/broken/missing_required_column.csv")
result = validate(sheet, schema="bulk-rnaseq")

for issue in result.issues:
    print(issue.severity, issue.code, issue.message)
```

## Development

Run tests and linting:

```bash
pytest
ruff check .
```

The project uses `src/` packaging, Typer for the command-line interface, PyYAML
for schemas, pytest for tests, and Ruff for linting.
