metasheet-guard 0.1.0__tar.gz

metasheet_guard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MetaSheet-Guard contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

metasheet_guard-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+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.

metasheet_guard-0.1.0/README.md

@@ -0,0 +1,110 @@
+# 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.

metasheet_guard-0.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "metasheet-guard"
+version = "0.1.0"
+description = "Experimental-design-aware quality control for sequencing analysis sample sheets."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "MetaSheet-Guard contributors" }
+]
+keywords = [
+  "bioinformatics",
+  "metadata",
+  "sample sheet",
+  "sequencing",
+  "quality control"
+]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Bio-Informatics"
+]
+dependencies = [
+  "jinja2>=3.1",
+  "pyyaml>=6.0",
+  "rich>=13.0",
+  "typer>=0.12"
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "ruff>=0.6.0",
+  "pre-commit>=3.5",
+  "mkdocs-material>=9.5"
+]
+
+[project.scripts]
+metasheet-guard = "metasheet_guard.cli:app"
+
+[project.urls]
+Homepage = "https://qchiujunhao.github.io/metasheet-guard/"
+Documentation = "https://qchiujunhao.github.io/metasheet-guard/"
+Repository = "https://github.com/qchiujunhao/metasheet-guard"
+Issues = "https://github.com/qchiujunhao/metasheet-guard/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+metasheet_guard = ["schemas/*.yaml", "report/templates/*.j2"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"

metasheet_guard-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

metasheet_guard-0.1.0/src/metasheet_guard/__init__.py

@@ -0,0 +1,84 @@
+"""Public API for MetaSheet-Guard."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from metasheet_guard.export import (
+    export_canonical,
+    export_deseq2_design,
+    export_nfcore_rnaseq,
+    export_snakemake,
+)
+from metasheet_guard.io.csv import SheetTable, read_table
+from metasheet_guard.repair import repair_sheet
+from metasheet_guard.report.json import write_json_report
+from metasheet_guard.result import ValidationResult
+from metasheet_guard.schema.loader import Schema, load_schema
+from metasheet_guard.validators import run_validators
+
+__version__ = "0.1.0"
+
+
+def read_sheet(path: str | Path) -> SheetTable:
+    """Read a CSV or TSV sample sheet into a table object."""
+
+    return read_table(path)
+
+
+def validate(
+    sheet: SheetTable | str | Path,
+    schema: Schema | str | Path = "generic-ngs",
+    root: str | Path | None = None,
+    include_export_readiness: bool = True,
+    **_: Any,
+) -> ValidationResult:
+    """Validate a sample sheet with the currently implemented rule set."""
+
+    table = read_table(sheet) if isinstance(sheet, str | Path) else sheet
+    schema_obj = load_schema(schema) if not isinstance(schema, Schema) else schema
+    issues, readiness = run_validators(
+        table,
+        schema_obj,
+        root=root,
+        include_export_readiness=include_export_readiness,
+    )
+    return ValidationResult.from_issues(
+        issues=issues,
+        row_count=len(table.rows),
+        column_count=len(table.headers),
+        export_readiness=readiness,
+    )
+
+
+def export_sheet(
+    sheet: SheetTable | str | Path,
+    target: str,
+    output: str | Path,
+) -> None:
+    """Export a sample sheet to a supported workflow target."""
+
+    if target == "nf-core-rnaseq":
+        export_nfcore_rnaseq(sheet, output)
+    elif target == "deseq2-design":
+        export_deseq2_design(sheet, output)
+    elif target == "snakemake":
+        export_snakemake(sheet, output)
+    elif target in {"canonical", "generic"}:
+        export_canonical(sheet, output)
+    else:
+        raise ValueError(f"Unsupported export target: {target}")
+
+
+__all__ = [
+    "Schema",
+    "SheetTable",
+    "ValidationResult",
+    "__version__",
+    "read_sheet",
+    "export_sheet",
+    "repair_sheet",
+    "validate",
+    "write_json_report",
+]

metasheet_guard-0.1.0/src/metasheet_guard/cli.py

@@ -0,0 +1,237 @@
+"""Command-line interface for MetaSheet-Guard."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from metasheet_guard import __version__, export_sheet, validate
+from metasheet_guard.io.csv import read_table
+from metasheet_guard.io.sra import import_sra_runinfo
+from metasheet_guard.repair import repair_sheet
+from metasheet_guard.report.html import write_html_report
+from metasheet_guard.report.json import write_json_report
+from metasheet_guard.schema.loader import load_schema
+
+app = typer.Typer(
+    add_completion=False,
+    help=(
+        "Experimental-design-aware quality control for sequencing analysis "
+        "sample sheets."
+    ),
+    no_args_is_help=True,
+)
+console = Console()
+schema_app = typer.Typer(help="Inspect bundled schemas.", no_args_is_help=True)
+import_app = typer.Typer(help="Import external metadata tables.", no_args_is_help=True)
+demo_app = typer.Typer(help="Create and run small local demos.", no_args_is_help=True)
+app.add_typer(schema_app, name="schema")
+app.add_typer(import_app, name="import")
+app.add_typer(demo_app, name="demo")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"metasheet-guard {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            callback=_version_callback,
+            help="Show the installed MetaSheet-Guard version and exit.",
+            is_eager=True,
+        ),
+    ] = False,
+) -> None:
+    """MetaSheet-Guard command group."""
+
+
+@app.command()
+def check(
+    path: Annotated[
+        Path,
+        typer.Argument(exists=True, file_okay=True, dir_okay=False, readable=True),
+    ],
+    schema: Annotated[
+        str,
+        typer.Option(
+            "--schema",
+            "-s",
+            help="Bundled schema name or path to a YAML schema file.",
+        ),
+    ] = "generic-ngs",
+    root: Annotated[
+        Path | None,
+        typer.Option(
+            "--root",
+            help=(
+                "FASTQ root directory. Accepted for CLI compatibility; "
+                "unused in Milestone 1."
+            ),
+        ),
+    ] = None,
+    json_path: Annotated[
+        Path | None,
+        typer.Option(
+            "--json",
+            help="Write a machine-readable JSON validation report.",
+        ),
+    ] = None,
+    html_path: Annotated[
+        Path | None,
+        typer.Option(
+            "--html",
+            help="Write a static HTML validation report.",
+        ),
+    ] = None,
+) -> None:
+    """Validate a CSV or TSV sequencing analysis sample sheet."""
+
+    schema_obj = load_schema(schema)
+    table = read_table(path)
+    result = validate(table, schema=schema_obj, root=root)
+
+    if json_path is not None:
+        write_json_report(result, json_path)
+    if html_path is not None:
+        write_html_report(result, html_path)
+
+    console.print(
+        "[bold]Validation complete[/bold]: "
+        f"{result.summary['errors']} error(s), "
+        f"{result.summary['warnings']} warning(s), "
+        f"{result.summary['infos']} info issue(s)."
+    )
+
+    if result.has_blocking_errors:
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def repair(
+    path: Annotated[
+        Path,
+        typer.Argument(exists=True, file_okay=True, dir_okay=False, readable=True),
+    ],
+    schema: Annotated[
+        str,
+        typer.Option("--schema", "-s", help="Bundled schema name or YAML schema path."),
+    ] = "generic-ngs",
+    out: Annotated[
+        Path, typer.Option("--out", help="Repaired output CSV path.")
+    ] = Path("clean.csv"),
+    changes: Annotated[
+        Path,
+        typer.Option("--changes", help="Repair provenance JSON path."),
+    ] = Path("changes.json"),
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run", help="Report repairs without changing output rows."),
+    ] = False,
+    safe_only: Annotated[
+        bool,
+        typer.Option(
+            "--safe-only/--allow-suggestions", help="Apply only safe repairs."
+        ),
+    ] = True,
+) -> None:
+    """Apply conservative safe repairs and write changes.json provenance."""
+
+    try:
+        result = repair_sheet(path, schema=schema, safe_only=safe_only, dry_run=dry_run)
+    except ValueError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+    result.to_csv(out)
+    result.write_changes(changes)
+    console.print(
+        f"Wrote {out} and {changes} with {len(result.changes)} recorded change(s)."
+    )
+
+
+@app.command()
+def export(
+    path: Annotated[
+        Path,
+        typer.Argument(exists=True, file_okay=True, dir_okay=False, readable=True),
+    ],
+    target: Annotated[
+        str,
+        typer.Option(
+            "--target",
+            help="Export target: nf-core-rnaseq, deseq2-design, snakemake, canonical.",
+        ),
+    ],
+    out: Annotated[Path, typer.Option("--out", help="Output path.")],
+) -> None:
+    """Export a cleaned sample sheet for a downstream workflow."""
+
+    export_sheet(path, target=target, output=out)
+    console.print(f"Wrote {target} export to {out}.")
+
+
+@import_app.command("sra-runinfo")
+def import_sra_runinfo_command(
+    path: Annotated[
+        Path,
+        typer.Argument(exists=True, file_okay=True, dir_okay=False, readable=True),
+    ],
+    out: Annotated[Path, typer.Option("--out", help="Canonical CSV output path.")],
+    schema: Annotated[
+        str,
+        typer.Option(
+            "--schema", help="Accepted for command symmetry; currently unused."
+        ),
+    ] = "generic-ngs",
+) -> None:
+    """Convert an SRA-like RunInfo CSV into a canonical sample sheet."""
+
+    del schema
+    import_sra_runinfo(path, out)
+    console.print(f"Wrote canonical sample sheet to {out}.")
+
+
+@schema_app.command("show")
+def schema_show(name: str) -> None:
+    """Print a bundled or user-provided schema as loaded YAML-like data."""
+
+    schema = load_schema(name)
+    console.print(schema)
+
+
+@schema_app.command("list")
+def schema_list() -> None:
+    """List bundled schemas."""
+
+    console.print("generic-ngs")
+    console.print("bulk-rnaseq")
+
+
+@demo_app.command("init")
+def demo_init() -> None:
+    """Show where bundled examples live."""
+
+    console.print("Use examples/valid and examples/broken in this repository.")
+
+
+@demo_app.command("run")
+def demo_run() -> None:
+    """Run the missing-required-column demo."""
+
+    demo_path = Path("examples/broken/missing_required_column.csv")
+    report_path = Path("report.json")
+    schema_obj = load_schema("bulk-rnaseq")
+    table = read_table(demo_path)
+    result = validate(table, schema=schema_obj)
+    write_json_report(result, report_path)
+    console.print(f"Wrote demo report to {report_path}.")
+    if result.has_blocking_errors:
+        raise typer.Exit(code=1)

metasheet_guard-0.1.0/src/metasheet_guard/export/__init__.py

@@ -0,0 +1,13 @@
+"""Workflow exporters."""
+
+from metasheet_guard.export.deseq2 import export_deseq2_design
+from metasheet_guard.export.generic import export_canonical
+from metasheet_guard.export.nfcore_rnaseq import export_nfcore_rnaseq
+from metasheet_guard.export.snakemake import export_snakemake
+
+__all__ = [
+    "export_canonical",
+    "export_deseq2_design",
+    "export_nfcore_rnaseq",
+    "export_snakemake",
+]