Hello, We've been discussing in <#CJRH30T6V|module...
# tools
a
Hello, We've been discussing in #modules https://nfcore.slack.com/archives/CJRH30T6V/p1737918804012469 about params. The first discussion was about the lack of documentation related to
params
for our users. We've been developing a lot of modules in our library (nf-neuro) for our users to help them implement their own neuroimaging pipeline. It is becoming obvious that without any documentation about the
params
used in the module, our users are lost and can't easily use our modules. It also became obvious that the topic params is far from being resolved. My suggestion was to, in the meantime, implement these useful features... • Allow keyword
params
in meta.yml • Make sure
nf-core module info
can list these params • Make sure it can be linted Is there something that some dev can push forward ? Thank you in advance 🙂
keanu thanks 1
j
I don't fully understand? Can you give some context why there are params in your modules? The nf-core modules specs explicitly say they should not be in there. User modifiable non-file options should be inserted either as an input channel (if mandatory) or via ext.args in a pipeline level (typical modules.config) config? https://nf-co.re/docs/guidelines/components/modules#use-of-parameters-within-modules
Embedding params in each module is not then portable across different pipelines because then a given pipeline may have to modify their user facing parameter name scheme to a completelt different style
(which is why we prefer the input channel/ext.args routes because then it's completely flexible for the pipeline developer)
(unless I misunderstand?)
a
Yes sorry I made a mistake.. I was talking about ext.args. How can these args be documented ?
btw: thank you for responding 🙂
j
I think you can already document in the yaml file but following the args/args2/args3 notation (again for familiarity/portability) 🤔
I seem to remember adding those for s module at some point (I don't know if you can change the names of not)
@mashehu @Júlia Mir can tell me if I'm halluncinating
a
Do you know which keyword would I use in the meta.yml to document them ? Would it be picked up by nf-core modules info ?
j
The latter i don't know, but the former maybe try searching in the nf-core modules repo for args2 but restricting the search to just yank files
Yaml*
a
from what i see it would only be in the description but no specific keyword.
j
Description of what?
a
of the module in the meta.yml.
j
(I'm on my phone so hard to look up, promise I'm not being lazy)
🤣 1
Ahh with the tool descriptions?
With the doi etc?
a
exactly 🙂
j
(btw you might want to modify your original post to say ext.args rather than params, a lot of people might not understand?
)
What is the problem exactly having 8t in the description? That it's then not picked up on the website/info command? You just want it displayed somewhere?
a
It would be more appropriate to have is own category and easy to read/understand/use (depending on the module we could have 5/6 ext.arg).
a
5/6
ext.arg
also seems a bit against the nf-core standard where the number of tools should really only be 1/2. I would say that it's better to stop using the term
params
for anything other than the nextflow
params
object/scope because as James says it causes confusion. I don't like
args
either really, would prefer
tool_args
or
tool_params
. When I look at one of your modules I see you are using specific terms in
ext.
which nf-core would typically use input values for instead
a
Ok let's put aside the number of tool_args. I would argue, it still does not make sense to not document this values in the meta.yml with a specific category. About the tool_args naming, we know it's "against" nf-core guidelines but it's part of our research domain and we have a lot of arguments for our tools, naming them make our life easier.
a
The reason why it's never been an issue before is because the way you are using
ext.<>
is not how nf-core does this. In nf-core those specific values would be expected to be declared as task inputs (which are documented in the meta yml).
ext.args
is then just a catch-all for any non-required tuning parameters people may want to use. I think nf-core starting to support a second method of doing the same job would be confusing and create inconsistency across modules.
👍 1
a
This is exactly the kind of use we have, those tool_args we are using are non-required tuning parameters.
a
Then really they should be left to the user via
ext.args
. There is no need to designate each one separately? This to me just seems to add unnecessary complexity and creates a difference between the way users of
nf-core
modules would expect the code to behave. In your module I linked above for example, you have mirrored each param for the tool explicitly except for
--mask
(obvious reason as it is a
path
) and
-v
for the verbose logging. I am unclear why:
Copy code
process {
    withName: IMAGE_POWDERAVERAGE {
        ext.args = "-v --shell_thr 10"
}
is considered worse than:
Copy code
process {
    withName: IMAGE_POWDERAVERAGE {
        ext.args = "-v"
        ext.shell_thr = 10
}
a
It's not because they are not mandatory that they don't deserve some respect 😄 #joke One expert could want to change this specific parameter if he feels it will better give him better result but the same expert would also need a clear documentation about the purpose of this tool_arg.
Also the module you choose has only one main command but a lot of module tool_args are used for different set of commands.
a
Isn’t that just a case of going to the tool documentation? Imagine doing this for a tool with more than a few optional parameters, the code would grow unreasonably bloated and how do you determine which args to include if you think you will only manually do a subset?
Also the module you choose has only one main command but a lot of module tool_args are used for different set of commands
I don’t quite follow this, perhaps you can show an example
a
Here is one for example with three tool_args applied to different commands in a module. https://github.com/scilus/nf-neuro/blob/main/modules/nf-neuro/betcrop/fslbetcrop/main.nf
a
AFAICT the args aren’t shared across the different tools, just slightly different invocations of the same tool. Thus the current standard would be:
Copy code
def args = task.ext.args ?: "" 
def args2 = task.ext.args2 ?: "" 
def args3 = task.ext.args3 ?: ""
Followed by:
Copy code
then
    scil_dwi_extract_b0.py $image $bval $bvec ${prefix}__b0.nii.gz --mean \
        $args --skip_b0_check

    bet ${prefix}__b0.nii.gz ${prefix}__image_bet.nii.gz -m -R $args2
    scil_volume_math.py convert ${prefix}__image_bet_mask.nii.gz ${prefix}__image_bet_mask.nii.gz --data_type uint8 -f
    mrcalc $image ${prefix}__image_bet_mask.nii.gz -mult ${prefix}__image_bet.nii.gz -quiet -nthreads 1 -force
else
    bet $image ${prefix}__image_bet.nii.gz -m -R $args2
    scil_volume_math.py convert ${prefix}__image_bet_mask.nii.gz ${prefix}__image_bet_mask.nii.gz --data_type uint8 -f
fi

if [ "$task.ext.crop" = "true" ];
then
    scil_volume_crop.py ${prefix}__image_bet.nii.gz ${prefix}__image_bet.nii.gz -f \
        --output_bbox ${prefix}__image_boundingBox.pkl
    scil_volume_crop.py ${prefix}__image_bet_mask.nii.gz ${prefix}__image_bet_mask.nii.gz -f\
        --input_bbox ${prefix}__image_boundingBox.pkl
    scil_volume_math.py convert ${prefix}__image_bet_mask.nii.gz ${prefix}__image_bet_mask.nii.gz \
        --data_type uint8 -f
fi

if [ "$task.ext.dilate" = "true" ];
then
    scil_volume_math.py dilation ${prefix}__image_bet_mask.nii.gz $args3 ${prefix}__image_bet_mask.nii.gz --data_type uint8 -f
fi
If they were shared across different tools then I would probably say that they should become real inputs.
a
Yes they are not shared across tools but putting "noname" args makes our module difficult to play with. Just to give you an example the module I shared with you (BET means brain extraction tool) could be use on a human brain but also for a macaque brain. Then the tools_args are getting very important to play with and without documentation it would be impossible to use it. An other example, an image from a GE scanner could need a slightly change with the arg_tool
bet_f
and not if the same brain would have been acquired with a SIEMENS scanner. Those are realistic use cases in neuroimaging.
💯 1
a
> Then the tools_args are getting very important to play with and without documentation it would be impossible to use it. But the
bet
tool presumably has it’s own documentation somewhere and the users should be interrogating that. The part here I would say (and it’s something I think myself) is that
ext.args
/
ext.args2
is not intuitive or informative as to which tool the args will be piped to. However I also understand why it’s standardised across
nf-core
as it makes it easier to remember or predict syntax, particularly in the case of a single tool (i.e. I can always do
ext.args = …
and I don’t have to think if the module uses e.g.
ext.picard
or
ext.Picard
) In that sense I would support some mapping of the generic
args
to a tool in the
meta.yml
e.g.:
Copy code
ext:
    args: samtools merge
    args2: samtools index
a
Hi all! Been following the thread; thank you for your responses! I understand the logic behind using
ext.args{1,2,...}
for modules containing a single command, as you indeed can refer to the tool's documentation. However, and I think this is where we mostly differ from
nf-core
philosophy, is that most of our modules are actually a combination of tools (in the example you cited, there are 3 tools:
bet
,
mrcalc
, and
scil_volume_crop
. This is a decision we made, knowing it was not
nf-core
philosophy, to reduce the number of files we generate (we often launch our pipelines on 1000+ subjects, which can easily and quickly exceed a cluster's quota for the number of files). This led us to name the
ext
to facilitate the understanding of which
ext
was associated with which tool. If we take the example you linked, the three tools come from three neuroimaging libraries. Does this mean the users should refer to three documentation sites for a single module? To me, this doesn't really make sense and represents a burden for the user. Documentation for those types of `ext`` is a must-have in our case. Thinking out loud here (if that's possible by writing...), I guess this stems from how we designed our modules. To us, they represent an "operation" applied to an image, which can require multiple tools, whereas, in the
nf-core
philosophy (AFAIK), the modules are tools. Does this makes sense?
a
Yes, your users should go to whichever tool docs they need to. Otherwise as I say above, you are heading down the road of maintaining effectively parallel documentation for multiple tools in one place that you will need to manually keep in sync. You aren’t just renaming e.g.
ext.args
to
ext.bet
you are splitting what would go into
ext.args
into many different
ext.<>
for each possible CLI arg for each tool. But as I have said I do think
ext.args
alone is quite opaque and in fact
nf-core
modules which use multiple
argsN
such as bcftools/mpileup are not always easy to guess what command any given
argsN
will be passed to, so I would support some way to document that.
💯 1
a
I agree with you that the constant documentation update when a tool updates its CLI arg will definitely be a burden. I guess we got used to updating the documentation. 😅
You aren’t just renaming e.g.
ext.args
to
ext.bet
you are splitting what would go into
ext.args
into many different
ext.<>
for each possible CLI arg for each tool.
This made me realize the advantages of doing it the way
nf-core
is doing it now (I guess it's better late than never 😅). I would have to test it out in our modules, but it does relieve the burden of supporting every possible CLI args the tools have and makes updating versions way more manageable when there are breaking changes.
💯 1
j
Sorry I left you dangling @Arnaud Boré one of my kids woke up and then I was tired 😅 But @Arthur has much better explained the nf-core stance - and I can see maybe pushing
ext.args2/3/4
into their own section with better metadata. But renaming them to non-standardised stuff is extremely unlikely to happen. I think it would be best to make an issue on #tools if you've not already, and we can discuss with Júlia and Matthias the best way to do this.
a
The good thing about just adding documentation for
args
into the
meta.yml
is that is can be made as a non-breaking change and/or is much, much easier to backwards update all the existing modules for
👍 1
j
I guess the question is what additional information we should add, and how it should be rendered
Copy code
- "bcftools plugin setGT":
      description: "Bcftools plugins are tools that can be used with bcftools to manipulate
        variant calls in Variant Call Format (VCF) and BCF. The setGT plugin sets genotypes according to the specified criteria and filtering expressions. For example, missing genotypes can be set to ref, but much more than that."
      homepage: "https://samtools.github.io/bcftools/howtos/plugins.html"
      documentation: "https://samtools.github.io/bcftools/howtos/plugin.setGT.html"
      tool_dev_url: "https://github.com/samtools/bcftools"
      doi: "10.1093/bioinformatics/btp352"
      licence: ["MIT"]
      args_id: "$args2"
      identifier: biotools:bcftools
Because IMO this is actually sufficient
Given what goes into
args2
is compeltely arbitrary
(But should be mandatory, which I guess it isn't atm)
That's from
bcftools/pluginsetgt
btw
a
Oh. How did I not notice
args_id
already exists lol. That’s v similar to what I was proposing
The cases where it falls down are e.g. bcftools/mpileup Only
mpileup
is listed (and doesn’t have an
args_id
), but yet:
Copy code
bcftools \\
        mpileup \\
        --fasta-ref $fasta \\
        $args \\
        $bam \\
        $intervals \\
        $mpileup \\
        | bcftools call --output-type v $args2 \\
        | bcftools reheader --samples sample_name.list \\
        | bcftools view --output-file ${prefix}.vcf.gz --output-type z $args3
👍 2
I think that taking out
args_id
from the tools section is useful because it allows for cases where also there is second invocation of the same tool (not sure how many cases this is but would not be shocked if it’s non-zero). Not real example which hopefully demonstrates how this is different:
Copy code
args_ids:
  args: samtools index
  args2: samtools merge
  args3: samtools index second invocation
j
Got it, that's reasonable t me
I guess also it's a developer facing info rather user facing info
Oh. How did I not notice args_id already exists lol. That’s v similar to what I was proposing
I swear it was added as a requirement recently and then now is not linted for...
cowboy mild panic 1
So it is rendered on the website for example, but right at the btoom under 'tools' which agreed is not a logical place where developers will look compared to the
input
sections
a
Yep. It’s rendered and it works nicely if present and if each tool is only called once. I think splitting it out would make it more flexible - allowing descriptive strings about the invocation for example - and easier to display more prominently
j
I'm arguing it's not nciely at present 😆
👍 1
as it's hidden at the bottom
a
I am pretty sure we are just agreeing here but getting crossed wires over phrasing
j
Yup 😆
So I think we need two PRs thenmL: 1. Tools: please make a new section for listing each args (2, 3, 4) with the sole(?) metadata for each one is simply the tool of the pipe it is effecting 2. Website: render this args section after input/output channel info but before the module description
👍 1
a
I think that is good. One thing that I wonder if this can be used to also render is some sort of pipeline help? Because typically it's a pipeline user that will override a specific module
ext.args
. So would be really cool to be able to display a list of qualified module names and what their
ext.args
control, but I think that could be quite convoluted
j
heloo! sorry this thread is so long! 😄 if I understand well, we want an extra section in the
meta.yml
to describe the
ext.args
values. At the level of
tools
,
inputs
and
outputs
. Sounds good! I think we only need a description for those. So it would be something like
Copy code
tools:
  - "bcftools":
      description: "..."
      homepage: ...
      args_id: "$args"
      identifier: biotools:bcftools
  - "bcftools plugin setGT":
      description: "..."
      homepage: ...
      args_id: "$args2"
      identifier: biotools:bcftools
args:
  - args:
      description: ""
  - args2:
      description: ""
input:
  - - meta:
        ...
    - vcf:
        ...
this 4
❤️ 2
j
Yes that would be perfect! I think a
description
and
'subcommand'
attribute would be perfect
a
Yup, think that's perfect. I'm leery of putting too much of the real command into the meta yml as then we head towards it being basically just the module code haha.
j
Yeah
By subcommand I mean more
samtools sort
or
samtools view
that's it
j
isn't this redundant with
args_id
then?
j
No, because
args_id
doesn't sa the subcommand
It just is
bcftools
or
samtools
where the args are associatd wiht
samtools view
then
samtools sort
etc.
j
ah ok,
args_id
is only useful if there are more than one tools, got it
a
Also not every
tools
will list or link to a sub command. It might just be the top-level tool and then it's less informative
👍🏻 1
👍 1
s
Just to chip in to say that I dislike our current
args
,
args2
policy, and do think it is much more helpful to name them with respect to what they actually do. I like Júlia's suggestion of a separate entry in the yml, and think that
description
would be sufficient.
a
"Morning" everyone 🙂 I'm catching up with this conversation. I'm really happy with what @Júlia Mir suggested. What would be the next step ? Do we need to open an issue ? Who is willing to give it go ? @Arthur @James Fellows Yates @Júlia Mir Thank you in advance, this is a great conversation. I learn a lot ! 🙂
j
Yes please make the two issues @Arnaud Boré as I described above
👍 1
(and you can summarise the solution form Julia, and then link the tools issue in the website issue)
a