Expose more parameters of tools

[a-frantz]

In the early days of this repo we tended to only expose parameters we use. We've since gotten much better at exposing parameters as we add tools. But there are still many old tasks with very little parameterization.

[a-frantz]

There are few places where we (me and @adthrasher ) decided it was best not to expose specific parameters. The reasoning here is varied, but is generally along the lines of "making use of this parameter would violate a best practice". These cases are sometimes documented (https://github.com/stjudecloud/workflows/blob/main/tools/qualimap.wdl#L7) but there are definitely some "ghost" omissions. I believe in STAR and Kraken both, perhaps in other tools as well.

We should correct this with a dedicated key in the meta section. Do not have a specific key to propose at this time.

[Gyan-max]

Hi @a-frantz can i work on this issue?

[PriyankaaXD]

I audited the two tools called out here (STAR and Kraken2) against their current state on main, plus looked at the qualimap example linked above.

STAR (tools/star.wdl): this is now very thoroughly parameterized — almost every CLI flag has a corresponding WDL input with parameter_meta docs. The gap called out in 2024 looks mostly closed already. Two small things remain hardcoded in the alignment task's command block with no explanation:

• --outMultimapperOrder Random — no input, no comment
• --outSAMtype BAM Unsorted — no input; STAR can also emit SortedByCoordinate directly

Kraken2 (tools/kraken2.wdl): bigger gap. The kraken task doesn't expose several parameters that are commonly considered important to tune:

• --confidence (defaults to Kraken2's permissive 0.0; widely flagged elsewhere as something you almost always want to set)
• --minimum-hit-groups
• --memory-mapping (relevant since this task's own memory_gb is sized specifically because the DB gets loaded into RAM)
• --quick

None of these have a help/warning explaining a deliberate decision, unlike the qualimap -p example — these look like genuine "ghost omissions" rather than intentional ones.

On the meta key you mentioned: since qualimap's existing "documented" omission is just prose in a help field (not structured/queryable), here's a idea:

meta {
    ...
    omitted_parameters: {
        "-p": {
            reason: "Disables certain calculations; we always want the full suite of calculations performed.",
        },
    }
}

Keyed by the underlying tool's flag name, with a required reason field. This makes intentional omissions greppable/lintable across the repo instead of living in inconsistent prose, and gives future contributors (and Sprocket's docs generator) something structured to surface.

Happy to take Kraken2 first since it's the clearest actual gap, and add the omitted_parameters key to qualimap.wdl as the reference implementation if that shape looks reasonable to you. Let me know if you'd rather see a different key name/shape before I start.

[a-frantz]

@PriyankaaXD all that sounds great! Really appreciate the investigation here :D

The only parameter you mentioned which I can recall reasoning for omitting is STAR's outSAMtype. STAR has an inefficient sort implementation that can blow up in the worst case. Run enough samples through STAR and you hit that worst case often enough we've hard disabled it and instead rely on a downstream, dedicated sorting step.

I like the omitted_parameters convention! If you wanted to add that to qualimap and STAR, we'd certainly accept the PR.

I agree that it sounds like Kraken2 should be exposing all of those options you found, except for memory mapping arg. If I understand it correctly (haven't run to verify), adding --memory-mapping would lower the RAM requirement by some (unknown) amount at the cost of at least speed and potentially higher disk usage. This seems like a bad trade to me, as WDL tasks are traditionally not run somewhere with tight memory constraints, and the unknown quantity of the RAM savings would complicate the implementation and involve more investigation. In my experience, the constraint in WDL that is most often a bottleneck is time, so slowing down an already long process should be avoided without good reason.