Nextflow parameter description scheme

[sven1103]

TL;DR

A naming scheme to enable meta-data annotation for workflow parameters.

Details

Usually, workflow-specific execution parameters for the single processes are defined in the params scope, a DSL-feature Nextflow provides to access parameter variables from the workflow script during wf execution.

Currently, there is no naming scheme / convention / language feature for annotating parameters with description text, mandatory/optional flags or similar.

This could be useful though for upstream applications in order to build graphical user interfaces and configure a workflow correctly before execution in a dynamic, user-friendly way.

I am very happy for any input here and design suggestions :)

Best, Sven

[pditommaso]

What kind of scheme/metadata would be useful for your use case ?

[ewels]

Suggestions:

• Name (allow spaces, stuff that shouldn't be in the variable name)
• Description
• Type
  • bool
  • numeric
    • max
    • min
  • str
    • max length

I think we spoke about this previously and pointed to some HTML spec or something, but that's probably overkill for now.

Phil

[sven1103]

• default value

[sven1103]

I think mandatory/optional is not necessary, as on definition of a parameter, a default value should always be present.

[ewels]

Yes, and we already have default values?

[sven1103]

implicit in the params definition yes, but not in the descriptions section

[sven1103]

I mean, a parser could just check the following parameter definition after a description section, maybe this is sufficient?

[sven1103]

For simplicity, i would suggest to have normal multi-line comment strings as in Groovy and extend it by tags, such as:

/**
The number of iterations of the algorithm

@name: Algo iterations
@type:  int
@range: {0,10(,1)} // including step size for range?
*/
params.iterations = 10

/**
Sequence type

@name: Nucleotide sequence type
@type: enum
@range: ["dna", "rna"]
*/
params.type = "dna"

maybe sth. in that direction?

[pditommaso]

Let's focus on metadata fields before, I see the following:

• name: (*) the parameter name, it should a valid identifier (no blanks, etc)
• label: human readable name
• help/usage: param description showed in the help text
• type: (*) string, text (multiline string) integer, decimal, file (path), url, upload, choice, range
• min: (value for numeric, length for string)
• max: (value for numeric, length for string)
• defvalue: (*) default value
• pattern: regex validation rule

[pditommaso]

I'm adding @ypriverol in this thread because he's interested in this topic.

[pditommaso]

Related to #88, #144.

[sven1103]

👍 looks good to me

[ewels]

type: (*) string, text (multiline string) integer, decimal, file (path), url, upload, choice, range

Maybe distinguish between a choice that can have multiple selected or just one? eg. radio and checkbox in HTML forms.

Love the idea of having a generic regex validation available 👍