docs(qpx): update output docs and qpx schema defaults

- add qpx/ to output directory trees
- drop verbose opt_ column explanations from docs
- set best_per_spectrum_only default to true

Co-Authored-By: Claude <noreply@anthropic.com>

Author: daichengxin

docs/output.md

@@ -60,6 +60,7 @@ results_iso/
 ├── pipeline_info/             # Nextflow pipeline information
 ├── sdrf/                      # SDRF files and configs
 ├── quant_tables/              # Quantification tables and results
+├── qpx/                       # qpx results
 └── pmultiqc/                  # pMultiQC reports
     ├── multiqc_data/
     └── multiqc_plots/
@@ -77,6 +78,7 @@ results_lfq/
 ├── spectra/                   # Spectra-related data (only present if --mzml_features is enabled)
 │   └── mzml_statistics/       # Statistics about mzML files
 ├── quant_tables/              # Quantification tables and results
+├── qpx/                       # qpx results
 └── pmultiqc/                  # pMultiQC reports
     ├── multiqc_data/
     └── multiqc_plots/
@@ -105,6 +107,7 @@ results_localize/
 ├── pipeline_info/             # Nextflow pipeline information
 ├── sdrf/                      # SDRF files and configs
 ├── quant_tables/              # Quantification tables and results
+├── qpx/                       # qpx results
 └── pmultiqc/                  # pMultiQC reports
     ├── multiqc_plots/
     │   ├── svg/
@@ -139,6 +142,7 @@ results/
 │   ├── fdr_consensusid/       # FDR calculation results
 │   └── id_filter/             # Filtered identification results
 ├── quant_tables/              # Quantification tables and results
+├── qpx/                       # qpx results
 └── pmultiqc/                  # pMultiQC reports
     ├── multiqc_plots/
     │   ├── svg/
@@ -247,41 +251,6 @@ QPX is the published quantification artifact for both DDA-LFQ and DDA-ISO. It is
 channel labels. The dataset is published flat under `qpx/`, the same layout as the DIA-NN (`quantmsdiann`) QPX
 output. See the [QPX specification](https://bigbio.github.io/qpx/) for the view schemas and file layout.
 
-Some explanations for optional ("opt\_") columns:
-
-PRT section:
-
-- opt_global_Posterior_Probability_score: As opposed to the best_search_engine_score columns (which usually represent an FDR [consult the MTD section]) this specifies the posterior probability for a protein or protein group as calculated by protein inference.
-- opt_global_nr_found_peptides: The number of found peptides for the protein (group). By default this counts unmodified peptide sequences (TODO double-check)
-- opt_global_cv_PRIDE:0000303_decoy_hit: If this was a real target hit or a decoy entry added artificially to the protein database.
-- opt_global_result_type:
-  - single_protein: A protein that is uniquely distinguishable from others. Note: this could be a subsumable protein.
-  - indistinguishable_protein_group: A group of proteins that share exactly the same set of observed peptides.
-  - protein_details: A dummy entry for every protein belonging to either of the two classes above. In case of an indistinguishable group, it would otherwise not be possible to report unique sequence coverage information about each member of the group. Do not use these entries for quantitative information or scoring as they will be "null/empty". They shall only be used to extract auxiliary information if required.
-
-PEP section:
-
-- opt_global_cv_MS:1000889_peptidoform_sequence: The sequence of the best explanation of this feature/spectrum but with modifications.
-- opt_global_feature_id: A unique ID assigned by internal algorithms. E.g., for looking up additional information in the PSM section or other output files like consensusXML
-- opt_global_SpecEValue_score: Spectral E-Value for the best match for this peptide (from the MSGF search engine)
-- opt_global_q-value(\_score): Experiment-wide q-value of the best match. The exact interpretation depends on the FDR/q-value settings of the pipeline.
-- opt_global_cv_MS:1002217_decoy_peptide: If the peptide from the best match was a target peptide from the digest of the input protein database, or an annotated or generated decoy.
-- opt_global_mass_to_charge_study_variable[n]: The m/z of the precursor (isobaric) or the feature (LFQ) in study_variable (= usually sample) n.
-- opt_global_retention_time_study_variable[n]: The retention time in seconds of the precursor (isobaric) or the feature (LFQ) in study_variable (= usually sample) n.
-
-PSM section:
-
-- opt_global_FFId_category: Currently always "internal".
-- opt_global_feature_id: A unique ID assigned by internal algorithms. E.g., for looking up additional information in the PEP section or other output files like consensusXML.
-- opt_global_map_index: May be ignored. Should be a one-to-one correspondence between "ms_run" in which this PSM was found and the value in this column + 1.
-- opt_global_spectrum_reference: May be ignored. Should be a one-to-one correspondence between the second part of the spectra_ref column and this column.
-- opt_global_cv_MS:1000889_peptidoform_sequence: The sequence for this match including modifications.
-- opt_global_SpecEValue_score: Spectral E-Value for this match (from the MSGF search engine)
-- opt_global_q-value(\_score): Experiment-wide q-value. The exact interpretation depends on the FDR/q-value settings of the pipeline.
-- opt_global_cv_MS:1002217_decoy_peptide: If the peptide from this match was a target peptide from the digest of the input protein database, or an annotated or generated decoy.
-
-Note that columns with scores heavily depend on the chosen search engines and rescoring tools and are better looked up in the documentation of the underlying tool.
-
 #### MSstats post-processing (external)
 
 The pipeline no longer runs MSstats post-processing. Instead, quantms produces MSstats-compatible input files (`quant_tables/*_msstats_in.csv`) that users can provide directly to MSstats outside the pipeline for normalization, imputation, and statistical analysis.

nextflow_schema.json

@@ -755,7 +755,8 @@
                 },
                 "best_per_spectrum_only": {
                     "type": "boolean",
-                    "description": "After applying score:fdr, retain only the best-scoring PSM per spectrum (default: keep all hits, matching legacy PercolatorAdapter behaviour).",
+                    "description": "After applying score:fdr, retain only the best-scoring PSM per spectrum.",
+                    "default": true,
                     "fa_icon": "far fa-check-square",
                     "hidden": true
                 }