parseet 0.2.0__py3-none-any.whl

parseet/core/utils/parse_samplesheet.py

@@ -0,0 +1,363 @@
+import pandas as pd
+import logging
+import re
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Result helpers
+# ---------------------------------------------------------------------------
+
+class ParseResult:
+    """Accumulates errors, warnings, ok messages, and column descriptions."""
+
+    def __init__(self):
+        self.errors: list[str] = []
+        self.warnings: list[str] = []
+        self.ok: list[str] = []
+        self.col_descriptions: dict[str, dict] = {}
+
+    def error(self, msg: str):
+        self.errors.append(msg)
+        logger.error(msg)
+
+    def warn(self, msg: str):
+        self.warnings.append(msg)
+        logger.warning(msg)
+
+    def good(self, msg: str):
+        self.ok.append(msg)
+        logger.info(msg)
+
+
+# ---------------------------------------------------------------------------
+# Sub-functions
+# ---------------------------------------------------------------------------
+
+def _check_metadata(df_input: pd.DataFrame, result: ParseResult) -> None:
+    """Validate the top-level metadata rows (rows 0-3, column B)."""
+    meta_labels = ["Referent Name", "Referent Email", "Group", "Multi-round"]
+    for i, label in enumerate(meta_labels):
+        value = df_input.iloc[i, 1] if i < len(df_input) else None
+        if pd.isna(value):
+            result.error(f"Missing {label}")
+        else:
+            result.good(f"{label} found: {value}")
+
+
+def _find_sample_block(df_input: pd.DataFrame, result: ParseResult) -> pd.DataFrame:
+    """
+    Locate the header row that contains 'Sample name' and return the
+    sub-DataFrame starting from that row (with the header promoted).
+
+    Raises ValueError if the header row cannot be found.
+    """
+    header_row_idx = None
+    for i, row in df_input.iterrows():
+        if row.astype(str).str.contains("Sample name", case=False).any():
+            header_row_idx = i
+            break
+
+    if header_row_idx is None:
+        result.error("Header row not found")
+        raise ValueError("No header row found in samplesheet")
+
+    logger.info("Found header row at index %d", header_row_idx)
+
+    # Promote that row to column names
+    df = df_input.iloc[header_row_idx:].copy()
+    df.columns = df.iloc[0]
+    df = df.iloc[1:].reset_index(drop=True)
+
+    # Basic clean-up
+    df["Sample name"] = df["Sample name"].astype(str).str.strip()
+    if "Ignore" in df.columns:
+        df = df[df["Ignore"].isna()].reset_index(drop=True)
+
+    result.good(f"Sample block found: {len(df)} sample(s)")
+    return df
+
+
+def _check_sample_names(df_samples: pd.DataFrame, result: ParseResult) -> pd.DataFrame:
+    """Warn and sanitise sample names that contain disallowed characters."""
+    allowed = re.compile(r'^[A-Za-z0-9\-]+$')
+    invalid_mask = df_samples["Sample name"].apply(
+        lambda x: not bool(allowed.match(str(x))) if pd.notnull(x) else False
+    )
+    invalid_count = invalid_mask.sum()
+
+    if invalid_count > 0:
+        result.warn(
+            f"Found {invalid_count} sample name(s) with disallowed characters — replacing with '-'."
+        )
+        df_samples = df_samples.copy()
+        df_samples["Sample name"] = df_samples["Sample name"].apply(
+            lambda x: re.sub(r'[^A-Za-z0-9\-]', '-', str(x))
+        )
+    else:
+        result.good("All sample names are valid")
+
+    return df_samples
+
+
+def _describe_metadata_columns(
+    df_samples: pd.DataFrame, result: ParseResult
+) -> None:
+    """
+    Inspect every metadata column between 'Quantity' and the first
+    'Contrast-N' column, populate result.col_descriptions, and emit
+    warnings for missing values or label inconsistencies.
+    """
+    if "Quantity" not in df_samples.columns:
+        result.warn("'Quantity' column not found — skipping metadata column inspection")
+        return
+
+    quantity_idx = df_samples.columns.get_loc("Quantity")
+    contrast_cols = [c for c in df_samples.columns if re.fullmatch(r"Contrast-\d+", str(c))]
+    first_contrast_idx = (
+        df_samples.columns.get_loc(contrast_cols[0]) if contrast_cols else len(df_samples.columns)
+    )
+    metadata_cols = df_samples.columns[quantity_idx:first_contrast_idx]
+    logger.info("Found %d metadata column(s)", len(metadata_cols))
+
+    for col in metadata_cols:
+        col_data = df_samples[col]
+        _describe_one_column(col, col_data, result)
+
+
+def _describe_one_column(
+    col: str, col_data: pd.Series, result: ParseResult
+) -> None:
+    """Build a description for a single metadata column and register warnings."""
+    col_type = col_data.dtype
+
+    if col_type in ("float64", "int64"):
+        description: dict = {
+            "type": str(col_type),
+            "max": col_data.max(),
+            "mean": col_data.mean(),
+            "min": col_data.min(),
+        }
+        if col_data.isna().any():
+            result.warn(f"Missing values in numeric column '{col}'")
+            description["has_missing"] = True
+
+        logger.info(
+            "Metadata '%s' [numeric]: min=%.2f mean=%.2f max=%.2f",
+            col, description["min"], description["mean"], description["max"],
+        )
+
+    else:
+        cat_counts = col_data.value_counts(dropna=False)
+        categories = {
+            (str(val) if pd.notna(val) else "__missing__"): int(cnt)
+            for val, cnt in cat_counts.items()
+        }
+        description = {
+            "type": "categorical",
+            "n_categories": int(cat_counts.dropna().shape[0]),
+            "categories": categories,
+        }
+
+        # Missing values
+        missing_count = col_data.isna().sum()
+        if missing_count > 0:
+            result.warn(f"Missing values in categorical column '{col}' ({missing_count} rows)")
+            description["has_missing"] = True
+
+        # Label-consistency check (flag rare case variants)
+        label_issues = _find_label_inconsistencies(col, col_data)
+        if label_issues:
+            for issue in label_issues:
+                result.warn(issue)
+            description["label_warnings"] = label_issues
+
+        logger.info(
+            "Metadata '%s' [categorical]: %d category/ies — %s",
+            col,
+            description["n_categories"],
+            ", ".join(f"{k}={v}" for k, v in categories.items()),
+        )
+
+    result.col_descriptions[col] = description
+
+
+def _find_label_inconsistencies(col: str, col_data: pd.Series) -> list[str]:
+    """
+    Return warning strings for labels that look like case variants of each
+    other but appear far less often than the dominant spelling.
+    """
+    lowered_map: dict[str, list[str]] = {}
+    for label in col_data.dropna().unique():
+        lowered_map.setdefault(str(label).lower(), []).append(str(label))
+
+    issues = []
+    for variants in lowered_map.values():
+        if len(variants) < 2:
+            continue
+        counts = {v: int((col_data == v).sum()) for v in variants}
+        max_count = max(counts.values())
+        for label, count in counts.items():
+            if count < 0.2 * max_count:
+                issues.append(
+                    f"Column '{col}': label '{label}' appears {count} time(s) "
+                    f"vs similar variant(s) {variants} — possible typo or case mismatch"
+                )
+    return issues
+
+
+def _validate_contrast_columns(df_samples: pd.DataFrame, result: ParseResult) -> None:
+    """
+    Check every column whose name starts with 'Contrast'.
+    Valid names match Contrast-<N>; valid values are 1 or 2 (or NaN).
+    """
+    contrast_columns = [c for c in df_samples.columns if str(c).startswith("Contrast")]
+
+    for col in contrast_columns:
+        if not re.fullmatch(r"Contrast-\d+", str(col)):
+            result.error(f"Invalid contrast column name: '{col}' (expected Contrast-<number>)")
+            continue
+
+        invalid_values = _collect_invalid_int_values(df_samples[col], allowed={1, 2})
+        if invalid_values:
+            result.error(f"Invalid value(s) in '{col}': {invalid_values}")
+        else:
+            c1 = (df_samples[col].astype(str) == "1").sum()
+            c2 = (df_samples[col].astype(str) == "2").sum()
+            result.good(f"Contrast '{col}': group-1={c1}, group-2={c2}")
+
+
+def _validate_timecourse_columns(df_samples: pd.DataFrame, result: ParseResult) -> None:
+    """
+    Check every column whose name starts with 'Timecourse'.
+    Valid names match Timecourse-<N>; values must be non-negative integers.
+    """
+    timecourse_columns = [c for c in df_samples.columns if str(c).startswith("Timecourse")]
+
+    for col in timecourse_columns:
+        if not re.fullmatch(r"Timecourse-\d+", str(col)):
+            result.error(f"Invalid timecourse column name: '{col}' (expected Timecourse-<number>)")
+            continue
+
+        invalid_values = _collect_invalid_int_values(df_samples[col], allowed=None)
+        if invalid_values:
+            result.error(f"Invalid value(s) in '{col}': {invalid_values}")
+        else:
+            counts = df_samples[col].dropna().value_counts().sort_index()
+            summary = ", ".join(f"{int(v)}:{c}" for v, c in counts.items())
+            result.good(f"Timecourse '{col}': {summary}")
+
+
+def _collect_invalid_int_values(series: pd.Series, allowed: set[int] | None) -> set:
+    """
+    Return the set of values in *series* that cannot be cast to int, or
+    (when *allowed* is provided) that are not in the allowed set.
+    NaN values are ignored.
+    """
+    invalid: set = set()
+    for v in series.dropna().unique():
+        try:
+            v_int = int(v)
+            if float(v) != v_int:          # reject 1.5, etc.
+                raise ValueError
+            if allowed is not None and v_int not in allowed:
+                raise ValueError
+        except (ValueError, TypeError):
+            invalid.add(v)
+    return invalid
+
+
+def _coerce_group_columns(df_samples: pd.DataFrame) -> pd.DataFrame:
+    """Cast contrast and timecourse columns to nullable Int64, then to clean strings."""
+    group_cols = [
+        c for c in df_samples.columns
+        if re.fullmatch(r"(Contrast|Timecourse)-\d+", str(c))
+    ]
+    if group_cols:
+        df_samples = df_samples.copy()
+        df_samples[group_cols] = (
+            df_samples[group_cols]
+            .apply(pd.to_numeric, errors="coerce")
+            .astype("Int64")
+            .astype(str)
+            .replace("<NA>", "")
+        )
+    return df_samples
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+def parse_samplesheet(
+    df_input: pd.DataFrame,
+) -> tuple[pd.DataFrame, list[str], list[str], list[str], dict[str, dict]]:
+    """
+    Parse and validate a samplesheet DataFrame.
+
+    Parameters
+    ----------
+    df_input:
+        Raw DataFrame as loaded from the spreadsheet (no header manipulation).
+
+    Returns
+    -------
+    df_samples:
+        Cleaned sample table.
+    errors:
+        List of blocking error messages.
+    warnings:
+        List of non-blocking warning messages.
+    ok:
+        List of passed-check messages.
+    col_descriptions:
+        Per-column summary statistics / category info.
+    """
+    result = ParseResult()
+
+    # 1. Top-level metadata (rows 0-3)
+    _check_metadata(df_input, result)
+
+    # 2. Locate the sample block
+    df_samples = _find_sample_block(df_input, result)
+
+    # 3. Sanitise sample names
+    df_samples = _check_sample_names(df_samples, result)
+
+    # 4. Describe metadata columns
+    _describe_metadata_columns(df_samples, result)
+
+    # 5. Validate contrast columns
+    _validate_contrast_columns(df_samples, result)
+
+    # 6. Validate timecourse columns
+    _validate_timecourse_columns(df_samples, result)
+
+    # 7. Coerce group columns to clean string representation
+    df_samples = _coerce_group_columns(df_samples)
+
+    logger.info(
+        "Parsing complete — %d error(s), %d warning(s)",
+        len(result.errors), len(result.warnings),
+    )
+
+    return df_samples, result.errors, result.warnings, result.ok, result.col_descriptions
+
+"""
+if __name__ == "__main__":
+
+    for test_file in [
+        "test_files/LC-MS_metabolomics_PLASMA.xlsx",
+        "test_files/LC-MS_metabolomics_PLASMA_warnings.xlsx",
+    ]:
+        df = pd.read_excel(test_file, header=None)
+        df_samples, errors, warnings, ok, col_desc = parse_samplesheet(df)
+        print(f"\nResults for {test_file}:")
+        print("Errors:", errors)
+        print("Warnings:", warnings)
+        print("OK:", ok)
+        print("Column descriptions:")
+        for col, desc in col_desc.items():
+            print(f"  {col}: {desc}")
+"""

parseet/core/utils/setup_logger.py

@@ -0,0 +1,24 @@
+import logging
+from pathlib import Path
+
+def configure_logging(
+    *,
+    level=logging.INFO,
+    log_file: Path | None = None,
+):
+    handlers = []
+
+    # Console handler
+    console_handler = logging.StreamHandler()
+    handlers.append(console_handler)
+
+    # Optional file handler
+    if log_file is not None:
+        file_handler = logging.FileHandler(log_file)
+        handlers.append(file_handler)
+
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s [%(levelname)s] %(name)s.%(funcName)s: %(message)s",
+        handlers=handlers,
+    )