parseet 0.2.0__py3-none-any.whl

parseet/core/utils/lcms_check_samples.py

@@ -0,0 +1,397 @@
+#!/usr/bin/env python
+"""
+Integration File Sample Checker
+================================
+
+Validates and aligns an integration Excel file against a reference
+samplesheet.
+
+It verifies that:
+- All integration file columns correspond to valid sample names, QC, FM,
+  or Blank entries.
+- Naming conventions are respected.
+- All samples appear in both the samplesheet and the integration file.
+
+The output is a merged samplesheet ordered to match the integration file
+column order.
+"""
+
+import logging
+import re
+
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Special column types recognised in integration files
+# ---------------------------------------------------------------------------
+_SPECIAL_TYPES: tuple[tuple[str, str], ...] = (
+    ("QC", "QC"),
+    ("FM", "FM"),
+    ("Blank", "Blank"),
+)
+
+
+# ---------------------------------------------------------------------------
+# Result helper
+# ---------------------------------------------------------------------------
+
+class CheckResult:
+    """Accumulates errors, warnings, and informational messages."""
+
+    def __init__(self):
+        self.errors:   list[str] = []
+        self.warnings: list[str] = []
+        self.ok:       list[str] = []
+
+    def error(self, msg: str) -> None:
+        self.errors.append(msg)
+        logger.error(msg)
+
+    def warn(self, msg: str) -> None:
+        self.warnings.append(msg)
+        logger.warning(msg)
+
+    def good(self, msg: str) -> None:
+        self.ok.append(msg)
+        logger.info(msg)
+
+
+# ---------------------------------------------------------------------------
+# Sub-functions
+# ---------------------------------------------------------------------------
+
+def _read_data(integration_file: str, software: str) -> pd.DataFrame:
+    """
+    Read the integration file based on its software type.
+
+    Parameters
+    ----------
+    integration_file:
+        Path to the Excel / TSV integration file.
+    software:
+        ``"crommy"`` or ``"msdial"``.
+
+    Returns
+    -------
+    pandas.DataFrame
+
+    Raises
+    ------
+    ValueError
+        If *software* is not supported.
+    """
+    if software == "crommy":
+        logger.debug("Reading crommy file: %s", integration_file)
+        return pd.read_excel(integration_file, sheet_name="Sheet1", index_col=0)
+    if software == "msdial":
+        logger.debug("Reading msdial file: %s", integration_file)
+        return pd.read_table(integration_file, sep="\t", header=4)
+    raise ValueError(f"Unsupported integration file type: '{software}'")
+
+
+def _extract_sample_columns(data: pd.DataFrame, software: str) -> pd.Index:
+    """
+    Slice out the intensity/peak columns that follow the sentinel column
+    (``"Charge"`` for crommy, ``"MS/MS spectrum"`` for msdial).
+
+    Parameters
+    ----------
+    data:
+        Raw integration DataFrame (already sorted by index).
+    software:
+        ``"crommy"`` or ``"msdial"``.
+
+    Returns
+    -------
+    pandas.Index
+        Ordered column labels for the sample/QC/blank entries.
+    """
+    sentinel = "MS/MS spectrum" if software == "msdial" else "Charge"
+    start_index = list(data.columns).index(sentinel)
+    last_index = data.columns.get_loc("1") if software == "msdial" else len(data.columns)
+    columns = data.columns[start_index + 1 : last_index]
+    logger.debug("Extracted %d sample columns after '%s'", len(columns), sentinel)
+    return columns
+
+
+def _build_sample_pattern(samplesheet: pd.DataFrame) -> re.Pattern:
+    """
+    Compile a single regex that matches ``<order>_<sample>_<phase>_<polarity>``
+    column names and captures the sample name in group 1.
+
+    Parameters
+    ----------
+    samplesheet:
+        Must contain a ``"Sample name"`` column.
+
+    Returns
+    -------
+    re.Pattern
+    """
+    sample_names = samplesheet["Sample name"].tolist()
+    samples_alternation = "|".join(re.escape(s) for s in sample_names)
+    pattern = re.compile(rf"\d+_({samples_alternation})_(C18|HILIC)_(np|p|n)")
+    logger.debug("Built sample-matching pattern for %d sample name(s)", len(sample_names))
+    return pattern
+
+
+def _classify_columns(
+    columns: pd.Index,
+    pattern: re.Pattern,
+    result: CheckResult,
+) -> pd.DataFrame:
+    """
+    Classify each integration column as a sample, QC/FM/Blank, or unmatched.
+
+    Parameters
+    ----------
+    columns:
+        Integration file column labels to classify.
+    pattern:
+        Compiled regex from :func:`_build_sample_pattern`.
+    result:
+        Accumulates warnings/errors encountered during classification.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Columns: ``Sample name``, ``filename``, ``_type``.
+
+    Raises
+    ------
+    ValueError
+        If any column has the wrong number of underscores, or if any column
+        cannot be matched to a sample or a known special type.
+    """
+    matched_entries:      list[dict] = []
+    wrong_name_entries:   list[str]  = []
+    unmatched_entries:    list[str]  = []
+
+    for entry in columns:
+        if entry.count("_") != 3:
+            wrong_name_entries.append(entry)
+
+        m = pattern.search(entry)
+        if m:
+            matched_entries.append({
+                "Sample name": m.group(1),
+                "filename": entry,
+                "_type": "sample",
+            })
+            result.good(f"Matched sample column: '{entry}' → '{m.group(1)}'")
+        else:
+            special_type = next(
+                (t for key, t in _SPECIAL_TYPES if key in entry), None
+            )
+            matched_entries.append({
+                "Sample name": None,
+                "filename": entry,
+                "_type": special_type or "Unmatched",
+            })
+            if special_type:
+                result.good(f"Recognised special column: '{entry}' → {special_type}")
+            else:
+                unmatched_entries.append(entry)
+
+    if wrong_name_entries:
+        raise ValueError(
+            "These columns have a wrong number of underscores: "
+            + ", ".join(wrong_name_entries)
+        )
+    if unmatched_entries:
+        raise ValueError(
+            "These columns have no match in the samplesheet: "
+            + ", ".join(unmatched_entries)
+        )
+
+    return pd.DataFrame(matched_entries)
+
+
+def _merge_and_validate(
+    samplesheet: pd.DataFrame,
+    matched_df: pd.DataFrame,
+    columns: pd.Index,
+    result: CheckResult,
+) -> pd.DataFrame:
+    """
+    Outer-merge the samplesheet with the classified columns and verify that
+    every samplesheet entry has a corresponding integration column.
+
+    Parameters
+    ----------
+    samplesheet:
+        Original sample metadata DataFrame.
+    matched_df:
+        Output of :func:`_classify_columns`.
+    columns:
+        Original ordered column index (used to assign ``col_order``).
+    result:
+        Accumulates warnings/errors.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Merged DataFrame with ``col_order``, ``polarity``, and
+        ``sample_order`` columns added.
+
+    Raises
+    ------
+    ValueError
+        If any samplesheet entry has no matching integration column.
+    """
+    col_order_map = {name: i for i, name in enumerate(columns)}
+    matched_df = matched_df.copy()
+    matched_df["col_order"] = matched_df["filename"].map(col_order_map)
+
+    merged_df = pd.merge(samplesheet, matched_df, on="Sample name", how="outer")
+
+    missing_in_data = merged_df.loc[merged_df["filename"].isna(), "Sample name"]
+    if not missing_in_data.empty:
+        raise ValueError(
+            "These samplesheet entries have no match in the integration file: "
+            + ", ".join(missing_in_data)
+        )
+
+    result.good(
+        f"All {(merged_df['_type'] == 'sample').sum()} sample(s) matched successfully"
+    )
+
+    # Derive polarity and injection order from the filename
+    split = merged_df["filename"].str.split("_")
+    merged_df["polarity"]     = split.str[-1].str.lower().astype("category")
+    merged_df["sample_order"] = split.str[0].astype(int)
+
+    return merged_df
+
+
+def _handle_batch_column(
+    merged_df: pd.DataFrame,
+    result: CheckResult,
+) -> tuple[pd.DataFrame, str]:
+    """
+    Ensure a ``"Batch"`` column is present and is of string type.
+
+    Parameters
+    ----------
+    merged_df:
+        Merged sample DataFrame.
+    result:
+        Accumulates warnings/errors.
+
+    Returns
+    -------
+    tuple[pandas.DataFrame, str]
+        The (possibly modified) DataFrame and an informational message string.
+    """
+    if "Batch" not in merged_df.columns:
+        merged_df = merged_df.copy()
+        merged_df["Batch"] = "1"
+        message = ""
+        result.good("No 'Batch' column found — defaulting all samples to batch '1'")
+    else:
+        merged_df = merged_df.copy()
+        merged_df["Batch"] = merged_df["Batch"].astype(str)
+        message = "Please fill Batch info for blanks and QC."
+        result.warn(message)
+
+    return merged_df, message
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+def check_samples(
+    samplesheet: pd.DataFrame,
+    integration_file: str,
+    software: str = "crommy",
+) -> tuple[pd.DataFrame, str, list[str], list[str], list[str]]:
+    """
+    Validate and match samples between a samplesheet and an integration file.
+
+    Reads an Excel/TSV integration file, extracts sample-related columns,
+    and matches them against the ``"Sample name"`` column in the provided
+    samplesheet. Enforces naming conventions, checks for missing or extra
+    samples, and returns a merged DataFrame ordered according to the
+    integration file column layout.
+
+    Parameters
+    ----------
+    samplesheet:
+        DataFrame containing sample metadata. Must include a
+        ``"Sample name"`` column.
+    integration_file:
+        Path to the Excel integration file.
+    software:
+        Integration software: ``"crommy"`` (default) or ``"msdial"``.
+
+    Returns
+    -------
+    merged_df:
+        DataFrame combining the samplesheet with matched integration file
+        entries, ordered to match the integration file.
+    message:
+        Informational message regarding batch handling (empty string when
+        no action is needed).
+    errors:
+        Blocking error messages collected during validation.
+    warnings:
+        Non-blocking warning messages collected during validation.
+    ok:
+        Passed-check messages collected during validation.
+
+    Raises
+    ------
+    ValueError
+        If column naming conventions are violated, or samples are missing
+        from either side of the merge.
+    """
+    result = CheckResult()
+    logger.info(
+        "Starting sample check — software='%s', file='%s'",
+        software, integration_file,
+    )
+
+    # 1. Read the integration file
+    data = _read_data(integration_file, software)
+    data.sort_index(inplace=True)
+
+    # 2. Slice the sample/QC/blank columns
+    columns = _extract_sample_columns(data, software)
+
+    # 3. Build the sample-matching regex
+    pattern = _build_sample_pattern(samplesheet)
+
+    # 4. Classify every column
+    matched_df = _classify_columns(columns, pattern, result)
+
+    # 5. Merge and validate completeness
+    merged_df = _merge_and_validate(samplesheet, matched_df, columns, result)
+
+    # 6. Resolve the Batch column
+    merged_df, message = _handle_batch_column(merged_df, result)
+
+    # 7. Sort to match integration file column order
+    merged_df = (
+        merged_df
+        .sort_values("col_order")
+        .reset_index(drop=True)
+        .drop(columns="col_order")
+    )
+
+    logger.info(
+        "Sample check complete — %d error(s), %d warning(s), %d ok",
+        len(result.errors), len(result.warnings), len(result.ok),
+    )
+
+    return merged_df, message, result.errors, result.warnings, result.ok
+
+if __name__ == "__main__":
+    from parse_samplesheet import parse_samplesheet
+    df = pd.read_excel("test_files/LC-MS_metabolomics_PLASMA.xlsx", header=None)
+    sample_df, _, _, _, _ = parse_samplesheet(df, )
+    
+    merged_df, message, errors, warnings, ok = check_samples(sample_df, "test_files/HILICp_Areas.txt", software="msdial")
+    print(merged_df)