[UPDATE] Feature Score plotting

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+### 🚀 Features
+
+- Add unified `pyprophet export feature-scores` command that works with all file formats (OSW, Parquet, Split Parquet)
+  - Auto-detects SCORE tables and adjusts behavior intelligently
+  - Applies RANK==1 filtering when SCORE tables exist
+  - Plots only VAR_ columns for unscored files
+  - Supports MS1, MS2, and transition level features
+
+### 🔧 Deprecated
+
+- Deprecate `pyprophet export score-plots` command in favor of `pyprophet export feature-scores`
+  - Old command still works with deprecation warning for backward compatibility
+
 ## [3.0.4] - 2025-10-21
 
 ### 🚀 Features

docs/cli.rst

@@ -144,10 +144,27 @@ To convert OpenSwath's *.osw* / *.sqMass* format to a parquet format, you can us
    :prog: pyprophet export parquet
    :nested: none
 
-Export Score Plots
-^^^^^^^^^^^^^^^^^^
+Export Feature Score Plots
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-It may be useful to export the distribution of scores for the different input features. This can help you investigate the distribution and quality of scores for target-decoy separation.
+To export the distribution of feature scores (VAR_ columns) and, if available, scorer scores (SCORE columns), you can use the :program:`export feature-scores` subcommand. This command works with all file formats (OSW, Parquet, and Split Parquet):
+
+- **For unscored files**: Plots only VAR_ columns (feature variables)
+- **For scored files**: Applies RANK==1 filtering and plots both SCORE and VAR_ columns
+
+This is useful for investigating the distribution and quality of scores for target-decoy separation.
+
+.. click:: pyprophet.cli.export:export_feature_scores
+   :prog: pyprophet export feature-scores
+   :nested: none
+
+Export Score Plots (Deprecated)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. deprecated:: 3.1
+   Use :program:`pyprophet export feature-scores` instead.
+
+The :program:`export score-plots` command is deprecated and will be removed in a future version. It has been replaced by the more flexible :program:`export feature-scores` command which works with all file formats.
 
 .. click:: pyprophet.cli.export:export_score_plots
    :prog: pyprophet export score-plots

pyprophet/cli/export.py

@@ -14,6 +14,9 @@
 from ..export.export_report import (
     export_scored_report as _export_scored_report,
 )
+from ..export.export_report import (
+    export_feature_scores as _export_feature_scores,
+)
 from ..export.calibration_report import generate_report as generate_calibration_report
 from ..glyco.export import (
     export_score_plots as export_glyco_score_plots,
@@ -43,8 +46,10 @@ def export():
     export.add_command(export_parquet, name="parquet")
     export.add_command(export_compound, name="compound")
     export.add_command(export_glyco, name="glyco")
-    export.add_command(export_score_plots, name="score-plots")
+    export.add_command(export_feature_scores, name="feature-scores")
+    export.add_command(export_score_plots, name="score-plots")  # Deprecated
     export.add_command(export_scored_report, name="score-report")
+    export.add_command(export_feature_scores, name="feature-scores")
     export.add_command(export_calibration_report, name="calibration-report")
 
     return export
@@ -829,7 +834,35 @@ def export_glyco(
     )
 
 
-# Export score plots
+# Export feature scores (unified command)
+@click.command(name="feature-scores", cls=AdvancedHelpCommand)
+@click.option(
+    "--in",
+    "infile",
+    required=True,
+    type=click.Path(exists=True),
+    help="PyProphet input file (OSW, Parquet, or Split Parquet directory).",
+)
+@click.option(
+    "--out",
+    "outfile",
+    type=click.Path(exists=False),
+    help="Output PDF file path. If not specified, will be derived from input filename.",
+)
+@measure_memory_usage_and_time
+def export_feature_scores(infile, outfile):
+    """
+    Export feature score plots
+
+    Works with OSW, Parquet, and Split Parquet formats.
+    - If SCORE tables exist: applies RANK==1 filtering and plots SCORE + VAR_ columns
+    - If SCORE tables don't exist: plots only VAR_ columns
+    """
+    from ..export.export_report import export_feature_scores as _export_feature_scores
+    _export_feature_scores(infile, outfile)
+
+
+# Export score plots (deprecated - use feature-scores instead)
 @click.command(name="score-plots", cls=AdvancedHelpCommand)
 @click.option(
     "--in",
@@ -849,8 +882,11 @@ def export_glyco(
 @measure_memory_usage_and_time
 def export_score_plots(infile, glycoform):
     """
-    Export score plots
+    Export score plots (DEPRECATED - use 'feature-scores' instead)
+
+    This command is deprecated. Please use 'pyprophet export feature-scores' instead.
     """
+    logger.warning("DEPRECATED: 'pyprophet export score-plots' is deprecated. Use 'pyprophet export feature-scores' instead.")
     if infile.endswith(".osw"):
         if not glycoform:
             _export_score_plots(infile)
@@ -880,6 +916,33 @@ def export_scored_report(infile):
     _export_scored_report(infile, outfile)
 
 
+# Export feature scores
+@click.command(name="feature-scores", cls=AdvancedHelpCommand)
+@click.option(
+    "--in",
+    "infile",
+    required=True,
+    type=click.Path(exists=True),
+    help="PyProphet input file (OSW, Parquet, or Split Parquet directory).",
+)
+@click.option(
+    "--out",
+    "outfile",
+    type=click.Path(exists=False),
+    help="Output PDF file. If not provided, will be auto-generated based on input filename.",
+)
+@measure_memory_usage_and_time
+def export_feature_scores(infile, outfile):
+    """
+    Export feature score plots from a PyProphet input file.
+
+    Creates plots showing the distribution of feature scores (var_* columns)
+    at different levels (ms1, ms2, transition, alignment) colored by target/decoy status.
+    Works with OSW, Parquet, and Split Parquet files (scored or unscored).
+    """
+    _export_feature_scores(infile, outfile)
+
+
 # Export OpenSwath Calibration debug plots
 @click.command(name="calibration-report", cls=AdvancedHelpCommand)
 @click.option(