Add VAF vs depth plots with independent modules and workflow integration

[Copilot]

Implements plotting functionality to analyze relationships between sequencing depth and quantitative metrics (VAF, mutation density, omega, OncodriveFML). The implementation uses independent modules with hyperbolic curves only for VAF and mutation density plots.

Implementation

Two independent scripts:

• bin/plot_vaf_mutdensity_depth.py - VAF and mutation density plots WITH hyperbolic curves

  • plot_vaf_vs_depth_per_site() - VAF scatter with per-site depth
  • plot_mutdensity_vs_depth() - Per-gene mutation density by type (all/SNV/indels)
  • add_hyperbolic_curves() - Overlays N/depth curves (N=1,2,3...configurable)
  • count_mutations_on_curves() - Tolerance-based assignment to curves

• bin/plot_selection_depth.py - Selection metrics plots WITHOUT hyperbolic curves

  • plot_omega_vs_depth() - dN/dS ratios by impact (missense/truncating)
  • plot_oncodrivefml_vs_depth() - Functional bias scores

Independent Nextflow modules:

• modules/local/plot/vaf_mutdensity_depth/ - VAF and mutation density module
  • Accepts optional MAF, mutation density, and depth files
  • Runs independently with any combination of inputs
• modules/local/plot/selection_depth/ - Selection metrics module
  • Accepts optional omega, OncodriveFML, and depth files
  • Runs independently with any combination of inputs

Workflow integration:

• subworkflows/local/plot_depth_relationships/ - Orchestrates both modules
• Connected to main workflow in workflows/deepcsa.nf
• Enabled with plot_depth_relationships = true parameter
• Each module runs independently based on data availability

Documentation:

• docs/vaf_depth_plots.md - Usage and interpretation guide for both modules
• docs/examples/vaf_depth_plots_example.sh - Usage patterns for each module
• docs/IMPLEMENTATION_SUMMARY.md - Technical details and integration

Usage

VAF and mutation density (with hyperbolic curves):

plot_vaf_mutdensity_depth.py \
  --sample_name sample_01 \
  --maf_file mutations.maf \
  --mutdensity_file densities.tsv \
  --depth_file depth_per_gene.tsv \
  --output_prefix sample_01 \
  --max_n 10

Selection metrics (without hyperbolic curves):

plot_selection_depth.py \
  --sample_name sample_01 \
  --omega_file omega.tsv \
  --oncodrivefml_file oncodrivefml.tsv \
  --depth_file depth_per_gene.tsv \
  --output_prefix sample_01

In pipeline:
Enable in nextflow.config: plot_depth_relationships = true

Key features

• Module independence: Each module runs separately with partial inputs

• Hyperbolic curves restricted: Only on VAF and mutation density plots, NOT on omega or OncodriveFML

• Automatic counting of mutations within 5% tolerance of each curve (VAF/mutation density only)

• Statistical significance color-coding (p < 0.05 for omega, q < 0.1 for OncodriveFML)

• Reference curves for mutation density showing expected counts at various depths

• Flexible input handling - each module generates only plots for provided files

• Workflow integration with proper channel handling for per-sample data

• Fixes Add VAF vs depth plots #391

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add VAF vs depth plots</issue_title>
<issue_description>Add the plots for the relationship between depth and a number of quantitative metrics:

• VAF (depth per site)
• Mutation density (with depth value from the mutation density file & also with average depth per gene)
  • Different flavours: all, protein affecting, non protein affecting
• Omega (average depth per gene)
• OncodriveFML (average depth per gene)

We should start with the plots for VAF and mutation density, since they are the simplest ones, and then it would be great to do it for the other metrics at the level of the gene where instead of using the depths per position we should load the information from the average depth in each of those genes.

For each of these metrics, we should generate this scatterplot and then add on top of it the hyperbolic curves of 1/depth, 2/depth up to N/depth for Ns up to a reasonable number.

It would be good to also get some counts on how many of the mutations/mutation density values follow these curves.</issue_description>

<agent_instructions>You are an expert developer and need to make these contributions.
Solving this issue will probably require adding a new module and python scripts to handle the plotting.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes Add VAF vs depth plots #391

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[FerriolCalvet]

@copilot the updates added do not work, the module you created is not connected to any workflow for it being executed.

Can you make sure to connect it appropriately?

Also, the current version of the module requires the user to run all methods: mutdensity, omega, oncodrivefml in order to get the module to work, but I would like them to be independent from each other so that each of them was run independently.

Also please restrict the hyperbolas to the vaf and mutation density plots, do not add them for the others.

Make sure all these tasks are completed before asking for my review again.

[Copilot]

@copilot the updates added do not work, the module you created is not connected to any workflow for it being executed.

Can you make sure to connect it appropriately? ...

I've addressed all the feedback:

1. Connected to workflow: Added PLOT_DEPTH_RELATIONSHIPS subworkflow integrated into workflows/deepcsa.nf (enabled with plot_depth_relationships = true)

2. Made modules independent: Split into two separate scripts and modules:

   • plot_vaf_mutdensity_depth.py / PLOT_VAF_MUTDENSITY_DEPTH - runs independently with MAF and/or mutation density + depth
   • plot_selection_depth.py / PLOT_SELECTION_DEPTH - runs independently with omega and/or oncodrivefml + depth

3. Removed hyperbolic curves from selection metrics: Omega and OncodriveFML plots now have NO hyperbolic curves, only VAF and mutation density plots have them

The modules are now fully independent - each checks for file availability and generates only the applicable plots. Fixed in commits 8e1a4ad and 9cf5d71.