Add function: export summary metric as CSV file.

Author: ygao61

README.md

@@ -97,11 +97,15 @@ If you want to use a specified list of valid cell barcodes, you can provide the
 
 To reduce runtime, you may enable the `--skip_umap_tsne` option to bypass dimensionality reduction and visualization steps.
 
-**7- Debug-level message**
+**7- Export the summary metrics**
+
+To export the summary metrics, specify the directory where the summary table should be saved as a CSV file.
+
+**8- Debug-level message**
 
 To get debug-level messages and more intermediate computation in cell calling step, you can specify `--verbose`
 
-**8- Re-run QCatch on modified h5ad file**
+**9- Re-run QCatch on modified h5ad file**
 If you re-run QCatch analysis on a modified `.h5ad` file (i.e., an `.h5ad` file with additional columns added for cell calling results), the existing cell calling-related columns will be removed and then replaced with new results. The new cell calling can be generated either through QCatch's internal method or based on a user-specified list of valid cell barcodes.
 
 **Example directory structures:**
@@ -148,6 +152,7 @@ For more advanced options and usage details, see the sections below.
 | `--valid_cell_list` | `-l` | `str` (Optional) |File provides a user-specified list of valid cell barcode. The file must be a TSV containing one column with cell barcodes without a header row. If provided, qcatch will skip the internal cell calling steps and and use the supplied list instead|
 | `--n_partitions` | `-n` | `int` (Optional) | Number of partitions (max number of barcodes to consider for ambient estimation). Skip this step if you already specified `--chemistry`. Only use `--n_partitions` when your experiment uses a custom chemistry not listed in the predefined chemistry options.|
 | `--skip_umap_tsne` | `-u` | `flag` (Optional) | If provided, skips generation of UMAP and t-SNE plots. |
+| `--summary_table_file` | `-t` | `Path` (Optional) | Path to a directory where the summary metrics will be saved as a CSV file. |
 | `--verbose` | `-b` | `flag` (Optional) | Enable verbose logging with debug-level messages. |
 | `--version` | `-v` | `flag` (Optional) | Display the installed version of qcatch. |
 

src/qcatch/convert_to_html.py

@@ -89,8 +89,15 @@ def create_plotly_plots(
         mapping_rate = round(map_json_data["num_mapped"] / num_processed * 100, 2)
     seq_saturation_value = generate_seq_saturation(retained_data)
 
+    summary_table_file = args.summary_table_file
     summary_table_html = generate_summary_table(
-        data, valid_bcs, total_detected_genes, median_genes_per_cell, mapping_rate, seq_saturation_value
+        data,
+        valid_bcs,
+        total_detected_genes,
+        median_genes_per_cell,
+        mapping_rate,
+        seq_saturation_value,
+        summary_table_file,
     )
 
     # ---------------- Tab2 - Barcode Frequency Plots ---------------

src/qcatch/main.py

@@ -80,6 +80,13 @@ def main():
     parser.add_argument(
         "--skip_umap_tsne", "-u", action="store_true", help="If provided, skips generation of UMAP and t-SNE plots."
     )
+    parser.add_argument(
+        "--summary_table_file",
+        "-t",
+        type=Path,
+        default=None,
+        help="Path to a directory where the summary metrics will be saved as a CSV file.",
+    )
     parser.add_argument("--verbose", "-b", action="store_true", help="Enable verbose logging with debug-level messages")
 
     parser.add_argument(

src/qcatch/plots_tables.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import logging
+import os
 
 import numpy as np
 import pandas as pd
@@ -664,17 +665,19 @@ def generate_summary_table(
     median_genes_per_cell: int,
     mapping_rate: float | None,
     seq_saturation_value: float,
+    summary_table_file: str | None = None,
 ) -> str:
     """
     Generate a summary table with total corrected reads, median UMI, and total number of cells, etc.
 
     Args:
-        raw_featuredump_data: DataFrame containing featurn dump data.
+        raw_featuredump_data: DataFrame containing feature dump data.
         valid_bcs: List of valid barcode strings.
         total_detected_genes: Total number of genes detected in retained cells.
         median_genes_per_cell: Median number of genes per retained cell.
         mapping_rate: Fraction of reads mapped to reference, or None.
         seq_saturation_value: Sequencing saturation percentage.
+        summary_table_file: Optional path to save the summary table as a CSV file.
 
     Returns
     -------
@@ -697,6 +700,13 @@ def generate_summary_table(
         "Sequencing saturation": f"{seq_saturation_value}%",
     }
 
+    # Optionally: Save the summary table to a CSV file
+    if summary_table_file:
+        summary_table_file_path = os.path.join(summary_table_file, "summary_table.csv")
+        logger.info(f"🍡 Saving summary table to CSV at: {summary_table_file_path}")
+        # Save the summary dictionary as a single-row CSV file with keys as column headers
+        pd.DataFrame([summary]).to_csv(summary_table_file_path, index=False)
+
     # Convert summary dict to a list of (key, value) pairs
     summary_items = list(summary.items())
 

tests/test_qcatch.py

@@ -78,6 +78,8 @@ def test_simpleaf_with_cb_list(tmp_path):
         "--valid_cell_list",
         str(valid_cb_list),
         "--skip_umap_tsne",
+        "--summary_table_file",
+        str(output_path),
         "--verbose",
     ]