parseet 0.2.0__tar.gz

parseet-0.2.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.1
+Name: parseet
+Version: 0.2.0
+Summary: This package is used to parse ms samplesheet for further analyses.
+Keywords: samplesheet,parser,data analyses,mass spectrometry,msdial
+Author-Email: Matteo Miotto <miotsdata@gmail.com>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: <3.13,>=3.12
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: openpyxl>=3.1.5
+Provides-Extra: gui
+Requires-Dist: pyside6>=6.11.1; extra == "gui"
+Description-Content-Type: text/markdown
+
+# BULK METABOLOMICS SAMPLESHEET
+
+This folder contains the files necessary for the samplesheet of LC-MS and spatial metabolomics.
+Samplesheet template (LC-MS_metabolomics_samplesheet.xlsx or spatial_metabolomics_samplesheet.xlsx) should be given to clients to be compiled. Once received back, it should be tested with the parser (LC-MS_parse_samplesheet.py or spatial_parse_samplesheet.py).
+
+## Samplesheet template
+Samplesheet templates contains 3 sheets:
+
+- input: the one the user should fill. It contains two sections, one with user info and the other with samples metadata.
+- example_ok: an example of a good samplesheet
+- example_fail: an example of a problematic samplesheet
+
+## Parser
+The parser will check the samplesheet for its correct compilation and raises warnings and/or errors if any.
+If no errors are found, the samples metadata section is saved as a csv file (specified as -o). Warnings also prevent file to be saved, but this can be overruled by --ignore-warnings.
+
+## Test
+In test folder, 3 test samplesheet for each technology are found:
+
+- test_error.xlsx: a test samplesheet with errrors
+- test_ok.xlsx: a test samplesheet correctly compiled
+- test_warning.xlsx: a test samplesheet with warnings
+
+Several test should be run after changind any file:
+
+- `python LC-MS_parse_samplesheet.py` (this should result in an error for missing input and output) 
+- `python LC-MS_parse_samplesheet.py -i test_files/LC-MS_test_ok.xlsx -o test.csv --dry-run` (this should be ok, with no errors nor warnings, but no file should be saved due to --dry-run)
+- `python LC-MS_parse_samplesheet.py -i test_files/LC-MS_test_ok.xlsx -o test.csv` (this should be ok, with also test.csv file saved)
+- `python LC-MS_parse_samplesheet.py -i test_files/LC-MS_test_error.xlsx -o test.csv` (this should raise errors and no test.csv file should be created)
+- `python LC-MS_parse_samplesheet.py -i test_files/LC-MS_test_warning.xlsx -o test.csv` (this should raise warnings and no test.csv file should be created)
+- `python LC-MS_parse_samplesheet.py` (this should result in an error for missing input and output) 
+- `python spatial_parse_samplesheet.py -i test_files/spatial_test_ok.xlsx -o test.csv --dry-run` (this should be ok, with no errors nor warnings, but no file should be saved due to --dry-run)
+- `python LC-MS_parse_samplesheet.py -i test_files/LC-MS_test_ok_timecourse.xlsx -o test.csv` (this should be ok, with also test.csv file saved)
+- `python spatial_parse_samplesheet.py -i test_files/spatial_test_ok.xlsx -o test.csv` (this should be ok, with also test.csv file saved)
+- `python spatial_parse_samplesheet.py -i test_files/spatial_test_error.xlsx -o test.csv` (this should raise errors and no test.csv file should be created)
+- `python spatial_parse_samplesheet.py -i test_files/spatial_test_warning.xlsx -o test.csv` (this should raise warnings and no test.csv file should be created)
+- `python spatial_parse_samplesheet.py -i test_files/spatial_test_warning.xlsx -o test.csv` --ignore-warnings (this should raise warnings, but test.csv file should be created)
+- `python spatial_parse_samplesheet.py -i test_files/spatial_test_warning.xlsx -o test.csv` --ignore-warnings (this should raise warnings, but test.csv file should be created)
+

parseet-0.2.0/README.md

@@ -0,0 +1,39 @@
+# BULK METABOLOMICS SAMPLESHEET
+
+This folder contains the files necessary for the samplesheet of LC-MS and spatial metabolomics.
+Samplesheet template (LC-MS_metabolomics_samplesheet.xlsx or spatial_metabolomics_samplesheet.xlsx) should be given to clients to be compiled. Once received back, it should be tested with the parser (LC-MS_parse_samplesheet.py or spatial_parse_samplesheet.py).
+
+## Samplesheet template
+Samplesheet templates contains 3 sheets:
+
+- input: the one the user should fill. It contains two sections, one with user info and the other with samples metadata.
+- example_ok: an example of a good samplesheet
+- example_fail: an example of a problematic samplesheet
+
+## Parser
+The parser will check the samplesheet for its correct compilation and raises warnings and/or errors if any.
+If no errors are found, the samples metadata section is saved as a csv file (specified as -o). Warnings also prevent file to be saved, but this can be overruled by --ignore-warnings.
+
+## Test
+In test folder, 3 test samplesheet for each technology are found:
+
+- test_error.xlsx: a test samplesheet with errrors
+- test_ok.xlsx: a test samplesheet correctly compiled
+- test_warning.xlsx: a test samplesheet with warnings
+
+Several test should be run after changind any file:
+
+- `python LC-MS_parse_samplesheet.py` (this should result in an error for missing input and output) 
+- `python LC-MS_parse_samplesheet.py -i test_files/LC-MS_test_ok.xlsx -o test.csv --dry-run` (this should be ok, with no errors nor warnings, but no file should be saved due to --dry-run)
+- `python LC-MS_parse_samplesheet.py -i test_files/LC-MS_test_ok.xlsx -o test.csv` (this should be ok, with also test.csv file saved)
+- `python LC-MS_parse_samplesheet.py -i test_files/LC-MS_test_error.xlsx -o test.csv` (this should raise errors and no test.csv file should be created)
+- `python LC-MS_parse_samplesheet.py -i test_files/LC-MS_test_warning.xlsx -o test.csv` (this should raise warnings and no test.csv file should be created)
+- `python LC-MS_parse_samplesheet.py` (this should result in an error for missing input and output) 
+- `python spatial_parse_samplesheet.py -i test_files/spatial_test_ok.xlsx -o test.csv --dry-run` (this should be ok, with no errors nor warnings, but no file should be saved due to --dry-run)
+- `python LC-MS_parse_samplesheet.py -i test_files/LC-MS_test_ok_timecourse.xlsx -o test.csv` (this should be ok, with also test.csv file saved)
+- `python spatial_parse_samplesheet.py -i test_files/spatial_test_ok.xlsx -o test.csv` (this should be ok, with also test.csv file saved)
+- `python spatial_parse_samplesheet.py -i test_files/spatial_test_error.xlsx -o test.csv` (this should raise errors and no test.csv file should be created)
+- `python spatial_parse_samplesheet.py -i test_files/spatial_test_warning.xlsx -o test.csv` (this should raise warnings and no test.csv file should be created)
+- `python spatial_parse_samplesheet.py -i test_files/spatial_test_warning.xlsx -o test.csv` --ignore-warnings (this should raise warnings, but test.csv file should be created)
+- `python spatial_parse_samplesheet.py -i test_files/spatial_test_warning.xlsx -o test.csv` --ignore-warnings (this should raise warnings, but test.csv file should be created)
+

parseet-0.2.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "parseet"
+version = "0.2.0"
+description = "This package is used to parse ms samplesheet for further analyses."
+authors = [
+    { name = "Matteo Miotto", email = "miotsdata@gmail.com" },
+]
+dependencies = [
+    "pandas>=2.3.3",
+    "openpyxl>=3.1.5",
+]
+requires-python = "<3.13,>=3.12"
+readme = "README.md"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+keywords = [
+    "samplesheet",
+    "parser",
+    "data analyses",
+    "mass spectrometry",
+    "msdial",
+]
+
+[project.license]
+text = "MIT"
+
+[project.optional-dependencies]
+gui = [
+    "pyside6>=6.11.1",
+]
+
+[project.scripts]
+parseet = "parseet.cli:main"
+
+[project.gui-scripts]
+parseet-gui = "parseet.app:main"
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[tool.pdm]
+distribution = true
+
+[dependency-groups]
+dev = [
+    "sphinx-rtd-theme>=0.5.1",
+    "sphinx-argparse>=0.5.2",
+    "sphinx<8,>=6",
+    "sphinx-autodoc-typehints<3.6",
+    "pyinstaller>=6.20.0",
+]

parseet-0.2.0/src/parseet/__init__.py

@@ -0,0 +1,2 @@
+from parseet import *
+from .version import __version__

parseet-0.2.0/src/parseet/app.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python
+"""
+app.py
+======
+
+Entry point: registers ``Backend`` with the QML engine and opens the window.
+
+Usage
+-----
+::
+
+    python -m your_package.app
+    # or
+    python app.py
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from parseet.backend import Backend
+
+def _resource(relative: str) -> Path:
+    """Resolve a path that works both in development and when bundled."""
+    if hasattr(sys, '_MEIPASS'):
+        return Path(sys._MEIPASS) / relative
+    return Path(__file__).parent / relative
+
+def main() -> None:
+    try:
+        from PySide6.QtGui import QGuiApplication #pylint: disable=no-name-in-module
+        from PySide6.QtQml import QQmlApplicationEngine #pylint: disable=no-name-in-module
+        from PySide6.QtCore import QUrl #pylint: disable=no-name-in-module
+    except ImportError:
+        print(
+            "Error: the GUI requires PySide6.\n"
+            "Install it with:  pip install parseet[gui]",
+            file=__import__("sys").stderr,
+        )
+        __import__("sys").exit(1)
+
+    app = QGuiApplication(sys.argv)
+    app.setApplicationName("Samplesheet Tools")
+    app.setOrganizationName("YourOrg")
+
+    engine = QQmlApplicationEngine()
+
+    # Expose the backend singleton to QML
+    backend = Backend()
+    engine.rootContext().setContextProperty("backend", backend)
+
+    qml_file = _resource("main.qml")
+    engine.load(QUrl.fromLocalFile(str(qml_file)))
+
+    if not engine.rootObjects():
+        sys.exit(1)
+
+    sys.exit(app.exec())
+
+
+if __name__ == "__main__":
+    main()

parseet-0.2.0/src/parseet/backend.py

@@ -0,0 +1,283 @@
+"""
+backend.py
+==========
+
+QML-exposed backend that runs ``check_raw_file_order`` and ``check_samples``
+in a worker thread and emits structured result signals back to the UI.
+"""
+
+from __future__ import annotations
+
+import logging
+import traceback
+from pathlib import Path
+
+import pandas as pd
+from PySide6.QtCore import ( #pylint: disable=no-name-in-module
+    Property,
+    QObject,
+    QRunnable,
+    QThreadPool,
+    Signal,
+    Slot,
+) #pylint: disable=no-name-in-module
+
+from parseet.core.utils import (
+    check_raw_file_order,
+    check_samples,
+    configure_logging,
+    parse_samplesheet,
+)
+
+configure_logging(level=logging.WARNING)
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Worker infrastructure
+# ---------------------------------------------------------------------------
+
+class _WorkerSignals(QObject):
+    """Signals emitted by the worker back to the main thread."""
+    finished = Signal(list, list, list)   # errors, warnings, ok
+    failed   = Signal(str)                # traceback / exception message
+
+
+class _Worker(QRunnable):
+    """Runs a callable in the thread pool and emits results via signals."""
+
+    def __init__(self, fn, *args, **kwargs):
+        super().__init__()
+        self._fn     = fn
+        self._args   = args
+        self._kwargs = kwargs
+        self.signals = _WorkerSignals()
+
+    def run(self) -> None:
+        try:
+            errors, warnings, ok = self._fn(*self._args, **self._kwargs)
+            self.signals.finished.emit(errors, warnings, ok)
+        except Exception:
+            self.signals.failed.emit(traceback.format_exc())
+
+
+# ---------------------------------------------------------------------------
+# Shared samplesheet loader
+# ---------------------------------------------------------------------------
+
+def _load_and_parse(path: str) -> tuple[pd.DataFrame, list[str], list[str], list[str]]:
+    """
+    Read an Excel samplesheet and run ``parse_samplesheet``.
+
+    Returns ``(df, errors, warnings, ok)``.  Raises ``ValueError`` on
+    hard parse errors so the worker can surface them cleanly.
+    """
+    raw = pd.read_excel(path, header=None)
+    df, errors, warnings, ok, _col_descriptions = parse_samplesheet(raw)
+    if errors:
+        raise ValueError(
+            "Samplesheet parse errors:\n" + "\n".join(f"  • {e}" for e in errors)
+        )
+    return df, errors, warnings, ok
+
+
+# ---------------------------------------------------------------------------
+# Command implementations (run inside the worker thread)
+# ---------------------------------------------------------------------------
+
+def _run_check(
+    samplesheet_path: str,
+    folder_path: str,
+    dry_run: bool,
+    ignore_id: bool,
+) -> tuple[list[str], list[str], list[str]]:
+    """Worker body for the ``check`` command."""
+    df, _errors, ss_warnings, ss_ok = _load_and_parse(samplesheet_path)
+
+    _rename_map, errors, warnings, ok = check_raw_file_order(
+        folder_path=folder_path,
+        samplesheet=df,
+        dry_run=dry_run,
+        ignore_id=ignore_id,
+    )
+
+    return errors, ss_warnings + warnings, ss_ok + ok
+
+
+def _run_create(
+    samplesheet_path: str,
+    file_paths: list[str],
+    output_folder: str,
+    software: str,
+    dry_run: bool,
+    ignore_warnings: bool,
+) -> tuple[list[str], list[str], list[str]]:
+    """Worker body for the ``create`` command."""
+    df, _errors, ss_warnings, ss_ok = _load_and_parse(samplesheet_path)
+
+    all_errors:   list[str] = []
+    all_warnings: list[str] = ss_warnings
+    all_ok:       list[str] = ss_ok
+
+    import csv, json
+    for file_path in file_paths:
+        logger.info("Processing '%s'", file_path)
+        processed_sheet, message, errors, warnings, ok = check_samples(
+            df,
+            file_path,
+            software=software,
+        )
+
+        all_errors   += errors
+        all_warnings += warnings
+        all_ok       += ok
+
+        if errors:
+            all_errors.append(f"Skipped output for '{file_path}' due to errors above.")
+            continue
+
+        if dry_run:
+            all_ok.append(f"[DRY-RUN] Would write output for '{file_path}'")
+            continue
+
+        if warnings and not ignore_warnings:
+            all_warnings.append(
+                f"Skipped output for '{file_path}' — warnings present. "
+                "Enable 'Ignore warnings' to force output."
+            )
+            continue
+
+        stem        = Path(file_path).stem
+        csv_path    = Path(output_folder) / f"{stem}_samplesheet.csv"
+        schema_path = Path(output_folder) / f"{stem}_samplesheet_schema.json"
+
+        processed_sheet.replace("<NA>", "").to_csv(
+            csv_path,
+            quotechar='"',
+            quoting=csv.QUOTE_STRINGS,
+            na_rep="",
+            index=False,
+        )
+        schema = {col: str(dtype) for col, dtype in processed_sheet.dtypes.items()}
+        with open(schema_path, "w") as fh:
+            json.dump(schema, fh, indent=2)
+
+        all_ok.append(f"Saved '{csv_path}'")
+        all_ok.append(f"Saved schema '{schema_path}'")
+        if message:
+            all_warnings.append(message)
+
+    return all_errors, all_warnings, all_ok
+
+
+# ---------------------------------------------------------------------------
+# QML-exposed backend object
+# ---------------------------------------------------------------------------
+
+class Backend(QObject):
+    """
+    Exposed to QML as ``backend``.
+
+    Signals
+    -------
+    runStarted()
+        Emitted when the worker thread begins.
+    runFinished(errors, warnings, ok)
+        Emitted with result lists when the run completes successfully.
+    runFailed(message)
+        Emitted with a traceback string when an unhandled exception occurs.
+    busyChanged()
+        Notifies QML that the ``busy`` property has changed.
+    """
+
+    runStarted  = Signal()
+    runFinished = Signal(list, list, list)
+    runFailed   = Signal(str)
+    busyChanged = Signal()
+
+    def __init__(self, parent: QObject | None = None) -> None:
+        super().__init__(parent)
+        self._busy       = False
+        self._thread_pool = QThreadPool.globalInstance()
+
+    # ------------------------------------------------------------------
+    # busy property
+    # ------------------------------------------------------------------
+
+    def _get_busy(self) -> bool:
+        return self._busy
+
+    def _set_busy(self, value: bool) -> None:
+        if self._busy != value:
+            self._busy = value
+            self.busyChanged.emit()
+
+    busy = Property(bool, _get_busy, _set_busy, notify=busyChanged)
+
+    # ------------------------------------------------------------------
+    # Slots called from QML
+    # ------------------------------------------------------------------
+
+    @Slot(str, str, bool, bool)
+    def runCheck(
+        self,
+        samplesheet_path: str,
+        folder_path: str,
+        dry_run: bool,
+        ignore_id: bool,
+    ) -> None:
+        """Start the ``check_raw_file_order`` pipeline in a worker thread."""
+        self._dispatch(
+            _run_check,
+            samplesheet_path,
+            folder_path,
+            dry_run,
+            ignore_id,
+        )
+
+    @Slot(str, list, str, str, bool, bool)
+    def runCreate(
+        self,
+        samplesheet_path: str,
+        file_paths: list,
+        output_folder: str,
+        software: str,
+        dry_run: bool,
+        ignore_warnings: bool,
+    ) -> None:
+        """Start the ``check_samples`` / CSV-write pipeline in a worker thread."""
+        self._dispatch(
+            _run_create,
+            samplesheet_path,
+            list(file_paths),
+            output_folder,
+            software,
+            dry_run,
+            ignore_warnings,
+        )
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _dispatch(self, fn, *args) -> None:
+        if self._busy:
+            logger.warning("A run is already in progress — ignoring request")
+            return
+
+        self._set_busy(True)
+        self.runStarted.emit()
+
+        worker = _Worker(fn, *args)
+        worker.signals.finished.connect(self._on_finished)
+        worker.signals.failed.connect(self._on_failed)
+        self._thread_pool.start(worker)
+
+    def _on_finished(self, errors: list, warnings: list, ok: list) -> None:
+        self._set_busy(False)
+        self.runFinished.emit(errors, warnings, ok)
+
+    def _on_failed(self, message: str) -> None:
+        self._set_busy(False)
+        logger.error("Worker failed:\n%s", message)
+        self.runFailed.emit(message)

parseet-0.2.0/src/parseet/cli.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python
+"""
+Samplesheet CLI
+===============
+
+.. program:: samplesheet
+
+Command-line interface for validating, parsing, and generating samplesheets.
+
+This CLI provides two subcommands:
+
+``reparse``
+    Reparse Excel input files into quoted CSV format.
+
+``create``
+    Validate a samplesheet against integration files and generate derived
+    samplesheet CSV files.
+
+Configuration is provided via a TOML file and merged with the default
+:data:`base_config`.
+
+Subcommands
+-----------
+
+reparse
+^^^^^^^
+Reparse Excel files into quoted CSV files.
+
+.. option:: reparse INPUTS [INPUTS ...]
+
+   One or more Excel files to reparse.
+
+.. option:: -c, --config CONFIG
+
+   Optional TOML configuration file.
+
+create
+^^^^^^
+Validate a samplesheet and generate per-input CSV files.
+
+.. option:: create FILES [FILES ...]
+
+   Integration files to process.
+
+.. option:: -s, --samplesheet PATH
+
+   Path to the samplesheet Excel file.
+
+.. option:: -o, --outdir DIR
+
+   Output directory for generated samplesheets.
+
+.. option:: --dry-run
+
+   Do not write output files.
+
+.. option:: --ignore-warnings
+
+   Save output even if warnings are present.
+
+.. option:: -c, --config CONFIG
+
+   Optional TOML configuration file.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+import json
+import sys
+from typing import List
+import pandas as pd
+
+import csv
+from .core.utils import (
+    parse_samplesheet,
+    check_samples,
+    build_parser,
+    check_raw_file_order,
+    configure_logging
+)
+
+
+def main(argv: list[str] | None = None) -> None:
+    """
+    Entry point for the samplesheet command-line interface.
+
+    This function parses command-line arguments, loads configuration,
+    dispatches subcommands, and coordinates samplesheet validation
+    and output generation.
+
+    Raises
+    ------
+    ValueError
+        If required inputs are missing or validation fails.
+    """
+
+    configure_logging(level=logging.INFO)
+
+    # This is necessary to build docs
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    # ---------------------
+    # CHECK SAMPLE ORDER
+    # ---------------------
+    if args.command == "check":
+        samplesheet = pd.read_excel(args.samplesheet, header=None)
+        samplesheet, errors, warnings, ok, col_description = parse_samplesheet(samplesheet, )
+        check_raw_file_order(folder_path=args.folder[0],
+                             dry_run=args.dry_run,
+                             samplesheet = samplesheet,
+                             ignore_id=args.ignore_id)
+
+    # ----------
+    # CREATE
+    # ----------
+    if args.command == "create":
+
+        files: List[str] = (
+            args.files
+        )
+
+        if not files:
+            logging.error("No input files provided. Use CLI arguments or config.")
+            sys.exit(1)
+
+        output_folder: str = args.outdir
+
+        dry_run: bool = args.dry_run
+
+        ignore_warnings: bool = args.ignore_warnings
+
+        samplesheet = pd.read_excel(args.samplesheet, header=None)
+        samplesheet, errors, warnings, ok, col_description = parse_samplesheet(samplesheet)
+
+        if errors:
+            sys.exit(1)
+
+        for file_path in files:
+            processed_sheet, message, errors, warnings, ok = check_samples(
+                samplesheet,
+                file_path,
+                software=args.software,
+            )
+
+            output_file: Path = Path(output_folder) / f"{Path(file_path).stem}_samplesheet.csv"
+
+            if dry_run:
+                print("[DRY-RUN] File not saved.")
+                continue
+
+            if warnings and not ignore_warnings:
+                logging.warning("Warnings were found. Use --ignore-warnings to proceed.")
+                sys.exit(1)
+
+            processed_sheet = processed_sheet.replace("<NA>", "").sort_values("sample_order")
+            processed_sheet.to_csv(
+                output_file,
+                quotechar='"',
+                quoting=csv.QUOTE_STRINGS,
+                na_rep="",
+                index=False
+            )
+
+            print(f"Samplesheet saved as {output_file}. {message}")
+
+            schema_file: Path = Path(output_folder) / f"{Path(file_path).stem}_samplesheet_schema.json"
+
+            schema = {col: str(dtype) for col, dtype in processed_sheet.dtypes.items()}
+            with open(schema_file, "w") as f:
+                json.dump(schema, f, indent=2)
+            print(f"Schema file saved as {schema_file}")
+
+if __name__ == "__main__":
+    main()

parseet-0.2.0/src/parseet/config/__init__.py

@@ -0,0 +1,6 @@
+import pathlib
+import tomllib
+
+path = pathlib.Path(__file__).parent / "config.toml"
+with path.open(mode="rb") as fp:
+    base_config = tomllib.load(fp)

parseet-0.2.0/src/parseet/config/config.toml

@@ -0,0 +1,7 @@
+[output]
+dir = "."
+
+[run]
+dry_run = false
+ignore_warnings = false
+